dsh-plugin-subagent-bridge 0.16.0 → 0.18.0

package/src/runners/claude.js

@@ -0,0 +1,177 @@
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { CLAUDE_CANDIDATES } from '../constants.js'
+import { expandHome } from '../settings.js'
+import { ok, text } from '../utils.js'
+
+export function resolveClaude(configured) {
+  const configuredValue = typeof configured === 'string' ? configured : ''
+  /* An explicit path is authoritative: never silently run a different binary. */
+  if (configuredValue.includes('/')) {
+    const expanded = expandHome(configuredValue)
+    return existsSync(expanded) ? expanded : undefined
+  }
+  for (const directory of String(process.env.PATH ?? '').split(':')) {
+    if (directory !== '' && existsSync(join(directory, 'claude'))) return 'claude'
+  }
+  for (const candidate of CLAUDE_CANDIDATES) {
+    const expanded = expandHome(candidate)
+    if (existsSync(expanded)) return expanded
+  }
+  return undefined
+}
+
+/**
+ * Run one `claude -p` turn and return its final answer.
+ *
+ * Claude Code prints a single JSON object in print mode, so the whole answer arrives at
+ * once — unlike Codex, which streams events. Anything on stderr is advisory: the CLI
+ * warns about an unrecognised model suffix while still succeeding, so only the JSON
+ * envelope decides the outcome.
+ * @param options - binary, prompt, cwd, resume id, model, timeout, signal, child registry.
+ * @returns `{ ok, text, sessionId?, durationMs, exitCode, error? }`.
+ */
+
+export async function runClaude({
+  bin,
+  prompt,
+  cwd,
+  resume,
+  model,
+  timeoutMs,
+  signal,
+  children,
+  spawnImpl = spawn,
+}) {
+  const started = Date.now()
+  if (bin === undefined) {
+    return { ok: false, text: '', exitCode: -1, durationMs: 0, error: 'claude executable not found; set config.claudeBin' }
+  }
+  const args = ['-p', prompt, '--output-format', 'json']
+  if (typeof resume === 'string' && resume !== '') args.unshift('--resume', resume)
+  if (typeof model === 'string' && model !== '') args.push('--model', model)
+
+  const outcome = await new Promise((resolve) => {
+    let child
+    try {
+      child = spawnImpl(bin, args, { cwd: cwd ?? homedir(), stdio: ['ignore', 'pipe', 'pipe'] })
+    } catch (error) {
+      resolve({ exitCode: -1, stdout: '', stderr: String(error), error: String(error) })
+      return
+    }
+    children?.add(child)
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    const finish = (value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      signal?.removeEventListener?.('abort', abort)
+      children?.delete(child)
+      resolve(value)
+    }
+    const kill = (reason) => {
+      try {
+        child.kill('SIGTERM')
+      } catch {
+        /* Already gone. */
+      }
+      setTimeout(() => {
+        try {
+          child.kill('SIGKILL')
+        } catch {
+          /* Already gone. */
+        }
+      }, 5000).unref?.()
+      finish({ exitCode: -1, stdout, stderr, error: reason })
+    }
+    const timer = setTimeout(() => kill(`claude timed out after ${timeoutMs} ms`), Math.max(1000, timeoutMs ?? 300000))
+    const abort = () => kill('cancelled by the caller')
+    if (signal?.aborted === true) abort()
+    else signal?.addEventListener?.('abort', abort)
+    child.stdout?.on('data', (chunk) => {
+      stdout += chunk.toString('utf8')
+    })
+    child.stderr?.on('data', (chunk) => {
+      stderr += chunk.toString('utf8')
+    })
+    child.on('error', (error) => finish({ exitCode: -1, stdout, stderr, error: error.message }))
+    child.on('close', (code) => finish({ exitCode: code ?? -1, stdout, stderr }))
+  })
+
+  const parsed = parseClaudeOutput(outcome.stdout)
+  const durationMs = Date.now() - started
+  const build = (ok, error) => ({
+    ok,
+    text: parsed.text,
+    exitCode: ok ? 0 : outcome.exitCode,
+    durationMs,
+    ...(parsed.sessionId === undefined ? {} : { sessionId: parsed.sessionId }),
+    ...(error === undefined ? {} : { error }),
+  })
+  if (outcome.error !== undefined) return build(false, outcome.error)
+  if (parsed.error !== undefined) return build(false, parsed.error)
+  if (outcome.exitCode !== 0) {
+    const detail = outcome.stderr.trim().split('\n').slice(-3).join('\n')
+    return build(false, `claude exited with ${outcome.exitCode}${detail === '' ? '' : `: ${detail}`}`)
+  }
+  return build(true, undefined)
+}
+
+/**
+ * Read the print-mode JSON envelope.
+ * @param stdout - raw standard output.
+ * @returns `{ text, sessionId?, error? }`.
+ */
+
+export function parseClaudeOutput(stdout) {
+  const raw = String(stdout ?? '').trim()
+  if (raw === '') return { text: '', error: 'claude printed nothing' }
+  /* A single object is the documented shape, but the CLI writes advisory lines to the
+   * same stream, and those lines can carry braces of their own. Parse whole output first,
+   * then scan lines backwards for the envelope that carries a result. */
+  const lines = raw.split('\n').map((line) => line.trim()).filter((line) => line !== '')
+  const candidates = [...lines].reverse()
+  let payload
+  let lastError
+  for (const candidate of candidates) {
+    if (!candidate.startsWith('{') || !candidate.endsWith('}')) continue
+    try {
+      const parsed = JSON.parse(candidate)
+      if (typeof parsed === 'object' && parsed !== null && typeof parsed.type === 'string') {
+        payload = parsed
+        break
+      }
+    } catch (error) {
+      lastError = error
+    }
+  }
+  if (payload === undefined) {
+    if (lastError !== undefined) {
+      return { text: '', error: `claude printed invalid JSON: ${String(lastError?.message ?? lastError)}` }
+    }
+    return { text: '', error: `claude printed no result envelope: ${raw.slice(0, 200)}` }
+  }
+  const text = typeof payload.result === 'string' ? payload.result.trim() : ''
+  const sessionId = typeof payload.session_id === 'string' && payload.session_id !== '' ? payload.session_id : undefined
+  const failed = payload.is_error === true || (typeof payload.subtype === 'string' && payload.subtype !== 'success')
+  const build = {
+    text,
+    ...(sessionId === undefined ? {} : { sessionId }),
+  }
+  if (failed !== true) return build
+  const detail =
+    typeof payload.result === 'string' && payload.result.trim() !== ''
+      ? payload.result.trim()
+      : `claude reported ${String(payload.subtype ?? payload.terminal_reason ?? 'an error')}`
+  return { ...build, error: detail }
+}
+
+/**
+ * Read a file, tolerating absence.
+ * @param path - file path.
+ * @returns the text, or undefined.
+ */

