pantheon-opencode 1.5.0-beta.14 → 1.5.0-beta.15

package/src/pantheon/compaction-handoff.ts

@@ -1,304 +0,0 @@
-/**
- * Compaction handoff coordinator.
- *
- * Coordinates the handoff of a compaction checkpoint from in-memory state to
- * durable persistence. The coordinator is deliberately dependency-free: it
- * does not import plugin, board, MCP, hooks, or provider modules.
- */
-
-export interface HandoffRecord {
-  digest: string
-  payload: string
-  version: number
-  sessionId: string
-  leaseToken: string
-}
-
-export interface PersistencePort {
-  prepare(input: HandoffRecord): Promise<void>
-  read(sessionId: string, key: string): Promise<HandoffRecord | null>
-  commit(sessionId: string, key: string, record: HandoffRecord): Promise<void>
-}
-
-export interface MemoryPort {
-  publishImmutable(sessionId: string, key: string, record: HandoffRecord): Promise<void>
-  readByIdempotencyKey(key: string): Promise<HandoffRecord | null>
-}
-
-export type HandoffStatus =
-  | 'COMMITTED'
-  | 'UNAVAILABLE'
-  | 'CONFLICT'
-  | 'NOT_SUPPORTED'
-  | 'INVALID_INPUT'
-
-/** Maximum allowed integer version value. */
-export const MAX_SAFE_INTEGER = Number.MAX_SAFE_INTEGER
-
-/** Maximum encoded payload size in bytes (128 KiB). */
-export const MAX_PAYLOAD_BYTES = 65_536
-
-/** Maximum length of URL-safe identifiers. */
-export const MAX_ID_LENGTH = 128
-
-const URL_SAFE_PATTERN = /^[A-Za-z0-9._~-]+$/
-const DIGEST_PATTERN = /^[a-f0-9]{64}$/
-
-/** Validate a URL-safe identifier: 1-128 chars, no control characters. */
-function isValidIdentifier(value: unknown): value is string {
-  if (typeof value !== 'string') {
-    return false
-  }
-  if (value.length < 1 || value.length > MAX_ID_LENGTH) {
-    return false
-  }
-  if (value.length > 0 && !URL_SAFE_PATTERN.test(value)) {
-    return false
-  }
-  return true
-}
-
-/** Validate a lease token: 1-128 chars, no control characters. */
-function isValidLeaseToken(value: unknown): value is string {
-  if (typeof value !== 'string') {
-    return false
-  }
-  if (value.length < 1 || value.length > MAX_ID_LENGTH) {
-    return false
-  }
-  for (const char of value) {
-    const code = char.charCodeAt(0)
-    if (code < 0x20 || code === 0x7f) {
-      return false
-    }
-  }
-  return true
-}
-
-/** Validate a positive integer version within the safe integer range. */
-function isValidVersion(value: unknown): value is number {
-  return (
-    typeof value === 'number' && Number.isInteger(value) && value > 0 && value <= MAX_SAFE_INTEGER
-  )
-}
-
-/** Validate a 64-character lowercase hex digest. */
-function isValidDigest(value: unknown): value is string {
-  return typeof value === 'string' && DIGEST_PATTERN.test(value)
-}
-
-/**
- * Validate that a payload is UTF-8 encodable and contains no NUL or control
- * characters (tab, LF, and CR are permitted).
- */
-function isValidPayload(value: unknown): value is string {
-  if (typeof value !== 'string') {
-    return false
-  }
-  if (value.length < 1 || value.length > MAX_PAYLOAD_BYTES) {
-    return false
-  }
-
-  const bytes = Buffer.byteLength(value, 'utf8')
-  if (bytes < 1 || bytes > MAX_PAYLOAD_BYTES) {
-    return false
-  }
-  if (value.includes('\0')) {
-    return false
-  }
-
-  for (const char of value) {
-    const code = char.charCodeAt(0)
-    if (code < 0x20 && code !== 0x09 && code !== 0x0a && code !== 0x0d) {
-      return false
-    }
-  }
-  return true
-}
-
-/**
- * Compute the digest over the exact UTF-8 encoded bytes of a payload.
- */
-export function computeDigest(payload: string): string {
-  const bytes = Buffer.from(payload, 'utf8')
-  let hash = ''
-  for (const byte of bytes) {
-    hash += byte.toString(16).padStart(2, '0')
-  }
-  return hash
-}
-
-/** Create a result describing a failed validation. */
-function invalid(message: string): { status: 'INVALID_INPUT'; message: string } {
-  return { status: 'INVALID_INPUT', message }
-}
-
-/** Create a result describing a missing dependency. */
-function notSupported(): { status: 'NOT_SUPPORTED' } {
-  return { status: 'NOT_SUPPORTED' }
-}
-
-/** Create a result describing a conflict. */
-function conflict(message: string): { status: 'CONFLICT'; message: string } {
-  return { status: 'CONFLICT', message }
-}
-
-/** Create a result describing an unavailable memory port. */
-function unavailable(message: string): { status: 'UNAVAILABLE'; message: string } {
-  return { status: 'UNAVAILABLE', message }
-}
-
-/** Create a successful committed result. */
-function committed(digest: string): { status: 'COMMITTED'; digest: string } {
-  return { status: 'COMMITTED', digest }
-}
-
-/**
- * Compaction handoff coordinator.
- *
- * The coordinator drives the handoff FSM:
- *
- *   no record -> prepare -> PREPARED -> memory.publishImmutable
- *   -> memory.readByIdempotencyKey -> persistence.commit -> COMMITTED
- *
- * It never retries after memory becomes unavailable; the PREPARED state is
- * left intact for a later explicit attempt.
- */
-export class CompactionHandoffCoordinator {
-  private readonly persistence: PersistencePort | undefined
-  private readonly memory: MemoryPort | undefined
-
-  constructor(persistence?: PersistencePort, memory?: MemoryPort) {
-    this.persistence = persistence
-    this.memory = memory
-  }
-
-  /**
-   * Attempt to hand off a compaction checkpoint.
-   *
-   * Returns immediately with INVALID_INPUT if any argument fails validation.
-   * Returns NOT_SUPPORTED if either required port is missing.
-   * Returns CONFLICT for digest or lease/version mismatches.
-   * Returns UNAVAILABLE if the memory port cannot publish/read the record.
-   * Returns COMMITTED when the record is durably committed.
-   */
-  async prepare(
-    sessionId: string,
-    idempotencyKey: string,
-    leaseToken: string,
-    version: number,
-    digest: string,
-    payload: string,
-  ): Promise<{ status: HandoffStatus; key?: string; digest?: string; message?: string }> {
-    // Validation first: no port calls are made before this block completes.
-    if (
-      !isValidIdentifier(sessionId) ||
-      !isValidIdentifier(idempotencyKey) ||
-      !isValidLeaseToken(leaseToken) ||
-      !isValidVersion(version) ||
-      !isValidDigest(digest) ||
-      !isValidPayload(payload)
-    ) {
-      return invalid('Invalid handoff input')
-    }
-
-    if (this.persistence === undefined || this.memory === undefined) {
-      return notSupported()
-    }
-
-    const _key = `${sessionId}:${idempotencyKey}`
-
-    // Check for an existing committed record before preparing a new one.
-    const existingRecord = await this.persistence.read(sessionId, idempotencyKey)
-    if (existingRecord !== null) {
-      if (existingRecord.digest === digest && existingRecord.sessionId === sessionId) {
-        // Idempotent replay: same digest and session. Verify lease/version match.
-        if (existingRecord.leaseToken !== leaseToken || existingRecord.version !== version) {
-          return conflict('Stale lease or version')
-        }
-
-        // Verify the record is also in memory. If missing, try to recover by publishing once.
-        let memoryRecord: HandoffRecord | null = null
-        try {
-          memoryRecord = await this.memory.readByIdempotencyKey(idempotencyKey)
-        } catch {
-          return unavailable('Memory port unavailable')
-        }
-
-        if (memoryRecord === null) {
-          // Recovery: memory lost the record but persistence has it. Publish once.
-          try {
-            await this.memory.publishImmutable(sessionId, idempotencyKey, existingRecord)
-          } catch (_error) {
-            return unavailable('Memory port unavailable')
-          }
-          try {
-            memoryRecord = await this.memory.readByIdempotencyKey(idempotencyKey)
-          } catch (_error) {
-            return unavailable('Memory port unavailable')
-          }
-        }
-
-        if (memoryRecord === null) {
-          return unavailable('Record not found in memory')
-        }
-
-        await this.persistence.commit(sessionId, idempotencyKey, existingRecord)
-        return committed(memoryRecord.digest)
-      }
-      // Different digest or session: conflict.
-      return conflict('Digest or session mismatch')
-    }
-
-    // Phase 1: prepare in persistence (PREPARED).
-    await this.persistence.prepare({ digest, payload, version, sessionId, leaseToken })
-
-    // Phase 2: publish the record to memory. If memory is unavailable, the
-    // coordinator stays in PREPARED and never retries automatically.
-    try {
-      await this.memory.publishImmutable(sessionId, idempotencyKey, {
-        digest,
-        payload,
-        version,
-        sessionId,
-        leaseToken,
-      })
-    } catch (_error) {
-      return unavailable('Memory port unavailable')
-    }
-
-    // Phase 3: read back from memory by idempotency key.
-    let memoryRecord: HandoffRecord | null = null
-    try {
-      memoryRecord = await this.memory.readByIdempotencyKey(idempotencyKey)
-    } catch (_error) {
-      return unavailable('Memory port unavailable')
-    }
-
-    if (memoryRecord === null) {
-      return unavailable('Record not found in memory')
-    }
-
-    // Stale lease or version check.
-    if (memoryRecord.leaseToken !== leaseToken || memoryRecord.version !== version) {
-      return conflict('Stale lease or version')
-    }
-
-    // Idempotent replay: same key and session is a success.
-    // The memory record is authoritative for recovery after crash.
-    if (memoryRecord.sessionId === sessionId) {
-      // Phase 4: commit to persistence.
-      try {
-        await this.persistence.commit(sessionId, idempotencyKey, memoryRecord)
-      } catch (_error) {
-        return conflict('Persistence commit failed')
-      }
-      return committed(memoryRecord.digest)
-    }
-
-    // Same key, different digest or session: conflict.
-    return conflict('Digest or session mismatch')
-  }
-}
-
-export default CompactionHandoffCoordinator

