@yaag/runtime 0.27.0 → 0.28.2

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yaag/runtime",
3
- "version": "0.27.0",
3
+ "version": "0.28.2",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -0,0 +1,22 @@
1
+ import { YaagError } from "../errors.ts";
2
+
3
+ /**
4
+ * Refuses an Agent name that forges a path segment.
5
+ *
6
+ * The node path of the TUI and the Group path of ADR-0070 both split on "/"
7
+ * and ":", so a name with either character would read as more than one
8
+ * segment. Nothing is sanitized: the name is refused.
9
+ *
10
+ * This is its own module because `defineAgent` calls it, and the vendored
11
+ * author type tree follows value imports (ADR-0045): the name allocator of
12
+ * `agent-names.ts` must stay out of that tree.
13
+ */
14
+ export function assertAgentName(name: string): void {
15
+ if (name.includes("/") || name.includes(":")) {
16
+ throw new YaagError(
17
+ "AGENT_NAME_INVALID",
18
+ `agent name "${name}" is invalid: a name must not contain "/" or ":"`,
19
+ name,
20
+ );
21
+ }
22
+ }
@@ -1,15 +1,19 @@
1
+ import { assertAgentName } from "./agent-name.ts";
2
+
1
3
  /**
2
4
  * Every Lifecycle Event identifies its Agent, so an unnamed Agent still needs a
3
5
  * name and a duplicate is suffixed rather than rejected — spawning in a loop
4
6
  * must not fail.
5
7
  *
6
- * `taken` is mutated: the chosen name is reserved.
8
+ * `taken` is mutated: the chosen name is reserved. A requested name that holds
9
+ * "/" or ":" is refused with `AGENT_NAME_INVALID` before anything is reserved.
7
10
  */
