@yaag/runtime 0.25.0 → 0.27.0

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 (79) hide show
  1. package/package.json +2 -3
  2. package/src/agent/agent.ts +75 -23
  3. package/src/agent/ask-user-capability.ts +36 -0
  4. package/src/agent/fork.ts +40 -12
  5. package/src/agent/host-fork.ts +85 -0
  6. package/src/agent/index.ts +2 -1
  7. package/src/agent/spawn-definition-request.ts +38 -3
  8. package/src/agent/spawn-open.ts +59 -100
  9. package/src/agent/spawn-plan.ts +114 -0
  10. package/src/agent/spawn-request.ts +34 -3
  11. package/src/agent/spawn.ts +41 -5
  12. package/src/ask/ask-exchange-options.ts +8 -6
  13. package/src/ask/ask-exchange.ts +102 -97
  14. package/src/ask/ask-guard.ts +207 -0
  15. package/src/ask/ask-settlement.ts +8 -0
  16. package/src/ask/ask-timing.ts +12 -0
  17. package/src/ask/idle-watch.ts +12 -2
  18. package/src/ask/index.ts +1 -0
  19. package/src/ask/stall-watchdog.ts +13 -3
  20. package/src/ask-contract/ask-limit.ts +24 -6
  21. package/src/ask-contract/index.ts +8 -0
  22. package/src/ask-contract/request-user-input-extension.ts +105 -0
  23. package/src/ask-contract/request-user-input.ts +58 -0
  24. package/src/cassette/cassette-loader.ts +56 -18
  25. package/src/cassette/cassette-schema.ts +37 -1
  26. package/src/cassette/cassette.ts +58 -32
  27. package/src/cassette/checkpoint.ts +306 -0
  28. package/src/cassette/index.ts +25 -7
  29. package/src/cassette/parked-asks.ts +38 -0
  30. package/src/cassette/replay-divergence.ts +7 -97
  31. package/src/cassette/resume-identity.ts +5 -1
  32. package/src/cassette/resume-preconditions.ts +24 -0
  33. package/src/cassette/resume-transport.ts +112 -13
  34. package/src/cassette/run-identity.ts +109 -0
  35. package/src/cassette/session-answer.ts +100 -0
  36. package/src/cassette/spawn-identity.ts +318 -0
  37. package/src/catalog/registry-reader.ts +1 -1
  38. package/src/config/config-schema.ts +33 -0
  39. package/src/config/effective-config.ts +53 -0
  40. package/src/config/index.ts +4 -0
  41. package/src/contract/agent-policy.ts +9 -0
  42. package/src/contract/error-codes.ts +3 -2
  43. package/src/contract/index.ts +1 -0
  44. package/src/contract/spawn-options.ts +33 -2
  45. package/src/control/index.ts +2 -0
  46. package/src/control/pause-drain.ts +81 -24
  47. package/src/error-factories.ts +8 -0
  48. package/src/events.ts +10 -2
  49. package/src/index.ts +15 -1
  50. package/src/model/index.ts +1 -1
  51. package/src/pi-session/append-tool-result.ts +165 -0
  52. package/src/pi-session/index.ts +30 -0
  53. package/src/pi-session/pi-session-error.ts +34 -0
  54. package/src/pi-session/session-copy.ts +113 -0
  55. package/src/pi-session/session-entries.ts +130 -0
  56. package/src/public-api.ts +1 -0
  57. package/src/question-summary/index.ts +18 -0
  58. package/src/question-summary/summarize-question.ts +129 -0
  59. package/src/question-summary/summary-policy.ts +28 -0
  60. package/src/run/agent-questions.ts +157 -0
  61. package/src/run/answers.ts +91 -0
  62. package/src/run/host-session.ts +233 -0
  63. package/src/run/index.ts +12 -0
  64. package/src/run/pause-questions.ts +98 -0
  65. package/src/run/pause-signal.ts +32 -0
  66. package/src/run/question-id.ts +18 -0
  67. package/src/run/questions.ts +31 -0
  68. package/src/run/run-context.ts +21 -0
  69. package/src/run/run-result.ts +21 -0
  70. package/src/run/run-settlement.ts +36 -4
  71. package/src/run/run.ts +248 -139
  72. package/src/system-prompt/agent-system-prompt.ts +1 -1
  73. package/src/transport/live-transport.ts +19 -0
  74. package/src/transport/pi-state.ts +31 -5
  75. package/src/transport/tool-probe.ts +4 -0
  76. package/src/transport/transport.ts +31 -1
  77. package/src/types.ts +1 -0
  78. package/src/cassette/checkpoint-flush.ts +0 -101
  79. package/src/cassette/run-checkpoint.ts +0 -223
