@defrex/autobuild 0.8.0

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

@@ -0,0 +1,185 @@
+/**
+ * The operator-session reducer (SPEC §7.1.1, §15.2): a session's status, open
+ * turn, pending approval, wake settings, wake cursors, and turn list are a
+ * pure reduction of its event log — never a stored column. The catalog is
+ * closed (`events/sessions.ts`), so this function is total over session
+ * history; unknown facts cannot exist.
+ */
+import type { SessionEvent } from '../events/sessions'
+
+export type SessionStatus = 'idle' | 'running' | 'suspended' | 'awaiting-approval' | 'archived'
+export type SessionSuspensionCause = 'budget' | 'approval'
+export type TurnOutcomeState = 'open' | 'suspended' | 'completed' | 'failed'
+
+export type SessionTurnTrigger =
+  | { kind: 'message'; messageSeq: number }
+  | { kind: 'wake'; build: string; seq: number; type: string }
+
+export interface SessionTurn {
+  turn: string
+  stream: string
+  startedSeq: number
+  trigger: SessionTurnTrigger
+  state: TurnOutcomeState
+  usage?: { inputTokens: number; outputTokens: number; turns?: number }
+  error?: string
+}
+
+export interface SessionState {
+  status: SessionStatus
+  /** Present only when status is `suspended`. */
+  suspendedCause?: SessionSuspensionCause
+  /** The most recent turn that has started and not completed or failed. */
+  openTurn?: { turn: string; stream: string; startedSeq: number; trigger: SessionTurnTrigger }
+  /** A requested approval with no matching `approval.answered` yet. */
+  pendingApproval?: {
+    turn: string
+    toolCallId: string
+    toolName: string
+    input: Record<string, unknown>
+    requestedSeq: number
+  }
+  /** Last `session.wake-set` wins; `[]` before the first (message-only). */
+  wakeGlobs: string[]
+  /** Per build, the highest build event seq a wake trigger has consumed. */
+  wakeCursors: Record<string, number>
+  /** Every turn in start order, with its stream id and outcome. */
+  turns: SessionTurn[]
+}
+
+interface TurnEntry extends SessionTurn {
+  /** The most recent suspension cause for this turn, if any. */
+  suspensionCause?: SessionSuspensionCause
+}
+
+const isTerminal = (state: SessionTurn['state']): boolean =>
+  state === 'completed' || state === 'failed'
+
+/** Reduce a session's events into its derived state. `session.archived` is
+ * terminal: every fact after it is ignored — the archived state is frozen. */
+export function reduceSession(events: SessionEvent[]): SessionState {
+  const turns: TurnEntry[] = []
+  let archived = false
+  let pendingApproval: SessionState['pendingApproval']
+  let wakeGlobs: string[] = []
+  const wakeCursors: Record<string, number> = {}
+
+  const open = (): TurnEntry | undefined => turns.findLast((turn) => !isTerminal(turn.state))
+
+  for (const event of events) {
+    if (archived) break
+    switch (event.type) {
+      case 'session.created':
+      case 'message.posted':
+        break
+      case 'session.wake-set':
+        wakeGlobs = [...event.payload.globs]
+        break
+      case 'turn.started': {
+        const entry: TurnEntry = {
+          turn: event.payload.turn,
+          stream: event.payload.stream,
+          startedSeq: event.seq,
+          trigger: event.payload.trigger,
+          state: 'open',
+        }
+        turns.push(entry)
+        if (event.payload.trigger.kind === 'wake') {
+          const build = event.payload.trigger.build
+          wakeCursors[build] = Math.max(wakeCursors[build] ?? 0, event.payload.trigger.seq)
+        }
+        break
+      }
+      case 'turn.suspended': {
+        const entry = turns.findLast((candidate) => candidate.turn === event.payload.turn)
+        if (entry && entry.state === 'open') {
+          entry.state = 'suspended'
+          entry.suspensionCause = event.payload.cause
+        }
+        break
+      }
+      case 'turn.resumed': {
+        const entry = turns.findLast((candidate) => candidate.turn === event.payload.turn)
+        if (entry && entry.state === 'suspended') entry.state = 'open'
+        break
+      }
+      case 'approval.requested':
+        pendingApproval = {
+          turn: event.payload.turn,
+          toolCallId: event.payload.toolCallId,
+          toolName: event.payload.toolName,
+          input: event.payload.input,
+          requestedSeq: event.seq,
+        }
+        break
+      case 'approval.answered': {
+        if (
+          pendingApproval?.turn === event.payload.turn &&
+          pendingApproval.toolCallId === event.payload.toolCallId
+        ) {
+          pendingApproval = undefined
+          // The answer resumes the turn; `turn.resumed` is the runner's
+          // acknowledgement of the same fact, so between answer and resume
+          // the status is already `running` when a turn is open.
+          const entry = turns.findLast((candidate) => candidate.turn === event.payload.turn)
+          if (entry && entry.state === 'suspended') entry.state = 'open'
+        }
+        break
+      }
+      case 'turn.completed': {
+        const entry = turns.findLast((candidate) => candidate.turn === event.payload.turn)
+        if (entry && !isTerminal(entry.state)) {
+          entry.state = 'completed'
+          entry.usage = event.payload.usage
+        }
+        break
+      }
+      case 'turn.failed': {
+        const entry = turns.findLast((candidate) => candidate.turn === event.payload.turn)
+        if (entry && !isTerminal(entry.state)) {
+          entry.state = 'failed'
+          entry.error = event.payload.error
+        }
+        break
+      }
+      case 'session.archived':
+        archived = true
+        break
+    }
+  }
+
+  const openEntry = open()
+  // Status precedence: archived > awaiting-approval > suspended > running >
+  // idle. An unanswered approval outranks its turn's suspension; the answer
+  // that clears it hands status back to the turn.
+  const status: SessionStatus = archived
+    ? 'archived'
+    : pendingApproval !== undefined
+      ? 'awaiting-approval'
+      : openEntry === undefined
+        ? 'idle'
+        : openEntry.state === 'suspended'
+          ? 'suspended'
+          : 'running'
+
+  return {
+    status,
+    ...(status === 'suspended' && openEntry?.suspensionCause !== undefined
+      ? { suspendedCause: openEntry.suspensionCause }
+      : {}),
+    ...(openEntry !== undefined
+      ? {
+          openTurn: {
+            turn: openEntry.turn,
+            stream: openEntry.stream,
+            startedSeq: openEntry.startedSeq,
+            trigger: openEntry.trigger,
+          },
+        }
+      : {}),
+    ...(pendingApproval !== undefined ? { pendingApproval } : {}),
+    wakeGlobs,
+    wakeCursors,
+    turns: turns.map(({ suspensionCause: _suspensionCause, ...turn }) => turn),
+  }
+}

