@yaag/runtime 0.22.0 → 0.24.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 (42) hide show
  1. package/package.json +1 -1
  2. package/src/agent/agent.ts +52 -2
  3. package/src/agent/fork.ts +7 -0
  4. package/src/agent/spawn-open.ts +25 -5
  5. package/src/agent/spawn-request.ts +123 -3
  6. package/src/agent/spawn.ts +6 -0
  7. package/src/ask/ask-hash.ts +7 -0
  8. package/src/ask-contract/ask-limit.ts +2 -4
  9. package/src/ask-contract/index.ts +2 -1
  10. package/src/ask-contract/wrap-up-steer.ts +17 -0
  11. package/src/cassette/index.ts +1 -0
  12. package/src/cassette/run-checkpoint.ts +17 -5
  13. package/src/contract/agent-policy.ts +15 -4
  14. package/src/contract/error-codes.ts +3 -2
  15. package/src/contract/index.ts +10 -0
  16. package/src/contract/spawn-options.ts +7 -1
  17. package/src/contract/system-prompt.ts +88 -0
  18. package/src/control/ask-admission.ts +24 -0
  19. package/src/control/control-commands.ts +300 -0
  20. package/src/control/index.ts +31 -0
  21. package/src/control/pause-drain.ts +105 -0
  22. package/src/control/run-controller.ts +88 -0
  23. package/src/events.ts +40 -0
  24. package/src/index.ts +30 -0
  25. package/src/public-api.ts +11 -0
  26. package/src/run/run-settlement.ts +93 -0
  27. package/src/run/run.ts +86 -32
  28. package/src/summary/summary.ts +6 -0
  29. package/src/system-prompt/agent-prompt-extension.ts +337 -0
  30. package/src/system-prompt/agent-prompt.ts +15 -0
  31. package/src/system-prompt/agent-system-prompt.ts +90 -0
  32. package/src/system-prompt/append-channel.ts +69 -0
  33. package/src/system-prompt/define-system-prompt.ts +112 -0
  34. package/src/system-prompt/index.ts +48 -0
  35. package/src/system-prompt/prompt-guards.ts +60 -0
  36. package/src/system-prompt/render-sentinel.ts +75 -0
  37. package/src/transport/append-env.ts +69 -0
  38. package/src/transport/index.ts +2 -0
  39. package/src/transport/live-transport.ts +50 -26
  40. package/src/transport/pi-state.ts +38 -4
  41. package/src/transport/transport.ts +4 -1
  42. package/src/types.ts +8 -0
package/src/index.ts CHANGED
@@ -76,6 +76,23 @@ export {
76
76
  PROJECT_CONFIG_DIR,
77
77
  resolveGlobalConfigDirectory,
78
78
  } from "./config/index.ts";
