@yaag/runtime 0.24.0 → 0.26.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 (62) hide show
  1. package/package.json +2 -3
  2. package/src/agent/agent.ts +46 -6
  3. package/src/agent/ask-user-capability.ts +36 -0
  4. package/src/agent/index.ts +3 -1
  5. package/src/agent/spawn-open.ts +24 -5
  6. package/src/agent/spawn-request.ts +18 -1
  7. package/src/agent/spawn.ts +31 -9
  8. package/src/agent/spawnable-definition.ts +9 -0
  9. package/src/ask/ask-exchange-options.ts +5 -0
  10. package/src/ask/ask-exchange.ts +67 -2
  11. package/src/ask/ask-settlement.ts +8 -0
  12. package/src/ask/idle-watch.ts +12 -2
  13. package/src/ask/stall-watchdog.ts +13 -3
  14. package/src/ask-contract/ask-limit.ts +24 -6
  15. package/src/ask-contract/index.ts +8 -0
  16. package/src/ask-contract/request-user-input-extension.ts +105 -0
  17. package/src/ask-contract/request-user-input.ts +58 -0
  18. package/src/cassette/cassette-loader.ts +50 -1
  19. package/src/cassette/cassette-schema.ts +27 -0
  20. package/src/cassette/cassette.ts +49 -0
  21. package/src/cassette/index.ts +10 -1
  22. package/src/cassette/replay-divergence.ts +5 -0
  23. package/src/cassette/resume-preconditions.ts +10 -0
  24. package/src/cassette/resume-transport.ts +111 -6
  25. package/src/cassette/run-checkpoint.ts +52 -3
  26. package/src/cassette/session-answer.ts +163 -0
  27. package/src/catalog/index.ts +5 -3
  28. package/src/catalog/registry-reader.ts +1 -1
  29. package/src/catalog/resolve.ts +184 -0
  30. package/src/config/config-schema.ts +33 -0
  31. package/src/config/effective-config.ts +53 -0
  32. package/src/config/index.ts +4 -0
  33. package/src/contract/agent-policy.ts +9 -0
  34. package/src/contract/catalog-resolve.ts +33 -0
  35. package/src/contract/error-codes.ts +5 -2
  36. package/src/contract/index.ts +10 -2
  37. package/src/control/index.ts +2 -0
  38. package/src/control/pause-drain.ts +81 -24
  39. package/src/errors.ts +8 -2
  40. package/src/events.ts +6 -0
  41. package/src/index.ts +18 -2
  42. package/src/model/index.ts +1 -1
  43. package/src/public-api.ts +7 -0
  44. package/src/question-summary/index.ts +22 -0
  45. package/src/question-summary/session-copy.ts +169 -0
  46. package/src/question-summary/summarize-question.ts +129 -0
  47. package/src/question-summary/summary-policy.ts +25 -0
  48. package/src/run/agent-questions.ts +75 -0
  49. package/src/run/answers.ts +70 -0
  50. package/src/run/index.ts +5 -0
  51. package/src/run/pause-questions.ts +98 -0
  52. package/src/run/pause-signal.ts +32 -0
  53. package/src/run/question-id.ts +18 -0
  54. package/src/run/questions.ts +31 -0
  55. package/src/run/run-context.ts +26 -1
  56. package/src/run/run-result.ts +21 -0
  57. package/src/run/run-settlement.ts +36 -4
  58. package/src/run/run.ts +119 -20
  59. package/src/system-prompt/agent-system-prompt.ts +1 -1
  60. package/src/transport/pi-state.ts +21 -4
  61. package/src/transport/tool-probe.ts +4 -0
  62. package/src/transport/transport.ts +26 -0
@@ -1,4 +1,11 @@
1
1
  import { type Static, Type } from "typebox";
2
+ import { THINKING_LEVELS } from "../model/index.ts";
3
+
4
+ /**
5
+ * The thinking union, built from `THINKING_LEVELS`, so a level pi adds cannot
6
+ * drift out of the config schema.
7
+ */
8
+ const ThinkingLevelSchema = Type.Union(THINKING_LEVELS.map((level) => Type.Literal(level)));
2
9
 
