pantheon-opencode 1.3.5-beta.60.efa533f → 1.3.6

package/src/pantheon/retry-policy.ts

@@ -0,0 +1,212 @@
+/**
+ * R1 — Per-error-type retry + provider cooldown (LiteLLM pattern).
+ *
+ * Pure library (no SDK, no I/O). When a delegation fails, the error is
+ * classified (auth | rate_limit | timeout | other), the per-error-type
+ * retry policy from routing.yml `retry_policy` is applied with exponential
+ * backoff, and provider cooldown state (routing.yml `cooldown`) is tracked
+ * in-memory: after `allowed_fails` consecutive failures a provider is
+ * skipped for `cooldown_time_seconds`; a success resets the counter.
+ *
+ * YAGNI: no usage-based routing, no Redis — a simple in-memory cooldown
+ * map plus config.
+ *
+ * @module retry-policy
+ */
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Error classes a delegation failure can be classified into. */
+export type ErrorType = 'auth' | 'rate_limit' | 'timeout' | 'other'
+
+/** Max retries per error class (routing.yml `retry_policy`). */
+export interface RetryPolicy {
+  auth: number
+  rate_limit: number
+  timeout: number
+  other: number
+}
+
+/** Provider cooldown config (routing.yml `cooldown`). */
+export interface CooldownConfig {
+  /** Consecutive failures before the provider is skipped. */
+  allowedFails: number
+  /** How long the provider stays skipped, in seconds. */
+  cooldownTimeSeconds: number
+}
+
+/** Defaults matching routing.yml `retry_policy`. */
+export const DEFAULT_RETRY_POLICY: RetryPolicy = {
+  auth: 0,
+  rate_limit: 3,
+  timeout: 2,
+  other: 1,
+}
+
+/** Defaults matching routing.yml `cooldown`. */
+export const DEFAULT_COOLDOWN: CooldownConfig = {
+  allowedFails: 3,
+  cooldownTimeSeconds: 60,
+}
+
+// ─── Error classification ──────────────────────────────────────────────
+
+const AUTH_RE = /(auth|unauthorized|401|403|api[ _-]?key|invalid credential|permission denied)/i
+const RATE_LIMIT_RE = /(rate[ _-]?limit|429|too many requests|quota|throttl)/i
+const TIMEOUT_RE = /(timeout|timed out|deadline|504|408|etimedout)/i
+
+/**
+ * Classify a thrown error into one of the four retry-policy buckets.
+ * Message-based matching (LiteLLM pattern); unknown errors → 'other'.
+ */
+export function classifyError(err: unknown): ErrorType {
+  const message = err instanceof Error ? err.message : String(err ?? '')
+  if (AUTH_RE.test(message)) return 'auth'
+  if (RATE_LIMIT_RE.test(message)) return 'rate_limit'
+  if (TIMEOUT_RE.test(message)) return 'timeout'
+  return 'other'
+}
+
+// ─── Exponential backoff ───────────────────────────────────────────────
+
+/**
+ * Exponential backoff delay for a retry attempt (0-based): base * 2^attempt,
+ * capped at maxMs. attempt 0 → base, attempt 1 → 2x base, etc.
+ */
+export function computeBackoffMs(attempt: number, baseMs = 1000, maxMs = 30_000): number {
+  const delay = baseMs * 2 ** attempt
+  return Math.min(delay, maxMs)
+}
+
+// ─── Provider cooldown tracker ─────────────────────────────────────────
+
+interface CooldownEntry {
+  fails: number
+  cooldownUntil: number
+}
+
+/**
+ * In-memory provider cooldown state. After `allowedFails` consecutive
+ * failures a provider is skipped until `cooldownUntil`; a success resets
+ * the counter. The clock is injectable for tests.
+ */
+export class ProviderCooldownTracker {
+  private readonly state = new Map<string, CooldownEntry>()
+  readonly config: CooldownConfig
+
+  constructor(config: CooldownConfig = DEFAULT_COOLDOWN) {
+    this.config = config
+  }
+
+  /** Record one failure for a provider; trips cooldown at allowedFails. */
+  recordFailure(provider: string): void {
+    const entry = this.state.get(provider) ?? { fails: 0, cooldownUntil: 0 }
+    entry.fails += 1
+    if (entry.fails >= this.config.allowedFails) {
+      entry.cooldownUntil = Date.now() + this.config.cooldownTimeSeconds * 1000
+    }
+    this.state.set(provider, entry)
+  }
+
+  /** Record a success — resets the failure counter (no spurious cooldown). */
+  recordSuccess(provider: string): void {
+    this.state.delete(provider)
+  }
+
+  /**
+   * Whether the provider is currently skipped. Expired cooldowns are
+   * cleared; entries that never tripped (cooldownUntil 0) are kept so the
+   * consecutive-failure counter survives the check.
+   */
+  isInCooldown(provider: string, now = Date.now()): boolean {
+    const entry = this.state.get(provider)
+    if (entry === undefined) return false
+    if (entry.cooldownUntil > now) return true
+    if (entry.cooldownUntil > 0) this.state.delete(provider)
+    return false
+  }
+
+  /** Remaining cooldown time in ms (0 when not in cooldown). */
+  remainingCooldownMs(provider: string, now = Date.now()): number {
+    const entry = this.state.get(provider)
+    if (entry === undefined) return 0
+    return Math.max(0, entry.cooldownUntil - now)
+  }
+
+  /** Current consecutive failure count for a provider. */
+  failCount(provider: string): number {
+    return this.state.get(provider)?.fails ?? 0
+  }
+}
+
+// ─── Retry policy engine ───────────────────────────────────────────────
+
+export type RetryDecisionReason = 'policy' | 'cooldown'
+
+export interface RetryDecision {
+  shouldRetry: boolean
+  /** Retries still available for this error class (0 when exhausted). */
+  retriesRemaining: number
+  /** Backoff delay to wait before the next attempt (ms). */
+  delayMs: number
+  /** Why the decision was made: policy budget or provider cooldown. */
+  reason: RetryDecisionReason
+}
+
+/**
+ * Combines error classification, the per-error-type retry policy, and the
+ * provider cooldown tracker into one decision point. Enforcement: when a
+ * delegation fails, call `decide(provider, err, attemptsUsed)`; when the
+ * result is content, call `recordSuccess`; when the budget is exhausted,
+ * call `recordFailure` so the cooldown can trip.
+ */
+export class RetryPolicyEngine {
+  private readonly cooldown: ProviderCooldownTracker
+  readonly policy: RetryPolicy
+  readonly backoffBaseMs: number
+
+  constructor(
+    policy: RetryPolicy = DEFAULT_RETRY_POLICY,
+    cooldown?: ProviderCooldownTracker,
+    backoffBaseMs = 1000,
+  ) {
+    this.policy = policy
+    this.backoffBaseMs = backoffBaseMs
+    this.cooldown = cooldown ?? new ProviderCooldownTracker()
+  }
+
+  /**
+   * Decide whether a failed dispatch should be retried.
+   *
+   * @param provider provider name (cooldown key, e.g. "opencode")
+   * @param err the failure (classified into auth/rate_limit/timeout/other)
+   * @param attemptsUsed retries already consumed for this dispatch
+   * @param now injectable clock (tests)
+   */
+  decide(provider: string, err: unknown, attemptsUsed: number, now = Date.now()): RetryDecision {
+    if (this.cooldown.isInCooldown(provider, now)) {
+      return { shouldRetry: false, retriesRemaining: 0, delayMs: 0, reason: 'cooldown' }
+    }
+    const type = classifyError(err)
+    const retriesRemaining = Math.max(0, this.policy[type] - attemptsUsed)
+    if (retriesRemaining <= 0) {
+      return { shouldRetry: false, retriesRemaining: 0, delayMs: 0, reason: 'policy' }
+    }
+    return {
+      shouldRetry: true,
+      retriesRemaining,
+      delayMs: computeBackoffMs(attemptsUsed, this.backoffBaseMs),
+      reason: 'policy',
+    }
+  }
+
+  /** Record a failure (feeds the cooldown tracker). */
+  recordFailure(provider: string, _err: unknown): void {
+    this.cooldown.recordFailure(provider)
+  }
+
+  /** Record a success (resets the provider's failure counter). */
+  recordSuccess(provider: string): void {
+    this.cooldown.recordSuccess(provider)
+  }
+}

