pantheon-opencode 1.4.3 → 1.5.0-beta.10

package/src/pantheon/native-task-status.ts

@@ -0,0 +1,139 @@
+/**
+ * Native Task Status — classifies BackgroundJobRecord results from native
+ * task() delegation into actionable status codes.
+ *
+ * Pure module — zero external dependencies. Consumed by native-probe.ts
+ * and the delegation manager to decide retry/skip/escalate strategy.
+ *
+ * @module native-task-status
+ */
+
+import type { BackgroundJobRecord } from './background-job-board.ts'
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Actionable status for a native task() delegation result. */
+export type NativeTaskStatus =
+  | 'OK'
+  | 'UNSUPPORTED'
+  | 'UNAVAILABLE'
+  | 'INVALID_INPUT'
+  | 'INVALID_STATE'
+  | 'CONFLICT'
+  | 'CORRUPT_DATA'
+  | 'TIMEOUT'
+  | 'ESCALATE'
+
+// ─── Helpers ───────────────────────────────────────────────────────────
+
+/** Check if a string contains any of the given substrings (case-insensitive). */
+function containsAny(text: string | undefined, patterns: readonly string[]): boolean {
+  if (text == null) return false
+  const lower = text.toLowerCase()
+  return patterns.some((p) => lower.includes(p.toLowerCase()))
+}
+
+/** Check if a job's output is empty or whitespace-only. */
+function isOutputEmpty(job: BackgroundJobRecord): boolean {
+  const summary = job.resultSummary
+  if (summary == null) return true
+  if (typeof summary !== 'string') return true
+  return summary.trim() === ''
+}
+
+// ─── Implementation ────────────────────────────────────────────────────
+
+/**
+ * Classify a BackgroundJobRecord result into a NativeTaskStatus.
+ *
+ * Priority order (first match wins):
+ * 1. verifyError and lastStatusError patterns → UNSUPPORTED, CONFLICT,
+ *    INVALID_INPUT, INVALID_STATE, CORRUPT_DATA, ESCALATE
+ * 2. state === startup_failed or timedOut → TIMEOUT
+ * 3. state === completed + non-empty output → OK
+ * 4. state === completed + empty output → UNAVAILABLE (silent failure / admission rejection)
+ * 5. state === error → UNAVAILABLE (safe default for provider/infra errors)
+ * 6. Fallback → UNAVAILABLE
+ */
+export function classifyNativeResult(
+  job: BackgroundJobRecord,
+  verifyError?: string,
+): NativeTaskStatus {
+  const statusError = [verifyError, job.lastStatusError]
+    .filter((value): value is string => value != null && value.length > 0)
+    .join(' ')
+
+  // A missing native task API is terminal and must not be retried or sent
+  // through a fallback model. Provider/transport failures remain unavailable.
+  if (
+    containsAny(statusError, [
+      'api unavailable',
+      'api not available',
+      'api missing',
+      'method not found',
+      'unknown method',
+      'not supported',
+      'unsupported',
+      'does not support',
+      'task() is not available',
+    ])
+  ) {
+    return 'UNSUPPORTED'
+  }
+
+  // ── Phase 1: verifyError explicit signals (highest priority) ───────
+
+  if (verifyError != null && verifyError.length > 0) {
+    // CONFLICT: canDispatch=false or concurrency exceeded
+    if (containsAny(verifyError, ['canDispatch', 'concurrency', 'conflict'])) {
+      return 'CONFLICT'
+    }
+
+    // INVALID_INPUT: agent not recognized / invalid
+    if (containsAny(verifyError, ['invalid agent', 'agent not found', 'unknown agent'])) {
+      return 'INVALID_INPUT'
+    }
+
+    // INVALID_STATE: child already in terminal state
+    if (containsAny(verifyError, ['already terminal', 'already in terminal', 'invalid state'])) {
+      return 'INVALID_STATE'
+    }
+
+    // CORRUPT_DATA: output can't be parsed / corrupted
+    if (containsAny(verifyError, ['corrupt', 'parse failed', 'malformed', 'invalid format'])) {
+      return 'CORRUPT_DATA'
+    }
+
+    // ESCALATE: unrecoverable failure
+    if (containsAny(verifyError, ['unrecoverable', 'fatal', 'max retries exceeded'])) {
+      return 'ESCALATE'
+    }
+  }
+
+  // ── Phase 2: state-based classification ────────────────────────────
+
+  // TIMEOUT: startup failure or timed out
+  if (job.state === 'startup_failed' || job.state === 'startup_unknown' || job.timedOut) {
+    return 'TIMEOUT'
+  }
+
+  // ── Phase 3: output-based classification ───────────────────────────
+
+  if (job.state === 'completed') {
+    if (!isOutputEmpty(job)) {
+      return 'OK'
+    }
+    // completed but empty → silent failure (BackendAdmissionRejected pattern)
+    return 'UNAVAILABLE'
+  }
+
+  // ── Phase 4: error state fallback ──────────────────────────────────
+
+  if (job.state === 'error') {
+    return 'UNAVAILABLE'
+  }
+
+  // ── Fallback ───────────────────────────────────────────────────────
+
+  return 'UNAVAILABLE'
+}