3
10
  /**
4
11
  * The config document of one layer (spec rule 1): plain JSON, namespaced as
@@ -9,6 +16,9 @@ import { type Static, Type } from "typebox";
9
16
  * a newer artifact still loads. A config file is hand-written, so an unknown
10
17
  * key is a typo the author wants named, not forward compatibility.
11
18
  *
19
+ * `askUser.summary` configures the Question Summary the fork summarizer writes
20
+ * (ADR-0022). Like `profile`, each of its keys is last-layer-wins.
21
+ *
12
22
  * `profile` is the one top-level scalar key. Unlike `agents.extensions`, which
13
23
  * concatenates across the layers, it does not concatenate: the last layer that
14
24
  * states it wins (ADR-0052).
@@ -22,6 +32,29 @@ export const YaagConfigSchema = Type.Object(
22
32
  ),
23
33
  ),
24
34
  profile: Type.Optional(Type.String()),
35
+ askUser: Type.Optional(
36
+ Type.Object(
37
+ {
38
+ summary: Type.Optional(
39
+ Type.Object(
40
+ {
41
+ policy: Type.Optional(
42
+ Type.Union([
43
+ Type.Literal("never"),
44
+ Type.Literal("always"),
45
+ Type.Literal("when-missing"),
46
+ ]),
47
+ ),
48
+ model: Type.Optional(Type.String()),
49
+ thinking: Type.Optional(ThinkingLevelSchema),
50
+ },
51
+ { additionalProperties: false },
52
+ ),
53
+ ),
54
+ },
55
+ { additionalProperties: false },
56
+ ),
57
+ ),
25
58
  },
26
59
  { additionalProperties: false },
27
60
  );
@@ -1,3 +1,4 @@
1
+ import type { ThinkingLevel } from "../model/index.ts";
1
2
  import { type ConfigLayer, readConfigLayer } from "./config-file.ts";
2
3
  import {
3
4
  type ConfigEnvironment,
@@ -5,6 +6,28 @@ import {
5
6
  resolveGlobalConfigPath,
6
7
  } from "./config-paths.ts";
7
8
 
9
+ /** When the fork summarizer runs for one Agent Question (ADR-0022). */
10
+ export type QuestionSummaryPolicy = "never" | "always" | "when-missing";
11
+
12
+ /** The resolved `askUser.summary` block; every default is already applied. */
13
+ export interface QuestionSummaryConfig {
14
+ readonly policy: QuestionSummaryPolicy;
15
+ /** Model pattern for the summarizer; absent means the parked Agent's own model. */
16
+ readonly model?: string;
17
+ readonly thinking: ThinkingLevel;
18
+ }
19
+
20
+ /** Reads the Question Summary settings of one config, defaults included. */
21
+ export function questionSummaryOf(config: EffectiveConfig | undefined): QuestionSummaryConfig {
22
+ return config?.askUserSummary ?? DEFAULT_QUESTION_SUMMARY;
23
+ }
24
+
25
+ /** The Question Summary settings of a Run that configured none. */
26
+ export const DEFAULT_QUESTION_SUMMARY: QuestionSummaryConfig = Object.freeze({
27
+ policy: "when-missing" as const,
28
+ thinking: "low" as const,
29
+ });
30
+
8
31
  /** Which of the three layers a config value came from. */
9
32
  export type ConfigLayerName = "global" | "project" | "run";
10
33
 
@@ -30,6 +53,12 @@ export interface EffectiveConfig {
30
53
  * when no layer stated one.
31
54
  */
32
55
  readonly profile?: string;
56
+ /**
57
+ * Resolved Question Summary settings (ADR-0022). Optional on purpose: an
58
+ * `EffectiveConfig` built outside this module stays valid, and every reader
59
+ * goes through `questionSummaryOf`, which applies the defaults.
60
+ */
61
+ readonly askUserSummary?: QuestionSummaryConfig;
33
62
  }
34
63
 
35
64
  /** What to discover and read. */
