pantheon-opencode 1.5.0-beta.2 → 1.5.0-beta.4

package/src/pantheon/background-job-board.ts

@@ -272,6 +272,20 @@ export class BackgroundJobBoard {
     return record
   }
 
+  /**
+   * Register a launch only when taskID has not already been claimed.
+   *
+   * The map check and set happen before the first await, so JavaScript's
+   * single-threaded event loop makes this critical section atomic even when
+   * two event handlers call it concurrently. The existing record is returned
+   * for the losing caller.
+   */
+  async registerLaunchIfAbsent(input: LaunchInput): Promise<BackgroundJobRecord> {
+    const existing = this.jobs.get(input.taskID)
+    if (existing !== undefined) return existing
+    return this.registerLaunch(input)
+  }
+
   /**
    * Update a job's state to a terminal state.
    *

package/src/pantheon/compaction-handoff.ts

@@ -0,0 +1,304 @@
+/**
+ * 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-command.ts

@@ -4,11 +4,8 @@
  *
  * Reads the opencode session database READ-ONLY (sum tokens by agent and
  * phase over the last N days → markdown table). Zero new dependencies:
- *   - primary path: node:sqlite (DatabaseSync, readOnly) — node ≥ 22.5;
- *   - CLI fallback: spawn scripts/cost.mjs with its explicit flag-based
- *     interface when the direct import is unavailable;
- *   - missing/unreadable db → FRIENDLY error string, never a crash (tools
- *     return errors as TEXT).
+ *   - only path: node:sqlite (DatabaseSync, readOnly) — node ≥ 22.5;
+ *   - missing/unreadable db → a diagnostic contract status as TEXT.
  *
  * dbPath resolution: explicit option > env PANTHEON_COST_DB > the version-aware
  * default selected by PANTHEON_OPENCODE_VERSION (v1 or v2). An unset version
@@ -18,16 +15,13 @@
  *
  * @module cost-command
  */
-import { execFile } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
-import { promisify } from 'node:util'
 import { z } from 'zod'
 
 import type { ToolContextLike } from './delegation.ts'
