Support per-session/per-agent instances with persistent Store lifetime

[JMLX42]

Summary

Currently, Wassette creates a fresh Store for each tool call, which means all WebAssembly linear memory state is reset between calls. This proposal requests an optional mode where a Store can persist across multiple calls within a session or agent context.

Motivation

1. Consistent Multi-Turn MCP Tool Calls

Many MCP tools benefit from maintaining state across a conversation. For example:

• A database query tool that keeps a connection pool
• A stateful interpreter (Python REPL, shell session)
• A tool that accumulates context or learns from previous calls

Currently, each call_tool invocation starts fresh, making it impossible for the WASM component to maintain any in-memory state between calls from the same agent.

2. Per-Instance MCP Resources

MCP's resources capability allows servers to expose data that clients can read. Resources often represent stateful entities:

• File handles or cursors
• Session-specific data
• Cached computation results

With per-call Store isolation, resource state cannot persist, limiting the expressiveness of WASM-based MCP servers.

3. Efficient Resource Utilization

Some components perform expensive initialization (loading models, parsing large configs, establishing connections). Re-doing this on every call is wasteful when multiple calls will be made within the same agent session.

Current Architecture

Wassette already optimizes compilation via InstancePre:

pub struct ComponentInstance {
    component: Arc<Component>,
    instance_pre: Arc<InstancePre<WassetteWasiState<WasiState>>>,
    // ...
}

But in execute_component_call(), a fresh Store is created per call:

let mut store = Store::new(self.runtime.as_ref(), state);
let instance = component.instance_pre.instantiate_async(&mut store).await?;
func.call_async(&mut store, &argument_vals, &mut results).await?;
// Store dropped here - state lost

Proposed Solution

Add an optional session/agent-scoped instance mode:

1. Session Registry: Maintain a map of (session_id, component_id) -> (Store, Instance)
2. Lifecycle Hooks:
   • create_session(session_id) - instantiate components for a session
   • destroy_session(session_id) - clean up Stores
   • Or automatic cleanup via TTL/LRU
3. Execution Mode: New method like execute_component_call_in_session(session_id, ...) that reuses the existing Store

This would be opt-in, preserving the current stateless behavior as the default for security-sensitive use cases.

Alternatives Considered

• External state via WASI APIs: Components could use wasi:keyvalue or similar, but this externalizes state management and adds complexity for simple in-memory use cases.
• Component-managed serialization: Components could serialize/deserialize state on each call, but this is inefficient and burdensome for component authors.

Use Case Example

An agentic runtime instantiates multiple agents, each with their own MCP server connections. With per-session instances:

• Agent A's calls to a "notes" tool accumulate in Agent A's memory
• Agent B gets a separate instance with its own state
• Component compilation remains shared across all agents

---

Disclosure: This issue was drafted with assistance from Claude (AI).

[github-actions]

Agentic Issue Triage triggered by this issue.

[JMLX42]

Related Issues

This feature request is closely related to:

• Support WIT resource types in MCP tool calls #601 - Support WIT resource types in MCP tool calls

  • Resources require persistent handles across calls, which implies session-scoped state

• Feature request: Host-provided background process management for long-running tools #600 - Host-provided background process management for long-running tools

  • Background processes also need session scope to remain alive between tool calls

• feat(component2json): add integer-based resource handle serialization #602 (PR) - feat(component2json): integer-based resource handle serialization

  • This PR introduces per-component ResourceHandleTable in LifecycleManager, which is a partial solution for handle persistence. The full per-session instance feature (Support per-session/per-agent instances with persistent Store lifetime #615) would generalize this to the entire Store (linear memory, globals, etc.).

These three issues together represent a broader need for session-scoped component state in Wassette.

[JMLX42]

Implementation Plan

Overview

An opt-in execution mode where a component's Store and Instance persist for the lifetime of the wassette process, enabling in-memory state and WASI resource continuity across tool calls.

Core Model

Key characteristics:

• Opt-in: Enabled via stateful: true parameter at load time
• Per-component: Each stateful component gets one persistent Store/Instance pair
• Serialized execution: Concurrent calls to the same stateful component are queued
• Process-scoped: State lives until component unload or process exit
• Simple cleanup: On unload, Store/Instance are dropped

What persists:

• WASM linear memory (heap, globals, static data)
• WASI resources (file handles, sockets bound to the Store)
• ResourceAny values (via existing ResourceHandleTable)

What doesn't change:

• Stateless mode remains the default
• Stateless components still get fresh Store/Instance per call
• Stateless components can still run concurrently

API Changes

LoadOptions Struct

pub struct LoadOptions {
    pub stateful: bool,
    // Extensible for future options
}

impl Default for LoadOptions {
    fn default() -> Self {
        Self { stateful: false }
    }
}

LifecycleManager::load_component

pub async fn load_component(
    &self,
    source: ComponentSource,
    options: LoadOptions,
) -> Result<LoadResult, Error>;

Internal State

struct StatefulInstance {
    store: Store<WassetteWasiState<WasiState>>,
    instance: Instance,
    call_lock: tokio::sync::Mutex<()>,
}

// In LifecycleManager
stateful_instances: Arc<Mutex<HashMap<String, StatefulInstance>>>

Execution Flow

Stateless (unchanged)

call_tool() →
  get_wasi_state_for_component() →
  Store::new() →
  instance_pre.instantiate_async() →
  func.call_async() →
  drop Store/Instance

Stateful

call_tool() →
  acquire call_lock →
  if first call:
    get_wasi_state_for_component() →
    Store::new() →
    instance_pre.instantiate_async() →
    cache in stateful_instances
  else:
    retrieve cached Store/Instance
  func.call_async() →
  release call_lock →
  (Store/Instance remain cached)

Call Serialization

• tokio::sync::Mutex<()> guards each stateful component's Store
• Concurrent calls queue on the lock, execute in order
• No timeout (component responsible for not blocking)

Unload Behavior

• Remove from stateful_instances map
• Drop Store/Instance (state lost)

Scope

In Scope

• LoadOptions struct with stateful: bool field
• StatefulInstance cache in LifecycleManager
• Call serialization via mutex for stateful components
• Simple drop on unload

Deferred

• wassette:drop / wasi:drop cleanup interface (inspired by Rust's Drop trait)
• TTL/idle timeout eviction
• Memory limits on stateful instances
• Multiple sessions per component
• Snapshot/restore of stateful instances

Testing

• Unit test: stateful component retains memory across calls
• Unit test: concurrent calls are serialized (not interleaved)
• Unit test: unload drops state, reload starts fresh

Documentation

• Update wassette docs with stateful mode explanation