package/src/pantheon/session-guard.ts

@@ -0,0 +1,48 @@
+/**
+ * Session Guard — shared server-side validation for session IDs.
+ *
+ * Opencode session IDs always start with "ses". The TUI previously forwarded
+ * the literal template placeholder "{sessionID}" (URL-encoded as "%7BsessionID%7D")
+ * into `session.children`, causing ~1.5 errors/s from the 1s safety poll.
+ * This module is the single chokepoint: every `client.session.*({path:{id}})`;
+ * call site MUST go through `safeSessionPath`/`buildChildrenPath`, which
+ * reject placeholders before they reach the server (fail-open: warn + return,
+ * never throw, never send the placeholder).
+ *
+ * Mirrors the TUI's `src/plugins/tui/src/index.tsx` contract verbatim so both
+ * sides agree on what "valid" means. The TUI file remains self-contained
+ * (dist/tui.tsx is a raw copy, no relative imports), so its local copy is kept
+ * in sync — this module is the shared source for `src/pantheon/*` and
+ * `src/plugin.ts`.
+ *
+ * @module session-guard
+ */
+
+/**
+ * Server-aligned session id validity: opencode rejects anything not starting
+ * with "ses" (SchemaError). Mirrors that exact contract — nothing stricter,
+ * nothing looser — so "{sessionID}", "%7BsessionID%7D", "", "wrk_…" never
+ * reach a path.
+ */
+export function isValidSessionId(id: unknown): id is string {
+  return typeof id === 'string' && id.startsWith('ses')
+}
+
+/**
+ * The single choke point for every `session.*({path:{id}})` call.
+ * Returns `{path:{id}}` ONLY for a server-valid id; otherwise null so the
+ * caller skips the call entirely (fail-open).
+ */
+export function safeSessionPath(id: unknown): { path: { id: string } } | null {
+  if (!isValidSessionId(id)) return null
+  return { path: { id } }
+}
+
+/**
+ * Build the `session.children` path ONLY from a validated session id.
+ * Delegates to {@link safeSessionPath} — the single choke point. Returns
+ * null for null/invalid ids so the caller skips the fetch.
+ */
+export function buildChildrenPath(id: string | null | undefined): { path: { id: string } } | null {
+  return safeSessionPath(id)
+}

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/todo-enforcer.ts

