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
- 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. - Reap abandoned workspaces on a schedule. For local-bash and local-sandbox, call
provider.reap({ olderThan })from a cron or alarm. PickolderThanlonger than your longest run plus how long a session's workspace should be kept when idle. - 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.
- Handle
workspace_unavailable. When a stored workspace can't be reattached, workspace tools fail with it. Callexecutor.resetWorkspace(sessionId)to start the session over with a fresh workspace (see below). - Update exhaustive
switches overWorkspaceEntryStateKind/EntrySnapshot.stateto 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 asresolve()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 implementreap. 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,failedorinterrupted), the framework clears its stored ref and destroys the workspace, so a companion's next consult starts fresh. This is skipped for a provider withoutdestroy.
destroyWorkspace / resetWorkspace
// 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 releaseresetWorkspaceis the same asdestroyWorkspace. - 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 withframework_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
reapremoves 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 withWorkspaceUnavailableError: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) andWorkspaceHooks.onUnavailablefire;- tracing-langfuse records an
ERRORspan.
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 (aWorkspaceUnavailableError), 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:
// 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:
InMemoryWorkspaceProvidernow 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 noreap. A long-lived process callsdestroyWorkspace(sessionId)for the sessions it's done with. - Peer dependency: the provider now declares
zodas 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 (
expiresAtin the past) that is notcompletedorfailed,expiredSessionCleanupnow clears its stored ref under the idle fence, then destroys the workspace. The result's newworkspacesDestroyedcounts them. - What it skips:
- a session with a live run is not touched, and counts in
errors; - a provider without
destroyis skipped; - completed and failed sessions are not handled here: their workspaces need your
destroyWorkspaceor the provider'sreap.
- a session with a live run is not touched, and counts in
See also
- Workspaces: Lifecycle
- Building a provider:
destroyandreapfor 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.