@defrex/autobuild 0.8.0

package/packages/core/src/operator/sessions.ts

@@ -0,0 +1,223 @@
+/**
+ * Operator-session operations behind the operator API (SPEC §7.1.1): the
+ * signed-in operator's orchestrator conversations. Every write is attributed
+ * to the signed-in operator — the token's user, never a client-supplied
+ * identity — and `via` is never set on session events: session events are the
+ * delegate's own log, and here the operator IS the actor.
+ *
+ * Ownership lives here, in the server seam, because the store has no
+ * principal concept: a session belongs to its creating operator; other
+ * operators of the same repository can read it and cannot write to it. The
+ * store stays neutral; the API is the gatekeeper — writes of any kind to an
+ * archived session are refusals here, not store errors.
+ */
+import { humanActor } from '../events/envelope'
+import type { SessionEventWrite } from '../events/sessions'
+import { reduceSession, type SessionState, type SessionTurn } from '../sessions/reducer'
+import type { StreamRead } from '../store/streams/types'
+import type { BuildStore, SessionRecord } from '../store/types'
+import type { OperatorSandboxService } from './sandbox'
+
+export class OperatorSessionError extends Error {
+  constructor(
+    readonly code: 'not-found' | 'refusal' | 'forbidden',
+    message: string,
+  ) {
+    super(message)
+    this.name = 'OperatorSessionError'
+  }
+}
+
+async function requireSession(
+  store: BuildStore,
+  repo: string,
+  sid: string,
+): Promise<SessionRecord> {
+  const record = await store.getSession(sid)
+  if (record === null || record.repo !== repo) {
+    throw new OperatorSessionError('not-found', `unknown session "${sid}"`)
+  }
+  return record
+}
+
+function requireOwner(record: SessionRecord, user: string, operation: string): void {
+  if (record.operator !== user) {
+    throw new OperatorSessionError(
+      'forbidden',
+      `session "${record.id}" belongs to operator ${JSON.stringify(record.operator)}; ${JSON.stringify(user)} may not ${operation}`,
+    )
+  }
+}
+
+/** Every append funnels through here: one attribution point, one archived
+ * gate. The store has no principal concept, so this is where a token's user
+ * meets a session's operator. */
+async function appendAs(
+  store: BuildStore,
+  record: SessionRecord,
+  user: string,
+  event: SessionEventWrite,
+): Promise<void> {
+  requireOwner(record, user, `write ${event.type}`)
+  const state = reduceSession(await store.getSessionEvents(record.id))
+  if (state.status === 'archived') {
+    throw new OperatorSessionError('refusal', `session "${record.id}" is archived and read-only`)
+  }
+  await store.appendSessionEvent(record.id, event)
+}
+
+export async function listOperatorSessions(
+  store: BuildStore,
+  repo: string,
+): Promise<SessionRecord[]> {
+  const sessions = await store.listSessions(repo)
+  return sessions.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+}
+
+export async function createOperatorSession(
+  store: BuildStore,
+  repo: string,
+  user: string,
+  title?: string,
+): Promise<SessionRecord> {
+  return store.createSession({
+    repo,
+    operator: user,
+    ...(title !== undefined ? { title } : {}),
+  })
+}
+
+export interface OperatorSessionView {
+  session: SessionRecord
+  state: SessionState
+  turns: SessionTurn[]
+}
+
+export async function getOperatorSession(
+  store: BuildStore,
+  repo: string,
+  sid: string,
+): Promise<OperatorSessionView> {
+  const record = await requireSession(store, repo, sid)
+  const state = reduceSession(await store.getSessionEvents(record.id))
+  return { session: record, state, turns: state.turns }
+}
+
+export async function postOperatorMessage(
+  store: BuildStore,
+  repo: string,
+  sid: string,
+  user: string,
+  text: string,
+): Promise<void> {
+  const record = await requireSession(store, repo, sid)
+  await appendAs(store, record, user, {
+    actor: humanActor(user),
+    type: 'message.posted',
+    payload: { text },
+  })
+}
+
+export async function setOperatorWake(
+  store: BuildStore,
+  repo: string,
+  sid: string,
+  user: string,
+  globs: string[],
+): Promise<void> {
+  const record = await requireSession(store, repo, sid)
+  await appendAs(store, record, user, {
+    actor: humanActor(user),
+    type: 'session.wake-set',
+    payload: { globs },
+  })
+}
+
+export async function answerOperatorApproval(
+  store: BuildStore,
+  repo: string,
+  sid: string,
+  user: string,
+  turn: string,
+  toolCallId: string,
+  decision: 'approve' | 'deny',
+): Promise<void> {
+  const record = await requireSession(store, repo, sid)
+  requireOwner(record, user, 'answer an approval')
+  const state = reduceSession(await store.getSessionEvents(record.id))
+  const pending = state.pendingApproval
+  if (
+    state.status === 'archived' ||
+    pending === undefined ||
+    pending.turn !== turn ||
+    pending.toolCallId !== toolCallId
+  ) {
+    throw new OperatorSessionError(
+      'refusal',
+      `session "${record.id}" has no pending approval for turn ${JSON.stringify(turn)} tool call ${JSON.stringify(toolCallId)}`,
+    )
+  }
+  await appendAs(store, record, user, {
+    actor: humanActor(user),
+    type: 'approval.answered',
+    payload: { turn, toolCallId, decision },
+  })
+}
+
+export async function archiveOperatorSession(
+  store: BuildStore,
+  repo: string,
+  sid: string,
+  user: string,
+  sandbox?: OperatorSandboxService,
+): Promise<void> {
+  const record = await requireSession(store, repo, sid)
+  requireOwner(record, user, 'archive')
+  const state = reduceSession(await store.getSessionEvents(record.id))
+  if (state.status === 'archived') {
+    throw new OperatorSessionError('refusal', `session "${record.id}" is already archived`)
+  }
+  await store.appendSessionEvent(record.id, {
+    actor: humanActor(user),
+    type: 'session.archived',
+    payload: {},
+  })
+  // When the archive leaves the operator with no open session for this
+  // repository, their sandbox environment is released (snapshot purge,
+  // journal fact). The service derives the environment via its pure
+  // describe — never provisioning — and a never-provisioned operator is a
+  // no-op. Contained: a release failure must not fail an accepted archive.
+  if (sandbox !== undefined) {
+    const sessions = await store.listSessions(repo)
+    const open: SessionRecord[] = []
+    for (const session of sessions) {
+      if (session.operator !== user) continue
+      const sessionState = reduceSession(await store.getSessionEvents(session.id))
+      if (sessionState.status !== 'archived') open.push(session)
+    }
+    if (open.length === 0) {
+      try {
+        await sandbox.release(user, { repo })
+      } catch {
+        // The archive already succeeded; the environment stays journaled and
+        // the dispatcher's idle settlement stops it later.
+      }
+    }
+  }
+}
+
+export async function readOperatorTurnStream(
+  store: BuildStore,
+  repo: string,
+  sid: string,
+  turn: string,
+  opts?: { since?: number; waitSeconds?: number },
+): Promise<StreamRead> {
+  const record = await requireSession(store, repo, sid)
+  const state = reduceSession(await store.getSessionEvents(record.id))
+  const target = state.turns.find((candidate) => candidate.turn === turn)
+  if (target === undefined) {
+    throw new OperatorSessionError('not-found', `unknown turn "${turn}" in session "${record.id}"`)
+  }
+  return store.readStream(target.stream, opts)
+}