package/src/pantheon/cost-tracker.ts

@@ -1,108 +0,0 @@
-/**
- * Cost Tracker (Wave 4, PR #46) — JSONL cost ledger for background
- * delegations. Every delegation that finishes (or times out) records one
- * line; the ledger lives at `.pantheon/costs/delegations.jsonl` and gives
- * Nyx / the /cost command a durable, human-readable cost history.
- *
- * record() APPENDS (appendFile + parent dir auto-create), never rewrites.
- * A missing ledger is an EMPTY ledger — list() → [], summary() → zeros,
- * no crash. Injectable clock not needed: timestamp is caller-provided
- * (ISO 8601), matching the delegation toolset's timestamping style.
- *
- * @module cost-tracker
- */
-import { appendFile, mkdir, readFile } from 'node:fs/promises'
-import { dirname } from 'node:path'
-
-/** One delegation cost event. */
-export interface CostRecord {
-  /** Board task ID (e.g. "ses_child_1" or the job alias "apo-1"). */
-  taskId: string
-  /** Session that owns the delegation — list(sessionID?) filters on this. */
-  sessionID?: string
-  /** Delegated agent name (e.g. "hermes"). */
-  agent: string
-  /** Model ID actually used (e.g. "opencode/deepseek-v4-flash"). */
-  model: string
-  tokensInput: number
-  tokensOutput: number
-  /** Cost in USD (already computed by the caller). */
-  costUsd: number
-  /** ISO 8601 timestamp of the record. */
-  timestamp: string
-}
-
-/** Aggregate across the whole ledger. */
-export interface CostSummary {
-  count: number
-  totalCostUsd: number
-  totalTokensInput: number
-  totalTokensOutput: number
-}
-
-export interface CostTrackerOptions {
-  /** Ledger path. Default: ".pantheon/costs/delegations.jsonl". */
-  filePath?: string
-}
-
-export interface CostTracker {
-  /** Append one record to the ledger (creates the parent dir on first write). */
-  record(entry: CostRecord): Promise<void>
-  /** All records, optionally filtered by sessionID. Missing file → []. */
-  list(sessionID?: string): Promise<CostRecord[]>
-  /** Aggregate totals across the whole ledger. Missing file → zeros. */
-  summary(): Promise<CostSummary>
-}
-
-/** Parse the ledger file; missing file → empty array (never throws). */
-async function readLedger(filePath: string): Promise<CostRecord[]> {
-  let raw: string
-  try {
-    raw = await readFile(filePath, 'utf8')
-  } catch {
-    return []
-  }
-  const records: CostRecord[] = []
-  for (const line of raw.split('\n')) {
-    if (line.trim() === '') continue
-    try {
-      records.push(JSON.parse(line) as CostRecord)
-    } catch {
-      // Skip malformed lines — a partial ledger never breaks the reader.
-    }
-  }
-  return records
-}
-
-export function createCostTracker(options?: CostTrackerOptions): CostTracker {
-  const filePath = options?.filePath ?? '.pantheon/costs/delegations.jsonl'
-
-  return {
-    async record(entry: CostRecord): Promise<void> {
-      await mkdir(dirname(filePath), { recursive: true })
-      await appendFile(filePath, `${JSON.stringify(entry)}\n`, 'utf8')
-    },
-
-    async list(sessionID?: string): Promise<CostRecord[]> {
-      const records = await readLedger(filePath)
-      if (sessionID === undefined) return records
-      return records.filter((r) => r.sessionID === sessionID)
-    },
-
-    async summary(): Promise<CostSummary> {
-      const records = await readLedger(filePath)
-      const summary: CostSummary = {
-        count: records.length,
-        totalCostUsd: 0,
-        totalTokensInput: 0,
-        totalTokensOutput: 0,
-      }
-      for (const r of records) {
-        summary.totalCostUsd += r.costUsd
-        summary.totalTokensInput += r.tokensInput
-        summary.totalTokensOutput += r.tokensOutput
-      }
-      return summary
-    },
-  }
-}

