@defrex/autobuild 0.8.0

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

@@ -0,0 +1,117 @@
+import { humanActor, type Via } from '../events/envelope'
+import type { RepositoryEventEnvelope } from '../events/repository'
+import { reduceDispatchSettings } from '../kernel/dispatch-settings'
+import { reduceHarvest } from '../kernel/harvest'
+import type { BuildStore } from '../store/types'
+import { projectHarvest, type HarvestRunAction } from '../cli/dashboard/model'
+
+export class OperatorControlError extends Error {
+  constructor(
+    readonly code:
+      | 'stale-harvest-run'
+      | 'harvest-paused'
+      | 'harvest-pending'
+      | 'harvest-unavailable',
+    message: string,
+  ) {
+    super(message)
+    this.name = 'OperatorControlError'
+  }
+}
+
+export type RepositorySetting = 'intake' | 'auto-merge-default'
+
+export async function setRepositorySetting(opts: {
+  store: BuildStore
+  repo: string
+  user: string
+  setting: RepositorySetting
+  enabled: boolean
+  /** Delegated-write attribution marker threaded onto the event's actor. */
+  via?: Via
+}): Promise<{ enabled: boolean; event: RepositoryEventEnvelope }> {
+  await opts.store.ensureRepo(opts.repo)
+  const event =
+    opts.setting === 'intake'
+      ? await opts.store.appendRepo(opts.repo, {
+          actor: humanActor(opts.user, opts.via),
+          type: 'dispatcher.intake-set',
+          payload: { enabled: opts.enabled },
+        })
+      : await opts.store.appendRepo(opts.repo, {
+          actor: humanActor(opts.user, opts.via),
+          type: 'dispatcher.auto-merge-default-set',
+          payload: { enabled: opts.enabled },
+        })
+  return { enabled: opts.enabled, event }
+}
+
+export async function toggleRepositorySetting(opts: {
+  store: BuildStore
+  repo: string
+  user: string
+  setting: RepositorySetting
+  via?: Via
+}): Promise<{ enabled: boolean; event: RepositoryEventEnvelope }> {
+  await opts.store.ensureRepo(opts.repo)
+  const settings = reduceDispatchSettings(await opts.store.getRepoEvents(opts.repo))
+  const enabled = opts.setting === 'intake' ? !settings.intake : !settings.defaultAutoMerge
+  return setRepositorySetting({ ...opts, enabled })
+}
+
+export async function toggleHarvestGate(opts: {
+  store: BuildStore
+  repo: string
+  user: string
+  via?: Via
+}): Promise<{ command: 'pause' | 'resume'; event: RepositoryEventEnvelope }> {
+  await opts.store.ensureRepo(opts.repo)
+  const state = reduceHarvest(await opts.store.getRepoEvents(opts.repo))
+  const pending = state.pendingCommands.at(-1)
+  const requestedPaused = pending === undefined ? state.paused : pending.command === 'pause'
+  const command = requestedPaused ? 'resume' : 'pause'
+  const event = await opts.store.appendRepo(opts.repo, {
+    actor: humanActor(opts.user, opts.via),
+    type: command === 'resume' ? 'harvest.resume-requested' : 'harvest.pause-requested',
+    payload: {},
+  })
+  return { command, event }
+}
+
+/** Act only on the concrete dashboard run captured by the caller. */
+export async function controlHarvestRun(opts: {
+  store: BuildStore
+  repo: string
+  user: string
+  run: string
+  via?: Via
+}): Promise<{ action: HarvestRunAction; event: RepositoryEventEnvelope }> {
+  await opts.store.ensureRepo(opts.repo)
+  const events = await opts.store.getRepoEvents(opts.repo)
+  const state = reduceHarvest(events)
+  const projected = projectHarvest(events)
+  if (projected === undefined || projected.run !== opts.run) {
+    throw new OperatorControlError(
+      'stale-harvest-run',
+      'harvest run action ignored: selected run is no longer active',
+    )
+  }
+  if (state.paused) {
+    throw new OperatorControlError(
+      'harvest-paused',
+      'harvest run action unavailable while harvest is OFF; select Dispatcher and press h',
+    )
+  }
+  if (state.pendingCommands.some((command) => command.command === 'resume')) {
+    throw new OperatorControlError('harvest-pending', 'harvest run: resume acknowledgement pending')
+  }
+  if (projected.action === undefined) {
+    throw new OperatorControlError('harvest-unavailable', 'harvest run has no available action')
+  }
+  const event = await opts.store.appendRepo(opts.repo, {
+    actor: humanActor(opts.user, opts.via),
+    type: 'harvest.resume-requested',
+    payload: {},
+  })
+  return { action: projected.action, event }
+}

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

