pantheon-opencode 1.3.2 → 1.3.3

package/src/pantheon/cost-tracker.ts

@@ -0,0 +1,108 @@
+/**
+ * Cost Tracker (Wave 4, PR #46) — JSONL cost ledger for background
+ * delegations. Every delegation that finishes (or times out) records one
+ * line; the ledger lives at `.pantheon/costs/delegations.jsonl` and gives
+ * Nyx / the /cost command a durable, human-readable cost history.
+ *
+ * record() APPENDS (appendFile + parent dir auto-create), never rewrites.
+ * A missing ledger is an EMPTY ledger — list() → [], summary() → zeros,
+ * no crash. Injectable clock not needed: timestamp is caller-provided
+ * (ISO 8601), matching the delegation toolset's timestamping style.
+ *
+ * @module cost-tracker
+ */
+import { appendFile, mkdir, readFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+/** One delegation cost event. */
+export interface CostRecord {
+  /** Board task ID (e.g. "ses_child_1" or the job alias "apo-1"). */
+  taskId: string
+  /** Session that owns the delegation — list(sessionID?) filters on this. */
+  sessionID?: string
+  /** Delegated agent name (e.g. "hermes"). */
+  agent: string
+  /** Model ID actually used (e.g. "opencode/deepseek-v4-flash"). */
+  model: string
+  tokensInput: number
+  tokensOutput: number
+  /** Cost in USD (already computed by the caller). */
+  costUsd: number
+  /** ISO 8601 timestamp of the record. */
+  timestamp: string
+}
+
+/** Aggregate across the whole ledger. */
+export interface CostSummary {
+  count: number
+  totalCostUsd: number
+  totalTokensInput: number
+  totalTokensOutput: number
+}
+
+export interface CostTrackerOptions {
+  /** Ledger path. Default: ".pantheon/costs/delegations.jsonl". */
+  filePath?: string
+}
+
+export interface CostTracker {
+  /** Append one record to the ledger (creates the parent dir on first write). */
+  record(entry: CostRecord): Promise<void>
+  /** All records, optionally filtered by sessionID. Missing file → []. */
+  list(sessionID?: string): Promise<CostRecord[]>
+  /** Aggregate totals across the whole ledger. Missing file → zeros. */
+  summary(): Promise<CostSummary>
+}
+
+/** Parse the ledger file; missing file → empty array (never throws). */
+async function readLedger(filePath: string): Promise<CostRecord[]> {
+  let raw: string
+  try {
+    raw = await readFile(filePath, 'utf8')
+  } catch {
+    return []
+  }
+  const records: CostRecord[] = []
+  for (const line of raw.split('\n')) {
+    if (line.trim() === '') continue
+    try {
+      records.push(JSON.parse(line) as CostRecord)
+    } catch {
+      // Skip malformed lines — a partial ledger never breaks the reader.
+    }
+  }
+  return records
+}
+
+export function createCostTracker(options?: CostTrackerOptions): CostTracker {
+  const filePath = options?.filePath ?? '.pantheon/costs/delegations.jsonl'
+
+  return {
+    async record(entry: CostRecord): Promise<void> {
+      await mkdir(dirname(filePath), { recursive: true })
+      await appendFile(filePath, `${JSON.stringify(entry)}\n`, 'utf8')
+    },
+
+    async list(sessionID?: string): Promise<CostRecord[]> {
+      const records = await readLedger(filePath)
+      if (sessionID === undefined) return records
+      return records.filter((r) => r.sessionID === sessionID)
+    },
+
+    async summary(): Promise<CostSummary> {
+      const records = await readLedger(filePath)
+      const summary: CostSummary = {
+        count: records.length,
+        totalCostUsd: 0,
+        totalTokensInput: 0,
+        totalTokensOutput: 0,
+      }
+      for (const r of records) {
+        summary.totalCostUsd += r.costUsd
+        summary.totalTokensInput += r.tokensInput
+        summary.totalTokensOutput += r.tokensOutput
+      }
+      return summary
+    },
+  }
+}

package/src/pantheon/delegation-compaction.ts

@@ -0,0 +1,110 @@
+/**
+ * Delegation Compaction Context (Phase 4) — build the context blocks injected
+ * by the `experimental.session.compacting` hook so a compacted session does
+ * not lose track of its in-flight background delegations.
+ *
+ * Returns a string[] (empty when there is nothing to preserve):
+ *   - "Background Delegations (running):" — every running job launched by the
+ *     session (active work is never capped): alias, agent, started ISO,
+ *     truncated prompt.
+ *   - "Background Delegations (finished, unread):" — terminal-unreconciled
+ *     jobs, newest first, capped at `maxItems` (default 10, matching
+ *     routing.yml background_delegation.max_compaction_items).
+ *
+ * Reconciled jobs are excluded — they have been read already.
+ *
+ * The block style mirrors board.formatForPrompt ("  [alias] description —
+ * STATUS") so compaction context reads consistently with the system prompt,
+ * but with the extra id/agent/started detail the compaction hook needs.
+ *
+ * @module delegation-compaction
+ */
+
+import type { BackgroundJobBoard, BackgroundJobRecord } from './background-job-board.ts'
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+export interface CompactionContextOptions {
+  /** Scope to jobs launched by this session; omit for all jobs. */
+  sessionID?: string
+  /** Cap on unread terminal jobs kept (default 10). */
+  maxItems?: number
+}
+
+/** Prompt truncation length for a context line. */
+const PROMPT_MAX_LEN = 100
+
+// ─── Formatting ────────────────────────────────────────────────────────
+
+/** Collapse whitespace and truncate a prompt to PROMPT_MAX_LEN chars. */
+function truncatePrompt(text: string): string {
+  const flat = text.trim().replace(/\s+/g, ' ')
+  if (flat.length <= PROMPT_MAX_LEN) return flat
+  return `${flat.slice(0, PROMPT_MAX_LEN)}…`
+}
+
+/** One-line terminal status label, mirroring formatForPrompt. */
+function terminalLabel(state: BackgroundJobRecord['state']): string {
+  switch (state) {
+    case 'completed':
+      return 'OK'
+    case 'error':
+      return 'ERR'
+    case 'cancelled':
+      return 'CAN'
+    default:
+      return state.toUpperCase()
+  }
+}
+
+function runningLine(job: BackgroundJobRecord): string {
+  return (
+    `  [${job.alias}] ${job.agent} — ${truncatePrompt(job.description)} — ` +
+    `RUNNING since ${new Date(job.launchedAt).toISOString()}`
+  )
+}
+
+function unreadTerminalLine(job: BackgroundJobRecord): string {
+  return (
+    `  [${job.alias}] ${job.agent} — ${truncatePrompt(job.description)} — ` +
+    `${terminalLabel(job.state)} ${new Date(job.updatedAt).toISOString()} [unread]`
+  )
+}
+
+// ─── Build ─────────────────────────────────────────────────────────────
+
+/**
+ * Build the compaction context blocks for a session's background delegations.
+ * Returns an empty array when there is nothing to preserve (caller skips the
+ * hook injection entirely).
+ */
+export function buildCompactionContext(
+  board: BackgroundJobBoard,
+  opts: CompactionContextOptions = {},
+): string[] {
+  const maxItems = opts.maxItems ?? 10
+  const jobs = opts.sessionID !== undefined ? board.list(opts.sessionID) : board.list()
+
+  const running = jobs
+    .filter((j) => j.state === 'running')
+    .sort((a, b) => a.launchedAt - b.launchedAt)
+  const unreadTerminal = jobs
+    .filter((j) => j.terminalUnreconciled)
+    .sort((a, b) => b.updatedAt - a.updatedAt)
+    .slice(0, maxItems)
+
+  if (running.length === 0 && unreadTerminal.length === 0) return []
+
+  const blocks: string[] = []
+  if (running.length > 0) {
+    blocks.push(`Background Delegations (running):\n${running.map(runningLine).join('\n')}`)
+  }
+  if (unreadTerminal.length > 0) {
+    blocks.push(
+      `Background Delegations (finished, unread):\n${unreadTerminal
+        .map(unreadTerminalLine)
+        .join('\n')}`,
+    )
+  }
+  return blocks
+}

package/src/pantheon/delegation-enforce.ts

@@ -0,0 +1,144 @@
+/**
+ * Read-Only Enforcement (Phase 4) — deny mutating tools inside sessions that
+ * were delegated as read-only (advisory `read_only: true` on
+ * pantheon_delegate, or the agent ∈ `readOnlyAgents` from routing.yml).
+ *
+ * OpenCode hook: `tool.execute.before`. The hook shape is
+ * `(input, output) => Promise<void>`; THROWING from the hook denies the tool
+ * call and the caller (the subagent session) sees the thrown message. This
+ * module never needs the opencode SDK — the handler is a structural closure
+ * wired from plugin.ts.
+ *
+ * Blocked tools (edit, write, bash, task, hashline_edit):
+ *   - edit/write/bash are the mutating surface — read-only agents (apollo,
+ *     gaia) must stay investigation-only.
+ *   - `hashline_edit` is the Wave 2 (PR #46) tag-anchored edit tool — it is a
+ *     write surface too, so read-only agents must not bypass enforcement via
+ *     it.
+ *   - `task` is blocked too, which hard-enforces depth-2: a read-only agent
+ *     cannot spawn its own subagents.
+ *
+ * Unknown sessions are ALLOWED by default — the guard only denies sessions
+ * that are explicitly registered, so normal (non-delegated) agent work is
+ * never blocked.
+ *
+ * The registry is populated by delegation.ts at delegate time: the CHILD
+ * session is registered when the delegate call is read-only.
+ *
+ * @module delegation-enforce
+ */
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Why a session is read-only. */
+export interface ReadOnlyEntry {
+  /** Agent name the session was delegated to (e.g. "apollo"). */
+  agent: string
+  /** Whether read_only was set explicitly on the delegate call. */
+  readOnlyFlag?: boolean
+  /** Epoch ms when the session was registered. */
+  registeredAt: number
+}
+
+/** Input the opencode `tool.execute.before` hook passes. */
+export interface ToolExecuteBeforeInput {
+  tool: string
+  sessionID: string
+  callID: string
+}
+
+/** The `tool.execute.before` handler shape (throw ⇒ deny). */
+export type ToolExecuteBeforeHandler = (input: ToolExecuteBeforeInput) => Promise<void>
+
+/** Options for createEnforcementGuard(). */
+export interface EnforcementGuardOptions {
+  /** Tools denied in read-only sessions (default: DEFAULT_BLOCKED_TOOLS). */
+  blockedTools?: ReadonlySet<string>
+  /** Prefix for the denial message. */
+  messagePrefix?: string
+}
+
+// ─── Defaults ──────────────────────────────────────────────────────────
+
+/** Mutating tools denied in read-only sessions. `task` ⇒ depth-2 guard. */
+export const DEFAULT_BLOCKED_TOOLS: ReadonlySet<string> = new Set([
+  'edit',
+  'write',
+  'bash',
+  'task',
+  'hashline_edit',
+])
+
+// ─── Registry ──────────────────────────────────────────────────────────
+
+/**
+ * Read-only session registry. `createDelegationTools` registers child
+ * sessions here; the plugin's `tool.execute.before` guard consults it.
+ * Process-wide singleton for plugin wiring + factory for test isolation.
+ */
+export class ReadOnlySessionRegistry {
+  private readonly sessions = new Map<string, ReadOnlyEntry>()
+
+  /** Register a session as read-only. Idempotent (re-registration updates). */
+  register(sessionID: string, entry: { agent: string; readOnlyFlag?: boolean }): void {
+    const record: ReadOnlyEntry = { agent: entry.agent, registeredAt: Date.now() }
+    if (entry.readOnlyFlag !== undefined) record.readOnlyFlag = entry.readOnlyFlag
+    this.sessions.set(sessionID, record)
+  }
+
+  /** Remove a session from the read-only set (dynamic revocation). */
+  unregister(sessionID: string): void {
+    this.sessions.delete(sessionID)
+  }
+
+  /** Whether the session is registered as read-only. */
+  has(sessionID: string): boolean {
+    return this.sessions.has(sessionID)
+  }
+
+  /** Snapshot of the registered entry, or undefined. */
+  get(sessionID: string): ReadOnlyEntry | undefined {
+    return this.sessions.get(sessionID)
+  }
+
+  /** Snapshot of all read-only session IDs (guards read a stable copy). */
+  sessionIDs(): ReadonlySet<string> {
+    return new Set(this.sessions.keys())
+  }
+
+  /** Remove every registration (test hygiene / plugin teardown). */
+  clear(): void {
+    this.sessions.clear()
+  }
+}
+
+/** Process-wide registry wired into the plugin. */
+export const readOnlyRegistry = new ReadOnlySessionRegistry()
+
+// ─── Guard ─────────────────────────────────────────────────────────────
+
+/**
+ * Build the `tool.execute.before` handler. Throws with an actionable message
+ * when a blocked tool is invoked from a registered read-only session; any
+ * other session (or tool) passes through untouched.
+ */
+export function createEnforcementGuard(input: {
+  getReadOnlySessions: () => ReadonlySet<string>
+  options?: EnforcementGuardOptions
+}): ToolExecuteBeforeHandler {
+  const blockedTools = input.options?.blockedTools ?? DEFAULT_BLOCKED_TOOLS
+  const prefix = input.options?.messagePrefix ?? 'pantheon_delegate guard'
+
+  return async (hook: ToolExecuteBeforeInput): Promise<void> => {
+    if (!blockedTools.has(hook.tool)) return
+    if (!input.getReadOnlySessions().has(hook.sessionID)) return
+
+    throw new Error(
+      `${prefix}: session ${hook.sessionID} is READ-ONLY — tool "${hook.tool}" is denied. ` +
+        `This session was delegated for investigation only (read-only agent); it cannot ` +
+        `modify files, run commands, or spawn subagents. ` +
+        `If a write result is needed, dispatch a write-capable agent ` +
+        `(e.g. hermes, aphrodite) with pantheon_delegate instead.`,
+    )
+  }
+}

package/src/pantheon/delegation-finalize.ts

@@ -0,0 +1,270 @@
+/**
+ * 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 }>
+}
+
+/** 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
+}