package/packages/core/src/skills.ts

@@ -0,0 +1,7 @@
+/** Repo-installed Autobuild skills share one harness-neutral namespace. */
+export const SKILL_NAMESPACE = 'ab-'
+
+/** Add the namespace once, accepting explicit namespaced config values too. */
+export function installedSkillName(name: string): string {
+  return name.startsWith(SKILL_NAMESPACE) ? name : `${SKILL_NAMESPACE}${name}`
+}

package/packages/core/src/spec-standard.ts

@@ -0,0 +1,47 @@
+/** The deterministic, mechanically checkable core of docs/spec-standard.md. */
+export interface SpecConformance {
+  conforms: boolean
+  missing: string[]
+}
+
+const LIST_ITEM = /^\s*(?:[-*+]|\d+[.)])\s+\S/
+const HEADING = /^(#{1,6})\s*(.+?)\s*$/
+
+function sectionUnder(lines: string[], name: string): string[] | null {
+  let start = -1
+  let level = 0
+  for (let i = 0; i < lines.length; i += 1) {
+    const match = lines[i]?.match(HEADING)
+    if (match?.[2]?.toLowerCase().startsWith(name)) {
+      start = i + 1
+      level = match[1]?.length ?? 0
+      break
+    }
+  }
+  if (start === -1) return null
+  const section: string[] = []
+  for (let i = start; i < lines.length; i += 1) {
+    const line = lines[i]
+    if (line === undefined) break
+    const heading = line.match(HEADING)
+    if (heading !== null && (heading[1]?.length ?? 0) <= level) break
+    section.push(line)
+  }
+  return section
+}
+
+export function specConformance(body: string): SpecConformance {
+  const missing: string[] = []
+  if (body.trim().length === 0) missing.push('a nonempty spec body')
+  const lines = body.split('\n')
+  const criteria = sectionUnder(lines, 'acceptance criteria')
+  if (criteria === null) {
+    missing.push("an '## Acceptance criteria' heading")
+  } else if (!criteria.some((line) => LIST_ITEM.test(line))) {
+    missing.push("at least one list item under '## Acceptance criteria'")
+  }
+  if (sectionUnder(lines, 'out of scope') === null) {
+    missing.push("an '## Out of scope' heading")
+  }
+  return { conforms: missing.length === 0, missing }
+}

package/packages/core/src/store/adapter.ts

@@ -0,0 +1,80 @@
+export { validateEventWrite } from '../events/catalog'
+export { humanActor } from '../events/envelope'
+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 { validateSessionEventWrite } from '../events/sessions'
+export type {
+  SessionEvent,
+  SessionEventEnvelope,
+  SessionEventType,
+  SessionEventWrite,
+} from '../events/sessions'
+export { createBuildScopedStore } from './build-scope'
+export { createSessionScopedStore } from './session-handle'
+export {
+  DEFAULT_ARTIFACT_RETENTION_MAX_REVISIONS,
+  DISPATCHER_RETENTION_BUILD_KINDS,
+  DISPATCHER_RETENTION_REPO_KINDS,
+  isRetentionManagedKind,
+  revisionsToPrune,
+} from './retention'
+export { assembleUIMessageDocument } from './streams/assemble'
+export {
+  EVENT_WAIT_POLL_MS,
+  readEventsWithWait,
+  readStreamWithWait,
+  STREAM_WAIT_POLL_MS,
+} from './streams/wait'
+export { createSessionStreamSink } from './streams/session-writer'
+export {
+  clampWaitSeconds,
+  MAX_STREAM_WAIT_SECONDS,
+  serializedBatchSize,
+  STREAM_BATCH_MAX_BYTES,
+  STREAM_FORMAT,
+  StreamBatchTooLargeError,
+  StreamClosedError,
+  streamArtifactInput,
+  validateStreamParts,
+} from './streams/types'
+export type {
+  StreamArtifactRef,
+  StreamChunk,
+  StreamOutcome,
+  StreamPart,
+  StreamRead,
+  StreamRecord,
+  StreamScope,
+  StreamStatus,
+} from './streams/types'
+export { pollingSubscribe } from './subscribe'
+export { contentHash, systemClock, toBytes, validateExpectedSeq } from './types'
+export type {
+  Artifact,
+  ArtifactInput,
+  ArtifactMeta,
+  BlobStore,
+  BuildRecord,
+  BuildScopedStore,
+  BuildStore,
+  Clock,
+  NewBuildInput,
+  NewSessionInput,
+  RepositoryArtifact,
+  RepositoryArtifactMeta,
+  RepositoryRecord,
+  SessionArtifact,
+  SessionArtifactMeta,
+  SessionRecord,
+  SessionScopedStore,
+  SubscribeOptions,
+  Unsubscribe,
+} from './types'
+export { normalizeOperator } from './types'

package/packages/core/src/store/build-scope.ts

@@ -0,0 +1,272 @@
+import type { EventType } from '../events/payloads'
+import type { EventWrite } from '../events/catalog'
+import type { RepositoryEventType, RepositoryEventWrite } from '../events/repository'
+import type { AbEvent, EventEnvelope } from '../events/catalog'
+import type { RepositoryEvent, RepositoryEventEnvelope } from '../events/repository'
+import type {
+  SessionEvent,
+  SessionEventEnvelope,
+  SessionEventType,
+  SessionEventWrite,
+} from '../events/sessions'
+import type {
+  Artifact,
+  ArtifactInput,
+  ArtifactMeta,
+  BuildRecord,
+  BuildScopedStore,
+  BuildStore,
+  NewBuildInput,
+  RepositoryArtifact,
+  RepositoryArtifactMeta,
+  RepositoryRecord,
+  SessionArtifactMeta,
+  SessionRecord,
+  SubscribeOptions,
+  Unsubscribe,
+} from './types'
+import type {
+  StreamChunk,
+  StreamOutcome,
+  StreamPart,
+  StreamRead,
+  StreamRecord,
+  StreamScope,
+} from './streams/types'
+
+/** Interface-level authority failure. It is deliberately independent of the
+ * remote transport's authentication errors: tokens carry this scope over the
+ * wire, while every adapter enforces it before delegation. */
+export class BuildScopeError extends Error {
+  constructor(
+    readonly scope: string,
+    readonly operation: string,
+    readonly target?: string,
+  ) {
+    super(
+      target === undefined
+        ? `build-scoped store for ${JSON.stringify(scope)} forbids ${operation}`
+        : `build-scoped store for ${JSON.stringify(scope)} forbids ${operation} targeting ${JSON.stringify(target)}`,
+    )
+    this.name = 'BuildScopeError'
+  }
+}
+
+/** Wrap a full store with one-build authority. The wrapper intentionally keeps
+ * the complete BuildStore shape so accidental admin, collection, repository,
+ * or foreign-build calls fail loudly instead of disappearing behind a type
+ * assertion. */
+export function createBuildScopedStore(store: BuildStore, scope: string): BuildScopedStore {
+  const own = (operation: string, slug: string): void => {
+    if (slug !== scope) throw new BuildScopeError(scope, operation, slug)
+  }
+  /** Stream scopes ride on the record, not on an argument: create and list
+   * name the scope directly; addressed operations resolve the target's scope
+   * and reject when it is not exactly this build's. An unknown id delegates
+   * so the backing store's `unknown stream` feedback survives. */
+  const ownStreamScope = (record: StreamRecord): void => {
+    if (record.scope.kind !== 'build' || record.scope.build !== scope) {
+      throw new BuildScopeError(scope, 'stream', record.id)
+    }
+  }
+  const ownStream = async (_operation: string, streamId: string): Promise<void> => {
+    const record = await store.getStream(streamId)
+    if (record) ownStreamScope(record)
+  }
+  const buildScope = (operation: string, candidate: StreamScope): void => {
+    if (candidate.kind !== 'build' || candidate.build !== scope) {
+      throw new BuildScopeError(scope, operation, JSON.stringify(candidate))
+    }
+  }
+  return {
+    buildScope: scope,
+    scopeBuild(slug: string): BuildScopedStore {
+      own('scopeBuild', slug)
+      return this
+    },
+    createBuild(_input: NewBuildInput): Promise<BuildRecord> {
+      return Promise.reject(new BuildScopeError(scope, 'createBuild'))
+    },
+    async getBuild(slug: string): Promise<BuildRecord | null> {
+      own('getBuild', slug)
+      return store.getBuild(slug)
+    },
+    listBuilds(): Promise<BuildRecord[]> {
+      return Promise.reject(new BuildScopeError(scope, 'listBuilds'))
+    },
+    async append<T extends EventType>(
+      slug: string,
+      event: EventWrite<T>,
+    ): Promise<EventEnvelope<T>> {
+      own('append', slug)
+      return store.append(slug, event)
+    },
+    async appendIfCurrent<T extends EventType>(
+      slug: string,
+      expectedSeq: number,
+      event: EventWrite<T>,
+    ): Promise<EventEnvelope<T> | null> {
+      own('appendIfCurrent', slug)
+      return store.appendIfCurrent(slug, expectedSeq, event)
+    },
+    async appendWithArtifacts<T extends EventType>(
+      slug: string,
+      artifacts: ArtifactInput[],
+      makeEvent: (deposited: ArtifactMeta[]) => EventWrite<T>,
+    ): Promise<{ event: EventEnvelope<T>; artifacts: ArtifactMeta[] }> {
+      own('appendWithArtifacts', slug)
+      return store.appendWithArtifacts(slug, artifacts, makeEvent)
+    },
+    async getEvents(
+      slug: string,
+      sinceSeq?: number,
+      opts?: { waitSeconds?: number; signal?: AbortSignal },
+    ): Promise<AbEvent[]> {
+      own('getEvents', slug)
+      return store.getEvents(slug, sinceSeq, opts)
+    },
+    async putArtifact(slug: string, artifact: ArtifactInput): Promise<ArtifactMeta> {
+      own('putArtifact', slug)
+      return store.putArtifact(slug, artifact)
+    },
+    async getArtifact(slug: string, kind: string, rev?: number): Promise<Artifact | null> {
+      own('getArtifact', slug)
+      return store.getArtifact(slug, kind, rev)
+    },
+    async listArtifacts(slug: string, kind?: string): Promise<ArtifactMeta[]> {
+      own('listArtifacts', slug)
+      return store.listArtifacts(slug, kind)
+    },
+    async claimLease(slug: string, holder: string, ttlMs: number): Promise<boolean> {
+      own('claimLease', slug)
+      return store.claimLease(slug, holder, ttlMs)
+    },
+    async heartbeat(slug: string, holder: string): Promise<boolean> {
+      own('heartbeat', slug)
+      return store.heartbeat(slug, holder)
+    },
+    async releaseLease(slug: string, holder: string): Promise<void> {
+      own('releaseLease', slug)
+      return store.releaseLease(slug, holder)
+    },
+    subscribe(
+      slug: string,
+      opts: SubscribeOptions,
+      onEvent: (event: AbEvent) => void,
+    ): Unsubscribe {
+      own('subscribe', slug)
+      return store.subscribe(slug, opts, onEvent)
+    },
+    ensureRepo(repo: string): Promise<RepositoryRecord> {
+      return Promise.reject(new BuildScopeError(scope, 'ensureRepo', repo))
+    },
+    getRepo(repo: string): Promise<RepositoryRecord | null> {
+      return Promise.reject(new BuildScopeError(scope, 'getRepo', repo))
+    },
+    appendRepo<T extends RepositoryEventType>(
+      repo: string,
+      _event: RepositoryEventWrite<T>,
+    ): Promise<RepositoryEventEnvelope<T>> {
+      return Promise.reject(new BuildScopeError(scope, 'appendRepo', repo))
+    },
+    appendRepoWithArtifacts<T extends RepositoryEventType>(
+      repo: string,
+      _artifacts: ArtifactInput[],
+      _makeEvent: (deposited: RepositoryArtifactMeta[]) => RepositoryEventWrite<T>,
+    ): Promise<{ event: RepositoryEventEnvelope<T>; artifacts: RepositoryArtifactMeta[] }> {
+      return Promise.reject(new BuildScopeError(scope, 'appendRepoWithArtifacts', repo))
+    },
+    getRepoEvents(repo: string, _sinceSeq?: number): Promise<RepositoryEvent[]> {
+      return Promise.reject(new BuildScopeError(scope, 'getRepoEvents', repo))
+    },
+    putRepoArtifact(repo: string, _artifact: ArtifactInput): Promise<RepositoryArtifactMeta> {
+      return Promise.reject(new BuildScopeError(scope, 'putRepoArtifact', repo))
+    },
+    getRepoArtifact(
+      repo: string,
+      _kind: string,
+      _rev?: number,
+    ): Promise<RepositoryArtifact | null> {
+      return Promise.reject(new BuildScopeError(scope, 'getRepoArtifact', repo))
+    },
+    listRepoArtifacts(repo: string, _kind?: string): Promise<RepositoryArtifactMeta[]> {
+      return Promise.reject(new BuildScopeError(scope, 'listRepoArtifacts', repo))
+    },
+    claimRepoLease(repo: string, _holder: string, _ttlMs: number): Promise<boolean> {
+      return Promise.reject(new BuildScopeError(scope, 'claimRepoLease', repo))
+    },
+    heartbeatRepo(repo: string, _holder: string): Promise<boolean> {
+      return Promise.reject(new BuildScopeError(scope, 'heartbeatRepo', repo))
+    },
+    releaseRepoLease(repo: string, _holder: string): Promise<void> {
+      return Promise.reject(new BuildScopeError(scope, 'releaseRepoLease', repo))
+    },
+    createSession(input): Promise<SessionRecord> {
+      return Promise.reject(new BuildScopeError(scope, 'createSession', input.repo))
+    },
+    getSession(id: string): Promise<SessionRecord | null> {
+      return Promise.reject(new BuildScopeError(scope, 'getSession', id))
+    },
+    listSessions(repo: string): Promise<SessionRecord[]> {
+      return Promise.reject(new BuildScopeError(scope, 'listSessions', repo))
+    },
+    appendSessionEvent<T extends SessionEventType>(
+      id: string,
+      _event: SessionEventWrite<T>,
+    ): Promise<SessionEventEnvelope<T>> {
+      return Promise.reject(new BuildScopeError(scope, 'appendSessionEvent', id))
+    },
+    getSessionEvents(id: string, _sinceSeq?: number): Promise<SessionEvent[]> {
+      return Promise.reject(new BuildScopeError(scope, 'getSessionEvents', id))
+    },
+    appendSessionWithArtifacts<T extends SessionEventType>(
+      id: string,
+      _artifacts: ArtifactInput[],
+      _makeEvent: (deposited: SessionArtifactMeta[]) => SessionEventWrite<T>,
+    ): Promise<{ event: SessionEventEnvelope<T>; artifacts: SessionArtifactMeta[] }> {
+      return Promise.reject(new BuildScopeError(scope, 'appendSessionWithArtifacts', id))
+    },
+    putSessionArtifact(id: string, _artifact: ArtifactInput): Promise<SessionArtifactMeta> {
+      return Promise.reject(new BuildScopeError(scope, 'putSessionArtifact', id))
+    },
+    getSessionArtifact(id: string, _kind: string, _rev?: number): Promise<null> {
+      return Promise.reject(new BuildScopeError(scope, 'getSessionArtifact', id))
+    },
+    listSessionArtifacts(id: string, _kind?: string): Promise<SessionArtifactMeta[]> {
+      return Promise.reject(new BuildScopeError(scope, 'listSessionArtifacts', id))
+    },
+    scopeSession(id: string): never {
+      throw new BuildScopeError(scope, 'scopeSession', id)
+    },
+    async createStream(candidate: StreamScope, label: string): Promise<StreamRecord> {
+      buildScope('createStream', candidate)
+      return store.createStream(candidate, label)
+    },
+    async appendStreamParts(streamId: string, parts: StreamPart[]): Promise<StreamChunk> {
+      await ownStream('appendStreamParts', streamId)
+      return store.appendStreamParts(streamId, parts)
+    },
+    async readStream(
+      streamId: string,
+      opts?: { since?: number; waitSeconds?: number },
+    ): Promise<StreamRead> {
+      await ownStream('readStream', streamId)
+      return store.readStream(streamId, opts)
+    },
+    async closeStream(streamId: string, outcome: StreamOutcome): Promise<StreamRecord> {
+      await ownStream('closeStream', streamId)
+      return store.closeStream(streamId, outcome)
+    },
+    async getStream(streamId: string): Promise<StreamRecord | null> {
+      await ownStream('getStream', streamId)
+      return store.getStream(streamId)
+    },
+    async listStreams(candidate: StreamScope): Promise<StreamRecord[]> {
+      buildScope('listStreams', candidate)
+      return store.listStreams(candidate)
+    },
+    close(): Promise<void> {
+      return Promise.reject(new BuildScopeError(scope, 'close'))
+    },
+  }
+}