pantheon-opencode 1.4.3 → 1.5.0-beta.10

package/src/pantheon/v2-bridge.ts

@@ -0,0 +1,129 @@
+/**
+ * V1→V2 Bridge — passes V1 infrastructure singletons through V2 context options.
+ *
+ * The V2 plugin (`plugin-v2.ts`) registers tools via `ctx.tool.transform()` but
+ * lacks the runtime singletons (BackgroundJobBoard, delegation client, goal store,
+ * todo enforcer, vision handler) that live in the V1 plugin. This bridge:
+ *
+ *   1. Wraps V1 singletons into a portable `PantheonV2Bridge` interface.
+ *   2. Attaches the bridge to V2 `ctx.options` so V2 tool handlers can access it.
+ *   3. Provides `getV2BridgeFromContext()` for V2 tools to retrieve the bridge.
+ *
+ * Design: the bridge is **optional** — V2 plugin works without it (graceful
+ * fallback with limited functionality). V1 and V2 are never directly coupled;
+ * communication is via the `PantheonV2Bridge` interface only.
+ *
+ * @module v2-bridge
+ */
+
+import type { BackgroundJobBoard } from './background-job-board.ts'
+import type { DelegationClient } from './delegation-finalize.ts'
+import type { GoalStore } from './goal-store.ts'
+import type { TodoEnforcer } from './todo-enforcer.ts'
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/**
+ * Minimal structural view of the V2 PluginContext — we only need `options`
+ * to inject/retrieve the bridge. Avoids importing V2 SDK types directly.
+ */
+export interface V2ContextLike {
+  options: Record<string, unknown>
+}
+
+/** Structural view of the V1 PluginInput — the fields the bridge needs. */
+export interface V1PluginInput {
+  client: unknown
+  directory: string
+}
+
+/**
+ * Vision handler surface — the subset of the V1 vision handler the bridge
+ * exposes. Full type is the return of `createVisionHandler(input)`, but we
+ * only need the hook functions for V2 event delegation.
+ */
+export interface VisionHandler {
+  chatMessage: (...args: unknown[]) => Promise<void>
+  messagesTransform: (...args: unknown[]) => Promise<void>
+  event: (...args: unknown[]) => Promise<void>
+}
+
+/**
+ * Full bridge interface — all V1 infrastructure V2 tools need.
+ *
+ * Every field is optional to support partial initialization and graceful
+ * degradation when V1 infrastructure is not available.
+ */
+export interface PantheonV2Bridge {
+  /** Background job board — tracks running/completed/cancelled delegated jobs. */
+  board?: BackgroundJobBoard
+  /** Structural delegation client — creates child sessions and sends prompts. */
+  delegationClient?: DelegationClient
+  /** Goal store — file-based persistence for full-auto goal loop. */
+  goalStore?: GoalStore
+  /** Todo enforcer — idle continuation when todos are incomplete. */
+  todoEnforcer?: TodoEnforcer
+  /** Vision handler — image analysis, chat message enrichment, event handling. */
+  visionHandler?: VisionHandler
+}
+
+/**
+ * Extended V2 context options that carry the bridge.
+ * The bridge is attached under the `__pantheonV1Bridge` key to avoid
+ * collisions with user-defined options.
+ */
+export const BRIDGE_OPTIONS_KEY = '__pantheonV1Bridge' as const
+
+// ─── Bridge Factory ────────────────────────────────────────────────────
+
+/**
+ * Create a bridge from V1 singletons.
+ *
+ * Call this inside the V1 plugin's `setup()` AFTER the singletons are
+ * initialized, then pass the result to V2 via `ctx.options`.
+ *
+ * @example
+ * ```ts
+ * // In V1 plugin setup (plugin.ts):
+ * const bridge = createV2Bridge({ board, delegationClient, goalStore, ... })
+ * // Then pass bridge to V2 context via options
+ * ```
+ */
+export function createV2Bridge(singletons: PantheonV2Bridge): PantheonV2Bridge {
+  // Return a frozen copy — bridge consumers must not mutate singletons.
+  return Object.freeze({ ...singletons })
+}
+
+/**
+ * Retrieve the bridge from a V2 PluginContext.
+ *
+ * Returns `null` when the bridge was not injected (V2 running standalone
+ * or V1 not yet initialized). V2 tools should check for null and
+ * degrade gracefully.
+ *
+ * @example
+ * ```ts
+ * // In a V2 tool handler:
+ * const bridge = getV2BridgeFromContext(ctx)
+ * if (!bridge?.board) {
+ *   return { text: 'Background job board unavailable — delegation disabled.' }
+ * }
+ * ```
+ */
+export function getV2BridgeFromContext(ctx: V2ContextLike): PantheonV2Bridge | null {
+  const bridge = ctx.options[BRIDGE_OPTIONS_KEY]
+  if (bridge != null && typeof bridge === 'object') {
+    return bridge as PantheonV2Bridge
+  }
+  return null
+}
+
+/**
+ * Inject the bridge into a V2 PluginContext's options.
+ *
+ * Call this in the V1 plugin to make the bridge available to V2 tools.
+ * Safe to call multiple times — subsequent calls overwrite the previous bridge.
+ */
+export function injectBridge(ctx: V2ContextLike, bridge: PantheonV2Bridge): void {
+  ctx.options[BRIDGE_OPTIONS_KEY] = bridge
+}

