pantheon-opencode 1.5.0-beta.1 → 1.5.0-beta.11

package/src/pantheon/delegate-manager.ts

@@ -23,7 +23,16 @@
  * @module delegate-manager
  */
 
+import { z } from 'zod'
 import type { BackgroundJobBoard, BackgroundJobRecord } from './background-job-board.ts'
+import type { DelegationToolset } from './delegation.ts'
+import {
+  DELEGATION_DEFAULTS,
+  type DelegationClient,
+  readDelegationReport,
+} from './delegation-finalize.ts'
+import { createNativeProbe, type NativeProbeFn, type ProbeClient } from './native-probe.ts'
+import { classifyNativeResult, type NativeTaskStatus } from './native-task-status.ts'
 import {
   buildStopInstruction,
   cappedSummary,
@@ -59,6 +68,7 @@ export interface ManagerReceipt {
   id: string
   agent: string
   state: 'reconciled' | 'error'
+  status: NativeTaskStatus
   line: string
 }
 
@@ -95,10 +105,15 @@ export interface DelegateManagerOptions {
   keepCompleted?: number
   /** Per-agent step budgets (routing.yml max_steps). */
   stepCap?: StepCapTracker
+  /** Lazy capability probe, invoked once before the first native dispatch. */
+  nativeProbe?: NativeProbeFn
+  /** V1 client used by the lazy capability probe. */
+  probeClient?: ProbeClient
 }
 
 export interface DelegateManager {
   launch(args: LaunchArgs): Promise<ManagerReceipt>
+  ensureNativeAvailable(): Promise<NativeTaskStatus | undefined>
   read(idOrAlias: string): Promise<string>
   list(): Promise<string[]>
   recover(): Promise<void>
@@ -113,13 +128,40 @@ export function isDelegationEnabled(
   return (env.PANTHEON_DELEGATION ?? '').trim().toLowerCase() !== 'off'
 }
 
+export type DelegateMode = 'native' | 'legacy'
+export function resolveDelegateMode(
+  env: Record<string, string | undefined> = process.env,
+): DelegateMode {
+  return (env.PANTHEON_DELEGATE_MODE ?? '').trim().toLowerCase() === 'native' ? 'native' : 'legacy'
+}
+
 // ─── Helpers ───────────────────────────────────────────────────────────
 
 const LINE_MAX = 160
 
+/** Remove terminal escapes and control characters from untrusted child output. */
+export function sanitizeReceiptText(text: string): string {
+  let clean = ''
+  let skippingAnsi = false
+  for (const char of text) {
+    const code = char.charCodeAt(0)
+    if (skippingAnsi) {
+      if (code === 0x5b) continue
+      if (code >= 0x40 && code <= 0x7e) skippingAnsi = false
+      continue
+    }
+    if (code === 0x1b) {
+      skippingAnsi = true
+      continue
+    }
+    if (char === '\n' || char === '\t' || (code >= 0x20 && code <= 0x7e)) clean += char
+  }
+  return clean
+}
+
 function firstLine(text: string, max = 80): string {
   const line =
-    (text ?? '')
+    sanitizeReceiptText(text ?? '')
       .split('\n')
       .map((l) => l.trim())
       .find((l) => l !== '') ?? ''
@@ -168,21 +210,30 @@ export function createDelegateManager(options: DelegateManagerOptions): Delegate
     task,
     parentSessionID,
     env = process.env,
-    models = [],
+    models: modelsOpt = [],
     timeoutMs = 120_000,
     readTimeoutMs = 60_000,
-    foregroundFallback = true,
+    foregroundFallback: fgFallbackOpt = true,
     maxEntries = 50,
     keepCompleted = 10,
     stepCap,
+    nativeProbe,
+    probeClient,
   } = options
 
+  // Strict native mode: foregroundFallback and models are overridden.
+  // The user-facing options are ignored when PANTHEON_DELEGATE_MODE=native.
+  const isNativeMode = resolveDelegateMode(env) === 'native'
+  const foregroundFallback = isNativeMode ? false : fgFallbackOpt
+  const models = isNativeMode ? [] : modelsOpt
+
   // Synchronous in-flight reservations per agent: launch() must decide
   // background vs foreground BEFORE its first await, otherwise concurrent
   // launches without interleaved awaits would all see an empty board.
   const pendingByAgent = new Map<string, number>()
   let seq = 0
   const foregroundRecent: { agent: string; line: string; at: number }[] = []
+  let probeResult: Awaited<ReturnType<NativeProbeFn>> | null = null
 
   function pending(agent: string): number {
     return pendingByAgent.get(agent.toLowerCase()) ?? 0
@@ -194,6 +245,12 @@ export function createDelegateManager(options: DelegateManagerOptions): Delegate
     }
   }
 
+  async function ensureNativeAvailable(): Promise<NativeTaskStatus | undefined> {
+    if (!isNativeMode || nativeProbe === undefined || probeClient === undefined) return undefined
+    probeResult ??= await nativeProbe({ client: probeClient, parentSessionID })
+    return probeResult.status === 'AVAILABLE' ? undefined : probeResult.status
+  }
+
   async function runTask(
     agent: string,
     prompt: string,
@@ -239,6 +296,7 @@ export function createDelegateManager(options: DelegateManagerOptions): Delegate
     // acknowledgment that the result was consumed.
     const terminalState = job.state
     const failed = verifyError !== undefined || terminalState === 'error'
+    const status = classifyNativeResult(job, verifyError)
     // Auto-reconcile + delete the signal file on the spot.
     if (job.state !== 'reconciled') await board.markReconciled(taskID)
     await board.deleteSignal(alias)
@@ -252,7 +310,7 @@ export function createDelegateManager(options: DelegateManagerOptions): Delegate
           LINE_MAX,
         )
       : boardLine(settled ?? job)
-    return { id: taskID, agent: job.agent, state: failed ? 'error' : 'reconciled', line }
+    return { id: taskID, agent: job.agent, state: failed ? 'error' : 'reconciled', status, line }
   }
 
   /** Apply a terminal transition best-effort: a racing hook may have gotten there first. */
