Open History to see the last commit
1/**
2 * Wiring test for the durable-run seam in `../src/adapters/text.ts`: the
3 * `runId` resolution, the journal option, and the attach-time alignment all
4 * come from `getSandboxDurability` (the capability `withSandbox(sandbox,
5 * { runs, durability })` provides) rather than being hardcoded.
6 *
7 * Every `runId` here is unique per test (`crypto.randomUUID()`), and every
8 * assertion is against the actual spawned/exec'd COMMAND string — not the
9 * journal file's existence — because the journal is deleted once a run
10 * reaches its `{"__exit":N}` sentinel (see `translate-determinism.test.ts`'s
11 * wiring block for the same rationale).
12 */
13import { afterAll, describe, expect, it } from 'vitest'
14import * as fsp from 'node:fs/promises'
15import * as os from 'node:os'
16import * as path from 'node:path'
17import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'
18import {
19 chunkFingerprint,
20 createRunScopedIdGen,
21 exitSentinelLine,
22 journalPaths,
23} from '@tanstack/ai-sandbox'
24import { claudeCodeText } from '../src/index'
25import { translateSdkStream } from '../src/stream/translate'
26import {
27 capabilityContextWith,
28 fakeDurability,
29 noopLogger,
30 pollStrategyHandle,
31} from './fakes'
32import type { StreamChunk } from '@tanstack/ai'
33import type { AgentSdkMessage } from '../src/stream/sdk-types'
34
35const baseDir = path.join(
36 os.tmpdir(),
37 `tanstack-ai-cc-attach-test-${Date.now()}`,
38)
39const provider = localProcessSandbox({ baseDir, removeOnDestroy: true })
40
41afterAll(async () => {
42 try {
43 await fsp.rm(baseDir, { recursive: true, force: true })
44 } catch {
45 // Windows can report EBUSY here when a child process handle briefly
46 // outlives `sbx.destroy()`; a cleanup nicety, not part of what the test
47 // verifies.
48 }
49})
50
51// Same stand-in as `text-adapter.test.ts`: ignores its flags, reads the
52// prompt from stdin, then emits stream-json (system/init → assistant text →
53// result). Its filename ("fake-claude") is asserted to be ABSENT from the
54// spawned commands on the attach path, proving the agent was never started.
55const FAKE_CLAUDE = [
56 `let input = ''`,
57 `process.stdin.on('data', (d) => { input += d })`,
58 `process.stdin.on('end', () => {`,
59 ` const w = (o) => process.stdout.write(JSON.stringify(o) + '\\n')`,
60 ` w({ type: 'system', subtype: 'init', session_id: 'sess-abc', model: 'haiku', tools: [] })`,
61 ` w({ type: 'assistant', message: { id: 'msg-1', content: [{ type: 'text', text: 'pong' }] }, parent_tool_use_id: null })`,
62 ` w({ type: 'result', subtype: 'success', result: 'pong', usage: { input_tokens: 1, output_tokens: 1 } })`,
63 `})`,
64].join('\n')
65
66function newRunId(label: string): string {
67 return `r-${label}-${crypto.randomUUID()}`
68}
69
70async function collect(
71 stream: AsyncIterable<StreamChunk>,
72): Promise<Array<StreamChunk>> {
73 const out: Array<StreamChunk> = []
74 for await (const chunk of stream) out.push(chunk)
75 return out
76}
77
78/**
79 * The DISTINCT `threadId`s stamped across a run's chunks.
80 *
81 * A set, not a list, because `threadId` appears on several chunk types
82 * (`RUN_STARTED`, `RUN_FINISHED`, …) and what matters is that they all agree on
83 * one id — the caller's on an attach, a generated one otherwise. Anything with
84 * more than one entry means the resolution ran twice.
85 */
86function threadIdsOf(chunks: Array<StreamChunk>): Array<string> {
87 const seen = new Set<string>()
88 for (const chunk of chunks) {
89 const value = (chunk as { threadId?: unknown }).threadId
90 if (typeof value === 'string') seen.add(value)
91 }
92 return [...seen]
93}
94
95/**
96 * Pre-populate a run's journal directly through the shell (never `fs.write` —
97 * see `journal.ts` rule 3: on local-process, `fs.write` resolves `/tmp` under
98 * the sandbox root while a shell redirect hits the real host `/tmp`, and only
99 * the latter is where the reader looks). Base64-encoded so the NDJSON content
100 * (which contains double quotes) never has to survive shell quoting.
101 */
102async function seedJournal(
103 sbx: Awaited<ReturnType<typeof provider.create>>,
104 runId: string,
105 lines: Array<AgentSdkMessage | { __exit: number }>,
106): Promise<void> {
107 const paths = journalPaths(runId)
108 // The exit sentinel is built by `exitSentinelLine`, never hand-JSON-stringified:
109 // it carries a per-run nonce so an agent's own stdout cannot forge it
110 // (`ai-sandbox`'s `journal.ts`), and a bare `{"__exit":0}` is therefore agent
111 // output that the reader deliberately does NOT stop at.
112 const content = `${lines
113 .map((l) =>
114 '__exit' in l ? exitSentinelLine(paths, l.__exit) : JSON.stringify(l),
115 )
116 .join('\n')}\n`
117 const b64 = Buffer.from(content, 'utf8').toString('base64')
118 const result = await sbx.process.exec(
119 `mkdir -p ${paths.dir} && printf '%s' ${b64} | base64 -d >> ${paths.journal}`,
120 )
121 if (result.exitCode !== 0) {
122 throw new Error(`seedJournal failed: ${result.stdout} ${result.stderr}`)
123 }
124}
125
126describe('claude-code durable-run wiring (attach path)', () => {
127 it('does NOT journal when no durability is wired — byte-identical to a pre-durability run', async () => {
128 // No `SandboxDurabilityCapability` provided at all (the default: an app
129 // that hasn't wired `runs`/`durability` into `withSandbox`). Before Phase
130 // 3 this adapter journaled every run unconditionally; this pins the new
131 // guarantee that a non-durable run's observable behavior — including
132 // "does spawnNdjson ever touch a journal file" — is unchanged.
133 const sbx = await provider.create({})
134 await sbx.fs.write('/workspace/fake-claude.mjs', FAKE_CLAUDE)
135 const recorder = pollStrategyHandle(sbx)
136 const runId = newRunId('no-durability')
137
138 const adapter = claudeCodeText('haiku', {
139 claudeExecutable: 'node fake-claude.mjs',
140 streamPartials: false,
141 emitDiff: false,
142 })
143
144 const chunks = await collect(
145 adapter.chatStream({
146 model: 'haiku',
147 messages: [{ role: 'user', content: 'say pong' }],
148 logger: noopLogger,
149 runId,
150 capabilities: capabilityContextWith(recorder.handle),
151 }),
152 )
153
154 expect(chunks.some((c) => c.type === 'RUN_FINISHED')).toBe(true)
155 // The agent still ran directly (unjournaled): its own command shows up,
156 // but no command anywhere references a journal path for this runId.
157 expect(
158 recorder.spawned.some((command) => command.includes('fake-claude.mjs')),
159 ).toBe(true)
160 const paths = journalPaths(runId)
161 expect(
162 recorder.spawned.some((command) => command.includes(paths.journal)),
163 ).toBe(false)
164
165 await sbx.destroy()
166 })
167
168 it('starts the agent and journals under the caller-supplied runId when NOT attaching', async () => {
169 const sbx = await provider.create({})
170 await sbx.fs.write('/workspace/fake-claude.mjs', FAKE_CLAUDE)
171 const recorder = pollStrategyHandle(sbx)
172 const runId = newRunId('not-attaching')
173
174 const adapter = claudeCodeText('haiku', {
175 claudeExecutable: 'node fake-claude.mjs',
176 streamPartials: false,
177 emitDiff: false,
178 })
179
180 const chunks = await collect(
181 adapter.chatStream({
182 model: 'haiku',
183 messages: [{ role: 'user', content: 'say pong' }],
184 logger: noopLogger,
185 runId,
186 capabilities: capabilityContextWith(
187 recorder.handle,
188 fakeDurability(runId, { attach: false }),
189 ),
190 }),
191 )
192
193 expect(chunks.some((c) => c.type === 'RUN_FINISHED')).toBe(true)
194
195 // The agent was actually started (`startJournaledAgent` spawns it).
196 expect(
197 recorder.spawned.some((command) => command.includes('fake-claude.mjs')),
198 ).toBe(true)
199
200 // ...and its output was journaled under a path derived from THIS runId.
201 const paths = journalPaths(runId)
202 const journaled = recorder.spawned.filter((command) =>
203 command.includes(paths.journal),
204 )
205 expect(journaled.length).toBeGreaterThan(0)
206 expect(journaled.some((command) => command.includes('>>'))).toBe(true)
207
208 await sbx.destroy()
209 })
210
211 it('does NOT start an agent when attaching — it only tails the existing journal', async () => {
212 const sbx = await provider.create({})
213 // No fake-claude.mjs written at all: if the adapter tried to start it,
214 // the run would fail with a "file not found"-shaped RUN_ERROR instead of
215 // producing the expected chunks below.
216 const runId = newRunId('attaching')
217 await seedJournal(sbx, runId, [
218 {
219 type: 'system',
220 subtype: 'init',
221 session_id: 'sess-attach',
222 model: 'haiku',
223 tools: [],
224 },
225 {
226 type: 'assistant',
227 message: { id: 'msg-1', content: [{ type: 'text', text: 'resumed' }] },
228 parent_tool_use_id: null,
229 },
230 {
231 type: 'result',
232 subtype: 'success',
233 result: 'resumed',
234 usage: { input_tokens: 1, output_tokens: 1 },
235 },
236 { __exit: 0 },
237 ])
238 const recorder = pollStrategyHandle(sbx)
239
240 const adapter = claudeCodeText('haiku', {
241 claudeExecutable: 'node fake-claude.mjs',
242 streamPartials: false,
243 emitDiff: false,
244 })
245
246 const chunks = await collect(
247 adapter.chatStream({
248 model: 'haiku',
249 messages: [{ role: 'user', content: 'say pong' }],
250 logger: noopLogger,
251 runId,
252 // A real attach always has the run record's `threadId` — core's
253 // `startRunDriver` hands it to `drive({ runId, threadId, signal })` —
254 // and `resolveDurableThreadId` now REQUIRES it, because an attach that
255 // mints a fresh one stamps every chunk with an id the stored log cannot
256 // match. Omitting it here (as this test originally did) exercised a
257 // configuration that could never align; supplying it keeps the subject
258 // of this test — that no agent is spawned on attach — unchanged.
259 threadId: `t-attaching-${crypto.randomUUID()}`,
260 capabilities: capabilityContextWith(
261 recorder.handle,
262 fakeDurability(runId, { attach: true }),
263 ),
264 }),
265 )
266
267 // Translated from the pre-existing journal, proving the read (not a live
268 // spawn) is what produced this content.
269 const text = chunks
270 .filter((c) => c.type === 'TEXT_MESSAGE_CONTENT')
271 .map((c) => (c as { delta?: string }).delta ?? '')
272 .join('')
273 expect(text).toContain('resumed')
274 expect(chunks.some((c) => c.type === 'RUN_FINISHED')).toBe(true)
275
276 // No command ever referenced the agent executable: the agent was never
277 // started on the attach path.
278 expect(
279 recorder.spawned.some((command) => command.includes('fake-claude.mjs')),
280 ).toBe(false)
281
282 // A read command against this run's journal DID happen.
283 const paths = journalPaths(runId)
284 expect(
285 recorder.spawned.some((command) => command.includes(paths.journal)),
286 ).toBe(true)
287
288 await sbx.destroy()
289 })
290
291 it('suppresses already-delivered chunks on attach via alignedIfAttaching', async () => {
292 // Proves `alignedIfAttaching` is actually IN the pipe, not merely that a
293 // fresh translation of the journal happens to look right. A durability
294 // adapter whose stored log already holds a PREFIX of what this run's
295 // journal translates to must have that prefix suppressed from the
296 // delivered stream — that suppression is `alignedIfAttaching`'s entire
297 // job (`align.ts`), and nothing else in this call site removes chunks.
298 const sbx = await provider.create({})
299 const runId = newRunId('align-proof')
300 const threadId = `t-${runId}`
301 const seedMessages: Array<AgentSdkMessage> = [
302 {
303 type: 'system',
304 subtype: 'init',
305 session_id: 'sess-align',
306 model: 'haiku',
307 tools: [],
308 },
309 {
310 type: 'assistant',
311 message: { id: 'msg-1', content: [{ type: 'text', text: 'resumed' }] },
312 parent_tool_use_id: null,
313 },
314 {
315 type: 'result',
316 subtype: 'success',
317 result: 'resumed',
318 usage: { input_tokens: 1, output_tokens: 1 },
319 },
320 ]
321 await seedJournal(sbx, runId, [...seedMessages, { __exit: 0 }])
322
323 // Independently reproduce what `chatStream`'s own translation will emit:
324 // same messages, same `model`/`runId`/`threadId`, same
325 // `createRunScopedIdGen(runId)` — deterministic, per
326 // `translate-determinism.test.ts`.
327 async function* asMessages(): AsyncIterable<AgentSdkMessage> {
328 for (const m of seedMessages) yield m
329 }
330 const fullTranslation: Array<StreamChunk> = []
331 for await (const chunk of translateSdkStream(asMessages(), {
332 model: 'haiku',
333 runId,
334 threadId,
335 genId: createRunScopedIdGen(runId),
336 })) {
337 fullTranslation.push(chunk)
338 }
339 expect(fullTranslation.length).toBeGreaterThan(1)
340
341 // Mark everything but the LAST chunk as "already delivered" by a
342 // predecessor host: append it straight to the adapter this run's
343 // durability will read back via `snapshot()`.
344 const alreadyDelivered = fullTranslation.slice(0, -1)
345 const notYetDelivered = fullTranslation.slice(-1)
346 const durability = fakeDurability(runId, { attach: true })
347 await durability.adapter.append(alreadyDelivered)
348
349 const recorder = pollStrategyHandle(sbx)
350 const adapter = claudeCodeText('haiku', {
351 claudeExecutable: 'node fake-claude.mjs',
352 streamPartials: false,
353 emitDiff: false,
354 })
355
356 const chunks = await collect(
357 adapter.chatStream({
358 model: 'haiku',
359 messages: [{ role: 'user', content: 'say pong' }],
360 logger: noopLogger,
361 runId,
362 threadId,
363 capabilities: capabilityContextWith(recorder.handle, durability),
364 }),
365 )
366
367 // Every chunk in `alreadyDelivered` is suppressed; only the tail this
368 // durability adapter had NOT yet seen comes through. Compared via
369 // `chunkFingerprint` (key-order independent, excludes the wall-clock
370 // `timestamp`) since the two translations run at different instants.
371 expect(chunks.map(chunkFingerprint)).toEqual(
372 notYetDelivered.map(chunkFingerprint),
373 )
374
375 await sbx.destroy()
376 })
377
378 it('throws DurableRunIdRequiredError (surfaced as a RUN_ERROR) when durability is wired without a runId', async () => {
379 const sbx = await provider.create({})
380 await sbx.fs.write('/workspace/fake-claude.mjs', FAKE_CLAUDE)
381 // `fakeDurability` needs SOME runId to build its `memoryStream` adapter
382 // key, but that id is never passed to `chatStream` — the point of this
383 // test is the ABSENCE of `options.runId`.
384 const durability = fakeDurability(newRunId('unused-adapter-key'))
385
386 const adapter = claudeCodeText('haiku', {
387 claudeExecutable: 'node fake-claude.mjs',
388 streamPartials: false,
389 emitDiff: false,
390 })
391
392 const chunks = await collect(
393 adapter.chatStream({
394 model: 'haiku',
395 messages: [{ role: 'user', content: 'say pong' }],
396 logger: noopLogger,
397 // runId intentionally omitted
398 capabilities: capabilityContextWith(sbx, durability),
399 }),
400 )
401
402 const runError = chunks.find((c) => c.type === 'RUN_ERROR')
403 expect(runError).toBeDefined()
404 expect((runError as { message?: string }).message).toMatch(
405 /caller-supplied `runId`/,
406 )
407
408 await sbx.destroy()
409 })
410
411 it('throws DurableThreadIdRequiredError (surfaced as a RUN_ERROR) when ATTACHING without a threadId', async () => {
412 // The silent-divergence hole this closes: `threadId` lands in every emitted
413 // chunk, so an attach that mints a fresh one replays a stream the stored log
414 // cannot match at index 0. Before this guard the run started, read the
415 // journal, and only then failed alignment mid-stream.
416 const sbx = await provider.create({})
417 const runId = newRunId('attach-no-thread')
418 // No journal seeded and no fake agent written: the refusal must precede
419 // both, so neither is needed for this to fail deterministically.
420 const adapter = claudeCodeText('haiku', {
421 claudeExecutable: 'node fake-claude.mjs',
422 streamPartials: false,
423 emitDiff: false,
424 })
425
426 const chunks = await collect(
427 adapter.chatStream({
428 model: 'haiku',
429 messages: [{ role: 'user', content: 'say pong' }],
430 logger: noopLogger,
431 runId,
432 // threadId intentionally omitted — the whole point of this test.
433 capabilities: capabilityContextWith(
434 sbx,
435 fakeDurability(runId, { attach: true }),
436 ),
437 }),
438 )
439
440 const runError = chunks.find((c) => c.type === 'RUN_ERROR')
441 expect(runError).toBeDefined()
442 expect((runError as { message?: string }).message).toMatch(
443 /ATTACHING durable sandboxed run requires the run record's `threadId`/,
444 )
445
446 await sbx.destroy()
447 })
448
449 it('carries a caller-supplied threadId into the chunks when ATTACHING', async () => {
450 const sbx = await provider.create({})
451 const runId = newRunId('attach-with-thread')
452 const threadId = `t-reused-${crypto.randomUUID()}`
453 await seedJournal(sbx, runId, [
454 {
455 type: 'system',
456 subtype: 'init',
457 session_id: 'sess-attach',
458 model: 'haiku',
459 tools: [],
460 },
461 {
462 type: 'assistant',
463 message: { id: 'msg-1', content: [{ type: 'text', text: 'resumed' }] },
464 parent_tool_use_id: null,
465 },
466 {
467 type: 'result',
468 subtype: 'success',
469 result: 'resumed',
470 usage: { input_tokens: 1, output_tokens: 1 },
471 },
472 { __exit: 0 },
473 ])
474 const recorder = pollStrategyHandle(sbx)
475
476 const adapter = claudeCodeText('haiku', {
477 claudeExecutable: 'node fake-claude.mjs',
478 streamPartials: false,
479 emitDiff: false,
480 })
481 const chunks = await collect(
482 adapter.chatStream({
483 model: 'haiku',
484 messages: [{ role: 'user', content: 'say pong' }],
485 logger: noopLogger,
486 runId,
487 threadId,
488 // Empty stored log, so nothing is suppressed and the chunks that carry
489 // `threadId` are observable.
490 capabilities: capabilityContextWith(
491 recorder.handle,
492 fakeDurability(runId, { attach: true }),
493 ),
494 }),
495 )
496
497 expect(chunks.some((c) => c.type === 'RUN_FINISHED')).toBe(true)
498 // Not merely "it did not throw": the id the caller passed must be the id
499 // stamped on the stream, which is the only thing that makes the replay
500 // alignable against the stored log.
501 expect(threadIdsOf(chunks)).toEqual([threadId])
502
503 await sbx.destroy()
504 })
505
506 it('lets a durable FRESH run generate its own threadId', async () => {
507 // The regression bar for the guard: a fresh durable run is the run that
508 // ESTABLISHES the threadId, so it must still mint one. A guard keyed on
509 // `durable` alone (rather than durable AND attaching) would break this.
510 const sbx = await provider.create({})
511 await sbx.fs.write('/workspace/fake-claude.mjs', FAKE_CLAUDE)
512 const recorder = pollStrategyHandle(sbx)
513 const runId = newRunId('fresh-thread')
514
515 const adapter = claudeCodeText('haiku', {
516 claudeExecutable: 'node fake-claude.mjs',
517 streamPartials: false,
518 emitDiff: false,
519 })
520 const chunks = await collect(
521 adapter.chatStream({
522 model: 'haiku',
523 messages: [{ role: 'user', content: 'say pong' }],
524 logger: noopLogger,
525 runId,
526 // threadId intentionally omitted.
527 capabilities: capabilityContextWith(
528 recorder.handle,
529 fakeDurability(runId, { attach: false }),
530 ),
531 }),
532 )
533
534 expect(chunks.some((c) => c.type === 'RUN_FINISHED')).toBe(true)
535 const threadIds = threadIdsOf(chunks)
536 expect(threadIds).toHaveLength(1)
537 expect(threadIds[0]).toMatch(/.+/)
538
539 await sbx.destroy()
540 })
541
542 it('lets a NON-durable run generate its own threadId, unchanged', async () => {
543 const sbx = await provider.create({})
544 await sbx.fs.write('/workspace/fake-claude.mjs', FAKE_CLAUDE)
545 const recorder = pollStrategyHandle(sbx)
546
547 const adapter = claudeCodeText('haiku', {
548 claudeExecutable: 'node fake-claude.mjs',
549 streamPartials: false,
550 emitDiff: false,
551 })
552 const chunks = await collect(
553 adapter.chatStream({
554 model: 'haiku',
555 messages: [{ role: 'user', content: 'say pong' }],
556 logger: noopLogger,
557 // Neither runId nor threadId, and no durability capability: exactly a
558 // pre-durability run.
559 capabilities: capabilityContextWith(recorder.handle),
560 }),
561 )
562
563 expect(chunks.some((c) => c.type === 'RUN_FINISHED')).toBe(true)
564 const threadIds = threadIdsOf(chunks)
565 expect(threadIds).toHaveLength(1)
566 expect(threadIds[0]).toMatch(/.+/)
567
568 await sbx.destroy()
569 })
570})