@@ -0,0 +1,62 @@
+export { OperatorApiClient, OperatorApiError } from './client'
+export type { DownloadedArtifact, OperatorApiClientOptions } from './client'
+export { createOperatorServer } from './server'
+export type { OperatorServerOptions } from './server'
+export {
+  answerRequestSchema,
+  buildControlRequestSchema,
+  buildListScopeSchema,
+  bulkControlRequestSchema,
+  harvestControlRequestSchema,
+  operatorErrorSchema,
+  settingRequestSchema,
+  ticketBlockerRequestSchema,
+  ticketCreateRequestSchema,
+  ticketMoveRequestSchema,
+  ticketUpdateRequestSchema,
+} from './protocol'
+export type {
+  OperatorAnswerRequest,
+  OperatorBuildControlRequest,
+  OperatorErrorBody,
+  OperatorTicketBlockerRequest,
+  OperatorTicketCreateRequest,
+  OperatorTicketMoveRequest,
+  OperatorTicketUpdateRequest,
+} from './protocol'
+export type {
+  BuildListScope,
+  OperatorBuildView,
+  OperatorDashboardSnapshot,
+} from './query'
+export { OperatorControlError } from './control'
+export { OperatorQueryError } from './query'
+export {
+  OPERATOR_NOTES_ARTIFACT,
+  TOOLS,
+  attributed,
+  buildRegistry,
+  RegistryError,
+} from './registry'
+export type {
+  OperatorToolRegistry,
+  RegistryErrorReason,
+  RegistryOptions,
+  ToolApproval,
+  ToolContext,
+  ToolEntry,
+  ToolFailureBody,
+  ToolHandler,
+} from './registry'
+export { OPERATOR_TOOL_ANNOTATIONS } from './annotations'
+export type { OperatorToolName, ToolAnnotationsTableEntry } from './annotations'
+export type { RouteRefusal } from './requests'
+export { RouteRefusalError } from './requests'
+export type {
+  OperatorTicketBackend,
+  OperatorTicketBuild,
+  OperatorTicketContext,
+  OperatorTicketDetail,
+  OperatorTicketQueue,
+} from './tickets'
+export * from './presentation'

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

@@ -0,0 +1,22 @@
+export {
+  buildActionAvailability,
+  dashboardBuildControl,
+  harvestActionAvailability,
+  repositoryActionAvailability,
+} from '../cli/dashboard/actions'
+export type { DashboardActionAvailability, DashboardBuildControl } from '../cli/dashboard/actions'
+export type {
+  DashboardBuild,
+  DashboardHarvest,
+  DashboardModel,
+  EffectiveStatus,
+  PipelineStep,
+  StepState,
+  StepTiming,
+} from '../cli/dashboard/model'
+export { parseTranscript } from '../cli/dashboard/transcript'
+export type {
+  TranscriptPresentation,
+  TranscriptTurn,
+  TranscriptUsage,
+} from '../cli/dashboard/transcript'

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