@@ -319,7 +377,33 @@ export function createDelegateManager(options: DelegateManagerOptions): Delegate
     )
     foregroundRecent.push({ agent: args.agent, line, at: Date.now() })
     if (foregroundRecent.length > 20) foregroundRecent.splice(0, foregroundRecent.length - 20)
-    return { id, agent: args.agent, state: ok ? 'reconciled' : 'error', line }
+    const status = classifyNativeResult(
+      {
+        taskID: id,
+        parentSessionID,
+        agent: args.agent,
+        description: args.description ?? firstLine(args.prompt, 120),
+        state: ok ? 'completed' : 'error',
+        timedOut: false,
+        alias: id,
+        launchedAt: Date.now(),
+        updatedAt: Date.now(),
+        totalErrors: 0,
+        timeoutCount: 0,
+        terminalUnreconciled: false,
+        contextFiles: [],
+        ...(ok
+          ? {
+              resultSummary: firstLine(
+                (outcome as { ok: true; result: NativeTaskResult }).result.content ?? '',
+                500,
+              ),
+            }
+          : {}),
+      },
+      ok ? undefined : (outcome as { ok: false; error?: string }).error,
+    )
+    return { id, agent: args.agent, state: ok ? 'reconciled' : 'error', status, line }
   }
 
   return {
@@ -332,13 +416,31 @@ export function createDelegateManager(options: DelegateManagerOptions): Delegate
         const maxSteps = stepCap.maxStepsFor(args.agent)
         if (stepCap.isCapped(args.agent)) {
           const line = cappedSummary(args.agent, maxSteps ?? DEFAULT_MAX_STEPS).slice(0, LINE_MAX)
-          return { id: `cap-${Date.now()}`, agent: args.agent, state: 'reconciled', line }
+          return {
+            id: `cap-${Date.now()}`,
+            agent: args.agent,
+            state: 'reconciled',
+            status: 'ESCALATE',
+            line,
+          }
         }
         const rec = stepCap.recordStep(args.agent)
         if (rec.capped && rec.maxSteps !== undefined) {
           prompt = `${args.prompt}${buildStopInstruction(args.agent, rec.maxSteps)}`
         }
       }
