pantheon-opencode 1.5.0-beta.2 → 1.5.0-beta.20

package/src/pantheon/cost-command.ts

@@ -4,11 +4,8 @@
  *
  * Reads the opencode session database READ-ONLY (sum tokens by agent and
  * phase over the last N days → markdown table). Zero new dependencies:
- *   - primary path: node:sqlite (DatabaseSync, readOnly) — node ≥ 22.5;
- *   - CLI fallback: spawn scripts/cost.mjs with its explicit flag-based
- *     interface when the direct import is unavailable;
- *   - missing/unreadable db → FRIENDLY error string, never a crash (tools
- *     return errors as TEXT).
+ *   - only path: node:sqlite (DatabaseSync, readOnly) — node ≥ 22.5;
+ *   - missing/unreadable db → a diagnostic contract status as TEXT.
  *
  * dbPath resolution: explicit option > env PANTHEON_COST_DB > the version-aware
  * default selected by PANTHEON_OPENCODE_VERSION (v1 or v2). An unset version
@@ -19,15 +16,16 @@
  * @module cost-command
  */
 import { execFile } from 'node:child_process'
-import { existsSync } from 'node:fs'
+import { accessSync, constants, existsSync, statSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { join } from 'node:path'
-import { promisify } from 'node:util'
+import { delimiter, dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { z } from 'zod'
+import type { NativeTaskStatus } from './native-task-status.ts'
+import type { ToolContextLike } from './tool-context.ts'
 
-import type { ToolContextLike } from './delegation.ts'
-
-const execFileAsync = promisify(execFile)
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
 
 /** One aggregated token row (per agent and phase). */
 export interface CostRow {
@@ -41,10 +39,23 @@ export interface CostRow {
 export interface CostCommandOptions {
   /** Explicit db path (testability / unusual installs). Default: resolved candidates. */
   dbPath?: string
+  /** Injectable loader for tests; production always loads node:sqlite. */
+  sqliteLoader?: () => Promise<SqliteModule>
+  /** Injectable CLI-fallback process boundary (tests / unusual runtimes). */
+  cliFallback?: CliFallbackDeps
 }
 
 export type OpenCodeVersion = 'v1' | 'v2'
 
+interface SqliteDatabase {
+  prepare(sql: string): { get(): unknown; all(...args: unknown[]): unknown[] }
+  close(): void
+}
+
+export interface SqliteModule {
+  DatabaseSync: new (path: string, options: { readOnly: boolean }) => SqliteDatabase
+}
+
 /** One cost tool: description + zod args shape + execute (delegation.ts shape). */
 export interface CostTool<Args extends z.ZodRawShape = typeof costArgs> {
   description: string
@@ -125,8 +136,11 @@ function assertCompatibleSchema(db: {
 }
 
 /** Aggregate tokens by agent and phase via node:sqlite (read-only). */
-async function queryWithNodeSqlite(dbPath: string, days: number): Promise<CostRow[]> {
-  const sqlite = await import('node:sqlite')
+async function queryWithNodeSqlite(
+  dbPath: string,
+  days: number,
+  sqlite: SqliteModule,
+): Promise<CostRow[]> {
   const db = new sqlite.DatabaseSync(dbPath, { readOnly: true })
   try {
     assertCompatibleSchema(db)
@@ -142,25 +156,6 @@ async function queryWithNodeSqlite(dbPath: string, days: number): Promise<CostRo
   }
 }
 
-/** CLI fallback: delegate the same aggregation to scripts/cost.mjs. */
-async function queryWithScript(
-  scriptPath: string,
-  dbPath: string,
-  days: number,
-): Promise<CostRow[]> {
-  const { stdout } = await execFileAsync(
-    process.execPath,
-    [scriptPath, '--db-path', dbPath, '--days', String(days)],
-    {
-      timeout: 15_000,
-      encoding: 'utf8',
-    },
-  )
-  const parsed = JSON.parse(stdout) as { ok: boolean; rows?: CostRow[]; error?: string }
-  if (!parsed.ok) throw new Error(parsed.error ?? 'cost.mjs failed')
-  return parsed.rows ?? []
-}
-
 /** Parse message.data JSON rows and aggregate tokens by assistant agent/phase. */
 function aggregateMessages(dataValues: readonly string[]): CostRow[] {
   const byAgentAndPhase = new Map<string, CostRow>()
@@ -231,8 +226,267 @@ function renderMarkdown(rows: readonly CostRow[], days: number): string {
   return lines.join('\n')
 }
 
+// ─── CLI fallback: resolve a REAL Node, not the plugin runtime ──────────
+//
+// Under Bun (the runtime that motivates this fallback), process.execPath IS
+// the Bun binary, which has no node:sqlite — so spawning it could never work.
+// Resolve a genuine Node instead: PANTHEON_NODE → `node` on PATH → clear error.
+
+/** First Node release exposing the built-in `node:sqlite` module. */
+const NODE_SQLITE_MIN_VERSION = '22.5'
+
+/** Minimal injectable child-process boundary (tests / unusual runtimes). */
+export type ExecFileLike = (
+  file: string,
+  args: readonly string[],
+) => Promise<{ stdout: string; stderr?: string }>
+
+/** Injectables so the fallback never depends on the real machine in tests. */
+export interface CliFallbackDeps {
+  /** Environment for PANTHEON_NODE / PATH lookup. Default: process.env. */
+  env?: NodeJS.ProcessEnv
+  /** Child-process boundary. Default: node:child_process.execFile. */
+  execFile?: ExecFileLike
+  /** Executable predicate used by the PANTHEON_NODE / PATH lookups. */
+  isExecutable?: (path: string) => boolean
+}
+
+/** A real Node executable located for the CLI fallback. */
+export interface ResolvedNode {
+  path: string
+  source: 'env' | 'path'
+}
+
+type ExecFailure = Error & { stdout?: string; stderr?: string }
+
+function defaultIsExecutable(path: string): boolean {
+  try {
+    accessSync(path, constants.X_OK)
+    return statSync(path).isFile()
+  } catch {
+    return false
+  }
+}
+
+function defaultExecFile(
+  file: string,
+  args: readonly string[],
+): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    execFile(file, [...args], { encoding: 'utf8' }, (error, stdout, stderr) => {
+      if (error) {
+        // execFile's callback error does not always carry the captured output;
+        // attach it so callers can surface cost.mjs's structured {ok:false}.
+        const failure = error as ExecFailure
+        if (typeof failure.stdout !== 'string') failure.stdout = stdout
+        if (typeof failure.stderr !== 'string') failure.stderr = stderr
+        reject(failure)
+        return
+      }
+      resolve({ stdout, stderr })
+    })
+  })
+}
+
+/** Scan PATH (no shell) for a `node` executable. */
+export function resolveNodeFromPath(
+  env: NodeJS.ProcessEnv,
+  isExecutable: (path: string) => boolean = defaultIsExecutable,
+): string | undefined {
+  const pathValue = env.PATH ?? env.Path ?? ''
+  if (pathValue === '') return undefined
+  const isWindows = process.platform === 'win32'
+  const extensions = isWindows
+    ? (env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM').split(';').filter((ext) => ext !== '')
+    : ['']
+  for (const dir of pathValue.split(delimiter)) {
+    if (dir === '') continue
+    for (const ext of extensions) {
+      const candidate = join(dir, `node${ext}`)
+      if (isExecutable(candidate)) return candidate
+    }
+  }
+  return undefined
+}
+
+/**
+ * Resolve a REAL Node.js binary for the CLI fallback.
+ *
+ * Order: PANTHEON_NODE (must exist and be executable — an explicit override
+ * that is unusable fails fast instead of being silently ignored) → `node`
+ * from PATH. Returns undefined only when neither source is available.
+ */
+export function resolveNodeExecutable(
+  env: NodeJS.ProcessEnv = process.env,
+  isExecutable: (path: string) => boolean = defaultIsExecutable,
+): ResolvedNode | undefined {
+  const explicit = env.PANTHEON_NODE
+  if (explicit !== undefined && explicit.trim() !== '') {
+    if (isExecutable(explicit)) return { path: explicit, source: 'env' }
+    throw new Error(
+      `PANTHEON_NODE is set to "${explicit}" but that is not an existing executable file`,
+    )
+  }
+  const fromPath = resolveNodeFromPath(env, isExecutable)
+  return fromPath === undefined ? undefined : { path: fromPath, source: 'path' }
+}
+
+function execErrorMessage(err: unknown): string {
+  if (err instanceof Error) {
+    const failure = err as ExecFailure
+    const stderr = typeof failure.stderr === 'string' ? failure.stderr.trim() : ''
+    if (stderr !== '') return stderr
+    return failure.message
+  }
+  return String(err)
+}
+
+function tryParseJson(text: string): unknown {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  }
+}
+
+function truncateForError(text: string): string {
+  const trimmed = text.trim()
+  return trimmed.length > 200 ? `${trimmed.slice(0, 200)}…` : trimmed
+}
+
+/** Probe the resolved binary for built-in node:sqlite support. */
+async function assertNodeSqliteSupport(
+  nodePath: string,
+  execFileAsync: ExecFileLike,
+): Promise<void> {
+  try {
+    await execFileAsync(nodePath, ['-e', "require('node:sqlite')"])
+  } catch (err: unknown) {
+    throw new Error(
+      `resolved Node binary "${nodePath}" does not support node:sqlite (Node.js >= ${NODE_SQLITE_MIN_VERSION} required): ${execErrorMessage(err)}`,
+    )
+  }
+}
+
+/** Pull the structured failure message cost.mjs prints to stdout (exit 1). */
+function extractScriptFailure(err: unknown): string {
+  const failure = err as { stdout?: unknown; stderr?: unknown }
+  const stdout = typeof failure.stdout === 'string' ? failure.stdout : ''
+  const parsed = tryParseJson(stdout)
+  if (parsed !== null && typeof parsed === 'object') {
+    const record = parsed as { ok?: unknown; error?: unknown }
+    if (record.ok === false && typeof record.error === 'string' && record.error !== '') {
+      return record.error
+    }
+  }
+  const stderr = typeof failure.stderr === 'string' ? failure.stderr.trim() : ''
+  if (stderr !== '') return stderr
+  return execErrorMessage(err)
+}
+
+/**
+ * Spawn `node scripts/cost.mjs` as a CLI fallback when node:sqlite is
+ * unavailable in the plugin process (e.g. Bun runtime). Returns CostRow[] by
+ * parsing the JSON the script writes to stdout.
+ *
+ * Resolves a REAL Node binary (PANTHEON_NODE → PATH): process.execPath under
+ * Bun is the Bun binary, which cannot run node:sqlite. The resolved binary is
+ * probed for node:sqlite support and the script is always run read-only with
+ * an argument array (never a shell).
+ */
+export async function queryWithCliFallback(
+  dbPath: string,
+  days: number,
+  deps?: CliFallbackDeps,
+): Promise<CostRow[]> {
+  const env = deps?.env ?? process.env
+  const execFileAsync = deps?.execFile ?? defaultExecFile
+  const isExecutable = deps?.isExecutable ?? defaultIsExecutable
+
+  const costScript = join(__dirname, '..', '..', 'scripts', 'cost.mjs')
+  if (!existsSync(costScript)) {
+    throw new Error(`CLI fallback script not found: ${costScript}`)
+  }
+
+  const node = resolveNodeExecutable(env, isExecutable)
+  if (node === undefined) {
+    throw new Error(
+      `no Node.js executable found for the node:sqlite CLI fallback: set PANTHEON_NODE to a Node.js >= ${NODE_SQLITE_MIN_VERSION} binary or put "node" on PATH`,
+    )
+  }
+
+  await assertNodeSqliteSupport(node.path, execFileAsync)
+
+  let stdout: string
+  try {
+    ;({ stdout } = await execFileAsync(node.path, [
+      costScript,
+      '--db-path',
+      dbPath,
+      '--days',
+      String(days),
+    ]))
+  } catch (err: unknown) {
+    // cost.mjs sets exitCode=1 (execFile rejects) and writes {ok:false,error}
+    // to stdout before exiting — surface that structured failure.
+    throw new Error(`CLI fallback failed: ${extractScriptFailure(err)}`)
+  }
+
+  const parsed = tryParseJson(stdout)
+  if (parsed === null || typeof parsed !== 'object') {
+    throw new Error(`CLI fallback returned non-JSON output: ${truncateForError(stdout)}`)
+  }
+  const record = parsed as { ok?: unknown; rows?: unknown; error?: unknown }
+  if (record.ok !== true) {
+    const detail =
+      typeof record.error === 'string' && record.error !== ''
+        ? record.error
+        : 'unexpected response shape from scripts/cost.mjs'
+    throw new Error(`CLI fallback failed: ${detail}`)
+  }
+  if (!Array.isArray(record.rows)) {
+    throw new Error('CLI fallback failed: scripts/cost.mjs response is missing the rows array')
+  }
+  return record.rows as CostRow[]
+}
+
 export function createCostCommand(options?: CostCommandOptions): CostCommand {
-  const scriptPath = new URL('../../scripts/cost.mjs', import.meta.url).pathname
+  const loadSqlite =
+    options?.sqliteLoader ?? (async () => (await import('node:sqlite')) as SqliteModule)
+
+  const failure = (status: NativeTaskStatus, detail: string): string =>
+    `status: ${status}\npantheon_cost failed: ${detail}`
+
+  const diagnostic = (err: unknown): string => {
+    if (err instanceof Error) {
+      const stderr = (err as Error & { stderr?: unknown }).stderr
+      const suffix =
+        typeof stderr === 'string' && stderr.trim() !== '' ? `; stderr: ${stderr.trim()}` : ''
+      return `${err.message}${suffix}`
+    }
+    return String(err)
+  }
+
+  const statusForError = (err: unknown): NativeTaskStatus => {
+    const detail = diagnostic(err).toLowerCase()
+    if (
+      detail.includes('not found') ||
+      detail.includes('unknown builtin') ||
+      detail.includes('no such built-in') ||
+      detail.includes('cannot find module')
+    ) {
+      return 'UNSUPPORTED'
+    }
+    if (
+      detail.includes('not a database') ||
+      detail.includes('malformed') ||
+      detail.includes('corrupt') ||
+      detail.includes('incompatible opencode.db schema')
+    ) {
+      return 'CORRUPT_DATA'
+    }
+    return 'UNAVAILABLE'
+  }
 
   const execute = async (args: { days?: number }, _ctx: ToolContextLike): Promise<string> => {
     const days = args?.days ?? 7
@@ -240,20 +494,31 @@ export function createCostCommand(options?: CostCommandOptions): CostCommand {
       const dbPath = findExistingDb(options?.dbPath)
       if (dbPath === undefined) {
         const expected = resolveCostDbPath(options)
-        return (
-          `pantheon_cost failed: opencode.db not found (expected at ${expected}). ` +
-          `No token history is available until opencode has stored session data.`
+        return failure(
+          'UNAVAILABLE',
+          `opencode.db not found (expected at ${expected}). No token history is available until opencode has stored session data.`,
         )
       }
-      const rows = await queryWithNodeSqlite(dbPath, days).catch(async (err: unknown) => {
-        if (err instanceof Error && err.message.startsWith('incompatible opencode.db schema'))
-          throw err
-        return queryWithScript(scriptPath, dbPath, days)
-      })
-      return renderMarkdown(rows, days)
+      let sqlite: SqliteModule | undefined
+      try {
+        sqlite = await loadSqlite()
+      } catch (loadErr: unknown) {
+        // node:sqlite unavailable (e.g. Bun runtime) — fall back to CLI.
+        const status = statusForError(loadErr)
+        if (status === 'UNSUPPORTED') {
+          try {
+            const rows = await queryWithCliFallback(dbPath, days, options?.cliFallback)
+            return `status: OK\n${renderMarkdown(rows, days)}`
+          } catch (cliErr: unknown) {
+            return failure(statusForError(cliErr), diagnostic(cliErr))
+          }
+        }
+        throw loadErr
+      }
+      const rows = await queryWithNodeSqlite(dbPath, days, sqlite)
+      return `status: OK\n${renderMarkdown(rows, days)}`
     } catch (err: unknown) {
-      const reason = err instanceof Error ? err.message : String(err)
-      return `pantheon_cost failed: ${reason}`
+      return failure(statusForError(err), diagnostic(err))
     }
   }
 

package/src/pantheon/delegation-enforce.ts

@@ -1,7 +1,7 @@
 /**
  * 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).
+ * were delegated as read-only (an explicit read-only flag, 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
@@ -22,8 +22,10 @@
  * fail-closed when the runtime matrix is wired: missing agent identity or
  * target metadata is denied rather than inferred.
  *
- * The registry is populated by delegation.ts at delegate time: the CHILD
- * session is registered when the delegate call is read-only.
+ * The registry is populated by the plugin's `chat.params` hook — the only
+ * place the SDK exposes the active agent: when the session's agent is
+ * read-only (apollo, gaia — routing.yml `background_delegation.read_only_agents`),
+ * the session is registered; `session.deleted` unregisters it.
  *
  * @module delegation-enforce
  */
@@ -147,7 +149,6 @@ export function isDelegationAllowed(
 function targetFromTool(tool: string, args: unknown): string | undefined {
   if (args === null || typeof args !== 'object') return undefined
   const record = args as Record<string, unknown>
-  if (tool === 'pantheon_delegate') return normalizeDelegationAgent(record.agent)
   if (tool === 'task') {
     return normalizeDelegationAgent(record.subagent_type ?? record.subagentType)
   }
@@ -236,9 +237,10 @@ export function zeusReadGuard(tool: string, args: unknown, agent: string | undef
 // ─── 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.
+ * Read-only session registry. The plugin's `chat.params` hook registers
+ * sessions whose active agent is read-only (see {@link syncReadOnlySession});
+ * the `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>()
@@ -279,6 +281,50 @@ export class ReadOnlySessionRegistry {
 /** Process-wide registry wired into the plugin. */
 export const readOnlyRegistry = new ReadOnlySessionRegistry()
 
+// ─── Read-Only Agent Policy ────────────────────────────────────────────
+
+/**
+ * Agents that must stay investigation-only. Mirrors
+ * `background_delegation.read_only_agents` in routing.yml — the parity is
+ * enforced by tests/pantheon/delegation-enforce.test.ts so the two cannot
+ * drift silently.
+ */
+export const READ_ONLY_AGENTS: ReadonlySet<string> = new Set(['apollo', 'gaia'])
+
+/**
+ * Whether an agent identity belongs to the read-only set. Identity is never
+ * inferred from prompts or tool names — only the normalized agent name counts.
+ */
+export function isReadOnlyAgent(
+  agent: unknown,
+  readOnlyAgents: ReadonlySet<string> = READ_ONLY_AGENTS,
+): boolean {
+  const normalized = normalizeDelegationAgent(agent)
+  return normalized !== undefined && readOnlyAgents.has(normalized)
+}
+
+/**
+ * Sync the read-only registry with a session's active agent. Called from the
+ * plugin's `chat.params` hook: a read-only agent registers the session;
+ * anything else (unknown/absent/non-read-only) unregisters it, which also
+ * covers an in-session agent switch. Returns whether the session is now
+ * registered.
+ */
+export function syncReadOnlySession(
+  registry: ReadOnlySessionRegistry,
+  sessionID: string,
+  agent: unknown,
+  readOnlyAgents: ReadonlySet<string> = READ_ONLY_AGENTS,
+): boolean {
+  const normalized = normalizeDelegationAgent(agent)
+  if (normalized === undefined || !readOnlyAgents.has(normalized)) {
+    registry.unregister(sessionID)
+    return false
+  }
+  registry.register(sessionID, { agent: normalized })
+  return true
+}
+
 // ─── Guard ─────────────────────────────────────────────────────────────
 
 /**
@@ -291,19 +337,18 @@ export function createEnforcementGuard(input: {
   options?: EnforcementGuardOptions
 }): ToolExecuteBeforeHandler {
   const blockedTools = input.options?.blockedTools ?? DEFAULT_BLOCKED_TOOLS
-  const prefix = input.options?.messagePrefix ?? 'pantheon_delegate guard'
+  const prefix = input.options?.messagePrefix ?? 'pantheon delegation guard'
 
   return async (hook: ToolExecuteBeforeInput, output?: ToolExecuteBeforeOutput): Promise<void> => {
-    const isDelegationTool = hook.tool === 'task' || hook.tool === 'pantheon_delegate'
+    const isDelegationTool = hook.tool === 'task'
     if (isDelegationTool && input.options?.isChildSession?.(hook.sessionID) === true) {
       throw new Error(
         `${prefix}: session ${hook.sessionID} is a child session — delegation tools are denied ` +
           'to prevent nested delegation',
       )
     }
-    // pantheon_delegate has the authoritative ToolContext.agent at execution
-    // time, so its matrix check lives in delegation.ts. The hook only has the
-    // session-scoped agent learned from chat.params for native task().
+    // The hook only has the session-scoped agent learned from chat.params,
+    // so the runtime matrix check for native task() lives here.
     if (
       hook.tool === 'task' &&
       input.options?.isRootSession !== undefined &&
@@ -336,7 +381,7 @@ export function createEnforcementGuard(input: {
         `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.`,
+        `(e.g. hermes, aphrodite) with native task() instead.`,
     )
   }
 }

package/src/pantheon/file-persistence-salvage.ts

@@ -0,0 +1,64 @@
+/**
+ * Best-effort salvage of complete top-level JSON objects from a corrupt
+ * `state.json`. The file is normally a JSON array; a torn write can leave a
+ * truncated tail (or interleaved NUL bytes). We scan for balanced `{…}`
+ * objects, parsing each independently, so every intact record survives.
+ *
+ * Extracted from file-persistence.ts to keep that module within the 300-line
+ * ceiling. Exported for tests.
+ */
+import type { BackgroundJobRecord } from './background-job-board.ts'
+
+export function salvageRecords(content: string): BackgroundJobRecord[] {
+  const records: BackgroundJobRecord[] = []
+  let depth = 0
+  let start = -1
+  let inString = false
+  let escaped = false
+
+  for (let i = 0; i < content.length; i++) {
+    const ch = content[i]
+
+    if (inString) {
+      if (escaped) {
+        escaped = false
+      } else if (ch === '\\') {
+        escaped = true
+      } else if (ch === '"') {
+        inString = false
+      }
+      continue
+    }
+
+    if (ch === '"') {
+      inString = true
+      continue
+    }
+    if (ch === '{') {
+      if (depth === 0) start = i
+      depth++
+      continue
+    }
+    if (ch === '}') {
+      if (depth > 0) depth--
+      if (depth === 0 && start >= 0) {
+        const candidate = content.slice(start, i + 1)
+        try {
+          const parsed: unknown = JSON.parse(candidate)
+          if (
+            parsed !== null &&
+            typeof parsed === 'object' &&
+            typeof (parsed as BackgroundJobRecord).taskID === 'string'
+          ) {
+            records.push(parsed as BackgroundJobRecord)
+          }
+        } catch {
+          // Incomplete/partial object — skip it, keep scanning.
+        }
+        start = -1
+      }
+    }
+  }
+
+  return records
+}