package/src/pantheon/permission-eval.ts

@@ -0,0 +1,284 @@
+/**
+ * S1 — Deny-first permission evaluation + PreToolUse-style hooks.
+ *
+ * Deny rules checked BEFORE allow rules. User-level denies cannot be
+ * overridden by project config. Hook exit-code semantics:
+ *   exit 0 → allow, exit 2 → hard deny, missing/throw → fail-open.
+ *
+ * @module permission-eval
+ */
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Result of a permission evaluation. */
+export interface PermissionResult {
+  allowed: boolean
+  reason: 'allow' | 'deny' | 'hook_deny' | 'no_match'
+  message?: string
+}
+
+/** Hook script result (mirrors hook-runner.ts HookResult). */
+export interface HookResult {
+  code: number
+  stdout: string
+  stderr: string
+  /** When true, the hook script was not found — treat as fail-open. */
+  missing?: boolean
+}
+
+/**
+ * PreToolUse hook function signature.
+ * exit 0 → allow, exit 2 → hard deny, exit 1 → soft deny.
+ * Throw = fail-open.
+ */
+export type PreToolUseHook = (tool: string, args: unknown) => Promise<HookResult> | HookResult
+
+/** Permission configuration. */
+export interface PermissionConfig {
+  /** Deny rules — evaluated first. User-level denies override project allows. */
+  deny: readonly string[]
+  /** Allow rules — evaluated after deny. */
+  allow: readonly string[]
+  /** Optional hooks configuration. */
+  hooks?: {
+    /** PreToolUse hook function (in-process, not script path). */
+    preToolUse?: PreToolUseHook
+  }
+}
+
+// ─── Pattern matching ──────────────────────────────────────────────────
+
+/**
+ * Parse a permission rule pattern into { tool, argPattern }.
+ *
+ * Supported formats:
+ *   - "tool"             → tool="tool", argPattern="*"
+ *   - "tool:*"           → tool="tool", argPattern="*"
+ *   - "tool:subcommand"  → tool="tool", argPattern="subcommand"
+ *   - "tool(pattern)"    → tool="tool", argPattern="pattern" (full match)
+ *   - "*:*"              → tool="*", argPattern="*"
+ *   - "git push:*"       → tool="git push", argPattern="*" (subcommand prefix)
+ */
+function parsePattern(pattern: string): { tool: string; argPattern: string } {
+  // Handle "tool(pattern)" format — the content inside parens is the full
+  // arg pattern. Colons inside parens are literal, not separators.
+  const parenMatch = /^([^(]+)\(([^)]+)\)$/.exec(pattern)
+  if (parenMatch) {
+    const tool = parenMatch[1] ?? ''
+    const argPattern = parenMatch[2] ?? ''
+    return { tool, argPattern }
+  }
+
+  // Handle "tool:argPattern" or just "tool"
+  const colonIdx = pattern.indexOf(':')
+  if (colonIdx === -1) {
+    return { tool: pattern, argPattern: '*' }
+  }
+  const argPattern = pattern.slice(colonIdx + 1)
+  return {
+    tool: pattern.slice(0, colonIdx),
+    // Empty argPattern after colon = wildcard (e.g. "*:" matches any args)
+    argPattern: argPattern === '' ? '*' : argPattern,
+  }
+}
+
+/**
+ * Convert a glob-like pattern to a regex. `*` matches any sequence.
+ * Anchored to full match.
+ */
+function globToRegex(pattern: string): RegExp {
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '.*')
+    .replace(/\?/g, '.')
+  return new RegExp(`^${escaped}$`)
+}
+
+/** Extract a string representation from tool args for pattern matching. */
+function argsToString(args: unknown): string {
+  if (args === null || args === undefined) return ''
+  if (typeof args === 'string') return args
+  if (typeof args === 'object') {
+    const record = args as Record<string, unknown>
+    // Try common field names
+    for (const key of ['command', 'cmd', 'query', 'pattern', 'filePath', 'path', 'url']) {
+      if (typeof record[key] === 'string') return record[key]
+    }
+    return JSON.stringify(args)
+  }
+  return String(args)
+}
+
+/**
+ * Build a combined string for matching: "toolName argString".
+ * This allows patterns like "git push:*" to match tool="git" with args
+ * containing "push".
+ */
+function combinedString(tool: string, args: unknown): string {
+  const argsStr = argsToString(args)
+  return argsStr !== '' ? `${tool} ${argsStr}` : tool
+}
+
+/**
+ * Check if a tool+args matches a permission rule pattern.
+ * Returns true when the pattern matches.
+ *
+ * Matching strategy:
+ *   1. Wildcard tool ("*") → match any tool with argPattern
+ *   2. Direct tool match → check argPattern against args
+ *   3. Combined match (for "git push:*" style patterns) → prefix match
+ */
+function matchesRule(pattern: string, tool: string, args: unknown): boolean {
+  const { tool: patternTool, argPattern } = parsePattern(pattern)
+
+  // Wildcard tool: match any tool
+  if (patternTool === '*') {
+    if (argPattern === '*') return true
+    const argsStr = argsToString(args)
+    return globToRegex(argPattern).test(argsStr)
+  }
+
+  // Check direct tool match
+  if (globToRegex(patternTool).test(tool)) {
+    if (argPattern === '*') return true
+    const argsStr = argsToString(args)
+    return globToRegex(argPattern).test(argsStr)
+  }
+
+  // Combined match for patterns with spaces (e.g. "git push:*")
+  // The pattern tool includes a subcommand that appears in args.
+  // Use prefix matching: "git push" matches "git push origin main"
+  if (patternTool.includes(' ')) {
+    const combined = combinedString(tool, args)
+    // Prefix match: combined starts with pattern tool
+    if (combined.startsWith(patternTool)) {
+      return true
+    }
+  }
+
+  return false
+}
+
+// ─── Evaluation ────────────────────────────────────────────────────────
+
+/**
+ * Evaluate a permission config against a tool+args invocation.
+ *
+ * Evaluation order:
+ *   1. Check deny rules (user-level first, then project-level)
+ *   2. If no deny matched, run the PreToolUse hook
+ *   3. If hook exits 0 (or missing), check allow rules
+ *   4. If no allow matched → deny (implicit deny)
+ *
+ * User-level denies override project-level allows: a deny in the user config
+ * cannot be cancelled by an allow in the project config.
+ */
+export function evaluatePermission(
+  config: PermissionConfig,
+  invocation: { tool: string; args?: unknown },
+): PermissionResult {
+  const { tool, args } = invocation
+
+  // ── Step 1: Deny-first check ────────────────────────────────────────
+  for (const pattern of config.deny) {
+    if (matchesRule(pattern, tool, args)) {
+      return { allowed: false, reason: 'deny', message: `denied by rule: ${pattern}` }
+    }
+  }
+
+  // ── Step 2: PreToolUse hook ─────────────────────────────────────────
+  if (config.hooks?.preToolUse !== undefined) {
+    try {
+      const hookResult = config.hooks.preToolUse(tool, args)
+      // Support both sync and async hooks
+      // For sync hooks (non-Promise), check immediately
+      if (!(hookResult instanceof Promise)) {
+        // missing flag: hook script not found → fail-open
+        if (hookResult.missing === true) {
+          // Fall through to config evaluation (fail-open)
+        } else if (hookResult.code === 2) {
+          return {
+            allowed: false,
+            reason: 'hook_deny',
+            message: `hook hard deny (exit 2): ${hookResult.stderr}`,
+          }
+        } else if (hookResult.code !== 0) {
+          return {
+            allowed: false,
+            reason: 'hook_deny',
+            message: `hook deny (exit ${hookResult.code}): ${hookResult.stderr}`,
+          }
+        }
+        // Hook exited 0 (or missing) → fall through to allow check
+      }
+      // For async hooks, we cannot await in a sync function.
+      // Use evaluatePermissionAsync for async hooks.
+    } catch {
+      // Hook throw → fail-open: fall through to config evaluation
+    }
+  }
+
+  // ── Step 3: Allow check ─────────────────────────────────────────────
+  for (const pattern of config.allow) {
+    if (matchesRule(pattern, tool, args)) {
+      return { allowed: true, reason: 'allow', message: `allowed by rule: ${pattern}` }
+    }
+  }
+
+  // ── Step 4: No match → implicit deny ────────────────────────────────
+  return { allowed: false, reason: 'no_match', message: 'no matching allow rule' }
+}
+
+/**
+ * Async version of evaluatePermission that properly awaits hooks.
+ * Use this when hooks may be async (e.g., shell scripts).
+ */
+export async function evaluatePermissionAsync(
+  config: PermissionConfig,
+  invocation: { tool: string; args?: unknown },
+): Promise<PermissionResult> {
+  const { tool, args } = invocation
+
+  // ── Step 1: Deny-first check ────────────────────────────────────────
+  for (const pattern of config.deny) {
+    if (matchesRule(pattern, tool, args)) {
+      return { allowed: false, reason: 'deny', message: `denied by rule: ${pattern}` }
+    }
+  }
+
+  // ── Step 2: PreToolUse hook ─────────────────────────────────────────
+  if (config.hooks?.preToolUse !== undefined) {
+    try {
+      const hookResult = await config.hooks.preToolUse(tool, args)
+      // missing flag: hook script not found → fail-open
+      if (hookResult.missing === true) {
+        // Fall through to config evaluation (fail-open)
+      } else if (hookResult.code === 2) {
+        return {
+          allowed: false,
+          reason: 'hook_deny',
+          message: `hook hard deny (exit 2): ${hookResult.stderr}`,
+        }
+      } else if (hookResult.code !== 0) {
+        return {
+          allowed: false,
+          reason: 'hook_deny',
+          message: `hook deny (exit ${hookResult.code}): ${hookResult.stderr}`,
+        }
+      }
+      // Hook exited 0 (or missing) → fall through to allow check
+    } catch {
+      // Hook throw → fail-open: fall through to config evaluation
+    }
+  }
+
+  // ── Step 3: Allow check ─────────────────────────────────────────────
+  for (const pattern of config.allow) {
+    if (matchesRule(pattern, tool, args)) {
+      return { allowed: true, reason: 'allow', message: `allowed by rule: ${pattern}` }
+    }
+  }
+
+  // ── Step 4: No match → implicit deny ────────────────────────────────
+  return { allowed: false, reason: 'no_match', message: 'no matching allow rule' }
+}

