@defrex/autobuild 0.8.0

package/packages/core/src/ports/runner/pi.ts

@@ -0,0 +1,617 @@
+/** AgentRunner adapter for the operator's locally installed Pi CLI. */
+import semver from 'semver'
+import type { StreamPart } from '../../store/streams/types'
+import {
+  agentInvocation,
+  type AgentContinueOpts,
+  type AgentRunner,
+  type AgentSessionHandle,
+  type AgentStartOpts,
+  type AgentTurnFailure,
+  type AgentTurnResult,
+  type SessionStreamEmitter,
+  type Transcript,
+} from '../types'
+import type { OneShotCompletion, OneShotCompletionInput, OneShotCompletionResult } from './one-shot'
+import { classifyProviderError, configurationFailure, credentialFailure } from './provider-error'
+import { createPiRpcSession, PI_MODEL_ARG, PI_RPC_MODE_ARG } from './pi-rpc'
+import {
+  abortPart,
+  errorPart,
+  finishPart,
+  finishStepPart,
+  promptPart,
+  reasoningDeltaPart,
+  reasoningEndPart,
+  reasoningStartPart,
+  startPart,
+  startStepPart,
+  textDeltaPart,
+  textEndPart,
+  textStartPart,
+  toolInputPart,
+  toolOutputPart,
+} from './stream-parts'
+import type { RuntimeUsabilityInput, RuntimeUsabilityResult } from './runtime'
+import { sessionEnv } from './session-env'
+
+export const MINIMUM_PI_VERSION = '0.84.3'
+const PI_TOOLS = ['read', 'bash', 'edit', 'write', 'grep', 'find', 'ls'] as const
+
+export interface PiModelRef {
+  provider: string
+  id: string
+}
+
+export function parsePiModel(model: string): PiModelRef {
+  const slash = model.indexOf('/')
+  if (slash <= 0 || slash === model.length - 1) {
+    throw new Error(
+      `pi runtime: model "${model}" is not provider-qualified — expected "<provider>/<id>". ` +
+        'Run `ab models <query>` to look up an id.',
+    )
+  }
+  return { provider: model.slice(0, slash), id: model.slice(slash + 1) }
+}
+
+export function parsePiModelCatalog(output: string): PiModelRef[] {
+  const lines = output
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+  const header = lines.shift()?.split(/\s{2,}/)
+  if (
+    header === undefined ||
+    header.length < 3 ||
+    header[0] !== 'provider' ||
+    header[1] !== 'model'
+  ) {
+    throw new Error('expected a header beginning with "provider" and "model" columns')
+  }
+
+  return lines.map((line, index) => {
+    const columns = line.split(/\s{2,}/)
+    if (columns.length !== header.length || columns[0] === '' || columns[1] === '') {
+      throw new Error(`row ${index + 1} does not match the catalog header`)
+    }
+    return { provider: columns[0]!, id: columns[1]! }
+  })
+}
+
+export interface PiCliInvocation {
+  args: string[]
+  cwd: string
+  env: Record<string, string>
+}
+
+export interface PiCliResult {
+  stdout: string
+  stderr: string
+  exitCode: number
+}
+
+export type PiCliRunFn = (invocation: PiCliInvocation) => Promise<PiCliResult>
+
+export const runPiCli: PiCliRunFn = async (invocation) => {
+  const proc = Bun.spawn(['pi', ...invocation.args], {
+    cwd: invocation.cwd,
+    env: invocation.env,
+    stdin: 'ignore',
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ])
+  return { stdout, stderr, exitCode }
+}
+
+export interface PiPrerequisite {
+  version: string
+}
+
+export async function checkLocalPi(
+  cwd: string,
+  env: Record<string, string>,
+  runCli: PiCliRunFn = runPiCli,
+): Promise<PiPrerequisite> {
+  let result: PiCliResult
+  try {
+    result = await runCli({ args: ['--version'], cwd, env })
+  } catch (error) {
+    if (isEnoent(error)) {
+      throw new Error(
+        'pi runtime: Pi CLI executable "pi" was not found. Install Pi, run `pi` and log in, then retry.',
+      )
+    }
+    throw new Error(`pi runtime: failed to launch Pi CLI executable "pi": ${errorText(error)}`)
+  }
+  const detected = result.stdout.trim()
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `pi runtime: "pi --version" exited with code ${result.exitCode}: ${result.stderr.trim() || detected || 'no diagnostic'}`,
+    )
+  }
+  const version = semver.valid(detected)
+  if (version === null) {
+    throw new Error(`pi runtime: could not parse detected Pi version "${detected || '(empty)'}"`)
+  }
+  if (semver.lt(version, MINIMUM_PI_VERSION)) {
+    throw new Error(
+      `pi runtime: detected Pi ${version}, but Autobuild requires Pi ${MINIMUM_PI_VERSION} or newer. Upgrade the local "pi" executable.`,
+    )
+  }
+  return { version }
+}
+
+export async function isPiRuntimeUsable(
+  input: RuntimeUsabilityInput,
+  runCli: PiCliRunFn = runPiCli,
+): Promise<RuntimeUsabilityResult> {
+  if (input.models.length === 0) {
+    return { usable: false, reason: 'Pi has no default model configured to probe' }
+  }
+  const env = cleanEnv(input.env)
+  try {
+    await checkLocalPi(input.cwd, env, runCli)
+    let catalog: PiModelRef[] | undefined
+    for (const model of new Set(input.models)) {
+      const modelRef = parsePiModel(model)
+      const result = await runCli({
+        args: ['auth', 'check', '--model', model, '--json'],
+        cwd: input.cwd,
+        env,
+      })
+      let payload: unknown
+      try {
+        payload = JSON.parse(result.stdout)
+      } catch {
+        return {
+          usable: false,
+          reason: `Pi authentication check for model "${model}" returned malformed JSON`,
+        }
+      }
+      const status = isRecord(payload) ? payload.status : undefined
+      if (result.exitCode !== 0 || status !== 'ready') {
+        const reason =
+          isRecord(payload) && typeof payload.reason === 'string' ? ` (${payload.reason})` : ''
+        return {
+          usable: false,
+          reason: `Pi model "${model}" is not ready with the configured provider credentials${reason}`,
+        }
+      }
+
+      if (catalog === undefined) {
+        let catalogResult: PiCliResult
+        try {
+          catalogResult = await runCli({ args: ['--list-models'], cwd: input.cwd, env })
+        } catch (error) {
+          return {
+            usable: false,
+            reason: `Pi local model catalog probe failed to launch: ${errorText(error)}`,
+          }
+        }
+        if (catalogResult.exitCode !== 0) {
+          return {
+            usable: false,
+            reason: `Pi local model catalog probe failed: "pi --list-models" exited with code ${catalogResult.exitCode}: ${catalogResult.stderr.trim() || catalogResult.stdout.trim() || 'no diagnostic'}`,
+          }
+        }
+        try {
+          catalog = parsePiModelCatalog(catalogResult.stdout)
+        } catch (error) {
+          return {
+            usable: false,
+            reason: `Pi local model catalog probe returned a malformed table: ${errorText(error)}`,
+          }
+        }
+      }
+      if (
+        !catalog.some(
+          (candidate) => candidate.provider === modelRef.provider && candidate.id === modelRef.id,
+        )
+      ) {
+        return {
+          usable: false,
+          reason: `Pi model "${model}" is unavailable from the local Pi model catalog`,
+        }
+      }
+    }
+    return { usable: true, reason: 'Local Pi CLI, model catalog, and authentication are available' }
+  } catch (error) {
+    return { usable: false, reason: errorText(error) }
+  }
+}
+
+/** Options that select the model or the RPC protocol parsed by the adapter. */
+export const PI_OWNED_ARGS = [PI_RPC_MODE_ARG, PI_MODEL_ARG] as const
+
+export interface PiTurn {
+  text: string
+  usage: { inputTokens: number; outputTokens: number }
+  failure?: AgentTurnFailure
+}
+
+export interface PiSession {
+  readonly sessionId: string
+  prompt(text: string, env: Record<string, string>, signal?: AbortSignal): Promise<PiTurn>
+  dispose(): Promise<void> | void
+}
+
+export type PiCreateSessionFn = (opts: {
+  cwd: string
+  model?: PiModelRef
+  tools: readonly string[]
+  args: readonly string[]
+  skill?: string
+  env: Record<string, string>
+  /** Session-event observer for stream translation (SPEC §9); fakes may
+   * invoke it to deliver native session events during a prompt. */
+  onEvent?: (event: JsonRecord) => void
+}) => Promise<PiSession>
+
+const createLocalPiSession: PiCreateSessionFn = async (opts) => {
+  await checkLocalPi(opts.cwd, opts.env)
+  return createPiRpcSession(opts)
+}
+
+interface TurnRecord {
+  turn: number
+  prompt: string
+  text: string
+  usage: { inputTokens: number; outputTokens: number }
+  failure?: AgentTurnFailure
+}
+
+type JsonRecord = Record<string, unknown>
+
+/** Per-session event hook: the current turn's translator, or none between
+ * turns. Prompts are sequential per session, so one slot is safe. */
+interface PiTurnEventHook {
+  translator?: PiTurnTranslator
+}
+
+interface SessionState {
+  opts: AgentStartOpts
+  model?: string
+  session?: PiSession
+  /** Set whenever the session was created through a path that could deliver
+   * native events; a turn without a stream leaves it unused. */
+  turnEvents?: PiTurnEventHook
+  turns: TurnRecord[]
+}
+
+/**
+ * Maps Pi's native session events onto the stream part vocabulary (SPEC §9).
+ * Unrecognized events produce no parts (fail open); the harness outcome is
+ * remembered so a turn ending in a provider abort emits an `abort` part
+ * rather than `error`.
+ */
+interface PiTurnTranslator {
+  onEvent(event: JsonRecord): void
+  /** Set when `message_end` carried stopReason "aborted". */
+  aborted(): boolean
+}
+
+function createPiTurnTranslator(emit: (parts: StreamPart[]) => void): PiTurnTranslator {
+  let nextId = 0
+  let textId: string | undefined
+  let thinkingId: string | undefined
+  let aborted = false
+
+  const blockId = (event: JsonRecord, current: string | undefined): string => {
+    const existing = event.id
+    if (typeof existing === 'string' && existing.length > 0) return existing
+    return current ?? `pi-${++nextId}`
+  }
+
+  return {
+    onEvent(event) {
+      switch (event.type) {
+        case 'agent_start':
+        case 'turn_start':
+          emit([startStepPart()])
+          break
+        case 'message_update': {
+          const update = isRecord(event.assistantMessageEvent) ? event.assistantMessageEvent : {}
+          switch (update.type) {
+            case 'text_start':
+              textId = blockId(update, textId ?? `pi-${++nextId}`)
+              emit([textStartPart(textId)])
+              break
+            case 'text_delta':
+              textId ??= `pi-${++nextId}`
+              if (typeof update.delta === 'string') emit([textDeltaPart(textId, update.delta)])
+              break
+            case 'text_end':
+              emit([textEndPart(blockId(update, textId ?? `pi-${++nextId}`))])
+              textId = undefined
+              break
+            case 'thinking_start':
+              thinkingId = blockId(update, thinkingId ?? `pi-${++nextId}`)
+              emit([reasoningStartPart(thinkingId)])
+              break
+            case 'thinking_delta':
+              thinkingId ??= `pi-${++nextId}`
+              if (typeof update.delta === 'string') {
+                emit([reasoningDeltaPart(thinkingId, update.delta)])
+              }
+              break
+            case 'thinking_end':
+              emit([reasoningEndPart(blockId(update, thinkingId ?? `pi-${++nextId}`))])
+              thinkingId = undefined
+              break
+            default:
+              break
+          }
+          break
+        }
+        case 'tool_execution_start': {
+          const toolCallId =
+            typeof event.toolCallId === 'string' ? event.toolCallId : `pi-${++nextId}`
+          const toolName = typeof event.toolName === 'string' ? event.toolName : 'tool'
+          emit([toolInputPart(toolCallId, toolName, event.args ?? {})])
+          break
+        }
+        case 'tool_execution_end': {
+          const toolCallId =
+            typeof event.toolCallId === 'string' ? event.toolCallId : `pi-${++nextId}`
+          emit([toolOutputPart(toolCallId, event.result ?? null)])
+          break
+        }
+        case 'message_end': {
+          const message = isRecord(event.message) ? event.message : {}
+          if (message.stopReason === 'aborted') aborted = true
+          break
+        }
+        case 'turn_end':
+          emit([finishStepPart()])
+          break
+        default:
+          break
+      }
+    },
+    aborted() {
+      return aborted
+    },
+  }
+}
+
+export class PiAgentRunner implements AgentRunner, OneShotCompletion {
+  readonly name = 'pi'
+  private readonly createSessionFn: PiCreateSessionFn
+  private readonly createSessionId: () => string
+  private readonly sessions = new Map<string, SessionState>()
+
+  constructor(opts: { createSessionFn?: PiCreateSessionFn; createSessionId?: () => string } = {}) {
+    this.createSessionFn = opts.createSessionFn ?? createLocalPiSession
+    this.createSessionId = opts.createSessionId ?? (() => crypto.randomUUID())
+  }
+
+  async complete(input: OneShotCompletionInput): Promise<OneShotCompletionResult> {
+    const model = input.model !== undefined ? parsePiModel(input.model) : undefined
+    const session = await this.createSessionFn({
+      cwd: input.cwd,
+      ...(model !== undefined ? { model } : {}),
+      tools: [],
+      args: input.args ?? [],
+      env: sessionEnv(input.env),
+    })
+    try {
+      const turn = await session.prompt(input.prompt, sessionEnv(input.env), input.signal)
+      if (turn.failure !== undefined) throw new Error(turn.failure.message)
+      return { text: turn.text }
+    } finally {
+      await session.dispose()
+    }
+  }
+
+  async start(
+    opts: AgentStartOpts,
+  ): Promise<{ session: AgentSessionHandle; result: AgentTurnResult }> {
+    const model = opts.model !== undefined ? parsePiModel(opts.model) : undefined
+    const prompt = `/skill:${opts.skill} ${agentInvocation(opts)}`
+    let native: PiSession | undefined
+    let turn: PiTurn
+    const turnEvents: PiTurnEventHook = {}
+    try {
+      native = await this.createSessionFn({
+        cwd: opts.workspacePath,
+        ...(model !== undefined ? { model } : {}),
+        tools: PI_TOOLS,
+        args: opts.args ?? [],
+        skill: opts.skill,
+        env: sessionEnv(opts.env),
+        // Stream translation is per turn; the hook stays live for later
+        // continued turns even when turn 1 streams nothing.
+        onEvent: (event) => turnEvents.translator?.onEvent(event),
+      })
+      turn = await this.runPrompt(
+        native,
+        prompt,
+        this.turnEnv(opts.env),
+        opts.signal,
+        opts.stream,
+        turnEvents,
+      )
+    } catch (error) {
+      turn = {
+        text: '',
+        usage: { inputTokens: 0, outputTokens: 0 },
+        failure: localPiFailure(error),
+      }
+    }
+    const id = native?.sessionId ?? this.createSessionId()
+    const handle: AgentSessionHandle = {
+      id,
+      runner: this.name,
+      ...(opts.model !== undefined ? { model: opts.model } : {}),
+    }
+    this.sessions.set(id, {
+      opts,
+      ...(opts.model !== undefined ? { model: opts.model } : {}),
+      ...(native !== undefined ? { session: native } : {}),
+      ...(native !== undefined ? { turnEvents } : {}),
+      turns: [this.turnRecord(1, prompt, turn)],
+    })
+    return { session: handle, result: this.toResult(turn) }
+  }
+
+  async continue(
+    handle: AgentSessionHandle,
+    message: string,
+    opts?: AgentContinueOpts,
+  ): Promise<AgentTurnResult> {
+    const state = this.liveState(handle, 'continue')
+    if (state.session === undefined) {
+      throw new Error(`pi: cannot continue session "${handle.id}" because local Pi failed to start`)
+    }
+    const scoped = opts?.env !== undefined ? { ...state.opts.env, ...opts.env } : state.opts.env
+    const turn = await this.runPrompt(
+      state.session,
+      message,
+      this.turnEnv(scoped),
+      opts?.signal,
+      opts?.stream,
+      state.turnEvents,
+    )
+    state.turns.push(this.turnRecord(state.turns.length + 1, message, turn))
+    return this.toResult(turn)
+  }
+
+  async end(handle: AgentSessionHandle): Promise<Transcript> {
+    const state = this.liveState(handle, 'end')
+    this.sessions.delete(handle.id)
+    await state.session?.dispose()
+    const usage = { inputTokens: 0, outputTokens: 0, turns: 0 }
+    for (const turn of state.turns) {
+      usage.inputTokens += turn.usage.inputTokens
+      usage.outputTokens += turn.usage.outputTokens
+      usage.turns += 1
+    }
+    return {
+      content: JSON.stringify(
+        {
+          session: handle.id,
+          skill: state.opts.skill,
+          invocation: agentInvocation(state.opts),
+          ...(state.opts.buildSlug !== undefined ? { buildSlug: state.opts.buildSlug } : {}),
+          turns: state.turns,
+        },
+        null,
+        2,
+      ),
+      metadata: {
+        runner: this.name,
+        ...(state.model !== undefined ? { model: state.model } : {}),
+        usage,
+      },
+    }
+  }
+
+  private async runPrompt(
+    session: PiSession,
+    prompt: string,
+    env: Record<string, string>,
+    signal?: AbortSignal,
+    stream?: SessionStreamEmitter,
+    turnEvents?: PiTurnEventHook,
+  ): Promise<PiTurn> {
+    if (stream !== undefined) stream.append([promptPart(prompt), startPart(crypto.randomUUID())])
+    const translator =
+      stream !== undefined ? createPiTurnTranslator((parts) => stream.append(parts)) : undefined
+    if (translator !== undefined && turnEvents !== undefined) turnEvents.translator = translator
+    try {
+      const turn = await session.prompt(prompt, env, signal)
+      if (stream !== undefined) {
+        if (turn.failure === undefined) {
+          stream.append([finishPart()])
+        } else if (translator?.aborted() === true || signal?.aborted === true) {
+          stream.append([abortPart(turn.failure.message)])
+        } else {
+          stream.append([errorPart(turn.failure.message)])
+        }
+      }
+      return turn
+    } catch (error) {
+      const failure = localPiFailure(error)
+      if (stream !== undefined) {
+        if (signal?.aborted) {
+          stream.append([abortPart(error instanceof Error ? error.message : String(error))])
+        } else if (translator?.aborted() === true) {
+          stream.append([abortPart(failure.message)])
+        } else {
+          stream.append([errorPart(failure.message)])
+        }
+      }
+      return {
+        text: '',
+        usage: { inputTokens: 0, outputTokens: 0 },
+        failure,
+      }
+    } finally {
+      if (translator !== undefined && turnEvents !== undefined) turnEvents.translator = undefined
+    }
+  }
+
+  private liveState(handle: AgentSessionHandle, operation: 'continue' | 'end'): SessionState {
+    const state = this.sessions.get(handle.id)
+    if (state === undefined) throw new Error(`pi: ${operation} on unknown session "${handle.id}"`)
+    return state
+  }
+
+  private turnRecord(number: number, prompt: string, turn: PiTurn): TurnRecord {
+    return {
+      turn: number,
+      prompt,
+      text: turn.text,
+      usage: turn.usage,
+      ...(turn.failure !== undefined ? { failure: turn.failure } : {}),
+    }
+  }
+
+  private toResult(turn: PiTurn): AgentTurnResult {
+    const base = { text: turn.text, usage: { ...turn.usage, turns: 1 } }
+    return turn.failure === undefined
+      ? { kind: 'completed', ...base }
+      : { kind: 'failed', ...base, failure: turn.failure }
+  }
+
+  private turnEnv(scoped: Record<string, string>): Record<string, string> {
+    return sessionEnv(scoped)
+  }
+}
+
+function localPiFailure(error: unknown): AgentTurnFailure {
+  const message = errorText(error)
+  if (
+    /executable "pi" was not found|requires Pi .* or newer|could not parse detected Pi version/.test(
+      message,
+    )
+  ) {
+    return configurationFailure(message)
+  }
+  if (/not ready|authentication|logged in|credentials/i.test(message))
+    return credentialFailure(message)
+  return classifyProviderError(message)
+}
+
+function cleanEnv(env: Readonly<Record<string, string | undefined>>): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(env).filter((entry): entry is [string, string] => entry[1] !== undefined),
+  )
+}
+
+function isEnoent(error: unknown): boolean {
+  return isRecord(error) && error.code === 'ENOENT'
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/packages/core/src/ports/runner/production.ts

@@ -0,0 +1,74 @@
+/**
+ * Production runtime registrations shared by every sessionless CLI path that
+ * needs agent judgment. Keeping the shipped adapters and their model families
+ * here prevents dispatch and other non-phase one-shots from drifting apart.
+ */
+import {
+  CLAUDE_OWNED_ARGS,
+  CLAUDE_PROMPT_BOUNDARY,
+  ClaudeAgentRunner,
+  isClaudeRuntimeUsable,
+} from './claude'
+import {
+  CODEX_OWNED_ARGS,
+  CODEX_PROMPT_BOUNDARY,
+  CodexAgentRunner,
+  isCodexRuntimeUsable,
+} from './codex'
+import { isPiRuntimeUsable, PI_OWNED_ARGS, PiAgentRunner } from './pi'
+import type { SessionStreamInfo, RuntimeRegistry } from './runtime'
+import type { SessionStreamSink } from '../types'
+
+export interface ProductionRuntimes {
+  runtimes: RuntimeRegistry
+}
+
+export function createProductionRuntimes(): ProductionRuntimes {
+  // Each adapter carries both the resumable AgentRunner contract and its
+  // optional tool-free OneShotCompletion capability.
+  const claude = new ClaudeAgentRunner()
+  const codex = new CodexAgentRunner()
+  const pi = new PiAgentRunner()
+
+  return {
+    runtimes: {
+      claude: {
+        runner: claude,
+        oneShot: claude,
+        initUsable: isClaudeRuntimeUsable,
+        servesModels: ['claude-'],
+        ownedArgs: CLAUDE_OWNED_ARGS,
+        promptBoundary: CLAUDE_PROMPT_BOUNDARY,
+        openSessionStream: openSessionStreamLabel,
+      },
+      codex: {
+        runner: codex,
+        oneShot: codex,
+        initUsable: isCodexRuntimeUsable,
+        // Codex CLI model ids are unqualified; an omitted model delegates to
+        // the operator's configured Codex default.
+        servesModels: ['gpt-'],
+        ownedArgs: CODEX_OWNED_ARGS,
+        promptBoundary: CODEX_PROMPT_BOUNDARY,
+        openSessionStream: openSessionStreamLabel,
+      },
+      pi: {
+        runner: pi,
+        oneShot: pi,
+        initUsable: isPiRuntimeUsable,
+        // The local Pi installation owns the provider catalog. Any
+        // provider-qualified model it resolves is valid here.
+        servesModels: ['*/*'],
+        defaultModel: 'kimi-coding/k3',
+        ownedArgs: PI_OWNED_ARGS,
+        openSessionStream: openSessionStreamLabel,
+      },
+    },
+  }
+}
+
+/** The one shared opener: a session bracket's stream is labeled by its
+ * Autobuild session id, never a harness-native session/thread id. */
+function openSessionStreamLabel(sink: SessionStreamSink, info: SessionStreamInfo): Promise<string> {
+  return sink.open(`session:${info.session}`)
+}