package/src/pantheon/dispatch-guard.ts

@@ -1,109 +0,0 @@
-/**
- * Dispatch Guard (Wave 4, PR #46) — auto-retry-on-empty for background
- * delegations. Classifies a dispatch result and redispatch once when it
- * came back empty.
- *
- * Failure signature classification:
- *   - 'content'     — text content present, nothing to do.
- *   - 'empty-mode1' — NO content AND NO tokens: the dispatch returned
- *                     nothing at all (no reply / early abort).
- *   - 'empty-mode2' — no text part but tokens present: reasoning happened
- *                     but the text part was lost — the themis Wave-2
- *                     failure signature that triggered this guard.
- *
- * Retry cap is HARD at 1 (never 2x). The guard is stateful per instance:
- * one retry budget total. It is a PURE library — it does NOT intercept
- * task() (opencode 1.18.x cannot intercept task completion via hooks, so
- * integration is manual-orchestration; see zeus.md "Empty-Result Retry").
- *
- * @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). */
-  content?: string | null
-  /** Input tokens (present when the model actually reasoned). */
-  tokensInput?: number
-  /** Output tokens (present when the model actually reasoned). */
-  tokensOutput?: number
-  /** R1: the failure that produced this result (classified by retry-policy). */
-  error?: unknown
-}
-
-/** Classification of a dispatch result. */
-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 the Pantheon file log, env-gated echo). */
-  logger?: { warn: (message: string) => void }
-}
-
-export interface DispatchGuard {
-  /** Classify a result: content, empty-mode1 (nothing), empty-mode2 (reasoning, no text). */
-  classifyResult(result: DispatchResultLike): DispatchClassification
-  /**
-   * Redispatch ONCE when the result is empty and retryOnEmpty is enabled.
-   * A retried result that is STILL empty is returned as-is — the cap of 1
-   * is never exceeded. Never throws.
-   */
-  maybeRetry(
-    result: DispatchResultLike,
-    redispatch: () => Promise<DispatchResultLike>,
-  ): Promise<{
-    classification: DispatchClassification
-    retried: boolean
-    result: DispatchResultLike
-  }>
-}
-
-/** 1-based retry budget — the hard cap. Never 2x. */
-const MAX_RETRIES = 1
-
-/** Whether a result carries any text content (whitespace-only counts as empty). */
-function hasContent(result: DispatchResultLike): boolean {
-  return typeof result.content === 'string' && result.content.trim() !== ''
-}
-
-/** Whether the result carries any token counts (i.e. the model actually ran). */
-function hasTokens(result: DispatchResultLike): boolean {
-  return (result.tokensInput ?? 0) > 0 || (result.tokensOutput ?? 0) > 0
-}
-
-export function createDispatchGuard(options?: DispatchGuardOptions): DispatchGuard {
-  const retryOnEmpty = options?.retryOnEmpty ?? true
-  const warn = options?.logger?.warn ?? ((message: string) => log.warn(message))
-  // Per-instance retry budget — the "cap 1" enforcement point.
-  let retriesUsed = 0
-
-  return {
-    classifyResult(result: DispatchResultLike): DispatchClassification {
-      if (hasContent(result)) return 'content'
-      return hasTokens(result) ? 'empty-mode2' : 'empty-mode1'
-    },
-
-    async maybeRetry(result, redispatch) {
-      const classification = this.classifyResult(result)
-      if (!retryOnEmpty || classification === 'content' || retriesUsed >= MAX_RETRIES) {
-        return { classification, retried: false, result }
-      }
-      retriesUsed += 1
-      warn(`dispatch returned ${classification}; retrying once (cap ${MAX_RETRIES})`)
-      const retriedResult = await redispatch()
-      return {
-        classification: this.classifyResult(retriedResult),
-        retried: true,
-        result: retriedResult,
-      }
-    },
-  }
-}