@yaag/runtime 0.18.2 → 0.19.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.
@@ -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(programIdentity, args);
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> = { args, spawn: spawnGate.spawn };
170
- emit({ type: "run_start", program: definition.name ?? "program", artifact: destination });
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
 
@@ -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));