pantheon-opencode 1.4.3 → 1.5.0-beta.10

package/src/pantheon/provider-stream-tracker.ts

@@ -0,0 +1,182 @@
+/**
+ * Pure provider stream usage tracker.
+ *
+ * The tracker stores only complete exact provider snapshots. It has no timers,
+ * polling, persistence, TUI dependency, provider client, credential fallback,
+ * token/cost estimation, or compaction/FSM integration.
+ *
+ * @module provider-stream-tracker
+ */
+
+import {
+  type ProviderUsageEvent,
+  type ProviderUsageSnapshot,
+  USAGE_STATUS,
+  type UsageStatus,
+  validateProviderUsageEvent,
+} from './provider-capabilities.ts'
+
+export type TrackerUpdateReason = 'PUBLISHED' | 'DUPLICATE' | 'STALE' | 'OUT_OF_SCOPE' | 'INVALID'
+
+export interface ProviderStreamTrackerOptions {
+  /** Optional exact stream scope. Events from another stream are unsupported. */
+  sessionId?: string
+  providerId?: string
+  modelId?: string
+  /** Injectable sink called only after a complete snapshot is stored. */
+  onSnapshot?: (snapshot: ProviderUsageSnapshot) => void
+}
+
+export interface ProviderStreamTrackerResult {
+  status: UsageStatus
+  published: boolean
+  reason: TrackerUpdateReason
+  snapshot?: ProviderUsageSnapshot
+}
+
+export interface ProviderStreamTracker {
+  /** Ingest one raw event without coercion or heuristic recovery. */
+  ingest(input: unknown): ProviderStreamTrackerResult
+  /** Read one complete snapshot for an isolated session/provider/model stream. */
+  getSnapshot(
+    sessionId: string,
+    providerId: string,
+    modelId: string,
+  ): ProviderUsageSnapshot | undefined
+  /** Read all complete snapshots, each isolated by stream identity. */
+  snapshots(): ProviderUsageSnapshot[]
+  /** Remove all in-memory stream state. */
+  clear(): void
+}
+
+interface StreamState {
+  snapshot: ProviderUsageSnapshot
+  eventIds: Set<string>
+  partIds: Set<string>
+  orderKind?: 'sequence' | 'observedAt'
+  orderValue?: number
+}
+
+function streamKey(sessionId: string, providerId: string, modelId: string): string {
+  return JSON.stringify([sessionId, providerId, modelId])
+}
+
+function copySnapshot(snapshot: ProviderUsageSnapshot): ProviderUsageSnapshot {
+  const copy: ProviderUsageSnapshot = {
+    eventId: snapshot.eventId,
+    partId: snapshot.partId,
+    sessionId: snapshot.sessionId,
+    providerId: snapshot.providerId,
+    modelId: snapshot.modelId,
+    usage: { ...snapshot.usage },
+    limit: { ...snapshot.limit },
+  }
+  if (snapshot.resetAt !== undefined) copy.resetAt = snapshot.resetAt
+  if (snapshot.sequence !== undefined) copy.sequence = snapshot.sequence
+  if (snapshot.observedAt !== undefined) copy.observedAt = snapshot.observedAt
+  return copy
+}
+
+function result(
+  status: UsageStatus,
+  reason: TrackerUpdateReason,
+  snapshot?: ProviderUsageSnapshot,
+): ProviderStreamTrackerResult {
+  return snapshot === undefined
+    ? { status, published: false, reason }
+    : { status, published: true, reason, snapshot: copySnapshot(snapshot) }
+}
+
+function isInScope(event: ProviderUsageEvent, options: ProviderStreamTrackerOptions): boolean {
+  return (
+    (options.sessionId === undefined || options.sessionId === event.sessionId) &&
+    (options.providerId === undefined || options.providerId === event.providerId) &&
+    (options.modelId === undefined || options.modelId === event.modelId)
+  )
+}
+
+function isStale(event: ProviderUsageEvent, state: StreamState): boolean {
+  if (event.sequence !== undefined) {
+    if (state.orderKind === 'sequence' && state.orderValue !== undefined) {
+      return event.sequence <= state.orderValue
+    }
+    return false
+  }
+
+  if (event.observedAt !== undefined) {
+    if (state.orderKind === 'observedAt' && state.orderValue !== undefined) {
+      return event.observedAt <= state.orderValue
+    }
+    return state.orderKind === 'sequence'
+  }
+
+  return state.orderKind !== undefined
+}
+
+function updateOrder(event: ProviderUsageEvent, state: StreamState): void {
+  if (event.sequence !== undefined) {
+    state.orderKind = 'sequence'
+    state.orderValue = event.sequence
+  } else if (event.observedAt !== undefined) {
+    state.orderKind = 'observedAt'
+    state.orderValue = event.observedAt
+  }
+}
+
+/**
+ * Create an in-memory tracker. With no scope options, multiple streams are
+ * tracked independently by their session/provider/model identity.
+ */
+export function createProviderStreamTracker(
+  options: ProviderStreamTrackerOptions = {},
+): ProviderStreamTracker {
+  const streams = new Map<string, StreamState>()
+
+  return {
+    ingest(input: unknown): ProviderStreamTrackerResult {
+      const event = validateProviderUsageEvent(input)
+      if (event === null) return result(USAGE_STATUS.UNSUPPORTED, 'INVALID')
+      if (!isInScope(event, options)) return result(USAGE_STATUS.UNSUPPORTED, 'OUT_OF_SCOPE')
+
+      const key = streamKey(event.sessionId, event.providerId, event.modelId)
+      const state = streams.get(key)
+      if (state?.eventIds.has(event.eventId) || state?.partIds.has(event.partId)) {
+        return result(USAGE_STATUS.SUPPORTED, 'DUPLICATE')
+      }
+
+      if (state !== undefined && isStale(event, state)) {
+        state.eventIds.add(event.eventId)
+        state.partIds.add(event.partId)
+        return result(USAGE_STATUS.SUPPORTED, 'STALE')
+      }
+
+      const nextState: StreamState = state ?? {
+        snapshot: event,
+        eventIds: new Set<string>(),
+        partIds: new Set<string>(),
+      }
+      nextState.snapshot = event
+      nextState.eventIds.add(event.eventId)
+      nextState.partIds.add(event.partId)
+      updateOrder(event, nextState)
+      streams.set(key, nextState)
+
+      const snapshot = copySnapshot(event)
+      options.onSnapshot?.(snapshot)
+      return result(USAGE_STATUS.SUPPORTED, 'PUBLISHED', snapshot)
+    },
+
+    getSnapshot(sessionId: string, providerId: string, modelId: string) {
+      const state = streams.get(streamKey(sessionId, providerId, modelId))
+      return state === undefined ? undefined : copySnapshot(state.snapshot)
+    },
+
+    snapshots() {
+      return [...streams.values()].map((state) => copySnapshot(state.snapshot))
+    },
+
+    clear() {
+      streams.clear()
+    },
+  }
+}

