feat(harness): memfs-less worker agents and explicit per-session memory scopes#3285
Merged
Conversation
…ry scopes Support for pipelines (e.g. the agent SDK's dreaming) that run many concurrent sessions on shared worker agents, each scoped to an isolated memory copy: - runtime_start create_agent gains memfs?: boolean. memfs: false creates a worker-style agent with NO memory filesystem: the memfs tag stamp, settings enable, and repo clone are skipped, and the agent is recorded as explicitly memfs-disabled. - Settings can now represent explicit memfs: false (previously stripped as a falsy value, making "deliberately memfs-less" unrepresentable), read via settingsManager.isMemfsExplicitlyDisabled(). - The listener's lazy memfs repair (which force-enables memfs for any untagged cloud agent) exempts explicitly memfs-disabled agents — they are workers, not broken agents. - The shell-env memory guard honors an EXPLICIT inherited memory scope (LETTA_MEMORY_DIR_EXPLICIT=1) when it lies outside the agents' memory store: such a path cannot be another agent's memory, which is what the guard protects. A launcher can therefore point a worker session's $MEMORY_DIR at an isolated memory copy (e.g. a dream batch's memfs clone). Unmarked non-parent-scoped values are still stripped as stale leakage, and an explicit marker pointing INTO another agent's store is still rejected.
sarahwooders
requested review from
4shub,
carenthomas,
christinatong01,
cpacker,
jnjpng and
kl2806
as code owners
July 9, 2026 03:55
devanshrj
approved these changes
Jul 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes around deliberately memfs-less agents, plus support for overriding a session's memory directory: the shell-env memory guard can now honor an explicitly-provided
MEMORY_DIRinstead of stripping it.Memory-scope override (the main change)
The shell-env guard strips inherited
MEMORY_DIR/LETTA_MEMORY_DIRfor memfs-less agents unless the value is parent-scoped — any other value is treated as stale leakage. That made it impossible for a launcher to deliberately scope a session's memory to an isolated copy (e.g. a clone of a memory filesystem that a background worker should edit in place).A launcher can now mark the scope as intentional with
LETTA_MEMORY_DIR_EXPLICIT=1. The guard honors the marked value iff it lies outside the agents' memory store — a path outside the store cannot be another agent's memory, which is the threat the guard exists to prevent. Concretely:$MEMORY_DIRresolves in the session)Bug fixes
memfs: falsecould not be persisted.upsertAgentSettingsdeleted falsy values, so "deliberately memfs-less" was unrepresentable in settings — indistinguishable from "never configured". Explicitfalseis now kept, readable viasettingsManager.isMemfsExplicitlyDisabled().create_agenthad no memfs opt-out. Every agent created throughruntime_startgot the memfs tag/settings/clone unconditionally.create_agent.memfs?: booleannow allowsmemfs: false, which skips the setup and records the agent as explicitly memfs-disabled (wiring into the two fixes above).Test plan
tsc --noEmitclean; layer/boundary/filename checks pass (pre-commit)bun test src/tools/shell-env.test.ts src/settings-manager.test.ts src/websocket/app-server.test.ts— 107 pass / 0 fail, including new guard tests for all three override casesmemfs: falsepersists the setting, gets no memory repo, and is not "repaired" at session start; a session launched withMEMORY_DIR=/tmp/probe-memory+ the explicit marker resolves$MEMORY_DIRto that path inside the session