@defrex/autobuild 0.8.0

package/packages/core/src/ports/runner/json-record.ts

@@ -0,0 +1,2 @@
+/** Minimal JSON-object shape shared by stream writer internals. */
+export type JsonRecord = Record<string, unknown>

package/packages/core/src/ports/runner/live-contract-fixture.ts

@@ -0,0 +1,176 @@
+import { expect } from 'bun:test'
+import { chmod, copyFile, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { AgentRunner, AgentTurnResult, Transcript } from '../types'
+import type { OneShotCompletion } from './one-shot'
+import { AGENT_BIN_DIR } from './session-env'
+
+interface LiveFixture {
+  cwd: string
+  evidencePath: string
+  cleanup: () => Promise<void>
+}
+
+interface ProbeEvidence {
+  phase: string
+  retained: string
+  collide: string
+  abPath: string
+  helpStatus: string
+}
+
+async function createLiveFixture(): Promise<LiveFixture> {
+  const cwd = await mkdtemp(join(tmpdir(), 'ab-runner-live-contract-'))
+  const skillDir = join(cwd, '.agents', 'skills', 'ab-runner-contract')
+  const claudeSkills = join(cwd, '.claude', 'skills')
+  await mkdir(skillDir, { recursive: true })
+  await mkdir(claudeSkills, { recursive: true })
+  const skillPath = join(skillDir, 'SKILL.md')
+  await writeFile(
+    skillPath,
+    `---\nname: ab-runner-contract\ndescription: Live AgentRunner contract probe.\ndisable-model-invocation: true\n---\n\n# Runner contract probe\n\nImmediately use the bash tool to execute \`./contract-probe\` exactly once.\nWait for it to finish, then reply with the single word \`probed\`.\n`,
+  )
+  const claudeSkill = join(claudeSkills, 'ab-runner-contract')
+  try {
+    await symlink(skillDir, claudeSkill, 'dir')
+  } catch {
+    await mkdir(claudeSkill, { recursive: true })
+    await copyFile(skillPath, join(claudeSkill, 'SKILL.md'))
+  }
+
+  const evidencePath = join(cwd, 'contract-evidence.tsv')
+  const probePath = join(cwd, 'contract-probe')
+  await writeFile(
+    probePath,
+    `#!/bin/sh\nset -eu\nab_path="$(command -v ab)"\nif ab --help >/dev/null 2>&1; then help=0; else help=$?; fi\nprintf '%s\\t%s\\t%s\\t%s\\t%s\\n' "\${AB_CONTRACT_PHASE:-}" "\${AB_CONTRACT_RETAINED:-}" "\${AB_CONTRACT_COLLIDE:-}" "$ab_path" "$help" >> ${JSON.stringify(evidencePath)}\n`,
+  )
+  await chmod(probePath, 0o755)
+  return {
+    cwd,
+    evidencePath,
+    cleanup: () => rm(cwd, { recursive: true, force: true }),
+  }
+}
+
+async function evidence(path: string): Promise<ProbeEvidence[]> {
+  const content = await readFile(path, 'utf8')
+  return content
+    .trim()
+    .split('\n')
+    .filter((line) => line !== '')
+    .map((line) => {
+      const [phase = '', retained = '', collide = '', abPath = '', helpStatus = ''] =
+        line.split('\t')
+      return { phase, retained, collide, abPath, helpStatus }
+    })
+}
+
+function expectCompleted(result: AgentTurnResult): void {
+  expect(result.kind).toBe('completed')
+  expect(Number.isInteger(result.usage.inputTokens)).toBe(true)
+  expect(Number.isInteger(result.usage.outputTokens)).toBe(true)
+  expect(result.usage.turns).toBeGreaterThan(0)
+}
+
+function expectTranscript(transcript: Transcript, runner: AgentRunner, model: string): void {
+  expect(transcript.content.trim()).not.toBe('')
+  expect(transcript.metadata.runner).toBe(runner.name)
+  expect(transcript.metadata.model).toBe(model)
+  expect(transcript.metadata.usage.turns).toBeGreaterThanOrEqual(2)
+}
+
+/** Successful real-provider smoke coverage. Deterministic failure taxonomy is
+ * deliberately covered by the full injected adapter contract instead. */
+export async function runLiveAgentRunnerContract(
+  runner: AgentRunner & OneShotCompletion,
+  model: string,
+): Promise<void> {
+  const fixture = await createLiveFixture()
+  let failure: unknown
+  try {
+    const started = await runner.start({
+      skill: 'ab-runner-contract',
+      invocation: 'live-contract',
+      workspacePath: fixture.cwd,
+      model,
+      env: {
+        AB_CONTRACT_PHASE: 'start',
+        AB_CONTRACT_RETAINED: 'retained',
+        AB_CONTRACT_COLLIDE: 'start-value',
+      },
+    })
+    let transcript: Transcript | undefined
+    try {
+      expect(started.session.id.trim()).not.toBe('')
+      expect(started.session.runner).toBe(runner.name)
+      expect(started.session.model).toBe(model)
+      expectCompleted(started.result)
+      expect(await evidence(fixture.evidencePath)).toEqual([
+        {
+          phase: 'start',
+          retained: 'retained',
+          collide: 'start-value',
+          abPath: join(AGENT_BIN_DIR, 'ab'),
+          helpStatus: '0',
+        },
+      ])
+
+      const continued = await runner.continue(
+        started.session,
+        'Use the bash tool to execute `./contract-probe` exactly once, wait for it, then reply with exactly the same single word as your previous response.',
+        {
+          env: {
+            AB_CONTRACT_PHASE: 'continue',
+            AB_CONTRACT_COLLIDE: 'continue-value',
+          },
+        },
+      )
+      expectCompleted(continued)
+      expect(continued.text.trim()).toBe('probed')
+      expect(await evidence(fixture.evidencePath)).toEqual([
+        {
+          phase: 'start',
+          retained: 'retained',
+          collide: 'start-value',
+          abPath: join(AGENT_BIN_DIR, 'ab'),
+          helpStatus: '0',
+        },
+        {
+          phase: 'continue',
+          retained: 'retained',
+          collide: 'continue-value',
+          abPath: join(AGENT_BIN_DIR, 'ab'),
+          helpStatus: '0',
+        },
+      ])
+    } catch (error) {
+      failure = error
+    }
+
+    try {
+      transcript = await runner.end(started.session)
+    } catch (endError) {
+      if (failure !== undefined) {
+        throw new AggregateError(
+          [failure, endError],
+          'live AgentRunner assertion and session end both failed',
+        )
+      }
+      throw endError
+    }
+    if (failure !== undefined) throw failure
+    expectTranscript(transcript, runner, model)
+
+    const nonce = crypto.randomUUID()
+    const oneShot = await runner.complete({
+      prompt: `Reply with exactly this token and no other text: ${nonce}`,
+      cwd: fixture.cwd,
+      env: { AB_CONTRACT_ONE_SHOT: nonce },
+      model,
+    })
+    expect(oneShot.text.trim()).toContain(nonce)
+  } finally {
+    await fixture.cleanup()
+  }
+}

package/packages/core/src/ports/runner/one-shot.ts

@@ -0,0 +1,29 @@
+/**
+ * A narrow, tool-free, non-phase judgment capability. Unlike AgentRunner,
+ * one-shot completions have no resumable session, skill invocation,
+ * transcript, or typed terminal: callers provide one prompt and consume text
+ * as an untrusted proposal behind deterministic validation.
+ */
+
+export interface OneShotCompletionInput {
+  prompt: string
+  /** Working directory used for project context and runtime resolution. */
+  cwd: string
+  /** Runtime environment (credentials, provider settings, and so on). */
+  env: Record<string, string>
+  /** Absent means the runtime's own default model. */
+  model?: string
+  /** Extra CLI argv tokens for the selected runtime, in declared order. */
+  args?: readonly string[]
+  /** Caller-owned cancellation, normally a deterministic deadline. */
+  signal?: AbortSignal
+}
+
+export interface OneShotCompletionResult {
+  text: string
+}
+
+/** Optional capability carried by a runtime registration. */
+export interface OneShotCompletion {
+  complete(input: OneShotCompletionInput): Promise<OneShotCompletionResult>
+}

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

@@ -0,0 +1,136 @@
+export interface BridgeToolSourceInfo {
+  origin?: string
+  source?: string
+}
+
+export interface BridgeTool {
+  name: string
+  sourceInfo?: BridgeToolSourceInfo
+}
+
+export interface BridgeApi {
+  getAllTools(): BridgeTool[]
+  setActiveTools(names: string[]): void
+  registerTool(tool: unknown): void
+  on(event: 'session_start', handler: (event: unknown, context: { cwd: string }) => void): void
+  registerCommand(
+    name: string,
+    command: {
+      description: string
+      handler: (args: string, context: BridgeCommandContext) => Promise<void>
+    },
+  ): void
+}
+
+export interface BridgeCommandContext {
+  modelRegistry: {
+    getAll(): Array<{ provider: string; id: string }>
+    getAvailable(): Array<{ provider: string; id: string }>
+  }
+  ui: { notify(message: string, type: 'info'): void }
+}
+
+export type BridgeBashToolFactory = (
+  cwd: string,
+  options: {
+    spawnHook: (input: { env?: Record<string, string>; [key: string]: unknown }) => {
+      env: Record<string, string>
+      [key: string]: unknown
+    }
+  },
+) => unknown
+
+const BUILTIN_TOOL_NAMES = new Set(['read', 'bash', 'edit', 'write', 'grep', 'find', 'ls'])
+const CATALOG_PREFIX = 'autobuild-pi-catalog:'
+
+export function selectActiveToolNames(
+  tools: readonly BridgeTool[],
+  baseTools: readonly string[],
+): string[] {
+  const allowedBase = new Set(baseTools)
+  return [
+    ...new Set(
+      tools
+        .filter((tool) => {
+          if (BUILTIN_TOOL_NAMES.has(tool.name)) return allowedBase.has(tool.name)
+          // Ambient discovery is disabled by the adapter. Every remaining
+          // non-builtin tool came from an explicitly loaded extension. An
+          // empty builtin allowlist marks a tool-free one-shot invocation.
+          return baseTools.length > 0
+        })
+        .map((tool) => tool.name),
+    ),
+  ]
+}
+
+export function installAutobuildBridge(pi: BridgeApi, createBashTool: BridgeBashToolFactory): void {
+  let environment: Record<string, string> = {}
+  let baseTools: string[] = []
+
+  const activateTools = (): void => {
+    pi.setActiveTools(selectActiveToolNames(pi.getAllTools(), baseTools))
+  }
+
+  pi.on('session_start', (_event, context) => {
+    pi.registerTool(
+      createBashTool(context.cwd, {
+        spawnHook: (input) => ({
+          ...input,
+          env: { ...input.env, ...environment },
+        }),
+      }),
+    )
+    activateTools()
+  })
+
+  pi.registerCommand('autobuild-configure', {
+    description: 'Configure an Autobuild-managed headless session',
+    handler: async (args) => {
+      const payload = decode(args)
+      if (!isRecord(payload)) throw new Error('invalid Autobuild bridge configuration')
+      environment = stringRecord(payload.environment)
+      baseTools = stringArray(payload.tools)
+      activateTools()
+    },
+  })
+
+  pi.registerCommand('autobuild-models', {
+    description: 'Return the local Pi model catalog to Autobuild',
+    handler: async (args, context) => {
+      const payload = decode(args)
+      if (!isRecord(payload) || typeof payload.nonce !== 'string' || payload.nonce.length < 8) {
+        throw new Error('invalid Autobuild model-catalog nonce')
+      }
+      const models = payload.availableOnly
+        ? context.modelRegistry.getAvailable()
+        : context.modelRegistry.getAll()
+      const entries = models.map((model) => ({ provider: model.provider, id: model.id }))
+      context.ui.notify(`${CATALOG_PREFIX}${payload.nonce}:${encode(entries)}`, 'info')
+    },
+  })
+}
+
+function decode(value: string): unknown {
+  return JSON.parse(Buffer.from(value, 'base64url').toString('utf8'))
+}
+
+function encode(value: unknown): string {
+  return Buffer.from(JSON.stringify(value), 'utf8').toString('base64url')
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value) && value.every((entry) => typeof entry === 'string') ? value : []
+}
+
+function stringRecord(value: unknown): Record<string, string> {
+  if (!isRecord(value)) return {}
+  return Object.fromEntries(
+    Object.entries(value).filter(
+      (entry): entry is [string, string] => typeof entry[1] === 'string',
+    ),
+  )
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/packages/core/src/ports/runner/pi-bridge.js

@@ -0,0 +1,6 @@
+import { createBashTool } from '@earendil-works/pi-coding-agent'
+import { installAutobuildBridge } from './pi-bridge-core.ts'
+
+export default function autobuildBridge(pi) {
+  installAutobuildBridge(pi, createBashTool)
+}