@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
package/package.json CHANGED
@@ -1,12 +1,11 @@
1
1
  {
2
2
  "name": "@yaag/runtime",
3
- "version": "0.25.0",
3
+ "version": "0.27.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": {
@@ -1,11 +1,12 @@
1
1
  import type { Static, TSchema } from "typebox";
2
- import type { EffectiveAskOptions } from "../ask/index.ts";
2
+ import type { AskTiming, 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,
@@ -54,14 +55,12 @@ export interface AgentOptions {
54
55
  readonly askDefaults?: AskOptions;
55
56
  /** Definition identity recorded on its Asks, outside replay identity. */
56
57
  readonly definitionName?: string;
57
- /** Test-only override for the fixed duration-limit grace. */
58
- readonly askLimitGraceMs?: number;
59
- /** Test-only override for the bounded wait for `agent_settled` after an idle abort. */
60
- readonly idleAbortSettleMs?: number;
61
- /** Test-only override for the bounded wait for the Stall Watchdog probe. */
62
- readonly stallProbeSettleMs?: number;
58
+ /** Test-only waits of the Ask Guard's controls; absent in production. */
59
+ readonly timing?: AskTiming;
63
60
  /** Run-scoped Ask gate; a closed gate refuses every later Ask (ADR-0024). */
64
61
  readonly askAdmission?: AskAdmission;
62
+ /** Run-scoped sink of Agent questions; absent when this Agent cannot ask (ADR-0023). */
63
+ readonly questions?: AgentQuestions;
65
64
  }
66
65
 
67
66
  /** One Agent as an Orchestration Program sees it. Lives above the transport seam. */
@@ -76,9 +75,7 @@ export class Agent implements Handle {
76
75
  readonly #spawnOptions: ResolvedSpawnOptions;
77
76
  readonly #askDefaults: AskOptions;
78
77
  readonly #definitionName: string | undefined;
79
- readonly #askLimitGraceMs: number | undefined;
80
- readonly #idleAbortSettleMs: number | undefined;
81
- readonly #stallProbeSettleMs: number | undefined;
78
+ readonly #timing: AskTiming | undefined;
82
79
  readonly #modelFallback: AgentModelFallback | undefined;
83
80
  #model: string;
84
81
  #candidate: string;
@@ -87,6 +84,7 @@ export class Agent implements Handle {
87
84
  readonly #sessionFile: string | undefined;
88
85
  readonly #fork: ForkSpawner | undefined;
89
86
  readonly #askAdmission: AskAdmission | undefined;
87
+ readonly #questions: AgentQuestions | undefined;
90
88
  #busy = false;
91
89
  #inFlight: AskInFlight | null = null;
92
90
  #incomplete = false;
@@ -109,10 +107,9 @@ export class Agent implements Handle {
109
107
  this.#definitionName = options.definitionName;
110
108
  this.#sessionFile = options.sessionFile;
111
109
  this.#fork = options.fork;
112
- this.#askLimitGraceMs = options.askLimitGraceMs;
113
- this.#idleAbortSettleMs = options.idleAbortSettleMs;
114
- this.#stallProbeSettleMs = options.stallProbeSettleMs;
110
+ this.#timing = options.timing;
115
111
  this.#askAdmission = options.askAdmission;
112
+ this.#questions = options.questions;
116
113
  this.#usage = new AgentUsage((snapshot) =>
117
114
  this.#emit({ type: "agent_usage", agent: this.name, ...snapshot }),
118
115
  );
@@ -124,6 +121,15 @@ export class Agent implements Handle {
124
121
  return this.#model;
125
122
  }
126
123
 
124
+ /**
125
+ * pi's session file for this Agent; the fork summarizer copies it (ADR-0022).
126
+ * Absent during playback. `Handle` does not carry it: this is Run machinery,
127
+ * not an author surface.
128
+ */
129
+ get sessionFile(): string | undefined {
130
+ return this.#sessionFile;
131
+ }
132
+
127
133
  async ask<Schema extends TSchema>(
128
134
  prompt: string,
129
135
  options: StructuredAskOptions<Schema>,
@@ -146,6 +152,8 @@ export class Agent implements Handle {
146
152
  const inFlight = this.#openInFlight(effective);
147
153
  this.#inFlight = inFlight;
148
154
  const index = this.#askIndex++;
155
+ // Kept, so the drain sees why an Ask left flight and can warn about it.
156
+ let failure: unknown;
149
157
  try {
150
158
  return await exchangeAsk({
151
159
  agent: this.name,
@@ -172,14 +180,18 @@ export class Agent implements Handle {
172
180
  },
173
181
  },
174
182
  close: () => void this.close().catch(() => {}),
175
- askLimitGraceMs: this.#askLimitGraceMs,
176
- idleAbortSettleMs: this.#idleAbortSettleMs,
177
- stallProbeSettleMs: this.#stallProbeSettleMs,
183
+ ...(this.#timing === undefined ? {} : { timing: this.#timing }),
184
+ ...(this.#questions === undefined
185
+ ? {}
186
+ : { questions: this.#questions, park: () => inFlight.park() }),
178
187
  });
188
+ } catch (error) {
189
+ failure = error;
190
+ throw error;
179
191
  } finally {
180
192
  this.#busy = false;
181
193
  this.#inFlight = null;
182
- inFlight.settle();
194
+ inFlight.settle(failure);
183
195
  // A failed Ask settles the conversation as much as a successful one: the
184
196
  // fork point is the boundary, not the outcome.
185
197
  this.#settledAsks += 1;
@@ -198,10 +210,20 @@ export class Agent implements Handle {
198
210
  * Builds the drain's controls of one Ask. Both commands report a refusal as
199
211
  * false and never throw, so a dead Agent cannot throw into the drain.
200
212
  */
201
- #openInFlight(ask: EffectiveAskOptions): AskInFlight & { settle(): void } {
202
- let settle: () => void = () => {};
203
- const settled = new Promise<void>((resolve) => {
204
- settle = resolve;
213
+ #openInFlight(
214
+ ask: EffectiveAskOptions,
215
+ ): AskInFlight & { settle(error?: unknown): void; park(): void } {
216
+ let settle: (error?: unknown) => void = () => {};
217
+ // A getter, not a snapshot: the drain reads `parked` at its start and again
218
+ // when it aborts what remains, and an Ask may park between the two. The
219
+ // signal covers the drain that is already waiting (ADR-0023).
220
+ let parked = false;
221
+ let raiseParked: () => void = () => {};
222
+ const parkedSignal = new Promise<void>((resolve) => {
223
+ raiseParked = resolve;
224
+ });
225
+ const settled = new Promise<AskSettled>((resolve) => {
226
+ settle = (error?: unknown) => resolve(error === undefined ? {} : { error });
205
227
  });
206
228
  // A structured Ask keeps reporting through report_result, so its wrap-up
207
229
  // carries the same suffix the soft-budget path uses (ADR-0032). Legacy
@@ -218,6 +240,14 @@ export class Agent implements Handle {
218
240
  agent: this.name,
219
241
  settled,
220
242
  settle,
243
+ get parked(): boolean {
244
+ return parked;
245
+ },
246
+ parkedSignal,
247
+ park: (): void => {
248
+ parked = true;
249
+ raiseParked();
250
+ },
221
251
  wrapUp: () => send({ type: "steer", message: wrapUpMessage(ask, suffix) }),
222
252
  abort: () => send({ type: "abort" }),
223
253
  };
@@ -244,7 +274,18 @@ export class Agent implements Handle {
244
274
  });
245
275
  }
246
276
 
247
- /** Spawns a new Agent from a copy of this Agent's session (ADR-0044). */
277
+ /**
278
+ * Spawns a new Agent from a copy of this Agent's session (ADR-0044).
279
+ *
280
+ * Four refusals, in this order: `FORK_REFUSED` when the Run cannot open a
281
+ * fork at all, `FORK_REFUSED` when the overrides name `fork`, because that
282
+ * verb belongs to `ctx.spawn({ fork: ctx.host })` and never to a fork of an
283
+ * Agent (ADR-0068), `FORK_DURING_ASK` while an Ask is in flight, and
284
+ * `FORK_REFUSED` when the tail of the session is undefined or the Agent
285
+ * holds no session file to copy. The value check comes before the state
286
+ * checks, so a wrong call is refused the same way whatever the Agent is
287
+ * doing.
288
+ */
248
289
  fork(overrides?: ForkOptions): Promise<Handle> {
249
290
  const spawner = this.#fork;
250
291
  if (spawner === undefined) {
@@ -252,6 +293,17 @@ export class Agent implements Handle {
252
293
  agentError(this.name, "FORK_REFUSED", "this Agent's Run cannot open a fork"),
253
294
  );
254
295
  }
296
+ // A Host Source is a spawn verb, not a fork override (ADR-0068). The key is
297
+ // absent from `ForkOptions`, so it can only arrive untyped.
298
+ if (overrides !== undefined && typeof overrides === "object" && "fork" in overrides) {
299
+ return Promise.reject(
300
+ agentError(
301
+ this.name,
302
+ "FORK_REFUSED",
303
+ "handle.fork() forks this Agent — a Host Source belongs to ctx.spawn({ fork })",
304
+ ),
305
+ );
306
+ }
255
307
  if (this.#busy) {
256
308
  return Promise.reject(
257
309
  agentError(this.name, "FORK_DURING_ASK", "an Ask is in flight — fork between Asks"),
@@ -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
+ }
package/src/agent/fork.ts CHANGED
@@ -6,6 +6,7 @@ import type {
6
6
  ResolvedSpawnOptions,
7
7
  SpawnOptions,
8
8
  } from "../types.ts";
9
+ import { withoutForkVerbs } from "./host-fork.ts";
9
10
 
10
11
  /** What one Agent hands the spawn gate when it is forked (ADR-0044). */
11
12
  export interface ForkSource {
@@ -26,14 +27,32 @@ export interface ForkSource {
26
27
  /** Opens one fork. The spawn gate owns it, so a fork walks the normal spawn path. */
27
28
  export type ForkSpawner = (source: ForkSource, overrides?: ForkOptions) => Promise<Handle>;
28
29
 
29
- /** Spawn identity and launch facts that only a fork carries. */
30
- export interface ForkIdentity {
31
- readonly forkOf: string;
32
- readonly forkAsks: number;
33
- /** The session pi copies with `--fork`; machine-specific, never identity. */
34
- readonly forkSession: string;
35
- readonly worktreeFrom?: WorktreeResolution;
36
- }
30
+ /**
31
+ * Spawn identity and launch facts that only a fork carries.
32
+ *
33
+ * The two fork kinds are one union, so no site can build a half fork: an Agent
34
+ * fork names its source Agent and the Asks it had settled, while a Host Fork
35
+ * names neither and carries the Host Session identity instead (ADR-0068).
36
+ */
37
+ export type ForkIdentity =
38
+ | {
39
+ readonly kind: "agent";
40
+ readonly forkOf: string;
41
+ readonly forkAsks: number;
42
+ /** The session pi copies with `--fork`; machine-specific, never identity. */
43
+ readonly forkSession: string;
44
+ readonly worktreeFrom?: WorktreeResolution;
45
+ }
46
+ | {
47
+ readonly kind: "host";
48
+ /**
49
+ * The copy of the Host Session pi forks with `--fork`. Absent when the
50
+ * Run holds no copy — a replay or a resume reconstructed its Host Source.
51
+ */
52
+ readonly forkSession?: string;
53
+ /** SHA-256 of the Host Session bytes as read; spawn identity (ADR-0068). */
54
+ readonly hostHash: string;
55
+ };
37
56
 
38
57
  /** One fork request: what to spawn, whose child it is, and whether to compact it. */
39
58
  export interface ForkRequest {
@@ -58,9 +77,15 @@ export interface ForkRequest {
58
77
  *
59
78
  * Inheritance is verbatim, with two deliberate exceptions: `name` is dropped,
60
79
  * so the child gets a fresh auto-name unless the overrides give it one, and
61
- * `compact` never reaches the spawn options, because it is a fork verb rather
62
- * than a property of the Agent. `askDefaults` travels beside the spawn
63
- * options, as on every spawn path, and an explicit one replaces the source's.
80
+ * neither fork verb reaches the spawn options, because `fork` and `compact`
81
+ * are verbs of the spawn rather than properties of the Agent (ADR-0068).
82
+ * The rule holds on both sides: the spawn gate strips both verbs before the
83
+ * render and `withSelection` strips them again, so a source cannot carry one
84
+ * to inherit, and `withoutForkVerbs` here drops an overridden one. `compact`
85
+ * travels as a field of the request instead, and an untyped `fork` is refused
86
+ * by `handle.fork()` above this function.
87
+ * `askDefaults` travels beside the spawn options, as on every spawn path, and
88
+ * an explicit one replaces the source's.
64
89
  */
65
90
  export function forkRequest(source: ForkSource, overrides?: ForkOptions): ForkRequest {
66
91
  if (source.sessionFile === undefined) {
@@ -69,10 +94,13 @@ export function forkRequest(source: ForkSource, overrides?: ForkOptions): ForkRe
69
94
  const { name: _name, ...inherited } = source.spawnOptions;
70
95
  const { compact, parent, askDefaults, ...explicit } = overrides ?? {};
71
96
  return {
72
- spawnOptions: { ...inherited, ...stripUndefined(explicit) },
97
+ // A Host Source belongs to `ctx.spawn({ fork })`: `handle.fork()` refuses
98
+ // one, and this strip is the wall behind that refusal.
99
+ spawnOptions: withoutForkVerbs({ ...inherited, ...stripUndefined(explicit) }),
73
100
  parent: parent ?? source.handle,
74
101
  askDefaults: askDefaults ?? source.askDefaults,
75
102
  fork: {
103
+ kind: "agent",
76
104
  forkOf: source.name,
77
105
  forkAsks: source.settledAsks,
78
106
  forkSession: source.sessionFile,
@@ -0,0 +1,85 @@
1
+ /**
2
+ * The Host Fork branch of the spawn gate: `ctx.spawn({ fork: ctx.host })`
3
+ * (ADR-0068).
4
+ *
5
+ * A Host Fork walks the ordinary spawn path. This module does two things and
6
+ * nothing else: it reads the Host Source a program handed back into the fork
7
+ * facts the open path already understands, and it refuses every other use of
8
+ * `fork` and `compact` before any transport work starts.
9
+ *
10
+ * Neither key may reach the rendered, resolved or recorded spawn options — the
11
+ * peeked request is what a resume compares against the recorded spawn — so the
12
+ * open path strips both, and this module is the only reader of them.
13
+ */
14
+ import { YaagError } from "../errors.ts";
15
+ import type { SpawnOptions } from "../types.ts";
16
+ import type { ForkIdentity } from "./fork.ts";
17
+
18
+ /** The Host Source as the Run built it; the brand itself is type-only. */
19
+ interface RuntimeHostSource {
20
+ readonly kind: "host";
21
+ /** Absent when the Run holds no copy: a replayed or resumed Host Source. */
22
+ readonly sessionFile?: string;
23
+ readonly hostHash: string;
24
+ }
25
+
26
+ /** What the spawn gate reads out of one options object. */
27
+ export interface HostForkRequest {
28
+ /** The fork facts, absent for an ordinary spawn. */
29
+ readonly fork?: ForkIdentity;
30
+ /** The compaction the sugar runs after the Agent opened (ADR-0043). */
31
+ readonly compact?: boolean | string;
32
+ }
33
+
34
+ /**
35
+ * Reads the Host Fork request of one spawn.
36
+ *
37
+ * Refuses with `FORK_REFUSED` when `fork` is present but is not a Host Source
38
+ * this Run prepared — `undefined` slipping past the type, or a foreign object —
39
+ * and with `OPTIONS_CONFLICT` when `compact` is given without `fork`, because
40
+ * compaction is a fork verb and not a property of an Agent.
41
+ */
42
+ export function hostForkRequest(options: SpawnOptions): HostForkRequest {
43
+ const holdsFork = "fork" in options;
44
+ const compact = options.compact;
45
+ if (!holdsFork) {
46
+ if (compact !== undefined) {
47
+ throw new YaagError("OPTIONS_CONFLICT", "cannot use compact without fork");
48
+ }
49
+ return {};
50
+ }
51
+ const source = options.fork;
52
+ if (!isRuntimeHostSource(source)) {
53
+ throw new YaagError(
54
+ "FORK_REFUSED",
55
+ 'spawn option "fork" must be the Run\'s ctx.host — a program cannot build one',
56
+ );
57
+ }
58
+ return {
59
+ fork: {
60
+ kind: "host",
61
+ ...(source.sessionFile === undefined ? {} : { forkSession: source.sessionFile }),
62
+ hostHash: source.hostHash,
63
+ },
64
+ ...(compact === undefined ? {} : { compact }),
65
+ };
66
+ }
67
+
68
+ /** The spawn options without the two fork verbs, which no consumer may see. */
69
+ export function withoutForkVerbs(options: SpawnOptions): SpawnOptions {
70
+ const { fork: _fork, compact: _compact, ...rest } = options;
71
+ return rest;
72
+ }
73
+
74
+ function isRuntimeHostSource(value: unknown): value is RuntimeHostSource {
75
+ return (
76
+ typeof value === "object" &&
77
+ value !== null &&
78
+ "kind" in value &&
79
+ value.kind === "host" &&
80
+ // The copy path is optional, but a present one must still be a path.
81
+ (!("sessionFile" in value) || typeof value.sessionFile === "string") &&
82
+ "hostHash" in value &&
83
+ typeof value.hostHash === "string"
84
+ );
85
+ }
@@ -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";
@@ -3,7 +3,7 @@
3
3
  * Definition, with its override validation. Separate from `spawn.ts` so the
4
4
  * profiled path can reuse it without a cycle.
5
5
  */
6
- import type { SpawnOptions, SpawnOverrides } from "../types.ts";
6
+ import type { HostSource, SpawnOptions, SpawnOverrides } from "../types.ts";
7
7
  import { type AgentDefinition, agentDefinitionConfig, isAgentDefinition } from "./define-agent.ts";
8
8
  import type { OpenAgentRequest } from "./spawn-open.ts";
9
9
 
@@ -26,7 +26,7 @@ interface ValidatedOverrides {
26
26
  * `askDefaults` leaves the spawn options and travels beside them, so it never
27
27
  * enters the recorded spawn options or the Cassette.
28
28
  * Throws a TypeError when the overrides are not an object, when they name a
29
- * key that is not `name`, `cwd`, `worktree` or `parent`, or when one of those
29
+ * key that is not `name`, `cwd`, `worktree`, `parent`, `fork` or `compact`, or when one of those
30
30
  * carries the wrong type. `parent` stays raw: `resolveParent` checks it.
31
31
  */
32
32
  export function resolveRequest(
@@ -45,6 +45,10 @@ export function resolveRequest(
45
45
  name: topology.name ?? name,
46
46
  ...(topology.cwd === undefined ? {} : { cwd: topology.cwd }),
47
47
  ...(topology.worktree === undefined ? {} : { worktree: topology.worktree }),
48
+ // Presence, not value: `ctx.spawn(def, { fork: undefined })` must reach the
49
+ // spawn gate and be refused there, exactly as the plain-options path is.
50
+ ...("fork" in topology ? { fork: topology.fork } : {}),
51
+ ...("compact" in topology ? { compact: topology.compact } : {}),
48
52
  },
49
53
  parent,
50
54
  askDefaults,
@@ -61,6 +65,11 @@ function definedFields<T extends object>(policy: T): Partial<T> {
61
65
  return copy;
62
66
  }
63
67
 
68
+ /** The shape a fork source has at runtime; the brand itself is type-only. */
69
+ function isHostSource(value: unknown): value is HostSource {
70
+ return typeof value === "object" && value !== null && "kind" in value && value.kind === "host";
71
+ }
72
+
64
73
  function validateOverrides(overrides: unknown): ValidatedOverrides {
65
74
  if (overrides === undefined) return { topology: {}, parent: undefined };
66
75
  if (typeof overrides !== "object" || overrides === null || Array.isArray(overrides)) {
@@ -69,7 +78,14 @@ function validateOverrides(overrides: unknown): ValidatedOverrides {
69
78
  );
70
79
  }
71
80
  for (const key of Object.keys(overrides)) {
72
- if (key !== "name" && key !== "cwd" && key !== "worktree" && key !== "parent") {
81
+ if (
82
+ key !== "name" &&
83
+ key !== "cwd" &&
84
+ key !== "worktree" &&
85
+ key !== "parent" &&
86
+ key !== "fork" &&
87
+ key !== "compact"
88
+ ) {
73
89
  throw new TypeError(
74
90
  `spawn override "${key}" is not allowed: definitions own policy and spawn overrides own topology`,
75
91
  );
@@ -99,6 +115,25 @@ function validateOverrides(overrides: unknown): ValidatedOverrides {
99
115
  }
100
116
  topology.worktree = value;
101
117
  }
118
+ // Both keys are checked here and then carried into the spawn options, where
119
+ // the spawn gate reads them: `host-fork.ts` turns them into the Host Fork
120
+ // facts or refuses them, and `spawn-open.ts` strips both above the prompt
121
+ // render, so neither reaches a rendered, resolved or recorded spawn
122
+ // request (ADR-0068). The check here is a shape check only: a wrong-typed
123
+ // value is a TypeError, and a well-shaped foreign object is FORK_REFUSED
124
+ // at the gate.
125
+ if (key === "fork") {
126
+ if (value !== undefined && !isHostSource(value)) {
127
+ throw new TypeError('spawn override "fork" must be a fork source when present');
128
+ }
129
+ topology.fork = value;
130
+ }
131
+ if (key === "compact") {
132
+ if (value !== undefined && typeof value !== "boolean" && typeof value !== "string") {
133
+ throw new TypeError('spawn override "compact" must be a boolean or a string when present');
134
+ }
135
+ topology.compact = value;
136
+ }
102
137
  }
103
138
  return { topology, parent };
104
139
  }