@@ -0,0 +1,98 @@
+import { z } from 'zod'
+
+export const buildListScopeSchema = z.enum(['active', 'queued', 'all'])
+
+export const buildControlRequestSchema = z.discriminatedUnion('action', [
+  z.strictObject({ action: z.literal('pause') }),
+  z.strictObject({ action: z.literal('cancel-pause') }),
+  z.strictObject({ action: z.literal('resume') }),
+  z.strictObject({ action: z.literal('abort') }),
+  z.strictObject({ action: z.literal('discard') }),
+  z.strictObject({ action: z.literal('auto-merge-on') }),
+  z.strictObject({ action: z.literal('auto-merge-off') }),
+])
+export type OperatorBuildControlRequest = z.infer<typeof buildControlRequestSchema>
+
+const optionalText = z.string().optional()
+export const answerRequestSchema = z.union([
+  z.strictObject({ resolution: z.literal('guidance'), text: z.string().trim().min(1) }),
+  z.strictObject({ resolution: z.literal('retry') }),
+  z.strictObject({ resolution: z.literal('dismiss'), text: optionalText }),
+  z.strictObject({
+    resolution: z.literal('review-round-ceiling'),
+    ceiling: z.number().int().positive(),
+    text: optionalText,
+  }),
+  z.strictObject({
+    resolution: z.literal('revise-spec'),
+    origin: z.literal('body'),
+    body: z.string(),
+    text: optionalText,
+    /** Accepted only so the shared core can return its exact incompatible-options refusal. */
+    ceiling: z.number().int().positive().optional(),
+  }),
+  z.strictObject({
+    resolution: z.literal('revise-spec'),
+    origin: z.literal('ticket'),
+    body: z.string(),
+    text: optionalText,
+    ceiling: z.number().int().positive().optional(),
+  }),
+])
+export type OperatorAnswerRequest = z.infer<typeof answerRequestSchema>
+
+export const settingRequestSchema = z.strictObject({ enabled: z.boolean() })
+export const bulkControlRequestSchema = z.strictObject({ action: z.enum(['pause', 'resume']) })
+export const harvestControlRequestSchema = z.discriminatedUnion('action', [
+  z.strictObject({ action: z.literal('toggle-gate') }),
+  z.strictObject({ action: z.literal('run'), run: z.string().min(1) }),
+])
+
+export const ticketCreateRequestSchema = z.strictObject({
+  title: z.string(),
+  body: z.string(),
+  labels: z.array(z.string()).optional(),
+  state: z.string().min(1).optional(),
+  blockedBy: z.array(z.string().min(1)).optional(),
+})
+export const ticketUpdateRequestSchema = z
+  .strictObject({
+    title: z.string().optional(),
+    body: z.string().optional(),
+    labels: z.array(z.string()).optional(),
+  })
+  .refine((value) => Object.keys(value).length > 0, 'update must name at least one field')
+export const ticketMoveRequestSchema = z.strictObject({ state: z.string().min(1) })
+export const ticketBlockerRequestSchema = z.strictObject({
+  blockerIds: z.array(z.string().min(1)).min(1),
+})
+export type OperatorTicketCreateRequest = z.infer<typeof ticketCreateRequestSchema>
+export type OperatorTicketUpdateRequest = z.infer<typeof ticketUpdateRequestSchema>
+export type OperatorTicketMoveRequest = z.infer<typeof ticketMoveRequestSchema>
+export type OperatorTicketBlockerRequest = z.infer<typeof ticketBlockerRequestSchema>
+
+export const operatorErrorSchema = z.strictObject({
+  kind: z.enum(['validation', 'auth', 'not-found', 'conflict', 'refusal', 'internal']),
+  error: z.string(),
+  code: z.string().optional(),
+  progress: z.unknown().optional(),
+})
+export type OperatorErrorBody = z.infer<typeof operatorErrorSchema>
+
+export const sessionCreateRequestSchema = z.strictObject({ title: z.string().min(1).optional() })
+export type OperatorSessionCreateRequest = z.infer<typeof sessionCreateRequestSchema>
+
+export const sessionMessageRequestSchema = z.strictObject({ text: z.string().trim().min(1) })
+export type OperatorSessionMessageRequest = z.infer<typeof sessionMessageRequestSchema>
+
+export const sessionWakeRequestSchema = z.strictObject({
+  globs: z.array(z.string().min(1)).max(100),
+})
+export type OperatorSessionWakeRequest = z.infer<typeof sessionWakeRequestSchema>
+
+export const sessionApprovalRequestSchema = z.strictObject({
+  turn: z.string().min(1),
+  toolCallId: z.string().min(1),
+  decision: z.enum(['approve', 'deny']),
+})
+export type OperatorSessionApprovalRequest = z.infer<typeof sessionApprovalRequestSchema>

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

