pantheon-opencode 1.4.3 → 1.5.0-beta.1

package/src/pantheon/delegation-classifier.ts

@@ -0,0 +1,307 @@
+/**
+ * Delegation Classifier — stuck-agent detection for delegation results.
+ *
+ * Classifies delegation results into actionable statuses:
+ *   - `content` / `success` — agent returned usable output
+ *   - `empty` (empty-mode1 / empty-mode2) — no or near-no output; retryable
+ *   - `budget-exhausted` — agent hit max_steps; partial result available
+ *   - `timeout` (timeout-with-partial / timeout-empty / timeout-exhausted)
+ *   - `error` — provider or infrastructure failure
+ *
+ * Integrates with the existing `dispatch-guard.ts` classification for
+ * empty-response detection and provides a structured `DelegationResult`
+ * that replaces raw-text returns.
+ *
+ * @module delegation-classifier
+ */
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Empty-response mode classification (matches dispatch-guard). */
+export type EmptyMode = 'empty-mode1' | 'empty-mode2'
+
+/** Timeout sub-type based on partial output and retry history. */
+export type TimeoutSubType = 'timeout-with-partial' | 'timeout-empty' | 'timeout-exhausted'
+
+/** Structured delegation result replacing raw-text returns. */
+export interface DelegationResult {
+  status:
+    | 'success'
+    | 'empty'
+    | 'budget-exhausted'
+    | 'timeout'
+    | 'error'
+    | 'startup_failed'
+    | 'bootstrap_unknown'
+  content: string
+  retryCount: number
+  /** When status is 'empty', which empty mode was detected. */
+  classification?: EmptyMode | undefined
+  /** When status is 'timeout', the timeout sub-type. */
+  subType?: TimeoutSubType | undefined
+  /** Available when budget-exhausted or timeout-with-partial. */
+  partialResult?: string | undefined
+  /** Actionable recommendation for the orchestrator. */
+  recommendation?: string | undefined
+}
+
+/** Result of empty-response classification. */
+export interface EmptyClassification {
+  mode: EmptyMode | 'content'
+  hasContent: boolean
+  hasTokens: boolean
+}
+
+/** Timeout classification input. */
+export interface TimeoutClassifyInput {
+  /** Report markdown (undefined if no report was written). */
+  report: string | undefined
+  /** Whether the child session had any messages at all. */
+  hasMessages: boolean
+  /** How many retries have already been attempted (0 or 1). */
+  retryCount: number
+}
+
+/** Result of stuck-agent classification. */
+export interface StuckClassification {
+  status: 'success' | 'budget-exhausted' | 'empty'
+  partialResult?: string | undefined
+  recommendation?: string | undefined
+}
+
+// ─── Patterns ──────────────────────────────────────────────────────────
+
+/** Matches budget-exhausted messages from the agent or step-cap system. */
+const BUDGET_EXHAUSTED_RE =
+  /maximum\s+(?:steps?|step\s*budget)\s+(?:for\s+this\s+agent\s+)?(?:has|have)\s+been\s+reached|step\s*budget\s+(?:was\s+)?exhausted/i
+
+/** Output-captured marker in delegation reports. */
+const NO_OUTPUT_RE = /_No output captured\._/i
+
+// ─── Empty-Response Classification ────────────────────────────────────
+
+/**
+ * Classify whether a response is empty, empty-with-tokens, or has content.
+ * Matches the dispatch-guard classification (empty-mode1, empty-mode2).
+ *
+ * @param text The response text (may be null/undefined).
+ * @param tokens Optional token counts for mode2 detection.
+ */
+export function classifyEmptyResponse(
+  text: string | null | undefined,
+  tokens?: { tokensInput?: number; tokensOutput?: number },
+): EmptyClassification {
+  const hasContent = typeof text === 'string' && text.trim() !== ''
+  if (hasContent) {
+    return { mode: 'content', hasContent: true, hasTokens: hasTokens(tokens) }
+  }
+  const hasT = hasTokens(tokens)
+  return {
+    mode: hasT ? 'empty-mode2' : 'empty-mode1',
+    hasContent: false,
+    hasTokens: hasT,
+  }
+}
+
+/** Whether token counts indicate the model actually ran. */
+function hasTokens(tokens?: { tokensInput?: number; tokensOutput?: number }): boolean {
+  if (tokens === undefined) return false
+  return (tokens.tokensInput ?? 0) > 0 || (tokens.tokensOutput ?? 0) > 0
+}
+
+// ─── Stuck-Agent Detection ────────────────────────────────────────────
+
+/**
+ * Classify a report as success, budget-exhausted, or empty.
+ * Detects max-steps patterns in the report text.
+ *
+ * @param report The delegation report markdown.
+ */
+export function classifyStuckAgent(report: string): StuckClassification {
+  const trimmed = report.trim()
+
+  // Empty output
+  if (NO_OUTPUT_RE.test(trimmed) || trimmed === '') {
+    return { status: 'empty' }
+  }
+
+  // Budget-exhausted: extract content before the marker as partialResult
+  if (BUDGET_EXHAUSTED_RE.test(trimmed)) {
+    const outputSection = extractOutputSection(trimmed)
+    const partialResult =
+      outputSection !== undefined && !NO_OUTPUT_RE.test(outputSection) ? outputSection : undefined
+
+    return {
+      status: 'budget-exhausted',
+      partialResult,
+      recommendation:
+        'Agent hit step budget; partial result available. ' +
+        'Consider resuming with task_id or dispatching with larger budget.',
+    }
+  }
+
+  return { status: 'success' }
+}
+
+/** Extract the text after "## Output" in a delegation report, or undefined. */
+function extractOutputSection(report: string): string | undefined {
+  const marker = '## Output'
+  const idx = report.indexOf(marker)
+  if (idx === -1) return undefined
+  const afterMarker = report.slice(idx + marker.length)
+  // Skip the newline after "## Output"
+  const content = afterMarker.replace(/^\n+/, '')
+  // Stop at the next section (## or **Error**)
+  const endIdx = content.search(/\n(?:##|\*\*Error\*\*|\[TIMEOUT)/)
+  return endIdx === -1 ? content.trim() : content.slice(0, endIdx).trim()
+}
+
+// ─── Timeout Classification ───────────────────────────────────────────
+
+/**
+ * Classify a timeout based on available output and retry history.
+ *
+ * - timeout-empty: no report, no messages, not yet retried → retryable
+ * - timeout-with-partial: has report or messages → return partial
+ * - timeout-exhausted: already retried → escalate
+ *
+ * @param input Report availability, message presence, and retry count.
+ */
+export function classifyTimeout(input: TimeoutClassifyInput): DelegationResult {
+  const { report, hasMessages, retryCount } = input
+  const hasPartial =
+    (report !== undefined && report.trim() !== '' && !NO_OUTPUT_RE.test(report)) || hasMessages
+
+  // Already retried → exhausted, no more retries
+  if (retryCount >= 1) {
+    return {
+      status: 'timeout',
+      content: report ?? '',
+      retryCount,
+      subType: 'timeout-exhausted',
+      partialResult: hasPartial ? (report ?? '') : undefined,
+      recommendation:
+        'Agent timed out after retry. Options: ' +
+        '(a) try different agent, (b) simplify scope, (c) manual intervention.',
+    }
+  }
+
+  // Has partial output → return it
+  if (hasPartial) {
+    return {
+      status: 'timeout',
+      content: report ?? '',
+      retryCount,
+      subType: 'timeout-with-partial',
+      partialResult: report ?? '',
+      recommendation:
+        'Agent timed out but partial work exists. ' + 'Partial result is available above.',
+    }
+  }
+
+  // No output at all → retryable
+  return {
+    status: 'timeout',
+    content: report ?? '',
+    retryCount,
+    subType: 'timeout-empty',
+    recommendation: 'Agent timed out with no output. Will retry once with rephrased prompt.',
+  }
+}
+
+// ─── Result Helpers ───────────────────────────────────────────────────
+
+/**
+ * Whether a delegation result is retryable (empty + retryCount < 1,
+ * or timeout-empty + retryCount < 1).
+ */
+export function isRetryableResult(result: DelegationResult): boolean {
+  if (result.retryCount >= 1) return false
+  if (result.status === 'empty') return true
+  if (result.status === 'timeout' && result.subType === 'timeout-empty') return true
+  return false
+}
+
+/**
+ * Format a DelegationResult into a human-readable string for the orchestrator.
+ * Success results are returned as-is (the raw content). Non-success results
+ * get a structured status message.
+ */
+export function formatDelegationResult(result: DelegationResult): string {
+  if (result.status === 'success') {
+    return result.content
+  }
+
+  const parts: string[] = []
+
+  // Status header
+  switch (result.status) {
+    case 'empty': {
+      const modeLabel =
+        result.classification === 'empty-mode2'
+          ? 'empty-mode2 (reasoning tokens present but no text output)'
+          : 'empty-mode1 (no tokens generated)'
+      parts.push(`[EMPTY RESULT — ${modeLabel}]`)
+      if (result.retryCount === 0) {
+        parts.push(
+          'The agent returned an empty response. ' +
+            'A retry with a rephrased prompt has been triggered automatically.',
+        )
+      } else {
+        parts.push(
+          'The agent returned an empty response even after retry. ' +
+            'Options: (a) try different agent, (b) simplify scope, (c) manual intervention.',
+        )
+      }
+      break
+    }
+    case 'budget-exhausted':
+      parts.push('[BUDGET EXHAUSTED]')
+      if (result.partialResult) {
+        parts.push('Partial result:')
+        parts.push(result.partialResult)
+      }
+      parts.push(result.recommendation ?? '')
+      break
+    case 'timeout': {
+      const subLabel =
+        result.subType === 'timeout-with-partial'
+          ? 'with partial output'
+          : result.subType === 'timeout-exhausted'
+            ? 'exhausted after retry'
+            : 'no output'
+      parts.push(`[TIMEOUT — ${subLabel}]`)
+      if (result.partialResult) {
+        parts.push('Partial result:')
+        parts.push(result.partialResult)
+      }
+      parts.push(result.recommendation ?? '')
+      break
+    }
+    case 'error':
+      parts.push('[ERROR]')
+      parts.push(result.content)
+      break
+    case 'startup_failed':
+      parts.push('[STARTUP FAILED]')
+      parts.push(result.content)
+      parts.push(
+        result.recommendation ??
+          'Retry once or inspect the child session before dispatching again.',
+      )
+      break
+    case 'bootstrap_unknown':
+      parts.push('[BOOTSTRAP UNKNOWN]')
+      parts.push(result.content)
+      parts.push(
+        result.recommendation ?? 'The host did not expose enough session state to verify startup.',
+      )
+      break
+  }
+
+  // Structured fields for non-success results
+  parts.push(`status: ${result.status}`)
+  parts.push(`retryCount: ${result.retryCount}`)
+
+  return parts.filter((p) => p !== '').join('\n')
+}

package/src/pantheon/delegation-enforce.ts

@@ -1,7 +1,7 @@
 /**
  * Read-Only Enforcement (Phase 4) — deny mutating tools inside sessions that
- * were delegated as read-only (advisory `read_only: true` on the native
- * `task` delegate, or the agent ∈ `readOnlyAgents` from routing.yml).
+ * were delegated as read-only (advisory `read_only: true` on
+ * pantheon_delegate, or the agent ∈ `readOnlyAgents` from routing.yml).
  *
  * OpenCode hook: `tool.execute.before`. The hook shape is
  * `(input, output) => Promise<void>`; THROWING from the hook denies the tool
@@ -18,11 +18,11 @@
  *   - `task` is blocked too, which hard-enforces depth-2: a read-only agent
  *     cannot spawn its own subagents.
  *
- * Unknown sessions are allowed for ordinary tools. The runtime matrix is
- * fail-closed when wired: missing agent identity or
+ * Unknown sessions are allowed for ordinary tools. Delegation tools are
+ * fail-closed when the runtime matrix is wired: missing agent identity or
  * target metadata is denied rather than inferred.
  *
- * The registry is populated at delegate time: the CHILD
+ * The registry is populated by delegation.ts at delegate time: the CHILD
  * session is registered when the delegate call is read-only.
  *
  * @module delegation-enforce
@@ -147,6 +147,7 @@ export function isDelegationAllowed(
 function targetFromTool(tool: string, args: unknown): string | undefined {
   if (args === null || typeof args !== 'object') return undefined
   const record = args as Record<string, unknown>
+  if (tool === 'pantheon_delegate') return normalizeDelegationAgent(record.agent)
   if (tool === 'task') {
     return normalizeDelegationAgent(record.subagent_type ?? record.subagentType)
   }
@@ -235,7 +236,7 @@ export function zeusReadGuard(tool: string, args: unknown, agent: string | undef
 // ─── Registry ──────────────────────────────────────────────────────────
 
 /**
- * Read-only session registry. The plugin's delegate wiring registers child
+ * Read-only session registry. `createDelegationTools` registers child
  * sessions here; the plugin's `tool.execute.before` guard consults it.
  * Process-wide singleton for plugin wiring + factory for test isolation.
  */
@@ -290,19 +291,19 @@ export function createEnforcementGuard(input: {
   options?: EnforcementGuardOptions
 }): ToolExecuteBeforeHandler {
   const blockedTools = input.options?.blockedTools ?? DEFAULT_BLOCKED_TOOLS
-  const prefix = input.options?.messagePrefix ?? 'delegation guard'
+  const prefix = input.options?.messagePrefix ?? 'pantheon_delegate guard'
 
   return async (hook: ToolExecuteBeforeInput, output?: ToolExecuteBeforeOutput): Promise<void> => {
-    const isDelegationTool = hook.tool === 'task'
+    const isDelegationTool = hook.tool === 'task' || hook.tool === 'pantheon_delegate'
     if (isDelegationTool && input.options?.isChildSession?.(hook.sessionID) === true) {
       throw new Error(
         `${prefix}: session ${hook.sessionID} is a child session — delegation tools are denied ` +
           'to prevent nested delegation',
       )
     }
-    // The native task() delegate has the authoritative ToolContext.agent at
-    // execution time, so its matrix check lives in dispatch-guard.ts. The hook
-    // only has the session-scoped agent learned from chat.params.
+    // pantheon_delegate has the authoritative ToolContext.agent at execution
+    // time, so its matrix check lives in delegation.ts. The hook only has the
+    // session-scoped agent learned from chat.params for native task().
     if (
       hook.tool === 'task' &&
       input.options?.isRootSession !== undefined &&
@@ -335,7 +336,7 @@ export function createEnforcementGuard(input: {
         `This session was delegated for investigation only (read-only agent); it cannot ` +
         `modify files, run commands, or spawn subagents. ` +
         `If a write result is needed, dispatch a write-capable agent ` +
-        `(e.g. hermes, aphrodite) with the native task() tool instead.`,
+        `(e.g. hermes, aphrodite) with pantheon_delegate instead.`,
     )
   }
 }