@parcha/agentrun-dsl 0.1.0-beta.2 → 0.1.0-beta.21
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/README.md +107 -17
- package/dist/author.d.ts +96 -0
- package/dist/author.js +320 -0
- package/dist/authoring.js +1 -1
- package/dist/cli.js +8 -3
- package/dist/code-exec.d.ts +6 -0
- package/dist/code-exec.js +126 -0
- package/dist/decision-receipts.d.ts +98 -0
- package/dist/decision-receipts.js +51 -0
- package/dist/dry-run.d.ts +14 -1
- package/dist/dry-run.js +39 -13
- package/dist/graph.d.ts +83 -0
- package/dist/graph.js +231 -0
- package/dist/index.d.ts +12 -4
- package/dist/index.js +6 -2
- package/dist/inspection.js +2 -2
- package/dist/job.d.ts +14 -0
- package/dist/job.js +5 -0
- package/dist/long-timer.d.ts +7 -0
- package/dist/long-timer.js +22 -0
- package/dist/observer-snapshot.d.ts +3 -0
- package/dist/observer-snapshot.js +46 -0
- package/dist/predicates.d.ts +4 -0
- package/dist/predicates.js +19 -2
- package/dist/recovery/binding.d.ts +10 -0
- package/dist/recovery/binding.js +43 -0
- package/dist/recovery/call-key.d.ts +13 -0
- package/dist/recovery/call-key.js +24 -0
- package/dist/recovery/canonical-hash.d.ts +7 -0
- package/dist/recovery/canonical-hash.js +22 -0
- package/dist/recovery/driver.d.ts +208 -0
- package/dist/recovery/driver.js +1222 -0
- package/dist/recovery/effect-failure.d.ts +34 -0
- package/dist/recovery/effect-failure.js +62 -0
- package/dist/recovery/errors.d.ts +31 -0
- package/dist/recovery/errors.js +51 -0
- package/dist/recovery/execution-path.d.ts +53 -0
- package/dist/recovery/execution-path.js +167 -0
- package/dist/recovery/file-store.d.ts +7 -0
- package/dist/recovery/file-store.js +131 -0
- package/dist/recovery/frozen-snapshot.d.ts +244 -0
- package/dist/recovery/frozen-snapshot.js +171 -0
- package/dist/recovery/handoff-block.d.ts +36 -0
- package/dist/recovery/handoff-block.js +148 -0
- package/dist/recovery/handoff-digest.d.ts +58 -0
- package/dist/recovery/handoff-digest.js +195 -0
- package/dist/recovery/handoff-files.d.ts +54 -0
- package/dist/recovery/handoff-files.js +162 -0
- package/dist/recovery/handoff-receipts.d.ts +42 -0
- package/dist/recovery/handoff-receipts.js +53 -0
- package/dist/recovery/handoff-redact.d.ts +12 -0
- package/dist/recovery/handoff-redact.js +44 -0
- package/dist/recovery/handoff.d.ts +44 -0
- package/dist/recovery/handoff.js +46 -0
- package/dist/recovery/index.d.ts +18 -0
- package/dist/recovery/index.js +16 -0
- package/dist/recovery/item-state.d.ts +48 -0
- package/dist/recovery/item-state.js +89 -0
- package/dist/recovery/journal.d.ts +28 -0
- package/dist/recovery/journal.js +139 -0
- package/dist/recovery/memory-store.d.ts +4 -0
- package/dist/recovery/memory-store.js +20 -0
- package/dist/recovery/store.d.ts +105 -0
- package/dist/recovery/store.js +6 -0
- package/dist/recovery/testing/conformance.d.ts +4 -0
- package/dist/recovery/testing/conformance.js +268 -0
- package/dist/recovery/testing/crash-points.d.ts +18 -0
- package/dist/recovery/testing/crash-points.js +43 -0
- package/dist/recovery/testing/crash-sweep.d.ts +65 -0
- package/dist/recovery/testing/crash-sweep.js +146 -0
- package/dist/recovery/testing/index.d.ts +3 -0
- package/dist/recovery/testing/index.js +4 -0
- package/dist/recovery/testing/preload.d.ts +1 -0
- package/dist/recovery/testing/preload.js +3 -0
- package/dist/recovery/transport-facts.d.ts +23 -0
- package/dist/recovery/transport-facts.js +46 -0
- package/dist/recovery/with-recovery.d.ts +44 -0
- package/dist/recovery/with-recovery.js +87 -0
- package/dist/system-one.d.ts +17 -1
- package/dist/system-one.js +62 -5
- package/dist/vocabulary.d.ts +42 -0
- package/dist/vocabulary.js +74 -0
- package/dist/workflow-shape.d.ts +7 -0
- package/dist/workflow-shape.js +85 -62
- package/dist/workflow.d.ts +187 -16
- package/dist/workflow.js +1007 -332
- package/package.json +18 -2
- package/schema/workflow.schema.json +251 -15
- package/skills/author/SKILL.md +122 -0
- package/skills/author/examples/evidence-gate.input.json +6 -0
- package/skills/author/examples/evidence-gate.json +125 -0
- package/skills/author/examples/read-file.input.json +1 -0
- package/skills/author/examples/read-file.json +44 -0
- package/skills/author/examples/read-source-decision.input.json +4 -0
- package/skills/author/examples/read-source-decision.json +37 -0
- package/skills/author/examples/release-note.txt +10 -0
- package/skills/author/examples/review-release-notes.input.json +6 -0
- package/skills/author/examples/review-release-notes.json +123 -0
- package/skills/author/references/jev-decisions.md +125 -0
- package/skills/author/references/language.md +118 -0
- package/skills/author/references/sdk-authoring.md +11 -0
- package/skills/author/references/workflow-format.md +137 -0
|
@@ -0,0 +1,244 @@
|
|
|
1
|
+
import { type PartialSlot, type Sha256, type StateDelta } from "./item-state.js";
|
|
2
|
+
export declare const FROZEN_SNAPSHOT_SCHEMA = "agentrun.frozen_run.v3";
|
|
3
|
+
/** The keyed layout: what lies in a map item is kept in that item's record beside the state, and a state the driver
|
|
4
|
+
* references is kept once by its digest, so no record rewritten at a commit grows with a map's items. */
|
|
5
|
+
export declare const FROZEN_SNAPSHOT_SCHEMA_V4 = "agentrun.frozen_run.v4";
|
|
6
|
+
type State = Record<string, unknown>;
|
|
7
|
+
export { stateDelta, applyStateDelta, canonicalJson, type StateDelta, type Sha256, type PartialSlot } from "./item-state.js";
|
|
8
|
+
/** A map the run started: how many items it has, how many item records were written (always the first ones: items
|
|
9
|
+
* start in order, and an item has a record from its start), and the digest of its base. */
|
|
10
|
+
export type MapEntry = {
|
|
11
|
+
length: number;
|
|
12
|
+
items: number;
|
|
13
|
+
base: string;
|
|
14
|
+
};
|
|
15
|
+
/** One map item's share of the driver's state (`agentrun.items`), keyed by the item's path. Every path in it lies in
|
|
16
|
+
* this item and in no item nested in it. */
|
|
17
|
+
export type ItemRecord = {
|
|
18
|
+
driver: string;
|
|
19
|
+
map: string;
|
|
20
|
+
index: number;
|
|
21
|
+
base: string;
|
|
22
|
+
/** The journal revision of the commit that wrote this value. */
|
|
23
|
+
revision: number;
|
|
24
|
+
/** `failed`: the item ended on its failure, which `outcome` holds; its map collects its items' failures. */
|
|
25
|
+
status: "running" | "committed" | "failed";
|
|
26
|
+
/** Present exactly when `status` is `failed`. */
|
|
27
|
+
outcome?: ItemOutcome;
|
|
28
|
+
frame: {
|
|
29
|
+
done: string[];
|
|
30
|
+
states: Record<string, StateDelta>;
|
|
31
|
+
chains: PathFrame["chains"];
|
|
32
|
+
loops: PathFrame["loops"];
|
|
33
|
+
routes: PathFrame["routes"];
|
|
34
|
+
inputs: PathFrame["inputs"];
|
|
35
|
+
steps: PathFrame["steps"];
|
|
36
|
+
};
|
|
37
|
+
effects: string[];
|
|
38
|
+
clocks: Record<string, number>;
|
|
39
|
+
files: Record<string, string>;
|
|
40
|
+
unknownResponses: Record<string, unknown>;
|
|
41
|
+
/** Maps started inside this item. */
|
|
42
|
+
maps: Record<string, MapEntry>;
|
|
43
|
+
};
|
|
44
|
+
/** The driver's own record in the keyed layout: the v3 snapshot without what lies in map items, its frame's states by
|
|
45
|
+
* digest, and the maps the run started. */
|
|
46
|
+
export type FrozenSnapshotV4 = Omit<FrozenSnapshot, "schema" | "pin"> & {
|
|
47
|
+
schema: typeof FROZEN_SNAPSHOT_SCHEMA_V4;
|
|
48
|
+
pin: Omit<PathFrame, "states" | "partial"> & {
|
|
49
|
+
states: Record<string, string>;
|
|
50
|
+
partial?: {
|
|
51
|
+
path: string;
|
|
52
|
+
as: string;
|
|
53
|
+
results: string;
|
|
54
|
+
};
|
|
55
|
+
};
|
|
56
|
+
maps: Record<string, MapEntry>;
|
|
57
|
+
};
|
|
58
|
+
/** Two values a state holds under one key are the same value. A key an item copied from its base holds the base's own
|
|
59
|
+
* object, or one with the same JSON. */
|
|
60
|
+
/** A map item's state at `path`, rebuilt as the driver rebuilds it (`./item-state.ts`, which imports nothing): the
|
|
61
|
+
* `agentrun.states` value its `base` names, with the item's `set` and `unset` for that path applied, checked against
|
|
62
|
+
* that path's `sha256`. `item` is an `agentrun.items` value; `states` holds `agentrun.states` values by SHA-256. When
|
|
63
|
+
* the base is missing, or a digest differs, it says why and never guesses. `sha256` defaults to Node's. */
|
|
64
|
+
export declare function itemState(item: unknown, states: Readonly<Record<string, unknown>> | ReadonlyMap<string, unknown>, path: string, options?: {
|
|
65
|
+
sha256?: Sha256;
|
|
66
|
+
}): {
|
|
67
|
+
state: State;
|
|
68
|
+
} | {
|
|
69
|
+
unreadable: string;
|
|
70
|
+
};
|
|
71
|
+
/** A failed map's finished results from the driver state's `pin.partial` (`./item-state.ts`, which imports nothing): in
|
|
72
|
+
* the keyed layout, the list of slots and each result read by digest and checked; a whole-state run's list as it is.
|
|
73
|
+
* Each slot is null (the item never finished), `{ result }`, or `{ unreadable }`, never a guess. `sha256` defaults to
|
|
74
|
+
* Node's. */
|
|
75
|
+
export declare function partialResults(partial: unknown, states: Readonly<Record<string, unknown>> | ReadonlyMap<string, unknown>, options?: {
|
|
76
|
+
sha256?: Sha256;
|
|
77
|
+
}): {
|
|
78
|
+
slots: PartialSlot[];
|
|
79
|
+
} | {
|
|
80
|
+
unreadable: string;
|
|
81
|
+
};
|
|
82
|
+
/** What a question's receipts need beyond its answer: the request's producer invocation, its size and its
|
|
83
|
+
* latency. */
|
|
84
|
+
export type QuestionReceipts = {
|
|
85
|
+
invocation: string;
|
|
86
|
+
request_bytes: number;
|
|
87
|
+
latency_ms: number;
|
|
88
|
+
};
|
|
89
|
+
/** A committed route: the judge's answer for the route's question, whole, so a resume re-derives the
|
|
90
|
+
* same branch from it without asking again; the branch it runs (the node's unsure branch when the answer
|
|
91
|
+
* was unsure), with the answer's choice and the unsure flag beside it (a checkpoint that holds a decision
|
|
92
|
+
* without those two fields has neither: the driver derives all three from `result` when it opens). `receipts`
|
|
93
|
+
* is set in the commit that decides and cleared by the save after the host has written what it keeps of the
|
|
94
|
+
* answer: a resume that finds it set writes them, so a crash between the two never leaves the spend without
|
|
95
|
+
* its receipts. A host that keeps nothing commits null. */
|
|
96
|
+
export type RouteDecision = {
|
|
97
|
+
label: string;
|
|
98
|
+
branch: string;
|
|
99
|
+
choice: string;
|
|
100
|
+
unsure: boolean;
|
|
101
|
+
request_sha256: string | null;
|
|
102
|
+
result: Record<string, unknown>;
|
|
103
|
+
receipts: QuestionReceipts | null;
|
|
104
|
+
};
|
|
105
|
+
/** What one document's run committed, by execution path. `done` is every committed path in commit
|
|
106
|
+
* order; `states` keeps the committed state of the paths a resume may still be answered from (a
|
|
107
|
+
* chain's frontier step, a finished map item or parallel branch whose structure has not committed, a
|
|
108
|
+
* loop's iterations); `chains` names each chain's frontier; `loops` counts each loop's completed
|
|
109
|
+
* iterations; `routes` holds each route's committed decision; `inputs` binds each started, uncommitted
|
|
110
|
+
* path to the state it started from; `steps` holds each LLM step's execution record. */
|
|
111
|
+
export type PathFrame = {
|
|
112
|
+
/** The state the document started from, bound at its first resume: every later process starts the
|
|
113
|
+
* document from the same bytes or is refused. */
|
|
114
|
+
input: string | null;
|
|
115
|
+
done: string[];
|
|
116
|
+
states: Record<string, State>;
|
|
117
|
+
chains: Record<string, {
|
|
118
|
+
index: number;
|
|
119
|
+
path: string;
|
|
120
|
+
}>;
|
|
121
|
+
loops: Record<string, number>;
|
|
122
|
+
routes: Record<string, RouteDecision>;
|
|
123
|
+
inputs: Record<string, string>;
|
|
124
|
+
steps: Record<string, StepRecord>;
|
|
125
|
+
/** A map that ended on an item's failure: the finished items' results, keyed by the map's `as`, so
|
|
126
|
+
* the handoff carries the completed child work and a redispatch never loses it. */
|
|
127
|
+
partial?: {
|
|
128
|
+
path: string;
|
|
129
|
+
as: string;
|
|
130
|
+
results: unknown[];
|
|
131
|
+
};
|
|
132
|
+
/** The map items that ended on their failure (`onItemFailure: "collect"`), by the item's path (`<map>/items/<i>`): an
|
|
133
|
+
* item here is answered from its row and its body never runs again. Kept with the run, as committed paths are. */
|
|
134
|
+
failures?: Record<string, ItemOutcome>;
|
|
135
|
+
};
|
|
136
|
+
/** How a map item that ended on its failure ended: the failing node's label, the failure's code and its message. */
|
|
137
|
+
export type ItemOutcome = {
|
|
138
|
+
code: string;
|
|
139
|
+
label: string;
|
|
140
|
+
message: string;
|
|
141
|
+
};
|
|
142
|
+
/** The recovery driver's durable state. It lives whole in the journal; each commit replaces it. No run
|
|
143
|
+
* clock: clocks exist only per effect. */
|
|
144
|
+
export type FrozenSnapshot = {
|
|
145
|
+
schema: typeof FROZEN_SNAPSHOT_SCHEMA;
|
|
146
|
+
/** What the run of the workflow document committed. */
|
|
147
|
+
pin: PathFrame;
|
|
148
|
+
startedAt: number;
|
|
149
|
+
status: "running" | "paused" | "cancelled";
|
|
150
|
+
/** Effect-level clocks (poll windows, attempt deadlines), absolute, keyed by effect. */
|
|
151
|
+
clocks: Record<string, number>;
|
|
152
|
+
files: Record<string, string>;
|
|
153
|
+
unknownResponses?: Record<string, unknown>;
|
|
154
|
+
/** Spend by question nodes, which have no session of their own: metered per answer, carried with the frames. */
|
|
155
|
+
questionSpendUsd?: number;
|
|
156
|
+
/** The durable form of the escalation that ended the run; set once, reused on resume. */
|
|
157
|
+
escalation?: EscalationRow;
|
|
158
|
+
};
|
|
159
|
+
export type StepRecord = {
|
|
160
|
+
label: string;
|
|
161
|
+
attempt: number;
|
|
162
|
+
attemptsAllowed: number;
|
|
163
|
+
status: "running" | "closed" | "failed" | "submitted";
|
|
164
|
+
/** The failure that failed the step, when it was an item failure (`isItemFailure`) in an item of a map that collects
|
|
165
|
+
* its items' failures: a later open refuses the step with it, so the item ends on the same failure in every process. */
|
|
166
|
+
failure?: {
|
|
167
|
+
code: string;
|
|
168
|
+
message: string;
|
|
169
|
+
};
|
|
170
|
+
};
|
|
171
|
+
export type EscalationRow = {
|
|
172
|
+
kind: string;
|
|
173
|
+
stage: string;
|
|
174
|
+
summary: string;
|
|
175
|
+
state: Record<string, unknown>;
|
|
176
|
+
workflow_sha_used: string;
|
|
177
|
+
pin_sha256: string;
|
|
178
|
+
/** The node that ended the run: the gate that fired or the LLM step that failed. */
|
|
179
|
+
step_label: string;
|
|
180
|
+
step_exec_id: string | null;
|
|
181
|
+
cost_usd: number;
|
|
182
|
+
turns: number;
|
|
183
|
+
effect_calls: number;
|
|
184
|
+
evidence_dir: string;
|
|
185
|
+
/** The identity the continuation of an escalated run runs under. */
|
|
186
|
+
tail: string;
|
|
187
|
+
/** The escalation commit's revision: what the continuation binds on. */
|
|
188
|
+
revision: number;
|
|
189
|
+
/** The typed failure that ended the attempt, when one did: its code and its typed detail (a rail's
|
|
190
|
+
* limit), so the handoff keeps the classification a resume reads back. */
|
|
191
|
+
failure?: {
|
|
192
|
+
code: string;
|
|
193
|
+
detail?: Record<string, number | string>;
|
|
194
|
+
};
|
|
195
|
+
};
|
|
196
|
+
/** What a saved snapshot is checked against: whether a path resolves in the run's document. */
|
|
197
|
+
export type FrozenShape = {
|
|
198
|
+
resolves: (path: string) => boolean;
|
|
199
|
+
};
|
|
200
|
+
export declare const emptyPathFrame: () => PathFrame;
|
|
201
|
+
/** Whether a value is an item's committed failure: three strings, and nothing else. */
|
|
202
|
+
export declare const isItemOutcome: (value: unknown) => value is ItemOutcome;
|
|
203
|
+
/** Refuses a saved snapshot the driver could not have produced for this run. */
|
|
204
|
+
export declare function validateFrozenSnapshot(saved: any, shape: FrozenShape): void;
|
|
205
|
+
/** The snapshot a driver runs under: the saved one (a paused run resumes running, retired keys
|
|
206
|
+
* dropped), or a fresh one. */
|
|
207
|
+
export declare function openedFrozenSnapshot(saved: FrozenSnapshot | null | undefined): FrozenSnapshot;
|
|
208
|
+
/** The snapshot as the journal stores it. Workflow state contains optional internal fields; this
|
|
209
|
+
* matches its JSON checkpoint semantics, while refusing non-finite values instead of silently
|
|
210
|
+
* changing them to null. */
|
|
211
|
+
export declare function serializeFrozenSnapshot(snapshot: FrozenSnapshot): FrozenSnapshot;
|
|
212
|
+
/** The namespace a frame's sessions and effects are named under. The driver writes `step`; `adapt` names the
|
|
213
|
+
* sessions and effects of a second document's frame in an older journal. */
|
|
214
|
+
export type FrameTag = "step" | "adapt";
|
|
215
|
+
/** The session an LLM step's attempt runs in: the step's label (for the reader: labels repeat across
|
|
216
|
+
* loop iterations and map items), its frame and execution path (what makes it unique), and the
|
|
217
|
+
* attempt. */
|
|
218
|
+
export declare function frozenStepSessionId(driver: string, label: string, frame: FrameTag, path: string, attempt: number): string;
|
|
219
|
+
/** A step's short identity where a name must be short and file-safe (its files, the continuation an
|
|
220
|
+
* escalation hands off to): a digest of its frame and execution path, so it is the same in every process. */
|
|
221
|
+
export declare function frozenStepId(frame: FrameTag, path: string): string;
|
|
222
|
+
/** The receipt id of a call's `ordinal`th effect at an execution path. */
|
|
223
|
+
export declare function frozenEffectId(frame: FrameTag, path: string, ordinal: number): string;
|
|
224
|
+
/** The execution path and ordinal an effect id names: the inverse of `frozenEffectId`. */
|
|
225
|
+
export declare function frozenEffectPath(id: string): {
|
|
226
|
+
path: string;
|
|
227
|
+
ordinal: number;
|
|
228
|
+
} | undefined;
|
|
229
|
+
/** An LLM step's execution record under admission. The first call fixes the label the interpreter
|
|
230
|
+
* names the step by and the retry limit; a later call gets the same
|
|
231
|
+
* record. A closed attempt advances to the next attempt here, and only here, when an admission asks
|
|
232
|
+
* and an attempt remains, else the step fails. `changed` says the snapshot owes a save. */
|
|
233
|
+
export declare function admitFrozenStep(steps: Record<string, StepRecord>, path: string, label: string, admission?: {
|
|
234
|
+
attemptsAllowed: number;
|
|
235
|
+
}): {
|
|
236
|
+
step: StepRecord;
|
|
237
|
+
changed: boolean;
|
|
238
|
+
};
|
|
239
|
+
/** The current attempt ended without a submission: `closed` until a retry is admitted, or
|
|
240
|
+
* `failed` when the failure is final or no attempt remains. */
|
|
241
|
+
export declare function closeFrozenStepAttempt(step: StepRecord, final: boolean, failure?: StepRecord["failure"]): void;
|
|
242
|
+
/** The run-wide stop the driver applies: the host's pause or cancel it was handed, or null when it keeps
|
|
243
|
+
* running. A cancelled snapshot stays cancelled. */
|
|
244
|
+
export declare function frozenStop(status: FrozenSnapshot["status"], requested: "pause" | "cancel" | undefined): "paused" | "cancelled" | null;
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
// The recovery driver's durable state and its workflow-free transitions. Everything the driver runs is
|
|
2
|
+
// addressed by the interpreter's execution path, an opaque string here: the driver (`driver.ts`) reads
|
|
3
|
+
// the path grammar, maps nodes onto these records and owns the store's lifecycle.
|
|
4
|
+
import { createHash } from "node:crypto";
|
|
5
|
+
import { RecoveryError } from "./errors.js";
|
|
6
|
+
import { itemState as rebuildItemState, partialResults as readPartialResults } from "./item-state.js";
|
|
7
|
+
const failure = (code, message) => new RecoveryError(message, code);
|
|
8
|
+
export const FROZEN_SNAPSHOT_SCHEMA = "agentrun.frozen_run.v3";
|
|
9
|
+
/** The keyed layout: what lies in a map item is kept in that item's record beside the state, and a state the driver
|
|
10
|
+
* references is kept once by its digest, so no record rewritten at a commit grows with a map's items. */
|
|
11
|
+
export const FROZEN_SNAPSHOT_SCHEMA_V4 = "agentrun.frozen_run.v4";
|
|
12
|
+
export { stateDelta, applyStateDelta, canonicalJson } from "./item-state.js";
|
|
13
|
+
/** Two values a state holds under one key are the same value. A key an item copied from its base holds the base's own
|
|
14
|
+
* object, or one with the same JSON. */
|
|
15
|
+
/** A map item's state at `path`, rebuilt as the driver rebuilds it (`./item-state.ts`, which imports nothing): the
|
|
16
|
+
* `agentrun.states` value its `base` names, with the item's `set` and `unset` for that path applied, checked against
|
|
17
|
+
* that path's `sha256`. `item` is an `agentrun.items` value; `states` holds `agentrun.states` values by SHA-256. When
|
|
18
|
+
* the base is missing, or a digest differs, it says why and never guesses. `sha256` defaults to Node's. */
|
|
19
|
+
export function itemState(item, states, path, options = {}) {
|
|
20
|
+
return rebuildItemState(item, states, path, { sha256: options.sha256 ?? ((text) => createHash("sha256").update(text).digest("hex")) });
|
|
21
|
+
}
|
|
22
|
+
/** A failed map's finished results from the driver state's `pin.partial` (`./item-state.ts`, which imports nothing): in
|
|
23
|
+
* the keyed layout, the list of slots and each result read by digest and checked; a whole-state run's list as it is.
|
|
24
|
+
* Each slot is null (the item never finished), `{ result }`, or `{ unreadable }`, never a guess. `sha256` defaults to
|
|
25
|
+
* Node's. */
|
|
26
|
+
export function partialResults(partial, states, options = {}) {
|
|
27
|
+
return readPartialResults(partial, states, { sha256: options.sha256 ?? ((text) => createHash("sha256").update(text).digest("hex")) });
|
|
28
|
+
}
|
|
29
|
+
export const emptyPathFrame = () => ({ input: null, done: [], states: {}, chains: {}, loops: {}, routes: {}, inputs: {}, steps: {} });
|
|
30
|
+
const record = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
|
|
31
|
+
const SHA256 = /^[a-f0-9]{64}$/;
|
|
32
|
+
/** `value` as an object whose fields can be read, or null. */
|
|
33
|
+
const fields = (value) => record(value) ? value : null;
|
|
34
|
+
const entriesOf = (value) => { const object = fields(value); return object ? Object.entries(object) : null; };
|
|
35
|
+
const isStepFailure = (value) => {
|
|
36
|
+
const at = fields(value);
|
|
37
|
+
return Boolean(at && Object.keys(at).length === 2 && typeof at.code === "string" && typeof at.message === "string");
|
|
38
|
+
};
|
|
39
|
+
/** Whether a value is an item's committed failure: three strings, and nothing else. */
|
|
40
|
+
export const isItemOutcome = (value) => {
|
|
41
|
+
const at = fields(value);
|
|
42
|
+
return Boolean(at && Object.keys(at).length === 3 && typeof at.code === "string" && typeof at.label === "string" && typeof at.message === "string");
|
|
43
|
+
};
|
|
44
|
+
const nonNegativeInt = (value) => Number.isSafeInteger(value) && value >= 0;
|
|
45
|
+
/** Whether a saved frame is one the driver could have written for its document. */
|
|
46
|
+
function validFrame(value, resolves) {
|
|
47
|
+
const frame = fields(value);
|
|
48
|
+
if (!frame || !Array.isArray(frame.done) || !frame.done.every((path) => typeof path === "string" && resolves(path)))
|
|
49
|
+
return false;
|
|
50
|
+
const doneList = frame.done;
|
|
51
|
+
const done = new Set(doneList);
|
|
52
|
+
if (done.size !== doneList.length)
|
|
53
|
+
return false;
|
|
54
|
+
if (!(frame.input === null ? doneList.length === 0 : typeof frame.input === "string" && SHA256.test(frame.input)))
|
|
55
|
+
return false;
|
|
56
|
+
const [states, chains, loops, routes, inputs, steps] = [frame.states, frame.chains, frame.loops, frame.routes, frame.inputs, frame.steps].map(entriesOf);
|
|
57
|
+
const partial = frame.partial === undefined ? undefined : fields(frame.partial);
|
|
58
|
+
const failures = frame.failures === undefined ? [] : entriesOf(frame.failures);
|
|
59
|
+
return Boolean(states && states.every(([path, state]) => done.has(path) && record(state))
|
|
60
|
+
&& failures && failures.every(([item, outcome]) => /\/items\/(?:0|[1-9]\d*)$/.test(item) && resolves(`${item}/body`) && isItemOutcome(outcome))
|
|
61
|
+
&& chains && chains.every(([, head]) => { const at = fields(head); return Boolean(at && nonNegativeInt(at.index) && typeof at.path === "string" && done.has(at.path)); })
|
|
62
|
+
&& loops && loops.every(([loop, count]) => resolves(loop) && nonNegativeInt(count))
|
|
63
|
+
&& routes && routes.every(([route, decision]) => {
|
|
64
|
+
const at = fields(decision);
|
|
65
|
+
const receipts = fields(at?.receipts);
|
|
66
|
+
return Boolean(at && resolves(route) && typeof at.label === "string" && typeof at.branch === "string" && ((typeof at.choice === "string" && typeof at.unsure === "boolean") || (at.choice === undefined && at.unsure === undefined)) && record(at.result) && (at.request_sha256 === null || typeof at.request_sha256 === "string")
|
|
67
|
+
&& (at.receipts === null || (receipts && typeof receipts.invocation === "string" && nonNegativeInt(receipts.request_bytes) && Number.isFinite(receipts.latency_ms))));
|
|
68
|
+
})
|
|
69
|
+
&& inputs && inputs.every(([path, digest]) => resolves(path) && !done.has(path) && typeof digest === "string" && SHA256.test(digest))
|
|
70
|
+
&& steps && steps.every(([path, step]) => {
|
|
71
|
+
const at = fields(step);
|
|
72
|
+
return Boolean(at && resolves(path) && typeof at.label === "string"
|
|
73
|
+
&& nonNegativeInt(at.attempt) && Number.isSafeInteger(at.attemptsAllowed) && at.attemptsAllowed >= 1
|
|
74
|
+
&& ["running", "closed", "failed", "submitted"].includes(String(at.status))
|
|
75
|
+
&& (at.failure === undefined || (at.status === "failed" && isStepFailure(at.failure))));
|
|
76
|
+
})
|
|
77
|
+
&& (partial === undefined || (partial && typeof partial.path === "string" && resolves(partial.path) && typeof partial.as === "string" && Array.isArray(partial.results))));
|
|
78
|
+
}
|
|
79
|
+
/** Refuses a saved snapshot the driver could not have produced for this run. */
|
|
80
|
+
export function validateFrozenSnapshot(saved, shape) {
|
|
81
|
+
if (!record(saved) || saved.schema !== FROZEN_SNAPSHOT_SCHEMA || !Number.isFinite(saved.startedAt)
|
|
82
|
+
|| (saved.questionSpendUsd !== undefined && !(Number.isFinite(saved.questionSpendUsd) && saved.questionSpendUsd >= 0))
|
|
83
|
+
|| !["running", "paused", "cancelled"].includes(saved.status)
|
|
84
|
+
|| !record(saved.clocks) || !Object.values(saved.clocks).every(Number.isFinite)
|
|
85
|
+
|| !record(saved.files) || !Object.values(saved.files).every(value => typeof value === "string" && SHA256.test(value))
|
|
86
|
+
|| !validFrame(saved.pin, shape.resolves)
|
|
87
|
+
|| (saved.escalation !== undefined && (!record(saved.escalation) || typeof saved.escalation.tail !== "string" || typeof saved.escalation.kind !== "string" || !Number.isSafeInteger(saved.escalation.revision)))
|
|
88
|
+
// A checkpoint that holds a second document's frame is refused: the driver runs one document.
|
|
89
|
+
|| saved.adaptation !== undefined) {
|
|
90
|
+
throw failure("FROZEN_CHECKPOINT_INVALID", "Invalid frozen recovery checkpoint");
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
/** Keys an older journal may hold that the driver neither reads nor writes: dropped on open, so a
|
|
94
|
+
* checkpoint that has them does not carry them forward as stale counts. */
|
|
95
|
+
const RETIRED_SNAPSHOT_KEYS = ["unpricedQuestions", "effectCalls", "effectGrants", "effectSpendUsd", "effectHoldsUsd", "effectRecoveredUsd", "lookSpendUsd"];
|
|
96
|
+
/** The snapshot a driver runs under: the saved one (a paused run resumes running, retired keys
|
|
97
|
+
* dropped), or a fresh one. */
|
|
98
|
+
export function openedFrozenSnapshot(saved) {
|
|
99
|
+
const snapshot = saved ?? { schema: FROZEN_SNAPSHOT_SCHEMA, pin: emptyPathFrame(), startedAt: Date.now(), status: "running", clocks: {}, files: {} };
|
|
100
|
+
if (snapshot.status === "paused")
|
|
101
|
+
snapshot.status = "running";
|
|
102
|
+
for (const key of RETIRED_SNAPSHOT_KEYS)
|
|
103
|
+
delete snapshot[key];
|
|
104
|
+
return snapshot;
|
|
105
|
+
}
|
|
106
|
+
/** The snapshot as the journal stores it. Workflow state contains optional internal fields; this
|
|
107
|
+
* matches its JSON checkpoint semantics, while refusing non-finite values instead of silently
|
|
108
|
+
* changing them to null. */
|
|
109
|
+
export function serializeFrozenSnapshot(snapshot) {
|
|
110
|
+
return JSON.parse(JSON.stringify(snapshot, (_key, value) => {
|
|
111
|
+
if (typeof value === "number" && !Number.isFinite(value))
|
|
112
|
+
throw failure("FROZEN_CHECKPOINT_INVALID", "Non-finite workflow state");
|
|
113
|
+
return value;
|
|
114
|
+
}));
|
|
115
|
+
}
|
|
116
|
+
/** The session an LLM step's attempt runs in: the step's label (for the reader: labels repeat across
|
|
117
|
+
* loop iterations and map items), its frame and execution path (what makes it unique), and the
|
|
118
|
+
* attempt. */
|
|
119
|
+
export function frozenStepSessionId(driver, label, frame, path, attempt) {
|
|
120
|
+
return `${driver}:${label}:${frame}:${path}:a${attempt}`;
|
|
121
|
+
}
|
|
122
|
+
/** A step's short identity where a name must be short and file-safe (its files, the continuation an
|
|
123
|
+
* escalation hands off to): a digest of its frame and execution path, so it is the same in every process. */
|
|
124
|
+
export function frozenStepId(frame, path) {
|
|
125
|
+
return createHash("sha256").update(`${frame}:${path}`).digest("hex").slice(0, 10);
|
|
126
|
+
}
|
|
127
|
+
/** The receipt id of a call's `ordinal`th effect at an execution path. */
|
|
128
|
+
export function frozenEffectId(frame, path, ordinal) {
|
|
129
|
+
return `${frame}:${path}#call:${ordinal}`;
|
|
130
|
+
}
|
|
131
|
+
/** The execution path and ordinal an effect id names: the inverse of `frozenEffectId`. */
|
|
132
|
+
export function frozenEffectPath(id) {
|
|
133
|
+
const match = /^[^:]+:(.*)#call:(\d+)$/s.exec(id);
|
|
134
|
+
return match ? { path: match[1], ordinal: Number(match[2]) } : undefined;
|
|
135
|
+
}
|
|
136
|
+
/** An LLM step's execution record under admission. The first call fixes the label the interpreter
|
|
137
|
+
* names the step by and the retry limit; a later call gets the same
|
|
138
|
+
* record. A closed attempt advances to the next attempt here, and only here, when an admission asks
|
|
139
|
+
* and an attempt remains, else the step fails. `changed` says the snapshot owes a save. */
|
|
140
|
+
export function admitFrozenStep(steps, path, label, admission) {
|
|
141
|
+
let step = steps[path];
|
|
142
|
+
if (!step) {
|
|
143
|
+
if (!admission)
|
|
144
|
+
throw failure("FROZEN_PATH_INVALID", `The step at ${path} is admitted with its retry limit`);
|
|
145
|
+
step = { label, attempt: 0, attemptsAllowed: Math.max(1, admission.attemptsAllowed), status: "running" };
|
|
146
|
+
steps[path] = step;
|
|
147
|
+
return { step, changed: true };
|
|
148
|
+
}
|
|
149
|
+
if (step.status === "closed" && admission) {
|
|
150
|
+
if (step.attempt + 1 >= step.attemptsAllowed)
|
|
151
|
+
step.status = "failed";
|
|
152
|
+
else {
|
|
153
|
+
step.attempt += 1;
|
|
154
|
+
step.status = "running";
|
|
155
|
+
}
|
|
156
|
+
return { step, changed: true };
|
|
157
|
+
}
|
|
158
|
+
return { step, changed: false };
|
|
159
|
+
}
|
|
160
|
+
/** The current attempt ended without a submission: `closed` until a retry is admitted, or
|
|
161
|
+
* `failed` when the failure is final or no attempt remains. */
|
|
162
|
+
export function closeFrozenStepAttempt(step, final, failure) {
|
|
163
|
+
step.status = final || step.attempt + 1 >= step.attemptsAllowed ? "failed" : "closed";
|
|
164
|
+
if (step.status === "failed" && failure)
|
|
165
|
+
step.failure = { code: failure.code, message: failure.message };
|
|
166
|
+
}
|
|
167
|
+
/** The run-wide stop the driver applies: the host's pause or cancel it was handed, or null when it keeps
|
|
168
|
+
* running. A cancelled snapshot stays cancelled. */
|
|
169
|
+
export function frozenStop(status, requested) {
|
|
170
|
+
return status === "cancelled" || requested === "cancel" ? "cancelled" : requested === "pause" ? "paused" : null;
|
|
171
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { type InputProvenance } from "./handoff-files.js";
|
|
2
|
+
/** What the block says of the escalation. */
|
|
3
|
+
export type HandoffBlockInput = {
|
|
4
|
+
kind: string;
|
|
5
|
+
stage: string;
|
|
6
|
+
summary: string;
|
|
7
|
+
step_label?: string | null;
|
|
8
|
+
step_exec_id?: string | null;
|
|
9
|
+
state?: Record<string, unknown> | null;
|
|
10
|
+
workflow_sha_used?: string | null;
|
|
11
|
+
cost_usd?: number | null;
|
|
12
|
+
evidence_dir?: string | null;
|
|
13
|
+
/** Where the attempt's report.md was moved, when one existed. */
|
|
14
|
+
report_path?: string | null;
|
|
15
|
+
/** Workspace-relative paths the attempt's files were written to. */
|
|
16
|
+
files?: readonly string[] | null;
|
|
17
|
+
/** Where each input the attempt started from came from, and its form. */
|
|
18
|
+
inputs?: readonly InputProvenance[] | null;
|
|
19
|
+
/** The host's sizes for the continuation, stated as one line. */
|
|
20
|
+
budget?: {
|
|
21
|
+
max_tool_calls?: number;
|
|
22
|
+
max_seconds?: number;
|
|
23
|
+
} | null;
|
|
24
|
+
};
|
|
25
|
+
/** The state at the gate is rendered whole up to this size; beyond it the block points at state.json. */
|
|
26
|
+
export declare const STATE_LIMIT: number;
|
|
27
|
+
/** Strings above the limit become a prefix plus a marker with the omitted length; nested values recurse. */
|
|
28
|
+
export declare function boundedValue(value: unknown, limit?: number): unknown;
|
|
29
|
+
/** One line per completed output in the state: the key the workflow wrote and the shape it holds. */
|
|
30
|
+
export declare function stateShapes(state: Record<string, unknown> | null | undefined): string[];
|
|
31
|
+
/** The one line that states the host's sizes for the continuation, or "" when the host sent none. */
|
|
32
|
+
export declare function escalationBudgetLine(budget: HandoffBlockInput["budget"]): string;
|
|
33
|
+
/** The block the continuation reads first. Deterministic for a given row; policy-agnostic. The reason is the
|
|
34
|
+
* workflow's own text, whole; the state at the gate is whole up to STATE_LIMIT, and beyond it the
|
|
35
|
+
* block points at the file that holds it. */
|
|
36
|
+
export declare function escalationContextBlock(context: HandoffBlockInput): string;
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
import path from "node:path";
|
|
2
|
+
import { redactSensitiveValue, redactText } from "./handoff-redact.js";
|
|
3
|
+
import { HANDOFF_FILES_DIR } from "./handoff-files.js";
|
|
4
|
+
const VALUE_LIMIT = 400;
|
|
5
|
+
const ARRAY_LIMIT = 20;
|
|
6
|
+
/** The state at the gate is rendered whole up to this size; beyond it the block points at state.json. */
|
|
7
|
+
export const STATE_LIMIT = 48 * 1024;
|
|
8
|
+
/** The Files section lists this many paths, then counts the rest by directory. */
|
|
9
|
+
const FILES_LIST_LIMIT = 200;
|
|
10
|
+
const SHAPES_LIMIT = 3 * 1024;
|
|
11
|
+
const SHAPE_LINE_LIMIT = 160;
|
|
12
|
+
/** Strings above the limit become a prefix plus a marker with the omitted length; nested values recurse. */
|
|
13
|
+
export function boundedValue(value, limit = VALUE_LIMIT) {
|
|
14
|
+
if (typeof value === "string")
|
|
15
|
+
return value.length > limit ? `${value.slice(0, limit)}<${value.length - limit} more chars>` : value;
|
|
16
|
+
if (Array.isArray(value)) {
|
|
17
|
+
const head = value.slice(0, ARRAY_LIMIT).map(v => boundedValue(v, limit));
|
|
18
|
+
return value.length > ARRAY_LIMIT ? [...head, `<${value.length - ARRAY_LIMIT} more items>`] : head;
|
|
19
|
+
}
|
|
20
|
+
if (value && typeof value === "object")
|
|
21
|
+
return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, boundedValue(v, limit)]));
|
|
22
|
+
return value;
|
|
23
|
+
}
|
|
24
|
+
/** One line per completed output in the state: the key the workflow wrote and the shape it holds. */
|
|
25
|
+
export function stateShapes(state) {
|
|
26
|
+
if (!state || typeof state !== "object")
|
|
27
|
+
return [];
|
|
28
|
+
return Object.entries(state).map(([key, value]) => {
|
|
29
|
+
let line;
|
|
30
|
+
if (value === null || value === undefined)
|
|
31
|
+
line = `- ${key}: empty`;
|
|
32
|
+
else if (Array.isArray(value))
|
|
33
|
+
line = `- ${key}: array of ${value.length}`;
|
|
34
|
+
else if (typeof value === "object") {
|
|
35
|
+
const keys = Object.keys(value);
|
|
36
|
+
line = `- ${key}: object {${keys.slice(0, 12).join(", ")}${keys.length > 12 ? ", …" : ""}}`;
|
|
37
|
+
}
|
|
38
|
+
else if (typeof value === "string")
|
|
39
|
+
line = `- ${key}: string (${value.length} chars)`;
|
|
40
|
+
else
|
|
41
|
+
line = `- ${key}: ${typeof value}`;
|
|
42
|
+
return line.length > SHAPE_LINE_LIMIT ? `${line.slice(0, SHAPE_LINE_LIMIT)}…` : line;
|
|
43
|
+
});
|
|
44
|
+
}
|
|
45
|
+
/** The shapes section under its own budget: whole lines until the budget is spent, then a count. */
|
|
46
|
+
function shapesSection(shapes, budget) {
|
|
47
|
+
if (!shapes.length)
|
|
48
|
+
return ["- none"];
|
|
49
|
+
const kept = [];
|
|
50
|
+
let used = 0;
|
|
51
|
+
for (const line of shapes) {
|
|
52
|
+
if (used + line.length + 1 > budget)
|
|
53
|
+
break;
|
|
54
|
+
kept.push(line);
|
|
55
|
+
used += line.length + 1;
|
|
56
|
+
}
|
|
57
|
+
if (kept.length < shapes.length)
|
|
58
|
+
kept.push(`- …and ${shapes.length - kept.length} more keys (${shapes.length} in total)`);
|
|
59
|
+
return kept;
|
|
60
|
+
}
|
|
61
|
+
/** The block lists this many inputs, then counts the rest; inputs.json lists every one. */
|
|
62
|
+
const INPUT_LINE_LIMIT = 100;
|
|
63
|
+
const INPUT_VALUE_LIMIT = 200;
|
|
64
|
+
/** The inputs section: one line per input, its path, its form and its value (a long value by size). */
|
|
65
|
+
function inputsSection(inputs, filed) {
|
|
66
|
+
if (!inputs?.length)
|
|
67
|
+
return [];
|
|
68
|
+
const label = (form) => form === "email" ? "identifier (email address)" : form === "url" ? "identifier (URL)" : form === "text" ? "typed text" : form;
|
|
69
|
+
return ["", `Inputs the run started from, as the dispatch carried them (path: form: value)${filed ? `; whole in \`${HANDOFF_FILES_DIR}/inputs.json\`` : ""}. An identifier is a value of a fixed form a source can be matched on; typed text is what was written in:`,
|
|
70
|
+
...inputs.slice(0, INPUT_LINE_LIMIT).map((input) => `- ${input.path}: ${label(input.form)}: ${input.value.length > INPUT_VALUE_LIMIT ? `(${input.value.length} chars)` : input.value.replace(/\s+/g, " ")}`),
|
|
71
|
+
...(inputs.length > INPUT_LINE_LIMIT ? [`- …${inputs.length - INPUT_LINE_LIMIT} more inputs (${inputs.length} in total)${filed ? `, each with its path and form in \`${HANDOFF_FILES_DIR}/inputs.json\`` : ""}`] : [])];
|
|
72
|
+
}
|
|
73
|
+
/** The one line that states the host's sizes for the continuation, or "" when the host sent none. */
|
|
74
|
+
export function escalationBudgetLine(budget) {
|
|
75
|
+
if (!budget)
|
|
76
|
+
return "";
|
|
77
|
+
const sizes = [
|
|
78
|
+
...(budget.max_tool_calls !== undefined ? [`${budget.max_tool_calls} external tool calls`] : []),
|
|
79
|
+
...(budget.max_seconds !== undefined ? [`${budget.max_seconds} seconds`] : []),
|
|
80
|
+
];
|
|
81
|
+
return sizes.length ? `Budget for this continuation (set by the host): ${sizes.join(" and ")}.` : "";
|
|
82
|
+
}
|
|
83
|
+
/** The Files section: every path the attempt left for the continuation. */
|
|
84
|
+
function filesSection(context) {
|
|
85
|
+
const frozen = [...(context.files ?? [])];
|
|
86
|
+
const lines = [];
|
|
87
|
+
const described = {
|
|
88
|
+
[`${HANDOFF_FILES_DIR}/state.json`]: "the workflow state at the gate, whole",
|
|
89
|
+
[`${HANDOFF_FILES_DIR}/gate.json`]: "the gate: kind, stage, step, reason, its state and every committed route decision",
|
|
90
|
+
[`${HANDOFF_FILES_DIR}/inputs.json`]: "the inputs the frozen attempt started from, with each one's path and form",
|
|
91
|
+
};
|
|
92
|
+
const shown = frozen.slice(0, FILES_LIST_LIMIT);
|
|
93
|
+
for (const file of shown)
|
|
94
|
+
lines.push(`- ${file}${described[file] ? `: ${described[file]}` : ""}`);
|
|
95
|
+
if (frozen.length > shown.length) {
|
|
96
|
+
const rest = new Map();
|
|
97
|
+
for (const file of frozen.slice(shown.length)) {
|
|
98
|
+
const dir = path.posix.dirname(file);
|
|
99
|
+
rest.set(dir, (rest.get(dir) ?? 0) + 1);
|
|
100
|
+
}
|
|
101
|
+
for (const [dir, count] of rest)
|
|
102
|
+
lines.push(`- …${count} more under ${dir}/`);
|
|
103
|
+
}
|
|
104
|
+
if (!lines.length)
|
|
105
|
+
return [];
|
|
106
|
+
const items = frozen.some((file) => file.startsWith(`${HANDOFF_FILES_DIR}/items/`));
|
|
107
|
+
const effects = frozen.some((file) => file.startsWith(`${HANDOFF_FILES_DIR}/effects/`));
|
|
108
|
+
return ["", "Files the frozen attempt left in the workspace (read them; they are whole where this text is not):",
|
|
109
|
+
...(items ? [`Each file under ${HANDOFF_FILES_DIR}/items/ is one record the workflow judged, with its text and its scores.`] : []),
|
|
110
|
+
...(effects ? [`Each file under ${HANDOFF_FILES_DIR}/effects/ is one paid call: its arguments and its full result.`] : []),
|
|
111
|
+
...lines];
|
|
112
|
+
}
|
|
113
|
+
/** The block the continuation reads first. Deterministic for a given row; policy-agnostic. The reason is the
|
|
114
|
+
* workflow's own text, whole; the state at the gate is whole up to STATE_LIMIT, and beyond it the
|
|
115
|
+
* block points at the file that holds it. */
|
|
116
|
+
export function escalationContextBlock(context) {
|
|
117
|
+
const step = context.step_label ?? context.stage;
|
|
118
|
+
const summary = redactText(String(context.summary || "").trim()) || "(no summary recorded)";
|
|
119
|
+
const budget = escalationBudgetLine(context.budget);
|
|
120
|
+
const header = [
|
|
121
|
+
"## YOU ARE CONTINUING A RUN THAT ESCALATED",
|
|
122
|
+
"",
|
|
123
|
+
`A reviewed workflow${context.workflow_sha_used ? ` (${String(context.workflow_sha_used).slice(0, 12)})` : ""} ran first and stopped at step \`${step}\`${context.step_exec_id ? ` (execution ${context.step_exec_id})` : ""}: ${context.kind}${context.stage && context.stage !== step ? ` at stage ${context.stage}` : ""}.`,
|
|
124
|
+
"",
|
|
125
|
+
"Why it stopped:",
|
|
126
|
+
summary,
|
|
127
|
+
...(budget ? ["", budget] : []),
|
|
128
|
+
"",
|
|
129
|
+
];
|
|
130
|
+
const footer = [
|
|
131
|
+
"",
|
|
132
|
+
...(context.evidence_dir ? [`Evidence gathered so far is under \`${context.evidence_dir}\`.`] : []),
|
|
133
|
+
...(context.report_path ? [`The frozen attempt's report was moved to \`${context.report_path}\`.`] : []),
|
|
134
|
+
...(typeof context.cost_usd === "number"
|
|
135
|
+
? [`The frozen attempt spent $${context.cost_usd.toFixed(4)}.`]
|
|
136
|
+
: []),
|
|
137
|
+
"",
|
|
138
|
+
"Continue the job from this state. Do not redo completed work; build on it. When you explain what happened, cite this escalation (its step and reason) rather than inventing a cause.",
|
|
139
|
+
];
|
|
140
|
+
const shapes = shapesSection(stateShapes(context.state), SHAPES_LIMIT);
|
|
141
|
+
const stateFile = (context.files ?? []).includes(`${HANDOFF_FILES_DIR}/state.json`) ? `${HANDOFF_FILES_DIR}/state.json` : null;
|
|
142
|
+
const stateJson = JSON.stringify(redactSensitiveValue(context.state ?? {}), null, 2);
|
|
143
|
+
const state = stateJson.length <= STATE_LIMIT
|
|
144
|
+
? ["", `State at the gate (whole${stateFile ? `; also in \`${stateFile}\`` : ""}):`, "```json", stateJson, "```"]
|
|
145
|
+
: ["", `State body is ${stateJson.length} chars (${Object.keys(context.state ?? {}).length} keys), beyond what this text carries; ${stateFile ? `read it whole in \`${stateFile}\`` : "the list above names every key with its type and size"}.`];
|
|
146
|
+
const filedInputs = (context.files ?? []).includes(`${HANDOFF_FILES_DIR}/inputs.json`);
|
|
147
|
+
return redactText([...header, "Completed outputs it left in the workflow state (do not redo this work):", ...shapes, ...state, ...inputsSection(context.inputs, filedInputs), ...filesSection(context), ...footer].join("\n"));
|
|
148
|
+
}
|