8
11
  export function uniqueAgentName(
9
12
  requested: string | undefined,
10
13
  ordinal: number,
11
14
  taken: Set<string>,
12
15
  ): string {
16
+ if (requested !== undefined) assertAgentName(requested);
13
17
  const base = requested ?? `a${ordinal + 1}`;
14
18
  let name = base;
15
19
  for (let suffix = 2; taken.has(name); suffix++) {
@@ -61,6 +61,8 @@ export interface AgentOptions {
61
61
  readonly askAdmission?: AskAdmission;
62
62
  /** Run-scoped sink of Agent questions; absent when this Agent cannot ask (ADR-0023). */
63
63
  readonly questions?: AgentQuestions;
64
+ /** The Group this Agent sits in (ADR-0070); a fork inherits it. */
65
+ readonly group?: string;
64
66
  }
65
67
 
66
68
  /** One Agent as an Orchestration Program sees it. Lives above the transport seam. */
@@ -85,6 +87,7 @@ export class Agent implements Handle {
85
87
  readonly #fork: ForkSpawner | undefined;
86
88
  readonly #askAdmission: AskAdmission | undefined;
87
89
  readonly #questions: AgentQuestions | undefined;
90
+ readonly #group: string | undefined;
88
91
  #busy = false;
89
92
  #inFlight: AskInFlight | null = null;
90
93
  #incomplete = false;
@@ -110,6 +113,7 @@ export class Agent implements Handle {
110
113
  this.#timing = options.timing;
111
114
  this.#askAdmission = options.askAdmission;
112
115
  this.#questions = options.questions;
116
+ this.#group = options.group;
113
117
  this.#usage = new AgentUsage((snapshot) =>
114
118
  this.#emit({ type: "agent_usage", agent: this.name, ...snapshot }),
115
119
  );
@@ -333,6 +337,7 @@ export class Agent implements Handle {
333
337
  worktree: this.#worktree(),
334
338
  settledAsks: this.#settledAsks,
335
339
  handle: this,
340
+ group: this.#group,
336
341
  },
337
342
  overrides,
338
343
  );
@@ -1,4 +1,5 @@
1
1
  import type { AgentPolicy } from "../contract/index.ts";
2
+ import { assertAgentName } from "./agent-name.ts";
2
3
 
3
4
  export type { ThinkingLevel } from "../contract/index.ts";
4
5
 
@@ -31,6 +32,8 @@ const arrayFields = [
31
32
  /**
32
33
  * Declares an Agent Definition: reusable policy, independent of where it runs.
33
34
  *
35
+ * A name that holds "/" or ":" throws `AGENT_NAME_INVALID`.
36
+ *
34
37
  * Throws a TypeError when `name` is missing or blank, or when `cwd`/`worktree`
35
38
  * appear — those are topology, chosen at spawn time, not baked into a definition.
36
39
  * The config is defensively copied and deep-frozen, so later mutation of the
@@ -42,6 +45,7 @@ export function defineAgent(config: AgentConfig): AgentDefinition {
42
45
  if (typeof config.name !== "string" || config.name.trim() === "") {
43
46
  throw new TypeError("defineAgent: name is required and must be non-empty");
44
47
  }
48
+ assertAgentName(config.name);
45
49
  if ("cwd" in config || "worktree" in config) {
46
50
  throw new TypeError(
47
51
  "defineAgent: cwd and worktree are topology concerns — set them at spawn time, not in the definition",
package/src/agent/fork.ts CHANGED
@@ -22,6 +22,11 @@ export interface ForkSource {
22
22
  readonly settledAsks: number;
23
23
  /** The source Handle itself, which becomes the fork's default Parent Link. */
24
24
  readonly handle: Handle;
25
+ /**
26
+ * The Group of the source; a fork lands in it unless the overrides name
27
+ * another Group (ADR-0070).
28
+ */
29
+ readonly group: string | undefined;
25
30
  }
26
31
 
27
32
  /** Opens one fork. The spawn gate owns it, so a fork walks the normal spawn path. */
@@ -60,6 +65,8 @@ export interface ForkRequest {
60
65
  readonly spawnOptions: SpawnOptions;
61
66
  /** The raw Parent Link, defaulting to the fork source. */
62
67
  readonly parent: unknown;
68
+ /** The source's Group, inherited unless the overrides name another Group. */
69
+ readonly group: string | undefined;
63
70
  /** The fork's own `askDefaults` when given, else the source's; never merged. */
64
71
  readonly askDefaults: AskOptions | undefined;
65
72
  readonly fork: ForkIdentity;
@@ -98,6 +105,9 @@ export function forkRequest(source: ForkSource, overrides?: ForkOptions): ForkRe
98
105
  // one, and this strip is the wall behind that refusal.
99
106
  spawnOptions: withoutForkVerbs({ ...inherited, ...stripUndefined(explicit) }),
100
107
  parent: parent ?? source.handle,
108
+ // No condition here: `treeFields` drops it when the override resolves to a
109
+ // Group position.
110
+ group: source.group,
101
111
  askDefaults: askDefaults ?? source.askDefaults,
102
112
  fork: {
103
113
  kind: "agent",
@@ -15,4 +15,5 @@ export {
15
15
  export { type ForkSource, type ForkSpawner, forkRequest } from "./fork.ts";
16
16
  export { makeSpawn, type SpawnDependencies, type SpawnGate } from "./spawn.ts";
17
17
  export type { OpenAgentRequest } from "./spawn-open.ts";
18
+ export { resolveParent } from "./spawn-parent.ts";
18
19
  export { isSpawnableDefinition } from "./spawnable-definition.ts";
@@ -7,7 +7,7 @@ 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
 
10
- /** Topology overrides after validation; `parent` stays raw for `resolveParent`. */
10
+ /** Topology overrides after validation; `parent` stays raw for `resolveParentPosition`. */
11
11
  type SpawnTopology = Omit<SpawnOverrides, "parent">;
12
12
 
13
13
  type MutableSpawnOverrides = { -readonly [Key in keyof SpawnTopology]: SpawnTopology[Key] };
@@ -27,7 +27,7 @@ interface ValidatedOverrides {
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
29
  * key that is not `name`, `cwd`, `worktree`, `parent`, `fork` or `compact`, or when one of those
30
- * carries the wrong type. `parent` stays raw: `resolveParent` checks it.
30
+ * carries the wrong type. `parent` stays raw: `resolveParentPosition` checks it.
31
31
  */
32
32
  export function resolveRequest(
33
33
  definitionOrOptions: SpawnOptions | AgentDefinition,
@@ -92,7 +92,7 @@ function validateOverrides(overrides: unknown): ValidatedOverrides {
92
92
  }
93
93
  }
94
94
  const topology: MutableSpawnOverrides = {};
95
- // `parent` is never narrowed here: `resolveParent` owns that check, so the
95
+ // `parent` is never narrowed here: `resolveParentPosition` owns that check, so the
96
96
  // error text stays in one place and no unchecked value becomes a Handle.
97
97
  let parent: unknown;
98
98
  for (const [key, value] of Object.entries(overrides)) {
@@ -21,7 +21,7 @@ import type { ForkIdentity, ForkSpawner } from "./fork.ts";
21
21
  import { withoutForkVerbs } from "./host-fork.ts";
22
22
  import type { SpawnDependencies } from "./spawn.ts";
23
23
  import { resolveSpawnExtensions } from "./spawn-extensions.ts";
24
- import { resolveParent } from "./spawn-parent.ts";
24
+ import { resolveParentPosition, treeFields } from "./spawn-parent.ts";
25
25
  import { createSpawnPlan } from "./spawn-plan.ts";
26
26
  import { type RenderedSpawnOptions, renderPolicyPrompt } from "./spawn-request.ts";
27
27
 
@@ -29,8 +29,13 @@ import { type RenderedSpawnOptions, renderPolicyPrompt } from "./spawn-request.t
29
29
  export interface OpenAgentRequest {
30
30
  /** Never carries `parent`: a Handle must not reach the recorded options. */
31
31
  readonly spawnOptions: SpawnOptions;
32
- /** The raw Parent Link option, validated by `resolveParent`. */
32
+ /** The raw Parent Link option, the author's raw Handle or Group, resolved by `resolveParentPosition` inside `openAgent`. */
33
33
  readonly parent: unknown;
34
+ /**
35
+ * The Group path a Fork inherits from its source; an explicit Group `parent`
36
+ * overrides it (ADR-0070).
37
+ */
38
+ readonly group?: string;
34
39
  readonly askDefaults: AskOptions | undefined;
35
40
  /** Definition identity stays separate from a topology-overridden Agent name. */
36
41
  readonly definitionName: string | undefined;
@@ -87,7 +92,8 @@ export async function openAgent(
87
92
  const cwd = resolve(request.spawnOptions.cwd ?? process.cwd());
88
93
  const name = uniqueAgentName(request.spawnOptions.name, deps.agents.length, deps.taken);
89
94
  // Resolved before any transport work, so a bad Parent Link costs nothing.
90
- const parent = resolveParent(request.parent, deps.agents);
95
+ const position = resolveParentPosition(request.parent, deps.agents, deps.isGroup);
96
+ const tree = treeFields(position, request.group);
91
97
  const resolution = normalizeModelResolution(request.spawnOptions);
92
98
  // One history per Agent: its spawn loop and every mid-Ask fallback loop
93
99
  // append to it, so a resolver sees every candidate that already failed.
@@ -124,7 +130,7 @@ export async function openAgent(
124
130
  rendered,
125
131
  ...(extensions === undefined ? {} : { extensions }),
126
132
  ...(request.fork === undefined ? {} : { fork: request.fork }),
127
- ...(parent === undefined ? {} : { parent }),
133
+ ...(Object.keys(tree).length === 0 ? {} : { tree }),
128
134
  sessionDir: deps.sessionDir,
129
135
  ...(request.sessionFile === undefined ? {} : { sessionFile: request.sessionFile }),
130
136
  });
@@ -179,6 +185,7 @@ export async function openAgent(
179
185
  : { modelFallback: { resolution, history, candidate: spawnOptions.model } }),
180
186
  ...(sessionFile === undefined ? {} : { sessionFile }),
181
187
  fork: deps.forkSpawner,
188
+ ...(tree.group === undefined ? {} : { group: tree.group }),
182
189
  ...(deps.askAdmission === undefined ? {} : { askAdmission: deps.askAdmission }),
183
190
  // Only an Agent that may ask gets the sink, so no other Ask can park.
184
191
  ...(deps.questions === undefined || rendered.canAskUser !== true
@@ -196,7 +203,7 @@ export async function openAgent(
196
203
  ...(branch === undefined ? {} : { branch }),
197
204
  ...(sessionFile === undefined ? {} : { sessionFile }),
198
205
  ...(thinking === undefined ? {} : { thinking }),
199
- ...(parent === undefined ? {} : { parent }),
206
+ ...tree,
200
207
  ...(plan.origin === undefined ? {} : { origin: plan.origin }),
201
208
  ...(request.profile === undefined
202
209
  ? {}
@@ -1,3 +1,4 @@
1
+ import type { Group } from "../contract/index.ts";
1
2
  import type { Agent } from "./agent.ts";
2
3
 
3
4
  /**
@@ -8,6 +9,10 @@ import type { Agent } from "./agent.ts";
8
9
  * spawn resolved. Liveness is deliberately not checked — a cleanly exited Agent
9
10
  * remains a valid parent, because the link states tree position, not a
10
11
  * dependency on a live process.
12
+ *
13
+ * This is the one Handle lookup of the Run: `resolveParentPosition` below
14
+ * builds on it for the spawn position, and the Group registry calls it for
15
+ * `ctx.group({ parent })` (ADR-0070).
11
16
  */
12
17
  export function resolveParent(parent: unknown, agents: readonly Agent[]): string | undefined {
13
18
  if (parent === undefined) return undefined;
@@ -19,3 +24,62 @@ export function resolveParent(parent: unknown, agents: readonly Agent[]): string
19
24
  }
20
25
  return known.name;
21
26
  }
27
+
28
+ /**
29
+ * Where a spawn sits in the Run tree (ADR-0070).
30
+ *
31
+ * Two variants: the parent Agent, and a Group, which is a tree position with no
32
+ * process.
33
+ */
34
+ export type ParentPosition =
35
+ | { readonly kind: "agent"; readonly name: string }
36
+ | { readonly kind: "group"; readonly path: string };
37
+
38
+ /** The tree fields one spawn stamps: an Agent parent, a Group, or neither. */
39
+ export interface SpawnTreeFields {
40
+ readonly parent?: string;
41
+ readonly group?: string;
42
+ }
43
+
44
+ /**
45
+ * Resolves a Parent Link to its tree position, or `undefined` when unset.
46
+ *
47
+ * A Group of this Run resolves to a Group position; everything else goes to the
48
+ * Handle lookup, so a foreign `{ kind: "group" }` literal is refused exactly as
49
+ * `ctx.group({ parent })` refuses it.
50
+ */
51
+ export function resolveParentPosition(
52
+ parent: unknown,
53
+ agents: readonly Agent[],
54
+ isGroup?: (value: unknown) => value is Group,
55
+ ): ParentPosition | undefined {
56
+ if (isGroup?.(parent) === true) return { kind: "group", path: parent.path };
57
+ const name = resolveParent(parent, agents);
58
+ return name === undefined ? undefined : { kind: "agent", name };
59
+ }
60
+
61
+ /**
62
+ * Projects a tree position onto the fields a spawn carries.
63
+ *
64
+ * The one place a position becomes `parent`/`group`, shared by the
65
+ * `agent_spawn` event and the open options, so a new variant lands in both at
66
+ * once. A Fork passes its source's Group as `inheritedGroup`: an explicit Group
67
+ * position wins over it, and it never merges.
68
+ */
69
+ export function treeFields(
70
+ position: ParentPosition | undefined,
71
+ inheritedGroup?: string,
72
+ ): SpawnTreeFields {
73
+ const inherited = inheritedGroup === undefined ? {} : { group: inheritedGroup };
74
+ if (position === undefined) return inherited;
75
+ switch (position.kind) {
76
+ case "agent":
77
+ return { parent: position.name, ...inherited };
78
+ case "group":
79
+ return { group: position.path };
80
+ default: {
81
+ const never: never = position;
82
+ throw new TypeError(`unknown parent position: ${JSON.stringify(never)}`);
83
+ }
84
+ }
85
+ }
@@ -10,6 +10,7 @@ import type { ModelSelection } from "../model/index.ts";
10
10
  import type { OpenOptions } from "../transport/index.ts";
11
11
  import type { ResolvedSpawnOptions } from "../types.ts";
12
12
  import type { ForkIdentity } from "./fork.ts";
13
+ import type { SpawnTreeFields } from "./spawn-parent.ts";
13
14
  import {
14
15
  type OpenRequestOptions,
15
16
  openRequest,
@@ -31,7 +32,12 @@ export interface SpawnPlanInput {
31
32
  };
32
33
  /** Fork facts, present only for a fork of an Agent or of the Host Session. */
33
34
  readonly fork?: ForkIdentity;
34
- readonly parent?: string;
35
+ /**
36
+ * The resolved tree fields (Parent Link, Group). Neither one ever becomes
37
+ * argv. `parent` and `group` are both spawn identity; neither ever becomes
38
+ * argv (ADR-0070).
39
+ */
40
+ readonly tree?: SpawnTreeFields;
35
41
  readonly sessionDir: string | undefined;
36
42
  readonly sessionFile?: string;
37
43
  }
@@ -98,7 +104,7 @@ export function createSpawnPlan(input: SpawnPlanInput): SpawnPlan {
98
104
  declaredExtensions: input.extensions.declared,
99
105
  }),
100
106
  ...(input.fork === undefined ? {} : forkFields(input.fork, origin)),
101
- ...(input.parent === undefined ? {} : { parent: input.parent }),
107
+ ...(input.tree === undefined ? {} : { tree: input.tree }),
102
108
  sessionDir: input.sessionDir,
103
109
  ...(input.sessionFile === undefined ? {} : { sessionFile: input.sessionFile }),
104
110
  } satisfies Omit<OpenRequestOptions, "spawnOptions">;
@@ -14,6 +14,7 @@ import {
14
14
  } from "../system-prompt/index.ts";
15
15
  import type { OpenOptions, WorktreeResolution } from "../transport/index.ts";
16
16
  import type { ResolvedSpawnOptions, SpawnOptions } from "../types.ts";
17
+ import type { SpawnTreeFields } from "./spawn-parent.ts";
17
18
 
18
19
  /** Spawn options whose `systemPrompt`, if set, is already a plain string. */
19
20
  export type RenderedSpawnOptions = Omit<SpawnOptions, "systemPrompt"> & {
@@ -104,8 +105,12 @@ export interface OpenRequestOptions {
104
105
  readonly spawnOptions: RenderedSpawnOptions;
105
106
  readonly resolvedExtensionPaths?: readonly string[];
106
107
  readonly declaredExtensions?: readonly string[];
107
- /** Resolved parent Agent name (Parent Link); spawn identity only, never argv. */
108
- readonly parent?: string;
108
+ /**
109
+ * The resolved tree fields (Parent Link, Group). Neither one ever becomes
110
+ * argv. `parent` and `group` are both spawn identity; neither ever becomes
111
+ * argv (ADR-0070).
112
+ */
113
+ readonly tree?: SpawnTreeFields;
109
114
  /** Fork facts (ADR-0044); the first three are spawn identity, the rest are not. */
110
115
  readonly origin?: SpawnOrigin;
111
116
  readonly forkOf?: string;
@@ -198,7 +203,7 @@ export function openRequest(options: OpenRequestOptions): OpenOptions {
198
203
  ...(options.declaredExtensions === undefined || options.declaredExtensions.length === 0
199
204
  ? {}
200
205
  : { declaredExtensions: options.declaredExtensions }),
201
- ...(options.parent === undefined ? {} : { parent: options.parent }),
206
+ ...(options.tree ?? {}),
202
207
  ...(options.origin === undefined ? {} : { origin: options.origin }),
203
208
  ...(options.forkOf === undefined ? {} : { forkOf: options.forkOf }),
204
209
  ...(options.forkAsks === undefined ? {} : { forkAsks: options.forkAsks }),
@@ -216,7 +221,8 @@ export function withSelection(
216
221
  options: RenderedSpawnOptions,
217
222
  selection: ModelSelection,
218
223
  ): ResolvedSpawnOptions {
219
- // `parent` is dropped here as well: a Handle must never reach recorded options.
224
+ // `parent` is dropped here as well: a Handle **or a Group** must never reach
225
+ // recorded options.
220
226
  // `fork` and `compact` are spawn verbs, not properties of the Agent. The spawn
221
227
  // gate already strips them before the render; this line is the second wall, so
222
228
  // an inherited one cannot travel into a resolved or recorded spawn request.
@@ -6,7 +6,7 @@ import type { ActiveProfile, ProfiledDefinition } from "../profile/index.ts";
6
6
  import { isProfiledDefinition } from "../profile/index.ts";
7
7
  import type { AgentQuestions, RunContext } from "../run/index.ts";
8
8
  import type { TransportFactory } from "../transport/index.ts";
9
- import type { Handle, SpawnOptions, SpawnOverrides } from "../types.ts";
9
+ import type { Group, 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";
@@ -32,6 +32,12 @@ export interface SpawnDependencies {
32
32
  readonly askAdmission?: AskAdmission;
33
33
  /** Run-scoped sink of the questions an Agent asks its human (ADR-0023). */
34
34
  readonly questions?: AgentQuestions;
35
+ /**
36
+ * Recognises a Group of this Run as a spawn position (ADR-0070). Everything
37
+ * this refuses goes to the Handle lookup, which names the parent Agent or
38
+ * throws the frozen TypeError.
39
+ */
40
+ readonly isGroup: (value: unknown) => value is Group;
35
41
  }
36
42
 
37
43
  /** A RunContext spawn function that can synchronously stop accepting new Agents. */
@@ -46,6 +52,15 @@ export interface SpawnGate {
46
52
  * then — nor its Agent-question sink, so it can neither be refused nor park.
47
53
  */
48
54
  readonly openInternal: (request: OpenAgentRequest) => Promise<Agent>;
55
+ /** Throws RUN_CLOSED once the gate closed. `ctx.group()` reads the same gate. */
56
+ readonly assertOpen: () => void;
57
+ /**
58
+ * True when an Agent or a root Group of this Run already holds the name.
59
+ * A root Group name joins the Agent name space (ADR-0070, amended 2026-09-11).
60
+ */
61
+ readonly hasName: (name: string) => boolean;
62
+ /** Reserves a root Group's name in the Run-unique Agent-name set (ADR-0070). */
63
+ readonly reserveName: (name: string) => void;
49
64
  close(): void;
50
65
  }
51
66
 
@@ -58,10 +73,13 @@ export interface SpawnGate {
58
73
  export function makeSpawn(deps: SpawnDependencies): SpawnGate {
59
74
  const taken = new Set<string>();
60
75
  let closed = false;
76
+ const assertOpen = (): void => {
77
+ if (closed) throw new YaagError("RUN_CLOSED", "run has already settled");
78
+ };
61
79
  // Declared before use: every Agent this gate opens is handed the same fork
62
80
  // spawner, so a fork is gated and named exactly like a spawn.
63
81
  const forkSpawner: ForkSpawner = async (source, overrides) => {
64
- if (closed) throw new YaagError("RUN_CLOSED", "run has already settled");
82
+ assertOpen();
65
83
  const request = forkRequest(source, overrides);
66
84
  const handle = await openAgent(context, {
67
85
  spawnOptions: request.spawnOptions,
@@ -70,6 +88,7 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
70
88
  definitionName: undefined,
71
89
  inheritedPrompt: request.inheritedPrompt,
72
90
  fork: request.fork,
91
+ ...(request.group === undefined ? {} : { group: request.group }),
73
92
  });
74
93
  if (request.compact !== undefined && request.compact !== false) {
75
94
  await handle.compact(typeof request.compact === "string" ? request.compact : undefined);
@@ -85,7 +104,7 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
85
104
  definitionOrOptions: SpawnOptions | AgentDefinition | ProfiledDefinition = {},
86
105
  overrides?: SpawnOverrides,
87
106
  ): Promise<Handle> => {
88
- if (closed) throw new YaagError("RUN_CLOSED", "run has already settled");
107
+ assertOpen();
89
108
  // The Agent Definition branch is explicit, although `resolveRequest` takes
90
109
  // a plain options object too: it states the three accepted shapes in order.
91
110
  if (isAgentDefinition(definitionOrOptions)) {
@@ -114,6 +133,11 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
114
133
  };
115
134
  return {
116
135
  spawn,
136
+ assertOpen,
137
+ hasName: (name: string): boolean => taken.has(name),
138
+ reserveName: (name: string): void => {
139
+ taken.add(name);
140
+ },
117
141
  // The concrete Agent, not a Handle: the Run reaps its own machinery itself,
118
142
  // and `close()` lives below the author surface.
119
143
  openInternal: (request: OpenAgentRequest): Promise<Agent> =>
@@ -52,6 +52,7 @@ const CassetteSpawnSchema = Type.Object({
52
52
  hostHash: Type.Optional(Type.String()),
53
53
  forkOf: Type.Optional(Type.String()),
54
54
  forkAsks: Type.Optional(Type.Number()),
55
+ group: Type.Optional(Type.String()),
55
56
  });
56
57
 
57
58
  const ContextSpawnSchema = Type.Object({
@@ -167,6 +167,11 @@ export interface CassetteSpawn {
167
167
  readonly forkOf?: string;
168
168
  /** Settled Asks of the fork source at the fork point. Spawn identity. */
169
169
  readonly forkAsks?: number;
170
+ /**
171
+ * Path of the Group this Agent was spawned into (ADR-0070). Spawn identity;
172
+ * absent for an Agent at its parent's level and for older Cassettes.
173
+ */
174
+ readonly group?: string;
170
175
  }
171
176
 
172
177
  /** The frames attributed to one Ask marker. */
@@ -102,6 +102,12 @@ const FIELD_TABLE = [
102
102
  // row keeps its hash, and never argv. The copy path (`forkSession`) stays a
103
103
  // launch row below, because that path is machine-specific.
104
104
  { field: "hostHash", kind: "identity", hash: "optional", argv: "never" },
105
+ // The Group a spawn landed in (ADR-0070). Spawn identity: a program that
106
+ // moved an Agent to another Group diverges at that spawn, and a resume goes
107
+ // live there. Omitted when undefined, so every Cassette recorded before
108
+ // Groups keeps its hash. Never argv, and never Ask-marker context: a Group
109
+ // is tree position, not Ask behaviour.
110
+ { field: "group", kind: "identity", hash: "optional", argv: "never" },
105
111
  ] as const satisfies readonly SpawnField[];
106
112
 
107
113
  /** The table as a uniform row list; `FIELD_TABLE` keeps the literal field names. */
@@ -129,8 +135,10 @@ const HASH_ORDER = [
129
135
  "origin",
130
136
  "forkOf",
131
137
  "forkAsks",
132
- // Appended last: an absent `hostHash` adds no key, so no recorded hash moves.
138
+ // The rows below are appended, never inserted: each one is optional, so an
139
+ // absent value adds no key and no recorded hash moves.
133
140
  "hostHash",
141
+ "group",
134
142
  ] as const;
135
143
 
136
144
  /** The key order of the recorded spawn, frozen for the same reason. */
@@ -153,8 +161,10 @@ const RECORD_ORDER = [
153
161
  "forkOf",
154
162
  "forkAsks",
155
163
  "worktree",
156
- // Appended last, for the same reason as in `HASH_ORDER`.
164
+ // The rows below are appended, never inserted, for the same reason as in
165
+ // `HASH_ORDER`.
157
166
  "hostHash",
167
+ "group",
158
168
  ] as const;
159
169
 
160
170
  const BY_FIELD = new Map(SPAWN_FIELDS.map((row) => [row.field, row]));
@@ -55,6 +55,9 @@ 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
+ | "AGENT_NAME_INVALID" // an Agent name contains "/" or ":"
59
+ | "GROUP_NAME_INVALID" // a Group name is empty, or contains "/" or ":" (ADR-0070)
60
+ | "GROUP_EXISTS" // a Group of that name is already open under that parent, or an Agent holds that root name (ADR-0070)
58
61
  | "PAUSE_REFUSED" // two pause questions claim one id (ADR-0022)
59
62
  | "RECORD_PATH_UNUSABLE" // the --record directory could not be created at Run start
60
63
  | "HOST_SESSION_UNUSABLE" // the host session file cannot start a Run: missing, unreadable, empty, header-less, ill-formed, without the named tool call, or without a tool call id on a live run
@@ -0,0 +1,38 @@
1
+ /**
2
+ * The Group declarations of the author contract (ADR-0070).
3
+ *
4
+ * Types only, and no import outside this directory (ADR-0045). A Group is a
5
+ * tree position with no process, so it lives here and not in
6
+ * `spawn-options.ts`, which is the home of the spawn verbs.
7
+ */
8
+
9
+ import type { Handle } from "./handle.ts";
10
+
11
+ /** Not exported, so a Group is unreachable outside this module. */
12
+ declare const group: unique symbol;
13
+
14
+ /**
15
+ * One Group of the Run tree.
16
+ *
17
+ * A program reads it back from `ctx.group()` and passes it on; it cannot build
18
+ * one, because the brand key is private to this module. It stays type-only, so
19
+ * the author declaration tree carries no value (ADR-0045).
20
+ */
21
+ export interface Group {
22
+ readonly kind: "group";
23
+ readonly name: string;
24
+ /**
25
+ * The `/`-joined chain from the top of the Group's branch down; an Agent name
26
+ * is the first segment when the Group sits under an Agent (ADR-0070).
27
+ */
28
+ readonly path: string;
29
+ readonly [group]: true;
30
+ }
31
+
32
+ /** What `ctx.group()` accepts: a name, and the position the Group opens at. */
33
+ export interface GroupOptions {
34
+ /** Must not be empty, and must not contain `/` or `:`. */
35
+ readonly name: string;
36
+ /** A Group or a Handle of this Run; absent opens a root Group. */
37
+ readonly parent?: Handle | Group;
38
+ }
@@ -24,6 +24,7 @@ export type {
24
24
  ModelResolutionOutcome,
25
25
  YaagErrorCode,
26
26
  } from "./error-codes.ts";
27
+ export type { Group, GroupOptions } from "./group.ts";
27
28
  export type { AskOptions, Handle, StructuredAskOptions } from "./handle.ts";
28
29
  export type {
29
30
  ModelError,
@@ -5,6 +5,7 @@
5
5
  */
6
6
 
7
7
  import type { AgentPolicy } from "./agent-policy.ts";
8
+ import type { Group } from "./group.ts";
8
9
  import type { Handle } from "./handle.ts";
9
10
  import type { ThinkingLevel } from "./model-spec.ts";
10
11
 
@@ -35,10 +36,12 @@ export interface SpawnOptions extends AgentPolicy {
35
36
  /** Request a fresh Git worktree. The requested cwd remains the base until spawn resolves. */
36
37
  readonly worktree?: boolean;
37
38
  /**
38
- * Names this Agent's parent in the Run tree (Parent Link). Data only: it is
39
- * no conversation channel and no lifetime rule.
39
+ * Names this Agent's position in the Run tree (Parent Link). Data only: it is
40
+ * no conversation channel and no lifetime rule. A Handle names a parent
41
+ * Agent, a Group names a position with no process (ADR-0070); a spawn carries
42
+ * at most one of the two.
40
43
  */
41
- readonly parent?: Handle;
44
+ readonly parent?: Handle | Group;
42
45
  /** Fork the Host Session's conversation instead of starting a fresh one. */
43
46
  readonly fork?: HostSource;
44
47
  /** true = pi's default compaction; a string = pi custom instructions. */
@@ -84,6 +87,9 @@ export interface ResolvedSpawnOptions
84
87
  * names one. The fork source becomes the child's default `parent`. An
85
88
  * `askDefaults` given here replaces the source's object; it does not merge.
86
89
  *
90
+ * A fork keeps its source's Group unless `parent` names another Group
91
+ * (ADR-0070).
92
+ *
87
93
  * The inherited model is the concrete one the source settled on, so the child
88
94
  * never re-runs the source's fallback list; `fork({ model })` is the way out.
89
95
  * A fork of a Worktree Agent gets its own fresh worktree, branched from the
@@ -103,8 +109,12 @@ export interface SpawnOverrides {
103
109
  readonly cwd?: string;
104
110
  /** Request a fresh Git worktree. */
105
111
  readonly worktree?: boolean;
106
- /** Names this Agent's parent in the Run tree (Parent Link). Data only. */
107
- readonly parent?: Handle;
112
+ /**
113
+ * Names this Agent's position in the Run tree (Parent Link). Data only. A
114
+ * Handle names a parent Agent, a Group names a position with no process
115
+ * (ADR-0070); a spawn carries at most one of the two.
116
+ */
117
+ readonly parent?: Handle | Group;
108
118
  /** Fork the Host Session's conversation instead of starting a fresh one. */
109
119
  readonly fork?: HostSource;
110
120
  /** true = pi's default compaction; a string = pi custom instructions. */
package/src/events.ts CHANGED
@@ -99,6 +99,12 @@ export type LifecycleEventBody =
99
99
  readonly sessionFile?: string;
100
100
  /** Resolved name of the Agent named as this Agent's parent (Parent Link). */
101
101
  readonly parent?: string;
102
+ /**
103
+ * Path of the Group this Agent sits in (ADR-0070). `parent` names an
104
+ * Agent, `group` names a Group; a plain spawn carries at most one of the
105
+ * two, and a Fork inherits `group` beside its source's `parent`.
106
+ */
107
+ readonly group?: string;
102
108
  /** How the Agent came to be; absent means "spawn". */
103
109
  readonly origin?: SpawnOrigin;
104
110
  /**
@@ -112,6 +118,18 @@ export type LifecycleEventBody =
112
118
  /** Roles the factory read, in order, duplicates kept; `[]` for none. */
113
119
  readonly role?: readonly string[];
114
120
  }
121
+ | {
122
+ /**
123
+ * A Group this Run opened (ADR-0070). It owns no process and it never
124
+ * closes. `path` is the `/`-joined name chain, so the parent Group is
125
+ * implicit in it. `parent` is the Agent name when the Group sits under an
126
+ * Agent, and it is absent in all other cases.
127
+ */
128
+ readonly type: "group_open";
129
+ readonly path: string;
130
+ readonly name: string;
131
+ readonly parent?: string;
132
+ }
115
133
  | {
116
134
  readonly type: "ask_start";
117
135
  readonly agent: string;
package/src/index.ts CHANGED
@@ -191,6 +191,7 @@ export type {
191
191
  CompactionInfo,
192
192
  EndedRunSummary,
193
193
  ExitedAgentInfo,
194
+ GroupInfo,
194
195
  IdleAgentInfo,
195
196
  ModelFallbackInfo,
196
197
  NodeInfo,
@@ -242,6 +243,8 @@ export type {
242
243
  AgentPolicy,
243
244
  AskOptions,
244
245
  ForkOptions,
246
+ Group,
247
+ GroupOptions,
245
248
  Handle,
246
249
  HostSource,
247
250
  LiteralPromptText,
package/src/public-api.ts CHANGED
@@ -21,6 +21,8 @@ export type {
21
21
  export type {
22
22
  AgentPolicy,
23
23
  AskOptions,
24
+ Group,
25
+ GroupOptions,
24
26
  Handle,
25
27
  LiteralPromptText,
26
28
  PromptAudience,
@@ -0,0 +1,111 @@
1
+ /**
2
+ * The Groups one Run opened (ADR-0070).
3
+ *
4
+ * A Group is a tree position with no process: it opens, it never closes, and it
5
+ * emits one `group_open` event. The registry keeps the sibling names, so a
6
+ * repeat name under one parent is refused, and a root Group's name is reserved
7
+ * in the Run-unique Agent-name set, so a root Group path can never collide with
8
+ * a Group under an Agent of the same name.
9
+ *
10
+ * Its dependencies are injected rather than imported, so this file stays pure
11
+ * and it adds no `run/` to `agent/` import.
12
+ */
13
+
14
+ import type { Group, GroupOptions } from "../contract/index.ts";
15
+ import { YaagError } from "../errors.ts";
16
+ import type { EventSink } from "../events.ts";
17
+
18
+ /** The parent key of a root Group. A symbol, so no name can collide with it. */
19
+ const ROOT = Symbol("root");
20
+
21
+ export interface GroupRegistry {
22
+ /** The `ctx.group` implementation; synchronous by contract. */
23
+ readonly group: (options: GroupOptions) => Group;
24
+ /** True for a Group this registry made. */
25
+ readonly holds: (value: unknown) => value is Group;
26
+ }
27
+
28
+ export interface GroupDependencies {
29
+ readonly emit: EventSink;
30
+ /** Throws RUN_CLOSED once the spawn gate closed; the same gate a spawn reads. */
31
+ readonly assertOpen: () => void;
32
+ /** The shared Handle lookup: an Agent name, or the frozen TypeError. */
33
+ readonly resolveAgentParent: (parent: unknown) => string | undefined;
34
+ /** True when an Agent or a root Group of this Run already holds the name. */
35
+ readonly hasName: (name: string) => boolean;
36
+ /** Reserves a root Group name in the Run-unique Agent-name set. */
37
+ readonly reserveName: (name: string) => void;
38
+ }
39
+
40
+ /** Builds the Run-scoped Group registry behind `ctx.group`. */
41
+ export function createGroups(deps: GroupDependencies): GroupRegistry {
42
+ const mine = new Set<Group>();
43
+ const siblings = new Map<object | typeof ROOT, Set<string>>();
44
+ const holds = (value: unknown): value is Group => mine.has(value as Group);
45
+
46
+ const group = (options: GroupOptions): Group => {
47
+ deps.assertOpen();
48
+ const name = options.name;
49
+ if (name === "" || name.includes("/") || name.includes(":")) {
50
+ throw new YaagError(
51
+ "GROUP_NAME_INVALID",
52
+ `group name "${name}" is invalid: a name must not be empty and must not contain "/" or ":"`,
53
+ );
54
+ }
55
+ const parent = options.parent;
56
+ // A Group of this Run is a position. Everything else goes to the Handle
57
+ // lookup, which refuses a foreign value the same way a spawn refuses it.
58
+ const parentGroup = holds(parent) ? parent : undefined;
59
+ const agent = parentGroup === undefined ? deps.resolveAgentParent(parent) : undefined;
60
+
61
+ const key: object | typeof ROOT = parentGroup ?? parent ?? ROOT;
62
+ const taken = siblings.get(key) ?? new Set<string>();
63
+ if (taken.has(name)) {
64
+ throw new YaagError(
65
+ "GROUP_EXISTS",
66
+ `group "${name}" is already open under ${parentLabel(parentGroup, agent)}`,
67
+ );
68
+ }
69
+ const isRoot = parentGroup === undefined && agent === undefined;
70
+ if (isRoot && deps.hasName(name)) {
71
+ throw new YaagError(
72
+ "GROUP_EXISTS",
73
+ `group "${name}" is already open: agent "${name}" holds that name`,
74
+ );
75
+ }
76
+ // A root name lands in both sets on purpose: the sibling set alone answers a
77
+ // repeat root Group with its own message, so the two GROUP_EXISTS messages
78
+ // stay distinct, and the Agent-name set makes a later spawn take a suffix.
79
+ taken.add(name);
80
+ siblings.set(key, taken);
81
+ if (isRoot) deps.reserveName(name);
82
+
83
+ // A Group under an Agent starts its chain with the Agent name, so no two
84
+ // Groups of one Run share a path. `group_open.parent` still names the Agent,
85
+ // so a reader never parses the path (ADR-0070, amended 2026-09-11).
86
+ const path =
87
+ parentGroup !== undefined
88
+ ? `${parentGroup.path}/${name}`
89
+ : agent === undefined
90
+ ? name
91
+ : `${agent}/${name}`;
92
+ // The one documented cast, as `host-session.ts` brands a HostSource.
93
+ const value = { kind: "group", name, path } as Group;
94
+ mine.add(value);
95
+ deps.emit({
96
+ type: "group_open",
97
+ path,
98
+ name,
99
+ ...(agent === undefined ? {} : { parent: agent }),
100
+ });
101
+ return value;
102
+ };
103
+
104
+ return { group, holds };
105
+ }
106
+
107
+ function parentLabel(parentGroup: Group | undefined, agent: string | undefined): string {
108
+ if (parentGroup !== undefined) return `group "${parentGroup.path}"`;
109
+ if (agent !== undefined) return `agent "${agent}"`;
110
+ return "the run";
111
+ }
package/src/run/index.ts CHANGED
@@ -11,6 +11,7 @@ export {
11
11
  type ProgramDefinition,
12
12
  programDefinition,
13
13
  } from "./define-run.ts";
14
+ export { createGroups, type GroupDependencies, type GroupRegistry } from "./groups.ts";
14
15
  export {
15
16
  adoptedHostSource,
16
17
  HOST_FORK_TOOL_RESULT_TEXT,
@@ -2,6 +2,8 @@
2
2
  // declaration tree must not pull the `agent/` barrel (ADR-0045).
3
3
  import type { AgentDefinition } from "../agent/define-agent.ts";
4
4
  import type {
5
+ Group,
6
+ GroupOptions,
5
7
  Handle,
6
8
  HostSource,
7
9
  SpawnableDefinition,
@@ -29,6 +31,16 @@ export interface RunContext<Args = unknown> {
29
31
  spawn(profiled: ProfiledDefinition, overrides?: SpawnOverrides): Promise<Handle>;
30
32
  /** Last on purpose: a union-typed value, e.g. what a Catalog Resolve gave back (ADR-0053). */
31
33
  spawn(definition: SpawnableDefinition, overrides?: SpawnOverrides): Promise<Handle>;
34
+ /**
35
+ * Opens one Group of the Run tree (ADR-0070).
36
+ *
37
+ * The call is synchronous, it emits one `group_open` event, and it gives back
38
+ * a tree position, not a Handle: a Group owns no process and it never closes.
39
+ * `parent` is a Group or a Handle of this Run; absent opens a root Group. An
40
+ * empty name, or a name with `/` or `:`, fails with `GROUP_NAME_INVALID`; a
41
+ * repeat name under one parent fails with `GROUP_EXISTS`.
42
+ */
43
+ group(options: GroupOptions): Group;
32
44
  /**
33
45
  * Asks the user one question and pauses the Run (ADR-0022).
34
46
  *
package/src/run/run.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import { join } from "node:path";
2
2
  import type { TSchema } from "typebox";
3
3
  import type { Agent } from "../agent/index.ts";
4
- import { makeSpawn } from "../agent/index.ts";
4
+ import { makeSpawn, resolveParent } from "../agent/index.ts";
5
5
  import {
6
6
  assertReplayable,
7
7
  assertReplayProfile,
@@ -45,10 +45,12 @@ import {
45
45
  skillRestrictionTransport,
46
46
  worktreeTransport,
47
47
  } from "../transport/index.ts";
48
+ import type { Group } from "../types.ts";
48
49
  import { createAgentQuestions, seedFromResume } from "./agent-questions.ts";
49
50
  import { type AnswerLedger, createAnswerLedger, emptyAnswerLedger } from "./answers.ts";
50
51
  import { validateArgs } from "./args-validation.ts";
51
52
  import { type OrchestrationProgram, programDefinition } from "./define-run.ts";
53
+ import { createGroups } from "./groups.ts";
52
54
  import { adoptedHostSource, type HostSessionOptions, prepareHostSource } from "./host-session.ts";
53
55
  import { createPauseRequests } from "./pause-questions.ts";
54
56
  import type { RunContext } from "./run-context.ts";
@@ -293,13 +295,27 @@ export async function executeRun<Args, Result>(
293
295
  // the Run the reader sees in the Run record.
294
296
  runName: definition.name ?? "program",
295
297
  configExtensions: options.config?.extensions ?? EMPTY_EFFECTIVE_CONFIG.extensions,
298
+ // Late-bound on purpose, like `agents` below: the registry is built under
299
+ // this call, and no spawn can run before the program starts.
300
+ isGroup: (value): value is Group => groups.holds(value),
296
301
  ...(profile === undefined ? {} : { profile }),
297
302
  });
298
303
 
304
+ // `agents` is the live array the spawn gate mutates, so a Handle spawned
305
+ // later is a valid Group parent.
306
+ const groups = createGroups({
307
+ emit,
308
+ assertOpen: spawnGate.assertOpen,
309
+ resolveAgentParent: (parent) => resolveParent(parent, agents),
310
+ hasName: spawnGate.hasName,
311
+ reserveName: spawnGate.reserveName,
312
+ });
313
+
299
314
  const pauseRequests = createPauseRequests(answers);
300
315
  const ctx: RunContext<Args> = {
301
316
  args,
302
317
  spawn: spawnGate.spawn,
318
+ group: groups.group,
303
319
  askUser: pauseRequests.askUser,
304
320
  pause: pauseRequests.pause,
305
321
  ...(profile === undefined ? {} : { profile: { id: profile.id } }),
@@ -23,3 +23,4 @@ export type {
23
23
  NodeInfo,
24
24
  SpawnOrigin,
25
25
  } from "./summary-agent.ts";
26
+ export type { GroupInfo } from "./summary-group.ts";
@@ -35,6 +35,8 @@ interface AgentInfoBase {
35
35
  readonly sessionFile: string | null;
36
36
  /** The Agent named as this one's parent (Parent Link), or null for a root Agent. */
37
37
  readonly parent: string | null;
38
+ /** The Group this Agent sits in, or null when it sits at its parent's level. */
39
+ readonly group: string | null;
38
40
  /** How the Agent came to be; "spawn" until forking ships. */
39
41
  readonly origin: SpawnOrigin;
40
42
  /** Id of the active Profile; absent unless this Agent came from a Profiled Definition. */
@@ -129,6 +131,7 @@ export function placeholderAgent(): IdleAgentInfo {
129
131
  branch: null,
130
132
  sessionFile: null,
131
133
  parent: null,
134
+ group: null,
132
135
  origin: "spawn",
133
136
  compactions: 0,
134
137
  lastCompaction: null,
@@ -163,6 +166,7 @@ export function spawnAgent(
163
166
  readonly branch?: string;
164
167
  readonly sessionFile?: string;
165
168
  readonly parent?: string;
169
+ readonly group?: string;
166
170
  readonly origin?: SpawnOrigin;
167
171
  readonly profile?: string;
168
172
  readonly role?: readonly string[];
@@ -178,6 +182,7 @@ export function spawnAgent(
178
182
  branch: identity.branch ?? null,
179
183
  sessionFile: identity.sessionFile ?? null,
180
184
  parent: identity.parent ?? null,
185
+ group: identity.group ?? null,
181
186
  origin: identity.origin ?? "spawn",
182
187
  ...(identity.profile === undefined ? {} : { profile: identity.profile }),
183
188
  ...(identity.role === undefined ? {} : { role: identity.role }),
@@ -195,6 +200,7 @@ export function spawnAgent(
195
200
  // spawn only fills what is still missing. `origin` has no missing value —
196
201
  // it defaults to "spawn" — so the spawn event is its only authority.
197
202
  parent: current.parent ?? identity.parent ?? null,
203
+ group: current.group ?? identity.group ?? null,
198
204
  origin: identity.origin ?? current.origin,
199
205
  ...((current.profile ?? identity.profile) === undefined
200
206
  ? {}
@@ -0,0 +1,31 @@
1
+ /**
2
+ * The Group table of the Run Summary (ADR-0070).
3
+ *
4
+ * A Group owns no process and never closes, so the fold has one operation:
5
+ * insert.
6
+ */
7
+
8
+ /** What one `group_open` event tells an observer about a Group. */
9
+ export interface GroupInfo {
10
+ readonly name: string;
11
+ /** The parent Agent name when the Group sits under an Agent; null in all other cases. */
12
+ readonly parent: string | null;
13
+ readonly openedAt: number | null;
14
+ }
15
+
16
+ /**
17
+ * Inserts one Group, keyed by its path. A Group path is unique in one Run
18
+ * (ADR-0070), so a repeated path can only be a repeated event: it is a no-op
19
+ * and the same object comes back.
20
+ */
21
+ export function openGroup(
22
+ groups: Readonly<Record<string, GroupInfo>>,
23
+ event: { readonly path: string; readonly name: string; readonly parent?: string },
24
+ at: number | null,
25
+ ): Readonly<Record<string, GroupInfo>> {
26
+ if (groups[event.path] !== undefined) return groups;
27
+ return {
28
+ ...groups,
29
+ [event.path]: { name: event.name, parent: event.parent ?? null, openedAt: at },
30
+ };
31
+ }
@@ -14,6 +14,7 @@ import {
14
14
  totalsFromAgents,
15
15
  } from "./summary-agent.ts";
16
16
  import { applyModelFallback } from "./summary-fallbacks.ts";
17
+ import { type GroupInfo, openGroup } from "./summary-group.ts";
17
18
  import { applyAgentModel } from "./summary-model.ts";
18
19
  import { applyNodeUpdate } from "./summary-nodes.ts";
19
20
 
@@ -30,6 +31,7 @@ export type {
30
31
  NodeInfo,
31
32
  SpawnOrigin,
32
33
  } from "./summary-agent.ts";
34
+ export type { GroupInfo } from "./summary-group.ts";
33
35
 
34
36
  /** The observer-facing lifecycle state of a Run. */
35
37
  export type RunState = "running" | "ended";
@@ -46,6 +48,11 @@ interface RunSummaryBase {
46
48
  /** Id of the active Profile, as `run_start` named it; absent without Profiles. */
47
49
  readonly profile?: string;
48
50
  readonly agents: Readonly<Record<string, AgentInfo>>;
51
+ /**
52
+ * The Groups this Run opened, keyed by Group path (ADR-0070), so an observer
53
+ * that holds a Summary alone can rebuild the tree.
54
+ */
55
+ readonly groups: Readonly<Record<string, GroupInfo>>;
49
56
  readonly asksStarted: number;
50
57
  readonly asksSettled: number;
51
58
  readonly cost: number;
@@ -112,6 +119,7 @@ export function initialSummary(): RunningRunSummary {
112
119
  startedAt: null,
113
120
  artifact: null,
114
121
  agents: {},
122
+ groups: {},
115
123
  asksStarted: 0,
116
124
  asksSettled: 0,
117
125
  cost: 0,
@@ -152,6 +160,10 @@ export function applyEvent(
152
160
  };
153
161
  case "agent_spawn":
154
162
  return withAgent(summary, event.agent, spawnAgent(summary.agents[event.agent], event, at));
163
+ case "group_open": {
164
+ const groups = openGroup(summary.groups, event, at);
165
+ return groups === summary.groups ? summary : { ...summary, groups };
166
+ }
155
167
  case "ask_start":
156
168
  return withAgent(
157
169
  { ...summary, asksStarted: summary.asksStarted + 1 },
@@ -252,6 +252,13 @@ export interface OpenOptions {
252
252
  * Spawn identity only: it never becomes argv.
253
253
  */
254
254
  readonly parent?: string;
255
+ /**
256
+ * Path of the Group this Agent was spawned into (ADR-0070).
257
+ *
258
+ * Spawn identity: the Cassette records it and a replay compares it. It never
259
+ * becomes argv (ADR-0070).
260
+ */
261
+ readonly group?: string;
255
262
  /** Session storage directory. Used by the e2e suite to stay out of ~/.pi (ticket 06). */
256
263
  readonly sessionDir?: string;
257
264
  /** Resumes an existing pi session, translated to `--session <path>`. */
package/src/types.ts CHANGED
@@ -10,6 +10,8 @@ export type {
10
10
  AskOptions,
11
11
  CompactionResult,
12
12
  ForkOptions,
13
+ Group,
14
+ GroupOptions,
13
15
  Handle,
14
16
  HostSource,
15
17
  LiteralPromptText,