Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

shell.ts

356 lines12.7 KB

1/**
2 * Internal persistent bootstrap shell.
3 *
4 * Spawns a single `sh` process via {@link SandboxHandle.process.spawn} and
5 * drives it over stdin/stdout with a sentinel-echo protocol. Commands run
6 * sequentially inside the same shell so `cd`, exported variables, etc. persist
7 * across calls — exactly the exec model the bootstrap setup plan needs.
8 *
9 * Providers WITHOUT a writable host→process stdin (`capabilities.writableStdin
10 * === false`, e.g. Cloudflare / Daytona / Vercel) can't be driven over stdin, so
11 * {@link createBootstrapShell} transparently falls back to an exec-backed shell
12 * ({@link createExecBootstrapShell}) that threads `cwd`/env across `exec` calls
13 * to reproduce the same persistent-shell semantics.
14 *
15 * This module is internal-only and must NOT be re-exported from
16 * `packages/ai-sandbox/src/index.ts`.
17 */
18import type { SandboxHandle } from './contracts'
19​
20/**
21 * Parse the output of `export -p` (or `declare -x`) into a plain env map.
22 * Shared by the stdin shell's `forkState` and the exec-backed shell.
23 */
24function parseExports(output: string): Record<string, string> {
25 const env: Record<string, string> = {}
26 for (const line of output.split('\n')) {
27 const trimmed = line.trim()
28 // Match `declare -x KEY=...` or `export KEY=...` forms.
29 const match =
30 /^(?:declare\s+-x\s+|export\s+)([A-Za-z_][A-Za-z0-9_]*)(?:="((?:[^"\\]|\\.)*)")?$/.exec(
31 trimmed,
32 )
33 if (match === null) continue
34 const key = match[1]
35 if (key === undefined) continue
36 // Value may be absent for exported-but-unset vars; skip those.
37 const raw = match[2]
38 if (raw === undefined) continue
39 // Unescape backslash-escaped chars inside double quotes.
40 env[key] = raw.replace(/\\(.)/g, '$1')
41 }
42 return env
44​
45/** The surface the bootstrap engine uses. */
46export interface BootstrapShell {
47 /** Run a shell command and capture its stdout + exit code. */
48 run: (command: string) => Promise<{ exitCode: number; stdout: string }>
49 /**
50 * Snapshot the shell's current working directory and exported environment.
51 * Used to fork parallel exec calls that inherit the serial shell's state.
52 */
53 forkState: () => Promise<{ cwd: string; env: Record<string, string> }>
54 /** End the shell session (closes stdin, kills the process). */
55 dispose: () => Promise<void>
57​
58/** Options for {@link createBootstrapShell}. */
59export interface BootstrapShellOptions {
60 /** Working directory to start the shell in (passed as ProcessOptions.cwd). */
61 cwd?: string
62 /**
63 * Belt-and-braces deadline for a single `run()` to see its sentinel. The
64 * primary termination condition is the stdout stream ending (see
65 * {@link createBootstrapShell}); this only catches a shell that is alive,
66 * silent, and never going to answer. Generous by default because setup steps
67 * legitimately run for a long time (`npm install`, image pulls).
68 */
69 commandTimeoutMs?: number
71​
72/** Default {@link BootstrapShellOptions.commandTimeoutMs} — 30 minutes. */
73const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60 * 1000
74​
75/** Race marker for the per-command deadline. A symbol cannot collide with a
76 * literal stdout line (a line of text `'timeout'` would). */
77const TIMED_OUT = Symbol('bootstrap-shell-timeout')
78​
79/**
80 * Spawn one `sh` process and return a {@link BootstrapShell} that drives it
81 * via the sentinel-echo protocol.
82 *
83 * Protocol: for each `run(cmd)` call, we write
84 * `<cmd>; printf "\n__BSSH_<N>__ $?\n"` to stdin, then read stdout lines
85 * until we see a line matching `__BSSH_<N>__ <exitCode>`. Everything before
86 * that line is the command's stdout; the trailing integer is the exit code.
87 * The counter `N` is a module-level monotonic integer — no Date.now / random.
88 */
89export async function createBootstrapShell(
90 handle: SandboxHandle,
91 opts: BootstrapShellOptions = {},
92): Promise<BootstrapShell> {
93 // Providers without a writable host→process stdin can't run the sentinel-echo
94 // protocol below (it feeds commands over stdin), so use the exec-backed shell.
95 if (!handle.capabilities.writableStdin) {
96 return createExecBootstrapShell(handle, opts)
97 }
98 const proc = await handle.process.spawn('sh', { cwd: opts.cwd })
99​
100 /*
101 * We need to read stdout lines across multiple run() calls while keeping
102 * the iterator open. Buffer chunks into lines manually.
103 */
104 const lineBuffer: Array<string> = []
105 // `null` means "the stdout stream ended" — distinct from an empty line, which
106 // `sh` emits constantly. Collapsing the two is what let a dead shell feed an
107 // infinite supply of `''` into a sentinel-hunting loop.
108 let pending: Array<(line: string | null) => void> = []
109 let streamDone = false
110 let streamError: unknown
111​
112 /** Feed the stdout async-iterable into the shared line queue. */
113 async function drainStdout(): Promise<void> {
114 let partial = ''
115 try {
116 for await (const chunk of proc.stdout) {
117 partial += chunk
118 const parts = partial.split('\n')
119 // All but the last element are complete lines.
120 for (let i = 0; i < parts.length - 1; i++) {
121 const line = parts[i] as string
122 const resolver = pending.shift()
123 if (resolver !== undefined) {
124 resolver(line)
125 } else {
126 lineBuffer.push(line)
127 }
128 }
129 partial = parts[parts.length - 1] as string
130 }
131 // Flush any trailing partial line.
132 if (partial.length > 0) {
133 const line = partial
134 const resolver = pending.shift()
135 if (resolver !== undefined) {
136 resolver(line)
137 } else {
138 lineBuffer.push(line)
139 }
140 }
141 } catch (error) {
142 // A throw while iterating stdout (transport reset, provider stream error)
143 // must NOT leave waiters parked on a promise nobody resolves. Record it so
144 // `run()` can name the cause, and fall through to the `finally` that
145 // unblocks everyone.
146 streamError = error
147 } finally {
148 streamDone = true
149 // Unblock any remaining waiters with the end-of-stream marker.
150 for (const resolver of pending) {
151 resolver(null)
152 }
153 pending = []
154 }
155 }
156​
157 /*
158 * Start draining immediately; do NOT await — runs concurrently. The `try/catch`
159 * inside `drainStdout` means this promise never rejects, so there is no
160 * unhandled rejection while nothing is awaiting it, and `dispose()` can await
161 * it unconditionally.
162 */
163 const drainPromise = drainStdout()
164​
165 /** Read the next line from the shared queue, or `null` once stdout ended. */
166 function nextLine(): Promise<string | null> {
167 const buffered = lineBuffer.shift()
168 if (buffered !== undefined) {
169 return Promise.resolve(buffered)
170 }
171 if (streamDone) {
172 return Promise.resolve(null)
173 }
174 return new Promise<string | null>((resolve) => {
175 pending.push(resolve)
176 })
177 }
178​
179 let counter = 0
180​
181 async function run(
182 command: string,
183 ): Promise<{ exitCode: number; stdout: string }> {
184 const id = counter
185 counter += 1
186 const sentinel = `__BSSH_${id}__`
187​
188 // Write the command followed by a sentinel printf to stdin. Merge the
189 // command's stderr into stdout (`{ … ; } 2>&1`) so a failing setup step's
190 // error text is captured and can be surfaced — otherwise only the exit code
191 // is visible. `$?` after the group is still the command's own exit code.
192 await proc.stdin.write(
193 `{ ${command} ; } 2>&1; printf "\\n${sentinel} $?\\n"\n`,
194 )
195​
196 const outputLines: Array<string> = []
197​
198 /*
199 * Read lines until we find the sentinel — but the wait MUST be able to end
200 * without one. `sh` can exit before it ever prints the sentinel (a missing
201 * binary, an OOM kill, the provider reaping the sandbox mid-bootstrap), and
202 * a loop whose only exit is the sentinel then spins on end-of-stream
203 * forever, pushing into `outputLines` until the host process dies of memory
204 * exhaustion. Two independent terminators:
205 * 1. `nextLine()` yields `null` the moment stdout is done — the real fix,
206 * it fires as soon as the shell is gone.
207 * 2. A deadline, for a shell that stays alive and simply never answers.
208 */
209 let timer: ReturnType<typeof setTimeout> | undefined
210 const deadline = new Promise<typeof TIMED_OUT>((resolve) => {
211 timer = setTimeout(
212 () => resolve(TIMED_OUT),
213 opts.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS,
214 )
215 })
216​
217 try {
218 for (;;) {
219 const line = await Promise.race([nextLine(), deadline])
220 if (line === TIMED_OUT) {
221 throw new Error(
222 `bootstrap shell: timed out after ${
223 opts.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS
224 }ms waiting for the sentinel of command: ${command}`,
225 )
226 }
227 if (line === null) {
228 throw new Error(
229 `bootstrap shell: the shell exited before the sentinel was printed; command: ${command}`,
230 streamError === undefined ? undefined : { cause: streamError },
231 )
232 }
233 if (line.startsWith(`${sentinel} `)) {
234 const codeStr = line.slice(sentinel.length + 1).trim()
235 const exitCode = parseInt(codeStr, 10)
236 return {
237 exitCode: Number.isFinite(exitCode) ? exitCode : 1,
238 stdout: outputLines.join('\n'),
239 }
240 }
241 outputLines.push(line)
242 }
243 } finally {
244 clearTimeout(timer)
245 }
246 }
247​
248 async function forkState(): Promise<{
249 cwd: string
250 env: Record<string, string>
251 }> {
252 const pwdResult = await run('pwd')
253 const cwd = pwdResult.stdout.trim()
254​
255 const exportResult = await run('export -p')
256 return { cwd, env: parseExports(exportResult.stdout) }
257 }
258​
259 async function dispose(): Promise<void> {
260 await proc.stdin.end()
261 await proc.kill()
262 // Drain the stdout iterator to completion so there are no dangling promises.
263 await drainPromise
264 }
265​
266 return { run, forkState, dispose }
268​
269/**
270 * Exec-backed {@link BootstrapShell} for providers WITHOUT a writable stdin.
271 *
272 * There is no persistent process to feed commands into, so persistence of `cd`
273 * and exported variables is reproduced by threading state across discrete
274 * {@link SandboxHandle.process.exec} calls: each `run()` executes the command in
275 * the tracked cwd+env, then captures the resulting `pwd` and `export -p` (via
276 * marker lines) so the NEXT command inherits any directory change or exports.
277 */
278export function createExecBootstrapShell(
279 handle: SandboxHandle,
280 opts: BootstrapShellOptions = {},
281): BootstrapShell {
282 let cwd = opts.cwd ?? '/'
283 let env: Record<string, string> = {}
284 let counter = 0
285​
286 async function run(
287 command: string,
288 ): Promise<{ exitCode: number; stdout: string }> {
289 const id = counter
290 counter += 1
291 const sentinel = `__BSSH_${id}__`
292​
293 // Run the command, then emit its exit code, cwd and exported env behind
294 // marker lines so we can recover state even when the command itself fails
295 // (no `set -e`). Capturing `$?` immediately after the command keeps the
296 // reported exit code the command's own, not the trailing introspection's.
297 const script = [
298 command,
299 `__bssh_rc=$?`,
300 `printf '\\n%s %s\\n' '${sentinel}' "$__bssh_rc"`,
301 `printf '%s\\n' '${sentinel}_CWD'`,
302 `pwd`,
303 `printf '%s\\n' '${sentinel}_ENV'`,
304 `export -p`,
305 ].join('\n')
306​
307 const res = await handle.process.exec(script, { cwd, env })
308​
309 const cmdOut: Array<string> = []
310 const cwdLines: Array<string> = []
311 const envLines: Array<string> = []
312 let exitCode = res.exitCode
313 let phase: 'cmd' | 'await-cwd' | 'cwd' | 'env' = 'cmd'
314​
315 for (const line of res.stdout.split('\n')) {
316 if (phase === 'cmd') {
317 if (line.startsWith(`${sentinel} `)) {
318 const parsed = parseInt(line.slice(sentinel.length + 1).trim(), 10)
319 exitCode = Number.isFinite(parsed) ? parsed : res.exitCode
320 phase = 'await-cwd'
321 continue
322 }
323 cmdOut.push(line)
324 } else if (phase === 'await-cwd') {
325 if (line === `${sentinel}_CWD`) phase = 'cwd'
326 } else if (phase === 'cwd') {
327 if (line === `${sentinel}_ENV`) phase = 'env'
328 else cwdLines.push(line)
329 } else {
330 envLines.push(line)
331 }
332 }
333​
334 // `pwd` prints a single line; the last non-empty one is the new cwd.
335 const newCwd = cwdLines
336 .map((l) => l.trim())
337 .filter(Boolean)
338 .pop()
339 if (newCwd) cwd = newCwd
340 const newEnv = parseExports(envLines.join('\n'))
341 if (Object.keys(newEnv).length > 0) env = newEnv
342​
343 return { exitCode, stdout: cmdOut.join('\n') }
344 }
345​
346 function forkState(): Promise<{ cwd: string; env: Record<string, string> }> {
347 return Promise.resolve({ cwd, env: { ...env } })
348 }
349​
350 function dispose(): Promise<void> {
351 // Nothing to tear down — there is no persistent process.
352 return Promise.resolve()
353 }
354​
355 return { run, forkState, dispose }