-
-const execFileAsync = promisify(execFile)
+import type { NativeTaskStatus } from './native-task-status.ts'
 
 /** One aggregated token row (per agent and phase). */
 export interface CostRow {
@@ -41,10 +35,21 @@ export interface CostRow {
 export interface CostCommandOptions {
   /** Explicit db path (testability / unusual installs). Default: resolved candidates. */
   dbPath?: string
+  /** Injectable loader for tests; production always loads node:sqlite. */
+  sqliteLoader?: () => Promise<SqliteModule>
 }
 
 export type OpenCodeVersion = 'v1' | 'v2'
 
+interface SqliteDatabase {
+  prepare(sql: string): { get(): unknown; all(...args: unknown[]): unknown[] }
+  close(): void
+}
+
+export interface SqliteModule {
+  DatabaseSync: new (path: string, options: { readOnly: boolean }) => SqliteDatabase
+}
+
 /** One cost tool: description + zod args shape + execute (delegation.ts shape). */
 export interface CostTool<Args extends z.ZodRawShape = typeof costArgs> {
   description: string
@@ -125,8 +130,11 @@ function assertCompatibleSchema(db: {
 }
 
 /** Aggregate tokens by agent and phase via node:sqlite (read-only). */
-async function queryWithNodeSqlite(dbPath: string, days: number): Promise<CostRow[]> {
-  const sqlite = await import('node:sqlite')
+async function queryWithNodeSqlite(
+  dbPath: string,
+  days: number,
+  sqlite: SqliteModule,
+): Promise<CostRow[]> {
   const db = new sqlite.DatabaseSync(dbPath, { readOnly: true })
   try {
     assertCompatibleSchema(db)
@@ -142,25 +150,6 @@ async function queryWithNodeSqlite(dbPath: string, days: number): Promise<CostRo
   }
 }
 
-/** CLI fallback: delegate the same aggregation to scripts/cost.mjs. */
-async function queryWithScript(
-  scriptPath: string,
-  dbPath: string,
-  days: number,
-): Promise<CostRow[]> {
-  const { stdout } = await execFileAsync(
-    process.execPath,
-    [scriptPath, '--db-path', dbPath, '--days', String(days)],
-    {
-      timeout: 15_000,
-      encoding: 'utf8',
-    },
-  )
-  const parsed = JSON.parse(stdout) as { ok: boolean; rows?: CostRow[]; error?: string }
-  if (!parsed.ok) throw new Error(parsed.error ?? 'cost.mjs failed')
-  return parsed.rows ?? []
-}
-
 /** Parse message.data JSON rows and aggregate tokens by assistant agent/phase. */
 function aggregateMessages(dataValues: readonly string[]): CostRow[] {
   const byAgentAndPhase = new Map<string, CostRow>()
@@ -232,7 +221,42 @@ function renderMarkdown(rows: readonly CostRow[], days: number): string {
 }
 
 export function createCostCommand(options?: CostCommandOptions): CostCommand {
-  const scriptPath = new URL('../../scripts/cost.mjs', import.meta.url).pathname
+  const loadSqlite =
+    options?.sqliteLoader ?? (async () => (await import('node:sqlite')) as SqliteModule)
+
+  const failure = (status: NativeTaskStatus, detail: string): string =>
+    `status: ${status}\npantheon_cost failed: ${detail}`
+
+  const diagnostic = (err: unknown): string => {
+    if (err instanceof Error) {
+      const stderr = (err as Error & { stderr?: unknown }).stderr
+      const suffix =
+        typeof stderr === 'string' && stderr.trim() !== '' ? `; stderr: ${stderr.trim()}` : ''
+      return `${err.message}${suffix}`
+    }
+    return String(err)
+  }
+
+  const statusForError = (err: unknown): NativeTaskStatus => {
+    const detail = diagnostic(err).toLowerCase()
+    if (
+      detail.includes('not found') ||
+      detail.includes('unknown builtin') ||
+      detail.includes('no such built-in') ||
+      detail.includes('cannot find module')
+    ) {
+      return 'UNSUPPORTED'
+    }
+    if (
+      detail.includes('not a database') ||
+      detail.includes('malformed') ||
+      detail.includes('corrupt') ||
+      detail.includes('incompatible opencode.db schema')
+    ) {
+      return 'CORRUPT_DATA'
+    }
+    return 'UNAVAILABLE'
+  }
 
   const execute = async (args: { days?: number }, _ctx: ToolContextLike): Promise<string> => {
     const days = args?.days ?? 7
@@ -240,20 +264,16 @@ export function createCostCommand(options?: CostCommandOptions): CostCommand {
       const dbPath = findExistingDb(options?.dbPath)
       if (dbPath === undefined) {
         const expected = resolveCostDbPath(options)
-        return (
-          `pantheon_cost failed: opencode.db not found (expected at ${expected}). ` +
-          `No token history is available until opencode has stored session data.`
+        return failure(
+          'UNAVAILABLE',
+          `opencode.db not found (expected at ${expected}). No token history is available until opencode has stored session data.`,
         )
       }
-      const rows = await queryWithNodeSqlite(dbPath, days).catch(async (err: unknown) => {
-        if (err instanceof Error && err.message.startsWith('incompatible opencode.db schema'))
-          throw err
-        return queryWithScript(scriptPath, dbPath, days)
-      })
-      return renderMarkdown(rows, days)
+      const sqlite = await loadSqlite()
+      const rows = await queryWithNodeSqlite(dbPath, days, sqlite)
+      return `status: OK\n${renderMarkdown(rows, days)}`
     } catch (err: unknown) {
-      const reason = err instanceof Error ? err.message : String(err)
-      return `pantheon_cost failed: ${reason}`
+      return failure(statusForError(err), diagnostic(err))
     }
   }