@@ -1,3 +1,5 @@
1
+ import { isReportResultCommandFrame, RESUME_NUDGE } from "../ask-contract/index.ts";
2
+ import { YaagError } from "../errors.ts";
1
3
  import type {
2
4
  AgentStats,
3
5
  AgentTransport,
@@ -14,14 +16,21 @@ import type {
14
16
  TransportStartupObserver,
15
17
  } from "../transport/index.ts";
16
18
  import { FrameQueue } from "../transport/index.ts";
17
- import type { Cassette, CassetteAgent } from "./cassette.ts";
19
+ import type { Cassette, CassetteAgent, CassetteAsk } from "./cassette.ts";
18
20
  import { CassetteReplay } from "./cassette-replay.ts";
19
- import {
20
- recordedSpawnSelection,
21
- replayMismatch,
22
- spawnMatchesExceptModel,
23
- } from "./replay-divergence.ts";
21
+ import { recordedSpawnSelection, replayMismatch } from "./replay-divergence.ts";
24
22
  import { checkResumePreconditions } from "./resume-preconditions.ts";
23
+ import { matchesExceptModel } from "./spawn-identity.ts";
24
+
25
+ /**
26
+ * What a resume knows about the human's answers (ADR-0023). A recorded Ask
27
+ * that parked on `request_user_input` reads its answer here: with one, the Ask
28
+ * is restored; without one, it parks again and the Run pauses.
29
+ */
30
+ export interface AskUserRestoration {
31
+ /** The answer of a recorded parked Ask, or undefined when it stays open. */
32
+ answerFor(questionId: string): string | undefined;
33
+ }
25
34
 
26
35
  /**
27
36
  * Creates a Cassette-prefix transport that continues with live pi at divergence.
@@ -29,7 +38,11 @@ import { checkResumePreconditions } from "./resume-preconditions.ts";
29
38
  * Matched Agents validate their recorded continuation point before replaying.
30
39
  * Spawn mismatches intentionally bypass those checks and start a fresh Agent.
31
40
  */
32
- export function resumeTransport(cassette: Cassette, live: TransportFactory): TransportFactory {
41
+ export function resumeTransport(
42
+ cassette: Cassette,
43
+ live: TransportFactory,
44
+ restoration?: AskUserRestoration,
45
+ ): TransportFactory {
33
46
  let spawnCursor = 0;
34
47
  return {
35
48
  async open(
@@ -38,21 +51,38 @@ export function resumeTransport(cassette: Cassette, live: TransportFactory): Tra
38
51
  ): Promise<AgentTransport> {
39
52
  const agent = cassette.agents[spawnCursor++] ?? null;
40
53
  const mismatch = replayMismatch.spawn(agent, options);
41
- if (mismatch) return live.open(options, observeStartup);
54
+ if (mismatch) {
55
+ // A diverged Host Fork with no copy path cannot go live: the argv
56
+ // builder emits `--fork` only when a `forkSession` exists
57
+ // (`transport/pi-state.ts`), so pi would silently start a fresh
58
+ // conversation instead of forking the human's one. ADR-0068 decision 2
59
+ // states the rule: the spawn side refuses rather than forks. The
60
+ // copy-less source is the Cassette-rebuilt one, and also the
61
+ // `--resume --host-session` one, which has no tool call id and so
62
+ // makes no copy.
63
+ if (options.origin === "host-fork" && options.forkSession === undefined) {
64
+ throw new YaagError(
65
+ "RESUME_REFUSED",
66
+ `resume refused for agent "${options.name}": the recorded host fork diverged and this Run holds no host session copy to fork from`,
67
+ options.name,
68
+ );
69
+ }
70
+ return live.open(options, observeStartup);
71
+ }
42
72
  await checkResumePreconditions(agent);
43
73
  const worktree = worktreeResolution(agent);
44
74
  observeStartup?.({
45
75
  ...(agent.sessionFile === undefined ? {} : { sessionFile: agent.sessionFile }),
46
76
  ...(worktree === undefined ? {} : { worktree }),
47
77
  });
48
- return new ResumeTransport(agent, live, options);
78
+ return new ResumeTransport(agent, live, options, restoration);
49
79
  },
50
80
 
51
81
  // A changed spawn must not silently inherit the recorded model, so the
52
82
  // recorded selection is offered only when every other field matches.
53
83
  recordedSpawn(options: OpenOptions): RecordedSpawnSelection | undefined {
54
84
  const agent = cassette.agents[spawnCursor] ?? null;
55
- if (agent === null || !spawnMatchesExceptModel(agent.spawn, options)) return undefined;
85
+ if (agent === null || !matchesExceptModel(agent.spawn, options)) return undefined;
56
86
  return recordedSpawnSelection(agent);
57
87
  },
58
88
  };
@@ -64,6 +94,9 @@ class ResumeTransport implements AgentTransport {
64
94
  readonly #liveFactory: TransportFactory;
65
95
  readonly #continuation: OpenOptions;
66
96
  readonly #replay: CassetteReplay;
97
+ readonly #restoration: AskUserRestoration | undefined;
98
+ /** The Ask prompt the nudge replaces, while a restored Ask still awaits it. */
99
+ #nudgePrompt: string | null = null;
67
100
  readonly #frames = new FrameQueue();
68
101
  readonly #buffered: Frame[] = [];
69
102
  #askCursor = 0;
@@ -74,8 +107,14 @@ class ResumeTransport implements AgentTransport {
74
107
  #activationFailed = false;
75
108
  #closed: Promise<AgentStats> | null = null;
76
109
 
77
- constructor(agent: CassetteAgent, liveFactory: TransportFactory, options: OpenOptions) {
110
+ constructor(
111
+ agent: CassetteAgent,
112
+ liveFactory: TransportFactory,
113
+ options: OpenOptions,
114
+ restoration?: AskUserRestoration,
115
+ ) {
78
116
  this.#agent = agent;
117
+ this.#restoration = restoration;
79
118
  this.#liveFactory = liveFactory;
80
119
  this.#continuation = continuationOptions(agent, options);
81
120
  this.#replay = new CassetteReplay(agent);
@@ -92,7 +131,7 @@ class ResumeTransport implements AgentTransport {
92
131
  this.#buffered.push(frame);
93
132
  return;
94
133
  }
95
- this.#live?.send(frame);
134
+ this.#live?.send(this.#nudged(frame));
96
135
  }
97
136
 
98
137
  frames(): AsyncIterable<Frame> {
@@ -104,6 +143,10 @@ class ResumeTransport implements AgentTransport {
104
143
  if (this.#mode === "activating") return undefined;
105
144
  const mismatch = replayMismatch.ask(this.#agent, this.#askCursor, marker);
106
145
  if (!mismatch) {
146
+ // The restoration comes after the match: a parked Ask whose marker moved
147
+ // is a diverged Ask, and it must never inherit another Ask's question.
148
+ const restored = this.#restore(this.#agent.asks[this.#askCursor]);
149
+ if (restored !== null) return restored;
107
150
  this.#askCursor += 1;
108
151
  return this.#replay.beginAsk(marker);
109
152
  }
@@ -146,6 +189,48 @@ class ResumeTransport implements AgentTransport {
146
189
  return this.#closed;
147
190
  }
148
191
 
192
+ /**
193
+ * Handles a recorded Ask that parked on `request_user_input` (ADR-0023).
194
+ *
195
+ * The recorded Ask has no settlement, so it can never replay. With an answer
196
+ * it is restored: the answer goes into the session, pi respawns on it, and
197
+ * the nudge replaces the Ask prompt the Agent already saw. Without an answer
198
+ * the playback names the parked call and its Question id, the Ask parks on
199
+ * the Question the run block holds, and the Run pauses again (ADR-0022).
200
+ */
201
+ #restore(ask: CassetteAsk | undefined): AskPlayback | undefined | null {
202
+ const incomplete = ask?.incomplete;
203
+ if (ask === undefined || incomplete === undefined) return null;
204
+ const answer = this.#restoration?.answerFor(incomplete.questionId);
205
+ if (answer === undefined) {
206
+ this.#askCursor += 1;
207
+ return {
208
+ settles: false,
209
+ parked: { toolCallId: incomplete.toolCallId, questionId: incomplete.questionId },
210
+ };
211
+ }
212
+ // The answer is already in the session: `restoreSessionAnswers` wrote it
213
+ // before the Run started. This side only respawns and nudges (ADR-0023).
214
+ // The latch names the recorded Ask prompt, so the substitution hits that
215
+ // one frame and never the `report_result` schema command beside it.
216
+ this.#nudgePrompt = recordedPrompt(ask);
217
+ this.#mode = "activating";
218
+ this.#activation = this.#activate(null);
219
+ return undefined;
220
+ }
221
+
222
+ /**
223
+ * Substitutes the nudge for the Ask prompt of a restored Ask, one time. Every
224
+ * other frame, the `report_result` schema command included, passes through
225
+ * unchanged, and the frame id stays, so the Ask's command still settles.
226
+ */
227
+ #nudged(frame: Frame): Frame {
228
+ if (this.#nudgePrompt === null) return frame;
229
+ if (frame.type !== "prompt" || frame.message !== this.#nudgePrompt) return frame;
230
+ this.#nudgePrompt = null;
231
+ return { ...frame, message: RESUME_NUDGE };
232
+ }
233
+
149
234
  async #activate(marker: AskMarker | null): Promise<void> {
150
235
  // End the old source before attaching the new one, but keep the outward
151
236
  // queue open so Connection remains attached across the handoff.
@@ -157,7 +242,7 @@ class ResumeTransport implements AgentTransport {
157
242
  const live = await this.#liveFactory.open(this.#continuation);
158
243
  this.#live = live;
159
244
  if (marker !== null) live.beginAsk(marker);
160
- for (const frame of this.#buffered.splice(0)) live.send(frame);
245
+ for (const frame of this.#buffered.splice(0)) live.send(this.#nudged(frame));
161
246
  this.#mode = "live";
162
247
  void this.#forward(live.frames());
163
248
  } catch {
@@ -198,6 +283,20 @@ class ResumeTransport implements AgentTransport {
198
283
  }
199
284
  }
200
285
 
286
+ /**
287
+ * The Ask prompt of a recorded Ask, read back from its sent frames. The private
288
+ * `report_result` schema command is a prompt frame too, and it is not the Ask
289
+ * prompt, so it is skipped (ADR-0032).
290
+ */
291
+ function recordedPrompt(ask: CassetteAsk): string | null {
292
+ for (const frame of ask.sentFrames) {
293
+ if (frame.type !== "prompt" || typeof frame.message !== "string") continue;
294
+ if (isReportResultCommandFrame(frame)) continue;
295
+ return frame.message;
296
+ }
297
+ return null;
298
+ }
299
+
201
300
  function continuationOptions(agent: CassetteAgent, original: OpenOptions): OpenOptions {
202
301
  const { worktree: _worktree, ...spawn } = agent.spawn;
203
302
  const worktree = worktreeResolution(agent);
@@ -0,0 +1,109 @@
1
+ import { mkdir } from "node:fs/promises";
2
+ import { dirname } from "node:path";
3
+ import { YaagError } from "../errors.ts";
4
+ import type { CassetteRun } from "./cassette.ts";
5
+ import { sha256Hex } from "./program-hash.ts";
6
+
7
+ /**
8
+ * What a resume is about to re-execute; resolved once, at Run start.
9
+ *
10
+ * The run-level `host` is part of this identity, but it is not resolved here:
11
+ * the Host Source is prepared after the identity (see the order in `run.ts`),
12
+ * so the Checkpoint receives it separately through `identifyHost` (ADR-0068).
13
+ */
14
+ export type RunIdentity = Omit<CassetteRun, "outcome" | "questions" | "answers" | "reason">;
15
+
16
+ /**
17
+ * Creates the directory the Run's artifact goes into. A `--record` path names
18
+ * where the artifact goes, so yaag creates the chain that path implies rather
19
+ * than refusing. ADR-0021 makes `--record` fix the destination path only, and a
20
+ * path yaag can make is a destination yaag makes. The checkpoint directory yaag owns stays
21
+ * private; a user-named `--record` directory takes the process umask, because it
22
+ * lives in the user's own tree.
23
+ */
24
+ export async function ensureCheckpointDirectory(
25
+ record: string | undefined,
26
+ destination: string,
27
+ ): Promise<void> {
28
+ const directory = dirname(destination);
29
+ if (record === undefined) {
30
+ await mkdir(directory, { recursive: true, mode: 0o700 });
31
+ return;
32
+ }
33
+ await mkdir(directory, { recursive: true });
34
+ }
35
+
36
+ /**
37
+ * Makes the directory chain of the `--record` path at Run start, and rejects the
38
+ * Run before the first spawn when that chain cannot exist. It does not prove the
39
+ * destination writable: an existing directory that refuses a write, or a name
40
+ * already taken, still fails later, at publication.
41
+ */
42
+ export async function prepareRecordDestination(record: string): Promise<void> {
43
+ try {
44
+ await ensureCheckpointDirectory(record, record);
45
+ } catch (error) {
46
+ throw new YaagError(
47
+ "RECORD_PATH_UNUSABLE",
48
+ `cannot create the Cassette directory ${dirname(record)}: ${String(error)}`,
49
+ );
50
+ }
51
+ }
52
+
53
+ /** Which program a Run executes: a file on disk, or inline source text (ADR-0033). */
54
+ export interface ProgramIdentity {
55
+ readonly programFile?: string;
56
+ /** Inline source, exactly as the caller gave it; it excludes any loader prelude. */
57
+ readonly programSource?: string;
58
+ }
59
+
60
+ /** What one Run's invocation identity is made of: program, args, and Profile. */
61
+ export interface RunIdentityRequest {
62
+ readonly program: ProgramIdentity;
63
+ readonly args: unknown;
64
+ /** Active Profile id; part of invocation identity, resolved before this call (ADR-0052). */
65
+ readonly profile?: string;
66
+ }
67
+
68
+ /**
69
+ * Resolves what a resume re-executes: the program, its args, and the active
70
+ * Profile. The program hash is advisory only.
71
+ */
72
+ export async function resolveRunIdentity(request: RunIdentityRequest): Promise<RunIdentity> {
73
+ const { program, args, profile } = request;
74
+ const profileKey = profile === undefined ? {} : { profile };
75
+ // An Inline Program's file is a temporary path, and no artifact may name it,
76
+ // so the inline arm drops `programFile` even when the caller supplies one.
77
+ if (program.programSource !== undefined) {
78
+ const programSource = program.programSource;
79
+ return { programSource, args, programHash: sha256Hex(programSource), ...profileKey };
80
+ }
81
+ const programFile = program.programFile;
82
+ // A Run with neither a program file nor inline source still has a Profile.
83
+ if (programFile === undefined) return { ...profileKey };
84
+ const programHash = await hashProgram(programFile);
85
+ return {
86
+ programFile,
87
+ args,
88
+ ...(programHash === null ? {} : { programHash }),
89
+ ...profileKey,
90
+ };
91
+ }
92
+
93
+ /** Advisory only: an unreadable program file omits the hash and never fails the Run. */
94
+ async function hashProgram(programFile: string): Promise<string | null> {
95
+ try {
96
+ return sha256Hex(await Bun.file(programFile).arrayBuffer());
97
+ } catch {
98
+ return null;
99
+ }
100
+ }
101
+
102
+ /** Reports a secondary Cassette publication failure without displacing the Run's primary error. */
103
+ export function writeRecordingDiagnostic(error: unknown): void {
104
+ try {
105
+ process.stderr.write(`[yaag] ${String(error)}\n`);
106
+ } catch {
107
+ // stderr diagnostics are best-effort: a broken stderr must not mask the Run's error either.
108
+ }
109
+ }
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Restoration of one human answer into a pi session file (ADR-0023).
3
+ *
4
+ * The Agent parked on a `request_user_input` tool call and the process died.
5
+ * The answer goes back into the session as the tool result of that call, so the
6
+ * respawned Agent reads it as the result of its own request.
7
+ *
8
+ * The write itself belongs to the pi session editor. This module owns the loop
9
+ * over the Cassette's incomplete marks, and the map from the editor's refusals
10
+ * to `RESUME_REFUSED`.
11
+ */
12
+ import { YaagError } from "../errors.ts";
13
+ import { appendToolResult, isPiSessionError } from "../pi-session/index.ts";
14
+ import type { Cassette } from "./cassette.ts";
15
+ import { parkedAsks } from "./parked-asks.ts";
16
+
17
+ /** One correlated answer, and the session file it belongs to. */
18
+ export interface SessionAnswerAppend {
19
+ readonly sessionFile: string;
20
+ /** The tool call id of the parked `request_user_input` call. */
21
+ readonly toolCallId: string;
22
+ readonly answer: string;
23
+ }
24
+
25
+ /**
26
+ * Appends the answer as the tool result of the parked call.
27
+ *
28
+ * The same answer already in the file is a skip, so retrying a resume changes
29
+ * nothing. A different answer for the same call is a refusal: an answered
30
+ * question has one answer (ADR-0022). An absent tool call is a refusal too —
31
+ * the session is not the one the Cassette recorded.
32
+ */
33
+ export async function appendSessionAnswer(request: SessionAnswerAppend): Promise<void> {
34
+ try {
35
+ await appendToolResult({
36
+ sessionFile: request.sessionFile,
37
+ toolCallId: request.toolCallId,
38
+ text: request.answer,
39
+ });
40
+ } catch (error) {
41
+ throw refusal(error, request);
42
+ }
43
+ }
44
+
45
+ /**
46
+ * Restores every answered park of a resume source, before the Run starts.
47
+ *
48
+ * The restoration runs first, and not at the respawn, so a refused answer stops
49
+ * the resume before it does any work (ADR-0023). It is same-or-refuse, so a
50
+ * retried resume changes nothing.
51
+ */
52
+ export async function restoreSessionAnswers(
53
+ cassette: Cassette,
54
+ answerFor: (questionId: string) => string | undefined,
55
+ ): Promise<void> {
56
+ for (const mark of parkedAsks(cassette)) {
57
+ const sessionFile = mark.sessionFile;
58
+ if (sessionFile === undefined) continue;
59
+ const answer = answerFor(mark.questionId);
60
+ if (answer === undefined) continue;
61
+ await appendSessionAnswer({ sessionFile, toolCallId: mark.toolCallId, answer });
62
+ }
63
+ }
64
+
65
+ /**
66
+ * Maps one editor refusal to the resume's own error, with the resume's words.
67
+ *
68
+ * Anything that is not a `PiSessionError` is handed back untouched, so the type
69
+ * is the widest one: only the caller's `throw` gives it a meaning.
70
+ */
71
+ function refusal(error: unknown, request: SessionAnswerAppend): unknown {
72
+ if (!isPiSessionError(error)) return error;
73
+ switch (error.reason) {
74
+ case "no-such-call":
75
+ return new YaagError(
76
+ "RESUME_REFUSED",
77
+ `the session file ${request.sessionFile} holds no tool call "${request.toolCallId}" — ` +
78
+ `it is not the session this checkpoint recorded`,
79
+ );
80
+ case "different-result":
81
+ return new YaagError(
82
+ "RESUME_REFUSED",
83
+ `the tool call "${request.toolCallId}" is already answered with ` +
84
+ `"${String(error.existing)}" — ` +
85
+ `it cannot be answered with "${request.answer}" as well`,
86
+ );
87
+ case "unreadable":
88
+ return new YaagError(
89
+ "RESUME_REFUSED",
90
+ `cannot read the session file ${request.sessionFile}: ${error.message}`,
91
+ );
92
+ case "bad-line":
93
+ return new YaagError("RESUME_REFUSED", error.message);
94
+ default: {
95
+ // A new refusal reason must be mapped here, not thrown without a message.
96
+ const never: never = error.reason;
97
+ return new YaagError("RESUME_REFUSED", `cannot restore the answer: ${String(never)}`);
98
+ }
99
+ }
100
+ }