package/src/pantheon/shared-board.ts

@@ -0,0 +1,37 @@
+/**
+ * Process-wide BackgroundJobBoard singleton shared by every Pantheon plugin
+ * surface (src/plugin.ts V1, src/plugins/pantheon-hooks.ts).
+ *
+ * WHY globalThis and not a module-level `const`: opencode loads each plugin
+ * TWICE from two different filesystem paths (the installed npm package AND
+ * the repo source — see src/pantheon/plugin-once.ts). Each load is a separate
+ * module instance, so a plain ESM singleton would yield TWO boards: the
+ * native-task mirror in pantheon-hooks would register jobs on one instance
+ * while the finalize path (session.idle + idle scan in plugin.ts) listens on
+ * the other, and the job would never finalize. A globalThis-anchored value is
+ * process-global by construction, deduping both module copies.
+ *
+ * The persistence file and signal dir are RELATIVE paths — the board operates
+ * against the opencode project root (the cwd of the plugin process), matching
+ * the pre-existing plugin.ts wiring exactly.
+ */
+import { BackgroundJobBoard } from './background-job-board.ts'
+import { FilePersistenceAdapter } from './file-persistence.ts'
+
+const BOARD_KEY = '__pantheonSharedBoard'
+
+/** Construction inputs mirror the original plugin.ts module-scope board. */
+const BOARD_OPTIONS = {
+  maxConcurrentPerAgent: 3,
+  signalDir: '.pantheon/deepwork/board-signals',
+} as const
+
+export function getSharedBoard(): BackgroundJobBoard {
+  const host = globalThis as { [BOARD_KEY]?: BackgroundJobBoard }
+  const existing = host[BOARD_KEY]
+  if (existing instanceof BackgroundJobBoard) return existing
+  const board = new BackgroundJobBoard(BOARD_OPTIONS)
+  board.setPersistence(new FilePersistenceAdapter('.pantheon/board/state.json'))
+  host[BOARD_KEY] = board
+  return board
+}

