@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
@@ -56,6 +56,10 @@ function dedupe(names: Iterable<string>): string[] {
56
56
  * `report_result` is allowed but never required: report-result-extension.ts
57
57
  * registers the tool when a schema-bearing Ask activates it, long after startup
58
58
  * (ADR-0032), so at startup the probe reports it as inactive.
59
+ *
60
+ * `request_user_input` is required whenever the spawn may ask its human: that
61
+ * extension registers its tool at startup, so a lost capability fails the spawn
62
+ * instead of surfacing as a silent inability to ask (ADR-0023).
59
63
  */
60
64
  export function toolContract(options: ToolContractOptions): ToolContract | null {
61
65
  // pi-state.ts strips this name from `--exclude-tools`, so it is never denied.
@@ -7,6 +7,7 @@ import type {
7
7
  TokenBreakdown,
8
8
  } from "../contract/index.ts";
9
9
  import type { AskLimitOutcome, AskStalledOutcome } from "../errors.ts";
10
+ import type { SpawnOrigin } from "../events.ts";
10
11
  import type { RecordedSpawnSelection } from "../model/index.ts";
11
12
 
12
13
  /**
@@ -90,6 +91,11 @@ export interface AskCompletion {
90
91
  readonly invalidOutput?: AskInvalidOutputPlayback;
91
92
  /** The Stall Watchdog settled this Ask from observed state (ADR-0029). */
92
93
  readonly recovered?: true;
94
+ /**
95
+ * The turn parked on `request_user_input` and never settled (ADR-0023).
96
+ * The collector records it as the incomplete-Ask marker of the Ask (ADR-0021).
97
+ */
98
+ readonly parked?: { readonly toolCallId: string; readonly questionId: string };
93
99
  }
94
100
 
95
101
  /**
@@ -141,6 +147,14 @@ export interface AskPlayback {
141
147
  * Cassette does not contain.
142
148
  */
143
149
  readonly settles?: false;
150
+ /**
151
+ * The recorded Ask parked on `request_user_input` and this resume holds no
152
+ * answer for it (ADR-0023). The playback reports only which Question this Ask
153
+ * is parked on: the question text lives in the run block of the Checkpoint,
154
+ * not in the recorded frames (ADR-0022). The Ask parks again, so the Run
155
+ * pauses with the Question still open.
156
+ */
157
+ readonly parked?: { readonly toolCallId: string; readonly questionId: string };
144
158
  }
145
159
 
146
160
  /** One Agent, as the layer above sees it. */