package/src/runners/codex.js

@@ -0,0 +1,185 @@
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { CODEX_CANDIDATES } from '../constants.js'
+import { expandHome } from '../settings.js'
+import { ok, text } from '../utils.js'
+
+export function resolveCodex(configured) {
+  const configuredValue = typeof configured === 'string' ? configured : ''
+  /* An explicit path is authoritative: never silently run a different binary. */
+  if (configuredValue.includes('/')) {
+    const expanded = expandHome(configuredValue)
+    return existsSync(expanded) ? expanded : undefined
+  }
+  for (const directory of String(process.env.PATH ?? '').split(':')) {
+    if (directory !== '' && existsSync(join(directory, 'codex'))) return 'codex'
+  }
+  for (const candidate of CODEX_CANDIDATES) {
+    const expanded = expandHome(candidate)
+    if (existsSync(expanded)) return expanded
+  }
+  return undefined
+}
+
+
+/**
+ * Locate the Claude Code executable.
+ * @param configured - configured path or bare command name.
+ * @returns the command to spawn, or undefined.
+ */
+
+export async function runCodex({
+  bin,
+  prompt,
+  cwd,
+  resume,
+  sandbox,
+  timeoutMs,
+  signal,
+  children,
+  spawnImpl = spawn,
+}) {
+  const started = Date.now()
+  if (bin === undefined) {
+    return { ok: false, text: '', exitCode: -1, durationMs: 0, error: 'codex executable not found; set config.codexBin' }
+  }
+  const temp = await mkdtemp(join(tmpdir(), 'dsh-codex-'))
+  const outFile = join(temp, 'last-message.txt')
+  const resuming = resume !== undefined
+  const args = ['exec']
+  if (resuming) args.push('resume', resume)
+  args.push('--json', '--skip-git-repo-check', '-o', outFile)
+  /* `codex exec resume` takes neither --sandbox nor --cd: the thread keeps its own. */
+  if (!resuming) {
+    args.push('-s', sandbox === undefined ? 'workspace-write' : sandbox)
+    if (typeof cwd === 'string' && cwd !== '') args.push('-C', cwd)
+  }
+  args.push(prompt)
+
+  try {
+    const outcome = await new Promise((resolve) => {
+      let child
+      try {
+        child = spawnImpl(bin, args, { cwd: cwd ?? homedir(), stdio: ['ignore', 'pipe', 'pipe'] })
+      } catch (error) {
+        resolve({ exitCode: -1, stdout: '', stderr: String(error), error: String(error) })
+        return
+      }
+      children?.add(child)
+      let stdout = ''
+      let stderr = ''
+      let settled = false
+      const finish = (value) => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        signal?.removeEventListener?.('abort', abort)
+        children?.delete(child)
+        resolve(value)
+      }
+      const kill = (reason) => {
+        try {
+          child.kill('SIGTERM')
+        } catch {
+          /* Already gone. */
+        }
+        setTimeout(() => {
+          try {
+            child.kill('SIGKILL')
+          } catch {
+            /* Already gone. */
+          }
+        }, 5000).unref?.()
+        finish({ exitCode: -1, stdout, stderr, error: reason })
+      }
+      const timer = setTimeout(() => kill(`codex timed out after ${timeoutMs} ms`), Math.max(1000, timeoutMs ?? 300000))
+      const abort = () => kill('cancelled by the caller')
+      if (signal?.aborted === true) abort()
+      else signal?.addEventListener?.('abort', abort)
+      child.stdout?.on('data', (chunk) => {
+        stdout += chunk.toString('utf8')
+      })
+      child.stderr?.on('data', (chunk) => {
+        stderr += chunk.toString('utf8')
+      })
+      child.on('error', (error) => finish({ exitCode: -1, stdout, stderr, error: error.message }))
+      child.on('close', (code) => finish({ exitCode: code ?? -1, stdout, stderr }))
+    })
+
+    const parsed = parseCodexOutput(outcome.stdout, await readIfExists(outFile))
+    const durationMs = Date.now() - started
+    /* A resumed run emits no thread.started, so every field stays optional: a tool
+     * result must be lossless JSON, and `undefined` is not. */
+    const build = (ok, error) => ({
+      ok,
+      text: parsed.text,
+      exitCode: ok ? 0 : outcome.exitCode,
+      durationMs,
+      ...(parsed.threadId === undefined ? {} : { threadId: parsed.threadId }),
+      ...(error === undefined ? {} : { error }),
+    })
+    if (outcome.error !== undefined) return build(false, outcome.error)
+    if (outcome.exitCode !== 0) {
+      const detail = parsed.error ?? outcome.stderr.trim().split('\n').slice(-3).join('\n')
+      return build(false, `codex exited with ${outcome.exitCode}${detail === '' ? '' : `: ${detail}`}`)
+    }
+    return build(true, undefined)
+  } finally {
+    await rm(temp, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+/**
+ * Parse `codex exec --json` output.
+ * @param stdout - JSONL event stream.
+ * @param lastMessage - contents of the `-o` file, when written.
+ * @returns `{ text, threadId, error }`.
+ */
+
+export function parseCodexOutput(stdout, lastMessage) {
+  let threadId
+  let error
+  const messages = []
+  for (const line of String(stdout ?? '').split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed.startsWith('{')) continue
+    let event
+    try {
+      event = JSON.parse(trimmed)
+    } catch {
+      continue
+    }
+    if (event.type === 'thread.started' && typeof event.thread_id === 'string') threadId = event.thread_id
+    if (event.type === 'item.completed' && event.item?.type === 'agent_message' && typeof event.item.text === 'string') {
+      messages.push(event.item.text)
+    }
+    if (event.type === 'error' && typeof event.message === 'string') error = event.message
+    if (event.type === 'turn.failed' && typeof event.error?.message === 'string') error = event.error.message
+  }
+  const text = typeof lastMessage === 'string' && lastMessage.trim() !== '' ? lastMessage.trim() : messages.join('\n\n').trim()
+  return { text, ...(threadId === undefined ? {} : { threadId }), ...(error === undefined ? {} : { error }) }
+}
+
+/**
+ * Find the `codex` executable.
+ * @param configured - configured binary name or path.
+ * @returns the path to use, or undefined when nothing resolves.
+ */
+
+export async function readIfExists(path) {
+  try {
+    return await readFile(path, 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Read one session title without letting a missing service break the listing.
+ * @param service - optional title service.
+ * @param session - live session.
+ * @returns the title, when one exists.
+ */

package/src/sessions.js

@@ -0,0 +1,336 @@
+import { mkdir } from 'node:fs/promises'
+import { ok, text } from './utils.js'
+
+export function lastTurn(ctx, sessionId) {
+  const session = ctx.get('sessions')?.get?.(sessionId)
+  if (session === undefined || session === null) return 0
+  let turn = 0
+  for (const event of session.snapshotEvents()) {
+    if (event.type === 'turn/start' && Number(event.data?.turn) > turn) turn = Number(event.data.turn)
+  }
+  return turn
+}
+
+/**
+ * Resolve when the session finishes the turn that this dispatch starts.
+ * Subscribes before the prompt so a fast turn cannot be missed.
+ * @param ctx - Host context.
+ * @param sessionId - session to watch.
+ * @param afterTurn - ignore turns at or below this number.
+ * @param timeoutMs - bounded wait.
+ * @returns the `turn/end` payload, or undefined on timeout.
+ */
+
+export function waitForTurnEnd(ctx, sessionId, afterTurn, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false
+    const finish = (value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      off()
+      resolve(value)
+    }
+    const off = ctx.on('session/event', (session, event) => {
+      if (session?.id !== sessionId) return
+      if (event?.type !== 'turn/end') return
+      if (Number(event.data?.turn) <= afterTurn) return
+      finish(event.data)
+    })
+    const timer = setTimeout(() => finish(undefined), Math.max(1000, timeoutMs))
+  })
+}
+
+/**
+ * Collect assistant text produced after a sequence number.
+ * @param ctx - Host context.
+ * @param sessionId - session to read.
+ * @param sinceSeq - only count messages after this sequence.
+ * @param settings - resolved settings.
+ * @returns the joined text and whether it was trimmed.
+ */
+
+export function collectAssistant(ctx, sessionId, sinceSeq, settings) {
+  const session = ctx.get('sessions')?.get?.(sessionId)
+  if (session === undefined || session === null) return { text: '', truncated: false }
+  const texts = []
+  for (const event of session.snapshotEvents()) {
+    if (Number(event.seq) <= sinceSeq) continue
+    if (event.type !== 'assistant/message') continue
+    const blocks = Array.isArray(event.data?.message?.content) ? event.data.message.content : []
+    const value = blocks
+      .filter((block) => block?.type === 'text' && typeof block.text === 'string')
+      .map((block) => block.text)
+      .join('\n')
+      .trim()
+    if (value !== '') texts.push(value)
+  }
+  const joined = texts.join('\n\n')
+  return {
+    text: joined.length > settings.maxResultChars ? joined.slice(-settings.maxResultChars) : joined,
+    truncated: joined.length > settings.maxResultChars,
+  }
+}
+
+
+/** Deepest cross-tool delegation currently in flight, or 0 when no chain is open. */
+
+export function firstDeliveredMessageSeq(ctx, sessionId, sinceSeq) {
+  const session = ctx.get('sessions')?.get?.(sessionId)
+  if (session === undefined || session === null) return sinceSeq
+  for (const event of session.snapshotEvents()) {
+    if (Number(event.seq) <= sinceSeq) continue
+    if (event.type !== 'user/message') continue
+    return Number(event.seq)
+  }
+  return sinceSeq
+}
+
+/**
+ * Start the bridge.
+ * @param ctx - Host context.
+ * @param config - row configuration from the bundle patch.
+ */
+
+export function parseModelSpec(ctx, spec) {
+  const raw = String(spec).trim()
+  if (raw === '') throw new Error('model must not be empty')
+  if (raw.startsWith('/') || raw.endsWith('/') || raw.includes('//')) {
+    throw new Error(`model must look like "provider/model", got ${JSON.stringify(spec)}`)
+  }
+  const slash = raw.indexOf('/')
+  if (slash > 0) {
+    const provider = raw.slice(0, slash).trim()
+    const model = raw.slice(slash + 1).trim()
+    if (provider === '' || model === '') throw new Error(`model must look like "provider/model", got ${JSON.stringify(spec)}`)
+    return { provider, model }
+  }
+  const current = ctx.get('agentDefaultModel')?.currentSelection?.()
+  const provider = typeof current?.provider === 'string' ? current.provider : ''
+  if (provider === '') throw new Error('model without a provider needs a default selection; pass "provider/model"')
+  return { provider, model: raw }
+}
+
+/**
+ * Install a model selection on one session before its next turn.
+ * `sessionController.selectModel` validates the pair and applies it to the next request.
+ * @param ctx - Host context.
+ * @param sessionId - session to switch.
+ * @param spec - `provider/model` or a bare model id.
+ * @param reasoningEffort - optional effort level.
+ * @returns {{ provider: string, model: string, reasoningEffort?: string } | undefined} applied selection.
+ */
+
+export async function applyModelSpec(ctx, sessionId, spec, reasoningEffort) {
+  if (typeof spec !== 'string' || spec.trim() === '') return undefined
+  const service = ctx.get('sessionController')
+  if (service === undefined || service === null) throw new Error('session controller is unavailable')
+  if (typeof service.selectModel !== 'function') throw new Error('this Host does not expose selectModel; update DeepSeek Harness')
+  const { provider, model } = parseModelSpec(ctx, spec)
+  try {
+    const result = await service.selectModel({
+      sessionId,
+      provider,
+      model,
+      ...(typeof reasoningEffort === 'string' && reasoningEffort !== '' ? { reasoningEffort } : {}),
+    })
+    return result?.selected ?? { provider, model, ...(reasoningEffort ? { reasoningEffort } : {}) }
+  } catch (error) {
+    throw new Error(`cannot switch ${String(sessionId)} to ${provider}/${model}: ${String(error?.message ?? error)}`)
+  }
+}
+
+/**
+ * Translate the `workspace` argument into attach options.
+ * - absent / `false` → never create, only reuse an existing project for the directory
+ * - `true` → create a project titled after the directory when none owns it
+ * - a string → same, with that title
+ * @param workspace - raw argument from the tool call.
+ * @returns options for {@link attachToWorkspace}.
+ */
+
+export function workspaceOptions(workspace) {
+  if (workspace === true) return { create: true }
+  if (typeof workspace === 'string' && workspace.trim() !== '') return { create: true, title: workspace.trim() }
+  return {}
+}
+
+/**
+ * Place a freshly created session in the workspace its directory belongs to.
+ * `sessionController.create` only records a working directory; the sidebar groups
+ * live in a separate registry, so without this step a worker shows up as ungrouped.
+ * @param ctx - Host context.
+ * @param sessionId - session just created.
+ * @param cwd - directory the session was opened in.
+ */
+
+export async function attachToWorkspace(ctx, sessionId, cwd, options = {}) {
+  if (typeof cwd !== 'string' || cwd === '') return undefined
+  try {
+    const registry = ctx.get('workspaceRegistry')
+    if (registry === undefined || registry === null) return undefined
+
+    /* Only create when the caller asked for it: an existing project is reused either way,
+     * because `create` returns the record that already owns the canonical path. */
+    let workspace
+    if (options.create === true && typeof registry.create === 'function') {
+      /* The registry rejects a directory that does not exist yet, and a brand-new project
+       * is exactly that, so the path is materialised first. */
+      await mkdir(cwd, { recursive: true }).catch(() => {})
+      const title = typeof options.title === 'string' && options.title.trim() !== '' ? options.title.trim() : undefined
+      workspace = await registry.create(cwd, title)
+    } else {
+      workspace = await registry.resolveByPath?.(cwd)
+    }
+
+    await workspace?.attachSession?.(sessionId)
+    return workspace === undefined || workspace === null
+      ? undefined
+      : { id: workspace.id, title: workspace.title, path: workspace.path }
+  } catch {
+    /* Grouping is cosmetic: a failure here must not fail the dispatch. */
+    return undefined
+  }
+}
+
+
+/**
+ * Restore the worker registry written by a previous process.
+ * @param settings - resolved settings.
+ * @param state - worker bookkeeping to fill.
+ */
+
+export function finalAnswer(ctx, sessionId, sinceSeq, settings) {
+  const session = ctx.get('sessions')?.get?.(sessionId)
+  if (session === undefined || session === null) return { text: '', truncated: false }
+  let last = ''
+  for (const event of session.snapshotEvents()) {
+    if (Number(event.seq) <= sinceSeq) continue
+    if (event.type !== 'assistant/message') continue
+    const blocks = Array.isArray(event.data?.message?.content) ? event.data.message.content : []
+    const value = blocks
+      .filter((block) => block?.type === 'text' && typeof block.text === 'string')
+      .map((block) => block.text)
+      .join('\n')
+      .trim()
+    if (value !== '') last = value
+  }
+  if (last.length <= settings.maxResultChars) return { text: last, truncated: false }
+  /* Keep the head: a conclusion states its verdict first. */
+  return { text: `${last.slice(0, settings.maxResultChars)}\n\n…`, truncated: true }
+}
+
+/**
+ * Describe one worker the way `wait_agent` does: a string state, or its final answer.
+ * @param ctx - Host context.
+ * @param sessionId - worker session.
+ * @param state - dispatch bookkeeping.
+ * @param settings - resolved settings.
+ * @returns 'not_found' | 'running' | 'pending' | { completed } | { errored }.
+ */
+
+export function workerStatus(ctx, sessionId, state, settings) {
+  if (!state.dispatched.has(sessionId)) return 'not_found'
+  let record
+  for (const candidate of state.workers.values()) {
+    if (candidate.sessionId === sessionId) record = candidate
+  }
+  if (record?.status === 'closed') return 'closed'
+  const session = ctx.get('sessions')?.get?.(sessionId)
+  if (session === undefined || session === null) {
+    /* After a restart the session is cold; a cached terminal outcome is still valid. */
+    if (record?.outcome !== undefined) return record.outcome
+    return 'offline'
+  }
+  if (ctx.get('agents')?.get?.(sessionId)?.status === 'running') return 'running'
+  const since = Number(state.baseline.get(sessionId) ?? 0)
+  const end = lastTurnEnd(session, since)
+  if (end === undefined) return 'pending'
+  const reason = end.reason?.kind ?? 'unknown'
+  if (reason !== 'completed') return { errored: String(reason) }
+  const answer = finalAnswer(ctx, sessionId, since, settings)
+  return { completed: answer.text }
+}
+
+/**
+ * Latest `turn/end` after a sequence, with its reason.
+ * @param session - live session.
+ * @param sinceSeq - only consider turns that ended after this event.
+ * @returns the payload, or undefined when the turn has not ended yet.
+ */
+
+export function lastTurnEnd(session, sinceSeq) {
+  let found
+  for (const event of session.snapshotEvents()) {
+    if (Number(event.seq) <= sinceSeq) continue
+    if (event.type === 'turn/end') found = event.data
+  }
+  return found
+}
+
+/**
+ * Read one session snapshot without waiting.
+ * @param ctx - Host context.
+ * @param sessionId - session to read.
+ * @param sinceSeq - only count assistant messages after this sequence.
+ * @param settings - resolved settings.
+ * @returns text, run state, and the session head sequence.
+ */
+
+export function readOnce(ctx, sessionId, sinceSeq, settings) {
+  const session = ctx.get('sessions')?.get?.(sessionId)
+  if (session === undefined || session === null) throw new Error(`session ${sessionId} is not live`)
+  const collected = collectAssistant(ctx, sessionId, sinceSeq, settings)
+  return {
+    sessionId,
+    running: ctx.get('agents')?.get?.(sessionId)?.status === 'running',
+    lastSeq: Number(session.seq ?? 0),
+    truncated: collected.truncated,
+    text: collected.text,
+  }
+}
+
+/**
+ * Resolve the directory Codex should run in.
+ * @param ctx - Host context.
+ * @param requested - explicit `cwd` argument.
+ * @param exec - tool run context.
+ * @returns the absolute directory.
+ */
+
+export async function resolveCwd(ctx, requested, exec) {
+  if (typeof requested === 'string' && requested !== '') return requested
+  const session = exec?.agent === undefined ? undefined : ctx.get('sessions')?.get?.(exec.agent.id)
+  const working = ctx.get('workingDirectory')
+  if (session !== undefined && session !== null && working !== undefined) {
+    try {
+      return working.get(session) ?? process.cwd()
+    } catch {
+      /* Fall through to the process directory. */
+    }
+  }
+  return process.cwd()
+}
+
+/**
+ * Run one `codex exec` and collect its answer.
+ * @param options - binary, prompt, directory, sandbox, timeout, and cancellation.
+ * @returns `{ ok, text, threadId, exitCode, durationMs, error? }`.
+ */
+
+export function safeTitle(service, session) {
+  try {
+    const snapshot = service?.get?.(session)
+    return typeof snapshot?.title === 'string' && snapshot.title !== '' ? snapshot.title : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Accept a request only when it carries the capability token in the path or as a bearer.
+ * @param request - node request.
+ * @param url - parsed request URL.
+ * @param token - expected token.
+ * @returns whether the request may proceed.
+ */