package/src/pantheon/v2-events.ts

@@ -0,0 +1,148 @@
+/**
+ * V2 Event Handlers — Pantheon event subscriptions for the V2 plugin API.
+ *
+ * Subscribes to session lifecycle events (created, idle, error, compacted)
+ * and routes them to the appropriate subsystem:
+ * - session.created → seed session hierarchy + root sessions
+ * - session.idle → delegation finalize / goal loop / todo enforcer
+ * - session.error → delegation finalize as error
+ * - session.compacted → todo preserve / compaction context
+ *
+ * These handlers are PURE — they depend only on structural interfaces,
+ * not on the V1 PluginInput or V2 PluginContext.
+ *
+ * @module pantheon/v2-events
+ */
+
+import type { BackgroundJobBoard } from './background-job-board.ts'
+import type { FinalizeInput } from './delegation-finalize.ts'
+import type { DelegationEventDeps, DelegationEventLike } from './delegation-notify.ts'
+import { handleDelegationEvent } from './delegation-notify.ts'
+import type { GoalLoopLike, TodoEnforcerLike } from './idle-continuation.ts'
+import { createIdleDispatcher, type IdleDispatcher } from './idle-continuation.ts'
+import { createPantheonLogger } from './logger.ts'
+
+const log = createPantheonLogger({ module: 'pantheon-v2-events' })
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+/**
+ * Structural session info from session.created events.
+ */
+export interface SessionInfo {
+  id: string
+  parentID?: string
+}
+
+/**
+ * Structural event from the V2 event stream.
+ */
+export interface V2SessionEvent {
+  type: string
+  properties?: Record<string, unknown>
+}
+
+/**
+ * Dependencies for the V2 event dispatcher.
+ */
+export interface V2EventDeps {
+  board: BackgroundJobBoard
+  finalize: (childSessionID: string, opts: FinalizeInput) => Promise<unknown>
+  goalLoop: GoalLoopLike
+  todoEnforcer: TodoEnforcerLike
+  /** Callback to register a session in the hierarchy. */
+  registerSession?: (info: SessionInfo) => void
+  /** Callback to add a session as root. */
+  addRootSession?: (sessionID: string) => void
+}
+
+/**
+ * V2 Event Dispatcher — routes session events to subsystems.
+ */
+export interface V2EventDispatcher {
+  /** Process a session event. Returns true if handled. */
+  handleEvent(event: V2SessionEvent): Promise<boolean>
+  /** Cleanup subscriptions. */
+  dispose(): void
+}
+
+// ─── Implementation ──────────────────────────────────────────────────────
+
+/**
+ * Create the V2 event dispatcher. Routes session lifecycle events to
+ * delegation finalize, goal loop, and todo enforcer.
+ *
+ * Usage:
+ * ```ts
+ * const dispatcher = createV2EventDispatcher(deps)
+ * // In event subscription loop:
+ * for await (const event of ctx.event.subscribe(...)) {
+ *   await dispatcher.handleEvent(event)
+ * }
+ * ```
+ */
+export function createV2EventDispatcher(deps: V2EventDeps): V2EventDispatcher {
+  const delegationDeps: DelegationEventDeps = {
+    board: deps.board,
+    finalize: deps.finalize,
+  }
+  const idleDispatcher: IdleDispatcher = createIdleDispatcher({
+    goalLoop: deps.goalLoop,
+    todoEnforcer: deps.todoEnforcer,
+  })
+
+  return {
+    handleEvent: async (event: V2SessionEvent): Promise<boolean> => {
+      try {
+        // session.created → seed hierarchy + board put-if-absent for native children
+        if (event.type === 'session.created') {
+          const info = event.properties?.info as SessionInfo | undefined
+          if (info) {
+            deps.registerSession?.(info)
+            if (info.parentID === undefined) {
+              deps.addRootSession?.(info.id)
+            } else {
+              // Native task(background=true) child: register on the board
+              // atomically (skip if V1 idle hook or re-dispatch already claimed it).
+              try {
+                await deps.board.registerLaunchIfAbsent({
+                  taskID: info.id,
+                  parentSessionID: info.parentID,
+                  agent: 'native',
+                  description: `native child ${info.id}`,
+                })
+              } catch (err) {
+                // The per-agent concurrency limit can refuse the launch. Do not
+                // abort the rest of the handler: this child is simply not
+                // mirrored on the board, while finalize/idle dispatch for every
+                // other event must still run.
+                log.warn(`[Pantheon V2] native child ${info.id} not mirrored on board:`, err)
+              }
+            }
+          }
+        }
+
+        // Delegate to handleDelegationEvent (covers idle + error for board children)
+        const delegated = await handleDelegationEvent(event as DelegationEventLike, delegationDeps)
+
+        // Non-board idle → idle dispatcher (goal loop / todo enforcer)
+        if (!delegated && event.type === 'session.idle') {
+          const sessionID = event.properties?.sessionID as string | undefined
+          if (sessionID) {
+            await idleDispatcher.onIdle(sessionID)
+          }
+        }
+
+        return delegated
+      } catch (err) {
+        log.error('[Pantheon V2] Event handling failed:', err)
+        return false
+      }
+    },
+
+    dispose: () => {
+      // No persistent subscriptions to clean up — the event stream
+      // lifecycle is managed by the caller.
+    },
+  }
+}

