pantheon-opencode 1.3.2 → 1.3.4

package/src/pantheon/hashline/tool.ts

@@ -0,0 +1,260 @@
+/**
+ * Hashline edit tool (Wave 2, PR #46) — structural `hashline_edit` tool that
+ * anchors edits to stable sha256 content tags instead of fragile line numbers.
+ *
+ * Tool shape matches the delegation tools (`{description, args, execute}`,
+ * zod-validated — same import pattern as delegation.ts).
+ *
+ * Safety model (council-approved):
+ *   1. ALL refs are validated against the ORIGINAL file snapshot BEFORE any
+ *      write — a mismatch returns an error-as-text with a re-tagged excerpt,
+ *      `>>>` marker, and a Did-you-mean suggestion. NO partial write ever.
+ *   2. Edits are applied BOTTOM-UP (highest line first) so every ref resolves
+ *      against the original numbering, even for adjacent edits.
+ *
+ * Ops:
+ *   - replace: `ref` (or `ref`..`endRef` range) → replace with `lines`
+ *   - append:  insert `content` AFTER the anchor `ref` line
+ *   - prepend: insert `content` BEFORE the anchor `ref` line
+ *   - delete:  remove the `ref` line (or `ref`..`endRef` range); no `lines`
+ *
+ * @module hashline/tool
+ */
+
+import { readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { isAbsolute, resolve, sep } from 'node:path'
+import { z } from 'zod'
+
+import { buildMismatchError, HASHLINE_REF_RE } from './core.ts'
+import { hashTag } from './xxhash.ts'
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Structural tool context (subset of the opencode ToolContext). */
+export interface HashlineEditContext {
+  sessionID: string
+  directory?: string
+  worktree?: string
+  agent?: string
+}
+
+/** One hashline edit operation. */
+export interface HashlineEditOp {
+  op: 'replace' | 'append' | 'prepend' | 'delete'
+  /** Anchor ref "LINE#TAG" against the ORIGINAL snapshot. */
+  ref: string
+  /** Optional range end for replace/delete ("LINE#TAG"). */
+  endRef?: string
+  /** Replacement lines (replace). */
+  lines?: string[]
+  /** Text to insert (append/prepend; split on newlines). */
+  content?: string
+}
+
+/** Tool result — string (error-as-text) or success with metadata. */
+export type HashlineToolResult =
+  | string
+  | { title?: string; output: string; metadata: { firstChangedLine: number; changedCount: number } }
+
+// ─── Args schema ───────────────────────────────────────────────────────
+
+const hashlineEditOpArgs = {
+  op: z.enum(['replace', 'append', 'prepend', 'delete']),
+  ref: z.string().min(1),
+  endRef: z.string().optional(),
+  lines: z.array(z.string()).optional(),
+  content: z.string().optional(),
+} satisfies z.ZodRawShape
+
+const hashlineEditArgs = {
+  file: z.string().min(1),
+  edits: z.array(z.object(hashlineEditOpArgs)).min(1),
+} satisfies z.ZodRawShape
+
+/** A ref validated against the original snapshot. */
+interface ResolvedRef {
+  line: number
+  tag: string
+  /** Ref string as given (for error messages). */
+  raw: string
+}
+
+/** A fully validated edit, ready to apply bottom-up. */
+interface ResolvedEdit {
+  op: HashlineEditOp['op']
+  line: number
+  endLine: number
+  insert: string[]
+}
+
+// ─── Helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Resolve the edit file to an absolute path, with a containment guard.
+ *
+ * Relative paths must stay inside `base` (worktree → directory → cwd):
+ * `../` traversal (`../../etc/passwd`) is rejected as error-as-text, so no
+ * read/write ever happens outside the worktree. Absolute paths are trusted
+ * as-is — hashline_edit carries the same privilege as edit/write/bash, so
+ * this is cheap defense-in-depth, not a security boundary.
+ */
+function resolveFile(
+  file: string,
+  ctx: HashlineEditContext,
+): { ok: true; file: string } | { ok: false; error: string } {
+  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: 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,
+      error: `hashline_edit: file "${file}" escapes the worktree (resolved to "${resolved}") — path containment denied`,
+    }
+  }
+  return { ok: true, file: resolved }
+}
+
+/** Parse + validate a ref string against the ORIGINAL snapshot lines. */
+function resolveRef(raw: string, file: string, lines: readonly string[]): ResolvedRef | string {
+  const m = HASHLINE_REF_RE.exec(raw)
+  if (!m) {
+    return `hashline_edit: invalid ref "${raw}" — expected "LINE#TAG" (e.g. "12#XJ")`
+  }
+  const line = Number(m[1])
+  const tag = m[2]
+  if (line < 1 || line > lines.length) {
+    return `hashline_edit: ref "${raw}" line ${line} out of range — file has ${lines.length} line(s)`
+  }
+  const actual = hashTag(lines[line - 1] ?? '', line)
+  if (actual !== tag) {
+    return buildMismatchError(file, raw, { line, tag: actual, content: lines[line - 1] }, lines)
+  }
+  return { line, tag, raw }
+}
+
+/**
+ * Validate ALL edits against the original snapshot; returns the resolved
+ * edit list or the error-as-text for the first failure.
+ */
+function validateEdits(
+  args: z.infer<z.ZodObject<typeof hashlineEditArgs>>,
+  file: string,
+  lines: readonly string[],
+): ResolvedEdit[] | string {
+  const resolved: ResolvedEdit[] = []
+  for (const [i, e] of args.edits.entries()) {
+    const pos = resolveRef(e.ref, file, lines)
+    if (typeof pos === 'string') return pos
+    const edit: ResolvedEdit = { op: e.op, line: pos.line, endLine: pos.line, insert: [] }
+
+    if (e.op === 'delete' && e.lines) {
+      return `hashline_edit: delete edit (index ${i}) must not provide "lines"`
+    }
+    if (e.op === 'replace' && (!e.lines || e.lines.length === 0)) {
+      return `hashline_edit: replace edit (index ${i}) requires non-empty "lines"`
+    }
+    if ((e.op === 'append' || e.op === 'prepend') && typeof e.content !== 'string') {
+      return `hashline_edit: ${e.op} edit (index ${i}) requires "content"`
+    }
+
+    if (e.endRef) {
+      const end = resolveRef(e.endRef, file, lines)
+      if (typeof end === 'string') return end
+      if (end.line < edit.line) {
+        return `hashline_edit: endRef "${e.endRef}" is before ref "${e.ref}"`
+      }
+      edit.endLine = end.line
+    }
+
+    if (e.op === 'replace') {
+      edit.insert = e.lines ?? []
+    } else if (e.op === 'append' || e.op === 'prepend') {
+      edit.insert = (e.content ?? '').split('\n')
+    }
+    resolved.push(edit)
+  }
+  return resolved
+}
+
+// ─── Tool factory ──────────────────────────────────────────────────────
+
+/**
+ * Build the structural `hashline_edit` tool. execute() returns error-as-text
+ * on any validation failure (never throws for user errors, never writes
+ * partially); on success returns the summary with `{firstChangedLine,
+ * changedCount}` metadata.
+ */
+export function createHashlineEditTool() {
+  return {
+    description:
+      'Edit a file anchored by hashline refs (LINE#TAG) instead of raw line numbers. ' +
+      'Ops: replace (ref..endRef or single ref → lines), append/prepend (anchor ref → content), ' +
+      'delete (ref..endRef). ALL refs must be validated against the ORIGINAL file before ' +
+      'anything is written; on mismatch the tool returns an error with a re-tagged excerpt ' +
+      'and a Did-you-mean suggestion, and nothing is modified.',
+    args: hashlineEditArgs,
+    execute: async (
+      args: z.infer<z.ZodObject<typeof hashlineEditArgs>>,
+      ctx: HashlineEditContext,
+    ): Promise<HashlineToolResult> => {
+      const resolved = resolveFile(args.file, ctx)
+      if (!resolved.ok) return resolved.error
+      const file = resolved.file
+
+      let original: string
+      try {
+        original = await readFile(file, 'utf8')
+      } catch {
+        return `hashline_edit: cannot read "${file}" — check the path and try again`
+      }
+
+      const hadTrailingNewline = original.endsWith('\n')
+      const lines = original.split('\n')
+
+      // Phase 1: validate every ref against the ORIGINAL snapshot — no writes.
+      const edits = validateEdits(args, file, lines)
+      if (typeof edits === 'string') return edits
+
+      // Phase 2: apply bottom-up (highest line first; ties: later edit first).
+      edits.sort((a, b) => b.line - a.line || b.endLine - a.endLine)
+      const working = [...lines]
+      for (const e of edits) {
+        const deleteCount = e.endLine - e.line + 1
+        if (e.op === 'replace') {
+          working.splice(e.line - 1, deleteCount, ...e.insert)
+        } else if (e.op === 'delete') {
+          working.splice(e.line - 1, deleteCount)
+        } else if (e.op === 'append') {
+          working.splice(e.line, 0, ...e.insert)
+        } else {
+          // prepend: insert before the anchor line.
+          working.splice(e.line - 1, 0, ...e.insert)
+        }
+      }
+
+      let out = working.join('\n')
+      if (hadTrailingNewline && !out.endsWith('\n')) out += '\n'
+      // Atomic write (tmp + rename — same pattern as file-persistence.ts
+      // writeState / background-job-board.ts writeSignal): a mid-write crash
+      // leaves at most a `.tmp-<pid>` file, never partial target content.
+      // The tmp file is best-effort cleaned up if the write or rename fails.
+      const tmpPath = `${file}.tmp-${process.pid}`
+      try {
+        await writeFile(tmpPath, out, 'utf8')
+        await rename(tmpPath, file)
+      } catch {
+        await rm(tmpPath, { force: true }).catch(() => {})
+        return `hashline_edit: cannot write "${file}" — check permissions and try again`
+      }
+
+      const firstChangedLine = Math.min(...edits.map((e) => e.line))
+      return {
+        title: 'hashline_edit',
+        output: `Updated ${file}: ${edits.length} edit(s) applied, first changed line ${firstChangedLine}.`,
+        metadata: { firstChangedLine, changedCount: edits.length },
+      }
+    },
+  }
+}

