@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
@@ -9,23 +9,21 @@ import {
9
9
  } from "../model/index.ts";
10
10
  import type {
11
11
  AgentTransport,
12
+ OpenOptions,
12
13
  TransportFactory,
13
14
  TransportStartup,
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";
21
+ import { withoutForkVerbs } from "./host-fork.ts";
20
22
  import type { SpawnDependencies } from "./spawn.ts";
21
23
  import { resolveSpawnExtensions } from "./spawn-extensions.ts";
22
24
  import { resolveParent } from "./spawn-parent.ts";
23
- import {
24
- openRequest,
25
- type RenderedSpawnOptions,
26
- renderPolicyPrompt,
27
- withSelection,
28
- } from "./spawn-request.ts";
25
+ import { createSpawnPlan } from "./spawn-plan.ts";
26
+ import { type RenderedSpawnOptions, renderPolicyPrompt } from "./spawn-request.ts";
29
27
 
30
28
  /** One request the open path serves: a plain spawn, or a fork of another Agent. */
31
29
  export interface OpenAgentRequest {
@@ -38,7 +36,7 @@ export interface OpenAgentRequest {
38
36
  readonly definitionName: string | undefined;
39
37
  /** The prompt is a fork's inherited rendered text, not author-written. */
40
38
  readonly inheritedPrompt?: boolean;
41
- /** Present only for a fork; adds `origin: "fork"` and the `--fork` source. */
39
+ /** Present only for a fork; supplies the origin and the `--fork` source. */
42
40
  readonly fork?: ForkIdentity;
43
41
  /**
44
42
  * Id of the active Profile, on a profiled spawn only. It rides the
@@ -48,6 +46,11 @@ export interface OpenAgentRequest {
48
46
  readonly profile?: string;
49
47
  /** Roles the factory read, in order, duplicates kept; `[]` for none. */
50
48
  readonly role?: readonly string[];
49
+ /**
50
+ * An existing pi session this Agent opens on (`pi --session`). Never spawn
51
+ * identity: the path is machine-specific (ADR-0022).
52
+ */
53
+ readonly sessionFile?: string;
51
54
  }
52
55
 
53
56
  /** What the open path needs beyond the Run's spawn dependencies. */
@@ -65,11 +68,22 @@ export interface OpenAgentContext extends SpawnDependencies {
65
68
  * A fork walks this very path, so the Tool Contract probe, Model Resolution,
66
69
  * the worktree wrapper and the Cassette identity cannot drift between a spawn
67
70
  * and a fork (ADR-0044).
71
+ *
72
+ * It resolves with the concrete `Agent`, not with the author-facing `Handle`:
73
+ * the Run's own machinery reaps what it opens, and `close()` lives below the
74
+ * author surface (ADR-0022).
68
75
  */
69
76
  export async function openAgent(
70
77
  deps: OpenAgentContext,
71
- request: OpenAgentRequest,
72
- ): Promise<Handle> {
78
+ incoming: OpenAgentRequest,
79
+ ): Promise<Agent> {
80
+ // The two fork verbs are read by the spawn gate and stripped here, above the
81
+ // prompt render: `rendered` feeds the peeked request a resume compares with
82
+ // the recorded spawn, so neither key may travel past this line (ADR-0039).
83
+ const request: OpenAgentRequest = {
84
+ ...incoming,
85
+ spawnOptions: withoutForkVerbs(incoming.spawnOptions),
86
+ };
73
87
  const cwd = resolve(request.spawnOptions.cwd ?? process.cwd());
74
88
  const name = uniqueAgentName(request.spawnOptions.name, deps.agents.length, deps.taken);
75
89
  // Resolved before any transport work, so a bad Parent Link costs nothing.
@@ -86,6 +100,9 @@ export async function openAgent(
86
100
  agent: { name, runName: deps.runName },
87
101
  ...(request.inheritedPrompt === true ? { inheritedPrompt: true } : {}),
88
102
  });
103
+ // A policy that both asks its human and removes the tool is a contradiction:
104
+ // it fails here, before any I/O and before the Agent starts (ADR-0023).
105
+ assertAskUserTools(name, rendered);
89
106
  // Extension paths do not vary per candidate, so a bad path fails once, generically.
90
107
  const extensions = await resolveSpawnExtensions({
91
108
  configExtensions: deps.configExtensions,
@@ -97,60 +114,32 @@ export async function openAgent(
97
114
  if (error instanceof YaagError) throw error;
98
115
  throw new YaagError("SPAWN_FAILED", `agent "${name}": ${String(error)}`, name);
99
116
  });
100
- // One local for both open sites, so the launch arguments and the recorded
101
- // identity cannot drift apart.
102
- const extensionFields =
103
- extensions === undefined
104
- ? {}
105
- : {
106
- resolvedExtensionPaths: extensions.resolvedPaths,
107
- declaredExtensions: extensions.declared,
108
- };
109
- const forkFields =
110
- request.fork === undefined
111
- ? {}
112
- : {
113
- origin: "fork" as const,
114
- forkOf: request.fork.forkOf,
115
- forkAsks: request.fork.forkAsks,
116
- forkSession: request.fork.forkSession,
117
- ...(request.fork.worktreeFrom === undefined
118
- ? {}
119
- : { worktreeFrom: request.fork.worktreeFrom }),
120
- };
117
+ // One plan for both open sites, so the launch arguments and the recorded
118
+ // identity cannot drift apart: the peek and every attempt differ only in the
119
+ // settled model and thinking.
120
+ const plan = createSpawnPlan({
121
+ name,
122
+ runName: deps.runName,
123
+ cwd,
124
+ rendered,
125
+ ...(extensions === undefined ? {} : { extensions }),
126
+ ...(request.fork === undefined ? {} : { fork: request.fork }),
127
+ ...(parent === undefined ? {} : { parent }),
128
+ sessionDir: deps.sessionDir,
129
+ ...(request.sessionFile === undefined ? {} : { sessionFile: request.sessionFile }),
130
+ });
121
131
  const attempt = async (
122
132
  selection: ModelSelection,
123
133
  ): Promise<{ opened: OpenedTransport; spawnOptions: ResolvedSpawnOptions }> => {
124
- const settled = withSelection(rendered, selection);
134
+ const settled = plan.attempt(selection);
125
135
  return {
126
- opened: await openTransport({
127
- factory: deps.factory,
128
- name,
129
- runName: deps.runName,
130
- cwd,
131
- spawnOptions: settled,
132
- ...extensionFields,
133
- ...forkFields,
134
- ...(parent === undefined ? {} : { parent }),
135
- sessionDir: deps.sessionDir,
136
- }),
137
- spawnOptions: settled,
136
+ opened: await openTransport(deps.factory, name, settled.request),
137
+ spawnOptions: settled.spawnOptions,
138
138
  };
139
139
  };
140
140
  // The peek must stay in the same synchronous block as the first open: a
141
141
  // Cassette-backed factory claims Agents in open order (ADR-0013).
142
- const recorded = deps.factory.recordedSpawn?.(
143
- openRequest({
144
- name,
145
- runName: deps.runName,
146
- cwd,
147
- spawnOptions: rendered,
148
- ...extensionFields,
149
- ...forkFields,
150
- ...(parent === undefined ? {} : { parent }),
151
- sessionDir: deps.sessionDir,
152
- }),
153
- );
142
+ const recorded = deps.factory.recordedSpawn?.(plan.peek());
154
143
  // A Cassette-backed spawn adopts the recorded resolved selection and skips
155
144
  // the loop, so a replayed Run emits no spawn-time fallback (ADR-0039).
156
145
  const adopted =
@@ -191,6 +180,10 @@ export async function openAgent(
191
180
  ...(sessionFile === undefined ? {} : { sessionFile }),
192
181
  fork: deps.forkSpawner,
193
182
  ...(deps.askAdmission === undefined ? {} : { askAdmission: deps.askAdmission }),
183
+ // Only an Agent that may ask gets the sink, so no other Ask can park.
184
+ ...(deps.questions === undefined || rendered.canAskUser !== true
185
+ ? {}
186
+ : { questions: deps.questions }),
194
187
  ...(request.askDefaults === undefined ? {} : { askDefaults: request.askDefaults }),
195
188
  ...(request.definitionName === undefined ? {} : { definitionName: request.definitionName }),
196
189
  });
@@ -204,7 +197,7 @@ export async function openAgent(
204
197
  ...(sessionFile === undefined ? {} : { sessionFile }),
205
198
  ...(thinking === undefined ? {} : { thinking }),
206
199
  ...(parent === undefined ? {} : { parent }),
207
- ...(request.fork === undefined ? {} : { origin: "fork" as const }),
200
+ ...(plan.origin === undefined ? {} : { origin: plan.origin }),
208
201
  ...(request.profile === undefined
209
202
  ? {}
210
203
  : { profile: request.profile, role: request.role ?? [] }),
@@ -226,57 +219,23 @@ function isSpawnFailure(error: unknown): error is YaagError {
226
219
  return error instanceof YaagError && error.code === "SPAWN_FAILED";
227
220
  }
228
221
 
229
- interface OpenTransportOptions {
230
- readonly factory: TransportFactory;
231
- readonly name: string;
232
- /** The Run name; the peek and the open must pass the same one (ADR-0013). */
233
- readonly runName: string;
234
- readonly cwd: string;
235
- readonly spawnOptions: ResolvedSpawnOptions;
236
- readonly resolvedExtensionPaths?: readonly string[];
237
- readonly declaredExtensions?: readonly string[];
238
- readonly parent?: string;
239
- readonly origin?: "fork";
240
- readonly forkOf?: string;
241
- readonly forkAsks?: number;
242
- readonly forkSession?: string;
243
- readonly worktreeFrom?: WorktreeResolution;
244
- readonly sessionDir: string | undefined;
245
- }
246
-
247
222
  interface OpenedTransport {
248
223
  readonly transport: AgentTransport;
249
224
  readonly startup: TransportStartup;
250
225
  }
251
226
 
252
- async function openTransport(options: OpenTransportOptions): Promise<OpenedTransport> {
227
+ /** Opens one built request, and turns any foreign failure into a spawn failure. */
228
+ async function openTransport(
229
+ factory: TransportFactory,
230
+ name: string,
231
+ request: OpenOptions,
232
+ ): Promise<OpenedTransport> {
253
233
  const startup: TransportStartup = {};
254
234
  try {
255
- const transport = await options.factory.open(
256
- openRequest({
257
- name: options.name,
258
- runName: options.runName,
259
- cwd: options.cwd,
260
- spawnOptions: options.spawnOptions,
261
- ...(options.resolvedExtensionPaths === undefined
262
- ? {}
263
- : { resolvedExtensionPaths: options.resolvedExtensionPaths }),
264
- ...(options.declaredExtensions === undefined
265
- ? {}
266
- : { declaredExtensions: options.declaredExtensions }),
267
- ...(options.parent === undefined ? {} : { parent: options.parent }),
268
- ...(options.origin === undefined ? {} : { origin: options.origin }),
269
- ...(options.forkOf === undefined ? {} : { forkOf: options.forkOf }),
270
- ...(options.forkAsks === undefined ? {} : { forkAsks: options.forkAsks }),
271
- ...(options.forkSession === undefined ? {} : { forkSession: options.forkSession }),
272
- ...(options.worktreeFrom === undefined ? {} : { worktreeFrom: options.worktreeFrom }),
273
- sessionDir: options.sessionDir,
274
- }),
275
- (report) => Object.assign(startup, report),
276
- );
235
+ const transport = await factory.open(request, (report) => Object.assign(startup, report));
277
236
  return { transport, startup };
278
237
  } catch (error) {
279
238
  if (error instanceof YaagError) throw error;
280
- throw new YaagError("SPAWN_FAILED", `agent "${options.name}": ${String(error)}`, options.name);
239
+ throw new YaagError("SPAWN_FAILED", `agent "${name}": ${String(error)}`, name);
281
240
  }
282
241
  }
@@ -0,0 +1,114 @@
1
+ /**
2
+ * The Spawn Plan: the one open request built for one spawn.
3
+ *
4
+ * The peek a Cassette-backed factory reads and every model attempt read from
5
+ * this value. Before it, the same field list was spread at three sites and
6
+ * mirrored by a fourth type, and only a comment said the three must agree.
7
+ */
8
+ import type { SpawnOrigin } from "../events.ts";
9
+ import type { ModelSelection } from "../model/index.ts";
10
+ import type { OpenOptions } from "../transport/index.ts";
11
+ import type { ResolvedSpawnOptions } from "../types.ts";
12
+ import type { ForkIdentity } from "./fork.ts";
13
+ import {
14
+ type OpenRequestOptions,
15
+ openRequest,
16
+ type RenderedSpawnOptions,
17
+ withSelection,
18
+ } from "./spawn-request.ts";
19
+
20
+ /** What one spawn knows before a model settles. */
21
+ export interface SpawnPlanInput {
22
+ readonly name: string;
23
+ readonly runName: string;
24
+ readonly cwd: string;
25
+ /** The Prompt Definition, rendered once above the plan (ADR-0064). */
26
+ readonly rendered: RenderedSpawnOptions;
27
+ /** Resolved and declared extension paths, or nothing when the Agent runs none. */
28
+ readonly extensions?: {
29
+ readonly resolvedPaths: readonly string[];
30
+ readonly declared: readonly string[];
31
+ };
32
+ /** Fork facts, present only for a fork of an Agent or of the Host Session. */
33
+ readonly fork?: ForkIdentity;
34
+ readonly parent?: string;
35
+ readonly sessionDir: string | undefined;
36
+ readonly sessionFile?: string;
37
+ }
38
+
39
+ /** One attempt's open request and the settled options the Agent records. */
40
+ export interface SpawnAttempt {
41
+ readonly request: OpenOptions;
42
+ readonly spawnOptions: ResolvedSpawnOptions;
43
+ }
44
+
45
+ /** The open requests of one spawn: the peek, and one per model attempt. */
46
+ export interface SpawnPlan {
47
+ /**
48
+ * The request a Cassette-backed factory peeks at, with the caller's unsettled
49
+ * `model`/`thinking` forms (ADR-0039).
50
+ */
51
+ peek(): OpenOptions;
52
+ /** The origin this spawn records, absent for an ordinary spawn. */
53
+ readonly origin?: SpawnOrigin;
54
+ /** The same request with one settled selection applied, and nothing else changed. */
55
+ attempt(selection: ModelSelection): SpawnAttempt;
56
+ }
57
+
58
+ /**
59
+ * The open-request fields of one fork. An Agent fork names its source; a Host
60
+ * Fork names the Host Session hash instead, and carries no `forkOf`/`forkAsks`.
61
+ */
62
+ function forkFields(
63
+ fork: ForkIdentity,
64
+ origin: SpawnOrigin | undefined,
65
+ ): Partial<OpenRequestOptions> {
66
+ if (fork.kind === "host") {
67
+ return {
68
+ origin,
69
+ ...(fork.forkSession === undefined ? {} : { forkSession: fork.forkSession }),
70
+ hostHash: fork.hostHash,
71
+ };
72
+ }
73
+ return {
74
+ origin,
75
+ forkOf: fork.forkOf,
76
+ forkAsks: fork.forkAsks,
77
+ forkSession: fork.forkSession,
78
+ ...(fork.worktreeFrom === undefined ? {} : { worktreeFrom: fork.worktreeFrom }),
79
+ };
80
+ }
81
+
82
+ /**
83
+ * Builds one spawn's plan. The base below is the single field roster of the
84
+ * open path: `peek()` and `attempt()` differ only in the spawn options they
85
+ * pass, so the peek and every attempt cannot drift apart (ADR-0013).
86
+ */
87
+ export function createSpawnPlan(input: SpawnPlanInput): SpawnPlan {
88
+ const origin: SpawnOrigin | undefined =
89
+ input.fork === undefined ? undefined : input.fork.kind === "host" ? "host-fork" : "fork";
90
+ const base = {
91
+ name: input.name,
92
+ runName: input.runName,
93
+ cwd: input.cwd,
94
+ ...(input.extensions === undefined
95
+ ? {}
96
+ : {
97
+ resolvedExtensionPaths: input.extensions.resolvedPaths,
98
+ declaredExtensions: input.extensions.declared,
99
+ }),
100
+ ...(input.fork === undefined ? {} : forkFields(input.fork, origin)),
101
+ ...(input.parent === undefined ? {} : { parent: input.parent }),
102
+ sessionDir: input.sessionDir,
103
+ ...(input.sessionFile === undefined ? {} : { sessionFile: input.sessionFile }),
104
+ } satisfies Omit<OpenRequestOptions, "spawnOptions">;
105
+
106
+ return {
107
+ ...(origin === undefined ? {} : { origin }),
108
+ peek: () => openRequest({ ...base, spawnOptions: input.rendered }),
109
+ attempt: (selection) => {
110
+ const spawnOptions = withSelection(input.rendered, selection);
111
+ return { request: openRequest({ ...base, spawnOptions }), spawnOptions };
112
+ },
113
+ };
114
+ }
@@ -1,5 +1,7 @@
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";
4
+ import type { SpawnOrigin } from "../events.ts";
3
5
  import type { ModelSelection } from "../model/index.ts";
4
6
  import {
5
7
  assertKnownSentinels,
@@ -105,12 +107,20 @@ export interface OpenRequestOptions {
105
107
  /** Resolved parent Agent name (Parent Link); spawn identity only, never argv. */
106
108
  readonly parent?: string;
107
109
  /** Fork facts (ADR-0044); the first three are spawn identity, the rest are not. */
108
- readonly origin?: "fork";
110
+ readonly origin?: SpawnOrigin;
109
111
  readonly forkOf?: string;
110
112
  readonly forkAsks?: number;
111
113
  readonly forkSession?: string;
114
+ /** Host Session identity of a Host Fork; a launch field, never argv (ADR-0068). */
115
+ readonly hostHash?: string;
112
116
  readonly worktreeFrom?: WorktreeResolution;
113
117
  readonly sessionDir: string | undefined;
118
+ /**
119
+ * An existing pi session to open on, translated to `pi --session <path>`.
120
+ * Never spawn identity: the path is machine-specific, exactly like
121
+ * `forkSession`. The fork summarizer opens on a copy this way (ADR-0022).
122
+ */
123
+ readonly sessionFile?: string;
114
124
  }
115
125
 
116
126
  /**
@@ -157,7 +167,11 @@ export function openRequest(options: OpenRequestOptions): OpenOptions {
157
167
  ...(model === undefined ? {} : { model }),
158
168
  systemPrompt:
159
169
  spawnOptions.systemPrompt ??
160
- yaagSystemPrompt({ agent: { name: options.name, runName: options.runName } }),
170
+ yaagSystemPrompt({
171
+ agent: { name: options.name, runName: options.runName },
172
+ // An Agent that may ask its human reads the audience line (ADR-0062).
173
+ ...(spawnOptions.canAskUser === true ? { audience: "user" as const } : {}),
174
+ }),
161
175
  ...(thinking === undefined ? {} : { thinking }),
162
176
  ...(spawnOptions.appendSystemPrompt === undefined
163
177
  ? {}
@@ -167,6 +181,11 @@ export function openRequest(options: OpenRequestOptions): OpenOptions {
167
181
  ...(spawnOptions.disallowedTools === undefined
168
182
  ? {}
169
183
  : { disallowedTools: spawnOptions.disallowedTools }),
184
+ // Both fields stay absent for an Agent that cannot ask, so every recorded
185
+ // spawn identity from before ADR-0023 is unchanged.
186
+ ...(spawnOptions.canAskUser === true
187
+ ? { canAskUser: true as const, askUserProtocol: REQUEST_USER_INPUT_PROTOCOL }
188
+ : {}),
170
189
  ...(spawnOptions.skills === undefined ? {} : { skills: spawnOptions.skills }),
171
190
  ...(spawnOptions.disallowedSkills === undefined
172
191
  ? {}
@@ -184,9 +203,11 @@ export function openRequest(options: OpenRequestOptions): OpenOptions {
184
203
  ...(options.forkOf === undefined ? {} : { forkOf: options.forkOf }),
185
204
  ...(options.forkAsks === undefined ? {} : { forkAsks: options.forkAsks }),
186
205
  ...(options.forkSession === undefined ? {} : { forkSession: options.forkSession }),
206
+ ...(options.hostHash === undefined ? {} : { hostHash: options.hostHash }),
187
207
  ...(options.worktreeFrom === undefined ? {} : { worktreeFrom: options.worktreeFrom }),
188
208
  ...(spawnOptions.worktree === true ? { worktree: true as const } : {}),
189
209
  ...(options.sessionDir === undefined ? {} : { sessionDir: options.sessionDir }),
210
+ ...(options.sessionFile === undefined ? {} : { sessionFile: options.sessionFile }),
190
211
  };
191
212
  }
192
213
 
@@ -196,7 +217,17 @@ export function withSelection(
196
217
  selection: ModelSelection,
197
218
  ): ResolvedSpawnOptions {
198
219
  // `parent` is dropped here as well: a Handle must never reach recorded options.
199
- const { model: _model, thinking: _thinking, parent: _parent, ...rest } = options;
220
+ // `fork` and `compact` are spawn verbs, not properties of the Agent. The spawn
221
+ // gate already strips them before the render; this line is the second wall, so
222
+ // an inherited one cannot travel into a resolved or recorded spawn request.
223
+ const {
224
+ model: _model,
225
+ thinking: _thinking,
226
+ parent: _parent,
227
+ fork: _fork,
228
+ compact: _compact,
229
+ ...rest
230
+ } = options;
200
231
  return {
201
232
  ...rest,
202
233
  ...(selection.model === undefined ? {} : { model: selection.model }),
@@ -4,14 +4,15 @@ 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
+ import { hostForkRequest } from "./host-fork.ts";
13
14
  import { resolveRequest } from "./spawn-definition-request.ts";
14
- import { type OpenAgentContext, openAgent } from "./spawn-open.ts";
15
+ import { type OpenAgentContext, type OpenAgentRequest, openAgent } from "./spawn-open.ts";
15
16
  import { profiledRequest } from "./spawn-profiled.ts";
16
17
 
17
18
  /** Dependencies for one Run's Agent-spawn gate. */
@@ -29,11 +30,22 @@ export interface SpawnDependencies {
29
30
  readonly profile?: ActiveProfile;
30
31
  /** Run-scoped Ask gate handed to every Agent this gate opens (ADR-0024). */
31
32
  readonly askAdmission?: AskAdmission;
33
+ /** Run-scoped sink of the questions an Agent asks its human (ADR-0023). */
34
+ readonly questions?: AgentQuestions;
32
35
  }
33
36
 
34
37
  /** A RunContext spawn function that can synchronously stop accepting new Agents. */
35
38
  export interface SpawnGate {
36
39
  readonly spawn: RunContext["spawn"];
40
+ /**
41
+ * Opens one Agent for the Run's own machinery, after the gate closed.
42
+ *
43
+ * The closed flag is ignored on purpose: the fork summarizer runs after
44
+ * settlement, when the author-facing gate must already refuse (ADR-0022).
45
+ * The opened Agent gets neither the Run's Ask admission — which is closed by
46
+ * then — nor its Agent-question sink, so it can neither be refused nor park.
47
+ */
48
+ readonly openInternal: (request: OpenAgentRequest) => Promise<Agent>;
37
49
  close(): void;
38
50
  }
39
51
 
@@ -65,6 +77,10 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
65
77
  return handle;
66
78
  };
67
79
  const context: OpenAgentContext = { ...deps, taken, forkSpawner };
80
+ // Same open path, minus the two Run-scoped gates: `askAdmission` and
81
+ // `questions` are dropped rather than overridden, so nothing can re-add them.
82
+ const { askAdmission: _askAdmission, questions: _questions, ...ungated } = deps;
83
+ const internalContext: OpenAgentContext = { ...ungated, taken, forkSpawner };
68
84
  const spawn: RunContext["spawn"] = async (
69
85
  definitionOrOptions: SpawnOptions | AgentDefinition | ProfiledDefinition = {},
70
86
  overrides?: SpawnOverrides,
@@ -73,15 +89,35 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
73
89
  // The Agent Definition branch is explicit, although `resolveRequest` takes
74
90
  // a plain options object too: it states the three accepted shapes in order.
75
91
  if (isAgentDefinition(definitionOrOptions)) {
76
- return openAgent(context, resolveRequest(definitionOrOptions, overrides));
92
+ return openRequested(resolveRequest(definitionOrOptions, overrides));
77
93
  }
78
94
  if (isProfiledDefinition(definitionOrOptions)) {
79
- return openAgent(context, profiledRequest(deps.profile, definitionOrOptions, overrides));
95
+ return openRequested(profiledRequest(deps.profile, definitionOrOptions, overrides));
80
96
  }
81
- return openAgent(context, resolveRequest(definitionOrOptions, overrides));
97
+ return openRequested(resolveRequest(definitionOrOptions, overrides));
98
+ };
99
+ /**
100
+ * Opens one requested Agent, as a Host Fork when the options carry `ctx.host`.
101
+ * A Host Fork gets no default Parent Link: `parent` stays the program's to
102
+ * give. `compact` is the ADR-0043 sugar — spawn, compact, hand the Handle back.
103
+ */
104
+ const openRequested = async (request: OpenAgentRequest): Promise<Handle> => {
105
+ const host = hostForkRequest(request.spawnOptions);
106
+ const handle = await openAgent(context, {
107
+ ...request,
108
+ ...(host.fork === undefined ? {} : { fork: host.fork }),
109
+ });
110
+ if (host.compact !== undefined && host.compact !== false) {
111
+ await handle.compact(typeof host.compact === "string" ? host.compact : undefined);
112
+ }
113
+ return handle;
82
114
  };
83
115
  return {
84
116
  spawn,
117
+ // The concrete Agent, not a Handle: the Run reaps its own machinery itself,
118
+ // and `close()` lives below the author surface.
119
+ openInternal: (request: OpenAgentRequest): Promise<Agent> =>
120
+ openAgent(internalContext, request),
85
121
  close: (): void => {
86
122
  closed = true;
87
123
  },
@@ -1,9 +1,11 @@
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";
8
+ import type { AskTiming } from "./ask-timing.ts";
7
9
 
8
10
  /** A frame consumer whose lifetime exceeds one Ask; the Agent's AgentUsage satisfies it. */
9
11
  export interface FrameObserver {
@@ -40,10 +42,10 @@ export interface AskExchangeOptions {
40
42
  readonly modelFallback: AskModelFallback | undefined;
41
43
  /** Kills the Agent on ASK_TIMEOUT and destructive stalls — the one upward capability. */
42
44
  readonly close: () => void;
43
- /** Test-only override for the fixed duration-limit grace. */
44
- readonly askLimitGraceMs: number | undefined;
45
- /** Test-only override for the bounded settle wait after an idle abort. */
46
- readonly idleAbortSettleMs: number | undefined;
47
- /** Test-only override for the bounded wait for the Stall Watchdog probe. */
48
- readonly stallProbeSettleMs: number | undefined;
45
+ /** Test-only waits of the Ask Guard's controls; absent in production. */
46
+ readonly timing?: AskTiming;
47
+ /** Records one parked question and raises the Run pause; absent when the Agent cannot ask. */
48
+ readonly questions?: AgentQuestions;
49
+ /** Marks this Ask parked, so the pause drain skips it (ADR-0022 §3, ADR-0023). */
50
+ readonly park?: () => void;
49
51
  }