@@ -48,6 +77,7 @@ export interface EffectiveConfigRequest {
48
77
  export const EMPTY_EFFECTIVE_CONFIG: EffectiveConfig = Object.freeze({
49
78
  extensions: Object.freeze([]) as readonly ConfigExtension[],
50
79
  files: Object.freeze([]) as readonly string[],
80
+ askUserSummary: DEFAULT_QUESTION_SUMMARY,
51
81
  });
52
82
 
53
83
  interface LoadedLayer {
@@ -123,5 +153,28 @@ function mergeLayers(found: readonly LoadedLayer[]): EffectiveConfig {
123
153
  extensions: Object.freeze(extensions),
124
154
  files: Object.freeze(found.map(({ layer }) => layer.file)),
125
155
  ...(profile === undefined ? {} : { profile }),
156
+ askUserSummary: mergeQuestionSummary(found),
157
+ });
158
+ }
159
+
160
+ /** Last-layer-wins per key, exactly like `profile`; it never concatenates. */
161
+ function mergeQuestionSummary(found: readonly LoadedLayer[]): QuestionSummaryConfig {
162
+ const merged = found.reduce<{
163
+ policy?: QuestionSummaryPolicy;
164
+ model?: string;
165
+ thinking?: ThinkingLevel;
166
+ }>((last, { layer }) => {
167
+ const summary = layer.document.askUser?.summary;
168
+ if (summary === undefined) return last;
169
+ return {
170
+ policy: summary.policy ?? last.policy,
171
+ model: summary.model ?? last.model,
172
+ thinking: summary.thinking ?? last.thinking,
173
+ };
174
+ }, {});
175
+ return Object.freeze({
176
+ policy: merged.policy ?? DEFAULT_QUESTION_SUMMARY.policy,
177
+ ...(merged.model === undefined ? {} : { model: merged.model }),
178
+ thinking: merged.thinking ?? DEFAULT_QUESTION_SUMMARY.thinking,
126
179
  });
127
180
  }
@@ -16,8 +16,12 @@ export type { YaagConfigDocument } from "./config-schema.ts";
16
16
  export {
17
17
  type ConfigExtension,
18
18
  type ConfigLayerName,
19
+ DEFAULT_QUESTION_SUMMARY,
19
20
  type EffectiveConfig,
20
21
  type EffectiveConfigRequest,
21
22
  EMPTY_EFFECTIVE_CONFIG,
22
23
  loadEffectiveConfig,
24
+ type QuestionSummaryConfig,
25
+ type QuestionSummaryPolicy,
26
+ questionSummaryOf,
23
27
  } from "./effective-config.ts";
