@defrex/autobuild 0.8.0

package/packages/core/src/ports/runner/contract.ts

@@ -0,0 +1,492 @@
+import { describe, expect, test } from 'bun:test'
+import { chmod, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { delimiter, join } from 'node:path'
+import type { StreamPart } from '../../store/streams/types'
+import type { AgentRunner, AgentSessionHandle, AgentTurnResult, Transcript } from '../types'
+import type { OneShotCompletion, OneShotCompletionInput } from './one-shot'
+import { AGENT_BIN_DIR } from './session-env'
+
+export type AgentRunnerContractScenario =
+  | 'success'
+  | 'retryable-failure'
+  | 'permanent-failure'
+  | 'exhaustion-failure'
+  | 'cancel-start'
+  | 'cancel-continue'
+  | 'stream-turn'
+
+export const CONTRACT_INVOCATION = 'agent-runner-contract'
+export const CONTRACT_SKILL = 'ab-runner-contract'
+export const CONTRACT_FOLLOW_UP = 'contract follow-up turn'
+export const CONTRACT_RETRYABLE_FAILURE = 'contract worker exited unexpectedly'
+export const CONTRACT_PERMANENT_FAILURE = 'contract authentication failed'
+export const CONTRACT_EXHAUSTION_FAILURE = 'contract usage quota exhausted'
+export const CONTRACT_ONE_SHOT_PROMPT = 'contract one-shot prompt'
+export const CONTRACT_ONE_SHOT_TEXT = 'contract-one-shot-result'
+export const CONTRACT_STREAM_TOOL = 'contract-tool'
+
+/** An observation made below the adapter boundary. Contract fixtures normalize
+ * their SDK-specific calls to this shape so the suite can verify delivery and
+ * effective process environment without reaching into an adapter. */
+export interface AgentRunnerContractTurnObservation {
+  /** Undefined for start; the exact follow-up string for continue. */
+  message?: string
+  env: Record<string, string>
+}
+
+export interface AgentRunnerContractOneShotObservation {
+  prompt: string
+  cwd: string
+  env: Record<string, string>
+  model?: string
+}
+
+export interface AgentRunnerContractOneShotHarness {
+  completion: OneShotCompletion
+  observation: () => AgentRunnerContractOneShotObservation | undefined
+}
+
+export interface AgentRunnerContractHarness {
+  runner: AgentRunner
+  /** A valid, explicit model identifier for this adapter. */
+  model: string
+  workspacePath: string
+  /** Independent observations from the script/SDK seam, in turn order. */
+  turns: () => readonly AgentRunnerContractTurnObservation[]
+  /** Adapter-specific disposal observation, when the transport exposes one. */
+  disposed?: () => number
+  /** Present only when the runtime declares the optional capability. */
+  oneShot?: AgentRunnerContractOneShotHarness
+  /** Stream-part observation (SPEC §9): every part the adapter appended via
+   * the per-turn emitter, across turns, in order. Present only when the
+   * offline fake supports streaming. */
+  stream?: () => readonly StreamPart[]
+  cleanup?: () => Promise<void>
+}
+
+export type AgentRunnerContractFactory = (
+  scenario: AgentRunnerContractScenario,
+) => Promise<AgentRunnerContractHarness> | AgentRunnerContractHarness
+
+async function withHarness(
+  factory: AgentRunnerContractFactory,
+  scenario: AgentRunnerContractScenario,
+  run: (harness: AgentRunnerContractHarness) => Promise<void>,
+): Promise<void> {
+  const harness = await factory(scenario)
+  let failure: unknown
+  try {
+    await run(harness)
+  } catch (error) {
+    failure = error
+  }
+
+  try {
+    await harness.cleanup?.()
+  } catch (cleanupError) {
+    if (failure !== undefined) {
+      throw new AggregateError(
+        [failure, cleanupError],
+        'AgentRunner contract assertion and cleanup both failed',
+      )
+    }
+    throw cleanupError
+  }
+  if (failure !== undefined) throw failure
+}
+
+/** Run assertions while guaranteeing that every successfully launched handle
+ * is ended. Assertion and end failures are both retained. */
+async function withEndedSession<T>(
+  runner: AgentRunner,
+  session: AgentSessionHandle,
+  run: () => Promise<T>,
+): Promise<{ value: T; transcript: Transcript }> {
+  let value: T | undefined
+  let failure: unknown
+  try {
+    value = await run()
+  } catch (error) {
+    failure = error
+  }
+
+  let transcript: Transcript | undefined
+  try {
+    transcript = await runner.end(session)
+  } catch (endError) {
+    if (failure !== undefined) {
+      throw new AggregateError(
+        [failure, endError],
+        'AgentRunner contract assertion and session end both failed',
+      )
+    }
+    throw endError
+  }
+  if (failure !== undefined) throw failure
+  return { value: value as T, transcript }
+}
+
+function expectUsage(usage: { inputTokens: number; outputTokens: number; turns: number }): void {
+  for (const value of [usage.inputTokens, usage.outputTokens, usage.turns]) {
+    expect(Number.isFinite(value)).toBe(true)
+    expect(Number.isInteger(value)).toBe(true)
+    expect(value).toBeGreaterThanOrEqual(0)
+  }
+  expect(usage.turns).toBeGreaterThan(0)
+}
+
+function expectTypedCompleted(result: AgentTurnResult): void {
+  expect(result.kind).toBe('completed')
+  expect(typeof result.text).toBe('string')
+  expectUsage(result.usage)
+}
+
+function expectTranscript(transcript: Transcript, runner: AgentRunner, model: string): void {
+  expect(transcript.content.trim().length).toBeGreaterThan(0)
+  expect(transcript.metadata.runner).toBe(runner.name)
+  expect(transcript.metadata.model).toBe(model)
+  expectUsage(transcript.metadata.usage)
+}
+
+async function waitForTurn(harness: AgentRunnerContractHarness, count: number): Promise<void> {
+  const deadline = Date.now() + 1000
+  while (harness.turns().length < count) {
+    if (Date.now() >= deadline)
+      throw new Error(`runner did not start turn ${count} within one second`)
+    await Bun.sleep(1)
+  }
+}
+
+async function invokeManagedCli(env: Record<string, string>): Promise<void> {
+  const path = env.PATH
+  expect(path).toBeDefined()
+  expect(path!.split(delimiter)[0]).toBe(AGENT_BIN_DIR)
+
+  const proc = Bun.spawn(['ab', '--help'], {
+    cwd: process.cwd(),
+    env,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ])
+  expect(exitCode).toBe(0)
+  expect(stderr).toBe('')
+  expect(stdout).toContain('ab — agent-driven software delivery')
+  expect(stdout).not.toContain('host-conflicting-ab')
+}
+
+/**
+ * Reusable AgentRunner semantics. Runtime transport, stream extraction,
+ * resumption mechanics, and disposal tests remain beside each adapter; this is
+ * the behavioral floor a future runtime plugin can run unchanged.
+ */
+export function describeAgentRunnerContract(
+  name: string,
+  factory: AgentRunnerContractFactory,
+): void {
+  describe(`AgentRunner contract: ${name}`, () => {
+    test('start/continue are typed, refresh ambient auth, resolve managed ab, and end with a complete transcript', async () => {
+      await withHarness(factory, 'success', async (harness) => {
+        const conflictDir = await mkdtemp(join(tmpdir(), 'ab-runner-contract-path-'))
+        try {
+          const conflictingAb = join(conflictDir, 'ab')
+          await writeFile(conflictingAb, '#!/bin/sh\necho host-conflicting-ab\nexit 91\n')
+          await chmod(conflictingAb, 0o755)
+
+          const startEnv = {
+            PATH: [conflictDir, process.env.PATH ?? '']
+              .filter((entry) => entry !== '')
+              .join(delimiter),
+            AB_CONTRACT_START_ONLY: 'retained',
+            AB_CONTRACT_COLLIDE: 'start-value',
+            AB_PHASE: 'implement@1',
+          }
+          const started = await harness.runner.start({
+            skill: CONTRACT_SKILL,
+            invocation: CONTRACT_INVOCATION,
+            workspacePath: harness.workspacePath,
+            model: harness.model,
+            env: startEnv,
+          })
+
+          const { transcript } = await withEndedSession(
+            harness.runner,
+            started.session,
+            async () => {
+              expect(started.session.id.trim().length).toBeGreaterThan(0)
+              expect(started.session.runner).toBe(harness.runner.name)
+              expect(started.session.model).toBe(harness.model)
+              expectTypedCompleted(started.result)
+
+              const continued = await harness.runner.continue(started.session, CONTRACT_FOLLOW_UP, {
+                env: {
+                  AB_CONTRACT_COLLIDE: 'continue-value',
+                  AB_CONTRACT_CONTINUE_ONLY: 'fresh',
+                  AB_PHASE: 'implement@2',
+                },
+              })
+              expectTypedCompleted(continued)
+
+              const turns = harness.turns()
+              expect(turns).toHaveLength(2)
+              expect(turns[0]?.message).toBeUndefined()
+              expect(turns[1]?.message).toBe(CONTRACT_FOLLOW_UP)
+              expect(turns[0]?.env.AB_CONTRACT_COLLIDE).toBe('start-value')
+              expect(turns[0]?.env.AB_CONTRACT_START_ONLY).toBe('retained')
+              expect(turns[1]?.env.AB_CONTRACT_COLLIDE).toBe('continue-value')
+              expect(turns[1]?.env.AB_CONTRACT_START_ONLY).toBe('retained')
+              expect(turns[1]?.env.AB_CONTRACT_CONTINUE_ONLY).toBe('fresh')
+              expect(turns[1]?.env.AB_PHASE).toBe('implement@2')
+              await invokeManagedCli(turns[0]!.env)
+              await invokeManagedCli(turns[1]!.env)
+            },
+          )
+          expectTranscript(transcript, harness.runner, harness.model)
+        } finally {
+          await rm(conflictDir, { recursive: true, force: true })
+        }
+      })
+    })
+
+    test('an aborted start terminates promptly and retains an endable transcript', async () => {
+      await withHarness(factory, 'cancel-start', async (harness) => {
+        const controller = new AbortController()
+        const pending = harness.runner.start({
+          skill: CONTRACT_SKILL,
+          invocation: CONTRACT_INVOCATION,
+          workspacePath: harness.workspacePath,
+          model: harness.model,
+          env: { AB_PHASE: 'implement@1' },
+          signal: controller.signal,
+        })
+        await waitForTurn(harness, 1)
+        controller.abort(new Error('contract operator cancellation'))
+        const started = await Promise.race([
+          pending,
+          Bun.sleep(1000).then(() => {
+            throw new Error('cancelled start did not settle within one second')
+          }),
+        ])
+        const { transcript } = await withEndedSession(harness.runner, started.session, async () => {
+          expect(started.result).toMatchObject({
+            kind: 'failed',
+            failure: { permanent: false },
+          })
+        })
+        expectTranscript(transcript, harness.runner, harness.model)
+        if (harness.disposed !== undefined) expect(harness.disposed()).toBe(1)
+        await expect(harness.runner.end(started.session)).rejects.toThrow()
+      })
+    })
+
+    test('an aborted continued turn terminates promptly and the whole session remains disposable', async () => {
+      await withHarness(factory, 'cancel-continue', async (harness) => {
+        const started = await harness.runner.start({
+          skill: CONTRACT_SKILL,
+          invocation: CONTRACT_INVOCATION,
+          workspacePath: harness.workspacePath,
+          model: harness.model,
+          env: { AB_PHASE: 'implement@1' },
+        })
+        expectTypedCompleted(started.result)
+        const controller = new AbortController()
+        const pending = harness.runner.continue(started.session, CONTRACT_FOLLOW_UP, {
+          env: { AB_PHASE: 'implement@2' },
+          signal: controller.signal,
+        })
+        await waitForTurn(harness, 2)
+        controller.abort(new Error('contract operator cancellation'))
+        const { transcript } = await withEndedSession(harness.runner, started.session, async () => {
+          const result = await Promise.race([
+            pending,
+            Bun.sleep(1000).then(() => {
+              throw new Error('cancelled continuation did not settle within one second')
+            }),
+          ])
+          expect(result).toMatchObject({ kind: 'failed', failure: { permanent: false } })
+        })
+        expectTranscript(transcript, harness.runner, harness.model)
+        if (harness.disposed !== undefined) expect(harness.disposed()).toBe(1)
+      })
+    })
+
+    test('an unclassified provider failure stays retryable and keeps an endable handle', async () => {
+      await withHarness(factory, 'retryable-failure', async (harness) => {
+        const started = await harness.runner.start({
+          skill: CONTRACT_SKILL,
+          invocation: CONTRACT_INVOCATION,
+          workspacePath: harness.workspacePath,
+          model: harness.model,
+          env: { AB_PHASE: 'implement@1' },
+        })
+        const { transcript } = await withEndedSession(harness.runner, started.session, async () => {
+          expect(started.result).toMatchObject({
+            kind: 'failed',
+            failure: {
+              message: CONTRACT_RETRYABLE_FAILURE,
+              permanent: false,
+            },
+          })
+          expectUsage(started.result.usage)
+        })
+        expectTranscript(transcript, harness.runner, harness.model)
+      })
+    })
+
+    test('positive authentication/permission evidence is a permanent credential failure', async () => {
+      await withHarness(factory, 'permanent-failure', async (harness) => {
+        const started = await harness.runner.start({
+          skill: CONTRACT_SKILL,
+          invocation: CONTRACT_INVOCATION,
+          workspacePath: harness.workspacePath,
+          model: harness.model,
+          env: { AB_PHASE: 'implement@1' },
+        })
+        const { transcript } = await withEndedSession(harness.runner, started.session, async () => {
+          expect(started.result).toMatchObject({
+            kind: 'failed',
+            failure: {
+              message: CONTRACT_PERMANENT_FAILURE,
+              permanent: true,
+              cause: 'credentials',
+            },
+          })
+          expectUsage(started.result.usage)
+        })
+        expectTranscript(transcript, harness.runner, harness.model)
+      })
+    })
+
+    test('quota evidence is permanent for retry policy but identified as provider exhaustion', async () => {
+      await withHarness(factory, 'exhaustion-failure', async (harness) => {
+        const started = await harness.runner.start({
+          skill: CONTRACT_SKILL,
+          invocation: CONTRACT_INVOCATION,
+          workspacePath: harness.workspacePath,
+          model: harness.model,
+          env: { AB_PHASE: 'implement@1' },
+        })
+        const { transcript } = await withEndedSession(harness.runner, started.session, async () => {
+          expect(started.result).toMatchObject({
+            kind: 'failed',
+            failure: {
+              message: CONTRACT_EXHAUSTION_FAILURE,
+              permanent: true,
+              cause: 'exhaustion',
+            },
+          })
+          expectUsage(started.result.usage)
+        })
+        expectTranscript(transcript, harness.runner, harness.model)
+      })
+    })
+
+    test('declared one-shot completion forwards its exact input and returns typed text', async () => {
+      await withHarness(factory, 'success', async (harness) => {
+        if (harness.oneShot === undefined) return
+        const input: OneShotCompletionInput = {
+          prompt: CONTRACT_ONE_SHOT_PROMPT,
+          cwd: harness.workspacePath,
+          env: { AB_CONTRACT_ONE_SHOT: 'scoped-value' },
+          model: harness.model,
+        }
+        const result = await harness.oneShot.completion.complete(input)
+        expect(result).toEqual({ text: CONTRACT_ONE_SHOT_TEXT })
+        const observed = harness.oneShot.observation()
+        expect(observed).toBeDefined()
+        expect(observed?.prompt).toBe(input.prompt)
+        expect(observed?.cwd).toBe(input.cwd)
+        expect(observed?.env.AB_CONTRACT_ONE_SHOT).toBe('scoped-value')
+        expect(observed?.model).toBe(input.model)
+      })
+    })
+
+    // ── Session streams (SPEC §9) ── exercised only when the offline fake
+    // supports the streaming boundary; a runner without it skips cleanly.
+
+    test('a representative turn streams prompt, text, one tool call with input and output, and finish-step', async () => {
+      await withHarness(factory, 'stream-turn', async (harness) => {
+        if (harness.stream === undefined) return
+        const parts: StreamPart[] = []
+        const started = await harness.runner.start({
+          skill: CONTRACT_SKILL,
+          invocation: CONTRACT_INVOCATION,
+          workspacePath: harness.workspacePath,
+          model: harness.model,
+          env: { AB_PHASE: 'implement@1' },
+          stream: { append: (appended: StreamPart[]) => parts.push(...appended) },
+        })
+        expectTypedCompleted(started.result)
+        const types = parts.map((part) => part.type)
+        // The turn's two sides are visible: its prompt precedes the output.
+        expect(types[0]).toBe('data-ab-prompt')
+        expect(types).toContain('start')
+        // At minimum: a completed assistant message, one tool call with its
+        // input and output, and the step bracket around them.
+        expect(types).toContain('start-step')
+        expect(types).toContain('finish-step')
+        expect(types).toContain('text-start')
+        expect(types).toContain('text-delta')
+        expect(types).toContain('text-end')
+        const toolInput = parts.find((part) => part.type === 'tool-input-available') as unknown as
+          | { toolName: string }
+          | undefined
+        expect(toolInput?.toolName).toBeDefined()
+        expect(parts.some((part) => part.type === 'tool-output-available')).toBe(true)
+        expect(parts.at(-1)?.type).toBe('finish')
+        // The prompt part carries this turn's skill invocation.
+        const prompt = parts.find((part) => part.type === 'data-ab-prompt') as unknown as
+          | { data: { text: string } }
+          | undefined
+        expect(prompt?.data.text).toContain(CONTRACT_SKILL)
+      })
+    })
+
+    test('a failed turn emits an error part before the stream closes', async () => {
+      await withHarness(factory, 'retryable-failure', async (harness) => {
+        if (harness.stream === undefined) return
+        const parts: StreamPart[] = []
+        await harness.runner.start({
+          skill: CONTRACT_SKILL,
+          invocation: CONTRACT_INVOCATION,
+          workspacePath: harness.workspacePath,
+          model: harness.model,
+          env: { AB_PHASE: 'implement@1' },
+          stream: { append: (appended: StreamPart[]) => parts.push(...appended) },
+        })
+        expect(parts.at(-1)?.type).toBe('error')
+      })
+    })
+
+    test('a cancelled turn emits an abort part', async () => {
+      await withHarness(factory, 'cancel-start', async (harness) => {
+        if (harness.stream === undefined) return
+        const parts: StreamPart[] = []
+        const controller = new AbortController()
+        const pending = harness.runner.start({
+          skill: CONTRACT_SKILL,
+          invocation: CONTRACT_INVOCATION,
+          workspacePath: harness.workspacePath,
+          model: harness.model,
+          env: { AB_PHASE: 'implement@1' },
+          signal: controller.signal,
+          stream: { append: (appended: StreamPart[]) => parts.push(...appended) },
+        })
+        await waitForTurn(harness, 1)
+        controller.abort(new Error('contract operator cancellation'))
+        await Promise.race([
+          pending,
+          Bun.sleep(1000).then(() => {
+            throw new Error('cancelled streaming turn did not settle within one second')
+          }),
+        ])
+        expect(parts.at(-1)?.type).toBe('abort')
+      })
+    })
+  })
+}

package/packages/core/src/ports/runner/fake.ts

@@ -0,0 +1,213 @@
+/**
+ * ScriptedAgentRunner (SPEC §9): the deterministic AgentRunner used by every
+ * kernel/process/integration test. A single script function plays the agent;
+ * the runner records every turn into public journals so tests can assert the
+ * exact session traffic — and `end()` produces a Transcript like any real
+ * adapter, because transcripts come back through the interface, guaranteed.
+ */
+import {
+  agentInvocation,
+  type AgentContinueOpts,
+  type AgentFailureCause,
+  type AgentRunner,
+  type AgentSessionHandle,
+  type AgentStartOpts,
+  type AgentTurnResult,
+  type Transcript,
+} from '../types'
+import { sessionEnv } from './session-env'
+
+/** What the script sees on each invocation — one call per turn. */
+export interface ScriptContext {
+  /** This TURN's opts: on `continue`, the refreshed ambient env (§10, D8)
+   * merged over the start env — exactly what a real adapter launches with. */
+  opts: AgentStartOpts
+  session: AgentSessionHandle
+  /** 1 on `start`, incremented on each `continue`. */
+  turn: number
+  /** The `continue` message; undefined on turn 1 (start has no message). */
+  message?: string
+  /** All prior `continue` messages, oldest first (excludes this turn's). */
+  history: string[]
+}
+
+export type Script = (ctx: ScriptContext) => Promise<AgentTurnResult> | AgentTurnResult
+
+/** Default completed turn (text '', usage 1/1/1) — keeps scripts terse. */
+export function defaultTurnResult(text = ''): AgentTurnResult {
+  return {
+    kind: 'completed',
+    text,
+    usage: { inputTokens: 1, outputTokens: 1, turns: 1 },
+  }
+}
+
+/** Script a provider/runner-declared failure while preserving the same endable
+ * fake session and transcript behavior as a real adapter. */
+export function failedTurnResult(
+  message: string,
+  permanent: boolean,
+  text = '',
+  cause?: AgentFailureCause,
+): AgentTurnResult {
+  return {
+    kind: 'failed',
+    text,
+    usage: { inputTokens: 0, outputTokens: 0, turns: 1 },
+    failure: { message, permanent, ...(cause !== undefined ? { cause } : {}) },
+  }
+}
+
+export interface RecordedTurn {
+  turn: number
+  /** Undefined on turn 1 — the start prompt is derived from `opts`. */
+  message?: string
+  result: AgentTurnResult
+}
+
+/** Per-session journal, public for assertions. */
+export interface SessionJournal {
+  session: AgentSessionHandle
+  opts: AgentStartOpts
+  turns: RecordedTurn[]
+  /** Messages passed to `continue`, in order. */
+  messages: string[]
+  ended: boolean
+}
+
+export class ScriptedAgentRunner implements AgentRunner {
+  readonly name = 'scripted'
+  /** Journals keyed by session id (`s_1`, `s_2`, …), in creation order. */
+  readonly sessions = new Map<string, SessionJournal>()
+
+  private readonly script: Script
+  private nextSession = 0
+
+  constructor(opts: { script: Script }) {
+    this.script = opts.script
+  }
+
+  async start(
+    opts: AgentStartOpts,
+  ): Promise<{ session: AgentSessionHandle; result: AgentTurnResult }> {
+    this.nextSession += 1
+    const session: AgentSessionHandle = {
+      id: `s_${this.nextSession}`,
+      runner: this.name,
+      ...(opts.model !== undefined ? { model: opts.model } : {}),
+    }
+    const journal: SessionJournal = {
+      session,
+      opts,
+      turns: [],
+      messages: [],
+      ended: false,
+    }
+    this.sessions.set(session.id, journal)
+
+    const result = await this.runScript(
+      {
+        // Scripts observe the same effective launch environment as production
+        // adapters; the journal below intentionally retains the caller's raw
+        // start options as the session identity.
+        opts: { ...opts, env: sessionEnv(opts.env) },
+        session,
+        turn: 1,
+        history: [],
+      },
+      opts.signal,
+    )
+    journal.turns.push({ turn: 1, result })
+    return { session, result }
+  }
+
+  async continue(
+    session: AgentSessionHandle,
+    message: string,
+    opts?: AgentContinueOpts,
+  ): Promise<AgentTurnResult> {
+    const journal = this.liveJournal(session, 'continue')
+    const history = [...journal.messages]
+    const turn = journal.turns.length + 1
+    // Mirror the real adapters (§10, D8): the continued turn runs under the
+    // refreshed ambient env merged over the start env, so the script's fake
+    // CLI resolves exactly what a real agent's `ab` would. The journal keeps
+    // the START opts — they are the session's identity. §9: the turn streams
+    // through THIS turn's emitter only — the start turn's emitter (if any)
+    // belongs to its own bracket and never receives this turn's parts.
+    const scoped = opts?.env !== undefined ? { ...journal.opts.env, ...opts.env } : journal.opts.env
+    const turnOpts = {
+      ...journal.opts,
+      env: sessionEnv(scoped),
+      stream: opts?.stream,
+      ...(opts?.signal !== undefined ? { signal: opts.signal } : {}),
+    }
+
+    const result = await this.runScript(
+      {
+        opts: turnOpts,
+        session: journal.session,
+        turn,
+        message,
+        history,
+      },
+      opts?.signal,
+    )
+    journal.messages.push(message)
+    journal.turns.push({ turn, message, result })
+    return result
+  }
+
+  async end(session: AgentSessionHandle): Promise<Transcript> {
+    const journal = this.liveJournal(session, 'end')
+    journal.ended = true
+
+    const usage = { inputTokens: 0, outputTokens: 0, turns: 0 }
+    for (const { result } of journal.turns) {
+      usage.inputTokens += result.usage.inputTokens
+      usage.outputTokens += result.usage.outputTokens
+      usage.turns += result.usage.turns
+    }
+
+    return {
+      content: JSON.stringify(
+        {
+          session: journal.session.id,
+          skill: journal.opts.skill,
+          invocation: agentInvocation(journal.opts),
+          ...(journal.opts.buildSlug !== undefined ? { buildSlug: journal.opts.buildSlug } : {}),
+          turns: journal.turns,
+        },
+        null,
+        2,
+      ),
+      metadata: {
+        runner: this.name,
+        ...(journal.session.model !== undefined ? { model: journal.session.model } : {}),
+        usage,
+      },
+    }
+  }
+
+  private async runScript(ctx: ScriptContext, signal?: AbortSignal): Promise<AgentTurnResult> {
+    const running = Promise.resolve(this.script(ctx))
+    if (signal === undefined) return running
+    if (signal.aborted) return failedTurnResult('scripted runner: turn aborted', false)
+    return new Promise<AgentTurnResult>((resolve, reject) => {
+      const aborted = (): void => resolve(failedTurnResult('scripted runner: turn aborted', false))
+      signal.addEventListener('abort', aborted, { once: true })
+      running.then(resolve, reject).finally(() => signal.removeEventListener('abort', aborted))
+    })
+  }
+
+  private liveJournal(session: AgentSessionHandle, op: 'continue' | 'end'): SessionJournal {
+    const journal = this.sessions.get(session.id)
+    if (!journal) {
+      throw new Error(`${this.name}: ${op} on unknown session "${session.id}"`)
+    }
+    if (journal.ended) {
+      throw new Error(`${this.name}: ${op} on ended session "${session.id}"`)
+    }
+    return journal
+  }
+}