| 1 | export type FleetRunId = string; |
| 2 | export type FleetRunStatus = |
| 3 | | "pending" |
| 4 | | "queued" |
| 5 | | "running" |
| 6 | | "paused" |
| 7 | | "completed" |
| 8 | | "failed" |
| 9 | | "cancelled"; |
| 10 | |
| 11 | export type FleetRuntimeTarget = "this_computer" | "another_computer" | "cloud"; |
| 12 | export type FleetWorkflowKind = "parallel"; |
| 13 | |
| 14 | export interface FleetWorkflowDescriptor { |
| 15 | id: string; |
| 16 | kind: FleetWorkflowKind; |
| 17 | } |
| 18 | |
| 19 | export type FleetWorkerStatus = |
| 20 | | "unknown" |
| 21 | | "online" |
| 22 | | "busy" |
| 23 | | "offline" |
| 24 | | "unhealthy" |
| 25 | | "draining" |
| 26 | | "retired"; |
| 27 | |
| 28 | export type FleetArtifactKind = |
| 29 | | "log" |
| 30 | | "patch" |
| 31 | | "test_result" |
| 32 | | "report" |
| 33 | | "checkpoint" |
| 34 | | "receipt" |
| 35 | | string; |
| 36 | |
| 37 | export interface FleetStatusSummary { |
| 38 | runs: number; |
| 39 | queued: number; |
| 40 | running: number; |
| 41 | completed: number; |
| 42 | partial: number; |
| 43 | failed: number; |
| 44 | restarted: number; |
| 45 | escalated: number; |
| 46 | transport_failed: number; |
| 47 | task_failed: number; |
| 48 | verifier_failed: number; |
| 49 | cancelled: number; |
| 50 | stale: number; |
| 51 | workers: Record<string, FleetWorkerStatus>; |
| 52 | } |
| 53 | |
| 54 | export interface FleetTaskStatusSummary { |
| 55 | task_id: string; |
| 56 | status: "enqueued" | "leased" | "completed" | "failed" | "cancelled"; |
| 57 | leased_to?: string | null; |
| 58 | attempts: number; |
| 59 | } |
| 60 | |
| 61 | export interface FleetRunSummary { |
| 62 | id: string; |
| 63 | name: string; |
| 64 | lifecycle_status: FleetRunStatus; |
| 65 | status: FleetStatusSummary; |
| 66 | target?: FleetRuntimeTarget | null; |
| 67 | workflow?: FleetWorkflowDescriptor | null; |
| 68 | roles: string[]; |
| 69 | task_count: number; |
| 70 | worker_count: number; |
| 71 | tasks: FleetTaskStatusSummary[]; |
| 72 | labels: Record<string, string>; |
| 73 | created_at: string; |
| 74 | updated_at?: string | null; |
| 75 | completed_at?: string | null; |
| 76 | } |
| 77 | |
| 78 | export interface FleetRunDetail extends FleetRunSummary { |
| 79 | task_specs: FleetTaskSpec[]; |
| 80 | worker_specs: FleetWorkerSpec[]; |
| 81 | } |
| 82 | |
| 83 | export interface FleetRunsResponse { |
| 84 | status: FleetStatusSummary; |
| 85 | runs: FleetRunSummary[]; |
| 86 | } |
| 87 | |
| 88 | export interface FleetTaskSpec { |
| 89 | id: string; |
| 90 | name: string; |
| 91 | description?: string | null; |
| 92 | objective?: string | null; |
| 93 | instructions: string; |
| 94 | worker?: FleetTaskWorkerProfile | null; |
| 95 | workspace?: FleetWorkspaceRequirements | null; |
| 96 | input_files?: string[]; |
| 97 | context?: string[]; |
| 98 | budget?: FleetTaskBudget | null; |
| 99 | tags?: string[]; |
| 100 | expected_artifacts?: FleetArtifactKind[]; |
| 101 | scorer?: Record<string, unknown> | null; |
| 102 | retry_policy?: Record<string, unknown> | null; |
| 103 | alert_policy?: FleetAlertPolicy | null; |
| 104 | timeout_seconds?: number | null; |
| 105 | metadata?: Record<string, unknown>; |
| 106 | } |
| 107 | |
| 108 | export interface FleetTaskWorkerProfile { |
| 109 | agent_profile?: string | null; |
| 110 | role?: string | null; |
| 111 | loadout?: string | null; |
| 112 | model_class?: string | null; |
| 113 | model?: string | null; |
| 114 | tool_profile?: string | null; |
| 115 | tools?: string[]; |
| 116 | capabilities?: string[]; |
| 117 | } |
| 118 | |
| 119 | export interface FleetWorkspaceRequirements { |
| 120 | root?: string | null; |
| 121 | required_files?: string[]; |
| 122 | writable_paths?: string[]; |
| 123 | environment?: FleetEnvironmentRequirements | null; |
| 124 | } |
| 125 | |
| 126 | export interface FleetEnvironmentRequirements { |
| 127 | required?: string[]; |
| 128 | allowlist?: string[]; |
| 129 | } |
| 130 | |
| 131 | export interface FleetTaskBudget { |
| 132 | max_tokens?: number | null; |
| 133 | /** Maximum model turns. Omitted, null, or zero means unbounded. */ |
| 134 | max_steps?: number | null; |
| 135 | /** Maximum admitted tool calls. Omitted, null, or zero means unbounded. */ |
| 136 | max_tool_calls?: number | null; |
| 137 | max_seconds?: number | null; |
| 138 | } |
| 139 | |
| 140 | export interface FleetAlertPolicy { |
| 141 | events?: string[]; |
| 142 | channels?: Array<Record<string, unknown>>; |
| 143 | after_attempts?: number | null; |
| 144 | after_minutes_stale?: number | null; |
| 145 | } |
| 146 | |
| 147 | export interface FleetWorkerSpec { |
| 148 | id: string; |
| 149 | name: string; |
| 150 | host: Record<string, unknown>; |
| 151 | labels?: Record<string, string>; |
| 152 | capabilities?: string[]; |
| 153 | max_concurrent_tasks?: number | null; |
| 154 | } |
| 155 | |
| 156 | export interface FleetArtifactRef { |
| 157 | kind: FleetArtifactKind; |
| 158 | path: string; |
| 159 | checksum?: string | null; |
| 160 | mime_type?: string | null; |
| 161 | size_bytes?: number | null; |
| 162 | } |
| 163 | |
| 164 | export type FleetWorkerEventPayload = |
| 165 | | { state: "queued" } |
| 166 | | { state: "leased"; lease_expires_at?: string | null } |
| 167 | | { state: "starting" } |
| 168 | | { state: "running" } |
| 169 | | { state: "model_wait"; model?: string | null } |
| 170 | | { state: "running_tool"; tool: string; call_id?: string | null } |
| 171 | | { state: "heartbeat"; cpu_percent?: number | null; memory_mb?: number | null } |
| 172 | | ({ state: "artifact" } & FleetArtifactRef) |
| 173 | | { state: "completed"; exit_code?: number | null; summary?: string | null } |
| 174 | | { state: "failed"; reason: string; recoverable?: boolean } |
| 175 | | { state: "cancelled"; cancelled_by?: string | null } |
| 176 | | { state: "interrupted"; signal?: string | null } |
| 177 | | { state: "stale"; last_heartbeat_at?: string | null } |
| 178 | | { state: "restarted"; restart_count?: number } |
| 179 | | { state: "escalated"; channel: string; alert_id?: string | null }; |
| 180 | |
| 181 | export interface FleetWorkerEvent { |
| 182 | seq: number; |
| 183 | run_id: string; |
| 184 | worker_id: string; |
| 185 | task_id: string; |
| 186 | timestamp: string; |
| 187 | label?: string; |
| 188 | payload: FleetWorkerEventPayload; |
| 189 | extra?: Record<string, unknown>; |
| 190 | } |
| 191 | |
| 192 | export interface FleetWorkerInspection { |
| 193 | worker_id: string; |
| 194 | status: FleetWorkerStatus; |
| 195 | run_id?: string | null; |
| 196 | task_id?: string | null; |
| 197 | objective?: string | null; |
| 198 | role?: string | null; |
| 199 | host?: Record<string, unknown> | null; |
| 200 | latest_heartbeat_at?: string | null; |
| 201 | latest_event?: FleetWorkerEvent | null; |
| 202 | artifacts: FleetArtifactRef[]; |
| 203 | last_error?: string | null; |
| 204 | alert_state?: Record<string, unknown> | null; |
| 205 | } |
| 206 | |
| 207 | export interface FleetWorkersResponse { |
| 208 | run_id: string; |
| 209 | workers: FleetWorkerInspection[]; |
| 210 | } |
| 211 | |
| 212 | export interface FleetWorkerActionResponse { |
| 213 | action: "interrupt" | "restart" | "stop"; |
| 214 | worker: FleetWorkerInspection; |
| 215 | } |
| 216 | |
| 217 | export interface StopFleetRunResponse { |
| 218 | action: "stop"; |
| 219 | run_id: string; |
| 220 | stopped: number; |
| 221 | status: FleetStatusSummary; |
| 222 | } |
| 223 | |
| 224 | export interface ManagedFleetRole { |
| 225 | name: string; |
| 226 | agent_profile?: string | null; |
| 227 | } |
| 228 | |
| 229 | export interface ManagedFleetWorkflow extends FleetWorkflowDescriptor { |
| 230 | tasks: FleetTaskSpec[]; |
| 231 | } |
| 232 | |
| 233 | export interface FleetRunCreateSpec { |
| 234 | name?: string; |
| 235 | target: FleetRuntimeTarget; |
| 236 | roles: ManagedFleetRole[]; |
| 237 | workflow: ManagedFleetWorkflow; |
| 238 | labels?: Record<string, string>; |
| 239 | max_workers?: number; |
| 240 | } |
| 241 | |
| 242 | export interface CreateFleetRunResponse { |
| 243 | execution: "awaiting_start"; |
| 244 | run: FleetRunDetail; |
| 245 | warnings: string[]; |
| 246 | } |
| 247 | |
| 248 | export interface StartFleetRunResponse { |
| 249 | action: "start"; |
| 250 | execution: "scheduled"; |
| 251 | run_id: string; |
| 252 | target: "this_computer"; |
| 253 | /** Leasing begins only after the scheduled driver owns the run. */ |
| 254 | leased: 0; |
| 255 | queued: number; |
| 256 | worker_ids: string[]; |
| 257 | } |
| 258 | |
| 259 | export interface FleetRuntimeEvent { |
| 260 | cursor: string; |
| 261 | event: string; |
| 262 | run_id: string; |
| 263 | worker_id?: string | null; |
| 264 | task_id?: string | null; |
| 265 | timestamp?: string | null; |
| 266 | worker_seq?: number | null; |
| 267 | payload: Record<string, unknown>; |
| 268 | } |
| 269 | |
| 270 | export interface FleetStreamControlEvent { |
| 271 | event: |
| 272 | | "fleet.replay.truncated" |
| 273 | | "fleet.replay.cursor_unavailable" |
| 274 | | "fleet.stream.error"; |
| 275 | run_id?: string; |
| 276 | cursor?: never; |
| 277 | reload_projection?: boolean; |
| 278 | retryable?: boolean; |
| 279 | } |
| 280 | |
| 281 | export type FleetStreamEvent = FleetRuntimeEvent | FleetStreamControlEvent; |
| 282 | |
| 283 | export interface FleetEventReplay { |
| 284 | run_id: string; |
| 285 | events: FleetRuntimeEvent[]; |
| 286 | has_more: boolean; |
| 287 | history_truncated: boolean; |
| 288 | next_cursor?: string | null; |
| 289 | } |
| 290 | |
| 291 | export interface FleetEventOptions { |
| 292 | after?: string; |
| 293 | limit?: number; |
| 294 | } |
| 295 | |
| 296 | export interface RuntimeClientOptions { |
| 297 | baseUrl?: string; |
| 298 | token?: string; |
| 299 | fetch?: typeof fetch; |
| 300 | } |
| 301 | |
| 302 | export interface ThreadRuntimeEvent { |
| 303 | schema_version?: number; |
| 304 | seq: number; |
| 305 | previous_seq?: number; |
| 306 | event: string; |
| 307 | thread_id: string; |
| 308 | turn_id?: string | null; |
| 309 | item_id?: string | null; |
| 310 | timestamp: string; |
| 311 | payload: Record<string, unknown>; |
| 312 | } |
| 313 | |
| 314 | /** Transport progress at the existing journal cursor; never a new event. */ |
| 315 | export interface ThreadStreamProgress { |
| 316 | event: "stream.progress"; |
| 317 | thread_id: string; |
| 318 | seq: number; |
| 319 | state: "replaying" | "live"; |
| 320 | } |
| 321 | |
| 322 | export interface ThreadEventOptions { |
| 323 | sinceSeq?: number; |
| 324 | replayLimit?: number; |
| 325 | signal?: AbortSignal; |
| 326 | } |
| 327 | |
| 328 | export class RuntimeApiError extends Error { |
| 329 | status?: number; |
| 330 | method?: string; |
| 331 | path?: string; |
| 332 | body?: string; |
| 333 | } |
| 334 | |
| 335 | export class RuntimeCapabilityError extends RuntimeApiError { |
| 336 | capability: string; |
| 337 | } |
| 338 | |
| 339 | export class CodeWhaleRuntimeClient { |
| 340 | constructor(options?: RuntimeClientOptions); |
| 341 | createFleetRun(spec: FleetRunCreateSpec): Promise<CreateFleetRunResponse>; |
| 342 | startFleetRun(runId: FleetRunId): Promise<StartFleetRunResponse>; |
| 343 | replayFleetEvents(runId: FleetRunId, options?: FleetEventOptions): Promise<FleetEventReplay>; |
| 344 | listFleetRuns(): Promise<FleetRunsResponse>; |
| 345 | getFleetRun(runId: FleetRunId): Promise<FleetRunDetail>; |
| 346 | listFleetWorkers(runId: FleetRunId): Promise<FleetWorkersResponse>; |
| 347 | getFleetWorker(workerId: string): Promise<FleetWorkerInspection>; |
| 348 | interruptWorker(workerId: string): Promise<FleetWorkerActionResponse>; |
| 349 | stopWorker(workerId: string): Promise<FleetWorkerActionResponse>; |
| 350 | restartWorker(workerId: string): Promise<FleetWorkerActionResponse>; |
| 351 | stopFleetRun(runId: FleetRunId): Promise<StopFleetRunResponse>; |
| 352 | fleetEvents( |
| 353 | runId: FleetRunId, |
| 354 | options?: FleetEventOptions & { path?: string }, |
| 355 | ): AsyncIterable<FleetStreamEvent>; |
| 356 | threadEvents(threadId: string, options: ThreadEventOptions & { includeProgress: true }): AsyncIterable<ThreadRuntimeEvent | ThreadStreamProgress>; |
| 357 | threadEvents(threadId: string, options?: ThreadEventOptions & { includeProgress?: false }): AsyncIterable<ThreadRuntimeEvent>; |
| 358 | threadEvents(threadId: string, options: ThreadEventOptions & { includeProgress: boolean }): AsyncIterable<ThreadRuntimeEvent | ThreadStreamProgress>; |
| 359 | } |
| 360 | |
| 361 | export function createRuntimeClient(options?: RuntimeClientOptions): CodeWhaleRuntimeClient; |
| 362 |