@frontera-sdk/cli 1.52.38 → 1.52.40

package/src/mcp/mcp-apps.ts

@@ -0,0 +1,435 @@
+import { spawn, spawnSync } from 'node:child_process'
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join, relative } from 'node:path'
+
+import { isLoopbackPortFree } from '../dev-broker'
+import { findSolutionRoot, localProject, type LocalProject } from '../local/local-project'
+import { isAlive } from '../local/local-state'
+import { readProject } from '../project'
+import { ensureAppPackages } from '../project-bootstrap'
+import { detectAppFramework } from '../provenance'
+import { selfCommand } from './mcp-cli'
+import type { RuntimeLink } from './mcp-runtime'
+
+/**
+ * Custom Apps a coding agent works on from a solution: each is its own
+ * project (`package.json` with `frontera.config.json`), found at the solution
+ * root, in `apps/<slug>/` or one folder down. Their dev servers run against
+ * the local runtime and are kept per App in `.frontera/local/app-dev/`, so
+ * every MCP call (and Forge) reuses the one already running.
+ */
+
+export interface AppProjectRef {
+  slug: string
+  name: string
+  /** Absolute. */
+  root: string
+  /** From the solution root, for messages. */
+  path: string
+  framework: 'next' | 'vite' | 'unknown'
+}
+
+function isAppRoot(dir: string): boolean {
+  if (!existsSync(join(dir, 'package.json'))) return false
+  if (existsSync(join(dir, 'frontera.config.json'))) return true
+  try {
+    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { frontera?: unknown }
+    return typeof pkg.frontera === 'object' && pkg.frontera !== null
+  } catch {
+    return false
+  }
+}
+
+const SKIP = new Set(['node_modules', '.git', '.frontera', 'dist', 'out', '.next', 'build'])
+
+function children(dir: string): string[] {
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && !SKIP.has(d.name) && !d.name.startsWith('.'))
+      .map((d) => join(dir, d.name))
+  } catch {
+    return []
+  }
+}
+
+export function findAppProjects(solutionRoot: string): AppProjectRef[] {
+  const candidates = [solutionRoot, ...children(join(solutionRoot, 'apps')), ...children(solutionRoot)]
+  const seen = new Set<string>()
+  const out: AppProjectRef[] = []
+  for (const dir of candidates) {
+    if (seen.has(dir) || !isAppRoot(dir)) continue
+    seen.add(dir)
+    try {
+      const project = readProject(dir)
+      out.push({ slug: project.slug, name: project.displayName, root: dir, path: relative(solutionRoot, dir) || '.', framework: detectAppFramework(dir) })
+    } catch {
+      // A broken package.json is not an App the agent can run.
+    }
+  }
+  return out.sort((a, b) => a.slug.localeCompare(b.slug))
+}
+
+/** The App a tool means: by slug, or the only one there is. */
+export function resolveAppProject(solutionRoot: string, slug: string | undefined): AppProjectRef {
+  const apps = findAppProjects(solutionRoot)
+  if (!apps.length) throw new Error('No Custom App in this project. Create one with `frontera app init <name>` in apps/, then try again.')
+  if (slug) {
+    const app = apps.find((a) => a.slug === slug || basename(a.root) === slug)
+    if (!app) throw new Error(`No App "${slug}" here; there is ${apps.map((a) => a.slug).join(', ')}.`)
+    return app
+  }
+  if (apps.length > 1) throw new Error(`This project has ${apps.length} Apps (${apps.map((a) => a.slug).join(', ')}): say which with app.`)
+  return apps[0]!
+}
+
+export interface DevServer {
+  slug: string
+  pid: number
+  port: number
+  /** What to open: the App's origin, or the Vite dev host page. */
+  url: string
+  startedAt: string
+  log: string
+  /**
+   * The process that started it: an MCP session (`app_dev`, `app_render`) or
+   * Forge (its Start). The server stops when that process ends (`frontera app
+   * dev` watches it), so a server an agent or Forge started never outlives it.
+   * Absent: started by hand.
+   */
+  owner?: { kind: 'mcp' | 'forge'; pid: number }
+}
+
+/** How a dev server this process started ended: its exit code (or signal) and the last lines it wrote. */
+export interface DevServerExit {
+  code: number | null
+  signal: string | null
+  at: string
+  /** The last lines of this run's output, from its log. */
+  tail: string
+}
+
+export interface EnsureDevServerOptions {
+  /**
+   * The `frontera` command to run `app dev` with. Default: this same CLI
+   * (`selfCommand`), right for `frontera mcp`; a host that only imports this
+   * module (Forge) passes its own, or it would start a copy of itself.
+   */
+  command?: string[]
+  /** Who owns the server's lifetime (this process either way). Default: an MCP session. */
+  owner?: 'mcp' | 'forge'
+  /** Called once when the server this call started ends, however it ends. */
+  onExit?: (exit: DevServerExit) => void
+}
+
+/** What tells `frontera app dev` which process started it, so it stops when that one ends. */
+export const DEV_OWNER_ENV = 'FRONTERA_APP_DEV_OWNER_PID'
+
+/** The dev servers this process started, by project and App, so they stop with the MCP session or Forge (`stopStartedDevServers`). */
+const startedHere = new Map<string, { project: LocalProject; slug: string; pid: number }>()
+
+const devDir = (project: LocalProject) => join(project.stateDir, 'app-dev')
+const devFile = (project: LocalProject, slug: string) => join(devDir(project), `${slug.replace(/[^a-z0-9-]+/gi, '-')}.json`)
+
+export function readDevServer(project: LocalProject, slug: string): DevServer | null {
+  try {
+    const server = JSON.parse(readFileSync(devFile(project, slug), 'utf8')) as DevServer
+    return isAlive(server.pid) ? server : null
+  } catch {
+    return null
+  }
+}
+
+export function listDevServers(project: LocalProject): DevServer[] {
+  try {
+    return readdirSync(devDir(project))
+      .filter((f) => f.endsWith('.json'))
+      .map((f) => readDevServer(project, f.replace(/\.json$/, '')))
+      .filter((s): s is DevServer => s !== null)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * The solution an App folder sits in, when it sits in one: the nearest folder
+ * above it marked as a Frontera project. Null for an App on its own.
+ */
+export function enclosingSolution(appRoot: string): LocalProject | null {
+  const root = findSolutionRoot(dirname(appRoot))
+  if (root === appRoot || !['frontera.yaml', 'frontera.solution.yaml'].some((f) => existsSync(join(root, f)))) return null
+  return localProject(root)
+}
+
+/**
+ * Record a dev server another command started (`frontera app dev` run by hand
+ * or by another session), so `app_dev`, `app_render` and Forge reuse it rather
+ * than start a second one, which Next.js refuses in the same folder.
+ */
+export function registerDevServer(project: LocalProject, server: DevServer): void {
+  mkdirSync(devDir(project), { recursive: true })
+  writeFileSync(devFile(project, server.slug), `${JSON.stringify(server, null, 2)}\n`)
+}
+
+/** Forget a dev server this process recorded, unless another has since taken its place. */
+export function forgetDevServer(project: LocalProject, slug: string, pid: number): void {
+  try {
+    const server = JSON.parse(readFileSync(devFile(project, slug), 'utf8')) as DevServer
+    if (server.pid === pid) rmSync(devFile(project, slug), { force: true })
+  } catch {
+    // Nothing recorded, or already gone.
+  }
+}
+
+async function answers(url: string): Promise<boolean> {
+  try {
+    const res = await fetch(url, { redirect: 'manual', signal: AbortSignal.timeout(2_000) })
+    return res.status < 500
+  } catch {
+    return false
+  }
+}
+
+async function freePort(from = 3100): Promise<number> {
+  // Free on both loopbacks: the dev server binds 127.0.0.1, but a browser opening localhost may reach ::1 first.
+  for (let port = from; port < from + 100; port++) if (await isLoopbackPortFree(port)) return port
+  throw new Error('no free port for the App dev server between 3100 and 3199')
+}
+
+/** The env that points an App command at the local runtime instead of the person's profile. */
+export function localAppEnv(link: RuntimeLink): Record<string, string> {
+  const key = link.creds.workspaceKey
+  if (!key) throw new Error('The local runtime has no workspace key yet. Restart it with `frontera local start`.')
+  return { FRONTERA_TOKEN: key, FRONTERA_API_URL: link.serviceUrl, FRONTERA_ORG_ID: link.creds.organizationId }
+}
+
+const READY_MS = 60_000
+
+/**
+ * The App's dev server against the local runtime: the one already running,
+ * or a new `frontera app dev` started in the background, its output in
+ * `.frontera/local/logs/app-<slug>.log`.
+ */
+export async function ensureDevServer(project: LocalProject, app: AppProjectRef, link: RuntimeLink, options: EnsureDevServerOptions = {}): Promise<{ server: DevServer; reused: boolean; installed?: string; trackedFiles?: string[] }> {
+  const running = readDevServer(project, app.slug)
+  if (running && (await answers(running.url))) return { server: running, reused: true }
+  if (app.framework === 'unknown') throw new Error(`${app.slug} has neither Next.js nor Vite in package.json, so it has no dev server to start.`)
+  // A pulled App comes without node_modules: its packages are installed first (bun install), or `next` isn't there to start.
+  // From its bun.lock as it is when it has one: a pulled App's lockfile is never rewritten here. One whose
+  // package.json names its own SDK copy where bun.lock locked a release installs from the copy, writing neither.
+  const install = await ensureAppPackages(app.root)
+  if (install?.lockMismatch) throw new Error(`${app.slug} has no node_modules, and they weren't installed: ${install.summary}.`)
+  if (install && !install.installed) throw new Error(`${app.slug} has no node_modules, and ${install.fromCopy ? '' : `\`bun install\` in ${relative(project.root, app.root) || '.'} failed: `}${install.summary}. Fix that, then try again.`)
+  const frozen = existsSync(join(app.root, 'bun.lock')) || existsSync(join(app.root, 'bun.lockb'))
+  // From its own SDK copy (package.json and bun.lock disagree because of it): said with what kept both files as pulled.
+  const where = relative(project.root, app.root) || app.slug
+  const installed = install ? (install.fromCopy || install.fromLock ? `${where} had no node_modules: ${install.summary}` : `${where} had no node_modules: ran bun install first${frozen ? ' from its bun.lock as it is (--frozen-lockfile; the lockfile is unchanged)' : ''} (${install.summary})`) : undefined
+  const port = await freePort()
+  mkdirSync(join(project.stateDir, 'logs'), { recursive: true })
+  mkdirSync(devDir(project), { recursive: true })
+  const log = join(project.stateDir, 'logs', `app-${app.slug}.log`)
+  const fd = openSync(log, 'a')
+  // Where this run's output starts in the log, which keeps earlier runs: its tail is this run's alone.
+  const from = statSync(log).size
+  const [exe, ...pre] = options.command ?? selfCommand()
+  const child = spawn(exe!, [...pre, 'app', 'dev', '--no-open', '--port', String(port)], {
+    cwd: app.root,
+    detached: true,
+    stdio: ['ignore', fd, fd],
+    // The server stops when this process ends, however it ends (`frontera app dev` watches it).
+    env: { ...process.env, ...localAppEnv(link), NO_COLOR: '1', [DEV_OWNER_ENV]: String(process.pid) },
+  })
+  closeSync(fd)
+  let exited: DevServerExit | null = null
+  child.on('exit', (code, signal) => {
+    exited = { code, signal, at: new Date().toISOString(), tail: logTail(log, from) }
+    options.onExit?.(exited)
+  })
+  child.on('error', () => {
+    // A command that could not start at all exits too ('exit' follows with its code); nothing else to do here.
+  })
+  child.unref()
+  const origin = `http://127.0.0.1:${port}`
+  const server: DevServer = { slug: app.slug, pid: child.pid!, port, url: app.framework === 'vite' ? `${origin}/dev-host.html` : origin, startedAt: new Date().toISOString(), log: relative(project.root, log), owner: { kind: options.owner ?? 'mcp', pid: process.pid } }
+  startedHere.set(`${project.root}\0${app.slug}`, { project, slug: app.slug, pid: server.pid })
+  writeFileSync(devFile(project, app.slug), `${JSON.stringify(server, null, 2)}\n`)
+  const deadline = Date.now() + READY_MS
+  while (Date.now() < deadline) {
+    if (exited || !isAlive(server.pid)) break
+    // Ready once it answers and `app dev` said so: by then it has put back the tracked files the server wrote.
+    if ((await answers(server.url)) && devSaidReady(log, from)) {
+      const tracked = trackedFileLines(log, from)
+      return { server, reused: false, ...(installed ? { installed } : {}), ...(tracked.length ? { trackedFiles: tracked } : {}) }
+    }
+    await new Promise((r) => setTimeout(r, 400))
+  }
+  rmSync(devFile(project, app.slug), { force: true })
+  startedHere.delete(`${project.root}\0${app.slug}`)
+  const gone = exited as DevServerExit | null
+  // Not ready in time: the server this call started is stopped, never left running unrecorded.
+  if (!gone) stopGroup(server.pid)
+  const tail = logTail(log, from)
+  const notFound = /command not found|not found: (next|vite)\b/i.test(tail) ? ` Its dev command isn't installed: run \`bun install\` in ${relative(project.root, app.root) || '.'}.` : ''
+  const why = gone ? `The dev server for ${app.slug} exited ${exitWords(gone)} before it was ready.` : `The dev server for ${app.slug} did not start within ${READY_MS / 1000} seconds, so it was stopped.`
+  throw new Error(`${why}${notFound}${tail ? `\n${tail}` : ''}`)
+}
+
+/** Whether this run of `frontera app dev` has said it is ready (`[dev] ready: …`), after putting back what the server wrote. */
+function devSaidReady(log: string, from: number): boolean {
+  return /^\[dev\] ready\b/m.test(logSince(log, from))
+}
+
+/**
+ * What this run of `frontera app dev` said of the App's tracked files: the
+ * ones the dev server rewrote and it put back (`next-env.d.ts`), the ones it
+ * left because they were edited, and an SDK path it set aside. Without the
+ * `[dev] ` prefix.
+ */
+export function trackedFileLines(log: string, from: number): string[] {
+  return logSince(log, from)
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => /^\[dev\] (put back|left|tsconfig\.json)\b/.test(l))
+    .map((l) => l.replace(/^\[dev\] /, ''))
+}
+
+function logSince(log: string, from: number): string {
+  try {
+    return readFileSync(log).subarray(from).toString('utf8')
+  } catch {
+    return ''
+  }
+}
+
+/** "with code 1", "on SIGTERM": how a dev server ended, for a sentence. */
+export function exitWords(exit: Pick<DevServerExit, 'code' | 'signal'>): string {
+  return exit.code !== null ? `with code ${exit.code}` : exit.signal ? `on ${exit.signal}` : 'with no exit code'
+}
+
+const TAIL_LINES = 30
+
+/** The last lines written to a log from an offset on: one run's output. */
+function logTail(log: string, from: number): string {
+  try {
+    // A byte offset: the log holds UTF-8 (Next.js prints ▲ and ✓), so it is cut as bytes, then read.
+    const text = readFileSync(log).subarray(from).toString('utf8')
+    return text.split('\n').map((l) => l.trimEnd()).filter((l, i, all) => l || i < all.length - 1).slice(-TAIL_LINES).join('\n').trim()
+  } catch {
+    return ''
+  }
+}
+
+/** SIGTERM to a dev server's whole group (`app dev` and the framework's server under it), or to it alone. */
+function stopGroup(pid: number): boolean {
+  try {
+    process.kill(-pid, 'SIGTERM')
+    return true
+  } catch {
+    try {
+      process.kill(pid, 'SIGTERM')
+      return true
+    } catch {
+      return false
+    }
+  }
+}
+
+/**
+ * Whether a recorded pid is still an App dev server (`frontera app dev`, or the
+ * framework under it), not an unrelated process that took the pid since: only
+ * such a process is ever signalled. Where `ps` can't say, the record is trusted.
+ */
+export function isDevServerProcess(pid: number): boolean {
+  const res = spawnSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8' })
+  if (res.error) return true
+  if (res.status !== 0) return false
+  return /\bapp\b.*\bdev\b|\bnext\b.*\bdev\b|\bvite\b/.test(res.stdout)
+}
+
+/**
+ * Stop an App's dev server and wait (a while) for it to end, then say what
+ * `frontera app dev` put back as it stopped: the tracked files the server
+ * rewrote. `stopped` false when none ran.
+ */
+export async function stopDevServerAndSay(project: LocalProject, slug: string, waitMs = 15_000): Promise<{ stopped: boolean; trackedFiles: string[] }> {
+  const server = readDevServer(project, slug)
+  const log = server?.log ? join(project.root, server.log) : null
+  let from = 0
+  try {
+    from = log ? statSync(log).size : 0
+  } catch {
+    // No log (started by hand): nothing to read back.
+  }
+  if (!stopDevServer(project, slug) || !server) return { stopped: false, trackedFiles: [] }
+  const deadline = Date.now() + waitMs
+  while (Date.now() < deadline && isAlive(server.pid)) await new Promise((r) => setTimeout(r, 200))
+  return { stopped: true, trackedFiles: log && existsSync(log) ? trackedFileLines(log, from) : [] }
+}
+
+/** Stop an App's dev server, when one runs. Only this project's record is read, so another project's server is never touched. */
+export function stopDevServer(project: LocalProject, slug: string): boolean {
+  const server = readDevServer(project, slug)
+  rmSync(devFile(project, slug), { force: true })
+  if (!server || !isDevServerProcess(server.pid)) return false
+  // The whole group: `app dev` and the framework's server under it.
+  return stopGroup(server.pid)
+}
+
+/**
+ * Stop every App dev server this project records (`local stop`, `local
+ * remove`): the ones an MCP session started and the ones run by hand, which
+ * point at the runtime that is going away. Records of servers already gone
+ * are cleared. Returns the servers stopped.
+ */
+export function stopDevServers(project: LocalProject): DevServer[] {
+  const stopped: DevServer[] = []
+  let files: string[] = []
+  try {
+    files = readdirSync(devDir(project)).filter((f) => f.endsWith('.json'))
+  } catch {
+    return stopped
+  }
+  for (const f of files) {
+    const slug = f.replace(/\.json$/, '')
+    const server = readDevServer(project, slug)
+    if (stopDevServer(project, slug) && server) stopped.push(server)
+  }
+  return stopped
+}
+
+/**
+ * Stop the dev servers this process started: an MCP session's when its
+ * connection closes, Forge's when it quits. One another session or a person
+ * has since taken over (a different pid in the record) is left running.
+ */
+export function stopStartedDevServers(): number {
+  let n = 0
+  for (const { project, slug, pid } of startedHere.values()) {
+    if (readDevServer(project, slug)?.pid === pid && stopDevServer(project, slug)) n++
+  }
+  startedHere.clear()
+  return n
+}
+
+/**
+ * Call `onGone` once, when the process `owner` is no longer there (checked
+ * every `everyMs`): how `frontera app dev` started by an MCP session stops
+ * with it, however the session ends. Returns the stop for the watch.
+ */
+export function watchOwner(owner: number, onGone: () => void, everyMs = 5_000): () => void {
+  const timer = setInterval(() => {
+    if (isAlive(owner)) return
+    clearInterval(timer)
+    onGone()
+  }, everyMs)
+  return () => clearInterval(timer)
+}
+
+/** "cdl-console on port 3101 (http://127.0.0.1:3101), started by an MCP session (pid 4242)" */
+export function devServerLine(s: DevServer): string {
+  const by = !s.owner
+    ? 'started by hand (`frontera app dev`)'
+    : s.owner.kind === 'forge'
+      ? `started from Forge (pid ${s.owner.pid}); it stops when Forge stops it or quits`
+      : `started by an MCP session (pid ${s.owner.pid}); it stops when that session ends`
+  return `${s.slug} on port ${s.port} (${s.url}), ${by}`
+}

package/src/mcp/mcp-chat.ts

@@ -0,0 +1,226 @@
+import { parkCall, type ToolCall } from '../local/local-test-runner'
+import type { RuntimeLink } from './mcp-runtime'
+
+/**
+ * One Agent turn as `agent_chat` reads it: the reply streamed from
+ * `/v1/chat`, read until the turn finishes or the Agent waits on the person.
+ *
+ * A turn that waits on the person keeps its stream open: a Function asked
+ * the person to confirm (`data-person-confirmation`), or a tool call waits
+ * for an approval (`tool-approval-request`). Read to its end, such a turn
+ * never ends, which is how a follow-up looked like a timeout. So the reader
+ * stops there, says what is waiting, and keeps the stream: the answer
+ * (`agent_chat` with `confirm` or `approval`) settles it and the rest of the
+ * turn is read from the same stream, or from the run's journal when that
+ * connection is gone.
+ */
+
+export interface PendingConfirmation {
+  kind: 'confirmation'
+  id: string
+  summary: string
+  details: string | null
+  confirmLabel: string
+  cancelLabel: string
+  expiresAt?: string
+}
+
+export interface PendingApproval {
+  kind: 'approval'
+  id: string
+  toolCallId: string | null
+  tool: string | null
+  summary?: string | null
+  expiresAt?: string
+  /** The card's reason, as the person reads it. */
+  reason?: string | null
+  /** What asked: the binding's own setting, or the chat's approval mode. */
+  askedBecause?: 'binding' | 'approval-mode'
+}
+
+export type PendingDecision = PendingConfirmation | PendingApproval
+
+export type TurnEnd =
+  | { status: 'finished' }
+  | { status: 'waiting'; pending: PendingDecision }
+  /** Nothing arrived for the idle window: the runtime took the turn and sent nothing back. */
+  | { status: 'idle'; silentMs: number }
+  | { status: 'timeout'; elapsedMs: number }
+
+export interface TurnRead {
+  reply: string
+  toolCalls: ToolCall[]
+  end: TurnEnd
+  /** The run behind the turn (`x-workflow-run-id`), to read its journal again. */
+  runId: string | null
+  /** Stream chunks read so far: where the journal picks up. */
+  chunks: number
+  /** Events seen, by type, for a turn that ended oddly. */
+  events: Record<string, number>
+  lastEvent: string | null
+}
+
+/** A turn's stream, kept between calls while the Agent waits on the person. */
+/** The part of a stream reader a held turn uses. */
+interface ChunkReader {
+  read(): Promise<{ done: boolean; value?: Uint8Array }>
+  cancel(): Promise<void>
+}
+
+export interface HeldTurn {
+  reader: ChunkReader | null
+  buffer: string
+  runId: string | null
+  chunks: number
+  reply: string
+  calls: Map<string, ToolCall & { id: string }>
+  events: Record<string, number>
+  lastEvent: string | null
+  /** Decisions already reported, so a replay of the journal does not stop on them again. */
+  seen: Set<string>
+}
+
+export const TURN_IDLE_MS = 90_000
+export const TURN_TOTAL_MS = 240_000
+
+function headers(link: RuntimeLink): Record<string, string> {
+  return {
+    authorization: `Bearer ${link.creds.session}`,
+    'x-org-id': link.creds.organizationId,
+    'x-workspace-id': link.creds.workspaceId,
+    'content-type': 'application/json',
+  }
+}
+
+/** Send the person's message and hold the turn's stream. */
+export async function startTurn(link: RuntimeLink, args: { conversationId: string; agentName: string; message: string }): Promise<HeldTurn> {
+  const res = await fetch(new URL('/v1/chat', link.serviceUrl), {
+    method: 'POST',
+    headers: headers(link),
+    body: JSON.stringify({
+      conversationId: args.conversationId,
+      agentName: args.agentName,
+      messages: [{ id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: args.message }] }],
+    }),
+  })
+  // A 409 carries what waits on the person (`decision_pending`): kept whole for the caller to read.
+  if (!res.ok || !res.body) throw new Error(`chat answered ${res.status}: ${(await res.text()).slice(0, res.status === 409 ? 20_000 : 300)}`)
+  return { reader: res.body.getReader() as ChunkReader, buffer: '', runId: res.headers.get('x-workflow-run-id'), chunks: 0, reply: '', calls: new Map(), events: {}, lastEvent: null, seen: new Set() }
+}
+
+/** Pick the held turn up again from the run's journal, after its connection went away. */
+export async function reattachTurn(link: RuntimeLink, held: HeldTurn): Promise<HeldTurn> {
+  if (!held.runId) throw new Error('the turn has no run to reattach to')
+  const res = await fetch(new URL(`/v1/chat/${encodeURIComponent(held.runId)}/stream?startIndex=${held.chunks}`, link.serviceUrl), { headers: headers(link) })
+  if (res.status === 404) {
+    // The run settled while nobody read it: what it said is in the conversation.
+    return { ...held, reader: null }
+  }
+  if (!res.ok || !res.body) throw new Error(`the turn's stream answered ${res.status}: ${(await res.text()).slice(0, 300)}`)
+  return { ...held, reader: res.body.getReader() as ChunkReader, buffer: '' }
+}
+
+interface StreamEvent {
+  type?: string
+  delta?: string
+  errorText?: string
+  toolCallId?: string
+  toolName?: string
+  input?: unknown
+  args?: unknown
+  approvalId?: string
+  data?: Record<string, unknown>
+}
+
+/** One event: reply text, a tool call, or a decision the Agent now waits on. */
+function take(held: HeldTurn, event: StreamEvent): PendingDecision | null {
+  const type = event.type ?? 'unknown'
+  held.events[type] = (held.events[type] ?? 0) + 1
+  held.lastEvent = type
+  if (type === 'text-delta' && typeof event.delta === 'string') held.reply += event.delta
+  if (type === 'tool-input-available' && event.toolCallId && event.toolName) held.calls.set(event.toolCallId, { id: event.toolCallId, name: event.toolName, args: event.input, ok: false })
+  if (type === 'tool-output-available' && event.toolCallId && held.calls.has(event.toolCallId)) Object.assign(held.calls.get(event.toolCallId)!, { ok: true, parked: false })
+  // Denied or failed: it waits no longer, and never ran.
+  if ((type === 'tool-output-denied' || type === 'tool-output-error') && event.toolCallId && held.calls.has(event.toolCallId)) held.calls.get(event.toolCallId)!.parked = false
+  if (type === 'error') throw new Error(event.errorText ?? 'the turn failed')
+  if (type === 'tool-approval-request' && event.approvalId && !held.seen.has(event.approvalId)) {
+    held.seen.add(event.approvalId)
+    // The call waits on the person: a test saved from this turn counts it as called.
+    const parked = parkCall(held.calls, event)
+    const call = parked ? held.calls.get(parked.id) : event.toolCallId ? held.calls.get(event.toolCallId) : undefined
+    return { kind: 'approval', id: event.approvalId, toolCallId: event.toolCallId ?? null, tool: call?.name ?? null }
+  }
+  if (type === 'data-person-confirmation' && event.data) {
+    const d = event.data as Partial<PendingConfirmation> & { status?: string; id?: string }
+    if (d.status === 'pending' && d.id && !held.seen.has(d.id)) {
+      held.seen.add(d.id)
+      return { kind: 'confirmation', id: d.id, summary: String(d.summary ?? ''), details: (d.details as string | null) ?? null, confirmLabel: String(d.confirmLabel ?? 'Confirm'), cancelLabel: String(d.cancelLabel ?? 'Cancel'), ...(d.expiresAt ? { expiresAt: String(d.expiresAt) } : {}) }
+    }
+  }
+  return null
+}
+
+/**
+ * Read the held turn until it finishes, waits on the person, goes silent
+ * for `idleMs`, or runs past `totalMs`. The reply and tool calls are
+ * everything since the person's message, across reads.
+ */
+export async function readTurn(held: HeldTurn, opts: { idleMs?: number; totalMs?: number } = {}): Promise<TurnRead> {
+  const idleMs = opts.idleMs ?? TURN_IDLE_MS
+  const totalMs = opts.totalMs ?? TURN_TOTAL_MS
+  const started = Date.now()
+  const decoder = new TextDecoder()
+  const result = (end: TurnEnd): TurnRead => ({ reply: held.reply, toolCalls: [...held.calls.values()].map(({ id: _id, ...c }) => c), end, runId: held.runId, chunks: held.chunks, events: { ...held.events }, lastEvent: held.lastEvent })
+  if (!held.reader) return result({ status: 'finished' })
+  let lastData = Date.now()
+  for (;;) {
+    // Keepalive comments arrive without data; only data counts against the idle window.
+    const wait = Math.max(0, Math.min(idleMs - (Date.now() - lastData), totalMs - (Date.now() - started)))
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const next = await Promise.race([
+      held.reader.read(),
+      new Promise<'timer'>((r) => {
+        timer = setTimeout(() => r('timer'), wait)
+      }),
+    ]).finally(() => clearTimeout(timer))
+    if (next === 'timer') {
+      if (Date.now() - started >= totalMs) return result({ status: 'timeout', elapsedMs: Date.now() - started })
+      return result({ status: 'idle', silentMs: Date.now() - lastData })
+    }
+    if (next.done) {
+      held.reader = null
+      return result({ status: 'finished' })
+    }
+    held.buffer += decoder.decode(next.value, { stream: true })
+    let newline: number
+    while ((newline = held.buffer.indexOf('\n')) >= 0) {
+      const line = held.buffer.slice(0, newline).trim()
+      held.buffer = held.buffer.slice(newline + 1)
+      if (!line.startsWith('data:')) continue
+      const payload = line.slice(5).trim()
+      if (payload === '[DONE]') continue
+      let event: StreamEvent
+      try {
+        event = JSON.parse(payload) as StreamEvent
+      } catch {
+        continue
+      }
+      held.chunks++
+      lastData = Date.now()
+      const pending = take(held, event)
+      if (pending) return result({ status: 'waiting', pending })
+      if (event.type === 'finish') {
+        // The turn is over; nothing after `finish` belongs to the reply.
+        void held.reader.cancel().catch(() => {})
+        held.reader = null
+        return result({ status: 'finished' })
+      }
+    }
+  }
+}
+
+/** Stop reading a held turn: the conversation moved on or the connection is being dropped. */
+export function dropTurn(held: HeldTurn | undefined): void {
+  void held?.reader?.cancel().catch(() => {})
+  if (held) held.reader = null
+}