package/packages/core/src/operator/tickets.ts

@@ -0,0 +1,177 @@
+import type { Config } from '../config/schema'
+import { reduceBuild } from '../kernel/reducer'
+import {
+  changeBlockers,
+  createTicket,
+  moveTicket,
+  requireTicket,
+  updateTicket,
+} from '../ports/tickets/operations'
+import type { DependencyState, Ticket, TicketSource, TicketUpdate } from '../ports/types'
+import type { BuildStore } from '../store/types'
+import { defaultTriageState } from '../processes/dispatcher'
+import { effectiveConfig, OperatorQueryError } from './query'
+
+export interface OperatorTicketContext {
+  teamKey: string
+  claimedState?: string
+  createState?: string
+}
+
+export interface OperatorTicketBackend {
+  sourceFor(context: OperatorTicketContext): TicketSource | Promise<TicketSource>
+  statesFor(context: OperatorTicketContext, source: TicketSource): string[] | Promise<string[]>
+}
+
+export interface OperatorTicketQueue {
+  states: string[]
+  tickets: Ticket[]
+  diagnostics: string[]
+  criteria: { state?: string; labels?: string[] }
+  /** Effective repository lifecycle names; clients must not invent provider states. */
+  triageState: string
+  readyState: string
+}
+
+export interface OperatorTicketBuild {
+  slug: string
+  status: string
+  updatedAt: string
+  link: string
+}
+
+export interface OperatorTicketDetail {
+  ticket: Ticket
+  blockers: DependencyState[]
+  build: OperatorTicketBuild | null
+}
+
+function contextFor(config: Config, repo: string): OperatorTicketContext {
+  const tickets = config.tickets
+  if (tickets.teamKey === undefined) {
+    throw new OperatorQueryError(
+      'effective-config-unavailable',
+      `effective config unavailable for repository "${repo}": [tickets].teamKey is required for hosted ticket access`,
+    )
+  }
+  return {
+    teamKey: tickets.teamKey,
+    ...(tickets.claimedState !== undefined ? { claimedState: tickets.claimedState } : {}),
+    ...(tickets.createState !== undefined ? { createState: tickets.createState } : {}),
+  }
+}
+
+export async function openOperatorTickets(opts: {
+  store: BuildStore
+  repo: string
+  backend: OperatorTicketBackend
+}): Promise<{ config: Config; context: OperatorTicketContext; source: TicketSource }> {
+  const { config } = await effectiveConfig(opts.store, opts.repo)
+  const context = contextFor(config, opts.repo)
+  return { config, context, source: await opts.backend.sourceFor(context) }
+}
+
+export async function listOperatorTickets(opts: {
+  store: BuildStore
+  repo: string
+  backend: OperatorTicketBackend
+  state?: string
+  labels?: string[]
+}): Promise<OperatorTicketQueue> {
+  const { config, context, source } = await openOperatorTickets(opts)
+  const triageState = defaultTriageState(config)
+  const readyState = config.tickets.readyState
+  // The operator surface is a grooming queue. Unlike the CLI's ticket list,
+  // labels narrow the default state instead of replacing its lifecycle gate.
+  const criteria = {
+    state: opts.state ?? triageState,
+    ...(opts.labels !== undefined ? { labels: opts.labels } : {}),
+  }
+  const [listing, states] = await Promise.all([
+    source.listReady(criteria),
+    opts.backend.statesFor(context, source),
+  ])
+  return {
+    states,
+    tickets: listing.tickets,
+    diagnostics: listing.diagnostics,
+    criteria,
+    triageState,
+    readyState,
+  }
+}
+
+async function matchingBuild(
+  store: BuildStore,
+  repo: string,
+  id: string,
+): Promise<OperatorTicketBuild | null> {
+  const matches = (await store.listBuilds()).filter(
+    (record) => record.repo === repo && record.ticket?.id === id,
+  )
+  const projected = await Promise.all(
+    matches.map(async (record) => ({
+      record,
+      state: reduceBuild(await store.getEvents(record.slug)),
+    })),
+  )
+  projected.sort((a, b) => {
+    const aActive = a.state.status !== 'done' && a.state.status !== 'aborted'
+    const bActive = b.state.status !== 'done' && b.state.status !== 'aborted'
+    if (aActive !== bActive) return aActive ? -1 : 1
+    return b.record.updatedAt.localeCompare(a.record.updatedAt)
+  })
+  const found = projected[0]
+  return found
+    ? {
+        slug: found.record.slug,
+        status: found.state.status,
+        updatedAt: found.record.updatedAt,
+        link: `#build-${encodeURIComponent(found.record.slug)}`,
+      }
+    : null
+}
+
+export async function getOperatorTicket(opts: {
+  store: BuildStore
+  repo: string
+  backend: OperatorTicketBackend
+  id: string
+}): Promise<OperatorTicketDetail> {
+  const { source } = await openOperatorTickets(opts)
+  const ticket = await requireTicket(source, opts.id)
+  const blockers = await source.dependencyStates(ticket.blockedBy ?? [])
+  return { ticket, blockers, build: await matchingBuild(opts.store, opts.repo, opts.id) }
+}
+
+export async function mutateOperatorTicket(opts: {
+  store: BuildStore
+  repo: string
+  backend: OperatorTicketBackend
+  operation:
+    | {
+        kind: 'create'
+        title: string
+        body: string
+        labels?: string[]
+        state?: string
+        blockedBy?: string[]
+      }
+    | { kind: 'update'; id: string; patch: TicketUpdate }
+    | { kind: 'move'; id: string; state: string }
+    | { kind: 'block' | 'unblock'; id: string; blockerIds: string[] }
+}): Promise<OperatorTicketDetail> {
+  const { source } = await openOperatorTickets(opts)
+  const operation = opts.operation
+  if (operation.kind === 'update') await requireTicket(source, operation.id)
+  const ticket =
+    operation.kind === 'create'
+      ? await createTicket(source, operation)
+      : operation.kind === 'update'
+        ? (await updateTicket(source, operation.id, operation.patch))!
+        : operation.kind === 'move'
+          ? await moveTicket(source, operation.id, operation.state)
+          : await changeBlockers(source, operation.id, operation.blockerIds, operation.kind)
+  const blockers = await source.dependencyStates(ticket.blockedBy ?? [])
+  return { ticket, blockers, build: await matchingBuild(opts.store, opts.repo, ticket.ref.id) }
+}

