Support skills and project context in the zero-config virtual sandbox

[FredKSchott]

The default zero-config virtual sandbox should ideally support project context like skills and AGENTS.md without requiring users to switch to sandbox: "local" or manually configure a custom virtual sandbox.

Today this is difficult because the agent discovers skills and context during init(), but the built-in virtual sandbox does not have an obvious setup phase where those files can be added before initialization. We should explore an API or runtime behavior that makes this work by default while preserving the isolation benefits of the virtual sandbox.

Moved from issue #43: #43

[stainlu]

from the managed-agent angle, this feels like an environment preparation problem, not a session problem.

init() currently discovers context after the sandbox exists. the zero-config virtual sandbox starts empty, so there is no phase where project context can enter before discovery.

maybe the primitive is a small prepare step for sandbox/context:

• default virtual sandbox can copy allowed project context into its fs before discovery (AGENTS.md, .agents/skills/**)
• external sandboxes can implement the same capability or fail loudly
• cwd stays explicit, so discovery path is deterministic
• keep it capability-gated so Flue does not fake parity across sandbox types

that would keep the default fast virtual sandbox useful while preserving isolation. it also avoids making users choose sandbox: "local" just to get project memory/skills.

[FredKSchott]

I just discovered https://www.strukto.ai/mirage which feels like an even more powerful just-bash, which is what we use today for our built-in sandbox.

I'm realizing that this space is going to be changing quickly. Maybe we just want to lean into this:

• by default, Flue agents have no sandbox. They can still operate like a harness, but no read | write | bash tools provided. You can still provide custom commands as tools.
• if you want your agent to have a sandbox, you pass it in, even the virtual in-memory on.

This way we're not tied to any one sandbox. You can provide just-bash, @cloudflare/shell, or mirage, all would be valid virtual sandboxes.

Plus then that solves the "how do I pass files to the virtual sandbox?" problem, because you'd be in control of its initialization, instead of today, where that is hidden from you.

[stainlu]

yeah this direction feels very managed-agents-aligned to me.

the Anthropic framing is basically: brain / session / hands should be separate. just-bash is one possible hand, not the framework boundary.

so maybe the split is:

• Agent: instructions, skills, model defaults, tools/policy
• Environment: sandbox capabilities: fs, bash, packages, network, persistence
• Session: durable event/context log
• Harness: the loop

today Flue couples some of these because init() discovers AGENTS.md + skills from SessionEnv, and SessionEnv also implies read/write/bash/grep/glob tools.

if default becomes “no sandbox”, i think that fits, but only if “no sandbox” means “no built-in filesystem/bash tools”, not “no project context.”

rough shape:

await init({
  model,
  context: projectContext(),      // AGENTS.md + skills
  sandbox: virtualSandbox(),      // optional hands
});

or maybe context lives on config later, but the key is: project memory should not require granting a shell/filesystem.

so +1 on explicit sandbox. i’d just keep ContextSource and Sandbox / Environment as separate primitives. that feels closer to managed agents than making hidden just-bash smarter.

[musaabhasan]

I would model this as a prepared context bundle rather than letting the virtual sandbox discover project context opportunistically during init().

A possible flow:

1. Host side resolves allowed context files: AGENTS.md, selected skills, project metadata, maybe package manifests.
2. The sandbox receives a read-only context bundle before agent initialization.
3. Agent init() reads from a stable virtual path such as /context or a declared API.
4. The runtime records the bundle hash/version in session metadata.

That keeps zero-config behavior while preserving isolation. It also avoids accidentally mounting the whole project or user home just so the agent can discover a few context files.

The main design question is policy: which files are allowed into the bundle, and can project code influence that selection? For safety, I would start with a small explicit allowlist and make additional context opt-in.

[ketankhairnar]

+1 to the explicit-sandbox direction. Grounded in code: the gap is real. getVirtualSandbox() in packages/sdk/src/cloudflare/virtual-sandbox.ts returns a BashFactory thunk with no pre-init phase, and discoverContext() in context.ts reads AGENTS.md / .agents/skills/** out of the already-built SessionEnv. So today, "project memory" is structurally tied to "has a filesystem sandbox," which is exactly the coupling stainlu's split dissolves.

Two small things worth pinning down before the API lands:

1. Capability declaration. If Environment becomes optional, the harness needs a typed answer to "do I have fs / bash / network?" so tools and discovery degrade explicitly rather than throwing at first use.
2. Migration for sandbox: "local". Today that path implicitly carries project context. If the new default is no-sandbox, decide whether local auto-wires projectContext({ cwd }) for back-compat or whether it's a breaking change with a codemod.

Happy to take a small PR once the shape is settled. Changes look contained to agent.ts (init() signature), context.ts (source-driven discovery), and the sandbox factories.

[musaabhasan]

Agree with the capability-declaration point. I would make that part testable rather than only API-shape guidance.

A small contract could be enough:

• capabilities.fs: none, read_context_only, workspace_rw
• capabilities.shell: none, restricted, full
• capabilities.network: none, allowlisted, open
• context_bundle: manifest hash, allowed files, source paths, and generated-at timestamp
• degraded_reason: why discovery skipped a source instead of throwing

Then the useful fixtures become straightforward: no filesystem but a valid read-only context bundle; missing skills directory; network disabled; context bundle hash mismatch; and a tool that asks for shell when the environment declares shell=none.

That would keep zero-config behavior convenient while making sandbox authority explicit and reviewable.

[stainlu]

looked at this again after #109 / #111, and i think the clean first cut is even smaller than a full capability taxonomy.

right now the hard coupling is:

• discoverSessionContext(env) reads AGENTS.md + .agents/skills/** from SessionEnv
• SessionEnv is also the authority that gives the model read/write/bash/grep/glob
• session.skill(name) assumes the model can later read the skill file from that same filesystem

so if the default becomes “no sandbox”, Flue accidentally loses project context too. imo those should split before we debate the full environment API.

rough v1:

interface ContextSource {
  cwd: string;
  readFile(path: string): Promise<string>;
  exists(path: string): Promise<boolean>;
  readdir(path: string): Promise<string[]>;
  stat(path: string): Promise<FileStat>;
  resolvePath(path: string): string;
}

then:

• discoverSessionContext(source) reads from ContextSource, not SessionEnv
• default/back-compat path is just contextSourceFromSessionEnv(env)
• later, projectContext({ root }) can be read-only host context with no shell/write authority
• SessionEnv stays the hands: fs tools + shell + cwd execution
• sandbox connectors do not need to learn how to import project memory unless they explicitly want to

one design detail that matters: named skills should probably record their resolved path/source in the registry. if the execution env can read that path, keep today’s “model reads the skill file” behavior. if context is read-only and no sandbox exists, either inline the SKILL.md body for that call or expose a tiny read-only context tool. i lean inline for v1 because it keeps “no sandbox” truly no-tools, and relative skill references can fail loudly until there is a context-tool follow-up.

so maybe the PR sequence is:

1. internal refactor: introduce ContextSource, keep current behavior exactly by adapting SessionEnv
2. add context: projectContext() / config wiring once the boundary is real
3. only then change the default sandbox story

this feels like the smallest step toward explicit sandbox ownership without making Flue own every sandbox provider’s initialization story.

[stainlu]

opened #114 as the small first cut here.

kept it intentionally boring:

• ContextSource is read-only
• current SessionEnv behavior is preserved through an adapter
• no new config / projectContext() API yet
• test proves context discovery can run without shell/write authority

if that boundary feels right, the next layer can be actual project-context wiring instead of making every sandbox connector own AGENTS.md / skills loading.

[astrobot-houston]

Possibly related contribution from @stainlu — opened #114 which appears to be addressing this.

Their summary: Introduces a read-only ContextSource interface that decouples project context discovery (AGENTS.md, skill resolution, cwd listing) from the full SessionEnv sandbox surface. Existing behavior is preserved via a contextSourceFromSessionEnv() adapter, and a new test verifies context discovery works without shell/write access. This lays groundwork for supporting project context loading without requiring a full sandbox.

Implementation: stainlu/flue@context-source-boundary (diff)

This comment was posted automatically when #114 was redirected. The implementation is preserved on the branch above so it can inform the work here.