baa-conductor

contracts.ts

  1export const DEFAULT_RUNS_DIRECTORY_NAME = "runs";
  2export const DEFAULT_RUN_LAYOUT_VERSION = "local-run-v1";
  3
  4export type StructuredValue =
  5  | string
  6  | number
  7  | boolean
  8  | null
  9  | StructuredValue[]
 10  | { [key: string]: StructuredValue };
 11
 12export type StructuredData = Record<string, StructuredValue>;
 13
 14export type LogLevel = "debug" | "info" | "warn" | "error";
 15export type WorkerLogChannel = "worker" | "stdout" | "stderr";
 16export type StreamLogChannel = "stdout" | "stderr";
 17export type RunStatus = "prepared" | "running" | "completed" | "failed" | "blocked";
 18
 19export type WorkerLifecycleEventType =
 20  | "run_prepared"
 21  | "checkpoint_slot_reserved"
 22  | "worker_started"
 23  | "worker_execution_deferred"
 24  | "worker_exited"
 25  | "step_prepared"
 26  | "step_completed"
 27  | "step_failed"
 28  | "step_blocked";
 29
 30export interface LocalRunDirectoryRequest {
 31  repoRoot: string;
 32  taskId: string;
 33  runId: string;
 34  runsRootDir?: string;
 35}
 36
 37export interface LocalRunPaths {
 38  layoutVersion: string;
 39  repoRoot: string;
 40  runsRootDir: string;
 41  taskRunsDir: string;
 42  runDir: string;
 43  checkpointsDir: string;
 44  artifactsDir: string;
 45  metaPath: string;
 46  statePath: string;
 47  workerLogPath: string;
 48  stdoutLogPath: string;
 49  stderrLogPath: string;
 50}
 51
 52export interface LocalRunLogContext {
 53  taskId: string;
 54  stepId: string;
 55  runId: string;
 56}
 57
 58export interface LocalRunLogTarget {
 59  channel: WorkerLogChannel;
 60  filePath: string;
 61}
 62
 63export interface LocalRunLogTargets {
 64  worker: LocalRunLogTarget;
 65  stdout: LocalRunLogTarget;
 66  stderr: LocalRunLogTarget;
 67}
 68
 69export interface WorkerLifecycleEventInput {
 70  type: WorkerLifecycleEventType;
 71  level: LogLevel;
 72  message: string;
 73  createdAt?: string;
 74  data?: StructuredData;
 75}
 76
 77export interface WorkerLifecycleLogEntry extends LocalRunLogContext {
 78  seq: number;
 79  channel: "worker";
 80  eventId: string;
 81  type: WorkerLifecycleEventType;
 82  level: LogLevel;
 83  createdAt: string;
 84  message: string;
 85  data: StructuredData;
 86  renderedLine: string;
 87}
 88
 89export interface StreamChunkInput {
 90  text: string;
 91  createdAt?: string;
 92}
 93
 94export interface StreamChunkLogEntry extends LocalRunLogContext {
 95  seq: number;
 96  channel: StreamLogChannel;
 97  createdAt: string;
 98  text: string;
 99}
100
101export interface WorkerLifecycleLogStream {
102  channel: "worker";
103  filePath: string;
104  entries: WorkerLifecycleLogEntry[];
105}
106
107export interface StreamChunkLogStream {
108  channel: StreamLogChannel;
109  filePath: string;
110  entries: StreamChunkLogEntry[];
111}
112
113export interface LocalRunLogSession {
114  context: LocalRunLogContext;
115  paths: LocalRunPaths;
116  nextSeq: number;
117  worker: WorkerLifecycleLogStream;
118  stdout: StreamChunkLogStream;
119  stderr: StreamChunkLogStream;
120}
121
122export interface LocalRunLogSummary {
123  totalEntries: number;
124  lastSeq: number;
125  lifecycleEventCount: number;
126  stdoutChunkCount: number;
127  stderrChunkCount: number;
128}
129
130export interface RunMetadata {
131  layoutVersion: string;
132  taskId: string;
133  stepId: string;
134  stepName: string;
135  runId: string;
136  workerKind: string;
137  attempt: number;
138  repoRoot: string;
139  worktreePath: string;
140  createdAt: string;
141  checkpointMode: string;
142  promptSummary?: string;
143  command?: string;
144}
145
146export interface RunMetadataInput {
147  taskId: string;
148  stepId: string;
149  stepName: string;
150  runId: string;
151  workerKind: string;
152  attempt: number;
153  repoRoot: string;
154  worktreePath: string;
155  createdAt: string;
156  checkpointMode: string;
157  promptSummary?: string;
158  command?: string;
159}
160
161export interface RunStateSnapshot {
162  status: RunStatus;
163  attempt: number;
164  startedAt: string;
165  updatedAt: string;
166  finishedAt?: string;
167  lastEventSeq: number;
168  checkpointSeq: number;
169  summary?: string;
170  exitCode?: number;
171}
172
173export interface RunStateSnapshotInput {
174  attempt: number;
175  startedAt: string;
176  checkpointSeq?: number;
177  summary?: string;
178}
179
180export interface RunStatePatch {
181  status?: RunStatus;
182  updatedAt?: string;
183  finishedAt?: string;
184  lastEventSeq?: number;
185  checkpointSeq?: number;
186  summary?: string;
187  exitCode?: number;
188}