package/src/pantheon/step-cap.ts

@@ -0,0 +1,110 @@
+/**
+ * R4 — Per-agent step caps (max_steps).
+ *
+ * Pure library. routing.yml `agents.<name>.max_steps` gives each agent a
+ * step budget (e.g. explore: 25, reviewer: 25, oracle: 15). When an agent's
+ * step count reaches max_steps it is forced to summarize-and-stop: the
+ * delegation is either skipped with a capped summary (already at cap) or
+ * the prompt is appended with a stop instruction (cap hit mid-dispatch).
+ *
+ * The tracker is PERMANENT-PER-PROCESS: counters accumulate for the process
+ * lifetime and are intentionally NOT reset on successful delegations or
+ * session end — a per-session reset would let an agent exceed its process
+ * budget over a long session. `reset()` exists as a tested utility for
+ * tests and future explicit reset points; no production caller wires it.
+ *
+ * @module step-cap
+ */
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Default step budget when routing.yml omits max_steps for an agent. */
+export const DEFAULT_MAX_STEPS = 25
+
+// ─── Stop instruction ──────────────────────────────────────────────────
+
+/**
+ * The forced summarize-and-stop instruction injected into a prompt when an
+ * agent's step count reaches max_steps.
+ */
+export function buildStopInstruction(agent: string, maxSteps: number): string {
+  return (
+    `\n\n[STEP CAP REACHED — ${agent} at ${maxSteps} steps] ` +
+    `You have reached the maximum step budget for this delegation. ` +
+    `STOP working immediately and summarize what was accomplished (and ` +
+    `what remains, if any) as your final message. Do not start new work.`
+  )
+}
+
+/**
+ * The text returned when a delegation is skipped because the agent is
+ * already at its step cap — marks the delegation as capped and asks for a
+ * summary of prior results instead of starting new work.
+ */
+export function cappedSummary(agent: string, maxSteps: number): string {
+  return (
+    `[STEP CAP REACHED] ${agent} has reached its max_steps budget (${maxSteps}). ` +
+    `Delegation skipped — no new work was started. ` +
+    `Summarize prior results and stop.`
+  )
+}
+
+// ─── Tracker ───────────────────────────────────────────────────────────
+
+/**
+ * Per-agent step counters with a max_steps budget. Keyed by lowercase agent
+ * name (matching is case-insensitive). Agents without a configured budget
+ * are never capped.
+ */
+export class StepCapTracker {
+  private readonly steps = new Map<string, number>()
+  readonly maxStepsByAgent: Readonly<Record<string, number>>
+
+  constructor(maxStepsByAgent: Readonly<Record<string, number>> = {}) {
+    this.maxStepsByAgent = maxStepsByAgent
+  }
+
+  /** The configured budget for an agent, or undefined when uncapped. */
+  maxStepsFor(agent: string): number | undefined {
+    return this.maxStepsByAgent[agent.toLowerCase()]
+  }
+
+  /** Current step count for an agent. */
+  stepCount(agent: string): number {
+    return this.steps.get(agent.toLowerCase()) ?? 0
+  }
+
+  /** Whether the agent has reached (or exceeded) its max_steps budget. */
+  isCapped(agent: string): boolean {
+    const max = this.maxStepsFor(agent)
+    if (max === undefined) return false
+    return this.stepCount(agent) >= max
+  }
+
+  /**
+   * Record one step for an agent. Returns the new count and whether this
+   * step hit the cap (capped === true exactly when steps >= maxSteps).
+   */
+  recordStep(agent: string): {
+    steps: number
+    capped: boolean
+    maxSteps: number | undefined
+  } {
+    const key = agent.toLowerCase()
+    const max = this.maxStepsFor(agent)
+    const steps = (this.steps.get(key) ?? 0) + 1
+    this.steps.set(key, steps)
+    return { steps, capped: max !== undefined && steps >= max, maxSteps: max }
+  }
+
+  /**
+   * Reset an agent's step count.
+   *
+   * Intentionally NOT wired in production: the tracker is permanent-per-
+   * process (see module docstring) so agents cannot exceed their process
+   * budget via resets. Exists for tests and future explicit reset points.
+   */
+  reset(agent: string): void {
+    this.steps.delete(agent.toLowerCase())
+  }
+}