package/src/pantheon/v2-hooks.ts

@@ -0,0 +1,287 @@
+/**
+ * V2 Session Hooks — Pantheon session hooks for the V2 plugin API.
+ *
+ * Provides two hook types:
+ * - `"prompt"` hook: Vision message interception (paste-and-ask). Intercepts
+ *   user messages with pasted images and replaces them with text instructions
+ *   or native vision descriptions.
+ * - `"context"` hook: Inject routing policy, active goals, and pending todos
+ *   into the system context before each LLM call.
+ *
+ * These handlers are PURE — they depend only on structural interfaces.
+ *
+ * @module pantheon/v2-hooks
+ */
+
+import type { BackgroundJobBoard } from './background-job-board.ts'
+import { buildCompactionContext } from './delegation-compaction.ts'
+import type { GoalStore } from './goal-loop.ts'
+import { createPantheonLogger } from './logger.ts'
+import type { TodoEnforcer } from './todo-enforcer.ts'
+
+const log = createPantheonLogger({ module: 'pantheon-v2-hooks' })
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+/**
+ * Structural context event passed to the "context" hook.
+ * V2 API: `ctx.session.hook("context", (event) => { ... })`
+ */
+export interface V2ContextHookEvent {
+  sessionID: string
+  // Unknown: host beta may send string, string[], SystemPart objects
+  // ({type,text}), mixed arrays, or non-array. Narrow internally (fail-open).
+  system: unknown
+  generation: {
+    temperature?: number
+  }
+}
+
+/**
+ * Structural prompt event passed to the "prompt" hook.
+ * V2 API: `ctx.session.hook("prompt", (event) => { ... })`
+ */
+export interface V2PromptHookEvent {
+  sessionID: string
+  message: unknown
+}
+
+/**
+ * Dependencies for session hooks.
+ */
+export interface V2HookDeps {
+  board: BackgroundJobBoard
+  goalStore: GoalStore
+  todoEnforcer: TodoEnforcer
+}
+
+// ─── Context Hook ────────────────────────────────────────────────────────
+
+const POLICY_MARKER = '<!-- pantheon-v2-policy -->'
+const ROUTING_POLICY =
+  `${POLICY_MARKER}\nFollow Pantheon routing policy: delegate implementation work ` +
+  `to the named specialist and do not claim work was performed without verification.`
+
+/** Default max compaction items (matching routing.yml background_delegation.max_compaction_items). */
+const DEFAULT_MAX_COMPACTION_ITEMS = 10
+
+/**
+ * Extract comparable text from a system entry: plain string or
+ * SystemPart-like object ({type,text}). Returns null for junk (null/number).
+ * Runtime sniffing: pinned SDK (@opencode-ai/plugin 1.18.18) only knows
+ * string/string[] — host beta sends objects. Never throws (fail-open).
+ */
+function systemEntryText(entry: unknown): string | null {
+  try {
+    if (typeof entry === 'string') return entry
+    if (
+      typeof entry === 'object' &&
+      entry !== null &&
+      typeof (entry as { text?: unknown }).text === 'string'
+    ) {
+      return (entry as { text: string }).text
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+function hasPolicyMarker(arr: unknown[]): boolean {
+  try {
+    return arr.some((s) => {
+      const t = systemEntryText(s)
+      return t?.includes(POLICY_MARKER) ?? false
+    })
+  } catch {
+    return false
+  }
+}
+
+function usesObjectShape(arr: unknown[]): boolean {
+  try {
+    return arr.some(
+      (s) =>
+        typeof s === 'object' && s !== null && typeof (s as { text?: unknown }).text === 'string',
+    )
+  } catch {
+    return false
+  }
+}
+
+function toSystemEntry(text: string, useObject: boolean): string | { type: 'text'; text: string } {
+  return useObject ? { type: 'text', text } : text
+}
+
+/**
+ * Context hook handler — injects Pantheon policy, routing, and compaction
+ * state into the system context before each LLM call.
+ *
+ * Registered via: `ctx.session.hook("context", handler)`
+ */
+export function createV2ContextHookHandler(deps: V2HookDeps) {
+  return async (event: V2ContextHookEvent): Promise<void> => {
+    try {
+      // Beta 19192 hardening (defense-in-depth) + SystemPart sniffing: the
+      // host may send string[], SystemPart objects ({type,text}), mixed
+      // arrays, a single string, or a non-array system. Preserve the string
+      // path behavior; inject object shape when the array contains objects
+      // (else host schema validation fails on system[N]). Never throw.
+      const rawSystem: unknown = (event as { system?: unknown } | null | undefined)?.system
+      let system: unknown[]
+      if (typeof rawSystem === 'string') {
+        system = rawSystem.includes(POLICY_MARKER) ? [rawSystem] : [rawSystem, ROUTING_POLICY]
+        ;(event as { system?: unknown }).system = system
+      } else if (Array.isArray(rawSystem)) {
+        // 1. Inject routing policy if not already present (string OU .text)
+        if (!hasPolicyMarker(rawSystem)) {
+          rawSystem.push(toSystemEntry(ROUTING_POLICY, usesObjectShape(rawSystem)))
+        }
+        system = rawSystem
+      } else {
+        // Non-string, non-array system: ignore silently (fail-open).
+        return
+      }
+
+      // 2. Inject compaction context (active goals, pending todos, delegations)
+      // Convert blocks to the same shape as the host array (object vs string).
+      const blocks = await buildCompactionContext(deps.board, {
+        sessionID: event.sessionID,
+        maxItems: DEFAULT_MAX_COMPACTION_ITEMS,
+        goals: {
+          enabled: true,
+          list: (sessionID: string) => deps.goalStore.list(sessionID),
+        },
+        todos: {
+          enabled: true,
+          list: (sessionID: string) => deps.todoEnforcer.listPendingTodos(sessionID),
+        },
+      })
+      if (blocks.length > 0) {
+        const useObject = usesObjectShape(system)
+        for (const b of blocks) {
+          system.push(useObject ? { type: 'text' as const, text: b } : b)
+        }
+      }
+
+      // 3. Apply conservative temperature for routing decisions
+      const generation = (event as { generation?: { temperature?: number } }).generation
+      if (generation != null && generation.temperature === undefined) {
+        generation.temperature = 0.2
+      }
+    } catch (err) {
+      log.warn('[Pantheon V2] Context hook failed:', err)
+      // Fail-open: never break the session
+    }
+  }
+}
+
+// ─── Prompt Hook ─────────────────────────────────────────────────────────
+
+/**
+ * Prompt hook handler — intercepts user messages for vision processing.
+ *
+ * Registered via: `ctx.session.hook("prompt", handler)`
+ *
+ * Note: The full vision handler is complex (file I/O, provider API calls).
+ * This is a minimal adapter that delegates to the V1 vision handler
+ * if available. Without vision infrastructure, it's a no-op.
+ */
+export function createV2PromptHookHandler(_deps: V2HookDeps) {
+  return async (event: V2PromptHookEvent): Promise<void> => {
+    // Vision interception is a complex subsystem (see src/pantheon/vision.ts).
+    // The V2 prompt hook delegates to the V1 vision handler via the plugin's
+    // integration point. Without V1 client access, this is a graceful no-op.
+    //
+    // TODO: Wire full vision handler when V2 provides SDK client access.
+    void event
+  }
+}
+
+// ─── Tool Hooks ──────────────────────────────────────────────────────────
+
+/**
+ * Tool execute.before hook — enforces read-only restrictions, command
+ * normalization, and todo preservation.
+ *
+ * Registered via: `ctx.tool.hook("execute.before", handler)`
+ */
+export interface V2ToolBeforeEvent {
+  tool: string
+  sessionID: string
+  callID: string
+  args?: unknown
+}
+
+export function createV2ToolBeforeHookHandler(
+  enforcementGuard: (
+    input: { tool: string; sessionID: string; callID: string },
+    output?: { args?: unknown },
+  ) => void,
+  commandNormalizer: (
+    input: { tool: string; sessionID: string; callID: string },
+    output?: { args?: unknown },
+  ) => Promise<void>,
+) {
+  return async (event: V2ToolBeforeEvent): Promise<void> => {
+    try {
+      enforcementGuard(
+        { tool: event.tool, sessionID: event.sessionID, callID: event.callID },
+        { args: event.args },
+      )
+      await commandNormalizer(
+        { tool: event.tool, sessionID: event.sessionID, callID: event.callID },
+        { args: event.args },
+      )
+    } catch (err) {
+      log.warn('[Pantheon V2] Tool before-hook failed:', err)
+    }
+  }
+}
+
+/**
+ * Tool execute.after hook — augments read output with hashline tags
+ * and applies context sandbox truncation.
+ *
+ * Registered via: `ctx.tool.hook("execute.after", handler)`
+ */
+export interface V2ToolAfterEvent {
+  tool: string
+  sessionID: string
+  callID: string
+  args?: unknown
+  // The host may send a non-string output (shape drift on beta). Keep this
+  // honest as unknown and narrow with typeof at the use site — never assume.
+  output: unknown
+}
+
+export function createV2ToolAfterHookHandler(
+  readEnhancer: (
+    input: { tool: string; sessionID: string; callID: string; args?: unknown },
+    output: { output: string },
+  ) => Promise<void>,
+  sandboxHandler: (
+    input: { tool: string; sessionID: string; callID: string; args?: unknown },
+    output: { output: string },
+  ) => Promise<void>,
+) {
+  return async (event: V2ToolAfterEvent): Promise<void> => {
+    try {
+      const input = {
+        tool: event.tool,
+        sessionID: event.sessionID,
+        callID: event.callID,
+        args: event.args,
+      }
+      // Narrow the honest unknown: only strings flow through the enhancers.
+      // Non-string output is left untouched (fail-open, preserve host shape).
+      if (typeof event.output !== 'string') return
+      const output = { output: event.output }
+      await sandboxHandler(input, output)
+      await readEnhancer(input, output)
+      event.output = output.output
+    } catch (err) {
+      log.warn('[Pantheon V2] Tool after-hook failed:', err)
+    }
+  }
+}