package/src/pantheon/hashline/xxhash.ts

@@ -0,0 +1,53 @@
+/**
+ * Hashline tag computation (Wave 2, PR #46) — sha256-truncated per-line tags.
+ *
+ * Pure `node:crypto` — zero vendored xxhash, zero deps. A 2-char tag is
+ * derived from the FIRST byte of the sha256 digest, mapped through a 16-char
+ * alphabet (16² = 256 possible tags — the same alphabet as the reference
+ * implementation for ecosystem familiarity).
+ *
+ * Seeding rule:
+ *   - Lines containing at least one letter/digit (`/[\p{L}\p{N}]/u`) use
+ *     seed 0 → the tag depends ONLY on the content, so identical content
+ *     yields the same tag anywhere in the file (stable anchors for moving
+ *     lines).
+ *   - Blank / symbol-only lines use the LINE NUMBER as seed → otherwise all
+ *     blank lines would share one tag and could never be anchored uniquely.
+ *
+ * @module hashline/xxhash
+ */
+
+import { createHash } from 'node:crypto'
+
+/** 16-char tag alphabet — same as the reference hashline (ecosystem familiarity). */
+export const HASHLINE_DICT = 'ZPMQVRWSNKTXJBYH'
+
+/** Lines that carry at least one letter or digit hash by content alone. */
+const ALNUM_RE = /[\p{L}\p{N}]/u
+
+/**
+ * Normalize a line before hashing: strip the trailing `\r` (CRLF inputs) and
+ * trim trailing whitespace so cosmetic edits do not change the tag.
+ */
+export function normalizeLine(line: string): string {
+  return line.replace(/\r$/, '').trimEnd()
+}
+
+/**
+ * Compute the 2-char hashline tag for `line` at 1-based `lineNumber`.
+ *
+ * @param line Raw line content (may include trailing newline artifacts).
+ * @param lineNumber 1-based line number (seeds blank/symbol lines only).
+ * @returns Two uppercase chars from HASHLINE_DICT.
+ */
+export function hashTag(line: string, lineNumber: number): string {
+  const normalized = normalizeLine(line)
+  const seed = ALNUM_RE.test(normalized) ? 0 : lineNumber
+  // The `\u0000` NUL between seed and content disambiguates the
+  // seed/content concatenation: without it, seed 1 + content "2" and
+  // seed 12 + content "" would collide into the same digest input. NUL
+  // never occurs in real source lines, so it is a safe separator.
+  const digest = createHash('sha256').update(`${seed}\u0000${normalized}`).digest()
+  const first = digest[0] ?? 0
+  return HASHLINE_DICT.charAt(first >> 4) + HASHLINE_DICT.charAt(first & 0x0f)
+}