@@ -0,0 +1,201 @@
+import { configSchema, type Config } from '../config/schema'
+import { detail, statusFilter, summarize, type BuildDetail, type BuildSummary } from '../cli/status'
+import { projectRepositoryStatus, type RepositoryStatus } from '../cli/repository-status'
+import { projectHarvestStatus, type HarvestStatusView } from '../cli/harvest'
+import {
+  buildDashboardFromProjected,
+  projectBuild,
+  type DashboardBuild,
+  type DashboardModel,
+} from '../cli/dashboard/model'
+import { reduceBuild } from '../kernel/reducer'
+import { reduceDispatchStatus } from '../kernel/dispatch-status'
+import { scanUnclaimedObservations } from '../processes/harvest'
+import type { BuildStore, Clock } from '../store/types'
+
+export type BuildListScope = 'active' | 'queued' | 'all'
+
+export class OperatorQueryError extends Error {
+  constructor(
+    readonly code: 'not-found' | 'effective-config-unavailable',
+    message: string,
+  ) {
+    super(message)
+    this.name = 'OperatorQueryError'
+  }
+}
+
+async function repoEvents(store: BuildStore, repo: string) {
+  return (await store.getRepo(repo)) === null ? [] : store.getRepoEvents(repo)
+}
+
+export async function listOperatorBuilds(opts: {
+  store: BuildStore
+  repo: string
+  scope: BuildListScope
+  now: Date
+}): Promise<BuildSummary[]> {
+  const statuses = new Set(statusFilter(opts.scope === 'all', opts.scope === 'queued'))
+  const output: BuildSummary[] = []
+  for (const record of await opts.store.listBuilds()) {
+    if (record.repo !== opts.repo) continue
+    const projected = summarize(record, await opts.store.getEvents(record.slug), opts.now)
+    if (statuses.has(projected.status)) output.push(projected)
+  }
+  return output.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+}
+
+async function requireBuild(store: BuildStore, repo: string, slug: string) {
+  const record = await store.getBuild(slug)
+  if (record === null) throw new OperatorQueryError('not-found', `no build "${slug}" in this store`)
+  if (record.repo !== repo) {
+    throw new OperatorQueryError('not-found', `unknown build "${slug}"`)
+  }
+  return record
+}
+
+export async function effectiveConfig(
+  store: BuildStore,
+  repo: string,
+): Promise<{
+  config: Config
+  repositoryEvents: Awaited<ReturnType<typeof repoEvents>>
+  status: ReturnType<typeof reduceDispatchStatus>
+}> {
+  const repositoryEvents = await repoEvents(store, repo)
+  let latestRun: string | undefined
+  for (const event of repositoryEvents) {
+    if (event.type === 'dispatcher.run-started') latestRun = event.payload.run
+  }
+  if (latestRun === undefined) {
+    throw new OperatorQueryError(
+      'effective-config-unavailable',
+      `effective config unavailable for repository "${repo}": no dispatcher run is recorded`,
+    )
+  }
+  const status = reduceDispatchStatus(repositoryEvents, latestRun)
+  const ref = status.effectiveConfig
+  if (ref === undefined) {
+    throw new OperatorQueryError(
+      'effective-config-unavailable',
+      `effective config unavailable for repository "${repo}"`,
+    )
+  }
+  const artifact = await store.getRepoArtifact(repo, ref.kind, ref.rev)
+  if (artifact === null) {
+    throw new OperatorQueryError(
+      'effective-config-unavailable',
+      `effective config ${ref.kind}@${ref.rev} is not retrievable`,
+    )
+  }
+  let raw: unknown
+  try {
+    raw = JSON.parse(new TextDecoder().decode(artifact.content))
+  } catch {
+    throw new OperatorQueryError(
+      'effective-config-unavailable',
+      `effective config ${ref.kind}@${ref.rev} is not valid JSON`,
+    )
+  }
+  const parsed = configSchema.safeParse(raw)
+  if (!parsed.success) {
+    throw new OperatorQueryError(
+      'effective-config-unavailable',
+      `effective config ${ref.kind}@${ref.rev} is invalid: ${parsed.error.message}`,
+    )
+  }
+  return { config: parsed.data, repositoryEvents, status }
+}
+
+export interface OperatorBuildView {
+  detail: BuildDetail
+  dashboardRow: DashboardBuild | null
+}
+
+export async function getOperatorBuild(opts: {
+  store: BuildStore
+  repo: string
+  slug: string
+  now: Date
+}): Promise<OperatorBuildView> {
+  const record = await requireBuild(opts.store, opts.repo, opts.slug)
+  const events = await opts.store.getEvents(opts.slug)
+  const state = reduceBuild(events)
+  const { config } = await effectiveConfig(opts.store, opts.repo)
+  const dashboardRow = projectBuild(record, state, config, events)
+  return { detail: detail(record, events, opts.now), dashboardRow }
+}
+
+export async function getRepositoryStatus(
+  store: BuildStore,
+  repo: string,
+): Promise<RepositoryStatus> {
+  return projectRepositoryStatus(repo, await repoEvents(store, repo))
+}
+
+export async function getHarvestStatus(
+  store: BuildStore,
+  repo: string,
+): Promise<HarvestStatusView> {
+  return projectHarvestStatus(repo, await repoEvents(store, repo))
+}
+
+export interface OperatorDashboardSnapshot {
+  generatedAt: string
+  model: DashboardModel
+  settingsHeader: {
+    intake: boolean
+    repositoryPaused: boolean
+    defaultAutoMerge: boolean
+    harvestPaused: boolean
+  }
+}
+
+export async function getOperatorDashboard(opts: {
+  store: BuildStore
+  repo: string
+  clock: Clock
+}): Promise<OperatorDashboardSnapshot> {
+  const { config, repositoryEvents, status } = await effectiveConfig(opts.store, opts.repo)
+  const projected: DashboardBuild[] = []
+  let activeCount = 0
+  for (const record of await opts.store.listBuilds()) {
+    if (record.repo !== opts.repo) continue
+    const events = await opts.store.getEvents(record.slug)
+    const state = reduceBuild(events)
+    if (state.status !== 'done' && state.status !== 'aborted') activeCount += 1
+    const row = projectBuild(record, state, config, events)
+    if (row !== null) projected.push(row)
+  }
+  const scan = await scanUnclaimedObservations(opts.store, opts.repo)
+  const warningLines = [
+    ...status.roleWarnings,
+    ...(status.warningNotice !== undefined ? [status.warningNotice] : []),
+  ]
+  const model = buildDashboardFromProjected(
+    projected,
+    {
+      repo: opts.repo,
+      queued: status.queued ?? 0,
+      activeCount,
+      capacity: config.capacity,
+      observationCount: scan.observations.length,
+      observationLimit: config.policy.harvestThreshold,
+      ...(status.availableUpgrade !== undefined
+        ? { availableUpgrade: status.availableUpgrade }
+        : {}),
+      ...(warningLines.length > 0 ? { warningLines } : {}),
+    },
+    repositoryEvents,
+  )
+  return {
+    generatedAt: opts.clock().toISOString(),
+    model,
+    settingsHeader: {
+      intake: !model.drained,
+      repositoryPaused: model.repositoryPaused,
+      defaultAutoMerge: model.defaultAutoMerge,
+      harvestPaused: model.harvestPaused,
+    },
+  }
+}