+      if (isNativeMode) {
+        const unavailableStatus = await ensureNativeAvailable()
+        if (unavailableStatus !== undefined) {
+          return {
+            id: `probe-${parentSessionID}`,
+            agent: args.agent,
+            state: 'error',
+            status: unavailableStatus,
+            line: `[native] ${args.agent} — native API ${unavailableStatus.toLowerCase()} — ERR`,
+          }
+        }
+      }
       // Synchronous routing decision: background when a slot is free,
       // foreground fallback when full, clean rejection otherwise.
       const free =
@@ -349,6 +451,7 @@ export function createDelegateManager(options: DelegateManagerOptions): Delegate
         `pantheon_delegate rejected: concurrency limit reached for agent "${args.agent}"`,
       )
     },
+    ensureNativeAvailable,
 
     async read(idOrAlias: string): Promise<string> {
       guardEnabled()
@@ -362,11 +465,11 @@ export function createDelegateManager(options: DelegateManagerOptions): Delegate
       if (terminal.state !== 'reconciled') await board.markReconciled(terminal.taskID)
       await board.deleteSignal(terminal.alias)
       if (terminal.state === 'error' && !terminal.resultSummary) {
-        return `# Delegation Report — ${terminal.alias}\n\nERROR: ${terminal.lastStatusError ?? 'failed'}\n`
+        return `# Delegation Report — ${terminal.alias}\n\nERROR: ${sanitizeReceiptText(terminal.lastStatusError ?? 'failed')}\n`
       }
       return (
         `# Delegation Report — ${terminal.alias}\n\n` +
-        `${terminal.resultSummary ?? terminal.lastStatusError ?? terminal.state}\n`
+        `${sanitizeReceiptText(terminal.resultSummary ?? terminal.lastStatusError ?? terminal.state)}\n`
       )
     },
 
@@ -382,3 +485,282 @@ export function createDelegateManager(options: DelegateManagerOptions): Delegate
     },
   }
 }
