@yaag/runtime 0.21.0 → 0.23.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/agent.ts +52 -2
- package/src/agent/spawn-open.ts +1 -0
- package/src/agent/spawn-profiled.ts +1 -1
- package/src/agent/spawn.ts +3 -0
- package/src/ask-contract/ask-limit.ts +2 -4
- package/src/ask-contract/index.ts +2 -1
- package/src/ask-contract/wrap-up-steer.ts +17 -0
- package/src/cassette/checkpoint-dir.ts +3 -3
- package/src/cassette/index.ts +1 -0
- package/src/cassette/run-checkpoint.ts +17 -5
- package/src/catalog/registry-schema.ts +6 -6
- package/src/config/config-paths.ts +3 -3
- package/src/contract/error-codes.ts +2 -1
- package/src/control/ask-admission.ts +24 -0
- package/src/control/control-commands.ts +300 -0
- package/src/control/index.ts +31 -0
- package/src/control/pause-drain.ts +105 -0
- package/src/control/run-controller.ts +88 -0
- package/src/events.ts +40 -0
- package/src/index.ts +23 -1
- package/src/profile/define-profiles.ts +121 -26
- package/src/profile/index.ts +10 -1
- package/src/profile/lowering.ts +30 -0
- package/src/profile/profile-view.ts +24 -13
- package/src/profile/role.ts +117 -0
- package/src/profile/use-profile.ts +32 -12
- package/src/public-api.ts +6 -1
- package/src/run/run-settlement.ts +93 -0
- package/src/run/run.ts +83 -32
- package/src/summary/summary.ts +6 -0
package/package.json
CHANGED
package/src/agent/agent.ts
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
import type { Static, TSchema } from "typebox";
|
|
2
2
|
import type { EffectiveAskOptions } from "../ask/index.ts";
|
|
3
3
|
import { exchangeAsk } from "../ask/index.ts";
|
|
4
|
-
import { ReportResultTool } from "../ask-contract/index.ts";
|
|
4
|
+
import { REPORT_RESULT_WRAP_UP, ReportResultTool, wrapUpMessage } from "../ask-contract/index.ts";
|
|
5
|
+
import type { AskAdmission, AskInFlight } from "../control/index.ts";
|
|
5
6
|
import { agentError } from "../error-factories.ts";
|
|
6
7
|
import type { EventSink } from "../events.ts";
|
|
7
8
|
import type { ModelErrorHistory, ModelResolution } from "../model/index.ts";
|
|
@@ -59,6 +60,8 @@ export interface AgentOptions {
|
|
|
59
60
|
readonly idleAbortSettleMs?: number;
|
|
60
61
|
/** Test-only override for the bounded wait for the Stall Watchdog probe. */
|
|
61
62
|
readonly stallProbeSettleMs?: number;
|
|
63
|
+
/** Run-scoped Ask gate; a closed gate refuses every later Ask (ADR-0024). */
|
|
64
|
+
readonly askAdmission?: AskAdmission;
|
|
62
65
|
}
|
|
63
66
|
|
|
64
67
|
/** One Agent as an Orchestration Program sees it. Lives above the transport seam. */
|
|
@@ -83,7 +86,9 @@ export class Agent implements Handle {
|
|
|
83
86
|
readonly #reportResultTool = new ReportResultTool();
|
|
84
87
|
readonly #sessionFile: string | undefined;
|
|
85
88
|
readonly #fork: ForkSpawner | undefined;
|
|
89
|
+
readonly #askAdmission: AskAdmission | undefined;
|
|
86
90
|
#busy = false;
|
|
91
|
+
#inFlight: AskInFlight | null = null;
|
|
87
92
|
#incomplete = false;
|
|
88
93
|
#askIndex = 0;
|
|
89
94
|
#settledAsks = 0;
|
|
@@ -107,6 +112,7 @@ export class Agent implements Handle {
|
|
|
107
112
|
this.#askLimitGraceMs = options.askLimitGraceMs;
|
|
108
113
|
this.#idleAbortSettleMs = options.idleAbortSettleMs;
|
|
109
114
|
this.#stallProbeSettleMs = options.stallProbeSettleMs;
|
|
115
|
+
this.#askAdmission = options.askAdmission;
|
|
110
116
|
this.#usage = new AgentUsage((snapshot) =>
|
|
111
117
|
this.#emit({ type: "agent_usage", agent: this.name, ...snapshot }),
|
|
112
118
|
);
|
|
@@ -124,6 +130,8 @@ export class Agent implements Handle {
|
|
|
124
130
|
): Promise<Static<Schema>>;
|
|
125
131
|
async ask(prompt: string, options?: AskOptions): Promise<string>;
|
|
126
132
|
async ask(prompt: string, options?: EffectiveAskOptions): Promise<unknown> {
|
|
133
|
+
if (this.#askAdmission?.closed === true)
|
|
134
|
+
throw agentError(this.name, "RUN_CLOSED", "run is settling — no new Ask");
|
|
127
135
|
if (this.#connection.dead)
|
|
128
136
|
throw agentError(this.name, "AGENT_DIED", "agent is no longer running");
|
|
129
137
|
if (this.#busy) {
|
|
@@ -134,6 +142,9 @@ export class Agent implements Handle {
|
|
|
134
142
|
);
|
|
135
143
|
}
|
|
136
144
|
this.#busy = true;
|
|
145
|
+
const effective: EffectiveAskOptions = { ...this.#askDefaults, ...options };
|
|
146
|
+
const inFlight = this.#openInFlight(effective);
|
|
147
|
+
this.#inFlight = inFlight;
|
|
137
148
|
const index = this.#askIndex++;
|
|
138
149
|
try {
|
|
139
150
|
return await exchangeAsk({
|
|
@@ -142,7 +153,7 @@ export class Agent implements Handle {
|
|
|
142
153
|
transport: this.#transport,
|
|
143
154
|
prompt,
|
|
144
155
|
index,
|
|
145
|
-
ask:
|
|
156
|
+
ask: effective,
|
|
146
157
|
spawnOptions: this.#spawnOptions,
|
|
147
158
|
definitionName: this.#definitionName,
|
|
148
159
|
reportResultTool: this.#reportResultTool,
|
|
@@ -167,12 +178,51 @@ export class Agent implements Handle {
|
|
|
167
178
|
});
|
|
168
179
|
} finally {
|
|
169
180
|
this.#busy = false;
|
|
181
|
+
this.#inFlight = null;
|
|
182
|
+
inFlight.settle();
|
|
170
183
|
// A failed Ask settles the conversation as much as a successful one: the
|
|
171
184
|
// fork point is the boundary, not the outcome.
|
|
172
185
|
this.#settledAsks += 1;
|
|
173
186
|
}
|
|
174
187
|
}
|
|
175
188
|
|
|
189
|
+
/**
|
|
190
|
+
* The Ask this Agent runs right now, as the pause drain controls it, or null
|
|
191
|
+
* between Asks. An Orchestration Program never sees it: `Handle` omits it.
|
|
192
|
+
*/
|
|
193
|
+
get askInFlight(): AskInFlight | null {
|
|
194
|
+
return this.#inFlight;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/**
|
|
198
|
+
* Builds the drain's controls of one Ask. Both commands report a refusal as
|
|
199
|
+
* false and never throw, so a dead Agent cannot throw into the drain.
|
|
200
|
+
*/
|
|
201
|
+
#openInFlight(ask: EffectiveAskOptions): AskInFlight & { settle(): void } {
|
|
202
|
+
let settle: () => void = () => {};
|
|
203
|
+
const settled = new Promise<void>((resolve) => {
|
|
204
|
+
settle = resolve;
|
|
205
|
+
});
|
|
206
|
+
// A structured Ask keeps reporting through report_result, so its wrap-up
|
|
207
|
+
// carries the same suffix the soft-budget path uses (ADR-0032). Legacy
|
|
208
|
+
// extraction exists on playback only, where no drain runs.
|
|
209
|
+
const suffix = "outputSchema" in ask ? REPORT_RESULT_WRAP_UP : undefined;
|
|
210
|
+
const send = async (frame: Parameters<Connection["command"]>[0]): Promise<boolean> => {
|
|
211
|
+
try {
|
|
212
|
+
return (await this.#connection.command(frame)).success;
|
|
213
|
+
} catch {
|
|
214
|
+
return false;
|
|
215
|
+
}
|
|
216
|
+
};
|
|
217
|
+
return {
|
|
218
|
+
agent: this.name,
|
|
219
|
+
settled,
|
|
220
|
+
settle,
|
|
221
|
+
wrapUp: () => send({ type: "steer", message: wrapUpMessage(ask, suffix) }),
|
|
222
|
+
abort: () => send({ type: "abort" }),
|
|
223
|
+
};
|
|
224
|
+
}
|
|
225
|
+
|
|
176
226
|
/** Replaces this Agent's context with a summary of it (ADR-0043). */
|
|
177
227
|
compact(instructions?: string): Promise<CompactionResult> {
|
|
178
228
|
if (this.#connection.dead)
|
package/src/agent/spawn-open.ts
CHANGED
|
@@ -174,6 +174,7 @@ export async function openAgent(
|
|
|
174
174
|
: { modelFallback: { resolution, history, candidate: spawnOptions.model } }),
|
|
175
175
|
...(sessionFile === undefined ? {} : { sessionFile }),
|
|
176
176
|
fork: deps.forkSpawner,
|
|
177
|
+
...(deps.askAdmission === undefined ? {} : { askAdmission: deps.askAdmission }),
|
|
177
178
|
...(request.askDefaults === undefined ? {} : { askDefaults: request.askDefaults }),
|
|
178
179
|
...(request.definitionName === undefined ? {} : { definitionName: request.definitionName }),
|
|
179
180
|
});
|
package/src/agent/spawn.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { ConfigExtension } from "../config/index.ts";
|
|
2
|
+
import type { AskAdmission } from "../control/index.ts";
|
|
2
3
|
import { YaagError } from "../errors.ts";
|
|
3
4
|
import type { EventSink } from "../events.ts";
|
|
4
5
|
import type { ActiveProfile, ProfiledDefinition } from "../profile/index.ts";
|
|
@@ -24,6 +25,8 @@ export interface SpawnDependencies {
|
|
|
24
25
|
readonly configExtensions: readonly ConfigExtension[];
|
|
25
26
|
/** The Profile this Run activated; absent for a program without Profiles. */
|
|
26
27
|
readonly profile?: ActiveProfile;
|
|
28
|
+
/** Run-scoped Ask gate handed to every Agent this gate opens (ADR-0024). */
|
|
29
|
+
readonly askAdmission?: AskAdmission;
|
|
27
30
|
}
|
|
28
31
|
|
|
29
32
|
/** A RunContext spawn function that can synchronously stop accepting new Agents. */
|
|
@@ -2,6 +2,7 @@ import type { AskLimitKind, AskLimitOutcome } from "../errors.ts";
|
|
|
2
2
|
import type { Frame } from "../transport/index.ts";
|
|
3
3
|
import type { AskOptions } from "../types.ts";
|
|
4
4
|
import { REPORT_RESULT_TOOL_NAME } from "./report-result.ts";
|
|
5
|
+
import { wrapUpMessage } from "./wrap-up-steer.ts";
|
|
5
6
|
|
|
6
7
|
/**
|
|
7
8
|
* True for a call to yaag's private result tool.
|
|
@@ -15,8 +16,6 @@ function isReportResult(frame: Frame): boolean {
|
|
|
15
16
|
return frame.toolName === REPORT_RESULT_TOOL_NAME;
|
|
16
17
|
}
|
|
17
18
|
|
|
18
|
-
/** The message sent when an Ask uses its allotted soft budget. */
|
|
19
|
-
export const DEFAULT_WRAP_UP_PROMPT = "Please wrap up now and provide your final answer.";
|
|
20
19
|
/** Fixed time allowed to conclude after a duration limit trips. */
|
|
21
20
|
export const ASK_LIMIT_DURATION_GRACE_MS = 5_000;
|
|
22
21
|
|
|
@@ -164,8 +163,7 @@ export class AskLimit {
|
|
|
164
163
|
}
|
|
165
164
|
|
|
166
165
|
#wrapUpMessage(): string {
|
|
167
|
-
|
|
168
|
-
return this.#wrapUpSuffix === undefined ? wrapUp : `${wrapUp} ${this.#wrapUpSuffix}`;
|
|
166
|
+
return wrapUpMessage(this.#ask, this.#wrapUpSuffix);
|
|
169
167
|
}
|
|
170
168
|
|
|
171
169
|
#abort(): void {
|
|
@@ -9,7 +9,7 @@ export {
|
|
|
9
9
|
validateCanonicalOutputSchema,
|
|
10
10
|
validateExtractionPolicy,
|
|
11
11
|
} from "./ask-contract-identity.ts";
|
|
12
|
-
export { AskLimit
|
|
12
|
+
export { AskLimit } from "./ask-limit.ts";
|
|
13
13
|
export {
|
|
14
14
|
type AskOutputExtractionPolicy,
|
|
15
15
|
DEFAULT_MAX_STEERS,
|
|
@@ -34,3 +34,4 @@ export {
|
|
|
34
34
|
resolvePlaybackReportedResult,
|
|
35
35
|
} from "./report-result-output.ts";
|
|
36
36
|
export { ReportResultSteering } from "./report-result-steering.ts";
|
|
37
|
+
export { DEFAULT_WRAP_UP_PROMPT, wrapUpMessage } from "./wrap-up-steer.ts";
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { AskOptions } from "../types.ts";
|
|
2
|
+
|
|
3
|
+
/** The message sent when an Ask uses its allotted soft budget. */
|
|
4
|
+
export const DEFAULT_WRAP_UP_PROMPT = "Please wrap up now and provide your final answer.";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* The wrap-up steer text of one Ask.
|
|
8
|
+
*
|
|
9
|
+
* Every wrap-up path shares it — the soft Ask budget of `AskLimit` and the
|
|
10
|
+
* bounded pause drain (ADR-0024) — so an Agent reads the same words whichever
|
|
11
|
+
* mechanism asks it to conclude. The optional suffix keeps a structured Ask
|
|
12
|
+
* reporting its result through `report_result` (ADR-0032).
|
|
13
|
+
*/
|
|
14
|
+
export function wrapUpMessage(ask: AskOptions, suffix?: string): string {
|
|
15
|
+
const wrapUp = ask.wrapUpPrompt ?? DEFAULT_WRAP_UP_PROMPT;
|
|
16
|
+
return suffix === undefined ? wrapUp : `${wrapUp} ${suffix}`;
|
|
17
|
+
}
|
|
@@ -23,11 +23,11 @@ export interface CheckpointEnvironment {
|
|
|
23
23
|
* `$HOME/.local/state`. A relative `XDG_STATE_HOME` is ignored (XDG spec).
|
|
24
24
|
*/
|
|
25
25
|
export function resolveCheckpointDirectory(env: CheckpointEnvironment = process.env): string {
|
|
26
|
-
const override = env
|
|
26
|
+
const override = env.YAAG_CHECKPOINT_DIR;
|
|
27
27
|
if (override !== undefined && override !== "") return override;
|
|
28
|
-
const xdg = env
|
|
28
|
+
const xdg = env.XDG_STATE_HOME;
|
|
29
29
|
if (xdg !== undefined && isAbsolute(xdg)) return join(xdg, CHECKPOINT_SUFFIX);
|
|
30
|
-
const home = env
|
|
30
|
+
const home = env.HOME !== undefined && env.HOME !== "" ? env.HOME : homedir();
|
|
31
31
|
return join(home, ".local", "state", CHECKPOINT_SUFFIX);
|
|
32
32
|
}
|
|
33
33
|
|
package/src/cassette/index.ts
CHANGED
|
@@ -15,7 +15,7 @@ export type RunIdentity = Omit<CassetteRun, "outcome">;
|
|
|
15
15
|
* `--record` path itself, or one name in the checkpoint directory.
|
|
16
16
|
*/
|
|
17
17
|
export interface RunCheckpointOptions {
|
|
18
|
-
/** Terminal outcome
|
|
18
|
+
/** Terminal outcome; `stopped` and `paused` keep the artifact without `record`. */
|
|
19
19
|
readonly outcome: RunOutcome;
|
|
20
20
|
readonly collector: CassetteCollector;
|
|
21
21
|
/** Explicit `--record` destination, or undefined when the Run only checkpoints. */
|
|
@@ -41,12 +41,12 @@ export type RunCheckpointResult =
|
|
|
41
41
|
/**
|
|
42
42
|
* Publishes the collected Cassette when the Run must be restorable: always under
|
|
43
43
|
* `--record`, and additionally into the checkpoint directory when the Run
|
|
44
|
-
* stopped (ADR-0021/0024).
|
|
44
|
+
* stopped or paused (ADR-0021/0024).
|
|
45
45
|
*/
|
|
46
46
|
export async function publishRunCheckpoint(
|
|
47
47
|
options: RunCheckpointOptions,
|
|
48
48
|
): Promise<RunCheckpointResult> {
|
|
49
|
-
if (!
|
|
49
|
+
if (!keepsCheckpoint(options)) {
|
|
50
50
|
// A clean settlement without --record publishes nothing, so the in-flight
|
|
51
51
|
// artifact this Run flushed goes away with it (ADR-0031).
|
|
52
52
|
await discardCheckpoint(options.destination);
|
|
@@ -88,8 +88,20 @@ export async function publishRunCheckpoint(
|
|
|
88
88
|
}
|
|
89
89
|
}
|
|
90
90
|
|
|
91
|
-
|
|
92
|
-
|
|
91
|
+
/**
|
|
92
|
+
* Whether a Run keeps its artifact: `--record` names a destination, or the Run
|
|
93
|
+
* paused or stopped. Every other Run discards the in-flight artifact, so it
|
|
94
|
+
* names no Checkpoint on `run_end` either — `run.ts` reads this same rule
|
|
95
|
+
* (ADR-0054). A paused Run promises restorability, so it keeps its artifact
|
|
96
|
+
* and can name its path.
|
|
97
|
+
*/
|
|
98
|
+
export function keepsCheckpoint(options: {
|
|
99
|
+
readonly record?: string;
|
|
100
|
+
readonly outcome: RunOutcome;
|
|
101
|
+
}): boolean {
|
|
102
|
+
return (
|
|
103
|
+
options.record !== undefined || options.outcome === "stopped" || options.outcome === "paused"
|
|
104
|
+
);
|
|
93
105
|
}
|
|
94
106
|
|
|
95
107
|
/**
|
|
@@ -156,9 +156,9 @@ function asRegistryDocument(value: unknown): RegistryDocument | undefined {
|
|
|
156
156
|
function toAgentEntry(element: unknown): AgentDefinitionEntry {
|
|
157
157
|
const record = asRecord(element);
|
|
158
158
|
return {
|
|
159
|
-
file: text(record
|
|
160
|
-
exportName: text(record
|
|
161
|
-
name: text(record
|
|
159
|
+
file: text(record.file),
|
|
160
|
+
exportName: text(record.exportName),
|
|
161
|
+
name: text(record.name),
|
|
162
162
|
...metadata(record),
|
|
163
163
|
};
|
|
164
164
|
}
|
|
@@ -166,7 +166,7 @@ function toAgentEntry(element: unknown): AgentDefinitionEntry {
|
|
|
166
166
|
/** Builds a program entry from a possibly malformed element, repaired the same way. */
|
|
167
167
|
function toProgramEntry(element: unknown): ProgramEntry {
|
|
168
168
|
const record = asRecord(element);
|
|
169
|
-
return { file: text(record
|
|
169
|
+
return { file: text(record.file), name: text(record.name), ...metadata(record) };
|
|
170
170
|
}
|
|
171
171
|
|
|
172
172
|
/** Keeps `description` when it is a string and keeps the string tags only. */
|
|
@@ -174,8 +174,8 @@ function metadata(record: Record<string, unknown>): {
|
|
|
174
174
|
description?: string;
|
|
175
175
|
tags?: string[];
|
|
176
176
|
} {
|
|
177
|
-
const description = record
|
|
178
|
-
const tags = record
|
|
177
|
+
const description = record.description;
|
|
178
|
+
const tags = record.tags;
|
|
179
179
|
return {
|
|
180
180
|
...(typeof description === "string" ? { description } : {}),
|
|
181
181
|
...(Array.isArray(tags) ? { tags: tags.filter((tag) => typeof tag === "string") } : {}),
|
|
@@ -23,11 +23,11 @@ export const PROJECT_CONFIG_DIR = ".yaag";
|
|
|
23
23
|
* `os.homedir()`.
|
|
24
24
|
*/
|
|
25
25
|
export function resolveGlobalConfigDirectory(env: ConfigEnvironment = process.env): string {
|
|
26
|
-
const override = env
|
|
26
|
+
const override = env.YAAG_CONFIG_DIR;
|
|
27
27
|
if (override !== undefined && override !== "") return override;
|
|
28
|
-
const xdg = env
|
|
28
|
+
const xdg = env.XDG_CONFIG_HOME;
|
|
29
29
|
if (xdg !== undefined && isAbsolute(xdg)) return join(xdg, "yaag");
|
|
30
|
-
const home = env
|
|
30
|
+
const home = env.HOME !== undefined && env.HOME !== "" ? env.HOME : homedir();
|
|
31
31
|
return join(home, ".config", "yaag");
|
|
32
32
|
}
|
|
33
33
|
|
|
@@ -61,7 +61,8 @@ export type YaagErrorCode =
|
|
|
61
61
|
| "PROFILE_NOT_FOUND" // a selected Profile is not declared by the program (ADR-0052)
|
|
62
62
|
| "PROFILE_REQUIRED" // a Profiled Definition was spawned by a program that declares no Profiles
|
|
63
63
|
| "ROLE_NOT_FOUND" // a factory read a Role the program does not declare
|
|
64
|
-
| "RUN_CLOSED" // spawn
|
|
64
|
+
| "RUN_CLOSED" // spawn or Ask requested after the Run began settling
|
|
65
|
+
| "RUN_PAUSED" // an external pause drain settled the Run (ADR-0024)
|
|
65
66
|
| "RUN_STOPPED" // the Run's abort signal fired before the program completed
|
|
66
67
|
| "WORKTREE_REFUSED" // base cwd is not a clean Git repository
|
|
67
68
|
| "MODEL_RESOLUTION_FAILED" // the resolver gave up, or every candidate failed; carries the history
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Run-scoped gate over new Asks, closed before a pause drain sends its first
|
|
3
|
+
* wrap-up steer (ADR-0024). Spawn admission has its own gate in `agent/spawn.ts`;
|
|
4
|
+
* both close together when the Run begins settling.
|
|
5
|
+
*/
|
|
6
|
+
export interface AskAdmission {
|
|
7
|
+
/** True once the Run began settling; a new Ask is refused with RUN_CLOSED. */
|
|
8
|
+
readonly closed: boolean;
|
|
9
|
+
/** Refuses every later Ask. Idempotent. */
|
|
10
|
+
close(): void;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
/** Creates one Run's Ask admission gate, open until the Run begins settling. */
|
|
14
|
+
export function createAskAdmission(): AskAdmission {
|
|
15
|
+
let closed = false;
|
|
16
|
+
return {
|
|
17
|
+
get closed(): boolean {
|
|
18
|
+
return closed;
|
|
19
|
+
},
|
|
20
|
+
close(): void {
|
|
21
|
+
closed = true;
|
|
22
|
+
},
|
|
23
|
+
};
|
|
24
|
+
}
|