@parcha/agentrun-dsl 0.1.0-beta.33 → 0.1.0-beta.35

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.
@@ -1,162 +0,0 @@
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
- }
@@ -1,12 +0,0 @@
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;
@@ -1,44 +0,0 @@
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>");
@@ -1,44 +0,0 @@
1
- import { type InheritedSession, type TranscriptMessage } from "./handoff-digest.js";
2
- import { type InheritedReceipt, type InheritedUnknown } from "./handoff-receipts.js";
3
- import type { RecoveryJournal } from "./store.js";
4
- /** What a continuation inherits from a run that escalated. The package returns it; the host decides who continues. */
5
- export type Handoff = {
6
- /** What happened, the typed state, inputs and spend: bounded and redacted. */
7
- block: string;
8
- /** Each LLM step's transcript, each paid effect and result, files and evidence; null when it could not be built. */
9
- digest: string | null;
10
- /** The attempt written as files under the workspace, relative paths, sorted. */
11
- files: string[];
12
- /** Completed tool effects, keyed by tool and argument hash. */
13
- receipts: InheritedReceipt[];
14
- /** Effects the continuation must not send again. */
15
- unknown: InheritedUnknown[];
16
- /** Why the attempt files could not be written, when they could not: the block then points at files that are not there. */
17
- filesError?: string;
18
- /** Why the digest is null, when it is. */
19
- digestError?: string;
20
- };
21
- export type HandoffOptions = {
22
- /** The run's workspace: the attempt's files are written under it. */
23
- cwd: string;
24
- /** The run's identity as its step sessions are named (`<run>:<label>:step:...`). */
25
- runId: string;
26
- /** The input the run started from, as the dispatch carried it. */
27
- input?: unknown;
28
- /** Where the attempt's report was moved to, when the host set one aside. */
29
- reportPath?: string | null;
30
- /** The host's sizes for the continuation. */
31
- budget?: {
32
- max_tool_calls?: number;
33
- max_seconds?: number;
34
- } | null;
35
- /** The run's step sessions with their spend, from the host's own record of them. */
36
- sessions?: readonly InheritedSession[];
37
- /** A step's transcript by its session id, or null when there is none. */
38
- transcriptOf?: (sessionId: string) => readonly TranscriptMessage[] | null;
39
- };
40
- /** The one place a handoff is built: the escalation row and effects of an open journal, rendered as the continuation's
41
- * first turn. The row must be one the driver committed. Deterministic for a journal and a workspace. */
42
- export declare function buildHandoff(journal: Pick<RecoveryJournal, "state" | "effects">, options: HandoffOptions): Promise<Handoff>;
43
- /** The continuation's first turn: the escalation block, then the digest. Deterministic from its inputs. */
44
- export declare const handoffFirstTurn: (handoff: Pick<Handoff, "block" | "digest">) => string;
@@ -1,46 +0,0 @@
1
- import fs from "node:fs/promises";
2
- import path from "node:path";
3
- import { escalationContextBlock } from "./handoff-block.js";
4
- import { inheritedJobDigest } from "./handoff-digest.js";
5
- import { HANDOFF_FILES_DIR, inputProvenance, writeHandoffFiles } from "./handoff-files.js";
6
- import { inheritableReceipts, inheritableUnknowns } from "./handoff-receipts.js";
7
- /** The one place a handoff is built: the escalation row and effects of an open journal, rendered as the continuation's
8
- * first turn. The row must be one the driver committed. Deterministic for a journal and a workspace. */
9
- export async function buildHandoff(journal, options) {
10
- const snapshot = journal.state;
11
- const row = snapshot?.escalation;
12
- if (!row)
13
- throw new Error("A handoff is built from an escalation the driver committed");
14
- const effects = journal.effects();
15
- const routes = snapshot?.pin?.routes && typeof snapshot.pin.routes === "object" && !Array.isArray(snapshot.pin.routes) ? { ...snapshot.pin.routes } : {};
16
- let files = [];
17
- let effectFiles = {};
18
- let filesError;
19
- try {
20
- ({ files, effectFiles } = await writeHandoffFiles(options.cwd, row, { effects, routes }, options.input));
21
- }
22
- catch (error) {
23
- filesError = String(error?.message ?? error);
24
- }
25
- const evidenceDir = path.join(options.cwd, "evidence");
26
- const gathered = await fs.readdir(evidenceDir).then((names) => names.some((name) => name !== path.basename(HANDOFF_FILES_DIR)), () => false);
27
- const evidence = gathered ? (row.evidence_dir ?? evidenceDir) : null;
28
- const block = escalationContextBlock({ ...row, evidence_dir: evidence, report_path: options.reportPath ?? null, files,
29
- inputs: options.input === undefined ? [] : inputProvenance(options.input), budget: options.budget ?? null });
30
- let digest = null;
31
- let digestError;
32
- try {
33
- digest = inheritedJobDigest({
34
- runId: options.runId, transcriptOf: options.transcriptOf ?? (() => null), cwd: options.cwd, evidenceDir: evidence,
35
- sessions: [...(options.sessions ?? [])],
36
- effects: effects.map((e) => ({ id: e.id, name: e.name, status: e.status, ...(e.status === "completed" ? { result: e.result } : {}) })),
37
- files: snapshot?.files && typeof snapshot.files === "object" ? snapshot.files : {}, effectFiles,
38
- });
39
- }
40
- catch (error) {
41
- digestError = `digest unavailable: ${String(error?.message ?? error)}`;
42
- }
43
- return { block, digest, files, receipts: inheritableReceipts(effects), unknown: inheritableUnknowns(effects), ...(filesError ? { filesError } : {}), ...(digestError && digest === null ? { digestError } : {}) };
44
- }
45
- /** The continuation's first turn: the escalation block, then the digest. Deterministic from its inputs. */
46
- export const handoffFirstTurn = (handoff) => [handoff.block, handoff.digest].filter(Boolean).join("\n\n");