+
+// Native delegation tools live with the manager so the plugin mounts the
+// manager directly; there is intentionally no adapter or kill-switch wrapper.
+const delegateArgs = {
+  prompt: z.string().min(1),
+  agent: z.string().min(1),
+  description: z.string().optional(),
+  read_only: z.boolean().optional(),
+  model: z.string().optional(),
+} satisfies z.ZodRawShape
+const readArgs = { id: z.string().min(1) } satisfies z.ZodRawShape
+const listArgs = {} satisfies z.ZodRawShape
+export interface ToolContextLike {
+  sessionID: string
+  agent?: string
+}
+export interface SessionTaskOptions {
+  client: DelegationClient
+  board: BackgroundJobBoard
+  outputDir?: string
+  promptTimeoutMs?: number
+  settleTimeoutMs?: number
+}
+export function parseModelRef(model: string): { id: string; providerID: string } | undefined {
+  const idx = model.indexOf('/')
+  return idx > 0 && idx < model.length - 1
+    ? { providerID: model.slice(0, idx), id: model.slice(idx + 1) }
+    : undefined
+}
+export function extractOutputSection(md: string | undefined): string {
+  if (md === undefined) return ''
+  const at = md.indexOf('## Output')
+  const body = at < 0 ? md : md.slice(at + 9)
+  const errAt = body.indexOf('\n**Error**:')
+  return (errAt < 0 ? body : body.slice(0, errAt)).trim()
+}
+async function promptAccept(
+  client: DelegationClient,
+  taskID: string,
+  agent: string,
+  prompt: string,
+  model: string | undefined,
+  signal: AbortSignal | undefined,
+  timeoutMs: number,
+): Promise<void> {
+  const modelRef = model === undefined ? undefined : parseModelRef(model)
+  let timer: ReturnType<typeof setTimeout> | undefined
+  try {
+    await Promise.race([
+      client.session
+        .promptAsync({
+          path: { id: taskID },
+          body: {
+            agent,
+            ...(modelRef === undefined ? {} : { model: modelRef }),
+            parts: [{ type: 'text', text: prompt }],
+          },
+          ...(signal === undefined ? {} : { signal }),
+        })
+        .then(undefined, (error: unknown) => {
+          throw new Error(
+            `promptAsync rejected: ${error instanceof Error ? error.message : String(error)}`,
+          )
+        }),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`promptAsync timed out after ${timeoutMs}ms`)),
+          timeoutMs,
+        )
+        timer.unref?.()
+      }),
+    ])
+  } finally {
+    if (timer !== undefined) clearTimeout(timer)
+  }
+}
+export function createSessionTaskFn(options: SessionTaskOptions): NativeTaskFn {
+  const {
+    client,
+    board,
+    outputDir = DELEGATION_DEFAULTS.outputDir,
+    promptTimeoutMs = 60_000,
+    settleTimeoutMs = DELEGATION_DEFAULTS.timeoutMs,
+  } = options
+  return async ({ agent, prompt, model, signal, taskID }) => {
+    await promptAccept(client, taskID, agent, prompt, model, signal, promptTimeoutMs)
+    const terminal = await board.waitForTerminal(taskID, settleTimeoutMs)
+    const md = await readDelegationReport(outputDir, terminal)
+    return { content: extractOutputSection(md) || terminal.resultSummary || '' }
+  }
+}
+export interface NativeDelegateWiring {
+  board: BackgroundJobBoard
+  client: DelegationClient
+  outputDir?: string
+  env?: Record<string, string | undefined>
+  isRootSession: (sessionID: string) => boolean
+  registerChildSession?: (sessionID: string, parentID: string) => void
+  registerReadOnlySession?: (
+    sessionID: string,
+    info: { agent: string; readOnlyFlag?: boolean },
+  ) => void
+  isReadOnlyAgent?: (agent: string) => boolean
+  agentModel?: (agent: string) => string | undefined
+  managerOptions?: Partial<
+    Omit<DelegateManagerOptions, 'board' | 'task' | 'parentSessionID' | 'env'>
+  >
+  stepCap?: StepCapTracker
+}
+export interface NativeDelegateToolset {
+  pantheon_delegate: {
+    description: string
+    args: typeof delegateArgs
+    execute(args: z.infer<z.ZodObject<typeof delegateArgs>>, ctx: ToolContextLike): Promise<string>
+  }
+  pantheon_delegation_read: {
+    description: string
+    args: typeof readArgs
+    execute(args: z.infer<z.ZodObject<typeof readArgs>>, ctx: ToolContextLike): Promise<string>
+  }
+  pantheon_delegation_list: {
+    description: string
+    args: typeof listArgs
+    execute(args: z.infer<z.ZodObject<typeof listArgs>>, ctx: ToolContextLike): Promise<string>
+  }
+}
+function shortFirstLine(text: string, max = 60): string {
+  const line =
+    sanitizeReceiptText(text)
+      .split('\n')
+      .map((item) => item.trim())
+      .find(Boolean) ?? ''
+  return line.length > max ? `${line.slice(0, max - 1)}…` : line
+}
+export function createNativeDelegateTools(wiring: NativeDelegateWiring): NativeDelegateToolset {
+  const {
+    board,
+    client,
+    env = process.env,
+    isRootSession,
+    registerChildSession,
+    registerReadOnlySession,
+    isReadOnlyAgent,
+    agentModel,
+    managerOptions = {},
+    stepCap,
+  } = wiring
+  const task = createSessionTaskFn({
+    client,
+    board,
+    ...(wiring.outputDir === undefined ? {} : { outputDir: wiring.outputDir }),
+    ...(managerOptions.timeoutMs === undefined
+      ? {}
+      : { promptTimeoutMs: managerOptions.timeoutMs }),
+  })
+  const managers = new Map<string, DelegateManager>()
+  const managerFor = (parentSessionID: string): DelegateManager => {
+    const existing = managers.get(parentSessionID)
+    if (existing !== undefined) return existing
+    const nativeProbe = createNativeProbe()
+    const manager = createDelegateManager({
+      ...managerOptions,
+      board,
+      task,
+      parentSessionID,
+      env,
+      ...(stepCap === undefined ? {} : { stepCap }),
+      nativeProbe,
+      probeClient: client,
+    })
+    managers.set(parentSessionID, manager)
+    return manager
+  }
+  return {
+    pantheon_delegate: {
+      description: 'Dispatch a background agent as a child session and return a verified receipt.',
+      args: delegateArgs,
+      execute: async (args, ctx) => {
+        if (!isDelegationEnabled(env))
+          throw new Error('pantheon delegation disabled (PANTHEON_DELEGATION=off)')
+        if (!isRootSession(ctx.sessionID))
+          throw new Error(
+            `pantheon_delegate rejected: session ${ctx.sessionID} is a sub-session — only root sessions can delegate`,
+          )
+        const manager = managerFor(ctx.sessionID)
+        const unavailableStatus = await manager.ensureNativeAvailable()
+        if (unavailableStatus !== undefined) {
+          return `status: ${unavailableStatus}\n[native] ${args.agent} — native API ${unavailableStatus.toLowerCase()} — ERR`
+        }
+        const model = args.model ?? agentModel?.(args.agent)
+        let childID: string
+        try {
+          const modelRef = model === undefined ? undefined : parseModelRef(model)
+          const created = await client.session.create({
+            body: {
+              parentID: ctx.sessionID,
+              title: args.description ?? shortFirstLine(args.prompt),
+              ...(modelRef === undefined ? {} : { model: modelRef }),
+            },
+          })
+          childID = created.id
+        } catch (error) {
+          return `pantheon_delegate failed: session.create rejected: ${sanitizeReceiptText(error instanceof Error ? error.message : String(error))}`
+        }
+        registerChildSession?.(childID, ctx.sessionID)
+        if (args.read_only === true || isReadOnlyAgent?.(args.agent) === true)
+          registerReadOnlySession?.(childID, {
+            agent: args.agent,
+            ...(args.read_only === undefined ? {} : { readOnlyFlag: args.read_only }),
+          })
+        const receipt = await manager.launch({
+          agent: args.agent,
+          prompt: args.prompt,
+          ...(args.description === undefined ? {} : { description: args.description }),
+          ...(args.model === undefined ? {} : { model: args.model }),
+          taskID: childID,
+        })
+        return `status: ${receipt.status}\n${receipt.line}`
+      },
+    },
+    pantheon_delegation_read: {
+      description: 'Block until a delegation finishes, then return its verified report.',
+      args: readArgs,
+      execute: async (args, ctx) => {
+        if (!isDelegationEnabled(env))
+          throw new Error('pantheon delegation disabled (PANTHEON_DELEGATION=off)')
+        return managerFor(ctx.sessionID).read(args.id)
+      },
+    },
+    pantheon_delegation_list: {
+      description: 'List background delegations.',
+      args: listArgs,
+      execute: async (_args, ctx) => {
+        if (!isDelegationEnabled(env))
+          throw new Error('pantheon delegation disabled (PANTHEON_DELEGATION=off)')
+        const lines = await managerFor(ctx.sessionID).list()
+        return lines.length > 0 ? lines.join('\n') : 'No delegations.'
+      },
+    },
+  }
+}
+export interface PluginNativeDelegationWiring {
+  board: BackgroundJobBoard
+  client: DelegationClient
+  isRootSession: (sessionID: string) => boolean
+  registerChildSession: (sessionID: string, parentID: string) => void
+  registerReadOnlySession: (
+    sessionID: string,
+    info: { agent: string; readOnlyFlag?: boolean },
+  ) => void
+  readOnlyAgents: ReadonlySet<string>
+  agentModels: Record<string, string | undefined>
+  stepCap: StepCapTracker
+  wallClockTimeoutMs?: number
+  finalizeDelegation: DelegationToolset['finalizeDelegation']
+}
+export type PluginNativeDelegation = NativeDelegateToolset & {
+  finalizeDelegation: DelegationToolset['finalizeDelegation']
+}
+export function buildPluginNativeDelegation(
+  wiring: PluginNativeDelegationWiring,
+): PluginNativeDelegation {
+  return {
+    ...createNativeDelegateTools({
+      board: wiring.board,
+      client: wiring.client,
+      isRootSession: wiring.isRootSession,
+      registerChildSession: wiring.registerChildSession,
+      registerReadOnlySession: wiring.registerReadOnlySession,
+      isReadOnlyAgent: (agent) => wiring.readOnlyAgents.has(agent.toLowerCase()),
+      agentModel: (agent) => wiring.agentModels[agent.toLowerCase()],
+      stepCap: wiring.stepCap,
+      ...(wiring.wallClockTimeoutMs === undefined
+        ? {}
+        : { managerOptions: { timeoutMs: wiring.wallClockTimeoutMs } }),
+    }),
+    finalizeDelegation: wiring.finalizeDelegation,
+  }
+}

