@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.
- package/package.json +1 -1
- package/src/agent/agent-name.ts +22 -0
- package/src/agent/agent-names.ts +5 -1
- package/src/agent/agent.ts +34 -17
- package/src/agent/define-agent.ts +4 -0
- package/src/agent/fork.ts +50 -12
- package/src/agent/host-fork.ts +85 -0
- package/src/agent/index.ts +1 -0
- package/src/agent/spawn-definition-request.ts +41 -6
- package/src/agent/spawn-open.ts +54 -107
- package/src/agent/spawn-parent.ts +64 -0
- package/src/agent/spawn-plan.ts +120 -0
- package/src/agent/spawn-request.ts +26 -6
- package/src/agent/spawn.ts +47 -6
- package/src/ask/ask-exchange-options.ts +3 -6
- package/src/ask/ask-exchange.ts +48 -108
- package/src/ask/ask-guard.ts +207 -0
- package/src/ask/ask-timing.ts +12 -0
- package/src/ask/index.ts +1 -0
- package/src/cassette/cassette-loader.ts +9 -20
- package/src/cassette/cassette-schema.ts +11 -1
- package/src/cassette/cassette.ts +16 -34
- package/src/cassette/checkpoint.ts +306 -0
- package/src/cassette/index.ts +16 -7
- package/src/cassette/parked-asks.ts +38 -0
- package/src/cassette/replay-divergence.ts +7 -102
- package/src/cassette/resume-identity.ts +5 -1
- package/src/cassette/resume-preconditions.ts +14 -0
- package/src/cassette/resume-transport.ts +26 -32
- package/src/cassette/run-identity.ts +109 -0
- package/src/cassette/session-answer.ts +51 -114
- package/src/cassette/spawn-identity.ts +328 -0
- package/src/contract/error-codes.ts +4 -0
- package/src/contract/group.ts +38 -0
- package/src/contract/index.ts +2 -0
- package/src/contract/spawn-options.ts +48 -7
- package/src/error-factories.ts +8 -0
- package/src/events.ts +22 -2
- package/src/index.ts +7 -0
- package/src/pi-session/append-tool-result.ts +165 -0
- package/src/pi-session/index.ts +30 -0
- package/src/pi-session/pi-session-error.ts +34 -0
- package/src/pi-session/session-copy.ts +113 -0
- package/src/pi-session/session-entries.ts +130 -0
- package/src/public-api.ts +2 -0
- package/src/question-summary/index.ts +4 -8
- package/src/question-summary/summarize-question.ts +1 -1
- package/src/question-summary/summary-policy.ts +5 -2
- package/src/run/agent-questions.ts +82 -0
- package/src/run/answers.ts +22 -1
- package/src/run/groups.ts +111 -0
- package/src/run/host-session.ts +233 -0
- package/src/run/index.ts +8 -0
- package/src/run/run-context.ts +15 -0
- package/src/run/run.ts +208 -182
- package/src/summary/index.ts +1 -0
- package/src/summary/summary-agent.ts +6 -0
- package/src/summary/summary-group.ts +31 -0
- package/src/summary/summary.ts +12 -0
- package/src/transport/live-transport.ts +19 -0
- package/src/transport/pi-state.ts +10 -1
- package/src/transport/transport.ts +20 -9
- package/src/types.ts +3 -0
- package/src/cassette/checkpoint-flush.ts +0 -101
- package/src/cassette/run-checkpoint.ts +0 -272
- package/src/question-summary/session-copy.ts +0 -169
package/src/ask/ask-exchange.ts
CHANGED
|
@@ -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 {
|
|
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
|
-
#
|
|
45
|
-
|
|
46
|
-
|
|
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
|
-
|
|
225
|
-
|
|
226
|
-
this.#
|
|
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.#
|
|
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
|
-
#
|
|
236
|
-
return new
|
|
228
|
+
#createGuard(): AskGuard {
|
|
229
|
+
return new AskGuard({
|
|
230
|
+
agent: this.#options.agent,
|
|
237
231
|
ask: this.#options.ask,
|
|
238
|
-
|
|
239
|
-
|
|
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.#
|
|
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.#
|
|
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.#
|
|
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
|
-
*
|
|
354
|
-
*
|
|
355
|
-
*
|
|
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?.
|
|
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.#
|
|
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.#
|
|
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
|
|
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.#
|
|
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.#
|
|
512
|
-
wrappingUp: () => this.#
|
|
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.#
|
|
529
|
-
wrappingUp: () => this.#
|
|
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.#
|
|
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.#
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
this.#
|
|
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
|
-
|
|
572
|
-
|
|
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.
|
|
177
|
-
*
|
|
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
|
-
|
|
181
|
-
|
|
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(
|
|
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()),
|