@@ -49,6 +49,7 @@
 
 import type { BackgroundJobBoard } from './background-job-board.ts'
 import { createPantheonLogger } from './logger.ts'
+import { buildChildrenPath, safeSessionPath } from './session-guard.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
@@ -233,8 +234,13 @@ export class TodoEnforcer {
    */
   async listPendingTodos(sessionID: string): Promise<TodoLike[]> {
     if (!this.options.enabled) return []
+    const path = safeSessionPath(sessionID)
+    if (!path) {
+      this.warn(`todo list skipped: invalid sessionID "${sessionID}"`)
+      return []
+    }
     try {
-      const todos = await this.client.session.todo({ path: { id: sessionID } })
+      const todos = await this.client.session.todo(path)
       return todos.filter((todo) => todo.status !== 'completed' && todo.status !== 'cancelled')
     } catch (err: unknown) {
       const reason = err instanceof Error ? err.message : String(err)
@@ -280,7 +286,12 @@ export class TodoEnforcer {
     // still waiting on it, so skip.
     if ((await this.activeChildren(sessionID, now)) > 0) return
 
-    const todos = await this.client.session.todo({ path: { id: sessionID } })
+    const path = safeSessionPath(sessionID)
+    if (!path) {
+      this.warn(`todo check skipped: invalid sessionID "${sessionID}"`)
+      return
+    }
+    const todos = await this.client.session.todo(path)
     const incomplete = todos.filter(
       (todo) => todo.status !== 'completed' && todo.status !== 'cancelled',
     ).length
@@ -328,8 +339,13 @@ export class TodoEnforcer {
     // (throwing) injection still applies the cooldown — no hot retry loop.
     this.lastInjectionAt.set(sessionID, now)
     const inherited = await this.inheritAgentOrModel(sessionID)
+    const promptPath = safeSessionPath(sessionID)
+    if (!promptPath) {
+      this.warn(`todo injection skipped: invalid sessionID "${sessionID}"`)
+      return
+    }
     await this.client.session.promptAsync({
-      path: { id: sessionID },
+      path: promptPath.path,
       body: {
         ...(inherited.agent !== undefined ? { agent: inherited.agent } : {}),
         ...(inherited.model !== undefined ? { model: inherited.model } : {}),
@@ -368,8 +384,13 @@ export class TodoEnforcer {
    * version-sensitive runtimes.
    */
   private async activeChildren(sessionID: string, now: number): Promise<number> {
+    const path = safeSessionPath(sessionID)
+    if (!path) {
+      this.warn(`children check skipped: invalid sessionID "${sessionID}"`)
+      return 0
+    }
     try {
-      const children = await this.client.session.children({ path: { id: sessionID } })
+      const children = await this.client.session.children(path)
       return children.filter((child) => this.isChildActive(child, now)).length
     } catch (err: unknown) {
       const reason = err instanceof Error ? err.message : String(err)
@@ -398,7 +419,12 @@ export class TodoEnforcer {
    * SDK then applies the session default.
    */
   private async inheritAgentOrModel(sessionID: string): Promise<InheritedContext> {
-    const messages = await this.client.session.messages({ path: { id: sessionID } })
+    const path = safeSessionPath(sessionID)
+    if (!path) {
+      this.warn(`inherit skipped: invalid sessionID "${sessionID}"`)
+      return {}
+    }
+    const messages = await this.client.session.messages(path)
     for (const msg of [...messages].reverse()) {
       const info = msg.info
       if (info === undefined || info.role !== 'assistant') continue

package/src/pantheon/todo-preserve.ts

@@ -48,6 +48,7 @@
  */
 
 import { createPantheonLogger } from './logger.ts'
+import { safeSessionPath } from './session-guard.ts'
 import type { TodoLike } from './todo-enforcer.ts'
 
 // Silence-by-default TUI policy (pantheon-hooks L42-58): console echo is
@@ -173,8 +174,13 @@ export class TodoPreserver {
    */
   async capture(sessionID: string): Promise<void> {
     this.pruneExpired()
+    const path = safeSessionPath(sessionID)
+    if (!path) {
+      this.warn(`todo snapshot capture skipped: invalid sessionID "${sessionID}"`)
+      return
+    }
     try {
-      const todos = await this.client.session.todo({ path: { id: sessionID } })
+      const todos = await this.client.session.todo(path)
       if (todos.length === 0) {
         // Nothing to preserve → drop any stale entry so no restore happens.
         this.snapshots.delete(sessionID)

package/src/pantheon/vision.ts

@@ -7,7 +7,12 @@ import { fileURLToPath } from 'node:url'
 import type { Hooks, PluginInput } from '@opencode-ai/plugin'
 import type { FilePart, Part, TextPart, UserMessage } from '@opencode-ai/sdk'
 import type { ResolvedPreset } from './presets.mjs'
-import { CAPABILITY_TABLE, hasVision, resolveActivePreset, visionBrokenOnGateway } from './presets.mjs'
+import {
+  CAPABILITY_TABLE,
+  hasVision,
+  resolveActivePreset,
+  visionBrokenOnGateway,
+} from './presets.mjs'
 
 // ─── Constants ────────────────────────────────────────────────────────────
 
@@ -136,10 +141,7 @@ export function providerIsTextOnly(providerID: string): boolean {
 }
 
 /** Return whether OpenCode's current model is known to accept image input. */
-export function modelAcceptsImages(
-  model: ModelInfo | undefined,
-  providerID?: string,
-): boolean {
+export function modelAcceptsImages(model: ModelInfo | undefined, providerID?: string): boolean {
   if (!model) {
     // Fail-closed for known text-only providers
     if (providerID && providerIsTextOnly(providerID)) return false