@@ -84,6 +84,15 @@ export interface AgentPolicy {
84
84
  readonly skills?: readonly string[];
85
85
  /** Skill-name denylist discovered from pi and applied last (ADR-0026). */
86
86
  readonly disallowedSkills?: readonly string[];
87
+ /**
88
+ * Loads yaag's injected `request_user_input` tool, so this Agent can ask the
89
+ * human one question and park its turn on the answer (ADR-0023).
90
+ *
91
+ * The capability is never widened and never dropped in silence: a `tools`
92
+ * allowlist that omits the tool, or a `disallowedTools` that denies it, fails
93
+ * the spawn before the Agent starts.
94
+ */
95
+ readonly canAskUser?: boolean;
87
96
  /**
88
97
  * Ask options applied to every Ask on this Agent unless overridden per call.
89
98
  * They never enter the recorded spawn options: the Ask hash sees them through
@@ -0,0 +1,33 @@
1
+ /**
2
+ * The Catalog Resolve author contract (ADR-0053): what `$yaag.<scope>.importAgent`
3
+ * returns, and the options `createYaagGlobal` takes.
4
+ *
5
+ * Type-only. It is the one file in this directory that names a type from
6
+ * outside it: `SpawnableDefinition` is the union of the two Definition shapes,
7
+ * and both already sit in the emitted author tree (ADR-0045).
8
+ */
9
+ import type { AgentDefinition } from "../agent/define-agent.ts";
10
+ import type { ProfiledDefinition } from "../profile/use-profile.ts";
11
+
12
+ /** An Agent Definition or a Profiled Definition: what a Catalog Resolve gives back. */
13
+ export type SpawnableDefinition = AgentDefinition | ProfiledDefinition;
14
+
15
+ /** One Catalog scope, global or project. */
16
+ export interface CatalogScope {
17
+ /** Resolves the Spawnable Definition registered under `name` in this scope. */
18
+ importAgent(name: string): Promise<SpawnableDefinition>;
19
+ }
20
+
21
+ /** The `$yaag` global an Orchestration Program reads. */
22
+ export interface YaagGlobal {
23
+ readonly global: CatalogScope;
24
+ readonly project: CatalogScope;
25
+ }
26
+
27
+ /** What `createYaagGlobal` needs to build the two scopes. */
28
+ export interface YaagGlobalOptions {
29
+ /** Absolute path of the global Registry File. The file may not exist. */
30
+ readonly globalRegistryPath: string;
31
+ /** Absolute path of the project Registry File. `undefined` when the Run has no Program Directory. */
32
+ readonly projectRegistryPath: string | undefined;
33
+ }
@@ -55,15 +55,18 @@ export type YaagErrorCode =
55
55
  | "ARGS_INVALID" // arguments failed schema validation before the Run started
56
56
  | "CONFIG_INVALID" // a config layer is missing, unparsable, or violates the schema
57
57
  | "OPTIONS_CONFLICT" // incompatible Run options were supplied
58
+ | "PAUSE_REFUSED" // two pause questions claim one id (ADR-0022)
58
59
  | "RECORD_PATH_UNUSABLE" // the --record directory could not be created at Run start
59
60
  | "REPLAY_DIVERGED" // replayed program differed from its Cassette
60
- | "RESUME_REFUSED" // resume metadata is absent or the recorded tree moved
61
+ | "RESUME_REFUSED" // resume metadata is absent, the recorded tree moved, or an answer is unknown or conflicting (ADR-0022/0023)
61
62
  | "PROFILE_NOT_FOUND" // a selected Profile is not declared by the program (ADR-0052)
62
63
  | "PROFILE_REQUIRED" // a Profiled Definition was spawned by a program that declares no Profiles
63
64
  | "ROLE_NOT_FOUND" // a factory read a Role the program does not declare
64
65
  | "RUN_CLOSED" // spawn or Ask requested after the Run began settling
65
- | "RUN_PAUSED" // an external pause drain settled the Run (ADR-0024)
66
66
  | "RUN_STOPPED" // the Run's abort signal fired before the program completed
67
67
  | "WORKTREE_REFUSED" // base cwd is not a clean Git repository
68
68
  | "MODEL_RESOLUTION_FAILED" // the resolver gave up, or every candidate failed; carries the history
69
+ | "CATALOG_ENTRY_NOT_FOUND" // no Registry File, no Program Directory, or no entry with that name (ADR-0053)
70
+ | "CATALOG_ENTRY_AMBIGUOUS" // two or more registry entries carry that name
71
+ | "CATALOG_ENTRY_UNRESOLVABLE" // the entry exists but did not yield a Spawnable Definition
69
72
  | "SPAWN_FAILED"; // the spawn was refused, e.g. a guarded system prompt, a broken tool contract or a startup timeout
@@ -3,11 +3,19 @@
3
3
  * Program author reads (ADR-0045).
4
4
  *
5
5
  * Every file here is type-only and imports nothing outside this directory
6
- * except `typebox`. That keeps the declaration tree a workspace gets small.
7
- * Files inside this directory import each other directly.
6
+ * except `typebox`, with one exception: `catalog-resolve.ts` names
7
+ * `AgentDefinition` and `ProfiledDefinition`, type-only, because both already
8
+ * sit in the emitted author tree. That keeps the declaration tree a workspace
9
+ * gets small. Files inside this directory import each other directly.
8
10
  */
9
11
  export type { AgentPolicy } from "./agent-policy.ts";
10
12
  export type { AgentProgress, CompactionResult, TokenBreakdown } from "./agent-report.ts";
13
+ export type {
14
+ CatalogScope,
15
+ SpawnableDefinition,
16
+ YaagGlobal,
17
+ YaagGlobalOptions,
18
+ } from "./catalog-resolve.ts";
11
19
  export type {
12
20
  AskInvalidOutputOutcome,
13
21
  AskLimitKind,
@@ -16,10 +16,12 @@ export {
16
16
  } from "./control-commands.ts";
17
17
  export {
18
18
  type AskInFlight,
19
+ type AskSettled,
19
20
  type DrainableAgent,
20
21
  drainForPause,
21
22
  type PauseDrainOptions,
22
23
  type PauseDrainResult,
24
+ type PauseGrace,
23
25
  } from "./pause-drain.ts";
24
26
  export {
25
27
  type ControlRequest,
@@ -1,16 +1,29 @@
1
1
  /**
2
- * The bounded pause drain (ADR-0024): wrap-up steer, then abort at the
2
+ * The pause drain, in two grace modes.
3
+ *
4
+ * `bounded` is the external pause of ADR-0024: wrap-up steer, then abort at the
3
5
  * deadline, then force-close through the Run's reap ladder.
4
6
  *
5
- * The function takes structural inputs only — Agent handles, a deadline, an
6
- * admission closer and a stop promise — so a program-initiated pause can call
7
- * it unchanged.
7
+ * `natural` is the program pause of ADR-0022: the program asked its user a
8
+ * question, so nothing is cut short. The drain sends no wrap-up steer, sets no
9
+ * timer, and waits for quiescence. The honest consequence: one sibling Ask
10
+ * that never returns holds the drain open forever. ADR-0022 accepts this — a
11
+ * stop is the way out, and a stop always wins.
12
+ *
13
+ * The function takes structural inputs only — Agent handles, a grace, an
14
+ * admission closer and a stop promise — so both callers use it unchanged.
8
15
  *
9
16
  * The drain deliberately does not trip `AskLimit`, so an externally paused Ask
10
17
  * never misreports `ASK_LIMIT`. A soft budget that trips at the same moment
11
18
  * simply sends its own steer first; both paths converge on the same reap ladder.
12
19
  */
13
20
 
21
+ /** How one Ask left flight. It never rejects; a failed Ask carries its error. */
22
+ export interface AskSettled {
23
+ /** What the Ask rejected with, or absent when it resolved. */
24
+ readonly error?: unknown;
25
+ }
26
+
14
27
  /** Controls of one Ask in flight, as the drain sees them; a Handle never exposes these. */
15
28
  export interface AskInFlight {
16
29
  readonly agent: string;
@@ -23,7 +36,20 @@ export interface AskInFlight {
23
36
  /** Aborts the turn. Never throws, and the drain never waits for its answer. */
24
37
  abort(): Promise<boolean>;
25
38
  /** Resolves when the Ask leaves flight, whatever its outcome. Never rejects. */
26
- readonly settled: Promise<void>;
39
+ readonly settled: Promise<AskSettled>;
40
+ /**
41
+ * The turn is parked on `request_user_input` (ADR-0023). The drain never
42
+ * waits for it, never steers it, never aborts it, and never names it cut
43
+ * short.
44
+ */
45
+ readonly parked?: boolean;
46
+ /**
47
+ * Resolves when this Ask parks, also after the drain read its wait set.
48
+ * ADR-0023 ends the drain at quiescence, where every Ask has settled **or**
49
+ * parked, so an Ask that parks later must leave the wait the same way a
50
+ * settled one does.
51
+ */
52
+ readonly parkedSignal?: Promise<void>;
27
53
  }
28
54
 
29
55
  /** What the drain needs from one Agent; `Agent` satisfies it structurally. */
@@ -32,11 +58,16 @@ export interface DrainableAgent {
32
58
  readonly askInFlight: AskInFlight | null;
33
59
  }
34
60
 
61
+ /** How long the drain waits, and whether it steers at all. */
62
+ export type PauseGrace =
63
+ | { readonly kind: "bounded"; readonly deadlineMs: number }
64
+ | { readonly kind: "natural" };
65
+
35
66
  export interface PauseDrainOptions {
36
67
  /** Live reference to the Run's Agent list; read at drain start. */
37
68
  readonly agents: readonly DrainableAgent[];
38
- /** Wall-clock grace before the abort (ADR-0024). */
39
- readonly deadlineMs: number;
69
+ /** Wall-clock grace before the abort (ADR-0024), or the natural wait (ADR-0022). */
70
+ readonly grace: PauseGrace;
40
71
  /** Closes Ask and spawn admission before the first steer. */
41
72
  readonly closeAdmission: () => void;
42
73
  /** A stop request; it skips the remaining grace and takes the outcome. */
@@ -45,7 +76,12 @@ export interface PauseDrainOptions {
45
76
 
46
77
  /** How one drain ended: paused, naming every Ask it cut short, or overridden by a stop. */
47
78
  export type PauseDrainResult =
48
- | { readonly kind: "paused"; readonly cutShort: readonly string[] }
79
+ | {
80
+ readonly kind: "paused";
81
+ readonly cutShort: readonly string[];
82
+ /** One line per Ask that rejected during the drain; never an outcome. */
83
+ readonly warnings: readonly string[];
84
+ }
49
85
  | { readonly kind: "stopped" };
50
86
 
51
87
  /**
@@ -56,19 +92,35 @@ export type PauseDrainResult =
56
92
  */
57
93
  export async function drainForPause(options: PauseDrainOptions): Promise<PauseDrainResult> {
58
94
  options.closeAdmission();
59
- const inFlight = options.agents
60
- .map((agent) => agent.askInFlight)
61
- .filter((ask): ask is AskInFlight => ask !== null);
62
- if (inFlight.length === 0) return { kind: "paused", cutShort: [] };
95
+ const inFlight = waitable(options.agents);
96
+ if (inFlight.length === 0) return { kind: "paused", cutShort: [], warnings: [] };
97
+ const warnings: string[] = [];
98
+ for (const ask of inFlight) {
99
+ void ask.settled.then((settled) => {
100
+ if (settled.error !== undefined) warnings.push(warningLine(ask.agent, settled.error));
101
+ });
102
+ }
63
103
  // The grace starts before the first steer, so an Agent that never answers a
64
104
  // command cannot hold the drain open past the deadline, and a stop always
65
105
  // lands. A refused steer is ignored on purpose: the deadline bounds it too.
66
106
  const grace = raceGrace(inFlight, options);
67
- for (const ask of inFlight) void ask.wrapUp();
107
+ if (options.grace.kind === "bounded") for (const ask of inFlight) void ask.wrapUp();
68
108
  const outcome = await grace;
69
109
  if (outcome === "stopped") return { kind: "stopped" };
70
- if (outcome === "settled") return { kind: "paused", cutShort: [] };
71
- return { kind: "paused", cutShort: abortRemaining(options.agents) };
110
+ if (outcome === "settled") return { kind: "paused", cutShort: [], warnings };
111
+ return { kind: "paused", cutShort: abortRemaining(options.agents), warnings };
112
+ }
113
+
114
+ /** Every Ask the drain waits for: in flight, and not parked on a user question. */
115
+ function waitable(agents: readonly DrainableAgent[]): readonly AskInFlight[] {
116
+ return agents
117
+ .map((agent) => agent.askInFlight)
118
+ .filter((ask): ask is AskInFlight => ask !== null && ask.parked !== true);
119
+ }
120
+
121
+ function warningLine(agent: string, error: unknown): string {
122
+ const message = error instanceof Error ? error.message : String(error);
123
+ return `${agent}: Ask rejected during the pause drain: ${message}`;
72
124
  }
73
125
 
74
126
  type GraceOutcome = "settled" | "deadline" | "stopped";
@@ -79,13 +131,20 @@ function raceGrace(
79
131
  options: PauseDrainOptions,
80
132
  ): Promise<GraceOutcome> {
81
133
  let timer: ReturnType<typeof setTimeout> | undefined;
82
- const deadline = new Promise<GraceOutcome>((resolve) => {
83
- timer = setTimeout(() => resolve("deadline"), options.deadlineMs);
84
- });
85
- const settled = Promise.all(inFlight.map((ask) => ask.settled)).then<GraceOutcome>(
86
- () => "settled",
134
+ // A parked Ask counts as quiescent: its own promise settles only at the reap,
135
+ // and the natural grace has no deadline that could end the wait (ADR-0023).
136
+ const quiet = inFlight.map((ask) =>
137
+ ask.parkedSignal === undefined
138
+ ? ask.settled
139
+ : Promise.race([ask.settled, ask.parkedSignal.then(() => ({}) as AskSettled)]),
87
140
  );
141
+ const settled = Promise.all(quiet).then<GraceOutcome>(() => "settled");
88
142
  const stopped = options.stopped.then<GraceOutcome>(() => "stopped");
143
+ const grace = options.grace;
144
+ if (grace.kind === "natural") return Promise.race([settled, stopped]);
145
+ const deadline = new Promise<GraceOutcome>((resolve) => {
146
+ timer = setTimeout(() => resolve("deadline"), grace.deadlineMs);
147
+ });
89
148
  return Promise.race([settled, deadline, stopped]).finally(() => {
90
149
  clearTimeout(timer);
91
150
  });
@@ -94,12 +153,10 @@ function raceGrace(
94
153
  /**
95
154
  * Aborts every Ask still in flight and names its Agent as cut short. The
96
155
  * answers are deliberately not awaited: an Agent that swallows the abort must
97
- * not hold the Run away from its reap ladder.
156
+ * not hold the Run away from its reap ladder. A parked Ask is exempt.
98
157
  */
99
158
  function abortRemaining(agents: readonly DrainableAgent[]): readonly string[] {
100
- const remaining = agents
101
- .map((agent) => agent.askInFlight)
102
- .filter((ask): ask is AskInFlight => ask !== null);
159
+ const remaining = waitable(agents);
103
160
  for (const ask of remaining) void ask.abort();
104
161
  return remaining.map((ask) => ask.agent);
105
162
  }
package/src/errors.ts CHANGED
@@ -22,7 +22,12 @@ export type {
22
22
  YaagErrorCode,
23
23
  } from "./contract/index.ts";
24
24
 
25
- /** The single error class of the runtime (ADR-0003). */
25
+ /**
26
+ * The single error class of the runtime (ADR-0003).
27
+ *
28
+ * The fifth constructor parameter `cause` goes to `Error.prototype.cause`, so
29
+ * a wrapped failure keeps its origin.
30
+ */
26
31
  export class YaagError extends Error {
27
32
  readonly code: YaagErrorCode;
28
33
  /** Agent name, when the error concerns one. */
@@ -57,8 +62,9 @@ export class YaagError extends Error {
57
62
  | AskStalledOutcome
58
63
  | AskInvalidOutputOutcome
59
64
  | ModelResolutionOutcome,
65
+ cause?: unknown,
60
66
  ) {
61
- super(message);
67
+ super(message, { cause });
62
68
  this.name = "YaagError";
63
69
  this.code = code;
64
70
  if (agent !== undefined) this.agent = agent;
package/src/events.ts CHANGED
@@ -261,6 +261,12 @@ export type LifecycleEventBody =
261
261
  * failed. Carries the publication error text. Absent on every other path.
262
262
  */
263
263
  readonly checkpointLost?: string;
264
+ /**
265
+ * What went wrong beside the outcome: a sibling Ask that rejected during
266
+ * a pause drain, and (ticket 04) a summarizer failure. It never changes
267
+ * `outcome`. Absent when the Run has nothing to warn about.
268
+ */
269
+ readonly warnings?: readonly string[];
264
270
  /**
265
271
  * Path of the Checkpoint this Run published, present only when the Run
266
272
  * paused or stopped and publication succeeded (ADR-0054). The Reattach
package/src/index.ts CHANGED
@@ -1,5 +1,10 @@
1
1
  export type { AgentConfig, AgentDefinition } from "./agent/index.ts";
2
- export { agentDefinitionConfig, defineAgent, isAgentDefinition } from "./agent/index.ts";
2
+ export {
3
+ agentDefinitionConfig,
4
+ defineAgent,
5
+ isAgentDefinition,
6
+ isSpawnableDefinition,
7
+ } from "./agent/index.ts";
3
8
  export type {
4
9
  Cassette,
5
10
  CassetteAgent,
@@ -48,6 +53,7 @@ export {
48
53
  AGENT_DESCRIBE_TRANSCRIPT,
49
54
  agentDescribeArgv,
50
55
  CATALOG_FIXTURE,
56
+ createYaagGlobal,
51
57
  describedAgent,
52
58
  encodeAgentDescribe,
53
59
  filterCatalog,
@@ -159,12 +165,22 @@ export {
159
165
  } from "./profile/index.ts";
160
166
  export { prompt, promptGist } from "./prompt/index.ts";
161
167
  export type {
168
+ AskUserOptions,
162
169
  OrchestrationProgram,
163
170
  ProgramDefinition,
171
+ Question,
164
172
  RunContext,
165
173
  RunOptions,
174
+ RunResult,
175
+ } from "./run/index.ts";
176
+ export {
177
+ defineRun,
178
+ executeRun,
179
+ isOrchestrationProgram,
180
+ isPauseSignal,
181
+ programDefinition,
182
+ RunPauseSignal,
166
183
  } from "./run/index.ts";
167
- export { defineRun, executeRun, isOrchestrationProgram, programDefinition } from "./run/index.ts";
168
184
  export type {
169
185
  AgentInfo,
170
186
  AgentState,
@@ -30,4 +30,4 @@ export {
30
30
  resolveModel,
31
31
  retryOnModelFailure,
32
32
  } from "./resolution-loop.ts";
33
- export { isThinkingLevel, type ThinkingLevel } from "./thinking-level.ts";
33
+ export { isThinkingLevel, THINKING_LEVELS, type ThinkingLevel } from "./thinking-level.ts";
package/src/public-api.ts CHANGED
@@ -12,6 +12,12 @@
12
12
 
13
13
  export type { AgentConfig, AgentDefinition } from "./agent/define-agent.ts";
14
14
  export { defineAgent } from "./agent/define-agent.ts";
15
+ export type {
16
+ CatalogScope,
17
+ SpawnableDefinition,
18
+ YaagGlobal,
19
+ YaagGlobalOptions,
20
+ } from "./contract/catalog-resolve.ts";
15
21
  export type {
16
22
  AgentPolicy,
17
23
  AskOptions,
@@ -53,6 +59,7 @@ export { isProfiledDefinition, useProfile } from "./profile/use-profile.ts";
53
59
  export { prompt } from "./prompt/prompt.ts";
54
60
  export type { OrchestrationProgram, ProgramDefinition } from "./run/define-run.ts";
55
61
  export { defineRun } from "./run/define-run.ts";
62
+ export type { AskUserOptions, Question } from "./run/questions.ts";
56
63
  export type { RunContext } from "./run/run-context.ts";
57
64
  export type { YaagSystemPromptOptions } from "./system-prompt/agent-system-prompt.ts";
58
65
  export { yaagSystemPrompt } from "./system-prompt/agent-system-prompt.ts";
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Public surface of the `question-summary/` module: the fork summarizer that
3
+ * fills `summary` on an Agent Question (ADR-0022). It is named for the glossary
4
+ * term, and stays apart from `summary/`, which owns the Run Summary fold.
5
+ * Files inside this directory import each other directly.
6
+ */
7
+
8
+ export {
9
+ prepareSessionCopy,
10
+ type SessionCopy,
11
+ type SessionCopyRequest,
12
+ SYNTHETIC_TOOL_RESULT_TEXT,
13
+ } from "./session-copy.ts";
14
+ export {
15
+ type InternalOpen,
16
+ type ParkedAgent,
17
+ type QuestionSummaryResult,
18
+ SUMMARIZER_PROMPT,
19
+ type SummarizeQuestionsRequest,
20
+ summarizeQuestions,
21
+ } from "./summarize-question.ts";
22
+ export { summarizes } from "./summary-policy.ts";