package/src/pantheon/provider-capabilities.ts

@@ -0,0 +1,221 @@
+/**
+ * Exact provider usage contract and the independent V1/V2 capability probes.
+ *
+ * This module deliberately does not inspect credentials, call a provider, read
+ * the TUI, calculate percentages, or derive token counts from text. A provider
+ * is supported only when it supplies the complete numeric contract below.
+ *
+ * @module provider-capabilities
+ */
+
+/** The only capability statuses exposed by the usage contract. */
+export const USAGE_STATUS = {
+  SUPPORTED: 'SUPPORTED',
+  UNSUPPORTED: 'UNSUPPORTED',
+} as const
+
+export type UsageStatus = (typeof USAGE_STATUS)[keyof typeof USAGE_STATUS]
+
+/** Exact token counters supplied by the provider. No totals are inferred. */
+export interface ExactProviderUsage {
+  inputTokens: number
+  outputTokens: number
+}
+
+/** Exact context limit supplied by the provider. */
+export interface ExactProviderLimit {
+  contextTokens: number
+}
+
+/**
+ * Minimum complete provider payload accepted by either capability probe.
+ * `resetAt`, when present, is an exact non-negative numeric provider value;
+ * date strings and other reset representations are unsupported.
+ */
+export interface ExactProviderUsageData {
+  sessionId: string
+  providerId: string
+  modelId: string
+  usage: ExactProviderUsage
+  limit: ExactProviderLimit
+  resetAt?: number
+}
+
+/** Stream event metadata required for de-duplication and freshness ordering. */
+export interface ProviderUsageEvent extends ExactProviderUsageData {
+  eventId: string
+  partId: string
+  /** Optional provider sequence. When supplied, it must be an integer. */
+  sequence?: number
+  /** Optional provider observation time in milliseconds or another numeric scale. */
+  observedAt?: number
+}
+
+/** A complete snapshot that has passed the exact contract validation. */
+export interface ProviderUsageSnapshot extends ProviderUsageEvent {}
+
+export type CapabilityProbeVersion = 'v1' | 'v2'
+
+export type CapabilityProbeReason =
+  | 'MISSING_SESSION_ID'
+  | 'MISSING_PROVIDER_ID'
+  | 'MISSING_MODEL_ID'
+  | 'MISSING_USAGE'
+  | 'MISSING_LIMIT'
+  | 'INVALID_USAGE'
+  | 'INVALID_LIMIT'
+  | 'INVALID_RESET'
+
+export type ProviderCapabilityResult =
+  | {
+      apiVersion: CapabilityProbeVersion
+      status: typeof USAGE_STATUS.SUPPORTED
+      data: ExactProviderUsageData
+    }
+  | {
+      apiVersion: CapabilityProbeVersion
+      status: typeof USAGE_STATUS.UNSUPPORTED
+      reason: CapabilityProbeReason
+    }
+
+type UnknownRecord = Record<string, unknown>
+
+function isRecord(value: unknown): value is UnknownRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+function isFiniteNonNegativeNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0
+}
+
+function hasOnlyKeys(value: UnknownRecord, allowed: readonly string[]): boolean {
+  return Object.keys(value).every((key) => allowed.includes(key))
+}
+
+function unsupported(
+  apiVersion: CapabilityProbeVersion,
+  reason: CapabilityProbeReason,
+): ProviderCapabilityResult {
+  return { apiVersion, status: USAGE_STATUS.UNSUPPORTED, reason }
+}
+
+/**
+ * Validate the complete exact payload without coercion or estimation.
+ *
+ * This is intentionally shared only as a validator. V1 and V2 entry points
+ * below remain separate capability probes and do not fall back to one another.
+ */
+function probeExactData(
+  apiVersion: CapabilityProbeVersion,
+  input: unknown,
+): ProviderCapabilityResult {
+  if (!isRecord(input)) return unsupported(apiVersion, 'MISSING_SESSION_ID')
+
+  if (!isNonEmptyString(input.sessionId)) {
+    return unsupported(apiVersion, 'MISSING_SESSION_ID')
+  }
+  if (!isNonEmptyString(input.providerId)) {
+    return unsupported(apiVersion, 'MISSING_PROVIDER_ID')
+  }
+  if (!isNonEmptyString(input.modelId)) {
+    return unsupported(apiVersion, 'MISSING_MODEL_ID')
+  }
+  if (!isRecord(input.usage)) return unsupported(apiVersion, 'MISSING_USAGE')
+  if (!isRecord(input.limit)) return unsupported(apiVersion, 'MISSING_LIMIT')
+  if (!hasOnlyKeys(input.usage, ['inputTokens', 'outputTokens'])) {
+    return unsupported(apiVersion, 'INVALID_USAGE')
+  }
+  if (!hasOnlyKeys(input.limit, ['contextTokens'])) {
+    return unsupported(apiVersion, 'INVALID_LIMIT')
+  }
+
+  const usage = input.usage
+  if (!isFiniteNonNegativeNumber(usage.inputTokens)) {
+    return unsupported(apiVersion, 'INVALID_USAGE')
+  }
+  if (!isFiniteNonNegativeNumber(usage.outputTokens)) {
+    return unsupported(apiVersion, 'INVALID_USAGE')
+  }
+
+  const limit = input.limit
+  if (!isFiniteNonNegativeNumber(limit.contextTokens)) {
+    return unsupported(apiVersion, 'INVALID_LIMIT')
+  }
+
+  let resetAt: number | undefined
+  if ('reset' in input) return unsupported(apiVersion, 'INVALID_RESET')
+  if ('resetAt' in input) {
+    const value = input.resetAt
+    if (!isFiniteNonNegativeNumber(value)) return unsupported(apiVersion, 'INVALID_RESET')
+    resetAt = value
+  }
+
+  const data: ExactProviderUsageData = {
+    sessionId: input.sessionId,
+    providerId: input.providerId,
+    modelId: input.modelId,
+    usage: {
+      inputTokens: usage.inputTokens,
+      outputTokens: usage.outputTokens,
+    },
+    limit: { contextTokens: limit.contextTokens },
+  }
+  if (resetAt !== undefined) data.resetAt = resetAt
+
+  return { apiVersion, status: USAGE_STATUS.SUPPORTED, data }
+}
+
+/**
+ * Probe the V1 exact payload shape supplied by a caller.
+ *
+ * V1 does not inherit V2 capability, credentials, cache, or lifecycle data.
+ * The caller must pass the exact payload after its host-specific extraction.
+ */
+export function probeV1Capability(input: unknown): ProviderCapabilityResult {
+  return probeExactData('v1', input)
+}
+
+/**
+ * Probe the V2 exact payload shape supplied by a caller.
+ *
+ * V2 is intentionally independent from V1: no V1 event, retry, cache, or
+ * fallback value is consulted when the exact payload is absent.
+ */
+export function probeV2Capability(input: unknown): ProviderCapabilityResult {
+  return probeExactData('v2', input)
+}
+
+/** Validate one complete stream event using the same exact data contract. */
+export function validateProviderUsageEvent(input: unknown): ProviderUsageEvent | null {
+  if (!isRecord(input)) return null
+  if (!isNonEmptyString(input.eventId) || !isNonEmptyString(input.partId)) return null
+
+  const data = probeExactData('v1', input)
+  if (data.status !== USAGE_STATUS.SUPPORTED) return null
+
+  let sequence: number | undefined
+  if ('sequence' in input) {
+    const value = input.sequence
+    if (!isFiniteNonNegativeNumber(value) || !Number.isInteger(value)) return null
+    sequence = value
+  }
+  let observedAt: number | undefined
+  if ('observedAt' in input) {
+    const value = input.observedAt
+    if (!isFiniteNonNegativeNumber(value)) return null
+    observedAt = value
+  }
+
+  const event: ProviderUsageEvent = {
+    ...data.data,
+    eventId: input.eventId,
+    partId: input.partId,
+  }
+  if (sequence !== undefined) event.sequence = sequence
+  if (observedAt !== undefined) event.observedAt = observedAt
+  return event
+}