79
+ export type {
80
+ ControlCommand,
81
+ ControlDecision,
82
+ ControlErrorCode,
83
+ ControlRequest,
84
+ ControlRequests,
85
+ ControlResponse,
86
+ ControlResponseStatus,
87
+ RunController,
88
+ } from "./control/index.ts";
89
+ export {
90
+ ControlCommandReader,
91
+ createRunController,
92
+ DEFAULT_PAUSE_DEADLINE_MS,
93
+ PAUSE_DEADLINE_MAX_MS,
94
+ PAUSE_DEADLINE_MIN_MS,
95
+ } from "./control/index.ts";
79
96
  export type {
80
97
  AskInvalidOutputOutcome,
81
98
  AskLimitKind,
@@ -164,6 +181,11 @@ export type {
164
181
  RunSummary,
165
182
  } from "./summary/index.ts";
166
183
  export { applyEvent, initialSummary } from "./summary/index.ts";
184
+ export type { YaagSystemPromptOptions } from "./system-prompt/index.ts";
185
+ // `isSystemPromptDefinition` and `renderSystemPrompt` stay on
186
+ // `system-prompt/index.ts`: the spawn seam uses them, and no consumer outside
187
+ // this package does.
188
+ export { defineSystemPrompt, yaagSystemPrompt } from "./system-prompt/index.ts";
167
189
  export type {
168
190
  AgentStats,
169
191
  AgentTransport,
@@ -202,10 +224,18 @@ export type {
202
224
  AskOptions,
203
225
  ForkOptions,
204
226
  Handle,
227
+ LiteralPromptText,
228
+ PromptAudience,
229
+ PromptText,
205
230
  ResolvedSpawnOptions,
206
231
  SpawnOptions,
207
232
  SpawnOverrides,
208
233
  StructuredAskOptions,
234
+ SystemPromptAgent,
235
+ SystemPromptBuilder,
236
+ SystemPromptContext,
237
+ SystemPromptDefinition,
238
+ SystemPromptInput,
209
239
  ThinkingLevel,
210
240
  } from "./types.ts";
211
241
  export {
package/src/public-api.ts CHANGED
@@ -16,9 +16,17 @@ export type {
16
16
  AgentPolicy,
17
17
  AskOptions,
18
18
  Handle,
19
+ LiteralPromptText,
20
+ PromptAudience,
21
+ PromptText,
19
22
  SpawnOptions,
20
23
  SpawnOverrides,
21
24
  StructuredAskOptions,
25
+ SystemPromptAgent,
26
+ SystemPromptBuilder,
27
+ SystemPromptContext,
28
+ SystemPromptDefinition,
29
+ SystemPromptInput,
22
30
  ThinkingLevel,
23
31
  } from "./contract/index.ts";
24
32
  export type { YaagErrorCode } from "./errors.ts";
@@ -46,3 +54,6 @@ export { prompt } from "./prompt/prompt.ts";
46
54
  export type { OrchestrationProgram, ProgramDefinition } from "./run/define-run.ts";
47
55
  export { defineRun } from "./run/define-run.ts";
48
56
  export type { RunContext } from "./run/run-context.ts";
57
+ export type { YaagSystemPromptOptions } from "./system-prompt/agent-system-prompt.ts";
58
+ export { yaagSystemPrompt } from "./system-prompt/agent-system-prompt.ts";
59
+ export { defineSystemPrompt } from "./system-prompt/define-system-prompt.ts";
@@ -0,0 +1,93 @@
1
+ import type { ControlRequests, DrainableAgent } from "../control/index.ts";
2
+ import { drainForPause } from "../control/index.ts";
3
+
4
+ /** How one Run settled, before it reaps its Agents and publishes its Checkpoint. */
5
+ export type RunSettlement<Result> =
6
+ | { readonly outcome: "completed"; readonly value: Result }
7
+ | { readonly outcome: "failed"; readonly error: unknown }
8
+ | { readonly outcome: "paused"; readonly cutShort: readonly string[] }
9
+ | { readonly outcome: "stopped" };
10
+
11
+ export interface RunSettlementOptions<Result> {
12
+ /** Starts the Orchestration Program body; a synchronous throw is a Run failure. */
13
+ readonly program: () => Promise<Result> | Result;
14
+ /** The folded external control view of this Run. */
15
+ readonly requests: ControlRequests;
16
+ /** Live reference to the Run's Agent list. */
17
+ readonly agents: readonly DrainableAgent[];
18
+ /** Closes Ask and spawn admission; the drain calls it before its first steer. */
19
+ readonly closeAdmission: () => void;
20
+ }
21
+
22
+ /**
23
+ * Settles one Run: its own program, an external stop, or a bounded pause drain
24
+ * (ADR-0024). The program's handlers are attached synchronously at entry, so a
25
+ * Run waiting on a control request can never leave a rejection unhandled.
26
+ *
27
+ * A program that resolves during a drain wins, because work that settles
28
+ * naturally reports its own outcome. A program that rejects during a drain is
29
+ * absorbed: the rejection is a consequence of the closed admission or the
30
+ * cut-short Ask, so the Run stays `paused`. The rule reads a settlement latch
31
+ * rather than error codes, so no failure vocabulary decides an outcome.
32
+ */
33
+ export async function settleRun<Result>(
34
+ options: RunSettlementOptions<Result>,
35
+ ): Promise<RunSettlement<Result>> {
36
+ // Attached synchronously, so the program promise can never be an unhandled
37
+ // rejection while the Run waits on a control request instead.
38
+ const latch: { settled: RunSettlement<Result> | null } = { settled: null };
39
+ const program = startProgram(options.program);
40
+ // Registered before the race entrant below, so the latch always holds the
41
+ // program's own settlement by the time the race reports it.
42
+ program.then(
43
+ (value): void => {
44
+ latch.settled = { outcome: "completed", value };
45
+ },
46
+ (error: unknown): void => {
47
+ latch.settled = { outcome: "failed", error };
48
+ },
49
+ );
50
+ // The program is the first entrant, so a Run whose program has already
51
+ // settled keeps its own outcome when a control request lands in the same tick.
52
+ const first = await Promise.race([
53
+ program.then(
54
+ () => "program" as const,
55
+ () => "program" as const,
56
+ ),
57
+ options.requests.first.then(() => "control" as const),
58
+ ]);
59
+ if (first === "program") return settledLatch(latch.settled);
60
+ const control = await options.requests.first;
61
+ if (control.kind === "stop") {
62
+ options.closeAdmission();
63
+ return { outcome: "stopped" };
64
+ }
65
+ const drained = await drainForPause({
66
+ agents: options.agents,
67
+ deadlineMs: control.deadlineMs,
68
+ closeAdmission: options.closeAdmission,
69
+ stopped: options.requests.stopped,
70
+ });
71
+ const settled = latch.settled;
72
+ if (settled !== null && settled.outcome === "completed") return settled;
73
+ if (drained.kind === "stopped") return { outcome: "stopped" };
74
+ return { outcome: "paused", cutShort: drained.cutShort };
75
+ }
76
+
77
+ /**
78
+ * Starts the body without adding a scheduling hop, so a program that settles in
79
+ * the same tick as a control request still wins the race. A synchronous throw
80
+ * settles like a rejection.
81
+ */
82
+ function startProgram<Result>(body: () => Promise<Result> | Result): Promise<Result> {
83
+ try {
84
+ return Promise.resolve(body());
85
+ } catch (error) {
86
+ return Promise.reject(error);
87
+ }
88
+ }
89
+
90
+ function settledLatch<Result>(latch: RunSettlement<Result> | null): RunSettlement<Result> {
91
+ if (latch === null) throw new Error("unreachable: the program settled without a latch");
92
+ return latch;
93
+ }
package/src/run/run.ts CHANGED
@@ -13,6 +13,7 @@ import {
13
13
  createCheckpointFlusher,
14
14
  flushingSink,
15
15
  interruptedResumeWarning,
16
+ keepsCheckpoint,
16
17
  loadCassette,
17
18
  type ProgramIdentity,
18
19
  prepareRecordDestination,
@@ -28,7 +29,8 @@ import {
28
29
  writeRecordingDiagnostic,
29
30
  } from "../cassette/index.ts";
30
31
  import { type EffectiveConfig, EMPTY_EFFECTIVE_CONFIG } from "../config/index.ts";
31
- import { isYaagError, YaagError } from "../errors.ts";
32
+ import { controlRequests, createAskAdmission, type RunController } from "../control/index.ts";
33
+ import { YaagError } from "../errors.ts";
32
34
  import type { EventSink, LifecycleEvent, RunOutcome, StampedEventSink } from "../events.ts";
33
35
  import { selectProfile } from "../profile/index.ts";
34
36
  import { applyEvent, initialSummary, type RunSummary } from "../summary/index.ts";
@@ -43,6 +45,7 @@ import {
43
45
  import { validateArgs } from "./args-validation.ts";
44
46
  import { type OrchestrationProgram, programDefinition } from "./define-run.ts";
45
47
  import type { RunContext } from "./run-context.ts";
48
+ import { type RunSettlement, settleRun } from "./run-settlement.ts";
46
49
 
47
50
  export interface RunOptions {
48
51
  /** Where Agents come from. Defaults to real `pi --mode rpc` processes. */
@@ -72,6 +75,12 @@ export interface RunOptions {
72
75
  readonly resume?: string;
73
76
  /** Ends the Run early; every Agent is still reaped and costed. */
74
77
  readonly signal?: AbortSignal;
78
+ /**
79
+ * External Run control: a bounded pause drain, or a stop (ADR-0024). A stop
80
+ * outranks a pause, before or during its drain. `signal` keeps working, and
81
+ * an abort is folded in as a stop.
82
+ */
83
+ readonly control?: RunController;
75
84
  /** Overrides the default checkpoint directory a stopped Run publishes into (ADR-0021). */
76
85
  readonly checkpointDir?: string;
77
86
  /**
@@ -187,12 +196,17 @@ export async function executeRun<Args, Result>(
187
196
  });
188
197
  const agents: Agent[] = [];
189
198
  const startedAt = Date.now();
199
+ const askAdmission = createAskAdmission();
190
200
  const spawnGate = makeSpawn({
191
201
  factory,
192
202
  agents,
193
203
  emit,
204
+ askAdmission,
194
205
  sessionDir: options.sessionDir,
195
206
  programFile: options.programFile,
207
+ // The same value `run_start.program` carries, so an Agent's prompt names
208
+ // the Run the reader sees in the Run record.
209
+ runName: definition.name ?? "program",
196
210
  configExtensions: options.config?.extensions ?? EMPTY_EFFECTIVE_CONFIG.extensions,
197
211
  ...(profile === undefined ? {} : { profile }),
198
212
  });
@@ -211,16 +225,19 @@ export async function executeRun<Args, Result>(
211
225
 
212
226
  // The program's settlement is held rather than rethrown from a `finally`, so
213
227
  // publication can displace it when the checkpoint fails (ADR-0021).
214
- let outcome: RunOutcome = "failed";
215
- let settled: Settlement<Result>;
216
- try {
217
- const value = await Promise.race([definition.run(ctx), stopped(options.signal)]);
218
- outcome = "completed";
219
- settled = { ok: true, value };
220
- } catch (error) {
221
- outcome = stopOutcome(error);
222
- settled = { ok: false, error };
223
- }
228
+ const settlement = await settleRun({
229
+ program: () => definition.run(ctx),
230
+ requests: controlRequests(options.control, options.signal),
231
+ agents,
232
+ closeAdmission: () => {
233
+ askAdmission.close();
234
+ spawnGate.close();
235
+ },
236
+ });
237
+ const outcome: RunOutcome = settlement.outcome;
238
+ const settled = heldSettlement(settlement);
239
+ // Idempotent: a settlement that never drained has not closed admission yet.
240
+ askAdmission.close();
224
241
  spawnGate.close();
225
242
  await reapAll({ agents, emit });
226
243
  // No flush may land after the settled artifact, or an acknowledged Run would
@@ -233,7 +250,7 @@ export async function executeRun<Args, Result>(
233
250
  emit,
234
251
  durationMs: Date.now() - startedAt,
235
252
  summary,
236
- ...endingFrom(publication, outcome),
253
+ ...endingFrom({ publication, outcome, destination, record: options.record }),
237
254
  });
238
255
  if (publication.kind === "displaced") throw publication.error;
239
256
  if (!settled.ok) throw settled.error;
@@ -284,9 +301,29 @@ type Settlement<Result> =
284
301
  | { readonly ok: true; readonly value: Result }
285
302
  | { readonly ok: false; readonly error: unknown };
286
303
 
287
- /** The stop signal is the only rejection that is not a Run failure (ADR-0022). */
288
- function stopOutcome(error: unknown): RunOutcome {
289
- return isYaagError(error) && error.code === "RUN_STOPPED" ? "stopped" : "failed";
304
+ /**
305
+ * Turns one settlement into the result the Run holds until its Checkpoint has
306
+ * landed. A stopped or paused Run rejects with its own code, so the caller can
307
+ * tell an ended Run from a failed one (ADR-0024).
308
+ */
309
+ function heldSettlement<Result>(settlement: RunSettlement<Result>): Settlement<Result> {
310
+ switch (settlement.outcome) {
311
+ case "completed":
312
+ return { ok: true, value: settlement.value };
313
+ case "failed":
314
+ return { ok: false, error: settlement.error };
315
+ case "paused":
316
+ // The cut-short Agents are named here, so the rejection says which Asks
317
+ // the deadline ended rather than leaving that to the Checkpoint alone.
318
+ return { ok: false, error: new YaagError("RUN_PAUSED", pauseMessage(settlement.cutShort)) };
319
+ case "stopped":
320
+ return { ok: false, error: new YaagError("RUN_STOPPED", "run stopped") };
321
+ }
322
+ }
323
+
324
+ /** Names the Asks a pause deadline cut short, or reports a clean drain. */
325
+ function pauseMessage(cutShort: readonly string[]): string {
326
+ return cutShort.length === 0 ? "run paused" : `run paused, cutting short: ${cutShort.join(", ")}`;
290
327
  }
291
328
 
292
329
  /**
@@ -337,17 +374,6 @@ function selectLiveFactory(selection: FactorySelection): TransportFactory {
337
374
  return selection.resume === null ? live : resumeTransport(selection.resume, live);
338
375
  }
339
376
 
340
- /** Rejects when the Run is stopped; never resolves. */
341
- function stopped(signal: AbortSignal | undefined): Promise<never> {
342
- return new Promise<never>((_resolve, reject) => {
343
- if (!signal) return;
344
- if (signal.aborted) reject(new YaagError("RUN_STOPPED", "run stopped"));
345
- signal.addEventListener("abort", () => reject(new YaagError("RUN_STOPPED", "run stopped")), {
346
- once: true,
347
- });
348
- });
349
- }
350
-
351
377
  interface ReapOptions {
352
378
  readonly agents: readonly Agent[];
353
379
  readonly emit: EventSink;
@@ -385,19 +411,39 @@ interface RunEndOptions {
385
411
  readonly summary: RunSummary;
386
412
  /** Publication error text when a requested Checkpoint was lost (ticket 04). */
387
413
  readonly checkpointLost?: string;
414
+ /** Path of the published Checkpoint a paused or stopped Run resumes from (ADR-0054). */
415
+ readonly checkpoint?: string;
388
416
  }
389
417
 
390
418
  /**
391
419
  * Folds one publication result into how the Run ends. A displaced publication
392
420
  * takes the outcome; a lost Checkpoint keeps it and reports the loss instead.
393
421
  */
394
- function endingFrom(
395
- publication: RunCheckpointResult,
396
- outcome: RunOutcome,
397
- ): { readonly outcome: RunOutcome; readonly checkpointLost?: string } {
422
+ function endingFrom(options: {
423
+ readonly publication: RunCheckpointResult;
424
+ readonly outcome: RunOutcome;
425
+ readonly destination: string;
426
+ /** The `--record` destination, or undefined; it decides what is kept. */
427
+ readonly record: string | undefined;
428
+ }): {
429
+ readonly outcome: RunOutcome;
430
+ readonly checkpointLost?: string;
431
+ readonly checkpoint?: string;
432
+ } {
433
+ const { publication, outcome, destination, record } = options;
398
434
  switch (publication.kind) {
399
435
  case "published":
400
- return { outcome };
436
+ // A Run names a Checkpoint only when publication kept the artifact, and
437
+ // only a paused or stopped Run resumes from one (ADR-0054). `keepsCheckpoint`
438
+ // is the one rule for the first half, so no Run can name a file that
439
+ // publication just deleted.
440
+ return {
441
+ outcome,
442
+ ...((outcome === "paused" || outcome === "stopped") &&
443
+ keepsCheckpoint({ outcome, ...(record === undefined ? {} : { record }) })
444
+ ? { checkpoint: destination }
445
+ : {}),
446
+ };
401
447
  case "lost":
402
448
  return { outcome, checkpointLost: publication.message };
403
449
  case "displaced":
@@ -406,10 +452,18 @@ function endingFrom(
406
452
  }
407
453
 
408
454
  /** Emits the Run's acknowledgement, the last Lifecycle Event of every Run. */
409
- function emitRunEnd({ emit, outcome, durationMs, summary, checkpointLost }: RunEndOptions): void {
455
+ function emitRunEnd({
456
+ emit,
457
+ outcome,
458
+ durationMs,
459
+ summary,
460
+ checkpointLost,
461
+ checkpoint,
462
+ }: RunEndOptions): void {
410
463
  emit({
411
464
  type: "run_end",
412
465
  ...(checkpointLost === undefined ? {} : { checkpointLost }),
466
+ ...(checkpoint === undefined ? {} : { checkpoint }),
413
467
  ok: outcome === "completed",
414
468
  outcome,
415
469
  durationMs,
@@ -78,6 +78,11 @@ export interface EndedRunSummary extends RunSummaryBase {
78
78
  * artifact too. Carries the publication error text (ticket 04).
79
79
  */
80
80
  readonly checkpointLost?: string;
81
+ /**
82
+ * Path of the Checkpoint the Run published; null when it kept none
83
+ * (ADR-0054). Only a paused or stopped Run names one.
84
+ */
85
+ readonly checkpoint: string | null;
81
86
  }
82
87
 
83
88
  /**
@@ -218,6 +223,7 @@ function endRun(
218
223
  endedAt: at,
219
224
  durationMs: event.durationMs,
220
225
  worstFrameGapMs: event.worstFrameGapMs,
226
+ checkpoint: event.checkpoint ?? null,
221
227
  ...(event.checkpointLost === undefined ? {} : { checkpointLost: event.checkpointLost }),
222
228
  };
223
229
  }