@@ -223,6 +237,16 @@ export interface OpenOptions {
223
237
  * Spawn identity only: it never becomes argv, and it is absent when empty.
224
238
  */
225
239
  readonly declaredExtensions?: readonly string[];
240
+ /**
241
+ * Loads the injected `request_user_input` extension (ADR-0023). Only ever
242
+ * true, so an Agent that never asks keeps a byte-identical open request.
243
+ */
244
+ readonly canAskUser?: true;
245
+ /**
246
+ * The protocol the injected extension declares. Spawn identity only: it never
247
+ * becomes argv, and it is compared when a recorded Agent reactivates.
248
+ */
249
+ readonly askUserProtocol?: number;
226
250
  /**
227
251
  * Resolved name of the Agent named as this Agent's parent (Parent Link).
228
252
  * Spawn identity only: it never becomes argv.
@@ -233,7 +257,13 @@ export interface OpenOptions {
233
257
  /** Resumes an existing pi session, translated to `--session <path>`. */
234
258
  readonly sessionFile?: string;
235
259
  /** How the Agent came to be; absent means an ordinary spawn. Spawn identity. */
236
- readonly origin?: "fork";
260
+ readonly origin?: SpawnOrigin;
261
+ /**
262
+ * Identity of the Host Session conversation a host-fork was taken from.
263
+ * Spawn identity: the Cassette records it and a replay compares it. It never
264
+ * becomes argv; the copy path pi forks from is `forkSession` (ADR-0068).
265
+ */
266
+ readonly hostHash?: string;
237
267
  /** Name of the Agent this one was forked from. Spawn identity; never argv. */
238
268
  readonly forkOf?: string;
239
269
  /** Settled Asks of the fork source at the fork point. Spawn identity. */
package/src/types.ts CHANGED
@@ -11,6 +11,7 @@ export type {
11
11
  CompactionResult,
12
12
  ForkOptions,
13
13
  Handle,
14
+ HostSource,
14
15
  LiteralPromptText,
15
16
  ModelError,
16
17
  PromptAudience,
@@ -1,101 +0,0 @@
1
- import type { CassetteRecorder, CassetteSink } from "./cassette.ts";
2
- import { publishCassette } from "./cassette-publish.ts";
3
- import {
4
- ensureCheckpointDirectory,
5
- type RunIdentity,
6
- writeRecordingDiagnostic,
7
- } from "./run-checkpoint.ts";
8
-
9
- /**
10
- * Publishes the Run's in-progress Checkpoint (ADR-0031).
11
- *
12
- * Each flush rewrites the full collected Cassette to the Run's destination with
13
- * the same atomic write a settled Checkpoint uses, and states the outcome
14
- * `interrupted`. Flushes never reject: a failed one writes a diagnostic, and the
15
- * next Ask boundary tries again.
16
- */
17
- export interface CheckpointFlusher {
18
- /** Requests a publication; returns at once. Concurrent requests coalesce. */
19
- flush(): void;
20
- /** Resolves when no publication is in flight, and stops accepting new ones. */
21
- quiesce(): Promise<void>;
22
- }
23
-
24
- export interface CheckpointFlushOptions {
25
- /** Read at each flush; its current content becomes the artifact. */
26
- readonly collector: CassetteSink;
27
- /** Explicit `--record` destination, or undefined when the Run only checkpoints. */
28
- readonly record: string | undefined;
29
- /** Where the in-progress artifact lives; fixed at Run start. */
30
- readonly destination: string;
31
- readonly identity: RunIdentity;
32
- }
33
-
34
- export function createCheckpointFlusher(options: CheckpointFlushOptions): CheckpointFlusher {
35
- let active: Promise<void> | null = null;
36
- let requested = false;
37
- let stopped = false;
38
-
39
- const publish = async (): Promise<void> => {
40
- try {
41
- await ensureCheckpointDirectory(options.record, options.destination);
42
- await publishCassette(
43
- options.destination,
44
- options.collector.cassette({ outcome: "interrupted", ...options.identity }),
45
- );
46
- } catch (error) {
47
- // Losing this boundary costs one Ask of restorability; failing the Run
48
- // would cost the whole Run (ADR-0031).
49
- writeRecordingDiagnostic(error);
50
- }
51
- };
52
-
53
- // Only one publication runs at a time, so two Asks settling together cannot
54
- // interleave two writes onto one destination. A request that arrives during a
55
- // write is folded into exactly one follow-up write.
56
- const pump = async (): Promise<void> => {
57
- while (requested && !stopped) {
58
- requested = false;
59
- await publish();
60
- }
61
- active = null;
62
- };
63
-
64
- return {
65
- flush: (): void => {
66
- if (stopped) return;
67
- requested = true;
68
- active ??= pump();
69
- },
70
- quiesce: async (): Promise<void> => {
71
- stopped = true;
72
- while (active !== null) await active;
73
- },
74
- };
75
- }
76
-
77
- /**
78
- * Wraps a sink so every Ask boundary publishes the Checkpoint: an Agent opened,
79
- * an Ask begun, an Ask finished, an Agent closed (ADR-0031).
80
- */
81
- export function flushingSink(sink: CassetteSink, flusher: CheckpointFlusher): CassetteSink {
82
- return {
83
- cassette: (run) => sink.cassette(run),
84
- reserve: (options): CassetteRecorder => {
85
- const recorder = sink.reserve(options);
86
- const boundary =
87
- <Args extends unknown[]>(record: (...args: Args) => void) =>
88
- (...args: Args): void => {
89
- record(...args);
90
- flusher.flush();
91
- };
92
- return {
93
- ...recorder,
94
- opened: boundary(recorder.opened),
95
- beginAsk: boundary(recorder.beginAsk),
96
- finishAsk: boundary(recorder.finishAsk),
97
- closed: boundary(recorder.closed),
98
- };
99
- },
100
- };
101
- }
@@ -1,223 +0,0 @@
1
- import { mkdir, unlink } from "node:fs/promises";
2
- import { dirname } from "node:path";
3
- import { YaagError } from "../errors.ts";
4
- import type { RunOutcome } from "../events.ts";
5
- import type { CassetteCollector, CassetteRun } from "./cassette.ts";
6
- import { publishCassette } from "./cassette-publish.ts";
7
- import { sha256Hex } from "./program-hash.ts";
8
-
9
- /** What a resume is about to re-execute; resolved once, at Run start. */
10
- export type RunIdentity = Omit<CassetteRun, "outcome">;
11
-
12
- /**
13
- * One Run's publication request: what settled, what it collected, and where the
14
- * artifact goes. The destination is fixed at Run start (ADR-0031): the
15
- * `--record` path itself, or one name in the checkpoint directory.
16
- */
17
- export interface RunCheckpointOptions {
18
- /** Terminal outcome; `stopped` and `paused` keep the artifact without `record`. */
19
- readonly outcome: RunOutcome;
20
- readonly collector: CassetteCollector;
21
- /** Explicit `--record` destination, or undefined when the Run only checkpoints. */
22
- readonly record: string | undefined;
23
- /** Where this Run's artifact lives, in-flight and at settlement. */
24
- readonly destination: string;
25
- /** Invocation identity written into the artifact's run block. */
26
- readonly identity: RunIdentity;
27
- }
28
-
29
- /**
30
- * What one publication attempt did. `published` covers both a written artifact
31
- * and a Run that keeps none. `displaced` carries the error that must become the
32
- * Run's outcome. `lost` reports a Checkpoint the Run asked for and did not get,
33
- * while the Run keeps its own outcome — a completed result, or a primary
34
- * program error (ADR-0021 amendment).
35
- */
36
- export type RunCheckpointResult =
37
- | { readonly kind: "published" }
38
- | { readonly kind: "displaced"; readonly error: unknown }
39
- | { readonly kind: "lost"; readonly message: string };
40
-
41
- /**
42
- * Publishes the collected Cassette when the Run must be restorable: always under
43
- * `--record`, and additionally into the checkpoint directory when the Run
44
- * stopped or paused (ADR-0021/0024).
45
- */
46
- export async function publishRunCheckpoint(
47
- options: RunCheckpointOptions,
48
- ): Promise<RunCheckpointResult> {
49
- if (!keepsCheckpoint(options)) {
50
- // A clean settlement without --record publishes nothing, so the in-flight
51
- // artifact this Run flushed goes away with it (ADR-0031).
52
- await discardCheckpoint(options.destination);
53
- return { kind: "published" };
54
- }
55
- try {
56
- await ensureCheckpointDirectory(options.record, options.destination);
57
- await publishCassette(
58
- options.destination,
59
- options.collector.cassette({ outcome: options.outcome, ...options.identity }),
60
- );
61
- return { kind: "published" };
62
- } catch (error) {
63
- // A secondary publication failure must not displace a primary program error,
64
- // so the loss rides on run_end instead (ticket 04). The stderr diagnostic
65
- // stays: it is the CLI user's own trace of the loss.
66
- if (options.outcome === "failed") {
67
- writeRecordingDiagnostic(error);
68
- return { kind: "lost", message: String(error) };
69
- }
70
- // A completed Run keeps its outcome and its result: the work is done, and
71
- // no restorability promise is broken. The lost Cassette rides
72
- // run_end.checkpointLost and the stderr diagnostic instead of displacing
73
- // the outcome (ADR-0021 amendment).
74
- if (options.outcome === "completed") {
75
- const message = `run completed but its Cassette could not be written: ${String(error)}`;
76
- writeRecordingDiagnostic(message);
77
- return { kind: "lost", message };
78
- }
79
- // A pausing or stopped Run promises restorability, and a Checkpoint that
80
- // did not land makes that acknowledgement a lie, so the failure takes the
81
- // outcome (ADR-0021: a flush failure is a hard failure there).
82
- return {
83
- kind: "displaced",
84
- error: new Error(`run ${options.outcome} but is not restorable: ${String(error)}`, {
85
- cause: error,
86
- }),
87
- };
88
- }
89
- }
90
-
91
- /**
92
- * Whether a Run keeps its artifact: `--record` names a destination, or the Run
93
- * paused or stopped. Every other Run discards the in-flight artifact, so it
94
- * names no Checkpoint on `run_end` either — `run.ts` reads this same rule
95
- * (ADR-0054). A paused Run promises restorability, so it keeps its artifact
96
- * and can name its path.
97
- */
98
- export function keepsCheckpoint(options: {
99
- readonly record?: string;
100
- readonly outcome: RunOutcome;
101
- }): boolean {
102
- return (
103
- options.record !== undefined || options.outcome === "stopped" || options.outcome === "paused"
104
- );
105
- }
106
-
107
- /**
108
- * Creates the directory the Run's artifact goes into. A `--record` path names
109
- * where the artifact goes, so yaag creates the chain that path implies rather
110
- * than refusing. ADR-0021 makes `--record` fix the destination path only, and a
111
- * path yaag can make is a destination yaag makes. The checkpoint directory yaag owns stays
112
- * private; a user-named `--record` directory takes the process umask, because it
113
- * lives in the user's own tree.
114
- */
115
- export async function ensureCheckpointDirectory(
116
- record: string | undefined,
117
- destination: string,
118
- ): Promise<void> {
119
- const directory = dirname(destination);
120
- if (record === undefined) {
121
- await mkdir(directory, { recursive: true, mode: 0o700 });
122
- return;
123
- }
124
- await mkdir(directory, { recursive: true });
125
- }
126
-
127
- /**
128
- * Makes the directory chain of the `--record` path at Run start, and rejects the
129
- * Run before the first spawn when that chain cannot exist. It does not prove the
130
- * destination writable: an existing directory that refuses a write, or a name
131
- * already taken, still fails later, at publication.
132
- */
133
- export async function prepareRecordDestination(record: string): Promise<void> {
134
- try {
135
- await ensureCheckpointDirectory(record, record);
136
- } catch (error) {
137
- throw new YaagError(
138
- "RECORD_PATH_UNUSABLE",
139
- `cannot create the Cassette directory ${dirname(record)}: ${String(error)}`,
140
- );
141
- }
142
- }
143
-
144
- /** Which program a Run executes: a file on disk, or inline source text (ADR-0033). */
145
- export interface ProgramIdentity {
146
- readonly programFile?: string;
147
- /** Inline source, exactly as the caller gave it; it excludes any loader prelude. */
148
- readonly programSource?: string;
149
- }
150
-
151
- /** What one Run's invocation identity is made of: program, args, and Profile. */
152
- export interface RunIdentityRequest {
153
- readonly program: ProgramIdentity;
154
- readonly args: unknown;
155
- /** Active Profile id; part of invocation identity, resolved before this call (ADR-0052). */
156
- readonly profile?: string;
157
- }
158
-
159
- /**
160
- * Resolves what a resume re-executes: the program, its args, and the active
161
- * Profile. The program hash is advisory only.
162
- */
163
- export async function resolveRunIdentity(request: RunIdentityRequest): Promise<RunIdentity> {
164
- const { program, args, profile } = request;
165
- const profileKey = profile === undefined ? {} : { profile };
166
- // An Inline Program's file is a temporary path, and no artifact may name it,
167
- // so the inline arm drops `programFile` even when the caller supplies one.
168
- if (program.programSource !== undefined) {
169
- const programSource = program.programSource;
170
- return { programSource, args, programHash: sha256Hex(programSource), ...profileKey };
171
- }
172
- const programFile = program.programFile;
173
- // A Run with neither a program file nor inline source still has a Profile.
174
- if (programFile === undefined) return { ...profileKey };
175
- const programHash = await hashProgram(programFile);
176
- return {
177
- programFile,
178
- args,
179
- ...(programHash === null ? {} : { programHash }),
180
- ...profileKey,
181
- };
182
- }
183
-
184
- /**
185
- * Removes the in-progress artifact of a Run that publishes nothing. A missing
186
- * file is the normal case: the Run may never have reached an Ask boundary. Any
187
- * other failure is a diagnostic, because the file left behind states
188
- * `interrupted` and a reader trusts that word (ADR-0031).
189
- */
190
- async function discardCheckpoint(destination: string): Promise<void> {
191
- try {
192
- await unlink(destination);
193
- } catch (error) {
194
- if (!isMissingFile(error)) writeRecordingDiagnostic(error);
195
- }
196
- }
197
-
198
- function isMissingFile(error: unknown): boolean {
199
- return (
200
- typeof error === "object" &&
201
- error !== null &&
202
- "code" in error &&
203
- (error as { readonly code?: unknown }).code === "ENOENT"
204
- );
205
- }
206
-
207
- /** Advisory only: an unreadable program file omits the hash and never fails the Run. */
208
- async function hashProgram(programFile: string): Promise<string | null> {
209
- try {
210
- return sha256Hex(await Bun.file(programFile).arrayBuffer());
211
- } catch {
212
- return null;
213
- }
214
- }
215
-
216
- /** Reports a secondary Cassette publication failure without displacing the Run's primary error. */
217
- export function writeRecordingDiagnostic(error: unknown): void {
218
- try {
219
- process.stderr.write(`[yaag] ${String(error)}\n`);
220
- } catch {
221
- // stderr diagnostics are best-effort: a broken stderr must not mask the Run's error either.
222
- }
223
- }