baa-conductor

contracts.ts

  1import type {
  2  CheckpointManager,
  3  CheckpointManagerState,
  4  CheckpointRecord,
  5  CheckpointType,
  6  GitDiffSnapshotPlan
  7} from "@baa-conductor/checkpointing";
  8import type {
  9  LocalRunLogSession,
 10  LocalRunLogSummary,
 11  LocalRunPaths,
 12  RunMetadata,
 13  RunStateSnapshot,
 14  WorkerLifecycleLogEntry
 15} from "@baa-conductor/logging";
 16
 17export type WorkerKind = "codex" | "shell" | "git";
 18export type StepKind = WorkerKind | "planner" | "review" | "finalize";
 19export type StepExecutionOutcome = "prepared" | "completed" | "failed" | "blocked";
 20export type CheckpointMode = "disabled" | "capture";
 21export type StepArtifactKind = "log" | "metadata" | "state" | "directory" | "artifact";
 22
 23export interface StepExecutionRuntime {
 24  repoRoot: string;
 25  worktreePath: string;
 26  runsRootDir?: string;
 27  env?: Record<string, string>;
 28}
 29
 30export interface StepCheckpointConfig {
 31  mode: CheckpointMode;
 32  resumeFromSeq?: number;
 33  summaryHint?: string;
 34  gitDiffBaseRef?: string;
 35  includeGitDiffStat?: boolean;
 36  logTailLines?: number;
 37}
 38
 39export interface StepExecutionRequest {
 40  taskId: string;
 41  stepId: string;
 42  runId: string;
 43  attempt: number;
 44  stepName: string;
 45  stepKind: StepKind;
 46  workerKind: WorkerKind;
 47  timeoutSec: number;
 48  runtime: StepExecutionRuntime;
 49  createdAt?: string;
 50  promptSummary?: string;
 51  command?: string;
 52  checkpoint?: StepCheckpointConfig;
 53}
 54
 55export interface StepCheckpointState extends CheckpointManagerState {
 56  mode: CheckpointMode;
 57  lastCheckpointSeq: number;
 58  nextCheckpointSeq: number;
 59  latest?: CheckpointRecord;
 60  supportedTypes: CheckpointType[];
 61  records: CheckpointRecord[];
 62  gitDiffPlan?: GitDiffSnapshotPlan;
 63}
 64
 65export interface StepArtifact {
 66  name: string;
 67  kind: StepArtifactKind;
 68  path: string;
 69  description: string;
 70}
 71
 72export interface SuggestedFollowup {
 73  stepName: string;
 74  stepKind: StepKind;
 75  reason: string;
 76}
 77
 78export interface WorkerExecutionOutcome {
 79  ok: boolean;
 80  outcome: StepExecutionOutcome;
 81  summary: string;
 82  needsHuman?: boolean;
 83  blocked?: boolean;
 84  stdout?: string[];
 85  stderr?: string[];
 86  artifacts?: StepArtifact[];
 87  suggestedFollowup?: SuggestedFollowup[];
 88  exitCode?: number;
 89}
 90
 91export interface WorkerExecutor {
 92  execute(run: PreparedStepRun): Promise<WorkerExecutionOutcome>;
 93}
 94
 95export interface PreparedStepRun {
 96  request: StepExecutionRequest;
 97  logPaths: LocalRunPaths;
 98  logSession: LocalRunLogSession;
 99  metadata: RunMetadata;
100  state: RunStateSnapshot;
101  checkpoint: StepCheckpointState;
102  checkpointManager: CheckpointManager;
103}
104
105export interface StepExecutionMetrics {
106  durationMs: number;
107  lifecycleEventCount: number;
108  stdoutChunkCount: number;
109  stderrChunkCount: number;
110  checkpointCount: number;
111}
112
113export interface StepExecutionResult {
114  ok: boolean;
115  outcome: StepExecutionOutcome;
116  summary: string;
117  needsHuman: boolean;
118  blocked: boolean;
119  taskId: string;
120  stepId: string;
121  runId: string;
122  attempt: number;
123  workerKind: WorkerKind;
124  startedAt: string;
125  finishedAt: string;
126  durationMs: number;
127  metadata: RunMetadata;
128  state: RunStateSnapshot;
129  logPaths: LocalRunPaths;
130  logSession: LocalRunLogSession;
131  logSummary: LocalRunLogSummary;
132  lifecycleEvents: WorkerLifecycleLogEntry[];
133  checkpoint: StepCheckpointState;
134  artifacts: StepArtifact[];
135  suggestedFollowup: SuggestedFollowup[];
136  metrics: StepExecutionMetrics;
137}