@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.
Files changed (102) hide show
  1. package/README.md +107 -17
  2. package/dist/author.d.ts +96 -0
  3. package/dist/author.js +320 -0
  4. package/dist/authoring.js +1 -1
  5. package/dist/cli.js +8 -3
  6. package/dist/code-exec.d.ts +6 -0
  7. package/dist/code-exec.js +126 -0
  8. package/dist/decision-receipts.d.ts +98 -0
  9. package/dist/decision-receipts.js +51 -0
  10. package/dist/dry-run.d.ts +14 -1
  11. package/dist/dry-run.js +39 -13
  12. package/dist/graph.d.ts +83 -0
  13. package/dist/graph.js +231 -0
  14. package/dist/index.d.ts +12 -4
  15. package/dist/index.js +6 -2
  16. package/dist/inspection.js +2 -2
  17. package/dist/job.d.ts +14 -0
  18. package/dist/job.js +5 -0
  19. package/dist/long-timer.d.ts +7 -0
  20. package/dist/long-timer.js +22 -0
  21. package/dist/observer-snapshot.d.ts +3 -0
  22. package/dist/observer-snapshot.js +46 -0
  23. package/dist/predicates.d.ts +4 -0
  24. package/dist/predicates.js +19 -2
  25. package/dist/recovery/binding.d.ts +10 -0
  26. package/dist/recovery/binding.js +43 -0
  27. package/dist/recovery/call-key.d.ts +13 -0
  28. package/dist/recovery/call-key.js +24 -0
  29. package/dist/recovery/canonical-hash.d.ts +7 -0
  30. package/dist/recovery/canonical-hash.js +22 -0
  31. package/dist/recovery/driver.d.ts +208 -0
  32. package/dist/recovery/driver.js +1222 -0
  33. package/dist/recovery/effect-failure.d.ts +34 -0
  34. package/dist/recovery/effect-failure.js +62 -0
  35. package/dist/recovery/errors.d.ts +31 -0
  36. package/dist/recovery/errors.js +51 -0
  37. package/dist/recovery/execution-path.d.ts +53 -0
  38. package/dist/recovery/execution-path.js +167 -0
  39. package/dist/recovery/file-store.d.ts +7 -0
  40. package/dist/recovery/file-store.js +131 -0
  41. package/dist/recovery/frozen-snapshot.d.ts +244 -0
  42. package/dist/recovery/frozen-snapshot.js +171 -0
  43. package/dist/recovery/handoff-block.d.ts +36 -0
  44. package/dist/recovery/handoff-block.js +148 -0
  45. package/dist/recovery/handoff-digest.d.ts +58 -0
  46. package/dist/recovery/handoff-digest.js +195 -0
  47. package/dist/recovery/handoff-files.d.ts +54 -0
  48. package/dist/recovery/handoff-files.js +162 -0
  49. package/dist/recovery/handoff-receipts.d.ts +42 -0
  50. package/dist/recovery/handoff-receipts.js +53 -0
  51. package/dist/recovery/handoff-redact.d.ts +12 -0
  52. package/dist/recovery/handoff-redact.js +44 -0
  53. package/dist/recovery/handoff.d.ts +44 -0
  54. package/dist/recovery/handoff.js +46 -0
  55. package/dist/recovery/index.d.ts +18 -0
  56. package/dist/recovery/index.js +16 -0
  57. package/dist/recovery/item-state.d.ts +48 -0
  58. package/dist/recovery/item-state.js +89 -0
  59. package/dist/recovery/journal.d.ts +28 -0
  60. package/dist/recovery/journal.js +139 -0
  61. package/dist/recovery/memory-store.d.ts +4 -0
  62. package/dist/recovery/memory-store.js +20 -0
  63. package/dist/recovery/store.d.ts +105 -0
  64. package/dist/recovery/store.js +6 -0
  65. package/dist/recovery/testing/conformance.d.ts +4 -0
  66. package/dist/recovery/testing/conformance.js +268 -0
  67. package/dist/recovery/testing/crash-points.d.ts +18 -0
  68. package/dist/recovery/testing/crash-points.js +43 -0
  69. package/dist/recovery/testing/crash-sweep.d.ts +65 -0
  70. package/dist/recovery/testing/crash-sweep.js +146 -0
  71. package/dist/recovery/testing/index.d.ts +3 -0
  72. package/dist/recovery/testing/index.js +4 -0
  73. package/dist/recovery/testing/preload.d.ts +1 -0
  74. package/dist/recovery/testing/preload.js +3 -0
  75. package/dist/recovery/transport-facts.d.ts +23 -0
  76. package/dist/recovery/transport-facts.js +46 -0
  77. package/dist/recovery/with-recovery.d.ts +44 -0
  78. package/dist/recovery/with-recovery.js +87 -0
  79. package/dist/system-one.d.ts +17 -1
  80. package/dist/system-one.js +62 -5
  81. package/dist/vocabulary.d.ts +42 -0
  82. package/dist/vocabulary.js +74 -0
  83. package/dist/workflow-shape.d.ts +7 -0
  84. package/dist/workflow-shape.js +85 -62
  85. package/dist/workflow.d.ts +187 -16
  86. package/dist/workflow.js +1007 -332
  87. package/package.json +18 -2
  88. package/schema/workflow.schema.json +251 -15
  89. package/skills/author/SKILL.md +122 -0
  90. package/skills/author/examples/evidence-gate.input.json +6 -0
  91. package/skills/author/examples/evidence-gate.json +125 -0
  92. package/skills/author/examples/read-file.input.json +1 -0
  93. package/skills/author/examples/read-file.json +44 -0
  94. package/skills/author/examples/read-source-decision.input.json +4 -0
  95. package/skills/author/examples/read-source-decision.json +37 -0
  96. package/skills/author/examples/release-note.txt +10 -0
  97. package/skills/author/examples/review-release-notes.input.json +6 -0
  98. package/skills/author/examples/review-release-notes.json +123 -0
  99. package/skills/author/references/jev-decisions.md +125 -0
  100. package/skills/author/references/language.md +118 -0
  101. package/skills/author/references/sdk-authoring.md +11 -0
  102. package/skills/author/references/workflow-format.md +137 -0