package/src/pantheon/delegation-finalize.ts

@@ -144,9 +144,25 @@ export interface DelegationOptions {
   promptTimeoutMs?: number
   /** Poll interval used by the bootstrap watchdog. */
   bootstrapPollIntervalMs?: number
+  /**
+   * Max completed jobs to keep per agent after pruning (default: 10).
+   * Matches the native delegate-manager default.
+   */
+  keepCompleted?: number
+  /**
+   * Hard cap on total board entries (default: 50).
+   * Matches the native delegate-manager default.
+   */
+  maxEntries?: number
   /** Injectable clock/sleeper for deterministic watchdog tests. */
   now?: () => number
   sleep?: (ms: number) => Promise<void>
+  /**
+   * Kill-switch: when false, all delegation tools (delegate/read/list) throw
+   * immediately. Mirrors `PANTHEON_DELEGATION=off` from the native manager.
+   * Defaults to true (delegation enabled) when not specified.
+   */
+  delegationEnabled?: boolean
 }
 
 /** Dependencies threaded to the finalize path. */
@@ -370,5 +386,21 @@ export async function finalizeDelegation(
     // Terminal in a DIFFERENT state (e.g. timeout already recorded) — the
     // report above still captures this finalize; the board state stands.
   }
+
+  // P1-1: Delete the auto-wake signal file to prevent leaks. The board
+  // writes .signal.json on every terminal transition, but the legacy path
+  // never called deleteSignal — only the native delegate-manager did.
+  // The consumer (auto-wake.ts consumeWakeSignals) is intentionally NOT
+  // wired in the event hook: finalizeDelegation already handles the
+  // terminal transition, so consuming signals would be redundant and risks
+  // double-processing. deleteSignal on finalize is sufficient.
+  await deps.board.deleteSignal(job.alias)
+
+  // P1-4: Prune old completed jobs and enforce the hard entry cap. The
+  // native delegate-manager called these in settle(), but the legacy
+  // finalize path omitted them, allowing unbounded board growth.
+  await deps.board.pruneCompleted(deps.options.keepCompleted ?? 10)
+  await deps.board.enforceEntryCap(deps.options.maxEntries ?? 50)
+
   return deps.board.get(childSessionID) ?? job
 }