@yaag/runtime 0.25.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 (56) 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 +2 -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 +21 -2
  8. package/src/ask/ask-exchange-options.ts +5 -0
  9. package/src/ask/ask-exchange.ts +67 -2
  10. package/src/ask/ask-settlement.ts +8 -0
  11. package/src/ask/idle-watch.ts +12 -2
  12. package/src/ask/stall-watchdog.ts +13 -3
  13. package/src/ask-contract/ask-limit.ts +24 -6
  14. package/src/ask-contract/index.ts +8 -0
  15. package/src/ask-contract/request-user-input-extension.ts +105 -0
  16. package/src/ask-contract/request-user-input.ts +58 -0
  17. package/src/cassette/cassette-loader.ts +50 -1
  18. package/src/cassette/cassette-schema.ts +27 -0
  19. package/src/cassette/cassette.ts +49 -0
  20. package/src/cassette/index.ts +10 -1
  21. package/src/cassette/replay-divergence.ts +5 -0
  22. package/src/cassette/resume-preconditions.ts +10 -0
  23. package/src/cassette/resume-transport.ts +111 -6
  24. package/src/cassette/run-checkpoint.ts +52 -3
  25. package/src/cassette/session-answer.ts +163 -0
  26. package/src/catalog/registry-reader.ts +1 -1
  27. package/src/config/config-schema.ts +33 -0
  28. package/src/config/effective-config.ts +53 -0
  29. package/src/config/index.ts +4 -0
  30. package/src/contract/agent-policy.ts +9 -0
  31. package/src/contract/error-codes.ts +2 -2
  32. package/src/control/index.ts +2 -0
  33. package/src/control/pause-drain.ts +81 -24
  34. package/src/events.ts +6 -0
  35. package/src/index.ts +11 -1
  36. package/src/model/index.ts +1 -1
  37. package/src/public-api.ts +1 -0
  38. package/src/question-summary/index.ts +22 -0
  39. package/src/question-summary/session-copy.ts +169 -0
  40. package/src/question-summary/summarize-question.ts +129 -0
  41. package/src/question-summary/summary-policy.ts +25 -0
  42. package/src/run/agent-questions.ts +75 -0
  43. package/src/run/answers.ts +70 -0
  44. package/src/run/index.ts +5 -0
  45. package/src/run/pause-questions.ts +98 -0
  46. package/src/run/pause-signal.ts +32 -0
  47. package/src/run/question-id.ts +18 -0
  48. package/src/run/questions.ts +31 -0
  49. package/src/run/run-context.ts +18 -0
  50. package/src/run/run-result.ts +21 -0
  51. package/src/run/run-settlement.ts +36 -4
  52. package/src/run/run.ts +119 -20
  53. package/src/system-prompt/agent-system-prompt.ts +1 -1
  54. package/src/transport/pi-state.ts +21 -4
  55. package/src/transport/tool-probe.ts +4 -0
  56. package/src/transport/transport.ts +26 -0
package/package.json CHANGED
@@ -1,12 +1,11 @@
1
1
  {
2
2
  "name": "@yaag/runtime",
3
- "version": "0.25.0",
3
+ "version": "0.26.0",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
7
7
  "files": [
8
8
  "src",
9
- "!src/**/*.test.ts",
10
9
  "!src/fixtures"
11
10
  ],
12
11
  "type": "module",
@@ -16,7 +15,7 @@
16
15
  },
17
16
  "scripts": {
18
17
  "typecheck": "tsc --noEmit",
19
- "test": "bun test --timeout 30000 src",
18
+ "test": "bun test --timeout 30000 ./test",
20
19
  "test:e2e": "bun test --timeout 30000 e2e"
21
20
  },