package/packages/core/src/plugin-sdk/index.ts

@@ -0,0 +1,174 @@
+/**
+ * Stable plugin-authoring surface. Internal source paths are not public API;
+ * plugins should import only `@defrex/autobuild/plugin-sdk` (normally with
+ * `import type`) and run these same contracts against their adapters.
+ */
+export type * from '../ports/types'
+export type * from '../ports/workspace/build-execution'
+export type * from '../store/types'
+export type {
+  RuntimeRegistration,
+  RuntimeRegistry,
+  SessionStreamInfo,
+} from '../ports/runner/runtime'
+export {
+  STREAM_PART_MAX_BYTES,
+  abortPart,
+  errorPart,
+  finishPart,
+  finishStepPart,
+  promptPart,
+  reasoningDeltaPart,
+  reasoningEndPart,
+  reasoningStartPart,
+  sessionPart,
+  startPart,
+  startStepPart,
+  textDeltaPart,
+  textEndPart,
+  textStartPart,
+  toolInputPart,
+  toolOutputPart,
+  truncationPart,
+} from '../ports/runner/stream-parts'
+export type {
+  OneShotCompletion,
+  OneShotCompletionInput,
+  OneShotCompletionResult,
+} from '../ports/runner/one-shot'
+
+export {
+  CONTRACT_FOLLOW_UP,
+  CONTRACT_INVOCATION,
+  CONTRACT_ONE_SHOT_PROMPT,
+  CONTRACT_ONE_SHOT_TEXT,
+  CONTRACT_PERMANENT_FAILURE,
+  CONTRACT_RETRYABLE_FAILURE,
+  CONTRACT_SKILL,
+  describeAgentRunnerContract,
+} from '../ports/runner/contract'
+export type {
+  AgentRunnerContractFactory,
+  AgentRunnerContractHarness,
+  AgentRunnerContractOneShotHarness,
+  AgentRunnerContractOneShotObservation,
+  AgentRunnerContractScenario,
+  AgentRunnerContractTurnObservation,
+} from '../ports/runner/contract'
+
+export {
+  PLUGIN_API_VERSION,
+  PluginApiCompatibilityError,
+  pluginApiCompatibility,
+  pluginManifestSchema,
+  parsePluginManifest,
+} from '../plugins/manifest'
+export type {
+  AgentRuntimePluginFactory,
+  AgentRuntimePluginRegistration,
+  AutobuildPluginManifest,
+  ForgePluginFactory,
+  ForgePluginRegistration,
+  PluginAdapterRegistration,
+  PluginApiCompatibility,
+  PluginContractDescriptor,
+  PluginFactory,
+  PluginFactoryContext,
+  TicketSourcePluginDescriptor,
+  TicketSourcePluginFactory,
+  TicketSourcePluginRegistration,
+  WorkspaceProviderPluginFactory,
+  WorkspaceProviderPluginRegistration,
+} from '../plugins/manifest'
+
+export {
+  describeTicketSourceContract,
+  CONTRACT_TICKET_BODY,
+  contractIdempotencyKey,
+  contractLabelName,
+  contractTicketTitle,
+} from '../ports/tickets/contract'
+export type {
+  TicketSourceContractFactory,
+  TicketSourceContractHarness,
+  TicketSourceContractStates,
+} from '../ports/tickets/contract'
+
+export { describeWorkspaceProviderContract } from '../ports/workspace/contract'
+export type {
+  WorkspaceProviderContractFactory,
+  WorkspaceProviderContractHarness,
+} from '../ports/workspace/contract'
+
+export { describeForgeContract } from '../ports/forge/contract'
+export type {
+  ForgeContractControls,
+  ForgeContractFactory,
+  ForgeContractFactoryOptions,
+  ForgeContractHarness,
+} from '../ports/forge/contract'
+
+export {
+  describeBlobStoreContract,
+  describeBuildStoreContract,
+  CONTRACT_T0,
+  ISO_TS,
+  buildCreatedWrite,
+  harvestStartedWrite,
+  messagePostedWrite,
+  planCompletedWrite,
+  sampleBuildInput,
+  sampleEventWrite,
+} from '../store/contract'
+export type {
+  BlobStoreFactory,
+  BlobStoreHarness,
+  BuildStoreFactory,
+  BuildStoreHarness,
+} from '../store/contract'
+
+export { FakeTicketSource } from '../ports/tickets/fake'
+export { validateTicketUpdate } from '../ports/tickets/update'
+export { FakeWorkspaceProvider } from '../ports/workspace/fake'
+export { FakeForge } from '../ports/forge/fake'
+export { ScriptedAgentRunner } from '../ports/runner/fake'
+export { MemoryBlobStore, MemoryBuildStore } from '../store/memory'
+
+// Runtime primitives needed by out-of-tree BuildStore adapters.
+export { validateEventWrite } from '../events/catalog'
+export type { AbEvent, EventEnvelope, EventWrite } from '../events/catalog'
+export type { EventType } from '../events/payloads'
+export { validateRepositoryEventWrite } from '../events/repository'
+export type {
+  RepositoryEvent,
+  RepositoryEventEnvelope,
+  RepositoryEventType,
+  RepositoryEventWrite,
+} from '../events/repository'
+export { BuildScopeError, createBuildScopedStore } from '../store/build-scope'
+export { createSessionStreamSink } from '../store/streams/session-writer'
+export { pollingSubscribe } from '../store/subscribe'
+export { assembleUIMessageDocument } from '../store/streams/assemble'
+export { readStreamWithWait, STREAM_WAIT_POLL_MS } from '../store/streams/wait'
+export {
+  clampWaitSeconds,
+  MAX_STREAM_WAIT_SECONDS,
+  serializedBatchSize,
+  STREAM_BATCH_MAX_BYTES,
+  STREAM_FORMAT,
+  StreamBatchTooLargeError,
+  StreamClosedError,
+  streamArtifactInput,
+  validateStreamParts,
+} from '../store/streams/types'
+export type {
+  StreamArtifactRef,
+  StreamChunk,
+  StreamOutcome,
+  StreamPart,
+  StreamRead,
+  StreamRecord,
+  StreamScope,
+  StreamStatus,
+} from '../store/streams/types'
+export { contentHash, systemClock, toBytes, validateExpectedSeq } from '../store/types'