package/src/pantheon/task-result-guard.ts

@@ -0,0 +1,107 @@
+/**
+ * Task Result Guard — detects empty task() results from native opencode
+ * subagent calls and converts them to explicit errors.
+ *
+ * Bug context (reproduced 2026-09-10): task() native creates a child session
+ * that inherits the parent transcript. When the payload exceeds the provider's
+ * admission limit (e.g. free-tier max_outstanding_uncached_prefill_tokens=1000
+ * vs 57k incoming tokens), the stream errors with BackendAdmissionRejected.
+ * The error is NOT propagated — the child loop exits normally, the child
+ * session goes idle with zero assistant/tool output, and opencode marks the
+ * task as `completed` with empty content. The parent LLM receives an empty
+ * result and proceeds as if the task succeeded.
+ *
+ * The guard intercepts this in the `tool.execute.after` hook: when the tool
+ * is `task` and the output is empty/whitespace-only, it replaces the output
+ * with an explicit error message so the parent sees a failure, not silence.
+ *
+ * Pure TypeScript — zero runtime dependencies. Meant to be wired into the
+ * `combinedAfter` hook chain in plugin.ts alongside the sandbox and read
+ * enhancer handlers.
+ *
+ * @module task-result-guard
+ */
+
+import { createPantheonLogger } from './logger.ts'
+
+const log = createPantheonLogger({ module: 'pantheon-task-result-guard' })
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Input shape of the opencode `tool.execute.after` hook. */
+export interface TaskGuardInput {
+  tool: string
+  sessionID: string
+  callID: string
+  args: unknown
+}
+
+/** Output shape of the opencode `tool.execute.after` hook (mutable). */
+export interface TaskGuardOutput {
+  title?: string
+  output: string
+  metadata?: Record<string, unknown>
+}
+
+/** The `tool.execute.after` handler shape. */
+export type TaskResultGuardHandler = (
+  input: TaskGuardInput,
+  output: TaskGuardOutput,
+) => Promise<void>
+
+export interface TaskResultGuardOptions {
+  /** Injectable logger (defaults to the Pantheon file log). */
+  logger?: { warn: (message: string) => void }
+}
+
+// ─── Constants ─────────────────────────────────────────────────────────
+
+/**
+ * The error message injected when a task() result is empty.
+ * Matches the existing delegation-finalize.ts contract:
+ * "Child session produced no assistant or tool output".
+ */
+export const EMPTY_TASK_ERROR =
+  'ERROR: task() returned empty output — child session produced no assistant or tool output. ' +
+  'This typically means the provider rejected the request (admission control / rate limit) ' +
+  'or the child session crashed before producing any response. ' +
+  'Consider using pantheon_delegate (clean context) instead of task() for large payloads.'
+
+// ─── Implementation ────────────────────────────────────────────────────
+
+/**
+ * Whether a result carries any text content (whitespace-only counts as empty).
+ */
+function isEmptyOutput(output: unknown): boolean {
+  if (output == null) return true
+  if (typeof output !== 'string') return true
+  return output.trim() === ''
+}
+
+/**
+ * Create a task result guard handler for the `tool.execute.after` hook.
+ *
+ * When the tool is `task` and the output is empty/whitespace-only, replaces
+ * the output with an explicit error message. All other tools pass through
+ * untouched.
+ *
+ * @returns A `ToolExecuteAfterHandler`-compatible async function.
+ */
+export function createTaskResultGuard(options?: TaskResultGuardOptions): TaskResultGuardHandler {
+  const warn = options?.logger?.warn ?? ((message: string) => log.warn(message))
+
+  return async (input: TaskGuardInput, output: TaskGuardOutput): Promise<void> => {
+    // Only intercept the `task` tool — all others pass through untouched.
+    if (input.tool !== 'task') return
+
+    // Only flag truly empty results — non-empty content is the happy path.
+    if (!isEmptyOutput(output.output)) return
+
+    warn(
+      `[task-result-guard] Empty task() result detected on session ${input.sessionID} ` +
+        `(callID=${input.callID}). Replacing with explicit error.`,
+    )
+
+    output.output = EMPTY_TASK_ERROR
+  }
+}