pantheon-opencode 1.3.3 → 1.3.4

package/src/pantheon/todo-enforcer.ts

@@ -13,11 +13,17 @@
  *      `userActivityQuietMs` is being driven interactively → skip;
  *   2. board-running — a session with a running background job is skipped
  *      (the parent is busy; the child session itself is never routed here);
- *   3. native-children — opencode `task(background=true)` children are NOT on
- *      our board, so `session.children()` is checked: an active child (its
- *      `time.updated` newer than `childActiveMs`) means the parent is still
- *      waiting on a native background task → skip. Throws fail open (log +
- *      inject) so version-sensitive APIs never break the enforcer;
+ *   3. children — `session.children()` is checked: a delegated child's
+ *      session ID IS its board task ID, so `board.get(child.id)` resolves
+ *      and the board state machine is authoritative — the child is active
+ *      ONLY while the job is `running`; terminal jobs (completed/error/
+ *      cancelled/reconciled) never suppress. Native children (opencode
+ *      `task(background=true)`, NOT on our board) fall back to the
+ *      `time.updated` heuristic (`childActiveMs`). The cross-ref fixes the
+ *      T6 bug: a completed delegation's frozen `time.updated` looked "still
+ *      running" for `childActiveMs` and suppressed every injection in that
+ *      window. Throws fail open (log + inject) so version-sensitive APIs
+ *      never break the enforcer;
  *   4. in-flight — one injection per idle, never concurrent;
  *   5. cooldown — exponential per-session backoff `cooldownBaseMs *
  *      2^min(failures, max)`, failures increment when an injection does not
@@ -42,6 +48,12 @@
  */
 
 import type { BackgroundJobBoard } from './background-job-board.ts'
+import { createPantheonLogger } from './logger.ts'
+
+// Silence-by-default TUI policy (pantheon-hooks L42-58): the default warn
+// fallback logs to .pantheon/logs/hooks.log; console echo is opt-in via
+// PANTHEON_HOOKS_LOG=1. `deps.logger` injection stays for tests.
+const log = createPantheonLogger({ module: 'pantheon-todo' })
 
 // ─── Constants ─────────────────────────────────────────────────────────
 
@@ -49,8 +61,7 @@ import type { BackgroundJobBoard } from './background-job-board.ts'
  * Version-controlled continuation text injected into the idle session.
  * Exported for tests and so the routing.yml comment stays in sync.
  */