package/packages/core/src/plugins/contract-entry.ts

@@ -0,0 +1,74 @@
+import { join } from 'node:path'
+import { loadConfig } from '../config/load'
+import { describeForgeContract, type ForgeContractFactory } from '../ports/forge/contract'
+import {
+  describeAgentRunnerContract,
+  type AgentRunnerContractFactory,
+} from '../ports/runner/contract'
+import {
+  describeTicketSourceContract,
+  type TicketSourceContractFactory,
+} from '../ports/tickets/contract'
+import {
+  describeWorkspaceProviderContract,
+  type WorkspaceProviderContractFactory,
+} from '../ports/workspace/contract'
+import { CONTRACT_ADAPTER_ENV, CONTRACT_PORT_ENV, CONTRACT_REPO_ENV } from './contract-env'
+import { loadPlugins } from './load'
+import { PLUGIN_PORTS, type PluginPort } from './registry'
+
+function requiredEnv(name: string): string {
+  const value = process.env[name]
+  if (value === undefined || value.trim() === '') {
+    throw new Error(`plugin contract runner requires private environment ${name}`)
+  }
+  return value
+}
+
+const repoRoot = requiredEnv(CONTRACT_REPO_ENV)
+const rawPort = requiredEnv(CONTRACT_PORT_ENV)
+const adapter = requiredEnv(CONTRACT_ADAPTER_ENV)
+if (!PLUGIN_PORTS.includes(rawPort as PluginPort)) {
+  throw new Error(
+    `${CONTRACT_PORT_ENV} must be one of ${PLUGIN_PORTS.join(', ')}; got "${rawPort}"`,
+  )
+}
+const port = rawPort as PluginPort
+const config = await loadConfig(join(repoRoot, 'autobuild.toml'))
+const registry = await loadPlugins(config.plugins, repoRoot)
+const registration = registry.registration(port, adapter)
+if (registration === undefined) {
+  throw new Error(`unknown ${port} adapter "${adapter}"`)
+}
+if (registration.contract === undefined) {
+  throw new Error(`${port} adapter "${adapter}" has no contract fixture descriptor`)
+}
+if (registration.contract.live === true && process.env.AB_RUN_LIVE_PORT_CONTRACTS !== '1') {
+  throw new Error('live plugin contracts require AB_RUN_LIVE_PORT_CONTRACTS=1')
+}
+
+const contractFactory = await registration.contract.factory({
+  config: {},
+  env: process.env,
+  repoRoot,
+})
+if (typeof contractFactory !== 'function') {
+  throw new Error(
+    `${port} adapter "${adapter}" contract.factory must return the shared suite's harness factory`,
+  )
+}
+
+switch (port) {
+  case 'ticket-source':
+    describeTicketSourceContract(adapter, contractFactory as TicketSourceContractFactory)
+    break
+  case 'agent-runtime':
+    describeAgentRunnerContract(adapter, contractFactory as AgentRunnerContractFactory)
+    break
+  case 'workspace-provider':
+    describeWorkspaceProviderContract(adapter, contractFactory as WorkspaceProviderContractFactory)
+    break
+  case 'forge':
+    describeForgeContract(adapter, contractFactory as ForgeContractFactory)
+    break
+}

package/packages/core/src/plugins/contract-env.ts

@@ -0,0 +1,3 @@
+export const CONTRACT_REPO_ENV = 'AB_PLUGIN_CONTRACT_REPO'
+export const CONTRACT_PORT_ENV = 'AB_PLUGIN_CONTRACT_PORT'
+export const CONTRACT_ADAPTER_ENV = 'AB_PLUGIN_CONTRACT_ADAPTER'