@yaag/runtime 0.26.0 → 0.28.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/package.json +1 -1
  2. package/src/agent/agent-name.ts +22 -0
  3. package/src/agent/agent-names.ts +5 -1
  4. package/src/agent/agent.ts +34 -17
  5. package/src/agent/define-agent.ts +4 -0
  6. package/src/agent/fork.ts +50 -12
  7. package/src/agent/host-fork.ts +85 -0
  8. package/src/agent/index.ts +1 -0
  9. package/src/agent/spawn-definition-request.ts +41 -6
  10. package/src/agent/spawn-open.ts +54 -107
  11. package/src/agent/spawn-parent.ts +64 -0
  12. package/src/agent/spawn-plan.ts +120 -0
  13. package/src/agent/spawn-request.ts +26 -6
  14. package/src/agent/spawn.ts +47 -6
  15. package/src/ask/ask-exchange-options.ts +3 -6
  16. package/src/ask/ask-exchange.ts +48 -108
  17. package/src/ask/ask-guard.ts +207 -0
  18. package/src/ask/ask-timing.ts +12 -0
  19. package/src/ask/index.ts +1 -0
  20. package/src/cassette/cassette-loader.ts +9 -20
  21. package/src/cassette/cassette-schema.ts +11 -1
  22. package/src/cassette/cassette.ts +16 -34
  23. package/src/cassette/checkpoint.ts +306 -0
  24. package/src/cassette/index.ts +16 -7
  25. package/src/cassette/parked-asks.ts +38 -0
  26. package/src/cassette/replay-divergence.ts +7 -102
  27. package/src/cassette/resume-identity.ts +5 -1
  28. package/src/cassette/resume-preconditions.ts +14 -0
  29. package/src/cassette/resume-transport.ts +26 -32
  30. package/src/cassette/run-identity.ts +109 -0
  31. package/src/cassette/session-answer.ts +51 -114
  32. package/src/cassette/spawn-identity.ts +328 -0
  33. package/src/contract/error-codes.ts +4 -0
  34. package/src/contract/group.ts +38 -0
  35. package/src/contract/index.ts +2 -0
  36. package/src/contract/spawn-options.ts +48 -7
  37. package/src/error-factories.ts +8 -0
  38. package/src/events.ts +22 -2
  39. package/src/index.ts +7 -0
  40. package/src/pi-session/append-tool-result.ts +165 -0
  41. package/src/pi-session/index.ts +30 -0
  42. package/src/pi-session/pi-session-error.ts +34 -0
  43. package/src/pi-session/session-copy.ts +113 -0
  44. package/src/pi-session/session-entries.ts +130 -0
  45. package/src/public-api.ts +2 -0
  46. package/src/question-summary/index.ts +4 -8
  47. package/src/question-summary/summarize-question.ts +1 -1
  48. package/src/question-summary/summary-policy.ts +5 -2
  49. package/src/run/agent-questions.ts +82 -0
  50. package/src/run/answers.ts +22 -1
  51. package/src/run/groups.ts +111 -0
  52. package/src/run/host-session.ts +233 -0
  53. package/src/run/index.ts +8 -0
  54. package/src/run/run-context.ts +15 -0
  55. package/src/run/run.ts +208 -182
  56. package/src/summary/index.ts +1 -0
  57. package/src/summary/summary-agent.ts +6 -0
  58. package/src/summary/summary-group.ts +31 -0
  59. package/src/summary/summary.ts +12 -0
  60. package/src/transport/live-transport.ts +19 -0
  61. package/src/transport/pi-state.ts +10 -1
  62. package/src/transport/transport.ts +20 -9
  63. package/src/types.ts +3 -0
  64. package/src/cassette/checkpoint-flush.ts +0 -101
  65. package/src/cassette/run-checkpoint.ts +0 -272
  66. package/src/question-summary/session-copy.ts +0 -169
@@ -1,7 +1,6 @@
1
1
  import type { TSchema } from "typebox";
2
2
  import type { AskOutputContract } from "../ask-contract/index.ts";