22
21
  "dependencies": {
@@ -2,10 +2,11 @@ import type { Static, TSchema } from "typebox";
2
2
  import type { EffectiveAskOptions } from "../ask/index.ts";
3
3
  import { exchangeAsk } from "../ask/index.ts";
4
4
  import { REPORT_RESULT_WRAP_UP, ReportResultTool, wrapUpMessage } from "../ask-contract/index.ts";
5
- import type { AskAdmission, AskInFlight } from "../control/index.ts";
5
+ import type { AskAdmission, AskInFlight, AskSettled } from "../control/index.ts";
6
6
  import { agentError } from "../error-factories.ts";
7
7
  import type { EventSink } from "../events.ts";
8
8
  import type { ModelErrorHistory, ModelResolution } from "../model/index.ts";
9
+ import type { AgentQuestions } from "../run/index.ts";
9
10
  import type {
10
11
  AgentStats,
11
12
  AgentTransport,
@@ -62,6 +63,8 @@ export interface AgentOptions {
62
63
  readonly stallProbeSettleMs?: number;
63
64
  /** Run-scoped Ask gate; a closed gate refuses every later Ask (ADR-0024). */
64
65
  readonly askAdmission?: AskAdmission;
66
+ /** Run-scoped sink of Agent questions; absent when this Agent cannot ask (ADR-0023). */
67
+ readonly questions?: AgentQuestions;
65
68
  }
66
69
 
67
70
  /** One Agent as an Orchestration Program sees it. Lives above the transport seam. */
@@ -87,6 +90,7 @@ export class Agent implements Handle {
87
90
  readonly #sessionFile: string | undefined;
88
91
  readonly #fork: ForkSpawner | undefined;
89
92
  readonly #askAdmission: AskAdmission | undefined;
93
+ readonly #questions: AgentQuestions | undefined;
90
94
  #busy = false;
91
95
  #inFlight: AskInFlight | null = null;
92
96
  #incomplete = false;
@@ -113,6 +117,7 @@ export class Agent implements Handle {
113
117
  this.#idleAbortSettleMs = options.idleAbortSettleMs;
114
118
  this.#stallProbeSettleMs = options.stallProbeSettleMs;
115
119
  this.#askAdmission = options.askAdmission;
120
+ this.#questions = options.questions;
116
121
  this.#usage = new AgentUsage((snapshot) =>
117
122
  this.#emit({ type: "agent_usage", agent: this.name, ...snapshot }),
118
123
  );
@@ -124,6 +129,15 @@ export class Agent implements Handle {
124
129
  return this.#model;
125
130
  }
126
131
 
132
+ /**
133
+ * pi's session file for this Agent; the fork summarizer copies it (ADR-0022).
134
+ * Absent during playback. `Handle` does not carry it: this is Run machinery,
135
+ * not an author surface.
136
+ */
137
+ get sessionFile(): string | undefined {
138
+ return this.#sessionFile;
139
+ }
140
+
127
141
  async ask<Schema extends TSchema>(
128
142
  prompt: string,
129
143
  options: StructuredAskOptions<Schema>,
@@ -146,6 +160,8 @@ export class Agent implements Handle {
146
160
  const inFlight = this.#openInFlight(effective);
147
161
  this.#inFlight = inFlight;
148
162
  const index = this.#askIndex++;
163
+ // Kept, so the drain sees why an Ask left flight and can warn about it.
164
+ let failure: unknown;
149
165
  try {
150
166
  return await exchangeAsk({
151
167
  agent: this.name,
@@ -175,11 +191,17 @@ export class Agent implements Handle {
175
191
  askLimitGraceMs: this.#askLimitGraceMs,
176
192
  idleAbortSettleMs: this.#idleAbortSettleMs,
177
193
  stallProbeSettleMs: this.#stallProbeSettleMs,
194
+ ...(this.#questions === undefined
195
+ ? {}
196
+ : { questions: this.#questions, park: () => inFlight.park() }),
178
197
  });
198
+ } catch (error) {
199
+ failure = error;
200
+ throw error;
179
201
  } finally {
180
202
  this.#busy = false;
181
203
  this.#inFlight = null;
182
- inFlight.settle();
204
+ inFlight.settle(failure);
183
205
  // A failed Ask settles the conversation as much as a successful one: the
184
206
  // fork point is the boundary, not the outcome.
185
207
  this.#settledAsks += 1;
@@ -198,10 +220,20 @@ export class Agent implements Handle {
198
220
  * Builds the drain's controls of one Ask. Both commands report a refusal as
199
221
  * false and never throw, so a dead Agent cannot throw into the drain.
200
222
  */
201
- #openInFlight(ask: EffectiveAskOptions): AskInFlight & { settle(): void } {
202
- let settle: () => void = () => {};
203
- const settled = new Promise<void>((resolve) => {
204
- settle = resolve;
223
+ #openInFlight(
224
+ ask: EffectiveAskOptions,
225
+ ): AskInFlight & { settle(error?: unknown): void; park(): void } {
226
+ let settle: (error?: unknown) => void = () => {};
227
+ // A getter, not a snapshot: the drain reads `parked` at its start and again
228
+ // when it aborts what remains, and an Ask may park between the two. The
229
+ // signal covers the drain that is already waiting (ADR-0023).
230
+ let parked = false;
231
+ let raiseParked: () => void = () => {};
232
+ const parkedSignal = new Promise<void>((resolve) => {
233
+ raiseParked = resolve;
234
+ });
235
+ const settled = new Promise<AskSettled>((resolve) => {
236
+ settle = (error?: unknown) => resolve(error === undefined ? {} : { error });
205
237
  });
206
238
  // A structured Ask keeps reporting through report_result, so its wrap-up
207
239
  // carries the same suffix the soft-budget path uses (ADR-0032). Legacy
@@ -218,6 +250,14 @@ export class Agent implements Handle {
218
250
  agent: this.name,
219
251
  settled,
220
252
  settle,
253
+ get parked(): boolean {
254
+ return parked;
255
+ },
256
+ parkedSignal,
257
+ park: (): void => {
258
+ parked = true;
259
+ raiseParked();
260
+ },
221
261
  wrapUp: () => send({ type: "steer", message: wrapUpMessage(ask, suffix) }),
222
262
  abort: () => send({ type: "abort" }),
223
263
  };
@@ -0,0 +1,36 @@
1
+ /**
2
+ * The fail-fast guard of the `canAskUser` capability (ADR-0023).
3
+ *
4
+ * The `report_result` precedent is deliberately inverted here: that allowlist
5
+ * widens itself in silence, this one does not. An Agent that may ask its human
6
+ * and whose tool flags remove the tool has a contradiction in its policy, so
7
+ * the spawn fails rather than losing the capability without a word.
8
+ */
9
+ import { REQUEST_USER_INPUT_TOOL_NAME } from "../ask-contract/index.ts";
10
+ import { YaagError } from "../errors.ts";
11
+
12
+ /** The tool flags of one spawn, as this guard reads them. */
13
+ export interface AskUserToolFlags {
14
+ readonly canAskUser?: boolean;
15
+ readonly tools?: readonly string[];
16
+ readonly disallowedTools?: readonly string[];
17
+ }
18
+
19
+ /** Rejects a spawn whose tool flags remove the tool `canAskUser` needs. */
20
+ export function assertAskUserTools(agent: string, options: AskUserToolFlags): void {
21
+ if (options.canAskUser !== true) return;
22
+ if (options.disallowedTools?.includes(REQUEST_USER_INPUT_TOOL_NAME) === true) {
23
+ throw refuse(agent, "and disallowedTools denies it");
24
+ }
25
+ if (options.tools !== undefined && !options.tools.includes(REQUEST_USER_INPUT_TOOL_NAME)) {
26
+ throw refuse(agent, "and the tools allowlist omits it");
27
+ }
28
+ }
29
+
30
+ function refuse(agent: string, cause: string): YaagError {
31
+ return new YaagError(
32
+ "SPAWN_FAILED",
33
+ `agent "${agent}": canAskUser needs the tool "${REQUEST_USER_INPUT_TOOL_NAME}", ${cause}`,
34
+ agent,
35
+ );
36
+ }
@@ -13,5 +13,6 @@ export {
13
13
  isAgentDefinition,
14
14
  } from "./define-agent.ts";
15
15
  export { type ForkSource, type ForkSpawner, forkRequest } from "./fork.ts";
16
- export { makeSpawn } from "./spawn.ts";
16
+ export { makeSpawn, type SpawnDependencies, type SpawnGate } from "./spawn.ts";
17
+ export type { OpenAgentRequest } from "./spawn-open.ts";
17
18
  export { isSpawnableDefinition } from "./spawnable-definition.ts";
@@ -13,9 +13,10 @@ import type {
13
13
  TransportStartup,
14
14
  WorktreeResolution,
15
15
  } from "../transport/index.ts";
16
- import type { AskOptions, Handle, ResolvedSpawnOptions, SpawnOptions } from "../types.ts";
16
+ import type { AskOptions, ResolvedSpawnOptions, SpawnOptions } from "../types.ts";
17
17
  import { Agent } from "./agent.ts";
18
18
  import { uniqueAgentName } from "./agent-names.ts";
19
+ import { assertAskUserTools } from "./ask-user-capability.ts";
19
20
  import type { ForkIdentity, ForkSpawner } from "./fork.ts";
20
21
  import type { SpawnDependencies } from "./spawn.ts";
21
22
  import { resolveSpawnExtensions } from "./spawn-extensions.ts";
@@ -48,6 +49,11 @@ export interface OpenAgentRequest {
48
49
  readonly profile?: string;
49
50
  /** Roles the factory read, in order, duplicates kept; `[]` for none. */
50
51
  readonly role?: readonly string[];
52
+ /**
53
+ * An existing pi session this Agent opens on (`pi --session`). Never spawn
54
+ * identity: the path is machine-specific (ADR-0022).
55
+ */
56
+ readonly sessionFile?: string;
51
57
  }
52
58
 
53
59
  /** What the open path needs beyond the Run's spawn dependencies. */
@@ -65,11 +71,12 @@ export interface OpenAgentContext extends SpawnDependencies {
65
71
  * A fork walks this very path, so the Tool Contract probe, Model Resolution,
66
72
  * the worktree wrapper and the Cassette identity cannot drift between a spawn
67
73
  * and a fork (ADR-0044).
74
+ *
75
+ * It resolves with the concrete `Agent`, not with the author-facing `Handle`:
76
+ * the Run's own machinery reaps what it opens, and `close()` lives below the
77
+ * author surface (ADR-0022).
68
78
  */
69
- export async function openAgent(
70
- deps: OpenAgentContext,
71
- request: OpenAgentRequest,
72
- ): Promise<Handle> {
79
+ export async function openAgent(deps: OpenAgentContext, request: OpenAgentRequest): Promise<Agent> {
73
80
  const cwd = resolve(request.spawnOptions.cwd ?? process.cwd());
74
81
  const name = uniqueAgentName(request.spawnOptions.name, deps.agents.length, deps.taken);
75
82
  // Resolved before any transport work, so a bad Parent Link costs nothing.
@@ -86,6 +93,9 @@ export async function openAgent(
86
93
  agent: { name, runName: deps.runName },
87
94
  ...(request.inheritedPrompt === true ? { inheritedPrompt: true } : {}),
88
95
  });
96
+ // A policy that both asks its human and removes the tool is a contradiction:
97
+ // it fails here, before any I/O and before the Agent starts (ADR-0023).
98
+ assertAskUserTools(name, rendered);
89
99
  // Extension paths do not vary per candidate, so a bad path fails once, generically.
90
100
  const extensions = await resolveSpawnExtensions({
91
101
  configExtensions: deps.configExtensions,
@@ -133,6 +143,7 @@ export async function openAgent(
133
143
  ...forkFields,
134
144
  ...(parent === undefined ? {} : { parent }),
135
145
  sessionDir: deps.sessionDir,
146
+ ...(request.sessionFile === undefined ? {} : { sessionFile: request.sessionFile }),
136
147
  }),
137
148
  spawnOptions: settled,
138
149
  };
@@ -149,6 +160,7 @@ export async function openAgent(
149
160
  ...forkFields,
150
161
  ...(parent === undefined ? {} : { parent }),
151
162
  sessionDir: deps.sessionDir,
163
+ ...(request.sessionFile === undefined ? {} : { sessionFile: request.sessionFile }),
152
164
  }),
153
165
  );
154
166
  // A Cassette-backed spawn adopts the recorded resolved selection and skips
@@ -191,6 +203,10 @@ export async function openAgent(
191
203
  ...(sessionFile === undefined ? {} : { sessionFile }),
192
204
  fork: deps.forkSpawner,
193
205
  ...(deps.askAdmission === undefined ? {} : { askAdmission: deps.askAdmission }),
206
+ // Only an Agent that may ask gets the sink, so no other Ask can park.
207
+ ...(deps.questions === undefined || rendered.canAskUser !== true
208
+ ? {}
209
+ : { questions: deps.questions }),
194
210
  ...(request.askDefaults === undefined ? {} : { askDefaults: request.askDefaults }),
195
211
  ...(request.definitionName === undefined ? {} : { definitionName: request.definitionName }),
196
212
  });
@@ -242,6 +258,8 @@ interface OpenTransportOptions {
242
258
  readonly forkSession?: string;
243
259
  readonly worktreeFrom?: WorktreeResolution;
244
260
  readonly sessionDir: string | undefined;
261
+ /** An existing pi session to open on; never spawn identity (ADR-0022). */
262
+ readonly sessionFile?: string;
245
263
  }
246
264
 
247
265
  interface OpenedTransport {
@@ -271,6 +289,7 @@ async function openTransport(options: OpenTransportOptions): Promise<OpenedTrans
271
289
  ...(options.forkSession === undefined ? {} : { forkSession: options.forkSession }),
272
290
  ...(options.worktreeFrom === undefined ? {} : { worktreeFrom: options.worktreeFrom }),
273
291
  sessionDir: options.sessionDir,
292
+ ...(options.sessionFile === undefined ? {} : { sessionFile: options.sessionFile }),
274
293
  }),
275
294
  (report) => Object.assign(startup, report),
276
295
  );
@@ -1,3 +1,4 @@
1
+ import { REQUEST_USER_INPUT_PROTOCOL } from "../ask-contract/index.ts";
1
2
  import type { SystemPromptAgent } from "../contract/index.ts";
2
3
  import { YaagError } from "../errors.ts";
3
4
  import type { ModelSelection } from "../model/index.ts";
@@ -111,6 +112,12 @@ export interface OpenRequestOptions {
111
112
  readonly forkSession?: string;
112
113
  readonly worktreeFrom?: WorktreeResolution;
113
114
  readonly sessionDir: string | undefined;
115
+ /**
116
+ * An existing pi session to open on, translated to `pi --session <path>`.
117
+ * Never spawn identity: the path is machine-specific, exactly like
118
+ * `forkSession`. The fork summarizer opens on a copy this way (ADR-0022).
119
+ */
120
+ readonly sessionFile?: string;
114
121
  }
115
122
 
116
123
  /**
@@ -157,7 +164,11 @@ export function openRequest(options: OpenRequestOptions): OpenOptions {
157
164
  ...(model === undefined ? {} : { model }),
158
165
  systemPrompt:
159
166
  spawnOptions.systemPrompt ??
160
- yaagSystemPrompt({ agent: { name: options.name, runName: options.runName } }),
167
+ yaagSystemPrompt({
168
+ agent: { name: options.name, runName: options.runName },
169
+ // An Agent that may ask its human reads the audience line (ADR-0062).
170
+ ...(spawnOptions.canAskUser === true ? { audience: "user" as const } : {}),
171
+ }),
161
172
  ...(thinking === undefined ? {} : { thinking }),
162
173
  ...(spawnOptions.appendSystemPrompt === undefined
163
174
  ? {}
@@ -167,6 +178,11 @@ export function openRequest(options: OpenRequestOptions): OpenOptions {
167
178
  ...(spawnOptions.disallowedTools === undefined
168
179
  ? {}
169
180
  : { disallowedTools: spawnOptions.disallowedTools }),
181
+ // Both fields stay absent for an Agent that cannot ask, so every recorded
182
+ // spawn identity from before ADR-0023 is unchanged.
183
+ ...(spawnOptions.canAskUser === true
184
+ ? { canAskUser: true as const, askUserProtocol: REQUEST_USER_INPUT_PROTOCOL }
185
+ : {}),
170
186
  ...(spawnOptions.skills === undefined ? {} : { skills: spawnOptions.skills }),
171
187
  ...(spawnOptions.disallowedSkills === undefined
172
188
  ? {}
@@ -187,6 +203,7 @@ export function openRequest(options: OpenRequestOptions): OpenOptions {
187
203
  ...(options.worktreeFrom === undefined ? {} : { worktreeFrom: options.worktreeFrom }),
188
204
  ...(spawnOptions.worktree === true ? { worktree: true as const } : {}),
189
205
  ...(options.sessionDir === undefined ? {} : { sessionDir: options.sessionDir }),
206
+ ...(options.sessionFile === undefined ? {} : { sessionFile: options.sessionFile }),
190
207
  };
191
208
  }
192
209
 
@@ -4,14 +4,14 @@ import { YaagError } from "../errors.ts";
4
4
  import type { EventSink } from "../events.ts";
5
5
  import type { ActiveProfile, ProfiledDefinition } from "../profile/index.ts";
6
6
  import { isProfiledDefinition } from "../profile/index.ts";
7
- import type { RunContext } from "../run/index.ts";
7
+ import type { AgentQuestions, RunContext } from "../run/index.ts";
8
8
  import type { TransportFactory } from "../transport/index.ts";
9
9
  import type { Handle, SpawnOptions, SpawnOverrides } from "../types.ts";
10
10
  import type { Agent } from "./agent.ts";
11
11
  import { type AgentDefinition, isAgentDefinition } from "./define-agent.ts";
12
12
  import { type ForkSpawner, forkRequest } from "./fork.ts";
13
13
  import { resolveRequest } from "./spawn-definition-request.ts";
14
- import { type OpenAgentContext, openAgent } from "./spawn-open.ts";
14
+ import { type OpenAgentContext, type OpenAgentRequest, openAgent } from "./spawn-open.ts";
15
15
  import { profiledRequest } from "./spawn-profiled.ts";
16
16
 
17
17
  /** Dependencies for one Run's Agent-spawn gate. */
@@ -29,11 +29,22 @@ export interface SpawnDependencies {
29
29
  readonly profile?: ActiveProfile;
30
30
  /** Run-scoped Ask gate handed to every Agent this gate opens (ADR-0024). */
31
31
  readonly askAdmission?: AskAdmission;
32
+ /** Run-scoped sink of the questions an Agent asks its human (ADR-0023). */
33
+ readonly questions?: AgentQuestions;
32
34
  }
33
35
 
34
36
  /** A RunContext spawn function that can synchronously stop accepting new Agents. */
35
37
  export interface SpawnGate {
36
38
  readonly spawn: RunContext["spawn"];
39
+ /**
40
+ * Opens one Agent for the Run's own machinery, after the gate closed.
41
+ *
42
+ * The closed flag is ignored on purpose: the fork summarizer runs after
43
+ * settlement, when the author-facing gate must already refuse (ADR-0022).
44
+ * The opened Agent gets neither the Run's Ask admission — which is closed by
45
+ * then — nor its Agent-question sink, so it can neither be refused nor park.
46
+ */
47
+ readonly openInternal: (request: OpenAgentRequest) => Promise<Agent>;
37
48
  close(): void;
38
49
  }
39
50
 
@@ -65,6 +76,10 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
65
76
  return handle;
66
77
  };
67
78
  const context: OpenAgentContext = { ...deps, taken, forkSpawner };
79
+ // Same open path, minus the two Run-scoped gates: `askAdmission` and
80
+ // `questions` are dropped rather than overridden, so nothing can re-add them.
81
+ const { askAdmission: _askAdmission, questions: _questions, ...ungated } = deps;
82
+ const internalContext: OpenAgentContext = { ...ungated, taken, forkSpawner };
68
83
  const spawn: RunContext["spawn"] = async (
69
84
  definitionOrOptions: SpawnOptions | AgentDefinition | ProfiledDefinition = {},
70
85
  overrides?: SpawnOverrides,
@@ -82,6 +97,10 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
82
97
  };
83
98
  return {
84
99
  spawn,
100
+ // The concrete Agent, not a Handle: the Run reaps its own machinery itself,
101
+ // and `close()` lives below the author surface.
102
+ openInternal: (request: OpenAgentRequest): Promise<Agent> =>
103
+ openAgent(internalContext, request),
85
104
  close: (): void => {
86
105
  closed = true;
87
106
  },
@@ -1,6 +1,7 @@
1
1
  import type { ReportResultTool } from "../ask-contract/index.ts";
2
2
  import type { EventSink } from "../events.ts";
3
3
  import type { ModelErrorHistory, ModelResolution } from "../model/index.ts";
4
+ import type { AgentQuestions } from "../run/index.ts";
4
5
  import type { AgentTransport, Connection, Frame } from "../transport/index.ts";
5
6
  import type { ResolvedSpawnOptions } from "../types.ts";
6
7
  import type { EffectiveAskOptions } from "./ask-hash.ts";
@@ -46,4 +47,8 @@ export interface AskExchangeOptions {
46
47
  readonly idleAbortSettleMs: number | undefined;
47
48
  /** Test-only override for the bounded wait for the Stall Watchdog probe. */
48
49
  readonly stallProbeSettleMs: number | undefined;
50
+ /** Records one parked question and raises the Run pause; absent when the Agent cannot ask. */
51
+ readonly questions?: AgentQuestions;
52
+ /** Marks this Ask parked, so the pause drain skips it (ADR-0022 §3, ADR-0023). */
53
+ readonly park?: () => void;
49
54
  }
@@ -6,6 +6,7 @@ import {
6
6
  REPORT_RESULT_WRAP_UP,
7
7
  ReportResultCall,
8
8
  ReportResultSteering,
9
+ readQuestionFrame,
9
10
  resolvePlaybackAskOutput,
10
11
  resolvePlaybackReportedResult,
11
12
  } from "../ask-contract/index.ts";
@@ -13,7 +14,7 @@ import { agentError, askLimitError, askStalledError } from "../error-factories.t
13
14
  import { type AskLimitOutcome, type AskStalledOutcome, isYaagError } from "../errors.ts";
14
15
  import { retryOnModelFailure, swapModel } from "../model/index.ts";
15
16
  import { NodeTracker } from "../node/index.ts";
16
- import type { AskPlayback } from "../transport/index.ts";
17
+ import type { AskPlayback, Frame } from "../transport/index.ts";
17
18
  import { FrameGapTracker } from "../transport/index.ts";
18
19
  import { AskActivityTracker } from "./ask-activity.ts";
19
20
  import { type AskEndOutcome, AskEvents } from "./ask-exchange-events.ts";
@@ -58,6 +59,13 @@ class AskExchange {
58
59
  #onSettled: () => void = () => {};
59
60
  #controlFailure: Promise<never> = new Promise<never>(() => {});
60
61
  #timeoutDeadline: number | undefined;
62
+ #isParked = false;
63
+ /** The parked `request_user_input` call of this Ask, when it parked (ADR-0021). */
64
+ #parkedCall: { readonly toolCallId: string; readonly questionId: string } | undefined;
65
+ #resolveParked: () => void = () => {};
66
+ readonly #parked: Promise<void> = new Promise<void>((resolve) => {
67
+ this.#resolveParked = resolve;
68
+ });
61
69
  #maxFrameGapMs: number | undefined;
62
70
  #cause: SettlementCause = "normal";
63
71
  #drainStaleFrames = false;
@@ -180,6 +188,7 @@ class AskExchange {
180
188
  });
181
189
  this.#began = true;
182
190
  this.#playback = playback;
191
+ if (playback?.parked !== undefined) this.#reopenParked(playback.parked);
183
192
  // `timeoutMs` is the Ask's hard ceiling and kills the Agent (ADR-0003), so
184
193
  // it is Ask-scoped: retries share one deadline, unlike the soft limits.
185
194
  this.#timeoutDeadline = this.#deadline();
@@ -292,6 +301,7 @@ class AskExchange {
292
301
  this.#options.connection.observe((frame) => {
293
302
  this.#turn.observe(frame);
294
303
  this.#limit?.observe(frame);
304
+ this.#observeQuestion(frame);
295
305
  if (frame.type !== "agent_settled" || this.#idle?.tripped) this.#idle?.observe(frame);
296
306
  this.#stall?.observe(frame);
297
307
  this.#gap?.observe();
@@ -313,6 +323,53 @@ class AskExchange {
313
323
  });
314
324
  }
315
325
 
326
+ /**
327
+ * Parks this Ask on one `request_user_input` call (ADR-0023).
328
+ *
329
+ * Order matters: every budget suspends before the question is raised, so no
330
+ * limit can trip between the two. First signal wins, so an Ask whose limit
331
+ * already tripped keeps its ASK_LIMIT and raises nothing. Replay never parks.
332
+ */
333
+ #observeQuestion(frame: Frame): void {
334
+ if (this.#playback !== undefined || this.#options.questions === undefined) return;
335
+ if (this.#isParked) return;
336
+ const call = readQuestionFrame(frame);
337
+ if (call === null) return;
338
+ if (this.#limit?.tripped === true) return;
339
+ this.#isParked = true;
340
+ this.#limit?.suspend();
341
+ this.#idle?.suspend();
342
+ this.#stall?.suspend();
343
+ // Suspends the Ask's hard timeout: the wait is the human's from here.
344
+ this.#resolveParked();
345
+ this.#options.park?.();
346
+ const questionId = this.#options.questions.raise({ agent: this.#options.agent, ...call });
347
+ // The incomplete-Ask marker of the artifact: this Ask has no settlement,
348
+ // and the Question it waits for names the way back (ADR-0021/0023).
349
+ this.#parkedCall = { toolCallId: call.toolCallId, questionId };
350
+ }
351
+
352
+ /**
353
+ * Re-opens the Question of a recorded parked Ask this resume did not answer
354
+ * (ADR-0023). No live Agent exists, so nothing can park again by itself: the
355
+ * Ask raises the same Question and stays open, and the Run pauses with it.
356
+ */
357
+ #reopenParked(parked: NonNullable<AskPlayback["parked"]>): void {
358
+ this.#isParked = true;
359
+ this.#resolveParked();
360
+ this.#options.park?.();
361
+ // 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).
363
+ const questionId =
364
+ this.#options.questions?.raise({
365
+ agent: this.#options.agent,
366
+ toolCallId: parked.toolCallId,
367
+ question: parked.question,
368
+ ...(parked.context === undefined ? {} : { context: parked.context }),
369
+ }) ?? parked.questionId;
370
+ this.#parkedCall = { toolCallId: parked.toolCallId, questionId };
371
+ }
372
+
316
373
  #createControlFailure(): Promise<never> {
317
374
  const controls = [
318
375
  this.#limit?.failed,
@@ -387,7 +444,13 @@ class AskExchange {
387
444
  // A recorded Ask that never settled has no settlement frame to wait for.
388
445
  // Waiting for one would reproduce, in replay, the exact stall this
389
446
  // watchdog exists to end.
390
- if (this.#playback?.settles === false && this.#playback.recovered !== true) {
447
+ // A re-opened parked Ask has no settlement either, and must not surface
448
+ // the recorded outcome: it waits for the human, exactly as it did before.
449
+ if (
450
+ this.#playback?.settles === false &&
451
+ this.#playback.recovered !== true &&
452
+ this.#playback.parked === undefined
453
+ ) {
391
454
  throw this.#recordedOutcome();
392
455
  }
393
456
  await awaitAskSettlement({
@@ -400,6 +463,7 @@ class AskExchange {
400
463
  controlFailure: this.#controlFailure,
401
464
  error: (code, message) => agentError(this.#options.agent, code, message),
402
465
  close: this.#options.close,
466
+ parked: this.#parked,
403
467
  });
404
468
  this.#outcome = this.#playback?.limit ?? this.#limit?.abortOutcome ?? undefined;
405
469
  if (this.#outcome !== undefined) throw askLimitError(this.#options.agent, this.#outcome);
@@ -520,6 +584,7 @@ class AskExchange {
520
584
  ...(this.#stalled === undefined ? {} : { stalled: this.#stalled }),
521
585
  ...(this.#invalidOutput === undefined ? {} : { invalidOutput: this.#invalidOutput }),
522
586
  ...(this.#cause === "recovered" ? { recovered: true as const } : {}),
587
+ ...(this.#parkedCall === undefined ? {} : { parked: this.#parkedCall }),
523
588
  });
524
589
  } catch {
525
590
  // Recording must not hide the Ask outcome it was observing.
@@ -7,6 +7,11 @@ export interface AwaitAskSettlementOptions {
7
7
  readonly controlFailure: Promise<never>;
8
8
  readonly error: (code: YaagError["code"], message: string) => YaagError;
9
9
  readonly close: () => void;
10
+ /**
11
+ * Resolves when the Ask parks on a user question; the Ask's hard timeout
12
+ * suspends, because the wait is the human's, not the Agent's (ADR-0023).
13
+ */
14
+ readonly parked?: Promise<void>;
10
15
  }
11
16
 
12
17
  /** Waits for one effort's settlement while preserving the Ask-wide timeout and death semantics. */
@@ -24,6 +29,9 @@ export async function awaitAskSettlement(options: AwaitAskSettlementOptions): Pr
24
29
  options.timeoutMs,
25
30
  );
26
31
  });
32
+ void options.parked?.then(() => {
33
+ clearTimeout(timer);
34
+ });
27
35
  try {
28
36
  await Promise.race([options.settled, death, expiry, options.controlFailure]);
29
37
  } catch (error) {
@@ -43,6 +43,7 @@ export class IdleWatch {
43
43
  #killTimer: ReturnType<typeof setTimeout> | undefined;
44
44
  #tripped = false;
45
45
  #done = false;
46
+ #suspended = false;
46
47
  #result: AskStalledOutcome | null = null;
47
48
 
48
49
  constructor(options: IdleWatchOptions) {
@@ -67,7 +68,7 @@ export class IdleWatch {
67
68
 
68
69
  /** Resets the silence timer; after escalation, watches for `agent_settled`. */
69
70
  observe(frame: Frame): void {
70
- if (this.#done) return;
71
+ if (this.#done || this.#suspended) return;
71
72
  if (this.#tripped) {
72
73
  if (frame.type === "agent_settled") this.#finish(false);
73
74
  return;
@@ -86,6 +87,15 @@ export class IdleWatch {
86
87
  this.cleanup();
87
88
  }
88
89
 
90
+ /**
91
+ * Suspends the watch while the Ask parks on a user question (ADR-0023). The
92
+ * silence that follows is the human thinking, not a hung Agent.
93
+ */
94
+ suspend(): void {
95
+ this.#suspended = true;
96
+ this.cleanup();
97
+ }
98
+
89
99
  /** Cancels timers on every other Ask exit path. Idempotent. */
90
100
  cleanup(): void {
91
101
  clearTimeout(this.#idleTimer);
@@ -120,7 +130,7 @@ export class IdleWatch {
120
130
  }
121
131
 
122
132
  #trip(): void {
123
- if (this.#done || this.#tripped) return;
133
+ if (this.#done || this.#suspended || this.#tripped) return;
124
134
  this.#tripped = true;
125
135
  clearTimeout(this.#idleTimer);
126
136
  this.#idleTimer = undefined;
@@ -63,6 +63,7 @@ export class StallWatchdog {
63
63
  #probeTimer: ReturnType<typeof setTimeout> | undefined;
64
64
  #tripped = false;
65
65
  #done = false;
66
+ #suspended = false;
66
67
  #cause: SettlementCause = "normal";
67
68
  #result: AskStalledOutcome | null = null;
68
69
 
@@ -86,7 +87,7 @@ export class StallWatchdog {
86
87
 
87
88
  /** Resets the silence timer. Frames that arrive after the probe are ignored. */
88
89
  observe(_frame: Frame): void {
89
- if (this.#done || this.#tripped) return;
90
+ if (this.#done || this.#suspended || this.#tripped) return;
90
91
  this.#arm();
91
92
  }
92
93
 
@@ -100,9 +101,18 @@ export class StallWatchdog {
100
101
  this.cleanup();
101
102
  }
102
103
 
104
+ /**
105
+ * Suspends the watchdog while the Ask parks on a user question (ADR-0023).
106
+ * The Agent is silent because it waits for the human, which is not a stall.
107
+ */
108
+ suspend(): void {
109
+ this.#suspended = true;
110
+ this.cleanup();
111
+ }
112
+
103
113
  /** Re-arms the timer for a further effort in the same Ask. Inert after a trip. */
104
114
  rearm(): void {
105
- if (this.#done || this.#tripped) return;
115
+ if (this.#done || this.#suspended || this.#tripped) return;
106
116
  this.#arm();
107
117
  }
108
118
 
@@ -135,7 +145,7 @@ export class StallWatchdog {
135
145
  }
136
146
 
137
147
  #trip(): void {
138
- if (this.#done || this.#tripped) return;
148
+ if (this.#done || this.#suspended || this.#tripped) return;
139
149
  this.#tripped = true;
140
150
  clearTimeout(this.#stallTimer);
141
151
  this.#stallTimer = undefined;