@yaag/runtime 0.18.2 → 0.20.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/src/agent/spawn-definition-request.ts +108 -0
- package/src/agent/spawn-open.ts +11 -0
- package/src/agent/spawn-profiled.ts +67 -0
- package/src/agent/spawn.ts +15 -95
- package/src/cassette/cassette-schema.ts +1 -0
- package/src/cassette/cassette.ts +2 -0
- package/src/cassette/index.ts +6 -1
- package/src/cassette/replay-divergence.ts +5 -4
- package/src/cassette/resume-identity.ts +61 -2
- package/src/cassette/run-checkpoint.ts +24 -8
- package/src/catalog/agent-describe-fixture.ts +21 -1
- package/src/catalog/agent-describe.ts +10 -3
- package/src/config/config-schema.ts +5 -0
- package/src/config/effective-config.ts +11 -0
- package/src/contract/error-codes.ts +3 -0
- package/src/events.ts +9 -0
- package/src/index.ts +33 -1
- package/src/profile/define-profiles.ts +178 -0
- package/src/profile/index.ts +23 -0
- package/src/profile/lowering.ts +37 -0
- package/src/profile/profile-view.ts +56 -0
- package/src/profile/seal.ts +98 -0
- package/src/profile/select-profile.ts +69 -0
- package/src/profile/use-profile.ts +57 -0
- package/src/public-api.ts +14 -0
- package/src/run/define-run.ts +17 -0
- package/src/run/run-context.ts +7 -0
- package/src/run/run.ts +43 -3
- package/src/summary/summary-agent.ts +14 -0
- package/src/summary/summary.ts +4 -0
package/src/run/run-context.ts
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
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 { Handle, SpawnOptions, SpawnOverrides } from "../contract/index.ts";
|
|
5
|
+
import type { ProfiledDefinition } from "../profile/use-profile.ts";
|
|
5
6
|
|
|
6
7
|
/** What an Orchestration Program is handed. */
|
|
7
8
|
export interface RunContext<Args = unknown> {
|
|
@@ -18,4 +19,10 @@ export interface RunContext<Args = unknown> {
|
|
|
18
19
|
*/
|
|
19
20
|
spawn(options?: SpawnOptions): Promise<Handle>;
|
|
20
21
|
spawn(definition: AgentDefinition, overrides?: SpawnOverrides): Promise<Handle>;
|
|
22
|
+
spawn(profiled: ProfiledDefinition, overrides?: SpawnOverrides): Promise<Handle>;
|
|
23
|
+
/**
|
|
24
|
+
* The Profile this Run activated (ADR-0052). Defined when the program
|
|
25
|
+
* declares Profiles, undefined otherwise.
|
|
26
|
+
*/
|
|
27
|
+
readonly profile?: { readonly id: string };
|
|
21
28
|
}
|
package/src/run/run.ts
CHANGED
|
@@ -4,6 +4,7 @@ import type { Agent } from "../agent/index.ts";
|
|
|
4
4
|
import { makeSpawn } from "../agent/index.ts";
|
|
5
5
|
import {
|
|
6
6
|
assertReplayable,
|
|
7
|
+
assertReplayProfile,
|
|
7
8
|
type Cassette,
|
|
8
9
|
CassetteCollector,
|
|
9
10
|
type CassetteSink,
|
|
@@ -15,6 +16,7 @@ import {
|
|
|
15
16
|
loadCassette,
|
|
16
17
|
type ProgramIdentity,
|
|
17
18
|
prepareRecordDestination,
|
|
19
|
+
profileIdentityWarning,
|
|
18
20
|
programIdentityWarning,
|
|
19
21
|
publishRunCheckpoint,
|
|
20
22
|
type RunCheckpointResult,
|
|
@@ -28,6 +30,7 @@ import {
|
|
|
28
30
|
import { type EffectiveConfig, EMPTY_EFFECTIVE_CONFIG } from "../config/index.ts";
|
|
29
31
|
import { isYaagError, YaagError } from "../errors.ts";
|
|
30
32
|
import type { EventSink, LifecycleEvent, RunOutcome, StampedEventSink } from "../events.ts";
|
|
33
|
+
import { selectProfile } from "../profile/index.ts";
|
|
31
34
|
import { applyEvent, initialSummary, type RunSummary } from "../summary/index.ts";
|
|
32
35
|
import type { TransportFactory } from "../transport/index.ts";
|
|
33
36
|
import {
|
|
@@ -77,6 +80,12 @@ export interface RunOptions {
|
|
|
77
80
|
* config it was not given, and every test stays hermetic.
|
|
78
81
|
*/
|
|
79
82
|
readonly config?: EffectiveConfig;
|
|
83
|
+
/**
|
|
84
|
+
* The Profile id the launch selected; it outranks the id a resumed Cassette
|
|
85
|
+
* stored, the `profile` key of a config file, and the program default
|
|
86
|
+
* (ADR-0052).
|
|
87
|
+
*/
|
|
88
|
+
readonly profile?: string;
|
|
80
89
|
}
|
|
81
90
|
|
|
82
91
|
/**
|
|
@@ -113,6 +122,23 @@ export async function executeRun<Args, Result>(
|
|
|
113
122
|
const replay = await loadReplay(options.replay, programIdentity);
|
|
114
123
|
const resume = await loadResume(options.resume, programIdentity);
|
|
115
124
|
const definition = programDefinition(program);
|
|
125
|
+
// Selected before the Run has an identity, so a PROFILE_NOT_FOUND rejection
|
|
126
|
+
// precedes every Checkpoint publish, run_start, and Agent (ADR-0052).
|
|
127
|
+
const profile = selectProfile({
|
|
128
|
+
profiles: definition.profiles,
|
|
129
|
+
...(options.profile === undefined ? {} : { launch: options.profile }),
|
|
130
|
+
// A resume keeps the Profile of the Run it continues unless the launch names one.
|
|
131
|
+
...(resume?.run.profile === undefined ? {} : { stored: resume.run.profile }),
|
|
132
|
+
...(options.config?.profile === undefined ? {} : { config: options.config.profile }),
|
|
133
|
+
});
|
|
134
|
+
// Strict replay re-executes one recorded invocation, and the Profile is part of it.
|
|
135
|
+
if (replay !== null && options.replay !== undefined) {
|
|
136
|
+
assertReplayProfile(replay, options.replay, profile?.id);
|
|
137
|
+
}
|
|
138
|
+
if (resume !== null && options.resume !== undefined) {
|
|
139
|
+
const warning = profileIdentityWarning(resume, options.resume, profile?.id);
|
|
140
|
+
if (warning !== null) writeRecordingDiagnostic(warning);
|
|
141
|
+
}
|
|
116
142
|
// Collection is universal so every Run can checkpoint, and every Run flushes
|
|
117
143
|
// that collection at each Ask boundary (ADR-0031). Only a stopped Run and a
|
|
118
144
|
// --record Run keep the artifact once the Run settles (ADR-0021). That memory
|
|
@@ -123,7 +149,11 @@ export async function executeRun<Args, Result>(
|
|
|
123
149
|
// Fixed here, so every Ask-boundary flush and the settlement write one file,
|
|
124
150
|
// and so run_start can name it (ADR-0031).
|
|
125
151
|
const destination = options.record ?? join(checkpointDir, checkpointFileName());
|
|
126
|
-
const identity = await resolveRunIdentity(
|
|
152
|
+
const identity = await resolveRunIdentity({
|
|
153
|
+
program: programIdentity,
|
|
154
|
+
args,
|
|
155
|
+
...(profile === undefined ? {} : { profile: profile.id }),
|
|
156
|
+
});
|
|
127
157
|
const checkpoint = { collector, record: options.record, destination, identity };
|
|
128
158
|
try {
|
|
129
159
|
assertArgs<Args>(definition.args, args);
|
|
@@ -164,10 +194,20 @@ export async function executeRun<Args, Result>(
|
|
|
164
194
|
sessionDir: options.sessionDir,
|
|
165
195
|
programFile: options.programFile,
|
|
166
196
|
configExtensions: options.config?.extensions ?? EMPTY_EFFECTIVE_CONFIG.extensions,
|
|
197
|
+
...(profile === undefined ? {} : { profile }),
|
|
167
198
|
});
|
|
168
199
|
|
|
169
|
-
const ctx: RunContext<Args> = {
|
|
170
|
-
|
|
200
|
+
const ctx: RunContext<Args> = {
|
|
201
|
+
args,
|
|
202
|
+
spawn: spawnGate.spawn,
|
|
203
|
+
...(profile === undefined ? {} : { profile: { id: profile.id } }),
|
|
204
|
+
};
|
|
205
|
+
emit({
|
|
206
|
+
type: "run_start",
|
|
207
|
+
program: definition.name ?? "program",
|
|
208
|
+
artifact: destination,
|
|
209
|
+
...(profile === undefined ? {} : { profile: profile.id }),
|
|
210
|
+
});
|
|
171
211
|
|
|
172
212
|
// The program's settlement is held rather than rethrown from a `finally`, so
|
|
173
213
|
// publication can displace it when the checkpoint fails (ADR-0021).
|
|
@@ -37,6 +37,10 @@ interface AgentInfoBase {
|
|
|
37
37
|
readonly parent: string | null;
|
|
38
38
|
/** How the Agent came to be; "spawn" until forking ships. */
|
|
39
39
|
readonly origin: SpawnOrigin;
|
|
40
|
+
/** Id of the active Profile; absent unless this Agent came from a Profiled Definition. */
|
|
41
|
+
readonly profile?: string;
|
|
42
|
+
/** Roles the factory read, in order, duplicates kept; `[]` for none, absent when unprofiled. */
|
|
43
|
+
readonly role?: readonly string[];
|
|
40
44
|
readonly activity: AgentActivity | null;
|
|
41
45
|
readonly tokens: TokenBreakdown | null;
|
|
42
46
|
readonly cost: number | null;
|
|
@@ -160,6 +164,8 @@ export function spawnAgent(
|
|
|
160
164
|
readonly sessionFile?: string;
|
|
161
165
|
readonly parent?: string;
|
|
162
166
|
readonly origin?: SpawnOrigin;
|
|
167
|
+
readonly profile?: string;
|
|
168
|
+
readonly role?: readonly string[];
|
|
163
169
|
},
|
|
164
170
|
at: number | null,
|
|
165
171
|
): AgentRecord {
|
|
@@ -173,6 +179,8 @@ export function spawnAgent(
|
|
|
173
179
|
sessionFile: identity.sessionFile ?? null,
|
|
174
180
|
parent: identity.parent ?? null,
|
|
175
181
|
origin: identity.origin ?? "spawn",
|
|
182
|
+
...(identity.profile === undefined ? {} : { profile: identity.profile }),
|
|
183
|
+
...(identity.role === undefined ? {} : { role: identity.role }),
|
|
176
184
|
stateChangedAt: at,
|
|
177
185
|
};
|
|
178
186
|
}
|
|
@@ -188,6 +196,12 @@ export function spawnAgent(
|
|
|
188
196
|
// it defaults to "spawn" — so the spawn event is its only authority.
|
|
189
197
|
parent: current.parent ?? identity.parent ?? null,
|
|
190
198
|
origin: identity.origin ?? current.origin,
|
|
199
|
+
...((current.profile ?? identity.profile) === undefined
|
|
200
|
+
? {}
|
|
201
|
+
: { profile: current.profile ?? identity.profile }),
|
|
202
|
+
...((current.role ?? identity.role) === undefined
|
|
203
|
+
? {}
|
|
204
|
+
: { role: current.role ?? identity.role }),
|
|
191
205
|
};
|
|
192
206
|
}
|
|
193
207
|
|
package/src/summary/summary.ts
CHANGED
|
@@ -43,6 +43,8 @@ interface RunSummaryBase {
|
|
|
43
43
|
* null for a Run whose CLI is older than that event field.
|
|
44
44
|
*/
|
|
45
45
|
readonly artifact: string | null;
|
|
46
|
+
/** Id of the active Profile, as `run_start` named it; absent without Profiles. */
|
|
47
|
+
readonly profile?: string;
|
|
46
48
|
readonly agents: Readonly<Record<string, AgentInfo>>;
|
|
47
49
|
readonly asksStarted: number;
|
|
48
50
|
readonly asksSettled: number;
|
|
@@ -140,6 +142,8 @@ export function applyEvent(
|
|
|
140
142
|
program: event.program,
|
|
141
143
|
startedAt: at,
|
|
142
144
|
artifact: event.artifact ?? null,
|
|
145
|
+
// Never erased by a later event that carries no id.
|
|
146
|
+
...(event.profile === undefined ? {} : { profile: event.profile }),
|
|
143
147
|
};
|
|
144
148
|
case "agent_spawn":
|
|
145
149
|
return withAgent(summary, event.agent, spawnAgent(summary.agents[event.agent], event, at));
|