@@ -0,0 +1,58 @@
1
+ /** One step's transcript message, as a host's reader returns it. */
2
+ export type TranscriptMessage = {
3
+ role: "user" | "assistant" | "toolResult";
4
+ content?: unknown;
5
+ toolCallId?: string;
6
+ toolName?: string;
7
+ isError?: boolean;
8
+ stopReason?: string;
9
+ };
10
+ export declare const DIGEST_STEP_LIMIT: number;
11
+ export declare const DIGEST_LIMIT: number;
12
+ /** A step's spend: `usd` is a floor when `state` is `partial` and unknown when null; a spend recorded without a state
13
+ * (a recorded trace's `session.spent` row) is complete. */
14
+ export type InheritedSession = {
15
+ id: string;
16
+ role: string;
17
+ state: string;
18
+ file: string | null;
19
+ spend?: {
20
+ usd: number | null;
21
+ turns: number;
22
+ state?: "complete" | "partial" | "unavailable";
23
+ toolCalls?: number;
24
+ };
25
+ };
26
+ export type InheritedEffect = {
27
+ id: string;
28
+ name: string;
29
+ status: string;
30
+ session?: string | null;
31
+ result?: unknown;
32
+ };
33
+ export type InheritedJob = {
34
+ runId: string;
35
+ /** A step's transcript by its session id (the run's durable file holds them), or null when there is none. */
36
+ transcriptOf: (sessionId: string) => readonly TranscriptMessage[] | null;
37
+ cwd: string;
38
+ evidenceDir?: string | null;
39
+ sessions: InheritedSession[];
40
+ effects: InheritedEffect[];
41
+ /** Workspace-relative produced files with the sha256 the driver committed for them. */
42
+ files: Record<string, string>;
43
+ /** The file writeFrozenEvidence wrote each effect's whole receipt to, by effect id. */
44
+ effectFiles?: Record<string, string>;
45
+ };
46
+ /** The label a step's identity carries, distinct for every session the frozen driver admits. A step's
47
+ * session is `<run>:<label>:<step|adapt>:<execution path>:a<attempt>` (the label as the
48
+ * interpreter names the node: a child's step `invocation/step`, a plan's `adapt:<gate>/step`, and a
49
+ * label may hold colons), read as the label with each map item index its path runs under as `[k]` and
50
+ * each loop iteration as `#k`. */
51
+ export declare function stepLabelOf(runId: string, sessionId: string): string | null;
52
+ /** One completed LLM step, from its transcript (`transcriptOf`): what it was asked, what it called, what it concluded and
53
+ * what it submitted. Bounded per step; a step whose transcript is absent or unreadable says so. */
54
+ export declare function stepDigest(runId: string, session: InheritedSession, transcriptOf: (sessionId: string) => readonly TranscriptMessage[] | null): string;
55
+ /** The digest the continuation reads after the escalation block: the completed
56
+ * LLM steps' transcripts, the evidence gathered, the files produced with their receipts, and the
57
+ * one rule that this is a continuation. Deterministic for a given ledger and workspace. */
58
+ export declare function inheritedJobDigest(job: InheritedJob): string;
@@ -0,0 +1,195 @@
1
+ import fs from "node:fs";
2
+ import path from "node:path";
3
+ import { redactSensitiveValue, redactText } from "./handoff-redact.js";
4
+ import { HANDOFF_FILES_DIR } from "./handoff-files.js";
5
+ import { boundedValue } from "./handoff-block.js";
6
+ export const DIGEST_STEP_LIMIT = 3 * 1024;
7
+ export const DIGEST_LIMIT = 24 * 1024;
8
+ const DIGEST_ARGS_LIMIT = 240;
9
+ const DIGEST_RESULT_LIMIT = 160;
10
+ const DIGEST_TEXT_LIMIT = 600;
11
+ const DIGEST_LIST_LIMIT = 40;
12
+ const spendText = (spend) => spend.usd === null ? "cost unknown" : spend.state === "partial" ? `at least $${spend.usd.toFixed(4)}, some cost unknown` : `$${spend.usd.toFixed(4)}`;
13
+ /** The label a step's identity carries, distinct for every session the frozen driver admits. A step's
14
+ * session is `<run>:<label>:<step|adapt>:<execution path>:a<attempt>` (the label as the
15
+ * interpreter names the node: a child's step `invocation/step`, a plan's `adapt:<gate>/step`, and a
16
+ * label may hold colons), read as the label with each map item index its path runs under as `[k]` and
17
+ * each loop iteration as `#k`. */
18
+ export function stepLabelOf(runId, sessionId) {
19
+ if (!sessionId.startsWith(`${runId}:`))
20
+ return null;
21
+ const match = /^(.+):(?:step|adapt):(\/root(?:\/.*)?):a\d+$/.exec(sessionId.slice(runId.length + 1));
22
+ if (!match)
23
+ return null;
24
+ const [, label, at] = match;
25
+ const marks = [...at.matchAll(/\/(items|iterations)\/(\d+)\/body(?=\/|$)/g)].map(([, kind, index]) => kind === "items" ? `[${index}]` : `#${index}`);
26
+ return `${label}${marks.join("")}`;
27
+ }
28
+ const oneLine = (value, limit) => {
29
+ const safe = redactSensitiveValue(value);
30
+ const text = typeof safe === "string" ? safe : JSON.stringify(safe);
31
+ const flat = String(text ?? "").replace(/\s+/g, " ").trim();
32
+ return flat.length > limit ? `${flat.slice(0, limit)}<${flat.length - limit} more chars>` : flat;
33
+ };
34
+ const textOf = (content) => Array.isArray(content)
35
+ ? content.filter((c) => c?.type === "text" && typeof c.text === "string").map((c) => c.text).join("\n")
36
+ : typeof content === "string" ? content : "";
37
+ /** One completed LLM step, from its transcript (`transcriptOf`): what it was asked, what it called, what it concluded and
38
+ * what it submitted. Bounded per step; a step whose transcript is absent or unreadable says so. */
39
+ export function stepDigest(runId, session, transcriptOf) {
40
+ const label = stepLabelOf(runId, session.id) ?? session.id;
41
+ const head = `### Step \`${label}\` (${session.state}${session.spend ? `, ${session.spend.turns} turn${session.spend.turns === 1 ? "" : "s"}, ${spendText(session.spend)}` : ""})`;
42
+ let messages;
43
+ try {
44
+ messages = transcriptOf(session.id);
45
+ }
46
+ catch {
47
+ return `${head}\n- transcript unreadable`;
48
+ }
49
+ if (!messages)
50
+ return `${head}\n- transcript unavailable`;
51
+ const lines = [head];
52
+ const firstUser = messages.find(m => m.role === "user");
53
+ if (firstUser)
54
+ lines.push(`- asked: ${oneLine(textOf(firstUser.content), DIGEST_TEXT_LIMIT)}`);
55
+ const results = new Map();
56
+ for (const m of messages)
57
+ if (m.role === "toolResult" && m.toolCallId)
58
+ results.set(m.toolCallId, m);
59
+ let submission;
60
+ let lastText = "";
61
+ const calls = [];
62
+ for (const m of messages) {
63
+ if (m.role !== "assistant" || !Array.isArray(m.content))
64
+ continue;
65
+ for (const block of m.content) {
66
+ if (block?.type === "toolCall") {
67
+ if (block.name === "submit") {
68
+ submission = block.arguments;
69
+ continue;
70
+ }
71
+ const result = results.get(block.id);
72
+ const outcome = result ? (result.isError ? "error" : "ok") + (textOf(result.content) ? `: ${oneLine(textOf(result.content), DIGEST_RESULT_LIMIT)}` : "") : "no result";
73
+ calls.push(`- called ${block.name}(${oneLine(block.arguments ?? {}, DIGEST_ARGS_LIMIT)}) → ${outcome}`);
74
+ }
75
+ else if (block?.type === "text" && typeof block.text === "string" && block.text.trim())
76
+ lastText = block.text;
77
+ }
78
+ }
79
+ const callLines = calls.length > DIGEST_LIST_LIMIT ? [...calls.slice(0, DIGEST_LIST_LIMIT), `- …${calls.length - DIGEST_LIST_LIMIT} more calls`] : calls;
80
+ lines.push(...callLines);
81
+ // Only what the step said and did crosses the boundary; its private reasoning never does.
82
+ if (lastText)
83
+ lines.push(`- concluded: ${oneLine(lastText, DIGEST_TEXT_LIMIT)}`);
84
+ else
85
+ lines.push("- ended without a text conclusion");
86
+ if (submission !== undefined)
87
+ lines.push(`- submitted: ${oneLine(boundedValue(submission), DIGEST_TEXT_LIMIT * 2)}`);
88
+ // The step's own budget: whole lines, then a count. The head is never dropped.
89
+ const kept = [lines[0]];
90
+ let used = lines[0].length;
91
+ for (const line of lines.slice(1)) {
92
+ if (used + line.length + 1 > DIGEST_STEP_LIMIT) {
93
+ kept.push(`- …${lines.length - kept.length} more lines omitted`);
94
+ break;
95
+ }
96
+ kept.push(line);
97
+ used += line.length + 1;
98
+ }
99
+ return redactText(kept.join("\n"));
100
+ }
101
+ const listDir = (dir, limit, skip = new Set()) => {
102
+ if (!dir || !fs.existsSync(dir))
103
+ return [];
104
+ const out = [];
105
+ const walk = (current, prefix) => {
106
+ let entries = [];
107
+ try {
108
+ entries = fs.readdirSync(current, { withFileTypes: true });
109
+ }
110
+ catch {
111
+ return;
112
+ }
113
+ for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
114
+ if (out.length >= limit)
115
+ return;
116
+ const full = path.join(current, entry.name);
117
+ if (skip.has(`${prefix}${entry.name}`))
118
+ continue;
119
+ if (entry.isDirectory())
120
+ walk(full, `${prefix}${entry.name}/`);
121
+ else {
122
+ let size = 0;
123
+ try {
124
+ size = fs.statSync(full).size;
125
+ }
126
+ catch { /* listed without size */ }
127
+ out.push(`- ${redactText(`${prefix}${entry.name}`)} (${size} bytes)`);
128
+ }
129
+ }
130
+ };
131
+ walk(dir, "");
132
+ return out;
133
+ };
134
+ /** The digest the continuation reads after the escalation block: the completed
135
+ * LLM steps' transcripts, the evidence gathered, the files produced with their receipts, and the
136
+ * one rule that this is a continuation. Deterministic for a given ledger and workspace. */
137
+ export function inheritedJobDigest(job) {
138
+ const steps = job.sessions
139
+ .filter(s => s.role === "step" && stepLabelOf(job.runId, s.id))
140
+ .map(s => stepDigest(job.runId, s, job.transcriptOf));
141
+ // The frozen attempt's own files are listed by the escalation block; this lists what the steps gathered.
142
+ const evidence = job.evidenceDir ? listDir(job.evidenceDir, DIGEST_LIST_LIMIT, new Set([path.posix.basename(HANDOFF_FILES_DIR)])) : [];
143
+ const effectsBy = new Map(job.effects.filter(e => e.status === "completed").map(e => [e.id, e]));
144
+ const fileEntries = Object.entries(job.files).sort(([a], [b]) => a.localeCompare(b));
145
+ const files = fileEntries.slice(0, DIGEST_LIST_LIMIT).map(([file, sha]) => {
146
+ let size = null;
147
+ try {
148
+ size = fs.statSync(path.join(job.cwd, file)).size;
149
+ }
150
+ catch { /* the receipt still names it */ }
151
+ return `- ${redactText(file)}${size === null ? " (missing on disk)" : ` (${size} bytes)`} sha256 ${sha.slice(0, 12)}`;
152
+ });
153
+ if (fileEntries.length > DIGEST_LIST_LIMIT)
154
+ files.push(`- …${fileEntries.length - DIGEST_LIST_LIMIT} more`);
155
+ const paid = [...effectsBy.values()].filter(e => e.name !== "submit" && !["read", "write", "edit", "grep", "find", "bash"].includes(e.name));
156
+ const header = ["## THE JOB AS IT STANDS (inherited from the frozen attempt)", ""];
157
+ const footer = ["", "You are continuing this job, not restarting it. Everything listed above is done and paid for: use it, do not redo it, and cite it (step labels, file names) when you explain what you did."];
158
+ const effectLine = (e) => `- ${e.name} [${e.id}] completed${e.result === undefined ? "" : ` → ${oneLine(e.result, DIGEST_RESULT_LIMIT)}`}${job.effectFiles?.[e.id] ? ` (whole: ${job.effectFiles[e.id]})` : ""}`;
159
+ // Display order: steps, effects, files, evidence. Budget order: the cheap ledger facts first, the
160
+ // transcripts take what is left. A section that does not fit keeps its heading and as many whole
161
+ // lines as fit, then a count.
162
+ const sections = {
163
+ steps: ["### LLM steps run so far (their transcripts, bounded; a step that did not submit shows how it ended)", ...(steps.length ? steps : ["- none"])],
164
+ effects: [`### Paid effects already made (${paid.length})`,
165
+ ...(paid.length ? ["These tool calls already ran; their results are previewed below, whole in the file each line names, and in the state above. Calling the same tool again buys the same answer twice.", ...paid.slice(0, DIGEST_LIST_LIMIT).map(effectLine)] : ["- none"]),
166
+ ...(paid.length > DIGEST_LIST_LIMIT ? [`- …${paid.length - DIGEST_LIST_LIMIT} more`] : [])],
167
+ files: ["### Files produced in the workspace (with the driver's receipts)", ...(files.length ? files : ["- none"])],
168
+ evidence: [`### Evidence directory${job.evidenceDir ? ` (\`${job.evidenceDir}\`)` : ""}`, ...(evidence.length ? evidence : ["- empty"])],
169
+ };
170
+ let budget = DIGEST_LIMIT - [...header, ...footer].join("\n").length;
171
+ const rendered = {};
172
+ for (const name of ["effects", "files", "evidence", "steps"]) {
173
+ const section = sections[name];
174
+ const text = section.join("\n");
175
+ if (text.length + 2 <= budget) {
176
+ rendered[name] = text;
177
+ budget -= text.length + 2;
178
+ continue;
179
+ }
180
+ const kept = [section[0]];
181
+ let used = section[0].length;
182
+ for (const line of section.slice(1)) {
183
+ if (used + line.length + 1 > budget - 48)
184
+ break;
185
+ kept.push(line);
186
+ used += line.length + 1;
187
+ }
188
+ if (kept.length < section.length)
189
+ kept.push(`- …${section.length - kept.length} more entries omitted`);
190
+ rendered[name] = kept.join("\n");
191
+ budget -= rendered[name].length + 2;
192
+ }
193
+ const body = ["steps", "effects", "files", "evidence"].flatMap(name => [rendered[name], ""]);
194
+ return redactText([...header, ...body, ...footer].join("\n"));
195
+ }
@@ -0,0 +1,54 @@
1
+ /** Where the attempt's files live, relative to the workspace. */
2
+ export declare const HANDOFF_FILES_DIR = "evidence/frozen";
3
+ export declare const WALK_DEPTH = 8;
4
+ /** What the files record of the escalation. */
5
+ export type HandoffRow = {
6
+ kind: string;
7
+ stage: string;
8
+ summary: string;
9
+ step_label?: string | null;
10
+ state?: Record<string, unknown> | null;
11
+ };
12
+ /** The journal facts the files are written from. */
13
+ export type HandoffMemo = {
14
+ effects?: ReadonlyArray<{
15
+ id: string;
16
+ name: string;
17
+ status: string;
18
+ result?: unknown;
19
+ }>;
20
+ /** The committed route decisions (the judge's answer, whole), by execution path. */
21
+ routes?: Record<string, unknown> | null;
22
+ } | null | undefined;
23
+ /** One input as the dispatch carried it: its path in the run's input and the form of its value. `email` and `url` are
24
+ * values of a fixed form (an identifier a source can be matched on); `text` is anything else that was typed. Form only:
25
+ * which claim weighs more is the workflow's call. */
26
+ export type InputProvenance = {
27
+ path: string;
28
+ form: "email" | "url" | "text" | "number" | "boolean";
29
+ value: string;
30
+ };
31
+ /** Every scalar leaf of the run's input with its path and form, in input order. */
32
+ export declare function inputProvenance(input: unknown): InputProvenance[];
33
+ /** Every record in the state that carries an `id` and sits in an array: the records a workflow judges.
34
+ * Structural only: no field name but `id` is read. A record seen twice with the same bytes is one. */
35
+ export declare function judgedRecords(state: unknown): Array<Record<string, unknown> & {
36
+ id: string | number;
37
+ }>;
38
+ /** One judged record as Markdown: short scalars (its numbers, flags and labels) as a list, then each
39
+ * long text and nested value whole under its own heading. A text that is JSON is pretty-printed. */
40
+ export declare function renderJudgedRecord(record: Record<string, unknown>): string;
41
+ /** The workspace-relative file an effect's receipt is written to. */
42
+ export declare const handoffEffectFile: (effect: {
43
+ id: string;
44
+ name: string;
45
+ }) => string;
46
+ /** Write the attempt into `<cwd>/evidence/frozen/`: state.json (the state at the gate), gate.json
47
+ * (the gate and every committed route decision), inputs.json (what the attempt started from), one
48
+ * effects/<id>-<name>.json per completed effect (its arguments and its full result) and one
49
+ * items/<id>.md per judged record. The directory is replaced whole. Returns the paths written,
50
+ * workspace-relative, sorted, and the file each effect went to. */
51
+ export declare function writeHandoffFiles(cwd: string, row: HandoffRow, memo: HandoffMemo, input?: unknown): Promise<{
52
+ files: string[];
53
+ effectFiles: Record<string, string>;
54
+ }>;
@@ -0,0 +1,162 @@
1
+ import fs from "node:fs";
2
+ import path from "node:path";
3
+ import { isCredentialKey, redactSensitiveValue } from "./handoff-redact.js";
4
+ // The attempt as files: what the continuation reads instead of a bounded rendering. Written once, before the continuation
5
+ // starts, from the escalation row and the journal's effects alone, so a resumed continuation rewrites the same bytes.
6
+ // Every value is redacted (secret-named keys and credential patterns) before it is written.
7
+ /** Where the attempt's files live, relative to the workspace. */
8
+ export const HANDOFF_FILES_DIR = "evidence/frozen";
9
+ /** At most this many judged records become item files; the rest stay in state.json. */
10
+ const ITEM_FILE_LIMIT = 1000;
11
+ const ITEM_INLINE_LIMIT = 200;
12
+ export const WALK_DEPTH = 8;
13
+ const EMAIL_FORM = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/;
14
+ const URL_FORM = /^https?:\/\/\S+$/i;
15
+ /** Every scalar leaf of the run's input with its path and form, in input order. */
16
+ export function inputProvenance(input) {
17
+ const out = [];
18
+ const walk = (value, at, depth) => {
19
+ if (depth > WALK_DEPTH || value === null || value === undefined)
20
+ return;
21
+ if (Array.isArray(value)) {
22
+ value.forEach((item, i) => walk(item, `${at}[${i}]`, depth + 1));
23
+ return;
24
+ }
25
+ if (typeof value === "object") {
26
+ for (const [key, item] of Object.entries(value)) {
27
+ const here = at ? `${at}.${key}` : key;
28
+ // A credential-named field is one input whose value is never copied, whatever it holds.
29
+ if (isCredentialKey(key)) {
30
+ if (item !== null && item !== undefined)
31
+ out.push({ path: here, form: "text", value: "<redacted>" });
32
+ continue;
33
+ }
34
+ walk(item, here, depth + 1);
35
+ }
36
+ return;
37
+ }
38
+ if (typeof value === "number" || typeof value === "boolean") {
39
+ out.push({ path: at, form: typeof value, value: String(value) });
40
+ return;
41
+ }
42
+ const text = String(value).trim();
43
+ if (!text)
44
+ return;
45
+ out.push({ path: at, form: EMAIL_FORM.test(text) ? "email" : URL_FORM.test(text) ? "url" : "text", value: text });
46
+ };
47
+ walk(input, "", 0);
48
+ return out;
49
+ }
50
+ const safeName = (value) => String(value).replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^[._-]+/, "").slice(0, 96) || "_";
51
+ const isRecordWithId = (value) => !!value && typeof value === "object" && !Array.isArray(value) && (typeof value.id === "string" || typeof value.id === "number") && String(value.id).trim() !== "";
52
+ /** Every record in the state that carries an `id` and sits in an array: the records a workflow judges.
53
+ * Structural only: no field name but `id` is read. A record seen twice with the same bytes is one. */
54
+ export function judgedRecords(state) {
55
+ const found = new Map();
56
+ const order = [];
57
+ const walk = (value, depth) => {
58
+ if (depth > WALK_DEPTH || order.length >= ITEM_FILE_LIMIT)
59
+ return;
60
+ if (Array.isArray(value)) {
61
+ for (const item of value) {
62
+ if (isRecordWithId(item)) {
63
+ const key = `${item.id}\u0000${JSON.stringify(item)}`;
64
+ if (!found.has(key)) {
65
+ found.set(key, item);
66
+ order.push(item);
67
+ }
68
+ }
69
+ walk(item, depth + 1);
70
+ }
71
+ }
72
+ else if (value && typeof value === "object")
73
+ for (const item of Object.values(value))
74
+ walk(item, depth + 1);
75
+ };
76
+ walk(state, 0);
77
+ return order.slice(0, ITEM_FILE_LIMIT);
78
+ }
79
+ /** One judged record as Markdown: short scalars (its numbers, flags and labels) as a list, then each
80
+ * long text and nested value whole under its own heading. A text that is JSON is pretty-printed. */
81
+ export function renderJudgedRecord(record) {
82
+ const safe = redactSensitiveValue(record);
83
+ const lines = [`# ${String(safe.id)}`, ""];
84
+ const long = [];
85
+ for (const [key, value] of Object.entries(safe)) {
86
+ if (key === "id")
87
+ continue;
88
+ if (value === null || typeof value === "number" || typeof value === "boolean" || (typeof value === "string" && value.length <= ITEM_INLINE_LIMIT && !value.includes("\n"))) {
89
+ lines.push(`- ${key}: ${value === null ? "null" : String(value)}`);
90
+ }
91
+ else
92
+ long.push([key, value]);
93
+ }
94
+ for (const [key, value] of long) {
95
+ lines.push("", `## ${key}`, "");
96
+ if (typeof value === "string") {
97
+ let parsed;
98
+ const trimmed = value.trim();
99
+ if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
100
+ try {
101
+ parsed = JSON.parse(trimmed);
102
+ }
103
+ catch { /* plain text */ }
104
+ }
105
+ lines.push(parsed !== undefined ? ["```json", JSON.stringify(redactSensitiveValue(parsed), null, 2), "```"].join("\n") : value);
106
+ }
107
+ else
108
+ lines.push("```json", JSON.stringify(value, null, 2), "```");
109
+ }
110
+ return `${lines.join("\n")}\n`;
111
+ }
112
+ /** The workspace-relative file an effect's receipt is written to. */
113
+ export const handoffEffectFile = (effect) => `${HANDOFF_FILES_DIR}/effects/${safeName(effect.id)}-${safeName(effect.name)}.json`;
114
+ /** Write the attempt into `<cwd>/evidence/frozen/`: state.json (the state at the gate), gate.json
115
+ * (the gate and every committed route decision), inputs.json (what the attempt started from), one
116
+ * effects/<id>-<name>.json per completed effect (its arguments and its full result) and one
117
+ * items/<id>.md per judged record. The directory is replaced whole. Returns the paths written,
118
+ * workspace-relative, sorted, and the file each effect went to. */
119
+ export async function writeHandoffFiles(cwd, row, memo, input) {
120
+ const root = path.join(cwd, HANDOFF_FILES_DIR);
121
+ await fs.promises.rm(root, { recursive: true, force: true });
122
+ await fs.promises.mkdir(root, { recursive: true });
123
+ const written = [];
124
+ const effectFiles = {};
125
+ const put = async (relative, body) => {
126
+ const full = path.join(cwd, relative);
127
+ await fs.promises.mkdir(path.dirname(full), { recursive: true });
128
+ await fs.promises.writeFile(full, body);
129
+ written.push(relative);
130
+ };
131
+ const json = (value) => `${JSON.stringify(redactSensitiveValue(value ?? null), null, 2)}\n`;
132
+ const state = row.state ?? {};
133
+ await put(`${HANDOFF_FILES_DIR}/state.json`, json(state));
134
+ await put(`${HANDOFF_FILES_DIR}/gate.json`, json({ kind: row.kind, stage: row.stage, step_label: row.step_label ?? null, summary: row.summary, state_at_gate: state, routes: memo?.routes ?? {} }));
135
+ if (input !== undefined)
136
+ await put(`${HANDOFF_FILES_DIR}/inputs.json`, json({ input, provenance: inputProvenance(input) }));
137
+ const taken = new Set();
138
+ const unique = (file) => {
139
+ let candidate = file;
140
+ for (let n = 2; taken.has(candidate); n++)
141
+ candidate = file.replace(/(\.[a-z]+)$/, `-${n}$1`);
142
+ taken.add(candidate);
143
+ return candidate;
144
+ };
145
+ for (const effect of memo?.effects ?? []) {
146
+ // A completed effect whose answer the journal does not hold has no file: a file with no answer listed as the call's full
147
+ // result would be a lie.
148
+ if (effect.status !== "completed" || effect.result === undefined || effect.result === null)
149
+ continue;
150
+ const receipt = effect.result && typeof effect.result === "object" ? effect.result : null;
151
+ const intent = receipt?.intent && typeof receipt.intent === "object" ? receipt.intent : null;
152
+ const file = unique(handoffEffectFile(effect));
153
+ effectFiles[effect.id] = file;
154
+ await put(file, json({ id: effect.id, name: effect.name, ...(intent?.tool ? { tool: intent.tool } : {}),
155
+ args: intent ? intent.args ?? null : receipt?.args ?? null,
156
+ result: receipt && "value" in receipt ? receipt.value : effect.result ?? null,
157
+ ...(receipt?.files && Object.keys(receipt.files).length ? { files: receipt.files } : {}) }));
158
+ }
159
+ for (const record of judgedRecords(state))
160
+ await put(unique(`${HANDOFF_FILES_DIR}/items/${safeName(record.id)}.md`), renderJudgedRecord(record));
161
+ return { files: written.sort(), effectFiles };
162
+ }
@@ -0,0 +1,42 @@
1
+ import type { RecoveryEffect, RecoveryIntent } from "./store.js";
2
+ /** A completed tool effect a continuation may answer an exact repeat from: the external call it paid for, and its value. */
3
+ export type InheritedReceipt = {
4
+ id: string;
5
+ name: string;
6
+ tool: string;
7
+ argsHash: string;
8
+ result: unknown;
9
+ session: string | null;
10
+ };
11
+ /** An effect whose outcome is unknown: its call is never dispatched again. `intent` is the external call it was admitted
12
+ * for, when its journal recorded one. */
13
+ export type InheritedUnknown = {
14
+ id: string;
15
+ name: string;
16
+ argsHash: string;
17
+ session: string | null;
18
+ intent?: RecoveryIntent;
19
+ };
20
+ /** A tool value that is itself a returned failure: an error envelope (`ok: false`, `isError: true`, `outcome: "error"`) as
21
+ * an object or as its JSON text. Such a value is not a paid result; the continuation may make the call again. Structural,
22
+ * never prose. */
23
+ export declare function returnedFailure(value: unknown): boolean;
24
+ /** The receipts a journal hands to its continuation: completed effects whose receipt names the external call (tool
25
+ * effects; shell and executor effects have no external call to repeat) and whose value is a result, not a returned
26
+ * failure. */
27
+ export declare function inheritableReceipts(effects: readonly RecoveryEffect[]): InheritedReceipt[];
28
+ /** The effects a continuation must not dispatch again: every effect whose outcome is unknown, by the name and argument
29
+ * hash its admission recorded, and by the external call it was admitted for when the journal holds one. A call the
30
+ * continuation's own tools make is matched by `reuseReceipts` on either key. A session effect's name and hash are
31
+ * already a tool's name and the hash of its arguments. A tool effect the driver admitted for a workflow node is named
32
+ * by the node's label and hashed over the node's whole invocation, so it is matched by its intent (the tool and the
33
+ * hash of its arguments, keyed as `gatewayIntentOf` keys a call); one a journal admitted before intents were recorded
34
+ * has none, and is matched by name and hash only. */
35
+ export declare function inheritableUnknowns(effects: readonly RecoveryEffect[]): InheritedUnknown[];
36
+ /** The external call a model tool call stands for: the gateway tool and the hash of its arguments. Only a `fetch`
37
+ * wrapper names the gateway tool in its arguments; every other tool is its own name, whatever its arguments look like.
38
+ * The same key is computed for an effect from its receipt's intent. */
39
+ export declare function gatewayIntentOf(name: string, args: unknown): {
40
+ tool: string;
41
+ argsHash: string;
42
+ };
@@ -0,0 +1,53 @@
1
+ import { canonicalHash } from "./canonical-hash.js";
2
+ /** A tool value that is itself a returned failure: an error envelope (`ok: false`, `isError: true`, `outcome: "error"`) as
3
+ * an object or as its JSON text. Such a value is not a paid result; the continuation may make the call again. Structural,
4
+ * never prose. */
5
+ export function returnedFailure(value) {
6
+ const failed = (parsed) => Boolean(parsed && typeof parsed === "object" && !Array.isArray(parsed) && (parsed.ok === false || parsed.isError === true || parsed.outcome === "error"));
7
+ if (typeof value !== "string")
8
+ return failed(value);
9
+ // The envelope may be the whole text (pretty-printed or not) or one line of it with guidance appended; each
10
+ // candidate is parsed structurally, never matched as prose.
11
+ for (const candidate of [value.trim(), ...value.split("\n").map((line) => line.trim())]) {
12
+ if (!candidate.startsWith("{"))
13
+ continue;
14
+ try {
15
+ if (failed(JSON.parse(candidate)))
16
+ return true;
17
+ }
18
+ catch { /* not this candidate */ }
19
+ }
20
+ return false;
21
+ }
22
+ /** The receipts a journal hands to its continuation: completed effects whose receipt names the external call (tool
23
+ * effects; shell and executor effects have no external call to repeat) and whose value is a result, not a returned
24
+ * failure. */
25
+ export function inheritableReceipts(effects) {
26
+ return effects.filter((e) => e.status === "completed" && e.result && typeof e.result === "object" && e.result.intent && typeof e.result.intent.tool === "string" && !returnedFailure(e.result.value))
27
+ .map((e) => {
28
+ const receipt = e.result;
29
+ // Keyed as a continuation's own call is: a node that reached the gateway through the fetch wrapper paid for the tool the wrapper names.
30
+ const { tool, argsHash } = gatewayIntentOf(receipt.intent.tool, receipt.intent.args ?? {});
31
+ return { id: e.id, name: e.name, tool, argsHash, result: receipt.value, session: e.session };
32
+ });
33
+ }
34
+ /** The effects a continuation must not dispatch again: every effect whose outcome is unknown, by the name and argument
35
+ * hash its admission recorded, and by the external call it was admitted for when the journal holds one. A call the
36
+ * continuation's own tools make is matched by `reuseReceipts` on either key. A session effect's name and hash are
37
+ * already a tool's name and the hash of its arguments. A tool effect the driver admitted for a workflow node is named
38
+ * by the node's label and hashed over the node's whole invocation, so it is matched by its intent (the tool and the
39
+ * hash of its arguments, keyed as `gatewayIntentOf` keys a call); one a journal admitted before intents were recorded
40
+ * has none, and is matched by name and hash only. */
41
+ export function inheritableUnknowns(effects) {
42
+ return effects.filter((e) => e.status === "unknown").map((e) => ({ id: e.id, name: e.name, argsHash: e.argsHash, session: e.session,
43
+ ...(e.intent ? { intent: { tool: e.intent.tool, argsHash: e.intent.argsHash } } : {}) }));
44
+ }
45
+ /** The external call a model tool call stands for: the gateway tool and the hash of its arguments. Only a `fetch`
46
+ * wrapper names the gateway tool in its arguments; every other tool is its own name, whatever its arguments look like.
47
+ * The same key is computed for an effect from its receipt's intent. */
48
+ export function gatewayIntentOf(name, args) {
49
+ const a = args;
50
+ if (name === "fetch" && a && typeof a === "object" && typeof a.tool === "string" && a.args && typeof a.args === "object" && !Array.isArray(a.args))
51
+ return { tool: a.tool, argsHash: canonicalHash(a.args) };
52
+ return { tool: name, argsHash: canonicalHash(args ?? {}) };
53
+ }
@@ -0,0 +1,12 @@
1
+ /** Whether a key names a credential, by the explicit lists above. */
2
+ export declare function isCredentialKey(key: string): boolean;
3
+ /** Credential-shaped substrings of any text, each replaced by `<redacted>`: an HTTP `Bearer` credential, an environment
4
+ * assignment (`NAME=value`) whose name is a credential key, a URL's userinfo, a JWT, and the prefixed keys providers
5
+ * issue (`sk-`, GitHub `gh?_` and `github_pat_`, Slack `xox?-`, AWS `AKIA`, Google `AIza`). A SHA-256 or any other
6
+ * unprefixed digest is not a credential. */
7
+ export declare function redactCredentialText(value: unknown): string;
8
+ /** A value with every credential-named key's value and every credential-shaped string redacted, objects and arrays walked. */
9
+ export declare function redactSensitiveValue(value: unknown): unknown;
10
+ /** Every string that reaches a continuation's first turn passes here: values redacted object-aware first, then the
11
+ * finished text once more by pattern, and an email address by its form. */
12
+ export declare const redactText: (text: string) => string;
@@ -0,0 +1,44 @@
1
+ // Credentials, not substrings. A value is redacted when its key names a credential or when the value has a credential's
2
+ // shape. Key names are compared as words (split on `_`, `-`, spaces and camelCase, lowercased): a key names a credential
3
+ // when any of its words is a credential word, or any two adjacent words are a credential pair. `input_tokens` is the
4
+ // words [input, tokens]; `tokens` is a count's word, never the credential word `token`, so counts and limits survive
5
+ // while `access_token`, `token_value` and `api_key_id` do not.
6
+ /** Words that name a credential wherever they stand in a key. */
7
+ const CREDENTIAL_WORDS = new Set(["token", "secret", "password", "passwd", "passphrase", "authorization", "cookie", "credential", "credentials", "apikey"]);
8
+ /** Adjacent word pairs that name a credential: `api_key`, `X-Api-Key`, `OPENAI_API_KEY`, `private_key`, `aws_secret_access_key`. */
9
+ const CREDENTIAL_PAIRS = new Set(["api key", "private key", "secret key", "access key", "master key", "signing key", "session key", "auth key"]);
10
+ const keyWords = (key) => key.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
11
+ /** Whether a key names a credential, by the explicit lists above. */
12
+ export function isCredentialKey(key) {
13
+ const words = keyWords(key);
14
+ return words.some((word, index) => CREDENTIAL_WORDS.has(word) || (index > 0 && CREDENTIAL_PAIRS.has(`${words[index - 1]} ${word}`)));
15
+ }
16
+ /** Credential-shaped substrings of any text, each replaced by `<redacted>`: an HTTP `Bearer` credential, an environment
17
+ * assignment (`NAME=value`) whose name is a credential key, a URL's userinfo, a JWT, and the prefixed keys providers
18
+ * issue (`sk-`, GitHub `gh?_` and `github_pat_`, Slack `xox?-`, AWS `AKIA`, Google `AIza`). A SHA-256 or any other
19
+ * unprefixed digest is not a credential. */
20
+ export function redactCredentialText(value) {
21
+ return String(value ?? "")
22
+ .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/g, "Bearer <redacted>")
23
+ .replace(/\b([A-Z][A-Z0-9_]*)=(\S+)/g, (whole, name) => (isCredentialKey(name) ? `${name}=<redacted>` : whole))
24
+ .replace(/\b([a-z][a-z0-9+.-]*:\/\/)[^\s/?#@:]+(?::[^\s/?#@]*)?@/gi, "$1<redacted>@")
25
+ .replace(/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, "<redacted>")
26
+ .replace(/\b(?:sk-[A-Za-z0-9_-]{16,}|crsr_[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|xox[abprs]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z_-]{35})/g, "<redacted>");
27
+ }
28
+ /** A value with every credential-named key's value and every credential-shaped string redacted, objects and arrays walked. */
29
+ export function redactSensitiveValue(value) {
30
+ if (typeof value === "string")
31
+ return redactCredentialText(value);
32
+ if (Array.isArray(value))
33
+ return value.map((item) => redactSensitiveValue(item));
34
+ if (value && typeof value === "object") {
35
+ const out = {};
36
+ for (const [key, item] of Object.entries(value))
37
+ out[key] = isCredentialKey(key) ? "<redacted>" : redactSensitiveValue(item);
38
+ return out;
39
+ }
40
+ return value;
41
+ }
42
+ /** Every string that reaches a continuation's first turn passes here: values redacted object-aware first, then the
43
+ * finished text once more by pattern, and an email address by its form. */
44
+ export const redactText = (text) => String(redactSensitiveValue(text)).replace(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, "<redacted email>");