Skip to content

Upgrade: a run's end keeps the workspace; deleting it is your call (core 15.0.0) ​

@helix-agents/core 15.0.0 changes what happens to a session's workspace when a run ends. Before, every run's end deleted the workspace's files on local-bash, local-sandbox and docker, including every suspension (a client tool, an approval, waiting on sub-agents) and every completed turn. The session's next run then silently got an empty workspace. Now a run's end only releases the workspace, and its data stays until you delete it.

The release also bumps the workspace providers, @helix-agents/runtime-js, @helix-agents/agent-server and @helix-agents/tracing-langfuse (minors). Deploy them together, in one release.

What to do ​

  1. Delete workspaces when you delete sessions. Call executor.destroyWorkspace(sessionId) from your own session deletion. Without it, local-bash / local-sandbox / docker files and in-memory workspaces stay until you reap them.
  2. Reap abandoned workspaces on a schedule. For local-bash and local-sandbox, call provider.reap({ olderThan }) from a cron or alarm. Pick olderThan longer than your longest run plus how long a session's workspace should be kept when idle.
  3. Route a session to one replica when a host-bound provider (local-bash, local-sandbox, docker) serves it. Another replica can't see that host's files, and a misrouted request now fails typed instead of silently starting empty.
  4. Handle workspace_unavailable. When a stored workspace can't be reattached, workspace tools fail with it. Call executor.resetWorkspace(sessionId) to start the session over with a fresh workspace (see below).
  5. Update exhaustive switches over WorkspaceEntryStateKind / EntrySnapshot.state to include 'unavailable'.

What changed ​

A run's end releases; destroy is explicit ​

  • local-bash and local-sandbox: close() keeps the tmpdir.
  • docker: close() stops and removes the container but keeps the host tmpdir. resolve() recreates a container over it.
  • New, optional provider methods:
    • WorkspaceProvider.destroy?(ref) deletes one workspace. It validates the ref exactly as resolve() does, and refuses (deleting nothing) a ref outside the provider's own storage.
    • WorkspaceProvider.reap?({ olderThan }) removes the provider's own abandoned workspaces, by last use. It never follows a link.
    • local-bash, local-sandbox, docker and in-memory implement destroy; local-bash and local-sandbox implement reap. The Cloudflare providers have neither yet, and keep their behaviour.
  • runtime-js keeps one workspace registry per session. A run takes a hold on it and releases the hold at its end. An inheriting child (inheritWorkspace: true) holds its parent's workspace until it ends, so a non-blocking companion still running after its parent's run keeps working on the same files.
  • Children end their own. A sub-agent or a companion consult with its own workspace keeps it across its own suspensions. When it ends (completed, failed or interrupted), the framework clears its stored ref and destroys the workspace, so a companion's next consult starts fresh. This is skipped for a provider without destroy.

destroyWorkspace / resetWorkspace ​

typescript
// From your own session deletion:
await executor.destroyWorkspace(sessionId);

// After a workspace_unavailable loss, or to start over:
await executor.resetWorkspace(sessionId);
  • What they do: both clear the session's stored workspace ref under the idle fence, then call the provider's destroy(ref). The session's next run opens a fresh workspace. In this release resetWorkspace is the same as destroyWorkspace.
  • A session with no stored workspace is a no-op.
  • Refused with AgentAlreadyRunningError, changing nothing:
    • while the session has a live run;
    • while a run or an inheriting child in this process still holds the workspace.
  • A provider without destroy (or one not registered on this executor) is refused with framework_not_supported.
  • If the provider's own delete fails, the error is rethrown after the ref is cleared. Nothing reattaches the workspace, and the provider's reap removes the leftover.

A lost workspace is typed: workspace_unavailable ​

  • When: a stored ref whose resolve() reports the workspace gone makes the registry entry 'unavailable'. Every workspace tool then fails with WorkspaceUnavailableError:

    • code: 'workspace_unavailable';
    • reason: 'not_found' | 'process_restarted';
    • non-retryable.

    Nothing is opened in its place. Before, the registry silently opened a fresh, empty workspace.

  • Typical causes:

    • the files were removed (a reap, a host wipe);
    • the request reached another replica (not_found);
    • an in-memory workspace's process restarted (process_restarted).
  • Signals:

    • onWorkspaceUnavailable (agent hook) and WorkspaceHooks.onUnavailable fire;
    • tracing-langfuse records an ERROR span.
  • Recovery: executor.resetWorkspace(sessionId).

  • onEvictionRetry / onWorkspaceEvictionRetry:

    • 'recovered' now always means the same workspace was reattached, never a fresh one;
    • 'exhausted' also fires when the retry finds the workspace gone (a WorkspaceUnavailableError), not only on a second eviction.

WorkspaceEntryStateKind gains 'unavailable' (the major) ​

The registry state union, also EntrySnapshot.state, has a new member. Code that switches over it exhaustively needs the new case:

typescript
// EntrySnapshot.state is WorkspaceEntryStateKind minus 'unknown' (peekState's no-entry sentinel).
switch (snapshot.state) {
  case 'configured':
  case 'opening':
  case 'open':
  case 'closing':
  case 'closed':
  case 'failed':
  case 'evicted':
    // …
    break;
  case 'unavailable':
    // New: the workspace is gone; tools fail with workspace_unavailable until resetWorkspace.
    break;
}

In-memory provider: a provider-level map ​

  • Reattaching: InMemoryWorkspaceProvider now keeps its workspaces in a provider-level map, so a session's workspace reattaches within the provider's process. Its ref is schema version 3 and carries the instance's nonce.
  • Restarts: after a restart, or on a new CF Durable Object instance, the ref is workspace_unavailable (process_restarted).
  • The map grows until destroy(ref), and the provider has no reap. A long-lived process calls destroyWorkspace(sessionId) for the sessions it's done with.
  • Peer dependency: the provider now declares zod as a peer dependency (core already requires it).

One replica per session for host-bound providers ​

local-bash, local-sandbox and docker store a workspace on one host. Serve a session's requests from the replica that holds its workspace (sticky routing by session id). A request that reaches another replica now fails with workspace_unavailable (not_found) instead of silently starting an empty workspace.

agent-server: expired sessions' workspaces are destroyed ​

  • What it does: for an expired session (expiresAt in the past) that is not completed or failed, expiredSessionCleanup now clears its stored ref under the idle fence, then destroys the workspace. The result's new workspacesDestroyed counts them.
  • What it skips:
    • a session with a live run is not touched, and counts in errors;
    • a provider without destroy is skipped;
    • completed and failed sessions are not handled here: their workspaces need your destroyWorkspace or the provider's reap.

See also ​

  • Workspaces: Lifecycle
  • Building a provider: destroy and reap for a custom provider.
  • The session-scoped workspaces design (phase 1 is the cut in its §13): docs/superpowers/specs/2026-11-14-session-scoped-workspaces-design.md.

Released under the MIT License.