@yaag/runtime 0.22.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.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/index.ts +1 -0
- package/src/cassette/run-checkpoint.ts +17 -5
- 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 +17 -0
- 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
|
+
}
|
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
|
/**
|
|
@@ -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
|
+
}
|
|
@@ -0,0 +1,300 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The control command state machine (ADR-0024, ADR-0054): one reader that both
|
|
3
|
+
* stdin and the Control Channel socket feed. It is pure — no I/O, no clock, no
|
|
4
|
+
* `node:` module. It takes text in and returns response bodies plus at most one
|
|
5
|
+
* typed command per accepted request; the caller does every side effect.
|
|
6
|
+
*/
|
|
7
|
+
import type { ControlErrorCode, ControlResponseStatus, LifecycleEventBody } from "../events.ts";
|
|
8
|
+
|
|
9
|
+
export type { ControlErrorCode, ControlResponseStatus } from "../events.ts";
|
|
10
|
+
|
|
11
|
+
/** ADR-0024 frame cap: a longer line is refused, never buffered. */
|
|
12
|
+
export const CONTROL_FRAME_MAX_BYTES = 64 * 1024;
|
|
13
|
+
/** Longest accepted request id. A longer id is `INVALID_FIELD`. */
|
|
14
|
+
export const CONTROL_ID_MAX_CHARS = 128;
|
|
15
|
+
/** Pause deadline used when the frame names none. */
|
|
16
|
+
export const PAUSE_DEADLINE_DEFAULT_MS = 60_000;
|
|
17
|
+
/** Smallest accepted pause deadline. */
|
|
18
|
+
export const PAUSE_DEADLINE_MIN_MS = 1_000;
|
|
19
|
+
/** Largest accepted pause deadline. */
|
|
20
|
+
export const PAUSE_DEADLINE_MAX_MS = 600_000;
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Bound on the answered-id table. An unbounded map is a memory hole a hostile
|
|
24
|
+
* client can grow one frame at a time. Eviction is safe: after the first
|
|
25
|
+
* accepted terminal every fresh id gets `RUN_SETTLING`/`RUN_ENDED` anyway.
|
|
26
|
+
*/
|
|
27
|
+
const CONTROL_ID_TABLE_MAX = 256;
|
|
28
|
+
|
|
29
|
+
/** The `control_response` Lifecycle Event body (ADR-0024 wire contract). */
|
|
30
|
+
export type ControlResponse = Extract<LifecycleEventBody, { type: "control_response" }>;
|
|
31
|
+
|
|
32
|
+
/** What an accepted request means for the Run. */
|
|
33
|
+
export type ControlCommand =
|
|
34
|
+
| { readonly kind: "pause"; readonly deadlineMs: number }
|
|
35
|
+
| { readonly kind: "stop" };
|
|
36
|
+
|
|
37
|
+
/** One line in, one response out, plus at most one command for the caller. */
|
|
38
|
+
export interface ControlDecision {
|
|
39
|
+
readonly response: ControlResponse;
|
|
40
|
+
readonly command: ControlCommand | null;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
type Phase =
|
|
44
|
+
| { readonly name: "open" }
|
|
45
|
+
| { readonly name: "pausing" }
|
|
46
|
+
| { readonly name: "stopping" }
|
|
47
|
+
| { readonly name: "settling" }
|
|
48
|
+
| { readonly name: "ended" };
|
|
49
|
+
|
|
50
|
+
type Request =
|
|
51
|
+
| { readonly id: string; readonly cmd: "pause"; readonly deadlineMs: number }
|
|
52
|
+
| { readonly id: string; readonly cmd: "stop" };
|
|
53
|
+
|
|
54
|
+
type ParsedFrame =
|
|
55
|
+
| { readonly ok: true; readonly request: Request }
|
|
56
|
+
| { readonly ok: false; readonly response: ControlResponse };
|
|
57
|
+
|
|
58
|
+
const KNOWN_KEYS = new Set(["v", "id", "cmd", "deadlineMs"]);
|
|
59
|
+
const encoder = new TextEncoder();
|
|
60
|
+
|
|
61
|
+
function error(id: string | null, code: ControlErrorCode, message: string): ControlResponse {
|
|
62
|
+
return { type: "control_response", id, status: "error", code, message };
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
function ok(id: string, status: ControlResponseStatus): ControlResponse {
|
|
66
|
+
return { type: "control_response", id, status };
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
function isInteger(value: unknown): value is number {
|
|
70
|
+
return typeof value === "number" && Number.isInteger(value);
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** Parses and validates one line, in the ADR-0024 order, without any state. */
|
|
74
|
+
function parseControlFrame(line: string): ParsedFrame {
|
|
75
|
+
let value: unknown;
|
|
76
|
+
try {
|
|
77
|
+
value = JSON.parse(line);
|
|
78
|
+
} catch {
|
|
79
|
+
return { ok: false, response: error(null, "MALFORMED", "the frame is not JSON") };
|
|
80
|
+
}
|
|
81
|
+
if (typeof value !== "object" || value === null || Array.isArray(value)) {
|
|
82
|
+
return { ok: false, response: error(null, "MALFORMED", "the frame is not a JSON object") };
|
|
83
|
+
}
|
|
84
|
+
const frame = value as Record<string, unknown>;
|
|
85
|
+
const id = frame.id;
|
|
86
|
+
// The id is read first, so a version error can still name the request it
|
|
87
|
+
// answers; `id: null` stays reserved for a frame with no usable id (ADR-0024).
|
|
88
|
+
const usableId =
|
|
89
|
+
typeof id === "string" && id !== "" && id.length <= CONTROL_ID_MAX_CHARS ? id : null;
|
|
90
|
+
if (!("v" in frame)) {
|
|
91
|
+
return { ok: false, response: error(usableId, "MALFORMED", "the field `v` is missing") };
|
|
92
|
+
}
|
|
93
|
+
if (!isInteger(frame.v)) {
|
|
94
|
+
return { ok: false, response: error(usableId, "MALFORMED", "the field `v` is not an integer") };
|
|
95
|
+
}
|
|
96
|
+
if (frame.v !== 1) {
|
|
97
|
+
return {
|
|
98
|
+
ok: false,
|
|
99
|
+
response: error(usableId, "UNSUPPORTED_VERSION", `unsupported version ${frame.v}`),
|
|
100
|
+
};
|
|
101
|
+
}
|
|
102
|
+
if (usableId === null) {
|
|
103
|
+
return { ok: false, response: error(null, "INVALID_FIELD", "the field `id` is invalid") };
|
|
104
|
+
}
|
|
105
|
+
if (!("cmd" in frame) || typeof frame.cmd !== "string") {
|
|
106
|
+
return { ok: false, response: error(usableId, "INVALID_FIELD", "the field `cmd` is invalid") };
|
|
107
|
+
}
|
|
108
|
+
const cmd = frame.cmd;
|
|
109
|
+
if (cmd !== "pause" && cmd !== "stop") {
|
|
110
|
+
return { ok: false, response: error(usableId, "UNKNOWN_CMD", `unknown command \`${cmd}\``) };
|
|
111
|
+
}
|
|
112
|
+
for (const key of Object.keys(frame)) {
|
|
113
|
+
if (!KNOWN_KEYS.has(key)) {
|
|
114
|
+
return { ok: false, response: error(usableId, "INVALID_FIELD", `unknown field \`${key}\``) };
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
if (cmd === "stop") {
|
|
118
|
+
if ("deadlineMs" in frame) {
|
|
119
|
+
return {
|
|
120
|
+
ok: false,
|
|
121
|
+
response: error(usableId, "INVALID_FIELD", "the field `deadlineMs` is not valid on a stop"),
|
|
122
|
+
};
|
|
123
|
+
}
|
|
124
|
+
return { ok: true, request: { id: usableId, cmd } };
|
|
125
|
+
}
|
|
126
|
+
if (!("deadlineMs" in frame)) {
|
|
127
|
+
return { ok: true, request: { id: usableId, cmd, deadlineMs: PAUSE_DEADLINE_DEFAULT_MS } };
|
|
128
|
+
}
|
|
129
|
+
const deadlineMs = frame.deadlineMs;
|
|
130
|
+
if (
|
|
131
|
+
!isInteger(deadlineMs) ||
|
|
132
|
+
deadlineMs < PAUSE_DEADLINE_MIN_MS ||
|
|
133
|
+
deadlineMs > PAUSE_DEADLINE_MAX_MS
|
|
134
|
+
) {
|
|
135
|
+
return {
|
|
136
|
+
ok: false,
|
|
137
|
+
response: error(usableId, "INVALID_FIELD", "the field `deadlineMs` is invalid"),
|
|
138
|
+
};
|
|
139
|
+
}
|
|
140
|
+
return { ok: true, request: { id: usableId, cmd, deadlineMs } };
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
function byteLength(text: string): number {
|
|
144
|
+
return encoder.encode(text).length;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
function overlong(): ControlDecision {
|
|
148
|
+
return {
|
|
149
|
+
response: error(null, "FRAME_TOO_LONG", "the frame is longer than the 64 KiB cap"),
|
|
150
|
+
command: null,
|
|
151
|
+
};
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
function signatureOf(request: Request): string {
|
|
155
|
+
return request.cmd === "pause" ? `pause|${request.deadlineMs}` : "stop";
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Reads `\n`-terminated control frames and arbitrates them: the first terminal
|
|
160
|
+
* request wins, a stop overrides a pause drain, and an identical id coalesces.
|
|
161
|
+
* It never does I/O and never reads a clock; the caller applies the commands.
|
|
162
|
+
*/
|
|
163
|
+
export class ControlCommandReader {
|
|
164
|
+
#buffer = "";
|
|
165
|
+
#skipping = false;
|
|
166
|
+
#phase: Phase = { name: "open" };
|
|
167
|
+
readonly #answered = new Map<string, { signature: string; response: ControlResponse }>();
|
|
168
|
+
|
|
169
|
+
/**
|
|
170
|
+
* The `BUSY` frame the Control Channel writes to a second client while one
|
|
171
|
+
* client holds the channel (spec decision 18). Static: no Run state is read.
|
|
172
|
+
*/
|
|
173
|
+
static busy(message = "another client holds the Control Channel"): ControlResponse {
|
|
174
|
+
return { type: "control_response", id: null, status: "error", code: "BUSY", message };
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/**
|
|
178
|
+
* Feeds one chunk of text and returns one decision per complete frame. A
|
|
179
|
+
* blank line is not a frame. An unterminated tail stays buffered; ADR-0024
|
|
180
|
+
* discards it at EOF.
|
|
181
|
+
*/
|
|
182
|
+
read(chunk: string): readonly ControlDecision[] {
|
|
183
|
+
const decisions: ControlDecision[] = [];
|
|
184
|
+
this.#buffer += chunk;
|
|
185
|
+
let newline = this.#buffer.indexOf("\n");
|
|
186
|
+
while (newline !== -1) {
|
|
187
|
+
const line = this.#buffer.slice(0, newline);
|
|
188
|
+
this.#buffer = this.#buffer.slice(newline + 1);
|
|
189
|
+
if (this.#skipping) this.#skipping = false;
|
|
190
|
+
else if (byteLength(line) > CONTROL_FRAME_MAX_BYTES) {
|
|
191
|
+
// The cap precedes the parse, so an overlong frame is never decoded.
|
|
192
|
+
decisions.push(overlong());
|
|
193
|
+
} else {
|
|
194
|
+
const decision = this.#line(line);
|
|
195
|
+
if (decision !== null) decisions.push(decision);
|
|
196
|
+
}
|
|
197
|
+
newline = this.#buffer.indexOf("\n");
|
|
198
|
+
}
|
|
199
|
+
if (!this.#skipping && byteLength(this.#buffer) > CONTROL_FRAME_MAX_BYTES) {
|
|
200
|
+
this.#buffer = "";
|
|
201
|
+
this.#skipping = true;
|
|
202
|
+
decisions.push(overlong());
|
|
203
|
+
}
|
|
204
|
+
if (this.#skipping) this.#buffer = "";
|
|
205
|
+
return decisions;
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* The caller reports that settlement began: later requests get `RUN_SETTLING`.
|
|
210
|
+
* The phase setters are not guarded against a backwards move; the Run calls
|
|
211
|
+
* them one time each, in order.
|
|
212
|
+
*/
|
|
213
|
+
settling(): void {
|
|
214
|
+
this.#phase = { name: "settling" };
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/** The caller reports that `run_end` was emitted: later new requests get `RUN_ENDED`. */
|
|
218
|
+
ended(): void {
|
|
219
|
+
this.#phase = { name: "ended" };
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
#line(raw: string): ControlDecision | null {
|
|
223
|
+
const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
|
|
224
|
+
if (line.trim() === "") return null;
|
|
225
|
+
const parsed = parseControlFrame(line);
|
|
226
|
+
if (!parsed.ok) {
|
|
227
|
+
const id = parsed.response.id;
|
|
228
|
+
if (id === null) return { response: parsed.response, command: null };
|
|
229
|
+
// The signature is the payload, not the code: two different payloads that
|
|
230
|
+
// share an id are a `DUPLICATE_ID`, whatever they failed on (ADR-0024).
|
|
231
|
+
return this.#answer(id, `raw|${line}`, { response: parsed.response, command: null });
|
|
232
|
+
}
|
|
233
|
+
return this.#arbitrate(parsed.request);
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
/** Coalesces on an identical payload, refuses a different one, else records the answer. */
|
|
237
|
+
#answer(id: string, signature: string, fresh: ControlDecision): ControlDecision {
|
|
238
|
+
const coalesced = this.#coalesce(id, signature);
|
|
239
|
+
if (coalesced !== null) return coalesced;
|
|
240
|
+
this.#remember(id, signature, fresh.response);
|
|
241
|
+
return fresh;
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
#coalesce(id: string, signature: string): ControlDecision | null {
|
|
245
|
+
const previous = this.#answered.get(id);
|
|
246
|
+
if (previous === undefined) return null;
|
|
247
|
+
if (previous.signature === signature) return { response: previous.response, command: null };
|
|
248
|
+
return {
|
|
249
|
+
response: error(id, "DUPLICATE_ID", `the id \`${id}\` already carries a different request`),
|
|
250
|
+
command: null,
|
|
251
|
+
};
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
#remember(id: string, signature: string, response: ControlResponse): void {
|
|
255
|
+
if (this.#answered.size >= CONTROL_ID_TABLE_MAX) {
|
|
256
|
+
const oldest = this.#answered.keys().next();
|
|
257
|
+
if (!oldest.done) this.#answered.delete(oldest.value);
|
|
258
|
+
}
|
|
259
|
+
this.#answered.set(id, { signature, response });
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
#arbitrate(request: Request): ControlDecision {
|
|
263
|
+
// There is no terminal-response cache: a request that arrives after
|
|
264
|
+
// settlement gets `RUN_SETTLING`/`RUN_ENDED`, even when it repeats an
|
|
265
|
+
// answered id (ADR-0024).
|
|
266
|
+
const phase = this.#phase.name;
|
|
267
|
+
if (phase === "ended") {
|
|
268
|
+
return { response: error(request.id, "RUN_ENDED", "the Run ended"), command: null };
|
|
269
|
+
}
|
|
270
|
+
if (phase === "settling") {
|
|
271
|
+
return { response: error(request.id, "RUN_SETTLING", "the Run is settling"), command: null };
|
|
272
|
+
}
|
|
273
|
+
const signature = signatureOf(request);
|
|
274
|
+
const coalesced = this.#coalesce(request.id, signature);
|
|
275
|
+
if (coalesced !== null) return coalesced;
|
|
276
|
+
// `#decide` moves the phase, so it runs only after coalescing ruled out a repeat.
|
|
277
|
+
const decision = this.#decide(request);
|
|
278
|
+
this.#remember(request.id, signature, decision.response);
|
|
279
|
+
return decision;
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
#decide(request: Request): ControlDecision {
|
|
283
|
+
const phase = this.#phase.name;
|
|
284
|
+
if (phase === "stopping") {
|
|
285
|
+
return { response: error(request.id, "RUN_SETTLING", "the Run is settling"), command: null };
|
|
286
|
+
}
|
|
287
|
+
if (request.cmd === "stop") {
|
|
288
|
+
this.#phase = { name: "stopping" };
|
|
289
|
+
return { response: ok(request.id, "accepted"), command: { kind: "stop" } };
|
|
290
|
+
}
|
|
291
|
+
if (phase === "pausing") {
|
|
292
|
+
return { response: ok(request.id, "already_pausing"), command: null };
|
|
293
|
+
}
|
|
294
|
+
this.#phase = { name: "pausing" };
|
|
295
|
+
return {
|
|
296
|
+
response: ok(request.id, "accepted"),
|
|
297
|
+
command: { kind: "pause", deadlineMs: request.deadlineMs },
|
|
298
|
+
};
|
|
299
|
+
}
|
|
300
|
+
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Public surface of the `control/` module: the command reader both inputs feed,
|
|
3
|
+
* external Run control, and the bounded pause drain (ADR-0024, ADR-0054).
|
|
4
|
+
* Files inside this directory import each other directly.
|
|
5
|
+
*/
|
|
6
|
+
export { type AskAdmission, createAskAdmission } from "./ask-admission.ts";
|
|
7
|
+
export {
|
|
8
|
+
type ControlCommand,
|
|
9
|
+
ControlCommandReader,
|
|
10
|
+
type ControlDecision,
|
|
11
|
+
type ControlErrorCode,
|
|
12
|
+
type ControlResponse,
|
|
13
|
+
type ControlResponseStatus,
|
|
14
|
+
PAUSE_DEADLINE_MAX_MS,
|
|
15
|
+
PAUSE_DEADLINE_MIN_MS,
|
|
16
|
+
} from "./control-commands.ts";
|
|
17
|
+
export {
|
|
18
|
+
type AskInFlight,
|
|
19
|
+
type DrainableAgent,
|
|
20
|
+
drainForPause,
|
|
21
|
+
type PauseDrainOptions,
|
|
22
|
+
type PauseDrainResult,
|
|
23
|
+
} from "./pause-drain.ts";
|
|
24
|
+
export {
|
|
25
|
+
type ControlRequest,
|
|
26
|
+
type ControlRequests,
|
|
27
|
+
controlRequests,
|
|
28
|
+
createRunController,
|
|
29
|
+
DEFAULT_PAUSE_DEADLINE_MS,
|
|
30
|
+
type RunController,
|
|
31
|
+
} from "./run-controller.ts";
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The bounded pause drain (ADR-0024): wrap-up steer, then abort at the
|
|
3
|
+
* deadline, then force-close through the Run's reap ladder.
|
|
4
|
+
*
|
|
5
|
+
* The function takes structural inputs only — Agent handles, a deadline, an
|
|
6
|
+
* admission closer and a stop promise — so a program-initiated pause can call
|
|
7
|
+
* it unchanged.
|
|
8
|
+
*
|
|
9
|
+
* The drain deliberately does not trip `AskLimit`, so an externally paused Ask
|
|
10
|
+
* never misreports `ASK_LIMIT`. A soft budget that trips at the same moment
|
|
11
|
+
* simply sends its own steer first; both paths converge on the same reap ladder.
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
/** Controls of one Ask in flight, as the drain sees them; a Handle never exposes these. */
|
|
15
|
+
export interface AskInFlight {
|
|
16
|
+
readonly agent: string;
|
|
17
|
+
/**
|
|
18
|
+
* Sends this Ask's wrap-up steer. Never throws; a refusal is reported as
|
|
19
|
+
* false. An Agent that never answers leaves it pending, so the drain bounds
|
|
20
|
+
* this call by its own deadline rather than trusting it to settle.
|
|
21
|
+
*/
|
|
22
|
+
wrapUp(): Promise<boolean>;
|
|
23
|
+
/** Aborts the turn. Never throws, and the drain never waits for its answer. */
|
|
24
|
+
abort(): Promise<boolean>;
|
|
25
|
+
/** Resolves when the Ask leaves flight, whatever its outcome. Never rejects. */
|
|
26
|
+
readonly settled: Promise<void>;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/** What the drain needs from one Agent; `Agent` satisfies it structurally. */
|
|
30
|
+
export interface DrainableAgent {
|
|
31
|
+
readonly name: string;
|
|
32
|
+
readonly askInFlight: AskInFlight | null;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export interface PauseDrainOptions {
|
|
36
|
+
/** Live reference to the Run's Agent list; read at drain start. */
|
|
37
|
+
readonly agents: readonly DrainableAgent[];
|
|
38
|
+
/** Wall-clock grace before the abort (ADR-0024). */
|
|
39
|
+
readonly deadlineMs: number;
|
|
40
|
+
/** Closes Ask and spawn admission before the first steer. */
|
|
41
|
+
readonly closeAdmission: () => void;
|
|
42
|
+
/** A stop request; it skips the remaining grace and takes the outcome. */
|
|
43
|
+
readonly stopped: Promise<void>;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** How one drain ended: paused, naming every Ask it cut short, or overridden by a stop. */
|
|
47
|
+
export type PauseDrainResult =
|
|
48
|
+
| { readonly kind: "paused"; readonly cutShort: readonly string[] }
|
|
49
|
+
| { readonly kind: "stopped" };
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Drains one Run for a pause and resolves once the Run may settle.
|
|
53
|
+
*
|
|
54
|
+
* It never waits after an abort: the reap ladder of `executeRun` is the
|
|
55
|
+
* force-close, and it is what stamps the incomplete marker (ADR-0021).
|
|
56
|
+
*/
|
|
57
|
+
export async function drainForPause(options: PauseDrainOptions): Promise<PauseDrainResult> {
|
|
58
|
+
options.closeAdmission();
|
|
59
|
+
const inFlight = options.agents
|
|
60
|
+
.map((agent) => agent.askInFlight)
|
|
61
|
+
.filter((ask): ask is AskInFlight => ask !== null);
|
|
62
|
+
if (inFlight.length === 0) return { kind: "paused", cutShort: [] };
|
|
63
|
+
// The grace starts before the first steer, so an Agent that never answers a
|
|
64
|
+
// command cannot hold the drain open past the deadline, and a stop always
|
|
65
|
+
// lands. A refused steer is ignored on purpose: the deadline bounds it too.
|
|
66
|
+
const grace = raceGrace(inFlight, options);
|
|
67
|
+
for (const ask of inFlight) void ask.wrapUp();
|
|
68
|
+
const outcome = await grace;
|
|
69
|
+
if (outcome === "stopped") return { kind: "stopped" };
|
|
70
|
+
if (outcome === "settled") return { kind: "paused", cutShort: [] };
|
|
71
|
+
return { kind: "paused", cutShort: abortRemaining(options.agents) };
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
type GraceOutcome = "settled" | "deadline" | "stopped";
|
|
75
|
+
|
|
76
|
+
/** Waits for every Ask to settle, the grace to elapse, or a stop to arrive. */
|
|
77
|
+
function raceGrace(
|
|
78
|
+
inFlight: readonly AskInFlight[],
|
|
79
|
+
options: PauseDrainOptions,
|
|
80
|
+
): Promise<GraceOutcome> {
|
|
81
|
+
let timer: ReturnType<typeof setTimeout> | undefined;
|
|
82
|
+
const deadline = new Promise<GraceOutcome>((resolve) => {
|
|
83
|
+
timer = setTimeout(() => resolve("deadline"), options.deadlineMs);
|
|
84
|
+
});
|
|
85
|
+
const settled = Promise.all(inFlight.map((ask) => ask.settled)).then<GraceOutcome>(
|
|
86
|
+
() => "settled",
|
|
87
|
+
);
|
|
88
|
+
const stopped = options.stopped.then<GraceOutcome>(() => "stopped");
|
|
89
|
+
return Promise.race([settled, deadline, stopped]).finally(() => {
|
|
90
|
+
clearTimeout(timer);
|
|
91
|
+
});
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Aborts every Ask still in flight and names its Agent as cut short. The
|
|
96
|
+
* answers are deliberately not awaited: an Agent that swallows the abort must
|
|
97
|
+
* not hold the Run away from its reap ladder.
|
|
98
|
+
*/
|
|
99
|
+
function abortRemaining(agents: readonly DrainableAgent[]): readonly string[] {
|
|
100
|
+
const remaining = agents
|
|
101
|
+
.map((agent) => agent.askInFlight)
|
|
102
|
+
.filter((ask): ask is AskInFlight => ask !== null);
|
|
103
|
+
for (const ask of remaining) void ask.abort();
|
|
104
|
+
return remaining.map((ask) => ask.agent);
|
|
105
|
+
}
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* External Run control: the AbortController analogue for a pause (ADR-0024).
|
|
3
|
+
*
|
|
4
|
+
* A control reader holds the controller and requests a pause or a stop; the Run
|
|
5
|
+
* reads the request side only. The first request wins, and a stop always
|
|
6
|
+
* overrides a drain that is already running.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
/** Default wall-clock grace one pause gives every Ask in flight (ADR-0024). */
|
|
10
|
+
export const DEFAULT_PAUSE_DEADLINE_MS = 60_000;
|
|
11
|
+
|
|
12
|
+
/** A terminal control request that settles the Run (ADR-0024). */
|
|
13
|
+
export type ControlRequest =
|
|
14
|
+
| { readonly kind: "pause"; readonly deadlineMs: number }
|
|
15
|
+
| { readonly kind: "stop" };
|
|
16
|
+
|
|
17
|
+
/** Run-side view: the first request wins, and a later stop overrides a drain. */
|
|
18
|
+
export interface ControlRequests {
|
|
19
|
+
/** The first pause or stop. Never rejects; never resolves without a request. */
|
|
20
|
+
readonly first: Promise<ControlRequest>;
|
|
21
|
+
/** A stop, whenever it arrives — including during a drain. Never rejects. */
|
|
22
|
+
readonly stopped: Promise<void>;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** External Run control handed to `executeRun`; the caller drives pause and stop. */
|
|
26
|
+
export interface RunController {
|
|
27
|
+
/** Requests a bounded drain. Coalesces once a first request landed. */
|
|
28
|
+
pause(deadlineMs?: number): void;
|
|
29
|
+
/** Requests an immediate stop; it outranks a pause, before or during a drain. */
|
|
30
|
+
stop(): void;
|
|
31
|
+
/** Read by `executeRun`; a control reader never touches it. */
|
|
32
|
+
readonly requests: ControlRequests;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** A resolve-only deferred, so no control promise can ever reject. */
|
|
36
|
+
interface Deferred<T> {
|
|
37
|
+
readonly promise: Promise<T>;
|
|
38
|
+
resolve(value: T): void;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
function deferred<T>(): Deferred<T> {
|
|
42
|
+
let resolve: (value: T) => void = () => {};
|
|
43
|
+
const promise = new Promise<T>((settle) => {
|
|
44
|
+
resolve = settle;
|
|
45
|
+
});
|
|
46
|
+
return { promise, resolve };
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** Creates one Run's control handle. Both requests are idempotent. */
|
|
50
|
+
export function createRunController(): RunController {
|
|
51
|
+
const first = deferred<ControlRequest>();
|
|
52
|
+
const stop = deferred<void>();
|
|
53
|
+
return {
|
|
54
|
+
pause(deadlineMs = DEFAULT_PAUSE_DEADLINE_MS): void {
|
|
55
|
+
first.resolve({ kind: "pause", deadlineMs });
|
|
56
|
+
},
|
|
57
|
+
stop(): void {
|
|
58
|
+
first.resolve({ kind: "stop" });
|
|
59
|
+
stop.resolve();
|
|
60
|
+
},
|
|
61
|
+
requests: { first: first.promise, stopped: stop.promise },
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* Folds an `AbortSignal` and a controller into one Run-side view.
|
|
67
|
+
*
|
|
68
|
+
* The signal is a stop request, so an abort settles the Run exactly as
|
|
69
|
+
* `controller.stop()` does, before or during a drain.
|
|
70
|
+
*/
|
|
71
|
+
export function controlRequests(
|
|
72
|
+
control: RunController | undefined,
|
|
73
|
+
signal: AbortSignal | undefined,
|
|
74
|
+
): ControlRequests {
|
|
75
|
+
const folded = createRunController();
|
|
76
|
+
if (control !== undefined) {
|
|
77
|
+
void control.requests.first.then((request) => {
|
|
78
|
+
if (request.kind === "stop") folded.stop();
|
|
79
|
+
else folded.pause(request.deadlineMs);
|
|
80
|
+
});
|
|
81
|
+
void control.requests.stopped.then(() => folded.stop());
|
|
82
|
+
}
|
|
83
|
+
if (signal !== undefined) {
|
|
84
|
+
if (signal.aborted) folded.stop();
|
|
85
|
+
else signal.addEventListener("abort", () => folded.stop(), { once: true });
|
|
86
|
+
}
|
|
87
|
+
return folded.requests;
|
|
88
|
+
}
|
package/src/events.ts
CHANGED
|
@@ -26,6 +26,25 @@ export type RunOutcome = "completed" | "failed" | "stopped" | "paused" | "interr
|
|
|
26
26
|
*/
|
|
27
27
|
export type SpawnOrigin = "spawn" | "fork";
|
|
28
28
|
|
|
29
|
+
/**
|
|
30
|
+
* Why a control request failed, or `BUSY` when a second Control Channel client
|
|
31
|
+
* asks while one holds the channel (ADR-0024, ADR-0054). It never says whether
|
|
32
|
+
* the Run acted: `run_end` is the durable phase-2 answer.
|
|
33
|
+
*/
|
|
34
|
+
export type ControlErrorCode =
|
|
35
|
+
| "MALFORMED"
|
|
36
|
+
| "UNSUPPORTED_VERSION"
|
|
37
|
+
| "UNKNOWN_CMD"
|
|
38
|
+
| "INVALID_FIELD"
|
|
39
|
+
| "DUPLICATE_ID"
|
|
40
|
+
| "FRAME_TOO_LONG"
|
|
41
|
+
| "RUN_SETTLING"
|
|
42
|
+
| "RUN_ENDED"
|
|
43
|
+
| "BUSY";
|
|
44
|
+
|
|
45
|
+
/** The outcome of one control request: taken, already in progress, or refused. */
|
|
46
|
+
export type ControlResponseStatus = "accepted" | "already_pausing" | "error";
|
|
47
|
+
|
|
29
48
|
/** The current, Ask-scoped observer projection derived from Agent frames. */
|
|
30
49
|
export type AgentActivity =
|
|
31
50
|
| { readonly type: "thinking" }
|
|
@@ -242,6 +261,27 @@ export type LifecycleEventBody =
|
|
|
242
261
|
* failed. Carries the publication error text. Absent on every other path.
|
|
243
262
|
*/
|
|
244
263
|
readonly checkpointLost?: string;
|
|
264
|
+
/**
|
|
265
|
+
* Path of the Checkpoint this Run published, present only when the Run
|
|
266
|
+
* paused or stopped and publication succeeded (ADR-0054). The Reattach
|
|
267
|
+
* client resumes from it, and refuses a path it did not expect.
|
|
268
|
+
*/
|
|
269
|
+
readonly checkpoint?: string;
|
|
270
|
+
}
|
|
271
|
+
| {
|
|
272
|
+
/**
|
|
273
|
+
* Phase-1 acknowledgement of exactly one control request (ADR-0024): the
|
|
274
|
+
* Run read the frame and decided. It is never durability — the Run's real
|
|
275
|
+
* answer is `run_end` (phase 2). `id` is null when the frame carried no
|
|
276
|
+
* usable id, so a client that waits on an id never hangs on a frame it
|
|
277
|
+
* can identify.
|
|
278
|
+
*/
|
|
279
|
+
readonly type: "control_response";
|
|
280
|
+
readonly id: string | null;
|
|
281
|
+
readonly status: ControlResponseStatus;
|
|
282
|
+
/** Present exactly when `status` is `"error"`. */
|
|
283
|
+
readonly code?: ControlErrorCode;
|
|
284
|
+
readonly message?: string;
|
|
245
285
|
};
|
|
246
286
|
|
|
247
287
|
/**
|
package/src/index.ts
CHANGED
|
@@ -76,6 +76,23 @@ export {
|
|
|
76
76
|
PROJECT_CONFIG_DIR,
|
|
77
77
|
resolveGlobalConfigDirectory,
|
|
78
78
|
} from "./config/index.ts";
|
|
79
|
+
export type {
|
|
80
|
+
ControlCommand,
|
|
81
|
+
ControlDecision,
|
|
82
|
+
ControlErrorCode,
|
|
83
|
+
ControlRequest,
|
|
84
|
+
ControlRequests,
|
|
85
|
+
ControlResponse,
|
|
86
|
+
ControlResponseStatus,
|
|
87
|
+
RunController,
|
|
88
|
+
} from "./control/index.ts";
|
|
89
|
+
export {
|
|
90
|
+
ControlCommandReader,
|
|
91
|
+
createRunController,
|
|
92
|
+
DEFAULT_PAUSE_DEADLINE_MS,
|
|
93
|
+
PAUSE_DEADLINE_MAX_MS,
|
|
94
|
+
PAUSE_DEADLINE_MIN_MS,
|
|
95
|
+
} from "./control/index.ts";
|
|
79
96
|
export type {
|
|
80
97
|
AskInvalidOutputOutcome,
|
|
81
98
|
AskLimitKind,
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
import type { ControlRequests, DrainableAgent } from "../control/index.ts";
|
|
2
|
+
import { drainForPause } from "../control/index.ts";
|
|
3
|
+
|
|
4
|
+
/** How one Run settled, before it reaps its Agents and publishes its Checkpoint. */
|
|
5
|
+
export type RunSettlement<Result> =
|
|
6
|
+
| { readonly outcome: "completed"; readonly value: Result }
|
|
7
|
+
| { readonly outcome: "failed"; readonly error: unknown }
|
|
8
|
+
| { readonly outcome: "paused"; readonly cutShort: readonly string[] }
|
|
9
|
+
| { readonly outcome: "stopped" };
|
|
10
|
+
|
|
11
|
+
export interface RunSettlementOptions<Result> {
|
|
12
|
+
/** Starts the Orchestration Program body; a synchronous throw is a Run failure. */
|
|
13
|
+
readonly program: () => Promise<Result> | Result;
|
|
14
|
+
/** The folded external control view of this Run. */
|
|
15
|
+
readonly requests: ControlRequests;
|
|
16
|
+
/** Live reference to the Run's Agent list. */
|
|
17
|
+
readonly agents: readonly DrainableAgent[];
|
|
18
|
+
/** Closes Ask and spawn admission; the drain calls it before its first steer. */
|
|
19
|
+
readonly closeAdmission: () => void;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Settles one Run: its own program, an external stop, or a bounded pause drain
|
|
24
|
+
* (ADR-0024). The program's handlers are attached synchronously at entry, so a
|
|
25
|
+
* Run waiting on a control request can never leave a rejection unhandled.
|
|
26
|
+
*
|
|
27
|
+
* A program that resolves during a drain wins, because work that settles
|
|
28
|
+
* naturally reports its own outcome. A program that rejects during a drain is
|
|
29
|
+
* absorbed: the rejection is a consequence of the closed admission or the
|
|
30
|
+
* cut-short Ask, so the Run stays `paused`. The rule reads a settlement latch
|
|
31
|
+
* rather than error codes, so no failure vocabulary decides an outcome.
|
|
32
|
+
*/
|
|
33
|
+
export async function settleRun<Result>(
|
|
34
|
+
options: RunSettlementOptions<Result>,
|
|
35
|
+
): Promise<RunSettlement<Result>> {
|
|
36
|
+
// Attached synchronously, so the program promise can never be an unhandled
|
|
37
|
+
// rejection while the Run waits on a control request instead.
|
|
38
|
+
const latch: { settled: RunSettlement<Result> | null } = { settled: null };
|
|
39
|
+
const program = startProgram(options.program);
|
|
40
|
+
// Registered before the race entrant below, so the latch always holds the
|
|
41
|
+
// program's own settlement by the time the race reports it.
|
|
42
|
+
program.then(
|
|
43
|
+
(value): void => {
|
|
44
|
+
latch.settled = { outcome: "completed", value };
|
|
45
|
+
},
|
|
46
|
+
(error: unknown): void => {
|
|
47
|
+
latch.settled = { outcome: "failed", error };
|
|
48
|
+
},
|
|
49
|
+
);
|
|
50
|
+
// The program is the first entrant, so a Run whose program has already
|
|
51
|
+
// settled keeps its own outcome when a control request lands in the same tick.
|
|
52
|
+
const first = await Promise.race([
|
|
53
|
+
program.then(
|
|
54
|
+
() => "program" as const,
|
|
55
|
+
() => "program" as const,
|
|
56
|
+
),
|
|
57
|
+
options.requests.first.then(() => "control" as const),
|
|
58
|
+
]);
|
|
59
|
+
if (first === "program") return settledLatch(latch.settled);
|
|
60
|
+
const control = await options.requests.first;
|
|
61
|
+
if (control.kind === "stop") {
|
|
62
|
+
options.closeAdmission();
|
|
63
|
+
return { outcome: "stopped" };
|
|
64
|
+
}
|
|
65
|
+
const drained = await drainForPause({
|
|
66
|
+
agents: options.agents,
|
|
67
|
+
deadlineMs: control.deadlineMs,
|
|
68
|
+
closeAdmission: options.closeAdmission,
|
|
69
|
+
stopped: options.requests.stopped,
|
|
70
|
+
});
|
|
71
|
+
const settled = latch.settled;
|
|
72
|
+
if (settled !== null && settled.outcome === "completed") return settled;
|
|
73
|
+
if (drained.kind === "stopped") return { outcome: "stopped" };
|
|
74
|
+
return { outcome: "paused", cutShort: drained.cutShort };
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* Starts the body without adding a scheduling hop, so a program that settles in
|
|
79
|
+
* the same tick as a control request still wins the race. A synchronous throw
|
|
80
|
+
* settles like a rejection.
|
|
81
|
+
*/
|
|
82
|
+
function startProgram<Result>(body: () => Promise<Result> | Result): Promise<Result> {
|
|
83
|
+
try {
|
|
84
|
+
return Promise.resolve(body());
|
|
85
|
+
} catch (error) {
|
|
86
|
+
return Promise.reject(error);
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
function settledLatch<Result>(latch: RunSettlement<Result> | null): RunSettlement<Result> {
|
|
91
|
+
if (latch === null) throw new Error("unreachable: the program settled without a latch");
|
|
92
|
+
return latch;
|
|
93
|
+
}
|
package/src/run/run.ts
CHANGED
|
@@ -13,6 +13,7 @@ import {
|
|
|
13
13
|
createCheckpointFlusher,
|
|
14
14
|
flushingSink,
|
|
15
15
|
interruptedResumeWarning,
|
|
16
|
+
keepsCheckpoint,
|
|
16
17
|
loadCassette,
|
|
17
18
|
type ProgramIdentity,
|
|
18
19
|
prepareRecordDestination,
|
|
@@ -28,7 +29,8 @@ import {
|
|
|
28
29
|
writeRecordingDiagnostic,
|
|
29
30
|
} from "../cassette/index.ts";
|
|
30
31
|
import { type EffectiveConfig, EMPTY_EFFECTIVE_CONFIG } from "../config/index.ts";
|
|
31
|
-
import {
|
|
32
|
+
import { controlRequests, createAskAdmission, type RunController } from "../control/index.ts";
|
|
33
|
+
import { YaagError } from "../errors.ts";
|
|
32
34
|
import type { EventSink, LifecycleEvent, RunOutcome, StampedEventSink } from "../events.ts";
|
|
33
35
|
import { selectProfile } from "../profile/index.ts";
|
|
34
36
|
import { applyEvent, initialSummary, type RunSummary } from "../summary/index.ts";
|
|
@@ -43,6 +45,7 @@ import {
|
|
|
43
45
|
import { validateArgs } from "./args-validation.ts";
|
|
44
46
|
import { type OrchestrationProgram, programDefinition } from "./define-run.ts";
|
|
45
47
|
import type { RunContext } from "./run-context.ts";
|
|
48
|
+
import { type RunSettlement, settleRun } from "./run-settlement.ts";
|
|
46
49
|
|
|
47
50
|
export interface RunOptions {
|
|
48
51
|
/** Where Agents come from. Defaults to real `pi --mode rpc` processes. */
|
|
@@ -72,6 +75,12 @@ export interface RunOptions {
|
|
|
72
75
|
readonly resume?: string;
|
|
73
76
|
/** Ends the Run early; every Agent is still reaped and costed. */
|
|
74
77
|
readonly signal?: AbortSignal;
|
|
78
|
+
/**
|
|
79
|
+
* External Run control: a bounded pause drain, or a stop (ADR-0024). A stop
|
|
80
|
+
* outranks a pause, before or during its drain. `signal` keeps working, and
|
|
81
|
+
* an abort is folded in as a stop.
|
|
82
|
+
*/
|
|
83
|
+
readonly control?: RunController;
|
|
75
84
|
/** Overrides the default checkpoint directory a stopped Run publishes into (ADR-0021). */
|
|
76
85
|
readonly checkpointDir?: string;
|
|
77
86
|
/**
|
|
@@ -187,10 +196,12 @@ export async function executeRun<Args, Result>(
|
|
|
187
196
|
});
|
|
188
197
|
const agents: Agent[] = [];
|
|
189
198
|
const startedAt = Date.now();
|
|
199
|
+
const askAdmission = createAskAdmission();
|
|
190
200
|
const spawnGate = makeSpawn({
|
|
191
201
|
factory,
|
|
192
202
|
agents,
|
|
193
203
|
emit,
|
|
204
|
+
askAdmission,
|
|
194
205
|
sessionDir: options.sessionDir,
|
|
195
206
|
programFile: options.programFile,
|
|
196
207
|
configExtensions: options.config?.extensions ?? EMPTY_EFFECTIVE_CONFIG.extensions,
|
|
@@ -211,16 +222,19 @@ export async function executeRun<Args, Result>(
|
|
|
211
222
|
|
|
212
223
|
// The program's settlement is held rather than rethrown from a `finally`, so
|
|
213
224
|
// publication can displace it when the checkpoint fails (ADR-0021).
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
225
|
+
const settlement = await settleRun({
|
|
226
|
+
program: () => definition.run(ctx),
|
|
227
|
+
requests: controlRequests(options.control, options.signal),
|
|
228
|
+
agents,
|
|
229
|
+
closeAdmission: () => {
|
|
230
|
+
askAdmission.close();
|
|
231
|
+
spawnGate.close();
|
|
232
|
+
},
|
|
233
|
+
});
|
|
234
|
+
const outcome: RunOutcome = settlement.outcome;
|
|
235
|
+
const settled = heldSettlement(settlement);
|
|
236
|
+
// Idempotent: a settlement that never drained has not closed admission yet.
|
|
237
|
+
askAdmission.close();
|
|
224
238
|
spawnGate.close();
|
|
225
239
|
await reapAll({ agents, emit });
|
|
226
240
|
// No flush may land after the settled artifact, or an acknowledged Run would
|
|
@@ -233,7 +247,7 @@ export async function executeRun<Args, Result>(
|
|
|
233
247
|
emit,
|
|
234
248
|
durationMs: Date.now() - startedAt,
|
|
235
249
|
summary,
|
|
236
|
-
...endingFrom(publication, outcome),
|
|
250
|
+
...endingFrom({ publication, outcome, destination, record: options.record }),
|
|
237
251
|
});
|
|
238
252
|
if (publication.kind === "displaced") throw publication.error;
|
|
239
253
|
if (!settled.ok) throw settled.error;
|
|
@@ -284,9 +298,29 @@ type Settlement<Result> =
|
|
|
284
298
|
| { readonly ok: true; readonly value: Result }
|
|
285
299
|
| { readonly ok: false; readonly error: unknown };
|
|
286
300
|
|
|
287
|
-
/**
|
|
288
|
-
|
|
289
|
-
|
|
301
|
+
/**
|
|
302
|
+
* Turns one settlement into the result the Run holds until its Checkpoint has
|
|
303
|
+
* landed. A stopped or paused Run rejects with its own code, so the caller can
|
|
304
|
+
* tell an ended Run from a failed one (ADR-0024).
|
|
305
|
+
*/
|
|
306
|
+
function heldSettlement<Result>(settlement: RunSettlement<Result>): Settlement<Result> {
|
|
307
|
+
switch (settlement.outcome) {
|
|
308
|
+
case "completed":
|
|
309
|
+
return { ok: true, value: settlement.value };
|
|
310
|
+
case "failed":
|
|
311
|
+
return { ok: false, error: settlement.error };
|
|
312
|
+
case "paused":
|
|
313
|
+
// The cut-short Agents are named here, so the rejection says which Asks
|
|
314
|
+
// the deadline ended rather than leaving that to the Checkpoint alone.
|
|
315
|
+
return { ok: false, error: new YaagError("RUN_PAUSED", pauseMessage(settlement.cutShort)) };
|
|
316
|
+
case "stopped":
|
|
317
|
+
return { ok: false, error: new YaagError("RUN_STOPPED", "run stopped") };
|
|
318
|
+
}
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
/** Names the Asks a pause deadline cut short, or reports a clean drain. */
|
|
322
|
+
function pauseMessage(cutShort: readonly string[]): string {
|
|
323
|
+
return cutShort.length === 0 ? "run paused" : `run paused, cutting short: ${cutShort.join(", ")}`;
|
|
290
324
|
}
|
|
291
325
|
|
|
292
326
|
/**
|
|
@@ -337,17 +371,6 @@ function selectLiveFactory(selection: FactorySelection): TransportFactory {
|
|
|
337
371
|
return selection.resume === null ? live : resumeTransport(selection.resume, live);
|
|
338
372
|
}
|
|
339
373
|
|
|
340
|
-
/** Rejects when the Run is stopped; never resolves. */
|
|
341
|
-
function stopped(signal: AbortSignal | undefined): Promise<never> {
|
|
342
|
-
return new Promise<never>((_resolve, reject) => {
|
|
343
|
-
if (!signal) return;
|
|
344
|
-
if (signal.aborted) reject(new YaagError("RUN_STOPPED", "run stopped"));
|
|
345
|
-
signal.addEventListener("abort", () => reject(new YaagError("RUN_STOPPED", "run stopped")), {
|
|
346
|
-
once: true,
|
|
347
|
-
});
|
|
348
|
-
});
|
|
349
|
-
}
|
|
350
|
-
|
|
351
374
|
interface ReapOptions {
|
|
352
375
|
readonly agents: readonly Agent[];
|
|
353
376
|
readonly emit: EventSink;
|
|
@@ -385,19 +408,39 @@ interface RunEndOptions {
|
|
|
385
408
|
readonly summary: RunSummary;
|
|
386
409
|
/** Publication error text when a requested Checkpoint was lost (ticket 04). */
|
|
387
410
|
readonly checkpointLost?: string;
|
|
411
|
+
/** Path of the published Checkpoint a paused or stopped Run resumes from (ADR-0054). */
|
|
412
|
+
readonly checkpoint?: string;
|
|
388
413
|
}
|
|
389
414
|
|
|
390
415
|
/**
|
|
391
416
|
* Folds one publication result into how the Run ends. A displaced publication
|
|
392
417
|
* takes the outcome; a lost Checkpoint keeps it and reports the loss instead.
|
|
393
418
|
*/
|
|
394
|
-
function endingFrom(
|
|
395
|
-
publication: RunCheckpointResult
|
|
396
|
-
outcome: RunOutcome
|
|
397
|
-
|
|
419
|
+
function endingFrom(options: {
|
|
420
|
+
readonly publication: RunCheckpointResult;
|
|
421
|
+
readonly outcome: RunOutcome;
|
|
422
|
+
readonly destination: string;
|
|
423
|
+
/** The `--record` destination, or undefined; it decides what is kept. */
|
|
424
|
+
readonly record: string | undefined;
|
|
425
|
+
}): {
|
|
426
|
+
readonly outcome: RunOutcome;
|
|
427
|
+
readonly checkpointLost?: string;
|
|
428
|
+
readonly checkpoint?: string;
|
|
429
|
+
} {
|
|
430
|
+
const { publication, outcome, destination, record } = options;
|
|
398
431
|
switch (publication.kind) {
|
|
399
432
|
case "published":
|
|
400
|
-
|
|
433
|
+
// A Run names a Checkpoint only when publication kept the artifact, and
|
|
434
|
+
// only a paused or stopped Run resumes from one (ADR-0054). `keepsCheckpoint`
|
|
435
|
+
// is the one rule for the first half, so no Run can name a file that
|
|
436
|
+
// publication just deleted.
|
|
437
|
+
return {
|
|
438
|
+
outcome,
|
|
439
|
+
...((outcome === "paused" || outcome === "stopped") &&
|
|
440
|
+
keepsCheckpoint({ outcome, ...(record === undefined ? {} : { record }) })
|
|
441
|
+
? { checkpoint: destination }
|
|
442
|
+
: {}),
|
|
443
|
+
};
|
|
401
444
|
case "lost":
|
|
402
445
|
return { outcome, checkpointLost: publication.message };
|
|
403
446
|
case "displaced":
|
|
@@ -406,10 +449,18 @@ function endingFrom(
|
|
|
406
449
|
}
|
|
407
450
|
|
|
408
451
|
/** Emits the Run's acknowledgement, the last Lifecycle Event of every Run. */
|
|
409
|
-
function emitRunEnd({
|
|
452
|
+
function emitRunEnd({
|
|
453
|
+
emit,
|
|
454
|
+
outcome,
|
|
455
|
+
durationMs,
|
|
456
|
+
summary,
|
|
457
|
+
checkpointLost,
|
|
458
|
+
checkpoint,
|
|
459
|
+
}: RunEndOptions): void {
|
|
410
460
|
emit({
|
|
411
461
|
type: "run_end",
|
|
412
462
|
...(checkpointLost === undefined ? {} : { checkpointLost }),
|
|
463
|
+
...(checkpoint === undefined ? {} : { checkpoint }),
|
|
413
464
|
ok: outcome === "completed",
|
|
414
465
|
outcome,
|
|
415
466
|
durationMs,
|
package/src/summary/summary.ts
CHANGED
|
@@ -78,6 +78,11 @@ export interface EndedRunSummary extends RunSummaryBase {
|
|
|
78
78
|
* artifact too. Carries the publication error text (ticket 04).
|
|
79
79
|
*/
|
|
80
80
|
readonly checkpointLost?: string;
|
|
81
|
+
/**
|
|
82
|
+
* Path of the Checkpoint the Run published; null when it kept none
|
|
83
|
+
* (ADR-0054). Only a paused or stopped Run names one.
|
|
84
|
+
*/
|
|
85
|
+
readonly checkpoint: string | null;
|
|
81
86
|
}
|
|
82
87
|
|
|
83
88
|
/**
|
|
@@ -218,6 +223,7 @@ function endRun(
|
|
|
218
223
|
endedAt: at,
|
|
219
224
|
durationMs: event.durationMs,
|
|
220
225
|
worstFrameGapMs: event.worstFrameGapMs,
|
|
226
|
+
checkpoint: event.checkpoint ?? null,
|
|
221
227
|
...(event.checkpointLost === undefined ? {} : { checkpointLost: event.checkpointLost }),
|
|
222
228
|
};
|
|
223
229
|
}
|