pantheon-opencode 1.3.2 → 1.3.4

package/src/pantheon/delegation-finalize.ts

@@ -0,0 +1,277 @@
+/**
+ * Delegation finalize — PULL output from a child session and persist the
+ * delegation report (markdown) + the terminal board transition.
+ *
+ * Completion is NOT pushed: the event hook observes `session.idle` on the
+ * child session, then calls `finalizeDelegation()` which pulls the child's
+ * messages via `client.session.messages()`, writes the report atomically
+ * (tmp + rename) to `.pantheon/delegations/<rootSessionID>/<alias>.md`, and
+ * moves the job to a terminal board state (persist-before-notify: the report
+ * file exists before `board.updateStatus` resolves waiters).
+ *
+ * Pure TypeScript — zero runtime dependencies beyond Node.js builtins and the
+ * BackgroundJobBoard. The client is a STRUCTURAL interface (fake-client
+ * friendly) so this module is testable standalone, without the opencode SDK.
+ *
+ * @module delegation-finalize
+ */
+
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import type { BackgroundJobBoard, BackgroundJobRecord } from './background-job-board.ts'
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** A minimal structural view of one message bundle from session.messages(). */
+export interface DelegationMessageBundle {
+  info?: { role?: string; finish?: string; error?: unknown }
+  parts?: Array<{
+    type?: string
+    text?: string
+    /** Tool name on `tool` parts — used by the activity sampler. */
+    tool?: string
+    /** Tool input on `tool` parts (opencode SDK ToolPart.metadata). */
+    metadata?: { input?: unknown }
+  }>
+}
+
+/** Minimal structural view of the opencode SDK session client we use. */
+export interface DelegationClientSession {
+  create(input: {
+    body: { parentID: string; title?: string; model?: { id: string; providerID: string } }
+  }): Promise<{ id: string }>
+  promptAsync(input: {
+    path: { id: string }
+    body: { agent: string; parts: Array<{ type: 'text'; text: string }> }
+  }): Promise<unknown>
+  messages(input: { path: { id: string } }): Promise<Array<DelegationMessageBundle>>
+}
+
+/** The client surface used by the delegation core. */
+export interface DelegationClient {
+  session: DelegationClientSession
+}
+
+/** Tunables for the delegation core (all optional — see DELEGATION_DEFAULTS). */
+export interface DelegationOptions {
+  /** Job timeout before the delegation is finalized as error/timedOut. */
+  timeoutMs?: number
+  /** Caller-side cap for pantheon_delegation_read's waitForTerminal. */
+  readTimeoutMs?: number
+  /** Base directory for delegation reports (default `.pantheon/delegations`). */
+  outputDir?: string
+  /** Explicit root-session allowlist for the depth guard. */
+  rootSessions?: ReadonlySet<string>
+  /** Custom depth-guard predicate — overrides rootSessions and the default. */
+  isRootSession?: (sessionID: string) => boolean
+  /**
+   * Agents whose delegated child sessions are registered as read-only
+   * (Phase 4 enforcement). Mirrors routing.yml
+   * background_delegation.read_only_agents. Matching is case-insensitive.
+   */
+  readOnlyAgents?: ReadonlySet<string>
+  /**
+   * Per-agent model overrides for delegated child sessions, keyed by agent
+   * name (lowercase, e.g. `apollo`). Values are opencode model IDs in
+   * `provider/model` form (e.g. `opencode/deepseek-v4-flash-free`), sourced
+   * from routing.yml agent entries. Higher priority than the active preset.
+   */
+  agentModels?: Readonly<Record<string, string>>
+  /**
+   * Env override for the active-preset resolution (see resolveActivePreset).
+   * Defaults to process.env. Primarily for tests.
+   */
+  presetEnv?: Record<string, string | undefined>
+  /** Warning sink for the no-model fallback (defaults to console). */
+  logger?: { warn?: (msg: string) => void }
+}
+
+/** Dependencies threaded to the finalize path. */
+export interface DelegationDeps {
+  board: BackgroundJobBoard
+  client: DelegationClient
+  options: DelegationOptions
+}
+
+/** Terminal transition requested by the finalize path. */
+export interface FinalizeInput {
+  state: 'completed' | 'error' | 'cancelled'
+  error?: string
+  timedOut?: boolean
+}
+
+/** Defaults matching routing.yml background_delegation (timeout_ms 900000). */
+export const DELEGATION_DEFAULTS = {
+  timeoutMs: 900_000,
+  readTimeoutMs: 900_000,
+  outputDir: '.pantheon/delegations',
+} as const
+
+// ─── Output pulling ────────────────────────────────────────────────────
+
+/** Concatenate every non-empty text part across the child's messages. */
+async function pullOutput(client: DelegationClient, childSessionID: string): Promise<string> {
+  try {
+    const bundles = await client.session.messages({ path: { id: childSessionID } })
+    const lines: string[] = []
+    for (const bundle of bundles) {
+      for (const part of bundle.parts ?? []) {
+        if (part.type === 'text' && typeof part.text === 'string' && part.text.trim() !== '') {
+          lines.push(part.text)
+        }
+      }
+    }
+    return lines.join('\n\n')
+  } catch (err: unknown) {
+    const reason = err instanceof Error ? err.message : String(err)
+    return `(failed to pull child session output: ${reason})`
+  }
+}
+
+// ─── Markdown rendering ────────────────────────────────────────────────
+
+/** Render the delegation report body. Public for tests/Phase 3 reuse. */
+export function renderDelegationMarkdown(
+  job: BackgroundJobRecord,
+  output: string,
+  opts: FinalizeInput & { at?: number },
+): string {
+  const at = opts.at ?? Date.now()
+  const lines = [
+    `# Delegation Report — ${job.alias}`,
+    '',
+    `- **Task ID**: \`${job.taskID}\``,
+    `- **Agent**: ${job.agent}`,
+    `- **Description**: ${job.description}`,
+    `- **State**: ${opts.state}`,
+    `- **Timed out**: ${opts.timedOut === true ? 'true' : 'false'}`,
+    `- **Started**: ${new Date(job.launchedAt).toISOString()}`,
+    `- **Finalized**: ${new Date(at).toISOString()}`,
+    '',
+    '## Output',
+    '',
+    output.trim() !== '' ? output : '_No output captured._',
+  ]
+  if (opts.error !== undefined) {
+    lines.push('', `**Error**: ${opts.error}`)
+  }
+  if (opts.timedOut === true) {
+    lines.push('', '[TIMEOUT REACHED]')
+  }
+  return `${lines.join('\n')}\n`
+}
+
+/** One-line result summary from the pulled output (for the board record). */
+function summarizeOutput(output: string): string {
+  const firstLine = output
+    .split('\n')
+    .map((l) => l.trim())
+    .find((l) => l !== '')
+  if (firstLine === undefined) return 'No output captured'
+  return firstLine.length > 120 ? `${firstLine.slice(0, 120)}…` : firstLine
+}
+
+// ─── Report persistence ────────────────────────────────────────────────
+
+/**
+ * Reject session IDs that could escape the delegation output directory.
+ * `parentSessionID` is embedded in the report path
+ * `<outputDir>/<parentSessionID>/<alias>.md` — `path.join` does NOT strip
+ * `..`, so a traversing ID would write outside the sandbox. Called BEFORE any
+ * path construction (F1 — path traversal hardening).
+ *
+ * @throws {Error} When the ID contains `..`, `/`, or `\`.
+ */
+export function assertSafeParentSessionID(parentSessionID: string): void {
+  if (
+    parentSessionID.includes('..') ||
+    parentSessionID.includes('/') ||
+    parentSessionID.includes('\\')
+  ) {
+    throw new Error(`Invalid parentSessionID: ${parentSessionID}`)
+  }
+}
+
+/** Atomic write (tmp + rename) of the report under <outputDir>/<parent>/<alias>.md. */
+async function writeDelegationReport(
+  outputDir: string,
+  job: BackgroundJobRecord,
+  md: string,
+): Promise<string> {
+  assertSafeParentSessionID(job.parentSessionID)
+  const dir = join(outputDir, job.parentSessionID)
+  const filePath = join(dir, `${job.alias}.md`)
+  const tmpPath = join(dir, `${job.alias}.md.tmp`)
+  await mkdir(dir, { recursive: true })
+  await writeFile(tmpPath, md, 'utf-8')
+  await rename(tmpPath, filePath)
+  return filePath
+}
+
+/** Read a previously written report; undefined when the file does not exist. */
+export async function readDelegationReport(
+  outputDir: string,
+  job: BackgroundJobRecord,
+): Promise<string | undefined> {
+  assertSafeParentSessionID(job.parentSessionID)
+  const filePath = join(outputDir, job.parentSessionID, `${job.alias}.md`)
+  try {
+    return await readFile(filePath, 'utf-8')
+  } catch (err: unknown) {
+    if (err instanceof Error && 'code' in err && (err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return undefined
+    }
+    throw err
+  }
+}
+
+// ─── Finalize ──────────────────────────────────────────────────────────
+
+/**
+ * Finalize a delegation for a child session: pull output, write the report
+ * atomically, then move the board job to the requested terminal state.
+ *
+ * The board transition is guarded: only `running` → terminal, or an
+ * idempotent same-terminal re-notify, are applied. A finalize that races a
+ * timeout (already `error`) never overwrites the terminal state — the report
+ * file is still (re)written, so the marker reflects the latest observation.
+ *
+ * @returns The updated job record, or undefined when the session is unknown.
+ */
+export async function finalizeDelegation(
+  deps: DelegationDeps,
+  childSessionID: string,
+  opts: FinalizeInput,
+): Promise<BackgroundJobRecord | undefined> {
+  const job = deps.board.get(childSessionID)
+  if (!job) return undefined
+
+  const output = await pullOutput(deps.client, childSessionID)
+  const outputDir = deps.options.outputDir ?? DELEGATION_DEFAULTS.outputDir
+  await writeDelegationReport(outputDir, job, renderDelegationMarkdown(job, output, opts))
+
+  const status: {
+    taskID: string
+    state: 'completed' | 'error' | 'cancelled'
+    error?: string
+    timedOut?: boolean
+    resultSummary?: string
+  } = {
+    taskID: childSessionID,
+    state: opts.state,
+    resultSummary: summarizeOutput(output),
+  }
+  if (opts.error !== undefined) status.error = opts.error
+  if (opts.timedOut !== undefined) status.timedOut = opts.timedOut
+
+  const current = deps.board.get(childSessionID)
+  if (current !== undefined) {
+    if (current.state === 'running' || current.state === opts.state) {
+      await deps.board.updateStatus(status)
+    }
+    // Terminal in a DIFFERENT state (e.g. timeout already recorded) — the
+    // report above still captures this finalize; the board state stands.
+  }
+  return deps.board.get(childSessionID) ?? job
+}

package/src/pantheon/delegation-notify.ts

@@ -0,0 +1,100 @@
+/**
+ * Delegation event wiring — observe background-job lifecycle events and
+ * route them to finalize. This module is the `event`-hook complement of the
+ * board: `session.idle`/`session.error` on a child session that is a board
+ * job → `finalizeDelegation` (Phase 2), which transitions the board and
+ * fires `onTerminal`.
+ *
+ * NOT a notification channel. The user policy is ZERO delegation
+ * notifications in the chat transcript — no `<task-notification>` block is
+ * ever injected into a `chat.message` output, and no queued delivery path
+ * exists. Completion visibility lives in the legitimate channels only:
+ * the board `[unread]` marker (`pantheon_delegation_list`),
+ * `pantheon_delegation_read`, TUI toasts (pantheon-hooks, PANTHEON_TOASTS
+ * gate), and compaction carry-forward. The plugin's `onTerminal` listener
+ * writes a file-only log line for the on-disk audit trail.
+ *
+ * `handleDelegationEvent` wires the `event` hook: `session.idle`/`session.error`
+ * on a child session that is a board job → `finalizeDelegation` (Phase 2),
+ * which transitions the board and fires `onTerminal`. Finalize never notifies
+ * directly, and `markReconciled` does not re-fire onTerminal (reconcile is an
+ * acknowledgment, not a completion), so every job gets exactly ONE terminal
+ * transition — never a reconciled echo. Unknown sessions are ignored.
+ *
+ * Pure TypeScript — zero runtime dependencies beyond the board types.
+ *
+ * Follow-up (Themis review, Phase 5): `extractErrorMessage` handles the two
+ * observed `session.error` error shapes (string, { message }). The opencode SDK
+ * MAY expose other shapes (e.g. Error-like with non-string `message`) — if a
+ * real session.error ever carries one, the extraction degrades to the generic
+ * "session error" label. No code change: there is no evidence any other shape
+ * occurs in practice; revisit if a session.error shows an unexpected payload.
+ *
+ * @module delegation-notify
+ */
+
+import type { BackgroundJobRecord } from './background-job-board.ts'
+import type { FinalizeInput } from './delegation-finalize.ts'
+
+export type { FinalizeInput } from './delegation-finalize.ts'
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Structural view of the event payload the `event` hook receives. */
+export interface DelegationEventLike {
+  type?: string
+  properties?: Record<string, unknown>
+}
+
+/** Dependencies threaded to handleDelegationEvent (board lookup + finalize). */
+export interface DelegationEventDeps {
+  /** Look up a board job by session ID (child session IDs are task IDs). */
+  board: { get(taskID: string): BackgroundJobRecord | undefined }
+  /** Bound Phase 2 finalize — clears the timeout timer + writes the report. */
+  finalize: (childSessionID: string, opts: FinalizeInput) => Promise<unknown>
+}
+
+// ─── Event → finalize wiring ───────────────────────────────────────────
+
+function extractErrorMessage(error: unknown): string {
+  if (typeof error === 'string' && error.trim() !== '') return error
+  if (error && typeof error === 'object' && 'message' in error) {
+    const message = (error as { message: unknown }).message
+    if (typeof message === 'string' && message.trim() !== '') return message
+  }
+  return 'session error'
+}
+
+/**
+ * Handle a lifecycle event for background delegations:
+ *  - `session.idle` on a board job → finalize as completed;
+ *  - `session.error` on a board job → finalize as error (message extracted);
+ *  - any other event, a missing session ID, or an unknown session → no-op.
+ *
+ * Finalize transitions the board, which fires `onTerminal` (the plugin's
+ * file-only audit log — no chat delivery; see module header). The board's
+ * same-terminal idempotency makes repeated idles harmless (finalize rewrites
+ * the report but never transitions a terminal job to a different state).
+ *
+ * @returns True when the event named a board job (handled).
+ */
+export async function handleDelegationEvent(
+  ev: DelegationEventLike,
+  deps: DelegationEventDeps,
+): Promise<boolean> {
+  const type = ev?.type
+  if (type !== 'session.idle' && type !== 'session.error') return false
+  const sessionID = ev.properties?.sessionID
+  if (typeof sessionID !== 'string' || sessionID === '') return false
+  if (deps.board.get(sessionID) === undefined) return false
+
+  if (type === 'session.idle') {
+    await deps.finalize(sessionID, { state: 'completed' })
+  } else {
+    await deps.finalize(sessionID, {
+      state: 'error',
+      error: extractErrorMessage(ev.properties?.error),
+    })
+  }
+  return true
+}