-export const TODO_CONTINUATION_PROMPT =
-  'Incomplete tasks remain in your todo list. Continue working on them. Do not stop until all are done. If you believe all work is complete, critically re-examine whether the completion claim is verifiable.'
+export const TODO_CONTINUATION_PROMPT = 'Continue: pending todos remain — review and proceed.'
 
 /** Defaults matching routing.yml `todo_enforcer`. */
 export const TODO_ENFORCER_DEFAULTS = {
@@ -60,7 +71,7 @@ export const TODO_ENFORCER_DEFAULTS = {
   failureResetMs: 300000,
   /** Skip injection this long after a user message in the session. */
   userActivityQuietMs: 30000,
-  /** A native child whose `time.updated` is newer than this is still running. */
+  /** A native (non-board) child whose `time.updated` is newer than this is still running. */
   childActiveMs: 120000,
 } as const
 
@@ -140,16 +151,16 @@ export interface TodoEnforcerOptions {
   failureResetMs?: number
   /** Skip injection while a user message is more recent than this. */
   userActivityQuietMs?: number
-  /** Native child sessions newer than this are considered active/running. */
+  /** Native (non-board) child sessions newer than this are considered active/running. */
   childActiveMs?: number
   /** Injectable clock (testable), defaults to `Date.now`. */
   now?: () => number
 }
 
-/** Dependencies threaded to the enforcer (structural board — list only). */
+/** Dependencies threaded to the enforcer (structural board — list + get). */
 export interface TodoEnforcerDeps {
   client: TodoEnforcerClient
-  board: Pick<BackgroundJobBoard, 'list'>
+  board: Pick<BackgroundJobBoard, 'list' | 'get'>
   options?: TodoEnforcerOptions
   logger?: { warn: (message: string) => void }
 }
@@ -170,7 +181,7 @@ type InheritedContext = {
  */
 export class TodoEnforcer {
   private readonly client: TodoEnforcerClient
-  private readonly board: Pick<BackgroundJobBoard, 'list'>
+  private readonly board: Pick<BackgroundJobBoard, 'list' | 'get'>
   private readonly options: Required<TodoEnforcerOptions>
   private readonly warn: (message: string) => void
 
@@ -201,8 +212,7 @@ export class TodoEnforcer {
       childActiveMs: opts.childActiveMs ?? TODO_ENFORCER_DEFAULTS.childActiveMs,
       now: opts.now ?? Date.now,
     }
-    this.warn =
-      deps.logger?.warn ?? ((message: string) => console.warn(`[pantheon-todo] ${message}`))
+    this.warn = deps.logger?.warn ?? ((message: string) => log.warn(message))
   }
 
   /**
@@ -214,6 +224,25 @@ export class TodoEnforcer {
     this.lastUserMessageAt.set(sessionID, this.options.now())
   }
 
+  /**
+   * List the session's PENDING todos (not completed/cancelled) — the same
+   * incomplete filter as the idle continuation, exposed for the compaction
+   * context builder. Returns [] when the enforcer is disabled or the todo
+   * API fails (fail-open: the compaction hook must never break the
+   * session).
+   */
+  async listPendingTodos(sessionID: string): Promise<TodoLike[]> {
+    if (!this.options.enabled) return []
+    try {
+      const todos = await this.client.session.todo({ path: { id: sessionID } })
+      return todos.filter((todo) => todo.status !== 'completed' && todo.status !== 'cancelled')
+    } catch (err: unknown) {
+      const reason = err instanceof Error ? err.message : String(err)
+      this.warn(`todo list failed for session ${sessionID}: ${reason}`)
+      return []
+    }
+  }
+
   /**
    * Handle a `session.idle` event for a non-board session. Evaluates the
    * previous injection's outcome, applies the guards, and injects the
@@ -245,8 +274,10 @@ export class TodoEnforcer {
     // Guard 2: a session with a running board job is busy — skip.
     if (this.board.list(sessionID).some((job) => job.state === 'running')) return
 
-    // Guard 3: native background task() children are NOT on our board — an
-    // active child means the parent is still waiting on it, so skip.
+    // Guard 3: children — a delegated child (session ID == board task ID) is
+    // active only while its job is `running`; a native child is active while
+    // its time.updated is fresh. Either active child means the parent is
+    // still waiting on it, so skip.
     if ((await this.activeChildren(sessionID, now)) > 0) return
 
     const todos = await this.client.session.todo({ path: { id: sessionID } })
@@ -317,21 +348,29 @@ export class TodoEnforcer {
   }
 
   /**
-   * Count active native child sessions. opencode `task(background=true)`
-   * children are NOT registered on our board, so the only way to see them is
-   * `session.children()`. A child is active while its `time.updated` is newer
-   * than `childActiveMs` — a running background task keeps updating its
-   * session while streaming; a completed one freezes. Fail-open: when the
-   * children API is unavailable (older opencode / permission), log and return
-   * 0 so the enforcer still works on version-sensitive runtimes.
+   * Count active child sessions. Children fall into two classes:
+   *
+   *  - BOARD children (delegated via the toolset): the child session ID IS
+   *    the board task ID, so `board.get(child.id)` resolves. The board state
+   *    machine is authoritative — active ONLY while `state === 'running'`;
+   *    a terminal job (completed/error/cancelled/reconciled) is NOT active,
+   *    even though its `time.updated` froze at completion (the frozen
+   *    timestamp is exactly the T6 bug that made a finished delegation look
+   *    "still running" for `childActiveMs`).
+   *  - NATIVE children (opencode `task(background=true)`, NOT on our board):
+   *    `board.get(child.id)` is undefined, so the heuristic applies — active
+   *    while its `time.updated` is newer than `childActiveMs` (a running
+   *    native task keeps updating its session while streaming; a completed
+   *    one freezes).
+   *
+   * Fail-open: when the children API is unavailable (older opencode /
+   * permission), log and return 0 so the enforcer still works on
+   * version-sensitive runtimes.
    */
   private async activeChildren(sessionID: string, now: number): Promise<number> {
     try {
       const children = await this.client.session.children({ path: { id: sessionID } })
-      return children.filter((child) => {
-        const updated = child.time?.updated
-        return typeof updated === 'number' && now - updated < this.options.childActiveMs
-      }).length
+      return children.filter((child) => this.isChildActive(child, now)).length
     } catch (err: unknown) {
       const reason = err instanceof Error ? err.message : String(err)
       this.warn(`todo children check failed for session ${sessionID}: ${reason}`)
@@ -339,6 +378,19 @@ export class TodoEnforcer {
     }
   }
 
+  /**
+   * Whether a single child counts as active. Board children (the child's
+   * session ID matches a board task ID) are active only while the job is
+   * `running` — terminal board states never suppress. Native children
+   * (no board job) use the `time.updated` freshness heuristic.
+   */
+  private isChildActive(child: TodoEnforcerChild, now: number): boolean {
+    const job = this.board.get(child.id)
+    if (job !== undefined) return job.state === 'running'
+    const updated = child.time?.updated
+    return typeof updated === 'number' && now - updated < this.options.childActiveMs
+  }
+
   /**
    * Inherit the agent (or model) from the LAST assistant message so the
    * continuation runs in the same context as the session's last turn. Returns

package/src/pantheon/todo-preserve.ts

@@ -0,0 +1,295 @@
+/**
+ * Todo Preserver (release-134 Phase 3) — post-compaction todo restore.
+ *
+ * WHY: opencode 1.18.11 exposes NO todo write API (SessionTodoData.body?:
+ * never — the `/session/{id}/todo` route is GET-only), so a session's todo
+ * list cannot be restored by a direct SDK call after compaction. The model's
+ * `todowrite` tool performs a FULL replace server-side (todos.update
+ * delete+insert), so a model that re-emits a partial list right after
+ * compaction silently clobbers the pre-compaction list.
+ *
+ * HOW: three phases, all additive to the existing plugin hooks:
+ *   1. CAPTURE — `experimental.session.compacting` calls `capture(sessionID)`
+ *      (a GET of the todo list) alongside the existing context build.
+ *   2. RESTORE — the `event` hook routes `session.compacted` to
+ *      `onCompacted(sessionID)`, activating the pending snapshot. The FIRST
+ *      `todowrite` of that session within `restoreWindowMs` has its
+ *      `output.args.todos` rewritten with the EXACT captured list — no model
+ *      cooperation, zero transcript noise. Subsequent writes inside the
+ *      window are denied with a clear "retry in a moment" message so the
+ *      restored list stays stable.
+ *   3. GUARD — `beforeTodoWrite` chains with the read-only enforcement guard
+ *      on `tool.execute.before` (enforcement first, restore second).
+ *
+ * FAIL-OPEN: every step is wrapped — a capture GET failure, a missing event,
+ * a malformed hook output, or an expired snapshot degrades to a logged warn
+ * and pass-through. The ONLY deliberate throw is the restore-window denial
+ * (TodoRestoreInProgressError), and only for the exact session being
+ * restored.
+ *
+ * STATE: transient in-memory Map<sessionID, {todos, capturedAt, restored}>
+ * (no files, no KV). `snapshotTtlMs` (60s) bounds how old a snapshot may be;
+ * `restoreWindowMs` (5s) bounds interception after capture. An empty captured
+ * list stores nothing → no restore, zero noise. Snapshots are anchored on
+ * `capturedAt`: capture and the compacted event are adjacent (the session is
+ * paused mid-compaction), so one timestamp covers both the TTL and the
+ * window — a second timestamp would be YAGNI.
+ *
+ * VERSION-SENSITIVE WRITE HOOK: `tryWriteApi` attempts a direct todo write
+ * when an adapter is injected (options.tryWriteApi). SDK 1.18.11 ships no
+ * adapter (the route is GET-only) → restore goes through interception. If a
+ * future SDK exposes a write, inject an adapter built on a dynamic
+ * `await import('@opencode-ai/sdk')` probe and the preserver prefers it: a
+ * successful direct write drops the snapshot and skips interception entirely.
+ *
+ * Pure TypeScript — zero runtime deps beyond the structural client type.
+ *
+ * @module todo-preserve
+ */
+
+import { createPantheonLogger } from './logger.ts'
+import type { TodoLike } from './todo-enforcer.ts'
+
+// Silence-by-default TUI policy (pantheon-hooks L42-58): console echo is
+// opt-in via PANTHEON_HOOKS_LOG=1. `deps.logger` injection stays for tests.
+const log = createPantheonLogger({ module: 'pantheon-todo-preserve' })
+
+// ─── Constants ─────────────────────────────────────────────────────────
+
+/** How long a captured snapshot stays valid (bounds staleness). */
+export const SNAPSHOT_TTL_MS = 60_000
+
+/** Interception window after capture: only the FIRST todowrite is restored. */
+export const RESTORE_WINDOW_MS = 5_000
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/**
+ * Structural client surface — the subset of the SDK the preserver uses
+ * (mirrors TodoEnforcerClient; only the GET is needed for capture).
+ */
+export interface TodoPreserverClient {
+  session: {
+    todo(input: { path: { id: string } }): Promise<TodoLike[]>
+  }
+}
+
+/** Tunables (all optional — see the constants). */
+export interface TodoPreserverOptions {
+  snapshotTtlMs?: number
+  restoreWindowMs?: number
+  /** Injectable clock (testable), defaults to `Date.now`. */
+  now?: () => number
+  /**
+   * Version-sensitive direct-write adapter. SDK 1.18.11 exposes no todo
+   * write (SessionTodoData.body?: never) — restore happens via
+   * `tool.execute.before` interception (beforeTodoWrite). If a future SDK
+   * adds a write endpoint, inject an adapter here (e.g. built on a dynamic
+   * `await import('@opencode-ai/sdk')` probe) and the preserver prefers the
+   * direct API restore: onCompacted calls this first and, when it resolves
+   * true, drops the snapshot so interception is skipped entirely. Absence
+   * or failure falls back to interception. Never throws (wrapped).
+   */
+  tryWriteApi?: (sessionID: string, todos: TodoLike[]) => Promise<boolean>
+}
+
+/** Dependencies threaded to the preserver. */
+export interface TodoPreserverDeps {
+  client: TodoPreserverClient
+  options?: TodoPreserverOptions
+  logger?: { warn: (message: string) => void }
+}
+
+/** Input the opencode `tool.execute.before` hook passes. */
+export interface TodoWriteBeforeInput {
+  tool: string
+  sessionID: string
+  callID: string
+}
+
+/** The `tool.execute.before` output — args mutated to restore the list. */
+export interface TodoWriteBeforeOutput {
+  args?: { todos?: unknown }
+}
+
+/** A captured (full) todo list awaiting post-compaction restore. */
+interface SnapshotEntry {
+  todos: TodoLike[]
+  /** Epoch ms of the capture — anchor for both the TTL and the window. */
+  capturedAt: number
+  /** True once the FIRST todowrite was intercepted (rewrite done). */
+  restored: boolean
+}
+
+/**
+ * Thrown to deny a `todowrite` while the post-compaction restore is settling
+ * (the list was just rewritten; a competing model write would clobber it).
+ */
+export class TodoRestoreInProgressError extends Error {
+  constructor(sessionID: string) {
+    super(`todo list being restored after compaction — retry in a moment (session ${sessionID})`)
+    this.name = 'TodoRestoreInProgressError'
+  }
+}
+
+/** Resolved tunables — tryWriteApi stays `| undefined` (optional adapter). */
+interface ResolvedTodoPreserverOptions {
+  snapshotTtlMs: number
+  restoreWindowMs: number
+  now: () => number
+  tryWriteApi: TodoPreserverOptions['tryWriteApi']
+}
+
+// ─── TodoPreserver ─────────────────────────────────────────────────────
+
+/**
+ * Preserve a session's todo list across compaction by intercepting the first
+ * post-compaction `todowrite`. All public methods are best-effort — the
+ * hooks can never break the session; failures are logged and swallowed.
+ */
+export class TodoPreserver {
+  private readonly client: TodoPreserverClient
+  private readonly options: ResolvedTodoPreserverOptions
+  private readonly warn: (message: string) => void
+  private readonly snapshots = new Map<string, SnapshotEntry>()
+
+  constructor(deps: TodoPreserverDeps) {
+    this.client = deps.client
+    const opts = deps.options ?? {}
+    this.options = {
+      snapshotTtlMs: opts.snapshotTtlMs ?? SNAPSHOT_TTL_MS,
+      restoreWindowMs: opts.restoreWindowMs ?? RESTORE_WINDOW_MS,
+      now: opts.now ?? Date.now,
+      tryWriteApi: opts.tryWriteApi,
+    }
+    this.warn = deps.logger?.warn ?? ((message: string) => log.warn(message))
+  }
+
+  /**
+   * CAPTURE (wired from `experimental.session.compacting`): GET the session's
+   * full todo list and store it as the restore snapshot. An empty list
+   * stores nothing (zero noise). Never throws — a GET failure is logged and
+   * the session compacts normally.
+   */
+  async capture(sessionID: string): Promise<void> {
+    this.pruneExpired()
+    try {
+      const todos = await this.client.session.todo({ path: { id: sessionID } })
+      if (todos.length === 0) {
+        // Nothing to preserve → drop any stale entry so no restore happens.
+        this.snapshots.delete(sessionID)
+        return
+      }
+      this.snapshots.set(sessionID, {
+        todos,
+        capturedAt: this.now(),
+        restored: false,
+      })
+    } catch (err: unknown) {
+      const reason = err instanceof Error ? err.message : String(err)
+      this.warn(`todo snapshot capture failed for session ${sessionID}: ${reason}`)
+    }
+  }
+
+  /**
+   * RESTORE activation (wired from the `event` hook on `session.compacted`):
+   * mark the captured snapshot as restore-pending. Without a fresh snapshot
+   * (no capture, empty list, or expired TTL) this is a no-op — fail-open.
+   * When a direct-write adapter is injected and succeeds, the snapshot is
+   * dropped so interception never runs. Never throws.
+   */
+  async onCompacted(sessionID: string): Promise<void> {
+    try {
+      const entry = this.snapshots.get(sessionID)
+      if (entry === undefined) return
+      if (this.expired(entry)) {
+        this.snapshots.delete(sessionID)
+        return
+      }
+      if (await this.tryWriteApi(sessionID, entry.todos)) {
+        this.snapshots.delete(sessionID)
+      }
+      // Otherwise the entry stays pending: the first todowrite within the
+      // restore window is rewritten with the snapshot (beforeTodoWrite).
+    } catch (err: unknown) {
+      const reason = err instanceof Error ? err.message : String(err)
+      this.warn(`todo restore activation failed for session ${sessionID}: ${reason}`)
+    }
+  }
+
+  /**
+   * GUARD (wired on `tool.execute.before`, chained after the read-only
+   * enforcement guard): intercept `todowrite` calls for a session whose
+   * snapshot is pending. The FIRST call inside the restore window has
+   * `output.args.todos` rewritten with the exact captured list; subsequent
+   * calls inside the window throw TodoRestoreInProgressError; calls outside
+   * the window, for other sessions, or for other tools pass through
+   * untouched. Fail-open: the only throw is the intentional denial.
+   */
+  async beforeTodoWrite(input: TodoWriteBeforeInput, output: TodoWriteBeforeOutput): Promise<void> {
+    if (input.tool !== 'todowrite') return
+    const entry = this.snapshots.get(input.sessionID)
+    if (entry === undefined) return
+    try {
+      const now = this.now()
+      if (now - entry.capturedAt >= this.options.snapshotTtlMs) {
+        this.snapshots.delete(input.sessionID)
+        return
+      }
+      if (now - entry.capturedAt >= this.options.restoreWindowMs) {
+        this.snapshots.delete(input.sessionID)
+        return
+      }
+      if (entry.restored) {
+        throw new TodoRestoreInProgressError(input.sessionID)
+      }
+      if (output.args === undefined) {
+        this.warn(
+          `todo restore: hook output.args missing for session ${input.sessionID} — passing through`,
+        )
+        return
+      }
+      output.args.todos = entry.todos
+      entry.restored = true
+    } catch (err: unknown) {
+      // Rethrow ONLY the intentional denial; everything else is fail-open.
+      if (err instanceof TodoRestoreInProgressError) throw err
+      const reason = err instanceof Error ? err.message : String(err)
+      this.warn(`todo restore interception failed for session ${input.sessionID}: ${reason}`)
+    }
+  }
+
+  /**
+   * Version-sensitive direct-write attempt. Returns false (fast) when no
+   * adapter is injected — the SDK 1.18.11 reality — so restore proceeds via
+   * interception. With an adapter, a resolved true means the list is already
+   * restored server-side; a throw or false falls back to interception.
+   * Never throws.
+   */
+  async tryWriteApi(sessionID: string, todos: TodoLike[]): Promise<boolean> {
+    const write = this.options.tryWriteApi
+    if (write === undefined) return false
+    try {
+      return await write(sessionID, todos)
+    } catch (err: unknown) {
+      const reason = err instanceof Error ? err.message : String(err)
+      this.warn(`todo write API attempt failed for session ${sessionID}: ${reason}`)
+      return false
+    }
+  }
+
+  private now(): number {
+    return this.options.now()
+  }
+
+  private expired(entry: SnapshotEntry): boolean {
+    return this.now() - entry.capturedAt >= this.options.snapshotTtlMs
+  }
+
+  /** Drop expired snapshots (bounded by capture frequency — no timers). */
+  private pruneExpired(): void {
+    for (const [sessionID, entry] of this.snapshots) {
+      if (this.expired(entry)) this.snapshots.delete(sessionID)
+    }
+  }
+}