The one-machine file bridge: @path in, outputFile out

Control plane stays embedded (D28); the chat's workbench sandbox
becomes the agent's filesystem, bridged by the sim_cli handler in both
directions. @-shaped argv tokens are pre-read from the session sandbox
into the embed context, and the CLI's OWN argument resolver consults
that map — so only genuinely file-accepting flags get file semantics
(a literal --text @channel stays literal) and the server's filesystem
stays unreadable from model argv (the earlier refusal remains as
defense in depth, now worded as this machine's not-found). outputFile
lands command stdout on the machine as a file and returns a short ack,
so exports and traces never transit the model's context. Find-only by
design: a cold machine degrades to inline with boot guidance.

Live e2e of the full loop: trace pulled to file (ack only), run_code
computed on it, @env.json fed a manual run byte-exact.

Claude-Session: https://claude.ai/code/session_01CgaxNAaeD3taGdghbXn17w

Author: Sg312

apps/sim/lib/execution/remote-sandbox/session-files.ts

@@ -0,0 +1,84 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { resolveProvider } from '@/lib/execution/remote-sandbox/provider'
+
+const logger = createLogger('SessionSandboxFiles')
+
+/**
+ * File I/O against an EXISTING session sandbox — the bridge that lets the
+ * Mothership's embedded CLI treat the chat's workbench as its filesystem:
+ * `@path` arguments read from it, `outputFile` writes command output into it,
+ * while the CLI itself keeps executing in-process on the server. Find-only by
+ * design: booting the machine belongs to the execution path (run_code), so a
+ * missing session degrades to an actionable answer instead of paying a sandbox
+ * spin-up inside a CLI call.
+ *
+ * Session sandboxes exist only on providers with session support (E2B), whose
+ * mothership image runs the default user at this home directory — the pinned
+ * cwd contract for relative paths.
+ */
+export const SESSION_SANDBOX_HOME = '/home/user'
+
+const READ_LIMIT_BYTES = 4 * 1024 * 1024
+
+export function resolveSessionPath(path: string): string {
+  return path.startsWith('/') ? path : `${SESSION_SANDBOX_HOME}/${path}`
+}
+
+export type SessionFileRead =
+  | { outcome: 'read'; content: string }
+  | { outcome: 'no-session' }
+  | { outcome: 'no-file'; detail: string }
+
+export async function readSessionSandboxFile(
+  sessionKey: string,
+  path: string
+): Promise<SessionFileRead> {
+  const provider = resolveProvider()
+  if (!provider.findSessionSandbox) return { outcome: 'no-session' }
+  let sandbox: Awaited<ReturnType<NonNullable<typeof provider.findSessionSandbox>>>
+  try {
+    sandbox = await provider.findSessionSandbox(sessionKey, {})
+  } catch (error) {
+    logger.warn('Session sandbox lookup failed for file read', {
+      sessionKey,
+      error: getErrorMessage(error),
+    })
+    return { outcome: 'no-session' }
+  }
+  if (!sandbox) return { outcome: 'no-session' }
+  try {
+    const file = await sandbox.readFileWithLimit(resolveSessionPath(path), {
+      maxBytes: READ_LIMIT_BYTES,
+      encoding: 'utf8',
+    })
+    return { outcome: 'read', content: file.content }
+  } catch (error) {
+    return { outcome: 'no-file', detail: getErrorMessage(error) }
+  }
+}
+
+export type SessionFileWrite = { outcome: 'written'; path: string } | { outcome: 'no-session' }
+
+export async function writeSessionSandboxFile(
+  sessionKey: string,
+  path: string,
+  content: string
+): Promise<SessionFileWrite> {
+  const provider = resolveProvider()
+  if (!provider.findSessionSandbox) return { outcome: 'no-session' }
+  let sandbox: Awaited<ReturnType<NonNullable<typeof provider.findSessionSandbox>>>
+  try {
+    sandbox = await provider.findSessionSandbox(sessionKey, {})
+  } catch (error) {
+    logger.warn('Session sandbox lookup failed for file write', {
+      sessionKey,
+      error: getErrorMessage(error),
+    })
+    return { outcome: 'no-session' }
+  }
+  if (!sandbox) return { outcome: 'no-session' }
+  const resolved = resolveSessionPath(path)
+  await sandbox.writeFile(resolved, content)
+  return { outcome: 'written', path: resolved }
+}

apps/sim/lib/mothership/tools/handlers/sim-cli.ts

@@ -1,6 +1,10 @@
 import { createLogger } from '@sim/logger'
 import { createEmbeddedClient, type EmbeddedCliIdentity, runEmbeddedCli } from 'sim/embed'
 import { getInternalApiBaseUrl } from '@/lib/core/utils/urls'
+import {
+  readSessionSandboxFile,
+  writeSessionSandboxFile,
+} from '@/lib/execution/remote-sandbox/session-files'
 import { mintDelegationToken } from '@/lib/mothership/chat/delegation'
 import type {
   ToolExecutionContext,
@@ -44,11 +48,31 @@ export async function executeSimCli(
   if (!context.workspaceId) {
     return { success: false, error: 'sim_cli requires a workspace-scoped execution context.' }
   }
-  const { cliArgs: args, stages } = splitPipeline(rawArgs)
-  if (args.length === 0) {
+  const { cliArgs: rawCliArgs, stages } = splitPipeline(rawArgs)
+  if (rawCliArgs.length === 0) {
     return { success: false, error: 'A pipe needs a sim CLI invocation before the first |.' }
   }
 
+  const args = rawCliArgs
+
+  // The chat's workbench sandbox is the agent's filesystem: every @-shaped token
+  // is pre-read from it into a map the embedded CLI's OWN argument resolver
+  // consults — so only genuinely file-aware flags get file semantics (a literal
+  // `--text @channel` stays literal), and the server's filesystem is never
+  // readable from model argv. A token that names no sandbox file is simply
+  // absent from the map; the resolver's refusal then says so.
+  const sessionKey = context.chatId ? `mothership-chat:${context.chatId}` : null
+  const fileArguments: Record<string, string> = {}
+  if (sessionKey) {
+    for (const token of args) {
+      if (!token.startsWith('@') || token.startsWith('@@') || token === '@-') continue
+      const path = token.slice(1)
+      if (fileArguments[path] !== undefined) continue
+      const read = await readSessionSandboxFile(sessionKey, path)
+      if (read.outcome === 'read') fileArguments[path] = read.content
+    }
+  }
+
   // Stages are validated before the CLI runs: a mutating command must never
   // execute and then fail on a malformed pipe, or a model retry would repeat
   // the mutation.
@@ -77,7 +101,7 @@ export async function executeSimCli(
         workspaceId: context.workspaceId,
         userId: context.userId,
       })
-    : await runEmbeddedCli(args, identity)
+    : await runEmbeddedCli(args, identity, { fileArguments })
   if (!agentMatch && isRootHelpInvocation(args) && result.exitCode === 0) {
     result.stdout += agentCliHelpSection()
   }
@@ -86,6 +110,24 @@ export async function executeSimCli(
     if (piped.ok) result.stdout = piped.stdout
   }
 
+  // outputFile: land large stdout directly on the agent's machine instead of
+  // returning it through the model window — the other half of the file bridge.
+  const outputFile = typeof params.outputFile === 'string' ? params.outputFile.trim() : ''
+  if (outputFile && result.exitCode === 0) {
+    if (!sessionKey) {
+      result.stdout +=
+        '\n[outputFile not written: no chat-scoped machine — output returned inline instead]'
+    } else {
+      const written = await writeSessionSandboxFile(sessionKey, outputFile, result.stdout)
+      if (written.outcome === 'written') {
+        result.stdout = `[stdout written to ${outputFile} on your machine: ${result.stdout.length} chars. Read or process it with run_code, or pass it back as @${outputFile}.]`
+      } else {
+        result.stdout +=
+          '\n[outputFile not written: your machine is not booted yet — run any run_code first. Output returned inline instead]'
+      }
+    }
+  }
+
   logger.info('CLI invocation finished', {
     exitCode: result.exitCode,
     argv0: args[0],

packages/sim-cli/src/embed-context.ts

@@ -17,6 +17,13 @@ export interface EmbedContext {
   identity: EmbeddedCliIdentity
   stdout: string[]
   stderr: string[]
+  /**
+   * Pre-read contents for `@path` file arguments, keyed by the path as written
+   * (without the `@`). The host resolves these from the caller's own file
+   * surface before the run; the in-process CLI never touches the server's
+   * filesystem.
+   */
+  fileArguments?: Record<string, string>
 }
 
 export const embedStore = new AsyncLocalStorage<EmbedContext>()

packages/sim-cli/src/embed.ts

@@ -68,10 +68,16 @@ export function createEmbeddedClient(identity: EmbeddedCliIdentity): SimClient {
  */
 export async function runEmbeddedCli(
   argv: string[],
-  identity: EmbeddedCliIdentity
+  identity: EmbeddedCliIdentity,
+  options?: { fileArguments?: Record<string, string> }
 ): Promise<EmbeddedCliResult> {
   installEmbedSinks()
-  const ctx: EmbedContext = { identity, stdout: [], stderr: [] }
+  const ctx: EmbedContext = {
+    identity,
+    stdout: [],
+    stderr: [],
+    ...(options?.fileArguments ? { fileArguments: options.fileArguments } : {}),
+  }
   return embedStore.run(ctx, async () => {
     let exitCode = 0
     try {

packages/sim-cli/src/runtime/embedded-file-args.test.ts

@@ -6,19 +6,34 @@ import { embedStore } from '../embed-context'
 import { readArgumentSource } from './request'
 
 describe('file arguments in embedded runs', () => {
-  it('refuses @path reads in-process, with inline guidance', () => {
+  it('refuses @path reads in-process when the host preloaded nothing', () => {
     const ctx = {
       identity: { endpoint: 'http://x', apiKey: 'k' },
       stdout: [] as string[],
       stderr: [] as string[],
     }
     embedStore.run(ctx, () => {
       expect(() => readArgumentSource('@/etc/hostname', 'input')).toThrow(
-        /not available in embedded runs.*inline/
+        /no file "\/etc\/hostname" on this machine/
       )
     })
   })
 
+  it('serves @path from host-preloaded file arguments, never local disk', () => {
+    const ctx = {
+      identity: { endpoint: 'http://x', apiKey: 'k' },
+      stdout: [] as string[],
+      stderr: [] as string[],
+      fileArguments: { 'env.json': '{"thread":"t1"}' },
+    }
+    embedStore.run(ctx, () => {
+      const resolved = readArgumentSource('@env.json', 'input')
+      expect(resolved.text).toBe('{"thread":"t1"}')
+      expect(resolved.from).toContain('your machine')
+      expect(() => readArgumentSource('@other.json', 'input')).toThrow(/no file "other.json"/)
+    })
+  })
+
   it('keeps @@ literal escape and inline values working embedded', () => {
     const ctx = {
       identity: { endpoint: 'http://x', apiKey: 'k' },

packages/sim-cli/src/runtime/request.ts

@@ -203,13 +203,16 @@ export function readArgumentSource(raw: string, flagName: string): { text: strin
   if (raw.startsWith('@@')) return { text: raw.slice(1), from: '' }
   if (!raw.startsWith('@')) return { text: raw, from: '' }
 
-  // An embedded run executes in-process on the hosting server, so a file path
-  // here would read the SERVER's filesystem with argv the model controls.
-  // There is no local file a caller could legitimately mean; the value must
-  // arrive inline (or as @@-escaped literal text).
-  if (embedStore.getStore()) {
+  // An embedded run executes in-process on the hosting server, so a raw file
+  // path here would read the SERVER's filesystem with argv the model controls.
+  // The host may pre-resolve @paths from the caller's own file surface into the
+  // embed context; anything else is refused — never read from local disk.
+  const embedded = embedStore.getStore()
+  if (embedded) {
+    const preloaded = embedded.fileArguments?.[raw.slice(1)]
+    if (preloaded !== undefined) return { text: preloaded, from: ' (read from your machine)' }
     throw new SimApiError(
-      `--${flagName} file arguments (@path) are not available in embedded runs — pass the JSON inline as a single argument`,
+      `--${flagName}: no file "${raw.slice(1)}" on this machine — write it first (run_code), or pass the value inline`,
       0
     )
   }