@krapht/ork 0.2.0 → 0.4.0

package/dist/src-UWkk1sl9.mjs

@@ -0,0 +1,1899 @@
+import { Ct as runScope, Et as envReadsOf, Gn as TOOL_PREFIX, Gt as parseTemplate, Hn as programsRunBy, Kn as integrationFor, Kt as renderTemplate, M as declaredProblem, Nn as markValue, Ot as declaredOutputOf, St as heldTimeout, Tt as calledWorkflows, Un as timeoutMs, Vn as isToolNode, Wn as INTEGRATIONS, Wt as evaluate, s as planReason, st as planNodeSession, zn as beforeOf } from "./src-CGqMati3.mjs";
+import path from "node:path";
+import { accessSync, constants, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+// ../nodes/src/call.ts
+/**
+* @file The `workflow.call` node type (RFC-004): renders what the node asks for
+*   and hands it to the run's call port, which starts the workflow as its own
+*   run and waits as the node says.
+*/
+/**
+* A call a limit stopped is cut off, as a session is: the called run ended
+* `quota_exhausted`, or was refused at its start, which the caller's own limits
+* can't see when its project has its own.
+*/
+const limitedCall = (result) => {
+	if (result.ok) return result;
+	return (result.error ?? "").includes("Not started: ") || result.output["runStatus"] === "quota_exhausted" ? {
+		...result,
+		limited: result.error ?? "the called run reached a limit"
+	} : result;
+};
+const callExecutor = (context) => {
+	const { node, calls } = context;
+	if (node.type !== "workflow.call") return Promise.resolve({
+		ok: false,
+		output: {},
+		error: `${context.id} is not a call`
+	});
+	if (calls === void 0) return Promise.resolve({
+		ok: false,
+		output: { status: "fail" },
+		error: "This run cannot call workflows."
+	});
+	const scope = runScope(context.inputs, context.outputs, context.runId);
+	const render = (text) => {
+		const template = parseTemplate(text);
+		return template.ok ? renderTemplate(template.parts, scope) : text;
+	};
+	return calls.invoke({
+		callId: context.id,
+		workflow: render(node.workflow),
+		project: node.project === void 0 ? void 0 : render(node.project),
+		node: node.node,
+		inputs: Object.fromEntries(Object.entries(node.inputs ?? {}).map(([name, value]) => [name, render(value)])),
+		wait: node.wait ?? (node.node === void 0 ? "run" : "node"),
+		ref: node.ref === void 0 ? void 0 : render(node.ref),
+		maxMessages: node.maxMessages,
+		input: context.input,
+		budgetLeftUsd: context.budgetLeftNow?.() ?? context.budgetLeftUsd,
+		channels: (context.workflow.messages ?? []).flatMap(({ between }) => {
+			const [a, b] = between;
+			if (a === context.id) return [b];
+			return b === context.id ? [a] : [];
+		}),
+		linked: (address) => {
+			context.mailbox?.alias(address);
+		}
+	}, context.signal).then(limitedCall);
+};
+// ../nodes/src/claude-result.ts
+/**
+* @file A finished session as a node's result: its report is the output, held
+*   to what the node declares (RFC-010).
+*/
+/** A finished session as a node result: its report is the node's output. */
+const resultOf = (outcome, declared) => {
+	if (outcome === null) return {
+		ok: false,
+		output: {
+			status: "fail",
+			summary: "the session ended without a result"
+		},
+		error: "the session ended without a result"
+	};
+	const { report, usage } = outcome;
+	if (report === null) {
+		const reason = outcome.errors[0] ?? "no valid report";
+		return {
+			ok: false,
+			output: {
+				status: "fail",
+				summary: reason,
+				usage
+			},
+			usage,
+			error: `ended without a report (${outcome.subtype}): ${reason}`,
+			sessionId: outcome.sessionId
+		};
+	}
+	const ran = { sessionId: outcome.sessionId };
+	const output = {
+		...report.fields,
+		status: report.status,
+		summary: report.summary,
+		artifacts: report.artifacts,
+		usage
+	};
+	if (report.branch !== void 0) output["branch"] = report.branch;
+	const problem = declaredProblem(declared, output);
+	if (problem !== null) return {
+		ok: false,
+		output: {
+			status: "fail",
+			summary: problem,
+			artifacts: report.artifacts,
+			usage,
+			...report.branch === void 0 ? {} : { branch: report.branch }
+		},
+		usage,
+		error: problem,
+		...ran
+	};
+	const result = {
+		ok: report.status !== "fail",
+		output,
+		usage,
+		...ran
+	};
+	if (!result.ok) result.error = report.summary;
+	return result;
+};
+// ../nodes/src/session-turns.ts
+/**
+* @file One session over several processes: the outcome after another turn, and
+*   what that turn may spend. Late messages and failed checks both resume a
+*   session that has finished, and neither is free.
+*/
+/**
+* The later outcome, with the tokens of both processes. Its cost is already the
+* session's total: Claude Code carries it across a resume (ADR-046).
+*/
+const withUsageOf = (first, later) => {
+	const sum = (key) => first.usage[key] + later.usage[key];
+	const usage = {
+		costUsd: Math.max(first.usage.costUsd, later.usage.costUsd),
+		inputTokens: sum("inputTokens"),
+		outputTokens: sum("outputTokens"),
+		cacheReadTokens: sum("cacheReadTokens"),
+		cacheWriteTokens: sum("cacheWriteTokens"),
+		turns: sum("turns"),
+		durationMs: sum("durationMs")
+	};
+	const sessionId = later.sessionId === "" ? first.sessionId : later.sessionId;
+	return {
+		...later,
+		sessionId,
+		usage
+	};
+};
+/**
+* The session after a late turn. A turn that gave no report, as when it ran out
+* of budget or was stopped, does not undo the report the node already gave.
+*/
+const afterLateTurn = (first, later) => {
+	const merged = withUsageOf(first, later);
+	return later.report === null ? {
+		...merged,
+		report: first.report,
+		subtype: first.subtype,
+		text: first.text,
+		errors: first.errors
+	} : merged;
+};
+/**
+* What another turn of a session may use. `spent` and `turns` are this
+* activation's, which neither the node's cap nor the run's budget has counted.
+* The quota has: the ledger took it as the session finished, so what it says is
+* left is left. `null` when nothing is, and the turn does not start.
+*/
+const lateLimits = (spec, { spent, turns }, runLeft, quotaLeft) => {
+	const budgets = [...[spec.budgetUsd, runLeft].flatMap((limit) => limit === void 0 ? [] : [limit - spent]), ...quotaLeft === void 0 ? [] : [quotaLeft]];
+	const budgetUsd = budgets.length === 0 ? void 0 : Math.min(...budgets);
+	if (budgetUsd !== void 0 && budgetUsd <= 0) return null;
+	const maxTurns = spec.maxTurns === void 0 ? void 0 : spec.maxTurns - turns;
+	if (maxTurns !== void 0 && maxTurns <= 0) return null;
+	return {
+		...budgetUsd === void 0 ? {} : { budgetUsd },
+		...maxTurns === void 0 ? {} : { maxTurns }
+	};
+};
+/** What a session may spend as it starts: the least of the budget and any quota. */
+const budgetNow = (context) => {
+	if (context.budgetLeftNow === void 0) return context.budgetLeftUsd;
+	const known = [context.budgetLeftNow(), context.quota?.().leftUsd].flatMap((left) => left === void 0 ? [] : [left]);
+	return known.length === 0 ? void 0 : Math.min(...known);
+};
+/**
+* Whether a limit across runs, rather than the node's work, ended a node: a
+* session whose cap was a quota's and that ran into it, or one its plan refused
+* and that gave no report. A node that still succeeded is left alone.
+*/
+const limitWatch = (context) => {
+	let why;
+	return {
+		stoppedBy: (reason) => {
+			why = reason;
+		},
+		session: (asked) => {
+			const left = context.quota?.().leftUsd;
+			let refused;
+			return {
+				saw: (event) => {
+					if (event.type === "plan.limit" && event.status === "rejected") refused = planReason(event);
+				},
+				ended: (outcome) => {
+					if (refused !== void 0 && (outcome?.report ?? null) === null) why = refused;
+					if (left !== void 0 && asked.budgetUsd !== void 0 && asked.budgetUsd >= left && outcome?.subtype === "error_max_budget_usd") why = context.quota?.().blocked ?? "a session reached what was left of a quota";
+				}
+			};
+		},
+		result: (result) => result.ok || why === void 0 ? result : {
+			...result,
+			limited: why
+		}
+	};
+};
+/** No session started: nothing was left for one. */
+const notStarted = (reason, limited) => ({
+	ok: false,
+	error: `not started: ${reason}`,
+	output: {
+		status: "fail",
+		summary: `not started: ${reason}`
+	},
+	...limited === void 0 ? {} : { limited }
+});
+// ../nodes/src/tool-output.ts
+/**
+* @file A tool node's structured result (`output: { format: json }`): the file
+*   at `$ORK_OUTPUT` when the program wrote one, otherwise its whole stdout. A
+*   result that cannot be read fails the node rather than turning into an empty
+*   value, and one too large to keep in an event is never cut. What a program
+*   wrote is not yet scrubbed, so these files live in a private folder that a
+*   run clears when it starts and ends.
+*/
+/** The run's private folder for results not yet read. */
+const OUTPUT_FOLDER = ".output";
+/**
+* Removes a result, or whatever else the program left in its place. What cannot
+* go here is reported when the run clears its folder.
+*/
+const removeOutputFile = (file) => {
+	try {
+		rmSync(file, {
+			force: true,
+			recursive: true
+		});
+	} catch {}
+};
+/**
+* Removes what a run left before it could read its results. A folder that will
+* not go is worth a warning, not worth failing a run over.
+*/
+const clearOutputFiles = (runDir, warn) => {
+	const folder = path.join(runDir, OUTPUT_FOLDER);
+	try {
+		rmSync(folder, {
+			force: true,
+			recursive: true
+		});
+	} catch {
+		warn(`Could not remove ${folder}, which may hold a result that was not scrubbed.`);
+	}
+};
+/** A clean place for the program to write to, in the run's files. */
+const prepareOutputFile = (runDir, id, round) => {
+	const folder = path.join(runDir, OUTPUT_FOLDER);
+	mkdirSync(runDir, { recursive: true });
+	mkdirSync(folder, {
+		mode: 448,
+		recursive: true
+	});
+	const file = path.join(folder, `${id}.${String(round)}.output.json`);
+	removeOutputFile(file);
+	return file;
+};
+/** Where a long field of a node's output is kept. */
+const keptFile = (context, field) => path.join(context.runDir, `${context.id}.${String(context.round)}.${field}.txt`);
+/** A way to write a field of a node's output to the run's files, when it's long. */
+const keepFile = (context, field, text) => () => {
+	mkdirSync(context.runDir, { recursive: true });
+	const file = keptFile(context, field);
+	writeFileSync(file, text);
+	return file;
+};
+/** Writes a node's `script:` where the run can start it, for this go only. */
+const writeScriptFile = (runDir, id, round, text) => {
+	const folder = path.join(runDir, OUTPUT_FOLDER);
+	mkdirSync(folder, {
+		mode: 448,
+		recursive: true
+	});
+	const file = path.join(folder, `${id}.${String(round)}.script`);
+	writeFileSync(file, text, { mode: 384 });
+	return file;
+};
+/** Two keys can mask to the same text; neither value is lost. */
+const scrubbedKeys = (value, scrub) => {
+	const entries = Object.entries(value).map(([key, item]) => [scrub(key), item]);
+	const named = new Set(entries.map(([name]) => name));
+	const used = /* @__PURE__ */ new Set();
+	return entries.map(([name, item]) => {
+		let unique = name;
+		for (let count = 2; used.has(unique); count += 1) {
+			const next = `${name} ${String(count)}`;
+			if (!named.has(next)) unique = next;
+		}
+		used.add(unique);
+		return [unique, item];
+	});
+};
+/** A parsed value with its keys and strings scrubbed; numbers are not touched. */
+const scrubbed = (value, scrub) => {
+	if (typeof value === "string") return scrub(value);
+	if (Array.isArray(value)) return value.map((item) => scrubbed(item, scrub));
+	if (typeof value === "object" && value !== null) return Object.fromEntries(scrubbedKeys(value, scrub).map(([key, item]) => [key, scrubbed(item, scrub)]));
+	return value;
+};
+/**
+* Parses, comparing each number by its text as written as well as its value:
+* `12345678901234567890` reads back as a different number, which would no
+* longer match the secret.
+*/
+const parseScrubbingNumbers = (text, scrub) => {
+	return JSON.parse(text, (_key, value, seen) => {
+		const source = seen?.source;
+		if (typeof value !== "number" || source === void 0) return value;
+		const masked = scrub(source);
+		if (masked !== source) return masked;
+		const read = String(value);
+		const maskedRead = scrub(read);
+		return maskedRead === read ? value : maskedRead;
+	});
+};
+/**
+* Reads JSON with everything in it scrubbed, numbers too. Throws as a parser
+* does.
+*/
+const parseScrubbed = (text, scrub) => scrubbed(parseScrubbingNumbers(text, scrub), scrub);
+const parsed = (text, source, scrub) => {
+	if (text.trim() === "") return {
+		ok: false,
+		error: `${source} is empty`
+	};
+	try {
+		return {
+			ok: true,
+			json: parseScrubbed(text, scrub)
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: error instanceof RangeError ? `${source} is nested too deeply to read` : `${source} is not valid JSON`
+		};
+	}
+};
+/** What the program wrote to `$ORK_OUTPUT`; a link or a folder is refused. */
+const readWritten = (file, scrub) => {
+	try {
+		return lstatSync(file).isFile() ? parsed(readFileSync(file, "utf8"), "$ORK_OUTPUT", scrub) : {
+			ok: false,
+			error: "$ORK_OUTPUT is not a file"
+		};
+	} catch {
+		return {
+			ok: false,
+			error: "$ORK_OUTPUT could not be read"
+		};
+	}
+};
+/** Whether something is there; a folder the program broke counts, and fails. */
+const wasWritten = (file) => {
+	try {
+		return lstatSync(file, { throwIfNoEntry: false }) !== void 0;
+	} catch {
+		return true;
+	}
+};
+/**
+* Reads the program's result and removes its file: what is kept is the scrubbed
+* value. `limit` is how long it may be once serialized; `keep` saves one that
+* is longer and says where.
+*/
+const readJsonOutput = (input) => {
+	const { file, stdout, scrub, limit, keep } = input;
+	const result = wasWritten(file) ? readWritten(file, scrub) : parsed(stdout, "stdout", scrub);
+	removeOutputFile(file);
+	if (!result.ok) return result;
+	const text = JSON.stringify(result.json) ?? "";
+	return text.length <= limit ? result : {
+		ok: false,
+		error: `the JSON result is ${String(text.length)} characters, over the limit of ${String(limit)}; it is in ${keep(text)}`
+	};
+};
+/**
+* The command line a tool node declares: its `command`, or what runs its
+* script.
+*/
+const commandLineOf = (node) => node.script === void 0 ? node.command : node.interpreter ?? "sh -eu";
+/**
+* Splits a command into arguments the way a shell would, without running one:
+* whitespace separates, `'…'` is literal, `"…"` and `\` escape, and `{{ … }}`
+* stays whole so a template is rendered inside its own argument.
+*/
+const tokenize = (command) => {
+	const args = [];
+	let current = null;
+	let index = 0;
+	const add = (text) => {
+		current = (current ?? "") + text;
+	};
+	while (index < command.length) {
+		const char = command.charAt(index);
+		if (command.startsWith("{{", index)) {
+			const end = command.indexOf("}}", index + 2);
+			if (end === -1) return {
+				ok: false,
+				error: "unclosed {{ in command"
+			};
+			add(command.slice(index, end + 2));
+			index = end + 2;
+		} else if (/\s/u.test(char)) {
+			if (current !== null) args.push(current);
+			current = null;
+			index += 1;
+		} else if (char === "'") {
+			const end = command.indexOf("'", index + 1);
+			if (end === -1) return {
+				ok: false,
+				error: "unclosed ' in command"
+			};
+			add(command.slice(index + 1, end));
+			index = end + 1;
+		} else if (char === "\"") {
+			let text = "";
+			index += 1;
+			while (index < command.length && command.charAt(index) !== "\"") {
+				if (command.charAt(index) === "\\") index += 1;
+				text += command.charAt(index);
+				index += 1;
+			}
+			if (index >= command.length) return {
+				ok: false,
+				error: "unclosed \" in command"
+			};
+			add(text);
+			index += 1;
+		} else if (char === "\\") {
+			add(command.charAt(index + 1));
+			index += 2;
+		} else {
+			add(char);
+			index += 1;
+		}
+	}
+	if (current !== null) args.push(current);
+	return {
+		ok: true,
+		args
+	};
+};
+// ../nodes/src/environ.ts
+/** A variable of the user's. */
+const readEnv = (environ, name) => Object.hasOwn(environ, name) ? environ[name] : void 0;
+// ../nodes/src/mcp-servers.ts
+/**
+* @file Reading an MCP server's definition from the project's `.mcp.json`, the
+*   file Claude Code reads too, so a server is defined in one place (RFC-006).
+*   `${VAR}` and `${VAR:-default}` read the user's environment, which is where
+*   secrets stay: Ork stores none, and a run masks each value read this way. A
+*   server that needs an OAuth sign-in holds Claude Code's tokens, not Ork's,
+*   so it is refused.
+*/
+const MCP_FILE = ".mcp.json";
+const VARIABLE = /\$\{([A-Za-z_]\w*)(?::-([^}]*))?\}/gu;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The file's `mcpServers`; `{}` when there is no file. */
+const serversIn = (root) => {
+	const file = path.join(root, MCP_FILE);
+	if (!existsSync(file)) return {
+		ok: true,
+		value: {}
+	};
+	try {
+		const parsed = JSON.parse(readFileSync(file, "utf8"));
+		const servers = isRecord(parsed) ? parsed["mcpServers"] : void 0;
+		return {
+			ok: true,
+			value: isRecord(servers) ? servers : {}
+		};
+	} catch (error) {
+		const reason = error instanceof SyntaxError ? "it is not valid JSON" : error instanceof Error ? error.message : String(error);
+		return {
+			ok: false,
+			error: `${MCP_FILE} can't be read: ${reason}`
+		};
+	}
+};
+const stringsOf = (value) => isRecord(value) ? Object.fromEntries(Object.entries(value).flatMap(([key, item]) => typeof item === "string" ? [[key, item]] : [])) : {};
+const listOf = (value) => Array.isArray(value) ? value.flatMap((item) => typeof item === "string" ? [item] : []) : [];
+/** A server's field that holds something other than text: it would be dropped. */
+const notTextIn = (server) => [
+	"args",
+	"env",
+	"headers"
+].find((field) => {
+	const value = server[field];
+	return (Array.isArray(value) ? value : isRecord(value) ? Object.values(value) : []).some((item) => typeof item !== "string");
+});
+/** The server as written, or why Ork can't call it. */
+const readMcpServer = (root, name) => {
+	const servers = serversIn(root);
+	if (!servers.ok) return servers;
+	const known = Object.keys(servers.value);
+	const server = Object.hasOwn(servers.value, name) ? servers.value[name] : void 0;
+	if (!isRecord(server)) return {
+		ok: false,
+		error: `no MCP server \`${name}\` in ${MCP_FILE}${known.length === 0 ? "" : `, which has ${known.join(", ")}`}`
+	};
+	if ("oauth" in server) return {
+		ok: false,
+		error: `MCP server \`${name}\` signs in with OAuth, whose tokens are Claude Code's: give it a token through headers and \`env:\`, or call it from a session`
+	};
+	const notText = notTextIn(server);
+	if (notText !== void 0) return {
+		ok: false,
+		error: `MCP server \`${name}\` has a value in ${notText} that isn't a string: write it in quotes`
+	};
+	const { type, url, command } = server;
+	if (type === "http" && typeof url === "string") return {
+		ok: true,
+		value: {
+			kind: "http",
+			url,
+			headers: stringsOf(server["headers"])
+		}
+	};
+	if ((type === void 0 || type === "stdio") && typeof command === "string") return {
+		ok: true,
+		value: {
+			kind: "stdio",
+			command,
+			args: listOf(server["args"]),
+			env: stringsOf(server["env"])
+		}
+	};
+	return {
+		ok: false,
+		error: `MCP server \`${name}\` is not one Ork can call: it takes stdio and http servers`
+	};
+};
+/** Each variable a server reads, and whether it has a default. */
+const readsOf = (server) => {
+	return (server.kind === "stdio" ? [
+		server.command,
+		...server.args,
+		...Object.values(server.env)
+	] : [server.url, ...Object.values(server.headers)]).flatMap((text) => [...text.matchAll(VARIABLE)].map((match) => ({
+		name: String(match[1]),
+		fallback: match[2] !== void 0
+	})));
+};
+/**
+* The server with its variables filled in, and the values to mask: all it read
+* but those `plain` names, which aren't secret.
+*/
+const expandServer = (server, environ, plain = []) => {
+	const unset = readsOf(server).find(({ name, fallback }) => !fallback && readEnv(environ, name) === void 0);
+	if (unset !== void 0) return {
+		ok: false,
+		error: `${MCP_FILE} reads ${unset.name}, which is not set`
+	};
+	const values = [];
+	const fill = (text) => text.replaceAll(VARIABLE, (_all, name, fallback) => {
+		const value = readEnv(environ, name);
+		if (value !== void 0 && !plain.includes(name)) values.push(value);
+		return value ?? fallback ?? "";
+	});
+	const fillAll = (record) => Object.fromEntries(Object.entries(record).map(([key, text]) => [key, fill(text)]));
+	return {
+		ok: true,
+		value: {
+			server: server.kind === "stdio" ? {
+				kind: "stdio",
+				command: fill(server.command),
+				args: server.args.map((arg) => fill(arg)),
+				env: fillAll(server.env)
+			} : {
+				kind: "http",
+				url: fill(server.url),
+				headers: fillAll(server.headers)
+			},
+			values
+		}
+	};
+};
+/** What a workflow's MCP servers read of the user's, unless called not secret. */
+const mcpVariablesOf = (workflow, root) => Object.values(workflow.nodes).flatMap((node) => {
+	if (node.type !== "mcp.call") return [];
+	const read = readMcpServer(root, node.server);
+	return read.ok ? readsOf(read.value).map(({ name }) => name).filter((name) => node.plainEnv?.includes(name) !== true) : [];
+});
+/** A stdio server's program, when its name can be known before it is filled in. */
+const programOf = (server) => server.kind === "stdio" && !server.command.includes("$") ? server.command : void 0;
+/**
+* What stops a workflow's `mcp.call` nodes, found before a run spends anything:
+* a server that isn't there or can't be called, a program that isn't installed,
+* or a variable that is not set.
+*/
+const mcpProblems = (workflow, root, environ = process.env, finished = /* @__PURE__ */ new Set(), installed = () => true) => Object.entries(workflow.nodes).flatMap(([id, node]) => {
+	if (node.type !== "mcp.call" || finished.has(id)) return [];
+	const read = readMcpServer(root, node.server);
+	if (!read.ok) return [`${id}: ${read.error}`];
+	const given = new Set(Object.keys(node.env ?? {}));
+	const unset = readsOf(read.value).flatMap(({ name, fallback }) => fallback || given.has(name) || readEnv(environ, name) !== void 0 ? [] : [`${id}: ${MCP_FILE} reads ${name}, which is not set`]);
+	const program = programOf(read.value);
+	return program === void 0 || installed(program) ? unset : [`\`${id}\`: MCP server \`${node.server}\` runs \`${program}\`, which is not installed`].concat(unset);
+});
+// ../nodes/src/tool-scrub.ts
+/**
+* @file Masking a secret in what a program prints. A plain search, so a value
+*   of any size or shape takes time in step with the text: it looks in the text
+*   as it is, and with JSON's escapes decoded once and twice, so that it does
+*   not matter which characters an encoder chose to escape. It masks the value,
+*   and the pieces programs print on their own: each line, and each value of a
+*   JSON document. Other encodings, such as base64, are out of its reach
+*   (L81).
+*/
+/** Shorter values than this would mask ordinary text: `1`, `true`, a word. */
+const MIN_SECRET_LENGTH = 8;
+const SHORT_ESCAPES = {
+	"\"": "\"",
+	"\\": "\\",
+	"/": "/",
+	b: "\b",
+	f: "\f",
+	n: "\n",
+	r: "\r",
+	t: "	"
+};
+/** The unit an escape at `at` stands for, and how long it is written. */
+const escapeAt = (text, at) => {
+	const next = text.charAt(at + 1);
+	const short = SHORT_ESCAPES[next];
+	if (short !== void 0) return {
+		unit: short,
+		width: 2
+	};
+	if (next !== "u") return null;
+	const hex = text.slice(at + 2, at + 6);
+	return /^[\da-f]{4}$/iu.test(hex) ? {
+		unit: String.fromCodePoint(Number(`0x${hex}`)),
+		width: 6
+	} : null;
+};
+/** The last mark at or before `index`, by a binary search. */
+const lastMark = (marks, index) => {
+	let low = 0;
+	let high = marks.length - 1;
+	while (low < high) {
+		const middle = Math.ceil((low + high) / 2);
+		if ((marks[middle] ?? 0) <= index) low = middle;
+		else high = middle - 1;
+	}
+	return low;
+};
+/** The view with its escapes decoded; `null` when it has none. */
+const decoded = (view) => {
+	const { text } = view;
+	const parts = [];
+	const decodedAt = [0];
+	const sourceAt = [0];
+	let from = 0;
+	let length = 0;
+	let at = text.indexOf("\\");
+	while (at !== -1) {
+		const escape = escapeAt(text, at);
+		if (escape === null) at = text.indexOf("\\", at + 1);
+		else {
+			parts.push(text.slice(from, at), escape.unit);
+			length += at - from;
+			decodedAt.push(length);
+			sourceAt.push(at);
+			length += 1;
+			from = at + escape.width;
+			decodedAt.push(length);
+			sourceAt.push(from);
+			at = text.indexOf("\\", from);
+		}
+	}
+	if (from === 0) return null;
+	parts.push(text.slice(from));
+	return {
+		text: parts.join(""),
+		toSource: (index) => {
+			const mark = lastMark(decodedAt, index);
+			return view.toSource((sourceAt[mark] ?? 0) + (index - (decodedAt[mark] ?? 0)));
+		}
+	};
+};
+/** The text as it is, then decoded as far as JSON inside JSON goes. */
+const viewsOf = (text) => {
+	const raw = {
+		text,
+		toSource: (index) => index
+	};
+	const once = decoded(raw);
+	const twice = once === null ? null : decoded(once);
+	return [
+		raw,
+		...once === null ? [] : [once],
+		...twice === null ? [] : [twice]
+	];
+};
+/** Where each secret is in the text, overlapping ones joined. */
+const rangesOf = (text, secrets) => {
+	const found = [];
+	for (const view of viewsOf(text)) for (const secret of secrets) {
+		let at = view.text.indexOf(secret);
+		while (at !== -1) {
+			found.push([view.toSource(at), view.toSource(at + secret.length)]);
+			at = view.text.indexOf(secret, at + secret.length);
+		}
+	}
+	const joined = [];
+	for (const [start, end] of found.toSorted((a, b) => a[0] - b[0])) {
+		const last = joined.at(-1);
+		if (last !== void 0 && start < last[1]) last[1] = Math.max(last[1], end);
+		else joined.push([start, end]);
+	}
+	return joined;
+};
+/** The strings and numbers inside a parsed JSON document. */
+const leavesOf = (value) => {
+	if (typeof value === "string") return [value];
+	if (typeof value === "number") return [String(value)];
+	if (typeof value === "object" && value !== null) return Object.values(value).flatMap((item) => leavesOf(item));
+	return [];
+};
+/** A value's leaves, when it is a JSON object or array. */
+const jsonLeavesOf = (value) => {
+	if (!/^\s*[[{]/u.test(value)) return [];
+	try {
+		return leavesOf(JSON.parse(value));
+	} catch {
+		return [];
+	}
+};
+/** A value, and the pieces of it a program may well print on their own. */
+const formsOf = (value) => [
+	value,
+	value.trim(),
+	...value.split(/\r?\n|\r/u).map((line) => line.trim()),
+	...jsonLeavesOf(value)
+];
+/** Replaces the values, in any form JSON writes them, with `[masked]`. */
+const scrubberOf = (values) => {
+	const secrets = [...new Set(values.flatMap((value) => formsOf(value)))].filter((secret) => secret.trim().length >= MIN_SECRET_LENGTH);
+	return (text) => {
+		if (secrets.length === 0) return text;
+		const parts = [];
+		let from = 0;
+		for (const [start, end] of rangesOf(text, secrets)) {
+			parts.push(text.slice(from, start), "[masked]");
+			from = end;
+		}
+		parts.push(text.slice(from));
+		return parts.join("");
+	};
+};
+// ../nodes/src/tool-env.ts
+/**
+* @file What a tool node's program sees besides what it inherits: who it is
+*   (`ORK_*`), and the node's `env:`, rendered as templates. Only `env:` may
+*   read the user's own variables, so their values never reach a recorded
+*   command, and those values are scrubbed from what the program prints.
+*/
+/** The file a node with `output: { format: json }` may write its result to. */
+const OUTPUT_ENV = "ORK_OUTPUT";
+/** A file a `watch:` node's program keeps between looks (RFC-011). */
+const STATE_ENV = "ORK_STATE";
+/** Set for a program in a run. */
+const RUN_ENV = "ORK_RUN";
+/** Set for a Claude session. It says no more than that: no run, no node. */
+const SESSION_ENV = "ORK_SESSION";
+/** The variables a caller's run reads, for a run it calls to mask too. */
+const MASKED_ENV = "ORK_MASKED";
+/** Every variable Ork sets itself; a workflow's `env:` cannot set them. */
+const IDENTITY_KEYS = /* @__PURE__ */ new Set([
+	RUN_ENV,
+	SESSION_ENV,
+	MASKED_ENV,
+	"ORK_NODE",
+	"ORK_ROUND",
+	"ORK_RUN_DIR",
+	"ORK_PROJECT",
+	"ORK_WORKFLOW",
+	"ORK_BIN",
+	OUTPUT_ENV,
+	STATE_ENV
+]);
+/**
+* `env` without Ork's identity variables. A run started by a program in another
+* run must not pass that run's identity on to its own sessions and programs.
+*/
+const withoutIdentity = (env) => Object.fromEntries(Object.entries(env).flatMap(([key, value]) => value === void 0 || IDENTITY_KEYS.has(key) ? [] : [[key, value]]));
+/**
+* What a Claude session runs with: no identity, only the marker that stops its
+* Bash from speaking as the user through `ork chat`.
+*/
+const sessionEnv = (env) => ({
+	...withoutIdentity(env),
+	[SESSION_ENV]: "1"
+});
+/**
+* The variable that says a program in a run or a session started this process,
+* or `null` when none does.
+*/
+const runMarkerIn = (env) => ["ORK_RUN", SESSION_ENV].find((name) => env[name] !== void 0) ?? null;
+/** Who a node's program is. It is attribution, not a security boundary. */
+const identityOf = (context, orkBin) => ({
+	[RUN_ENV]: context.runId,
+	ORK_NODE: context.id,
+	ORK_ROUND: String(context.round),
+	ORK_RUN_DIR: context.runDir,
+	ORK_PROJECT: context.projectRoot,
+	ORK_WORKFLOW: context.workflow.name,
+	...orkBin === void 0 ? {} : { ORK_BIN: orkBin }
+});
+/** The variables a workflow's nodes read that no `plainEnv` excuses. */
+const secretNamesOf = (workflow) => Object.values(workflow.nodes).flatMap((node) => programsRunBy(node, workflow.defaults)).flatMap(({ program }) => {
+	const plain = new Set(program.plainEnv);
+	return Object.values(program.env ?? {}).flatMap((value) => envReadsOf(value)).filter((name) => !plain.has(name));
+});
+/** What the run that called this one told it to mask. */
+const inheritedNames = (environ) => (environ[MASKED_ENV] ?? "").split(",").filter((name) => name !== "");
+/**
+* The variables a run must mask: what its workflow and its MCP servers read,
+* what the workflows it calls by name read, and what its caller reads. Any of
+* them may print any of these, since a called run inherits the same
+* environment.
+*/
+const maskedNamesOfRun = (workflow, own, registered, environ = process.env) => [...new Set([workflow, ...calledWorkflows(workflow, own, registered, { everyCall: true })].flatMap((one) => secretNamesOf(one)).concat(mcpVariablesOf(workflow, own.root), inheritedNames(environ)))];
+/**
+* A program learns the names too, never their values: `ork send` masks with
+* them before it writes to the store, and a run the program starts passes them
+* on.
+*/
+const namesToMask = (workflow, environ, also = []) => [.../* @__PURE__ */ new Set([
+	...secretNamesOf(workflow),
+	...also,
+	...inheritedNames(environ)
+])];
+const valuesOf = (names, environ) => names.flatMap((name) => {
+	const value = readEnv(environ, name);
+	return value === void 0 ? [] : [value];
+});
+/** What a process in a program masks: what its run told it to. */
+const inheritedScrubber = (environ) => scrubberOf(valuesOf(inheritedNames(environ), environ));
+/** What a run masks in a message of its own: the same names' values. */
+const runScrubber = (names, environ) => scrubberOf(valuesOf(names, environ));
+/** What a run tells a run it calls: names, never values. */
+const maskedEnv = (names) => names.length === 0 ? {} : { [MASKED_ENV]: names.join(",") };
+/** The values to mask: what the workflow reads, and the names given. */
+const secretsOf = (workflow, environ, also = []) => valuesOf(namesToMask(workflow, environ, also), environ);
+/** A node's `env:`, rendered. */
+const renderEnv = (node, context, environ) => {
+	const values = {};
+	const scope = {
+		...runScope(context.inputs, context.outputs, context.runId),
+		output: { env: environ }
+	};
+	for (const [key, text] of Object.entries(node.env ?? {})) {
+		const template = parseTemplate(text);
+		if (!template.ok) return {
+			ok: false,
+			error: template.message
+		};
+		for (const name of envReadsOf(text)) if (readEnv(environ, name) === void 0) return {
+			ok: false,
+			error: `env.${key} reads ${name}, which is not set`
+		};
+		const value = renderTemplate(template.parts, scope);
+		if (value.includes("\0")) return {
+			ok: false,
+			error: `env.${key} holds a null byte`
+		};
+		values[key] = value;
+	}
+	return {
+		ok: true,
+		values
+	};
+};
+/** A runner whose refusal to start is a failed run, with nothing secret in it. */
+const safeRunner = (runner, scrub) => async (program, args, options) => {
+	try {
+		return await runner(program, args, options);
+	} catch (error) {
+		return {
+			exitCode: -1,
+			stdout: "",
+			stderr: scrub(error instanceof Error ? error.message : String(error))
+		};
+	}
+};
+// ../nodes/src/tool-state.ts
+/**
+* @file `$ORK_STATE` (RFC-011): a file a `watch:` node's program keeps between
+*   looks, rounds and a resume, so a script can tell what's new without
+*   inventing a place to keep it. It's the program's to create, and holds what
+*   the program wrote, so it's private, and goes when the run has succeeded.
+*/
+const STATE_FOLDER = ".state";
+/** The file `$ORK_STATE` names, for one node in one run. */
+const prepareStateFile = (runDir, id) => {
+	const folder = path.join(runDir, STATE_FOLDER);
+	mkdirSync(folder, {
+		mode: 448,
+		recursive: true
+	});
+	return path.join(folder, id);
+};
+/** Removes what programs kept, once the run can't go on from it. */
+const clearStateFiles = (runDir, warn) => {
+	const folder = path.join(runDir, STATE_FOLDER);
+	try {
+		rmSync(folder, {
+			force: true,
+			recursive: true
+		});
+	} catch {
+		warn(`Could not remove ${folder}, which holds what a program kept.`);
+	}
+};
+// ../nodes/src/tools.ts
+/**
+* @file The tool node executor, for every registered integration (`tool.gh`,
+*   `tool.aws`, `tool.git`, `tool.shell`, …): the user's own program, run
+*   without a shell, checked against `allow` (or the integration's default),
+*   its arguments and observed output fields from the integration's adapter,
+*   long output kept in run files. It sees who it is and the node's `env:`
+*   (`tool-env.ts`), and may return JSON (`tool-output.ts`).
+*/
+/** How much of stdout and stderr a node's output keeps. */
+const OUTPUT_LIMIT = 65536;
+const ERROR_LIMIT = 1024;
+/** Whether `args` starts with one of the allowed prefixes (`"pr merge"`). */
+const isAllowed = (args, allow) => allow === void 0 || allow.some((prefix) => {
+	return prefix.trim().split(/\s+/u).every((word, i) => args[i] === word);
+});
+const render = (text, context) => {
+	const template = parseTemplate(text);
+	if (!template.ok) return {
+		ok: false,
+		error: template.message
+	};
+	return {
+		ok: true,
+		value: renderTemplate(template.parts, runScope(context.inputs, context.outputs, context.runId))
+	};
+};
+/** The program and arguments a tool node runs, before the allow check. */
+const commandOf = (node, context) => {
+	const line = commandLineOf(node);
+	if (line === void 0) return {
+		ok: false,
+		error: "the node has no command or script"
+	};
+	const tokens = tokenize(line);
+	if (!tokens.ok) return tokens;
+	const args = [];
+	for (const token of tokens.args) {
+		if (node.script !== void 0) {
+			args.push(token);
+			continue;
+		}
+		const rendered = render(token, context);
+		if (!rendered.ok) return rendered;
+		args.push(rendered.value);
+	}
+	const integration = integrationFor(node.type);
+	if (integration === void 0) return {
+		ok: false,
+		error: `no integration for ${node.type}`
+	};
+	const extra = integration.args(node);
+	if (integration.program !== null) return {
+		ok: true,
+		program: integration.program,
+		args: [...args, ...extra]
+	};
+	const [program, ...rest] = [...args, ...extra];
+	if (program === void 0 || program === "") return {
+		ok: false,
+		error: "the command names no program"
+	};
+	return {
+		ok: true,
+		program,
+		args: rest
+	};
+};
+/** Keeps the first `OUTPUT_LIMIT` characters; the rest goes to a file. */
+const capped = (text, file) => {
+	if (text.length <= 65536) return text;
+	return `${text.slice(0, OUTPUT_LIMIT)}\n… (truncated; the full output is in ${file()})`;
+};
+/**
+* Text for a node's `error`, which reaches its events, its `notify:` rules and
+* what a session is told. All of it is kept in the output's fields and files.
+*/
+const clipError = (text) => text.length <= ERROR_LIMIT ? text : `${text.slice(0, ERROR_LIMIT)}…`;
+const failed$1 = (error) => ({
+	ok: false,
+	output: {
+		exitCode: -1,
+		stdout: "",
+		stderr: error
+	},
+	error
+});
+/** Runs a user's CLI through its integration's adapter, with its own login. */
+const toolExecutor = (given, options = {}) => async (context) => {
+	const { node } = context;
+	if (!isToolNode(node)) return failed$1(`${context.id} is not a tool node`);
+	const environ = options.environ ?? process.env;
+	const scrub = scrubberOf(secretsOf(context.workflow, environ, options.maskedNames));
+	const command = commandOf(node, context);
+	if (!command.ok) return failed$1(scrub(command.error));
+	const integration = integrationFor(node.type);
+	const checked = integration?.program === null ? [command.program, ...command.args] : command.args;
+	const allow = node.allow ?? integration?.allow;
+	if (!isAllowed(checked, allow)) return failed$1(scrub(`${markValue(checked.join(" "))} is not in the node's allow list (${(allow ?? []).map((entry) => markValue(entry)).join(", ")})`));
+	let cwd = context.cwd;
+	if (node.cwd !== void 0) {
+		const rendered = render(node.cwd, context);
+		if (!rendered.ok) return failed$1(rendered.error);
+		cwd = path.resolve(context.cwd, rendered.value);
+	}
+	const nodeEnv = renderEnv(node, context, environ);
+	if (!nodeEnv.ok) return failed$1(nodeEnv.error);
+	const runner = safeRunner(given, scrub);
+	const outputFile = node.output?.format === "json" ? prepareOutputFile(context.runDir, context.id, context.round) : void 0;
+	const env = {
+		...nodeEnv.values,
+		...identityOf(context, options.orkBin),
+		...maskedEnv(namesToMask(context.workflow, environ, options.maskedNames)),
+		...outputFile === void 0 ? {} : { [OUTPUT_ENV]: outputFile },
+		...node.watch === void 0 ? {} : { [STATE_ENV]: prepareStateFile(context.runDir, context.id) }
+	};
+	const names = Object.keys(nodeEnv.values);
+	context.emit({
+		type: "tool.called",
+		id: context.id,
+		name: scrub(command.program),
+		input: {
+			command: scrub([
+				command.program,
+				...command.args,
+				...node.script === void 0 ? [] : ["<script>"]
+			].join(" ")),
+			...names.length === 0 ? {} : { env: names }
+		}
+	});
+	const scriptFile = node.script === void 0 ? void 0 : writeScriptFile(context.runDir, context.id, context.round, node.script);
+	const raw = await runner(command.program, scriptFile === void 0 ? command.args : [...command.args, scriptFile], {
+		cwd,
+		signal: context.signal,
+		env
+	});
+	if (scriptFile !== void 0) removeOutputFile(scriptFile);
+	const run = {
+		exitCode: raw.exitCode,
+		stdout: scrub(raw.stdout),
+		stderr: scrub(raw.stderr)
+	};
+	const observed = await integration?.observe?.read(async (args) => {
+		const seen = await runner(command.program, args, {
+			cwd,
+			signal: context.signal,
+			env
+		});
+		return {
+			ok: seen.exitCode === 0,
+			stdout: seen.stdout
+		};
+	}) ?? {};
+	const keep = (field, text) => keepFile(context, field, text);
+	const output = {
+		exitCode: run.exitCode,
+		stdout: capped(run.stdout, keep("stdout", run.stdout)),
+		stderr: capped(run.stderr, keep("stderr", run.stderr))
+	};
+	for (const [field, text] of Object.entries(observed)) output[field] = capped(scrub(text), keep(field, scrub(text)));
+	if (outputFile !== void 0 && run.exitCode !== 0) removeOutputFile(outputFile);
+	const json = outputFile === void 0 || run.exitCode !== 0 ? null : readJsonOutput({
+		file: outputFile,
+		stdout: raw.stdout,
+		scrub,
+		limit: OUTPUT_LIMIT,
+		keep: (text) => keep("json", text)()
+	});
+	const declared = json?.ok === true ? declaredProblem(node.output?.schema, json.json) : null;
+	context.emit({
+		type: "tool.result",
+		id: context.id,
+		isError: run.exitCode !== 0 || json?.ok === false || declared !== null
+	});
+	if (json?.ok === false) return {
+		ok: false,
+		output,
+		error: `${context.id}: ${json.error}`
+	};
+	if (declared !== null) return {
+		ok: false,
+		output,
+		error: declared
+	};
+	if (json !== null) output["json"] = json.json;
+	if (run.exitCode === 0) return {
+		ok: true,
+		output
+	};
+	const last = run.stderr.trim().split("\n").at(-1) ?? "";
+	return {
+		ok: false,
+		transient: true,
+		output,
+		error: `${scrub(command.program)} exited with ${String(run.exitCode)}${last === "" ? "" : `: ${clipError(last)}`}`
+	};
+};
+// ../nodes/src/verify.ts
+/**
+* @file `verify:` (RFC-006): a program that must pass before a session's report
+*   is accepted. On a failure, the same session hears what failed and gets to
+*   fix it, a set number of times, and then the node fails. What goes back to
+*   the session stays small, as a session's cost grows with what it holds.
+*/
+/** A setup that failed: no session started, so nothing was spent on it. */
+const beforeFailed = (ran) => {
+	const error = `its before step failed: ${ran.error ?? "no reason given"}`;
+	return {
+		ok: false,
+		error,
+		output: {
+			status: "fail",
+			summary: error,
+			before: ran.output
+		}
+	};
+};
+/** With nothing to run a step, a report cannot be accepted. */
+const noSteps = () => Promise.resolve({
+	ok: false,
+	output: {},
+	error: "this run has no way to run a check"
+});
+/** How much of a failed check's output a session is sent. */
+const TAIL_LIMIT = 8192;
+/**
+* A report a check stands between: `fail` and `changes_requested` accept
+* nothing.
+*/
+const isAcceptance = (outcome) => outcome.report !== null && outcome.report.status !== "fail" && outcome.report.status !== "changes_requested";
+/** Runs a step as a one-off tool node, in the node's checkout, as the node. */
+const runStep = async (tool, context, { timeout, ...fields }) => {
+	const node = {
+		type: "tool.shell",
+		...fields
+	};
+	const ms = timeoutMs(timeout);
+	if (ms === void 0) return tool({
+		...context,
+		node
+	});
+	const limit = new AbortController();
+	const finished = new AbortController();
+	let expired = false;
+	const watch = async () => {
+		if (await heldTimeout(context.hold, ms, AbortSignal.any([context.signal, finished.signal]))) {
+			expired = true;
+			limit.abort();
+		}
+	};
+	watch();
+	const signal = AbortSignal.any([context.signal, limit.signal]);
+	try {
+		const result = await tool({
+			...context,
+			node,
+			signal
+		});
+		return expired ? {
+			...result,
+			ok: false,
+			error: `timed out after ${String(timeout)}`
+		} : result;
+	} finally {
+		finished.abort();
+	}
+};
+const textOf$1 = (value) => typeof value === "string" ? value.trim() : "";
+/**
+* All a check printed on one stream. A node's output holds only the first 64
+* KiB, and what matters in a failure is usually at the end, so a longer one is
+* read back from the file it was kept in.
+*/
+const printed = (check, field, where) => {
+	const shown = textOf$1(check.output[field]);
+	if (shown.length <= 65536) return shown;
+	try {
+		return readFileSync(keptFile(where, field), "utf8").trim();
+	} catch {
+		return shown;
+	}
+};
+/** The end of what a check printed, and a file with the rest when there is more. */
+const tailOf = (check, context) => {
+	const said = [printed(check, "stdout", context), printed(check, "stderr", context)].filter((text) => text !== "").join("\n");
+	if (said === "") return "It printed nothing.";
+	if (said.length <= TAIL_LIMIT) return `\`\`\`\n${said}\n\`\`\``;
+	mkdirSync(context.runDir, { recursive: true });
+	const file = path.join(context.runDir, `${context.id}.${String(context.round)}.verify.txt`);
+	writeFileSync(file, said);
+	return `The end of what it printed, with all of it in ${file}:\n\n\`\`\`\n${said.slice(-8192)}\n\`\`\``;
+};
+/** What a session is told when the check on its report failed. */
+const checkFailedMessage = (check, context) => `[ork] Your report was not accepted: the workflow's check failed (${check.error ?? "no reason given"}).\n\n${tailOf(check, context)}\n\nFix what it found, and end with a new structured report.`;
+/**
+* Checks a report and, while a check fails and attempts and budget remain,
+* resumes the session. A resume that ends with a report that accepts nothing
+* ends it there, with the check still failed.
+*/
+const checkReport = (given) => {
+	const attempts = given.verify.attempts ?? 1;
+	const go = async (outcome, resumes, readLate) => {
+		const check = given.signal.aborted ? {
+			ok: false,
+			output: {},
+			error: "the node was stopped before its check finished"
+		} : await given.check();
+		if (check.ok && !readLate && !given.signal.aborted) {
+			const later = await given.late?.(outcome) ?? null;
+			if (later !== null) {
+				const merged = afterLateTurn(outcome, later);
+				return isAcceptance(merged) ? go(merged, resumes, true) : {
+					outcome: merged,
+					check,
+					resumes
+				};
+			}
+		}
+		if (check.ok || given.signal.aborted || resumes >= attempts) return {
+			outcome,
+			check,
+			resumes
+		};
+		const later = await given.resume(outcome, check);
+		if (later === null) return {
+			outcome,
+			check,
+			resumes
+		};
+		const merged = withUsageOf(outcome, later);
+		return isAcceptance(merged) ? go(merged, resumes + 1, readLate) : {
+			outcome: merged,
+			check,
+			resumes: resumes + 1
+		};
+	};
+	return go(given.first, 0, false);
+};
+/**
+* A node's result once its report has been checked. A later report that fails
+* says why.
+*/
+const checkedResult = (result, { check, resumes }) => {
+	const verify = {
+		exitCode: check.output["exitCode"],
+		resumes
+	};
+	if (check.ok) return {
+		...result,
+		output: {
+			...result.output,
+			verify
+		}
+	};
+	const reason = `its check failed: ${check.error ?? "no reason given"}`;
+	const error = result.ok ? reason : `${reason} (then: ${result.error ?? "no report"})`;
+	return {
+		...result,
+		ok: false,
+		error,
+		output: {
+			...result.output,
+			status: "fail",
+			summary: error,
+			verify
+		}
+	};
+};
+// ../nodes/src/claude.ts
+/**
+* @file The Claude node type: runs a `claude.leader` or `claude.worker` as one
+*   session, planned with the run's outputs (and the brief its owner gave it),
+*   and turns its report into the node's output. A leader gets its children
+*   through the session's ports, and resumes its session on re-entry
+*   (ADR-019).
+*/
+const MAX_INPUT = 8192;
+/** On a loop re-entry, the brief carries what the workflow sent back. */
+const reentryNote = (round, input) => {
+	const json = JSON.stringify(input ?? {}, void 0, 2);
+	const body = json.length > MAX_INPUT ? `${json.slice(0, MAX_INPUT)}\n…` : json;
+	return `\n\n## Round ${String(round)}\n\nThe workflow sent this task back to you with:\n\n\`\`\`json\n${body}\n\`\`\``;
+};
+/**
+* What a resumed leader is told: it already has its brief and its earlier work,
+* so only the new round, and the new task when its owner sent one.
+*/
+const resumeMessage = (round, input, brief) => [brief === void 0 ? sentBack(round, input) : `## New task from \`${brief.from}\`\n\n${brief.text}`, "End with a new structured report."].join("\n\n");
+/** A first-round resume is a session the run was cut off in (`ork resume`). */
+const sentBack = (round, input) => round === 1 ? "Ork was stopped while you worked on this task, and the run is resumed. Your earlier turns are above: check what you finished, and carry on from there." : `The workflow sent your task back to you.${reentryNote(round, input)}`;
+/** What a session is told when messages came in as it finished. */
+const lateMessage = (count) => `[ork] ${String(count)} message${count === 1 ? "" : "s"} came in while you finished. Call read_inbox, act on ${count === 1 ? "it" : "them"} if needed, and end with a new structured report.`;
+/** A re-entered leader resumes; anyone else starts with the full brief. */
+const specFor = (spec, context) => {
+	if (context.resume !== void 0) return {
+		...spec,
+		resume: context.resume,
+		prompt: resumeMessage(context.round, context.input, context.brief)
+	};
+	if (context.round > 1 && context.brief === void 0) return {
+		...spec,
+		prompt: spec.prompt + reentryNote(context.round, context.input)
+	};
+	return spec;
+};
+/** Runs a `claude.leader` or `claude.worker` as one session. */
+const claudeExecutor = (options) => async (context) => {
+	const planOptions = {
+		cwd: context.cwd,
+		inputs: context.inputs,
+		outputs: context.outputs,
+		inPlace: options.inPlace,
+		workflowDir: context.workflowDir,
+		projectRoot: context.projectRoot,
+		...context.orkDir === void 0 ? {} : { orkDir: context.orkDir },
+		pluginDir: path.join(context.runDir, "plugins", context.id)
+	};
+	if (context.checkout !== void 0) planOptions.checkout = context.checkout;
+	if (context.brief !== void 0) planOptions.brief = context.brief;
+	if (context.template !== void 0) planOptions.template = context.template;
+	if (context.ownership !== void 0) planOptions.ownership = context.ownership;
+	if (context.mailbox !== void 0) planOptions.mailbox = context.mailbox;
+	if (context.claims !== void 0) planOptions.claims = context.claims;
+	const before = beforeOf(context.node, context.workflow.defaults);
+	if (before !== void 0) {
+		const ran = await runStep(options.steps ?? noSteps, context, before);
+		if (!ran.ok) return beforeFailed(ran);
+		await context.hold?.wait("start", context.signal);
+		if (context.signal.aborted) return beforeFailed({
+			...ran,
+			error: "the node was stopped"
+		});
+		planOptions.before = ran.output;
+	}
+	const blocked = context.quota?.().blocked;
+	if (blocked !== void 0) return notStarted(blocked, blocked);
+	const budget = budgetNow(context);
+	if (budget !== void 0 && budget <= 0) return notStarted("nothing is left of the run's budget");
+	if (budget !== void 0) planOptions.budgetLeftUsd = budget;
+	const plan = planNodeSession(context.workflow, context.id, planOptions);
+	if (!plan.ok) return {
+		ok: false,
+		output: {
+			status: "fail",
+			summary: plan.error
+		},
+		error: plan.error
+	};
+	const spec = specFor(plan.spec, context);
+	const runtime = await options.runtimeFor(options.driver ?? plan.driver);
+	const ports = { human: context.human };
+	if (context.hold !== void 0) ports.hold = context.hold;
+	if (context.ownership !== void 0) ports.ownership = context.ownership;
+	if (context.mailbox !== void 0) ports.mailbox = context.mailbox;
+	if (context.claims !== void 0) ports.claims = context.claims;
+	if (context.feedback !== void 0) ports.feedback = context.feedback;
+	const watch = limitWatch(context);
+	const run = async (asked) => {
+		const watching = watch.session(asked);
+		const session = runtime.start(asked, ports);
+		const stop = () => {
+			session.interrupt();
+		};
+		context.signal.addEventListener("abort", stop, { once: true });
+		if (context.signal.aborted) stop();
+		const disconnect = context.mailbox?.connect((notice) => {
+			session.send(notice);
+		});
+		let outcome = null;
+		try {
+			for await (const event of session.events) {
+				if (event.type === "session.finished") outcome = event.outcome;
+				watching.saw(event);
+				context.emit(event);
+			}
+		} finally {
+			disconnect?.();
+			context.signal.removeEventListener("abort", stop);
+		}
+		watching.ended(outcome);
+		return outcome;
+	};
+	const first = await run(spec);
+	const limitsAfter = ({ sessionId, usage }) => {
+		const quota = context.quota?.();
+		if (quota?.blocked !== void 0) {
+			watch.stoppedBy(quota.blocked);
+			return null;
+		}
+		return lateLimits(spec, {
+			spent: context.ownSpend?.(sessionId, usage.costUsd) ?? usage.costUsd,
+			turns: usage.turns
+		}, context.budgetLeftNow?.(), quota?.leftUsd);
+	};
+	const resumeWith = (outcome, prompt, limits) => run({
+		...spec,
+		...limits,
+		resume: outcome.sessionId,
+		prompt
+	});
+	const lateTurn = (current) => {
+		const late = context.mailbox?.pending() ?? 0;
+		const limits = limitsAfter(current);
+		return late === 0 || context.signal.aborted || limits === null ? Promise.resolve(null) : resumeWith(current, lateMessage(late), limits);
+	};
+	const again = first === null || first.report === null ? null : await lateTurn(first);
+	const outcome = first === null || again === null ? first : afterLateTurn(first, again);
+	const { node } = context;
+	const verify = "verify" in node ? node.verify : void 0;
+	if (outcome === null || verify === void 0 || !isAcceptance(outcome)) return watch.result(resultOf(outcome, declaredOutputOf(node)));
+	const checked = await checkReport({
+		verify,
+		first: outcome,
+		signal: context.signal,
+		check: () => runStep(options.steps ?? noSteps, context, verify),
+		late: lateTurn,
+		resume: async (current, check) => {
+			const limits = limitsAfter(current);
+			if (limits === null) return null;
+			await context.hold?.wait("start", context.signal);
+			return context.signal.aborted ? null : resumeWith(current, checkFailedMessage(check, context), limits);
+		}
+	});
+	return watch.result(checkedResult(resultOf(checked.outcome, declaredOutputOf(node)), checked));
+};
+// ../nodes/src/gate.ts
+/**
+* @file The `human.gate` node type: asks the human the rendered question, and
+*   answers with the `default` when the `timeout` passes. The timeout counts
+*   only while the run and the gate are not paused (ADR-041).
+*/
+/** A promise that never settles: the losing side of a race. */
+const NEVER = new Promise(() => {});
+const choiceOf = (option) => {
+	if (typeof option === "string") return { id: option };
+	const choice = { id: option.id };
+	if (option.label !== void 0) choice.label = option.label;
+	if (option.description !== void 0) choice.description = option.description;
+	return choice;
+};
+/**
+* Asks the human and outputs `choice` and `answeredBy`. With `timeout`, the
+* `default` answers when no one has.
+*/
+const gateExecutor = async (context) => {
+	const { node } = context;
+	if (node.type !== "human.gate") return {
+		ok: false,
+		output: {},
+		error: `${context.id} is not a gate`
+	};
+	const template = parseTemplate(node.question);
+	const question = template.ok ? renderTemplate(template.parts, runScope(context.inputs, context.outputs, context.runId)) : node.question;
+	const options = node.options.map((o) => choiceOf(o));
+	const withdraw = new AbortController();
+	context.signal.addEventListener("abort", () => {
+		withdraw.abort();
+	});
+	const asked = {
+		nodeId: context.id,
+		question,
+		options,
+		signal: withdraw.signal
+	};
+	if (node.recommended !== void 0) asked.recommended = node.recommended;
+	const answer = context.human.ask(asked).then((choice) => ({
+		choice,
+		answeredBy: "user"
+	}));
+	const ms = timeoutMs(node.timeout);
+	const answered = new AbortController();
+	const expired = ms === void 0 || node.default === void 0 ? [] : [heldTimeout(context.hold, ms, answered.signal).then((elapsed) => {
+		if (!elapsed) return NEVER;
+		withdraw.abort();
+		return {
+			choice: node.default ?? "",
+			answeredBy: "timeout"
+		};
+	})];
+	try {
+		const output = await Promise.race([answer, ...expired]);
+		if (!options.some((o) => o.id === output.choice)) return {
+			ok: false,
+			output,
+			error: "no one answered the gate"
+		};
+		return {
+			ok: true,
+			output
+		};
+	} catch {
+		return {
+			ok: false,
+			output: {},
+			error: "the gate was withdrawn"
+		};
+	} finally {
+		answered.abort();
+	}
+};
+// ../nodes/src/mcp-call.ts
+/**
+* @file The `mcp.call` node type (RFC-006): calls one named tool on one MCP
+*   server, with no session and so no model turn. The server comes from the
+*   project's `.mcp.json` (`mcp-servers.ts`), its secrets from the user's
+*   environment. The workflow's author named the tool, so this asks for no
+*   permission, as a tool node does not.
+*/
+/** A node's `timeout:` is what limits a call; this only lifts the SDK's 60 s. */
+const NO_LIMIT_MS = 864e5;
+const failed = (error, output = {}) => ({
+	ok: false,
+	output,
+	error
+});
+/** A failure another try might not have, so a `watch:` looks again. */
+const missed = (error, output = {}) => ({
+	ok: false,
+	transient: true,
+	output,
+	error
+});
+/**
+* A string's templates rendered. A string that is one `{{ … }}` and nothing
+* else keeps its value's type, so a tool that asks for a number gets one.
+*/
+const renderValue = (value, scope) => {
+	if (typeof value === "string") {
+		const template = parseTemplate(value);
+		if (!template.ok) return value;
+		const [only, ...rest] = template.parts;
+		if (only !== void 0 && typeof only !== "string" && rest.length === 0) return evaluate(only.expr, scope);
+		return renderTemplate(template.parts, scope);
+	}
+	if (Array.isArray(value)) return value.map((item) => renderValue(item, scope));
+	if (typeof value === "object" && value !== null) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, renderValue(item, scope)]));
+	return value;
+};
+const transportFor = (server, context, environ, env) => server.kind === "stdio" ? new StdioClientTransport({
+	command: server.command,
+	args: server.args,
+	env: {
+		...withoutIdentity(environ),
+		...env,
+		...server.env
+	},
+	cwd: context.projectRoot,
+	stderr: "ignore"
+}) : new StreamableHTTPClientTransport(new URL(server.url), { requestInit: { headers: server.headers } });
+/** The text of a tool's result; what is not text is named, not dropped silently. */
+const textOf = (content) => (Array.isArray(content) ? content : []).map((part) => part.type === "text" && typeof part.text === "string" ? part.text : `[${String(part.type)} content]`).join("\n");
+/** The result as JSON, read before masking so a masked number stays valid. */
+const jsonOf = (structured, text, scrub) => {
+	try {
+		return parseScrubbed(structured === void 0 ? text : JSON.stringify(structured), scrub);
+	} catch {
+		return;
+	}
+};
+const reasonOf = (error, server) => {
+	const message = error instanceof Error ? error.message : String(error);
+	return (typeof error === "object" && error !== null && "code" in error ? error.code : void 0) === 401 || error?.constructor.name === "UnauthorizedError" ? `MCP server \`${server}\` asks for a sign-in: give it a token through headers and \`env:\`, or call it from a session` : message;
+};
+const mcpCallExecutor = (options = {}) => async (context) => {
+	const { node } = context;
+	if (node.type !== "mcp.call") return failed(`${context.id} is not an MCP call`);
+	const environ = options.environ ?? process.env;
+	const declared = readMcpServer(context.projectRoot, node.server);
+	if (!declared.ok) return failed(declared.error);
+	const nodeEnv = renderEnv(node, context, environ);
+	if (!nodeEnv.ok) return failed(nodeEnv.error);
+	const expanded = expandServer(declared.value, {
+		...environ,
+		...nodeEnv.values
+	}, node.plainEnv);
+	if (!expanded.ok) return failed(expanded.error);
+	const scrub = scrubberOf([...secretsOf(context.workflow, environ, options.maskedNames), ...expanded.value.values]);
+	const scope = runScope(context.inputs, context.outputs, context.runId);
+	const args = Object.fromEntries(Object.entries(node.arguments ?? {}).map(([key, value]) => [key, renderValue(value, scope)]));
+	const name = `${node.server}.${node.tool}`;
+	context.emit({
+		type: "tool.called",
+		id: context.id,
+		name,
+		input: { arguments: scrubbed(args, scrub) }
+	});
+	const client = new Client({
+		name: "ork",
+		version: "1"
+	});
+	try {
+		await client.connect(transportFor(expanded.value.server, context, environ, nodeEnv.values), {
+			signal: context.signal,
+			timeout: NO_LIMIT_MS
+		});
+		const result = await client.callTool({
+			name: node.tool,
+			arguments: args
+		}, void 0, {
+			signal: context.signal,
+			timeout: NO_LIMIT_MS
+		});
+		const raw = textOf(result.content);
+		const said = scrub(raw);
+		const text = capped(said, keepFile(context, "text", said));
+		const json = jsonOf(result.structuredContent, raw, scrub);
+		const tooLong = JSON.stringify(json ?? null).length > OUTPUT_LIMIT;
+		const reported = result.isError === true;
+		const problem = declaredProblem(node.output?.schema, json);
+		const output = {
+			text,
+			...json === void 0 || tooLong || problem !== null ? {} : { json }
+		};
+		context.emit({
+			type: "tool.result",
+			id: context.id,
+			isError: reported || tooLong || problem !== null
+		});
+		if (reported) return missed(`${name} failed: ${clipError(said)}`, output);
+		if (tooLong) return failed(`${name}'s result is over 64 KiB`, output);
+		return problem === null ? {
+			ok: true,
+			output
+		} : failed(problem, output);
+	} catch (error) {
+		context.emit({
+			type: "tool.result",
+			id: context.id,
+			isError: true
+		});
+		return missed(clipError(scrub(reasonOf(error, node.server))));
+	} finally {
+		await client.close().catch(() => {});
+	}
+};
+// ../nodes/src/spawn.ts
+/**
+* @file The real tool runner: `spawn` without a shell, output collected as
+*   text. A program runs in its own process group, so aborting it reaches
+*   whatever it started: SIGTERM, then SIGKILL for what ignores that. A stop or
+*   a timeout therefore leaves nothing running, and an escaped process that
+*   keeps the output pipes open cannot hold the node.
+*/
+/** How long a program may take to end after SIGTERM. */
+const KILL_AFTER_MS = 2e3;
+/** How long to wait for the pipes to close after SIGKILL. */
+const CLOSE_AFTER_MS = 500;
+const spawnTool = (program, args, { cwd, signal, env }) => {
+	if (signal.aborted) return Promise.resolve({
+		exitCode: -1,
+		stdout: "",
+		stderr: `${program} was not started: the node was stopped`
+	});
+	return new Promise((resolve) => {
+		const stdout = [];
+		const stderr = [];
+		const timers = [];
+		const child = spawn(program, args, {
+			cwd,
+			detached: true,
+			env: {
+				...withoutIdentity(process.env),
+				...env
+			},
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		const killGroup = (kill) => {
+			if (child.pid === void 0) return;
+			try {
+				process.kill(-child.pid, kill);
+			} catch {}
+		};
+		const finish = (run) => {
+			for (const timer of timers) clearTimeout(timer);
+			signal.removeEventListener("abort", abort);
+			resolve(run);
+		};
+		const collected = (exitCode) => ({
+			exitCode,
+			stdout: stdout.join(""),
+			stderr: stderr.join("")
+		});
+		const abort = () => {
+			killGroup("SIGTERM");
+			timers.push(setTimeout(() => {
+				killGroup("SIGKILL");
+				timers.push(setTimeout(() => {
+					finish(collected(-1));
+				}, CLOSE_AFTER_MS));
+			}, KILL_AFTER_MS));
+		};
+		signal.addEventListener("abort", abort, { once: true });
+		child.stdout.setEncoding("utf8").on("data", (chunk) => {
+			stdout.push(chunk);
+		});
+		child.stderr.setEncoding("utf8").on("data", (chunk) => {
+			stderr.push(chunk);
+		});
+		child.on("error", (error) => {
+			finish({
+				exitCode: -1,
+				stdout: stdout.join(""),
+				stderr: `could not run ${program}: ${error.message}`
+			});
+		});
+		child.on("close", (code) => {
+			finish(collected(code ?? -1));
+		});
+	});
+};
+// ../nodes/src/builtins.ts
+/** Every built-in node type that does work; control nodes are the scheduler's. */
+const builtinExecutors = (options) => {
+	const tool = toolExecutor(options.tools ?? spawnTool, {
+		...options.orkBin === void 0 ? {} : { orkBin: options.orkBin },
+		...options.maskedNames === void 0 ? {} : { maskedNames: options.maskedNames }
+	});
+	const claude = claudeExecutor({
+		...options,
+		steps: tool
+	});
+	const executors = {
+		"claude.leader": claude,
+		"claude.worker": claude,
+		"human.gate": gateExecutor,
+		"workflow.call": callExecutor,
+		"mcp.call": mcpCallExecutor(options.maskedNames === void 0 ? {} : { maskedNames: options.maskedNames })
+	};
+	for (const integration of INTEGRATIONS) executors[`${TOOL_PREFIX}${integration.id}`] = tool;
+	return executors;
+};
+// ../nodes/src/programs.ts
+/**
+* @file Which programs a workflow's tool nodes run, and which of them are not
+*   installed. Integrations are optional: `ork run` checks only the programs
+*   the workflow uses, before anything starts.
+*/
+const isRelativePath = (program) => program.includes(path.sep) && !path.isAbsolute(program);
+/**
+* The programs the workflow's tool nodes run: an integration's own (`gh`,
+* `aws`), or the first word of a `tool.shell` command or interpreter, when it
+* is not a template. A relative path is not asked about: it means a node's
+* checkout, where a `before:` or an earlier node may yet make it.
+*/
+const neededPrograms = (workflow) => Object.entries(workflow.nodes).flatMap(([id, node]) => programsRunBy(node, workflow.defaults).flatMap(({ program }) => {
+	const type = isToolNode(node) ? node.type : "tool.shell";
+	const integration = integrationFor(type);
+	if (integration === void 0) return [];
+	if (integration.program !== null) return [{
+		node: id,
+		type,
+		program: integration.program
+	}];
+	const tokens = tokenize(commandLineOf(program) ?? "");
+	const first = tokens.ok ? tokens.args[0] : void 0;
+	return first === void 0 || first.includes("{{") || isRelativePath(first) ? [] : [{
+		node: id,
+		type,
+		program: first
+	}];
+}));
+/** The `{{env.NAME}}` a workflow reads that are not set, with their nodes. */
+const missingEnv = (workflow, environ = process.env, finished = /* @__PURE__ */ new Set()) => {
+	const missing = /* @__PURE__ */ new Map();
+	for (const [id, node] of Object.entries(workflow.nodes)) {
+		if (finished.has(id)) continue;
+		const values = programsRunBy(node, workflow.defaults).flatMap(({ program }) => Object.values(program.env ?? {}));
+		for (const value of values) for (const name of envReadsOf(value)) {
+			if (readEnv(environ, name) !== void 0) continue;
+			missing.set(name, (missing.get(name) ?? /* @__PURE__ */ new Set()).add(id));
+		}
+	}
+	return [...missing].map(([variable, nodes]) => ({
+		variable,
+		nodes: [...nodes]
+	}));
+};
+/** The nodes a resumed run hands back rather than runs: their last go worked. */
+const finishedOf = (history) => new Set([...history].filter(([, results]) => results.at(-1)?.ok === true).map(([id]) => id));
+/**
+* What a workflow this run may call reads and is not set. Whether a call runs
+* is often only known at run time, so this warns; the call fails if reached. A
+* call a resumed run already finished is not asked about.
+*/
+const calledEnvWarning = (workflow, own, registered, history = /* @__PURE__ */ new Map(), environ = process.env) => {
+	const merged = /* @__PURE__ */ new Map();
+	const unreadable = [];
+	for (const called of calledWorkflows(workflow, own, registered, {
+		finished: finishedOf(history),
+		unreadable: (name) => {
+			unreadable.push(name);
+		}
+	})) for (const { variable, nodes } of missingEnv(called, environ)) {
+		const seen = merged.get(variable) ?? /* @__PURE__ */ new Set();
+		for (const node of nodes) seen.add(`${called.name}/${node}`);
+		merged.set(variable, seen);
+	}
+	return [...merged.size === 0 ? [] : [
+		"A workflow this run may call reads variables that are not set:",
+		...[...merged].map(([variable, nodes]) => `  ${variable}, for ${[...nodes].join(", ")}`),
+		"That call fails if the run reaches it."
+	], ...unreadable.length === 0 ? [] : [`Could not read ${unreadable.join(", ")}, which this run may call, so what ${unreadable.length === 1 ? "it reads" : "they read"} is neither checked nor masked.`]];
+};
+/** Why a run refuses to start when a variable its nodes read is not set. */
+const missingEnvMessage = (missing) => [
+	"This workflow reads environment variables that are not set:",
+	...missing.map((m) => `  ${m.variable}, for ${m.nodes.join(", ")}`),
+	"Set them, and run it again."
+];
+/** Why a run refuses to start when a program its tool nodes need is missing. */
+const missingProgramMessage = (missing) => [
+	"This workflow runs programs that are not installed:",
+	...missing.map((m) => `  ${m.program}, for ${m.nodes.join(", ")} (${m.type})`),
+	"Install them, or take those nodes out. Integrations are optional: only the ones a workflow uses must be installed (`ork doctor` shows what you have)."
+];
+/**
+* What stops this run for want of a variable, as lines to print; what only
+* might stop it goes to `warn`.
+*/
+const envProblems = (workflow, own, registered, history, warn) => {
+	const unset = missingEnv(workflow, process.env, finishedOf(history ?? /* @__PURE__ */ new Map()));
+	if (unset.length > 0) return missingEnvMessage(unset);
+	const servers = mcpProblems(workflow, own.root, process.env, finishedOf(history ?? /* @__PURE__ */ new Map()), (program) => isRelativePath(program) || onPath(program));
+	if (servers.length > 0) return servers;
+	for (const line of calledEnvWarning(workflow, own, registered, history)) warn(line);
+	return [];
+};
+const runnable = (file) => {
+	try {
+		accessSync(file, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+};
+/** Whether `program` runs: a path that is executable, or a name on `PATH`. */
+const onPath = (program, env = process.env) => {
+	if (program.includes(path.sep)) return runnable(program);
+	return (env["PATH"] ?? "").split(path.delimiter).filter((dir) => dir !== "").some((dir) => runnable(path.join(dir, program)));
+};
+/** The needed programs that are not installed, one entry per program. */
+const missingPrograms = (workflow, installed = (program) => onPath(program)) => {
+	const missing = /* @__PURE__ */ new Map();
+	for (const need of neededPrograms(workflow)) {
+		if (installed(need.program)) continue;
+		const entry = missing.get(need.program) ?? {
+			program: need.program,
+			nodes: [],
+			type: need.type
+		};
+		entry.nodes.push(need.node);
+		missing.set(need.program, entry);
+	}
+	return [...missing.values()];
+};
+export { resultOf as _, builtinExecutors as a, toolExecutor as c, maskedEnv as d, maskedNamesOfRun as f, clearOutputFiles as g, sessionEnv as h, onPath as i, clearStateFiles as l, runScrubber as m, missingProgramMessage as n, spawnTool as o, runMarkerIn as p, missingPrograms as r, mcpCallExecutor as s, envProblems as t, inheritedScrubber as u };