package/src/pantheon/idle-continuation.ts

@@ -0,0 +1,54 @@
+/**
+ * Idle Continuation Dispatcher (Wave 3, PR #46) — routes `session.idle`
+ * events to the subsystem that owns the idle.
+ *
+ * Priority: an ACTIVE GOAL owns the idle — `GoalLoop.onIdle` continues the
+ * goal. Without an active goal, the TODO enforcer gets the idle (it
+ * self-guards on its own enabled flag + guards). Board-child sessions never
+ * reach the dispatcher — the plugin's event hook routes those to the
+ * delegation finalize path first (`handleDelegationEvent` returns true) and
+ * only calls the dispatcher on the `!delegated` branch.
+ *
+ * Independently testable — the loop and enforcer are structural interfaces;
+ * the real GoalLoop/TodoEnforcer satisfy them.
+ *
+ * Pure TypeScript — zero runtime dependencies.
+ *
+ * @module idle-continuation
+ */
+
+/** Structural goal-loop surface the dispatcher needs. */
+export interface GoalLoopLike {
+  hasActiveGoal(sessionID: string): Promise<boolean>
+  onIdle(sessionID: string): Promise<void>
+}
+
+/** Structural todo-enforcer surface the dispatcher needs. */
+export interface TodoEnforcerLike {
+  onIdle(sessionID: string): Promise<void>
+}
+
+/** The dispatcher's onIdle surface (used by the plugin event hook). */
+export interface IdleDispatcher {
+  onIdle(sessionID: string): Promise<void>
+}
+
+/**
+ * Build the idle router. The plugin event hook calls this only on the
+ * `!delegated` branch of `handleDelegationEvent`, so board children never
+ * arrive here.
+ */
+export function createIdleDispatcher(deps: {
+  goalLoop: GoalLoopLike
+  todoEnforcer: TodoEnforcerLike
+}): IdleDispatcher {
+  return {
+    onIdle: async (sessionID: string): Promise<void> => {
+      if (await deps.goalLoop.hasActiveGoal(sessionID)) {
+        await deps.goalLoop.onIdle(sessionID)
+        return
+      }
+      await deps.todoEnforcer.onIdle(sessionID)
+    },
+  }
+}

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