@yaag/runtime 0.27.0 → 0.28.1
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 +1 -1
- package/src/agent/agent-name.ts +22 -0
- package/src/agent/agent-names.ts +5 -1
- package/src/agent/agent.ts +5 -0
- package/src/agent/define-agent.ts +4 -0
- package/src/agent/fork.ts +10 -0
- package/src/agent/index.ts +1 -0
- package/src/agent/spawn-definition-request.ts +3 -3
- package/src/agent/spawn-open.ts +12 -5
- package/src/agent/spawn-parent.ts +64 -0
- package/src/agent/spawn-plan.ts +8 -2
- package/src/agent/spawn-request.ts +10 -4
- package/src/agent/spawn.ts +27 -3
- package/src/cassette/cassette-schema.ts +1 -0
- package/src/cassette/cassette.ts +5 -0
- package/src/cassette/spawn-identity.ts +12 -2
- package/src/contract/error-codes.ts +3 -0
- package/src/contract/group.ts +38 -0
- package/src/contract/index.ts +1 -0
- package/src/contract/spawn-options.ts +15 -5
- package/src/events.ts +18 -0
- package/src/index.ts +3 -0
- package/src/public-api.ts +2 -0
- package/src/run/groups.ts +111 -0
- package/src/run/index.ts +1 -0
- package/src/run/run-context.ts +12 -0
- package/src/run/run.ts +17 -1
- package/src/summary/index.ts +1 -0
- package/src/summary/summary-agent.ts +6 -0
- package/src/summary/summary-group.ts +31 -0
- package/src/summary/summary.ts +12 -0
- package/src/transport/transport.ts +7 -0
- package/src/types.ts +2 -0
package/package.json
CHANGED
|
@@ -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
|
+
}
|
package/src/agent/agent-names.ts
CHANGED
|
@@ -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++) {
|
package/src/agent/agent.ts
CHANGED
|
@@ -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",
|
package/src/agent/index.ts
CHANGED
|
@@ -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 `
|
|
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: `
|
|
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: `
|
|
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)) {
|
package/src/agent/spawn-open.ts
CHANGED
|
@@ -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 {
|
|
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,
|
|
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
|
|
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
|
-
...(
|
|
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
|
-
...
|
|
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
|
+
}
|
package/src/agent/spawn-plan.ts
CHANGED
|
@@ -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
|
-
|
|
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.
|
|
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
|
-
/**
|
|
108
|
-
|
|
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.
|
|
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
|
|
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.
|
package/src/agent/spawn.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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({
|
package/src/cassette/cassette.ts
CHANGED
|
@@ -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
|
-
//
|
|
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
|
-
//
|
|
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
|
+
}
|
package/src/contract/index.ts
CHANGED
|
@@ -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
|
|
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
|
-
/**
|
|
107
|
-
|
|
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
|
@@ -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
package/src/run/run-context.ts
CHANGED
|
@@ -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 } }),
|
package/src/summary/index.ts
CHANGED
|
@@ -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
|
+
}
|
package/src/summary/summary.ts
CHANGED
|
@@ -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>`. */
|