3
3
  import {
4
- AskLimit,
5
4
  LEGACY_ASK_OUTPUT_EXTRACTION_POLICY,
6
5
  REPORT_RESULT_WRAP_UP,
7
6
  ReportResultCall,
@@ -19,18 +18,13 @@ import { FrameGapTracker } from "../transport/index.ts";
19
18
  import { AskActivityTracker } from "./ask-activity.ts";
20
19
  import { type AskEndOutcome, AskEvents } from "./ask-exchange-events.ts";
21
20
  import type { AskExchangeOptions } from "./ask-exchange-options.ts";
21
+ import { AskGuard } from "./ask-guard.ts";
22
22
  import { askHash, askMarkerContext, structuredOutputContract } from "./ask-hash.ts";
23
23
  import { AskOutputSteering } from "./ask-output-steering.ts";
24
24
  import { AskOutputTail } from "./ask-output-tail.ts";
25
25
  import { awaitAskSettlement } from "./ask-settlement.ts";
26
26
  import { AskTurn } from "./ask-turn.ts";
27
- import { IdleKillSignal, IdleWatch } from "./idle-watch.ts";
28
- import {
29
- type SettlementCause,
30
- StallSignal,
31
- StallWatchdog,
32
- stallBudgetMs,
33
- } from "./stall-watchdog.ts";
27
+ import type { SettlementCause } from "./stall-watchdog.ts";
34
28
 
35
29
  export type { AskExchangeOptions } from "./ask-exchange-options.ts";
36
30
  /** Runs one Ask's transport exchange, including controls and structured-output correction. */
@@ -41,9 +35,13 @@ class AskExchange {
41
35
  readonly #options: AskExchangeOptions;
42
36
  #turn = new AskTurn();
43
37
  readonly #events: AskEvents;
44
- #limit: AskLimit | null = null;
45
- #idle: IdleWatch | null = null;
46
- #stall: StallWatchdog | null = null;
38
+ #guard: AskGuard | null = null;
39
+ /**
40
+ * The failure of an Ask with no guard: a replayed Ask has no control. It is
41
+ * per-exchange, so the reaction every settlement race registers on it dies
42
+ * with this Ask instead of accruing for the life of the process.
43
+ */
44
+ readonly #noFailure: Promise<never> = new Promise<never>(() => {});
47
45
  #gap: FrameGapTracker | null = null;
48
46
  #activity: AskActivityTracker | null = null;
49
47
  #output: AskOutputTail | null = null;
@@ -57,7 +55,6 @@ class AskExchange {
57
55
  #stalled: AskStalledOutcome | undefined;
58
56
  #invalidOutput: { readonly kind: "invalid_output"; readonly steeringEfforts: number } | undefined;
59
57
  #onSettled: () => void = () => {};
60
- #controlFailure: Promise<never> = new Promise<never>(() => {});
61
58
  #timeoutDeadline: number | undefined;
62
59
  #isParked = false;
63
60
  /** The parked `request_user_input` call of this Ask, when it parked (ADR-0021). */
@@ -68,7 +65,6 @@ class AskExchange {
68
65
  });
69
66
  #maxFrameGapMs: number | undefined;
70
67
  #cause: SettlementCause = "normal";
71
- #drainStaleFrames = false;
72
68
  constructor(options: AskExchangeOptions) {
73
69
  this.#options = options;
74
70
  this.#events = new AskEvents(options.emit, options.agent, options.index);
@@ -221,23 +217,25 @@ class AskExchange {
221
217
  // Playback reads the recorded call from the Cassette instead, so its value
222
218
  // cannot depend on how far the replayed frame stream has drained.
223
219
  this.#call = playback === undefined ? new ReportResultCall() : null;
224
- this.#limit = playback === undefined ? this.#createLimit() : null;
225
- this.#idle = playback === undefined ? this.#createIdleWatch() : null;
226
- this.#stall = playback === undefined ? this.#createStallWatchdog() : null;
220
+ // One guard per attempt: a failed attempt's trip may never settle the next
221
+ // one (ADR-0038). Playback builds none and reads the Cassette instead.
222
+ this.#guard = playback === undefined ? this.#createGuard() : null;
227
223
  this.#observe();
228
- this.#limit?.start();
229
- this.#idle?.start();
230
- this.#stall?.start();
224
+ this.#guard?.start();
231
225
  this.#gap?.start();
232
- this.#controlFailure = this.#createControlFailure();
233
226
  }
234
227
 
235
- #createLimit(): AskLimit {
236
- return new AskLimit({
228
+ #createGuard(): AskGuard {
229
+ return new AskGuard({
230
+ agent: this.#options.agent,
237
231
  ask: this.#options.ask,
238
- durationGraceMs: this.#options.askLimitGraceMs,
239
- command: async (frame) => (await this.#options.connection.command(frame)).success,
232
+ command: async (frame) => await this.#options.connection.command(frame),
233
+ terminal: () => this.#turn.terminal,
240
234
  ...(this.#reportsResult() ? { wrapUpSuffix: REPORT_RESULT_WRAP_UP } : {}),
235
+ ...(this.#options.timing === undefined ? {} : { timing: this.#options.timing }),
236
+ // The guard owns `cause` and `drainStaleFrames`; the exchange copies both
237
+ // at cleanup, so this hook only settles the turn.
238
+ onRecovered: () => this.#onSettled(),
241
239
  });
242
240
  }
243
241
 
@@ -266,44 +264,11 @@ class AskExchange {
266
264
  return recorded === LEGACY_ASK_OUTPUT_EXTRACTION_POLICY;
267
265
  }
268
266
 
269
- #createIdleWatch(): IdleWatch | null {
270
- if (this.#options.ask.idleMs === undefined) return null;
271
- return new IdleWatch({
272
- idleMs: this.#options.ask.idleMs,
273
- ...(this.#options.idleAbortSettleMs === undefined
274
- ? {}
275
- : { abortSettleMs: this.#options.idleAbortSettleMs }),
276
- command: async (frame) => (await this.#options.connection.command(frame)).success,
277
- });
278
- }
279
-
280
- #createStallWatchdog(): StallWatchdog | null {
281
- const stallMs = stallBudgetMs(this.#options.ask.stallMs);
282
- if (stallMs === null) return null;
283
- return new StallWatchdog({
284
- stallMs,
285
- ...(this.#options.stallProbeSettleMs === undefined
286
- ? {}
287
- : { probeSettleMs: this.#options.stallProbeSettleMs }),
288
- command: async (frame) => await this.#options.connection.command(frame),
289
- terminal: () => this.#turn.terminal,
290
- recover: () => {
291
- this.#cause = "recovered";
292
- // The missing `agent_settled` may still arrive: it belongs to the turn
293
- // yaag just settled by hand, never to the next Ask.
294
- this.#drainStaleFrames = true;
295
- this.#onSettled();
296
- },
297
- });
298
- }
299
-
300
267
  #observe(): void {
301
268
  this.#options.connection.observe((frame) => {
302
269
  this.#turn.observe(frame);
303
- this.#limit?.observe(frame);
270
+ this.#guard?.observe(frame);
304
271
  this.#observeQuestion(frame);
305
- if (frame.type !== "agent_settled" || this.#idle?.tripped) this.#idle?.observe(frame);
306
- this.#stall?.observe(frame);
307
272
  this.#gap?.observe();
308
273
  this.#activity?.observe(frame);
309
274
  this.#output?.observe(frame);
@@ -317,7 +282,7 @@ class AskExchange {
317
282
  this.#onSettled();
318
283
  }
319
284
  if (this.#turn.settled) {
320
- this.#stall?.settled();
285
+ this.#guard?.settled();
321
286
  this.#onSettled();
322
287
  }
323
288
  });
@@ -335,11 +300,8 @@ class AskExchange {
335
300
  if (this.#isParked) return;
336
301
  const call = readQuestionFrame(frame);
337
302
  if (call === null) return;
338
- if (this.#limit?.tripped === true) return;
303
+ if (this.#guard !== null && !this.#guard.suspend()) return;
339
304
  this.#isParked = true;
340
- this.#limit?.suspend();
341
- this.#idle?.suspend();
342
- this.#stall?.suspend();
343
305
  // Suspends the Ask's hard timeout: the wait is the human's from here.
344
306
  this.#resolveParked();
345
307
  this.#options.park?.();
@@ -350,50 +312,29 @@ class AskExchange {
350
312
  }
351
313
 
352
314
  /**
353
- * Re-opens the Question of a recorded parked Ask this resume did not answer
354
- * (ADR-0023). No live Agent exists, so nothing can park again by itself: the
355
- * Ask raises the same Question and stays open, and the Run pauses with it.
315
+ * Parks a recorded Ask this resume did not answer (ADR-0023). The Question is
316
+ * the Checkpoint's: the Run seeded the registry from its run block before the
317
+ * first Agent started, so this branch raises no Question. It marks the Ask
318
+ * parked, and the Run pauses with the same Question still open (ADR-0022).
356
319
  */
357
320
  #reopenParked(parked: NonNullable<AskPlayback["parked"]>): void {
358
321
  this.#isParked = true;
359
322
  this.#resolveParked();
360
323
  this.#options.park?.();
361
324
  // The registry's own id wins: the Question the Run advertises and the
362
- // incomplete marker the successor records must name one id (ADR-0022).
325
+ // incomplete marker the successor records must name one id (ADR-0022). An
326
+ // Agent with no ask-user capability still records a faithful marker.
363
327
  const questionId =
364
- this.#options.questions?.raise({
328
+ this.#options.questions?.park({
365
329
  agent: this.#options.agent,
366
330
  toolCallId: parked.toolCallId,
367
- question: parked.question,
368
- ...(parked.context === undefined ? {} : { context: parked.context }),
369
331
  }) ?? parked.questionId;
370
332
  this.#parkedCall = { toolCallId: parked.toolCallId, questionId };
371
333
  }
372
334
 
373
- #createControlFailure(): Promise<never> {
374
- const controls = [
375
- this.#limit?.failed,
376
- this.#idle?.failed,
377
- this.#idle?.killed,
378
- this.#stall?.failed,
379
- ].filter((promise): promise is Promise<never> => promise !== undefined);
380
- return Promise.race(controls.length === 0 ? [new Promise<never>(() => {})] : controls).catch(
381
- (error: unknown) => {
382
- if (error instanceof IdleKillSignal)
383
- throw askStalledError(this.#options.agent, error.outcome);
384
- if (error instanceof StallSignal) {
385
- this.#cause = "stalled";
386
- this.#drainStaleFrames = !error.outcome.destructive;
387
- throw askStalledError(this.#options.agent, error.outcome);
388
- }
389
- throw this.#failed(error instanceof Error ? error.message : "limit control command failed");
390
- },
391
- );
392
- }
393
-
394
335
  #armSettlement(): Promise<void> {
395
336
  this.#turn.rearm();
396
- this.#stall?.rearm();
337
+ this.#guard?.rearm();
397
338
  return new Promise<void>((resolve) => {
398
339
  this.#onSettled = resolve;
399
340
  });
@@ -460,14 +401,14 @@ class AskExchange {
460
401
  this.#timeoutDeadline === undefined
461
402
  ? undefined
462
403
  : Math.max(0, this.#timeoutDeadline - Date.now()),
463
- controlFailure: this.#controlFailure,
404
+ controlFailure: this.#guard?.failure ?? this.#noFailure,
464
405
  error: (code, message) => agentError(this.#options.agent, code, message),
465
406
  close: this.#options.close,
466
407
  parked: this.#parked,
467
408
  });
468
- this.#outcome = this.#playback?.limit ?? this.#limit?.abortOutcome ?? undefined;
409
+ this.#outcome = this.#playback?.limit ?? this.#guard?.limit ?? undefined;
469
410
  if (this.#outcome !== undefined) throw askLimitError(this.#options.agent, this.#outcome);
470
- this.#stalled = this.#playback?.stalled ?? this.#idle?.result ?? undefined;
411
+ this.#stalled = this.#playback?.stalled ?? this.#guard?.settlementStall() ?? undefined;
471
412
  if (this.#stalled !== undefined) throw askStalledError(this.#options.agent, this.#stalled);
472
413
  const failure = this.#turn.failure();
473
414
  if (failure !== null && !ignoreAbortFailure) throw this.#failed(failure);
@@ -508,8 +449,8 @@ class AskExchange {
508
449
  schema,
509
450
  maxSteers: this.#maxSteers(),
510
451
  reported: () => this.#call?.reported,
511
- beginCorrection: () => this.#limit?.enterOutputCorrection() ?? true,
512
- wrappingUp: () => this.#limit?.tripped ?? false,
452
+ beginCorrection: () => this.#guard?.beginCorrection() ?? true,
453
+ wrappingUp: () => this.#guard?.wrappingUp ?? false,
513
454
  correct: async (message) => this.#correct(message),
514
455
  abort: async () => this.#abort(),
515
456
  }).resolve();
@@ -525,8 +466,8 @@ class AskExchange {
525
466
  agent: this.#options.agent,
526
467
  schema,
527
468
  maxSteers: this.#maxSteers(),
528
- beginCorrection: () => this.#limit?.enterOutputCorrection() ?? true,
529
- wrappingUp: () => this.#limit?.tripped ?? false,
469
+ beginCorrection: () => this.#guard?.beginCorrection() ?? true,
470
+ wrappingUp: () => this.#guard?.wrappingUp ?? false,
530
471
  correct: async (message) => {
531
472
  await this.#correct(message);
532
473
  return await this.#lastAssistantText();
@@ -544,7 +485,7 @@ class AskExchange {
544
485
  if (!response.success) throw this.#failed(response.error ?? "correction prompt was rejected");
545
486
  await this.#verify(settled);
546
487
  } finally {
547
- this.#limit?.leaveOutputCorrection();
488
+ this.#guard?.leaveCorrection();
548
489
  }
549
490
  }
550
491
 
@@ -563,15 +504,14 @@ class AskExchange {
563
504
  /** Ends one attempt; the envelope stays open, so a retry can arm the next one. */
564
505
  #cleanupAttempt(): void {
565
506
  this.#maxFrameGapMs = maxGap(this.#maxFrameGapMs, this.#gap?.maxGapMs);
566
- this.#stalled ??= this.#idle?.result ?? this.#stall?.result ?? undefined;
567
- this.#limit?.cleanup();
568
- this.#idle?.cleanup();
569
- this.#stall?.cleanup();
507
+ this.#stalled ??= this.#guard?.stalled ?? undefined;
508
+ // The guard is the single writer of both while it exists; playback sets
509
+ // `#cause` itself and has no guard, so a guard-absent attempt copies nothing.
510
+ this.#cause = this.#guard?.cause ?? this.#cause;
511
+ this.#guard?.cleanup();
570
512
  this.#output?.close();
571
- if (this.#drainStaleFrames) {
572
- this.#options.connection.drainStaleTurn();
573
- this.#drainStaleFrames = false;
574
- }
513
+ // Only a live guard can leave a stale turn behind; a replayed Ask cannot.
514
+ if (this.#guard?.drainStaleFrames === true) this.#options.connection.drainStaleTurn();
575
515
  }
576
516
 
577
517
  /** Closes the Ask envelope: one `finishAsk` for the whole Ask, retries included. */
@@ -0,0 +1,207 @@
1
+ import { AskLimit } from "../ask-contract/index.ts";
2
+ import { agentError, askStalledError } from "../error-factories.ts";
3
+ import type { AskLimitOutcome, AskStalledOutcome } from "../errors.ts";
4
+ import type { CommandResponse, Frame } from "../transport/index.ts";
5
+ import type { EffectiveAskOptions } from "./ask-hash.ts";
6
+ import type { AskTiming } from "./ask-timing.ts";
7
+ import { IdleKillSignal, IdleWatch } from "./idle-watch.ts";
8
+ import {
9
+ type SettlementCause,
10
+ StallSignal,
11
+ StallWatchdog,
12
+ stallBudgetMs,
13
+ } from "./stall-watchdog.ts";
14
+
15
+ export interface AskGuardOptions {
16
+ /** The Agent this Ask runs on; names every error the guard reports. */
17
+ readonly agent: string;
18
+ readonly ask: EffectiveAskOptions;
19
+ /** Sends one control frame to the Agent and resolves with its response. */
20
+ readonly command: (frame: Frame) => Promise<CommandResponse>;
21
+ /** True when this Ask already observed a terminal assistant `message_end`. */
22
+ readonly terminal: () => boolean;
23
+ /** One sentence appended to the wrap-up, present when the Ask reports a result. */
24
+ readonly wrapUpSuffix?: string;
25
+ /** Test-only waits of the controls; absent in production. */
26
+ readonly timing?: AskTiming;
27
+ /** Called once when the Stall Watchdog recovered, so the Ask settles by hand. */
28
+ readonly onRecovered: () => void;
29
+ }
30
+
31
+ /**
32
+ * Every control of one Ask attempt, behind one object (ADR-0020, ADR-0038).
33
+ *
34
+ * The guard owns the Ask limit, the idle watch and the Stall Watchdog. It is a
35
+ * composition unit only: it adds no policy and ranks nothing. "First trip wins"
36
+ * stays a race between the controls' own failure promises, and the guard
37
+ * translates whichever signal wins into a `YaagError`. One guard serves one
38
+ * attempt and is never reused.
39
+ */
40
+ export class AskGuard {
41
+ readonly #agent: string;
42
+ readonly #limit: AskLimit;
43
+ readonly #idle: IdleWatch | null;
44
+ readonly #stall: StallWatchdog | null;
45
+ readonly #failure: Promise<never>;
46
+ #cause: SettlementCause = "normal";
47
+ #drain = false;
48
+
49
+ constructor(options: AskGuardOptions) {
50
+ this.#agent = options.agent;
51
+ const command = options.command;
52
+ this.#limit = new AskLimit({
53
+ ask: options.ask,
54
+ durationGraceMs: options.timing?.askLimitGraceMs,
55
+ command: async (frame) => (await command(frame)).success,
56
+ ...(options.wrapUpSuffix === undefined ? {} : { wrapUpSuffix: options.wrapUpSuffix }),
57
+ });
58
+ this.#idle =
59
+ options.ask.idleMs === undefined
60
+ ? null
61
+ : new IdleWatch({
62
+ idleMs: options.ask.idleMs,
63
+ ...(options.timing?.idleAbortSettleMs === undefined
64
+ ? {}
65
+ : { abortSettleMs: options.timing.idleAbortSettleMs }),
66
+ command: async (frame) => (await command(frame)).success,
67
+ });
68
+ const stallMs = stallBudgetMs(options.ask.stallMs);
69
+ this.#stall =
70
+ stallMs === null
71
+ ? null
72
+ : new StallWatchdog({
73
+ stallMs,
74
+ ...(options.timing?.stallProbeSettleMs === undefined
75
+ ? {}
76
+ : { probeSettleMs: options.timing.stallProbeSettleMs }),
77
+ command,
78
+ terminal: options.terminal,
79
+ recover: () => {
80
+ this.#cause = "recovered";
81
+ // The missing `agent_settled` may still arrive: it belongs to the
82
+ // turn yaag just settled by hand, never to the next Ask.
83
+ this.#drain = true;
84
+ options.onRecovered();
85
+ },
86
+ });
87
+ this.#failure = this.#raceFailures();
88
+ // A control may trip before the Ask starts awaiting the race.
89
+ void this.#failure.catch(() => {});
90
+ }
91
+
92
+ /** Arms every control it holds. */
93
+ start(): void {
94
+ this.#limit.start();
95
+ this.#idle?.start();
96
+ this.#stall?.start();
97
+ }
98
+
99
+ /** Feeds one frame to every control. */
100
+ observe(frame: Frame): void {
101
+ this.#limit.observe(frame);
102
+ // The idle watch only cares about `agent_settled` once it escalated: before
103
+ // that the frame is the settlement the Ask itself is waiting for.
104
+ if (frame.type !== "agent_settled" || this.#idle?.tripped === true) this.#idle?.observe(frame);
105
+ this.#stall?.observe(frame);
106
+ }
107
+
108
+ /** The turn settled normally. */
109
+ settled(): void {
110
+ this.#stall?.settled();
111
+ }
112
+
113
+ /**
114
+ * Parks every control before an Agent Question is raised (ADR-0023), so no
115
+ * control can trip between the park and the Question. Returns false when a
116
+ * limit already tripped: first signal wins and the Ask raises nothing.
117
+ */
118
+ suspend(): boolean {
119
+ if (this.#limit.tripped) return false;
120
+ this.#limit.suspend();
121
+ this.#idle?.suspend();
122
+ this.#stall?.suspend();
123
+ return true;
124
+ }
125
+
126
+ /** Opens a new settlement window after a correction steer. */
127
+ rearm(): void {
128
+ this.#stall?.rearm();
129
+ }
130
+
131
+ /** Stops every timer. Idempotent. */
132
+ cleanup(): void {
133
+ this.#limit.cleanup();
134
+ this.#idle?.cleanup();
135
+ this.#stall?.cleanup();
136
+ }
137
+
138
+ /** Rejects with a `YaagError` when the first control trips destructively. */
139
+ get failure(): Promise<never> {
140
+ return this.#failure;
141
+ }
142
+
143
+ /** How this Ask settled, as reported in its `ask_end` Lifecycle Event. */
144
+ get cause(): SettlementCause {
145
+ return this.#cause;
146
+ }
147
+
148
+ /** True when the connection must drain a stale turn at cleanup. */
149
+ get drainStaleFrames(): boolean {
150
+ return this.#drain;
151
+ }
152
+
153
+ /** The limit outcome, once a limit aborted this Ask. */
154
+ get limit(): AskLimitOutcome | null {
155
+ return this.#limit.abortOutcome;
156
+ }
157
+
158
+ /** The recording view of a stall: whichever control ended the Ask. */
159
+ get stalled(): AskStalledOutcome | null {
160
+ return this.#idle?.result ?? this.#stall?.result ?? null;
161
+ }
162
+
163
+ /**
164
+ * The post-settlement check, which is the idle watch alone. A stall reaches
165
+ * the Ask through {@link failure}; reading it here too would let a stall that
166
+ * resolves together with settlement be thrown from the settled path.
167
+ */
168
+ settlementStall(): AskStalledOutcome | null {
169
+ return this.#idle?.result ?? null;
170
+ }
171
+
172
+ /** Opens one output-correction pass under the limit's budget. */
173
+ beginCorrection(): boolean {
174
+ return this.#limit.enterOutputCorrection();
175
+ }
176
+
177
+ leaveCorrection(): void {
178
+ this.#limit.leaveOutputCorrection();
179
+ }
180
+
181
+ /** True once a limit tripped and the Ask is wrapping up. */
182
+ get wrappingUp(): boolean {
183
+ return this.#limit.tripped;
184
+ }
185
+
186
+ #raceFailures(): Promise<never> {
187
+ const controls = [
188
+ this.#limit.failed,
189
+ this.#idle?.failed,
190
+ this.#idle?.killed,
191
+ this.#stall?.failed,
192
+ ].filter((promise): promise is Promise<never> => promise !== undefined);
193
+ return Promise.race(controls).catch((error: unknown) => {
194
+ if (error instanceof IdleKillSignal) throw askStalledError(this.#agent, error.outcome);
195
+ if (error instanceof StallSignal) {
196
+ this.#cause = "stalled";
197
+ this.#drain = !error.outcome.destructive;
198
+ throw askStalledError(this.#agent, error.outcome);
199
+ }
200
+ throw agentError(
201
+ this.#agent,
202
+ "AGENT_FAILED",
203
+ error instanceof Error ? error.message : "limit control command failed",
204
+ );
205
+ });
206
+ }
207
+ }
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Test-only waits of the Ask Guard's controls; production passes none and every
3
+ * control applies its own fixed constant.
4
+ */
5
+ export interface AskTiming {
6
+ /** Test-only override for the fixed duration-limit grace. */
7
+ readonly askLimitGraceMs?: number;
8
+ /** Test-only override for the bounded settle wait after an idle abort. */
9
+ readonly idleAbortSettleMs?: number;
10
+ /** Test-only override for the bounded wait for the Stall Watchdog probe. */
11
+ readonly stallProbeSettleMs?: number;
12
+ }
package/src/ask/index.ts CHANGED
@@ -8,5 +8,6 @@ export { exchangeAsk } from "./ask-exchange.ts";
8
8
  export type { AskModelFallback } from "./ask-exchange-options.ts";
9
9
  export { askHash, askMarkerContext, type EffectiveAskOptions } from "./ask-hash.ts";
10
10
  export { AskOutputTail } from "./ask-output-tail.ts";
11
+ export type { AskTiming } from "./ask-timing.ts";
11
12
  export { AskTurn } from "./ask-turn.ts";
12
13
  export type { SettlementCause } from "./stall-watchdog.ts";
@@ -8,6 +8,7 @@ import {
8
8
  type CassetteAsk,
9
9
  } from "./cassette.ts";
10
10
  import { CassetteSchema } from "./cassette-schema.ts";
11
+ import { readableCassette } from "./checkpoint.ts";
11
12
 
12
13
  /**
13
14
  * Reads and validates one Cassette artifact before replay begins.
@@ -135,7 +136,9 @@ function assertRunPresence(artifact: CassetteArtifact, path: string): void {
135
136
  * Deliberately not checked: that every `ask.incomplete.questionId` names a
136
137
  * Question of this run block. A `stopped` artifact can hold a parked Ask whose
137
138
  * Question the drain never collected, and the loader must not refuse an
138
- * artifact yaag itself writes.
139
+ * artifact yaag itself writes. The loader stays permissive on purpose: the rule
140
+ * belongs to resume, which refuses such a marker at ledger construction, in
141
+ * `run/answers.ts`, before the first Agent starts (ADR-0022/ADR-0023).
139
142
  */
140
143
  function assertUniqueQuestionIds(artifact: CassetteArtifact, path: string): void {
141
144
  const seen = new Set<string>();
@@ -173,15 +176,13 @@ function upgrade(artifact: CassetteArtifact): Cassette {
173
176
  }
174
177
 
175
178
  /**
176
- * Strict replay demands a settled Run. An `interrupted` artifact stops at the
177
- * last Ask boundary, so its final Ask has no recorded settlement (ADR-0031).
179
+ * Strict replay demands a settled Run. The `interrupted` refusal is the
180
+ * Checkpoint's own read-side rule (ADR-0031); the parked-Ask refusal below is a
181
+ * replay rule and stays here.
178
182
  */
179
183
  export function assertReplayable(cassette: Cassette, path: string): void {
180
- if (cassette.run.outcome === "interrupted") {
181
- throw new Error(
182
- `cannot replay interrupted cassette "${path}": the Run died before it settled; use resume instead`,
183
- );
184
- }
184
+ const readable = readableCassette(cassette, path, "replay");
185
+ if (!readable.ok) throw new Error(readable.reason);
185
186
  for (const agent of cassette.agents) {
186
187
  for (const [index, ask] of agent.asks.entries()) {
187
188
  if (ask.incomplete === undefined) continue;
@@ -192,18 +193,6 @@ export function assertReplayable(cassette: Cassette, path: string): void {
192
193
  }
193
194
  }
194
195
 
195
- /**
196
- * Warns once when a resume source came from a hard death. The Run continues:
197
- * resume already handles an incomplete last Ask.
198
- */
199
- export function interruptedResumeWarning(cassette: Cassette, path: string): string | null {
200
- if (cassette.run.outcome !== "interrupted") return null;
201
- return (
202
- `resuming interrupted cassette "${path}": the Run died before it settled, ` +
203
- "the recording stops at the last Ask boundary, and re-run tools can repeat their effects"
204
- );
205
- }
206
-
207
196
  function message(error: unknown): string {
208
197
  return error instanceof Error ? error.message : "is invalid";
209
198
  }
@@ -21,6 +21,11 @@ const ThinkingSchema = Type.Union(
21
21
 
22
22
  const StringArray = Type.Array(Type.String());
23
23
 
24
+ /**
25
+ * The policy half of a recorded spawn. It mirrors the rows the spawn field
26
+ * table marks `askContext` (`spawn-identity.ts`), minus `cwd` and `worktree`,
27
+ * which the two schemas below place themselves.
28
+ */
24
29
  const spawnPolicyFields = {
25
30
  model: Type.Optional(Type.String()),
26
31
  systemPrompt: Type.Optional(Type.String()),
@@ -41,9 +46,13 @@ const CassetteSpawnSchema = Type.Object({
41
46
  canAskUser: Type.Optional(Type.Literal(true)),
42
47
  askUserProtocol: Type.Optional(Type.Integer()),
43
48
  parent: Type.Optional(Type.String()),
44
- origin: Type.Optional(Type.Literal("fork")),
49
+ origin: Type.Optional(
50
+ Type.Union([Type.Literal("spawn"), Type.Literal("fork"), Type.Literal("host-fork")]),
51
+ ),
52
+ hostHash: Type.Optional(Type.String()),
45
53
  forkOf: Type.Optional(Type.String()),
46
54
  forkAsks: Type.Optional(Type.Number()),
55
+ group: Type.Optional(Type.String()),
47
56
  });
48
57
 
49
58
  const ContextSpawnSchema = Type.Object({
@@ -189,6 +198,7 @@ const CassetteRunSchema = Type.Object({
189
198
  args: Type.Optional(Type.Unknown()),
190
199
  programHash: Type.Optional(Type.String()),
191
200
  profile: Type.Optional(Type.String()),
201
+ host: Type.Optional(Type.Object({ hostHash: Type.String() })),
192
202
  questions: Type.Optional(Type.Array(CassetteQuestionSchema)),
193
203
  answers: Type.Optional(Type.Array(CassetteAnswerSchema)),
194
204
  reason: Type.Optional(Type.String()),