pantheon-opencode 1.3.3 → 1.3.4

package/src/pantheon/dispatch-guard.ts

@@ -19,6 +19,13 @@
  * @module dispatch-guard
  */
 
+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. `logger` injection stays for tests.
+const log = createPantheonLogger({ module: 'pantheon-dispatch-guard' })
+
 /** A dispatch result — the minimal shape needed to classify emptiness. */
 export interface DispatchResultLike {
   /** Text content of the result (task_result / report markdown). */
@@ -35,7 +42,7 @@ export type DispatchClassification = 'content' | 'empty-mode1' | 'empty-mode2'
 export interface DispatchGuardOptions {
   /** Enable auto-retry on empty results. Default: true. */
   retryOnEmpty?: boolean
-  /** Injectable logger (defaults to console.warn with a prefix). */
+  /** Injectable logger (defaults to the Pantheon file log, env-gated echo). */
   logger?: { warn: (message: string) => void }
 }
 
@@ -72,9 +79,7 @@ function hasTokens(result: DispatchResultLike): boolean {
 
 export function createDispatchGuard(options?: DispatchGuardOptions): DispatchGuard {
   const retryOnEmpty = options?.retryOnEmpty ?? true
-  const warn =
-    options?.logger?.warn ??
-    ((message: string) => console.warn(`[pantheon-dispatch-guard] ${message}`))
+  const warn = options?.logger?.warn ?? ((message: string) => log.warn(message))
   // Per-instance retry budget — the "cap 1" enforcement point.
   let retriesUsed = 0
 

package/src/pantheon/goal-loop.ts

@@ -19,16 +19,20 @@ import { z } from 'zod'
 import type { BackgroundJobBoard } from './background-job-board.ts'
 import type { ToolContextLike } from './delegation.ts'
 import { GoalStore } from './goal-store.ts'
+import { createPantheonLogger } from './logger.ts'
 import type { TodoEnforcerMessage } from './todo-enforcer.ts'
 
+// Silence-by-default TUI policy (pantheon-hooks L42-58): warn → hooks.log,
+// console echo opt-in via PANTHEON_HOOKS_LOG=1. `deps.logger` stays for tests.
+const log = createPantheonLogger({ module: 'pantheon-goal' })
+
 export type { Goal, GoalStatus } from './goal-store.ts'
 export { GoalStore }
 
 // ─── Constants ─────────────────────────────────────────────────────────
 
 /** Continuation text injected into idle sessions. `{objective}` is substituted. */
-export const GOAL_CONTINUATION_PROMPT =
-  "Active goal: {objective}. Continue working toward it. Do not stop until you update the goal to done. If you believe it's complete, call pantheon_goal_update with status done."
+export const GOAL_CONTINUATION_PROMPT = 'Continue goal: {objective}'
 
 /** Defaults matching routing.yml `full_auto`. */
 export const GOAL_LOOP_DEFAULTS = {
@@ -141,8 +145,7 @@ export class GoalLoop {
       maxContinuations: opts.maxContinuations ?? GOAL_LOOP_DEFAULTS.maxContinuations,
       now: opts.now ?? Date.now,
     }
-    this.warn =
-      deps.logger?.warn ?? ((message: string) => console.warn(`[pantheon-goal] ${message}`))
+    this.warn = deps.logger?.warn ?? ((message: string) => log.warn(message))
   }
 
   /** True when the session has an active (non-done) goal. Used by the idle dispatcher. */

package/src/pantheon/hashline/tool.ts

@@ -105,7 +105,8 @@ function resolveFile(
   if (isAbsolute(file)) return { ok: true, file: resolve(file) }
   const base = resolve(ctx.worktree ?? ctx.directory ?? process.cwd())
   const resolved = resolve(base, file)
-  // Prefix check with a path.sep boundary: `/tmp/x` must not match `/tmp2/x`.
+  // Prefix check with a path.sep boundary: base + sep + name must not
+  // match a sibling prefix (e.g. `/data/x` vs `/data2/x`).
   if (resolved !== base && !resolved.startsWith(base + sep)) {
     return {
       ok: false,

package/src/pantheon/logger.ts

@@ -0,0 +1,117 @@
+/**
+ * Pantheon plugin logger — silence-by-default TUI policy (shared with
+ * pantheon-hooks, see src/plugins/pantheon-hooks.ts L42-58).
+ *
+ * WHY: `console.log`/`console.error` in an opencode plugin writes to the
+ * process stdout/stderr, which the TUI renders DIRECTLY into the terminal —
+ * the user-visible "lixo" (e.g. `[Pantheon Plugin] Board terminal: ...` in
+ * the TUI footer). Every Pantheon module therefore routes its logs through
+ * this helper:
+ *
+ *   1. ALWAYS append one ISO-stamped, module-prefixed line to the
+ *      project-local `.pantheon/logs/hooks.log` (same file pantheon-hooks
+ *      uses, so the plugin trail stays auditable on disk);
+ *   2. echo to the console ONLY when `PANTHEON_HOOKS_LOG=1` (or any truthy
+ *      value — same env var pantheon-hooks uses; read at creation time).
+ *
+ * All channels are best-effort and fire-and-forget: a logging failure must
+ * never break the plugin, and an unhandled rejection could itself pollute
+ * the TUI, so writes are swallowed.
+ *
+ * Pure TypeScript — zero external deps beyond Node.js builtins (fs/path).
+ *
+ * @module logger
+ */
+
+import { appendFile, mkdir } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+export interface PantheonLoggerOptions {
+  /** Module tag prefixed to every line (e.g. 'pantheon-plugin'). */
+  module: string
+  /**
+   * Env gate for the console echo — truthy means echo in addition to the
+   * log file. Defaults to `process.env.PANTHEON_HOOKS_LOG` (read at
+   * creation), matching the pantheon-hooks policy. Injectable for tests.
+   */
+  env?: string | undefined
+  /**
+   * Project directory — the log lands at `<logDir>/.pantheon/logs/hooks.log`.
+   * Defaults to `process.cwd()` (opencode runs plugins with cwd = project,
+   * consistent with the plugin's other relative `.pantheon/...` paths).
+   */
+  logDir?: string | undefined
+}
+
+export interface PantheonLogger {
+  info(message: string, ...args: unknown[]): void
+  warn(message: string, ...args: unknown[]): void
+  error(message: string, ...args: unknown[]): void
+}
+
+const LOG_LEVELS = ['info', 'warn', 'error'] as const
+type LogLevel = (typeof LOG_LEVELS)[number]
+
+/** Console method per level — info maps to console.log (the only console touch). */
+const CONSOLE_METHODS: Record<LogLevel, 'log' | 'warn' | 'error'> = {
+  info: 'log',
+  warn: 'warn',
+  error: 'error',
+}
+
+/** Serialize a log arg — Errors to stack/message, never "[object Object]". */
+function formatArg(arg: unknown): string {
+  if (arg instanceof Error) return arg.stack ?? arg.message
+  if (typeof arg === 'string') return arg
+  try {
+    return JSON.stringify(arg)
+  } catch {
+    return String(arg)
+  }
+}
+
+/**
+ * Append one ISO-stamped line to the hooks.log. Multi-line messages are
+ * split so EVERY line carries the stamp (pantheon-hooks appendHookLog
+ * pattern). Throws only on IO failure — callers swallow.
+ */
+async function appendToLog(logPath: string, prefix: string, args: unknown[]): Promise<void> {
+  const body = [prefix, ...args.map(formatArg)].join(' ')
+  const stamp = new Date().toISOString()
+  const lines = body
+    .split('\n')
+    .map((p) => p.trim())
+    .filter((p) => p !== '')
+    .map((p) => `[${stamp}] ${p}`)
+  if (lines.length === 0) return
+  await mkdir(dirname(logPath), { recursive: true })
+  await appendFile(logPath, `${lines.join('\n')}\n`, 'utf8')
+}
+
+/**
+ * Create a module logger. Every level writes to the log file ALWAYS and
+ * echoes to the console only when the env gate is truthy. Fire-and-forget:
+ * returns void, never throws.
+ */
+export function createPantheonLogger(options: PantheonLoggerOptions): PantheonLogger {
+  const echo = (options.env ?? process.env.PANTHEON_HOOKS_LOG ?? '').trim() !== ''
+  const logPath = join(options.logDir ?? process.cwd(), '.pantheon', 'logs', 'hooks.log')
+
+  const write = (level: LogLevel, message: string, args: unknown[]): void => {
+    void appendToLog(logPath, `[${options.module}] ${message}`, args).catch(() => {
+      // Best-effort file log — never break the plugin over logging.
+    })
+    if (echo) {
+      // Opt-in debug echo (PANTHEON_HOOKS_LOG=1). Off by default: console
+      // output in a plugin renders into the opencode TUI (the pollution bug).
+      const consoleMethod = CONSOLE_METHODS[level]
+      console[consoleMethod](`[${options.module}] ${message}`, ...args)
+    }
+  }
+
+  return {
+    info: (message, ...args) => write('info', message, args),
+    warn: (message, ...args) => write('warn', message, args),
+    error: (message, ...args) => write('error', message, args),
+  }
+}

package/src/pantheon/plugin-once.ts

@@ -0,0 +1,76 @@
+/**
+ * Runtime double-registration guard for the Pantheon opencode plugins.
+ *
+ * PROBLEM (2026-08-12, live logs — duplicate toasts + duplicate task_ids in
+ * ONE process): opencode MERGES the global `~/.config/opencode/opencode.json`
+ * (which points at the INSTALLED npm package's plugin paths) with the project
+ * `opencode.json` (which points at the REPO source paths). Both list the SAME
+ * two plugins — `src/plugin.ts` and `src/plugins/pantheon-hooks.ts` — so each
+ * module is LOADED TWICE from two different filesystem paths in the same
+ * process. Each load is a separate module instance with its own module scope;
+ * the plugin factory then runs twice, registering every hook twice (duplicate
+ * toasts, duplicate delegation correlation, duplicated tool registrations).
+ *
+ * FIX: claim a stable per-plugin key on a process-global Set
+ * (`globalThis.__pantheonPluginsLoaded`). The second factory invocation sees
+ * its key already claimed and returns an empty hooks object — a no-op — so
+ * hooks register exactly once. The guard is PROCESS-global BY DESIGN: only a
+ * shared global can dedupe two separate module instances.
+ *
+ * Fail-safe: access to globalThis is wrapped — if the runtime ever lacks it
+ * (never in bun/node), the helper returns false and the plugin always runs
+ * (double registration returns, but the plugin never breaks startup).
+ *
+ * TEST ESCAPE HATCH: set PANTHEON_PLUGIN_ONCE=off to disable the guard. The
+ * multi-phase regression suites (pantheon-hooks-chat.test.mjs,
+ * plugin-log-policy.test.mjs) deliberately invoke the hooks factory once per
+ * phase in the SAME process via cache-busted imports, and the process-global
+ * guard would turn every phase after the first into a no-op. Production
+ * never sets this — the guard stays active and dedupes the npm-package +
+ * repo double load.
+ *
+ * USAGE — at the TOP of the plugin factory:
+ *
+ *   const plugin: Plugin = async (input: PluginInput) => {
+ *     if (pantheonPluginOnce('pantheon:plugin')) return {}
+ *     ... // full factory body — runs exactly once per process
+ *   }
+ *
+ * NOTE: this module is imported (never re-exported) by the plugin modules —
+ * the opencode legacy loader invokes every FUNCTION-valued export of a plugin
+ * module as a plugin factory, so helpers must live in a separate module.
+ */
+const GLOBAL_KEY = '__pantheonPluginsLoaded'
+
+/** Read (or lazily create) the shared guard Set. Null on any failure. */
+function guardSet(): Set<string> | null {
+  try {
+    const g = globalThis as Record<string, unknown>
+    if (g[GLOBAL_KEY] === undefined) {
+      g[GLOBAL_KEY] = new Set<string>()
+    }
+    const set = g[GLOBAL_KEY]
+    return set instanceof Set ? (set as Set<string>) : null
+  } catch {
+    return null // fail-open: no globalThis support — see header
+  }
+}
+
+/**
+ * Claim `key` for this process. Returns TRUE when the key was ALREADY claimed
+ * by another module instance — the caller MUST become a no-op (return an
+ * empty hooks object). Returns FALSE on the FIRST claim — the caller runs its
+ * full factory body. Fail-open: without globalThis support every call returns
+ * false, so the plugin always runs (never breaks startup).
+ */
+export function pantheonPluginOnce(key: string): boolean {
+  // Test escape hatch (see header): the multi-phase regression suites invoke
+  // the factory once per phase in one process — the dedup must not apply.
+  // Production never sets it, so the npm+repo double load stays deduped.
+  if (process.env.PANTHEON_PLUGIN_ONCE === 'off') return false
+  const set = guardSet()
+  if (set === null) return false
+  if (set.has(key)) return true
+  set.add(key)
+  return false
+}

package/src/pantheon/preemptive-compact.ts

@@ -0,0 +1,76 @@
+/**
+ * Preemptive Compaction Check (release-134 Phase 5) — dormant, ready-to-wire.
+ *
+ * WHY: the SDK 1.18.x exposes NO runtime source of context-usage percentage,
+ * so there is nothing to observe at runtime yet. This module is the pure
+ * decision core that warns the model BEFORE the context fills up — ready to
+ * be wired to a future usage source, but deliberately NOT wired today.
+ *
+ * HOW: `preemptiveCompactCheck` is a pure function: given the current usage
+ * fraction and the last fraction at which a warning was emitted, it decides
+ * whether to warn again (threshold + re-warn step) and returns the effective
+ * `lastWarnedPct`. The `enqueue` callback is INJECTED by the caller — this
+ * module stays standalone and does NOT import the shared chat-reminders
+ * buffer.
+ *
+ * YAGNI: no background timers, no polling, no plugin wiring. When (if) the
+ * SDK exposes a usage source, the caller wires it into this check.
+ *
+ * FAIL-OPEN: the whole check is wrapped — an enqueue failure returns the
+ * previous state and never throws.
+ *
+ * @module preemptive-compact
+ */
+
+// ─── Constants ─────────────────────────────────────────────────────────
+
+/** Warn when context usage reaches this fraction (78%). */
+export const PREEMPTIVE_COMPACTION_THRESHOLD = 0.78
+
+/** Re-warn only when usage rose at least this much since the last warning (5pp). */
+export const PREEMPTIVE_REWARN_STEP = 0.05
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Dependencies threaded to preemptiveCompactCheck (wired from plugin.ts). */
+export interface PreemptiveCompactDeps {
+  /** The session whose context usage is being checked. */
+  sessionID: string
+  /** Current context usage as a fraction (0..1). */
+  usagePct: number
+  /** Last fraction at which a warning was emitted (undefined = never). */
+  lastWarnedPct: number | undefined
+  /** Injectable enqueue (testable). The module stays standalone. */
+  enqueue: (text: string) => void
+}
+
+// ─── Decision ──────────────────────────────────────────────────────────
+
+/**
+ * Pure decision: should a warning be emitted at the given usage?
+ * True when usage is at/above the threshold AND either no warning was
+ * emitted yet or usage rose by at least the re-warn step since the last one.
+ */
+export function shouldWarn(usagePct: number, lastWarnedPct: number | undefined): boolean {
+  if (usagePct < PREEMPTIVE_COMPACTION_THRESHOLD) return false
+  if (lastWarnedPct === undefined) return true
+  return usagePct >= lastWarnedPct + PREEMPTIVE_REWARN_STEP
+}
+
+/**
+ * Preemptive compaction check: when a warning should fire, enqueue the
+ * reminder and return the usage fraction as the new `lastWarnedPct`.
+ * Otherwise (or on any failure) return the previous `lastWarnedPct`.
+ * NEVER throws — the hook must never break the session.
+ */
+export function preemptiveCompactCheck(deps: PreemptiveCompactDeps): number | undefined {
+  try {
+    if (!shouldWarn(deps.usagePct, deps.lastWarnedPct)) return deps.lastWarnedPct
+    deps.enqueue(
+      `context usage at ${Math.round(deps.usagePct * 100)}% — consider compacting before continuing`,
+    )
+    return deps.usagePct
+  } catch {
+    return deps.lastWarnedPct
+  }
+}

package/src/pantheon/presets.d.mts

@@ -84,6 +84,20 @@ export declare function visionBrokenOnGateway(model: string, providerID: string)
 
 export declare function loadPresetDefs(routingPath?: string): Record<string, PresetDef>
 
+export interface RoutingAgentModelsOptions {
+  routingPath?: string
+  logger?: { warn?: (msg: string) => void }
+}
+
+/**
+ * Lowercase agent → "provider/model" mapping from routing.yml's FIRST
+ * (default) preset — the static source for the delegation toolset's
+ * options.agentModels. Fail-open: missing/corrupt routing.yml → {}.
+ */
+export declare function loadRoutingAgentModels(
+  options?: RoutingAgentModelsOptions,
+): Record<string, string>
+
 export declare function resolveActivePreset(options?: ResolveOptions): ResolvedPreset | null
 
 export declare function applyActivePresetToConfig<C extends object>(
@@ -91,6 +105,23 @@ export declare function applyActivePresetToConfig<C extends object>(
   options?: ResolveOptions & { env?: Record<string, string | undefined> },
 ): ResolvedPreset | null
 
+export interface ProviderKeyOptions {
+  env?: Record<string, string | undefined>
+  routingPath?: string
+}
+
+/** Name of the env var whose value is missing for a provider, or undefined when usable. */
+export declare function missingProviderKeyEnv(
+  providerID: string,
+  options?: ProviderKeyOptions,
+): string | undefined
+
+/** Whether the provider's API key is configured (apiKeyEnv set + non-empty, or no gate). */
+export declare function providerKeyConfigured(
+  providerID: string,
+  options?: ProviderKeyOptions,
+): boolean
+
 export interface MissingApiKeyError extends Error {
   code: 'PANTHEON_MISSING_API_KEY'
   envVar: string

package/src/pantheon/presets.mjs

@@ -210,6 +210,49 @@ export function loadPresetDefs(routingPath) {
   return (routing && typeof routing === 'object' && routing.presets) || {}
 }
 
+/**
+ * Load the DEFAULT agent → model mapping from routing.yml for the delegation
+ * toolset (Fase 6 — wiring agentModels).
+ *
+ * routing.yml keeps per-agent models ONLY inside presets
+ * (`presets.<name>.agents.<agent>.model`) — the top-level `agents:` section
+ * carries no model field. The FIRST-listed preset is the static default
+ * (go-deepseek today): a mapping INDEPENDENT of the active preset, so a
+ * delegated child always gets a sane per-agent model even when no preset is
+ * active — delegation no longer depends 100% on the active preset (branch (b)
+ * of resolveChildModel, which outranks the active-preset branch (c)).
+ *
+ * Fail-open: a missing or unparseable routing.yml yields {} (the caller keeps
+ * the previous behavior — active preset / opencode default) and warns via the
+ * optional logger; it NEVER throws at startup.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.routingPath]
+ * @param {{warn?: Function}} [opts.logger]
+ * @returns {Record<string, string>} lowercase agent → "provider/model"
+ */
+export function loadRoutingAgentModels({ routingPath, logger = console } = {}) {
+  let defs
+  try {
+    defs = loadPresetDefs(routingPath)
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    logger.warn?.(
+      `presets: routing.yml agent models unavailable (${reason}) — delegation falls back to the active preset/default`,
+    )
+    return {}
+  }
+  const names = Object.keys(defs)
+  if (names.length === 0) return {}
+  const models = {}
+  for (const [agent, spec] of Object.entries(defs[names[0]]?.agents ?? {})) {
+    if (spec && typeof spec === 'object' && typeof spec.model === 'string' && spec.model !== '') {
+      models[agent.toLowerCase()] = spec.model
+    }
+  }
+  return models
+}
+
 /**
  * Resolve the active preset: env PANTHEON_MODEL_PRESET > first existing
  * candidate file > null. "none" disables. Unknown names warn and return null
@@ -326,6 +369,66 @@ function buildResolved(defs, name, source, rawFile) {
   return { name, source, agents, providers, overrides, vision }
 }
 
+/**
+ * Whether a single provider DEF has its API key configured: no apiKeyEnv
+ * (native provider, no external key gate) → always configured; otherwise the
+ * env var must be set and non-empty. Shared by applyPreset (startup config
+ * path) and providerKeyConfigured / missingProviderKeyEnv (delegate dispatch).
+ *
+ * @param {object|null|undefined} provider provider def ({baseURL, apiKeyEnv})
+ * @param {Record<string, string|undefined>} env
+ * @returns {boolean}
+ */
+function providerDefKeyConfigured(provider, env) {
+  if (!provider || typeof provider !== 'object') return true
+  const envVar = provider.apiKeyEnv
+  if (typeof envVar !== 'string' || envVar === '') return true
+  const key = env[envVar]
+  return typeof key === 'string' && key.trim() !== ''
+}
+
+/**
+ * Name of the env var whose value is missing for a provider, or undefined
+ * when the provider is usable. A provider is usable when it declares no
+ * apiKeyEnv (native providers like opencode Zen) or its apiKeyEnv env var is
+ * set and non-empty. Provider defs come from routing.yml preset definitions —
+ * the SAME source applyPreset enforces at startup, so the delegate dispatch
+ * path and the config path can never disagree.
+ *
+ * @param {string} providerID e.g. 'openai' | 'opencode' | 'opencode-go'
+ * @param {object} [opts]
+ * @param {Record<string, string|undefined>} [opts.env]
+ * @param {string} [opts.routingPath]
+ * @returns {string|undefined} missing env var name, or undefined when usable
+ */
+export function missingProviderKeyEnv(providerID, { env = process.env, routingPath } = {}) {
+  const defs = loadPresetDefs(routingPath)
+  for (const def of Object.values(defs)) {
+    const provider = def?.providers?.[providerID]
+    if (provider === undefined) continue
+    if (providerDefKeyConfigured(provider, env)) return undefined
+    return provider.apiKeyEnv
+  }
+  // Provider not declared in any preset → no external key gate (opencode
+  // manages its own auth) → usable.
+  return undefined
+}
+
+/**
+ * Whether the given provider's API key is configured (see
+ * missingProviderKeyEnv). Convenience boolean for callers that only need the
+ * yes/no answer.
+ *
+ * @param {string} providerID
+ * @param {object} [opts]
+ * @param {Record<string, string|undefined>} [opts.env]
+ * @param {string} [opts.routingPath]
+ * @returns {boolean}
+ */
+export function providerKeyConfigured(providerID, opts) {
+  return missingProviderKeyEnv(providerID, opts) === undefined
+}
+
 /**
  * Apply a resolved preset to an opencode config object (mutates `config`).
  * - Providers: config.provider[id].options.baseURL + apiKey (env-gated).
@@ -339,8 +442,7 @@ export function applyPreset(config, resolved, { env = process.env } = {}) {
   if (!resolved) return config
 
   for (const [id, provider] of Object.entries(resolved.providers ?? {})) {
-    const apiKey = env[provider.apiKeyEnv]
-    if (!apiKey) {
+    if (!providerDefKeyConfigured(provider, env)) {
       const err = new Error(`presets: provider "${id}" requires env var ${provider.apiKeyEnv}`)
       err.code = 'PANTHEON_MISSING_API_KEY'
       err.envVar = provider.apiKeyEnv
@@ -350,7 +452,7 @@ export function applyPreset(config, resolved, { env = process.env } = {}) {
     config.provider[id] ??= {}
     config.provider[id].options ??= {}
     config.provider[id].options.baseURL = provider.baseURL
-    config.provider[id].options.apiKey = apiKey
+    config.provider[id].options.apiKey = env[provider.apiKeyEnv]
   }
 
   for (const [agent, spec] of Object.entries(resolved.agents ?? {})) {