@krapht/ork 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/{run-CQIfq918.mjs → run-CiPsW9Kf.mjs}

@@ -1,4 +1,4 @@
-import { Rt as git, zt as gitOk } from "./src-BeR6f70A.mjs";
+import { Jt as gitOk, qt as git } from "./src-Dr_fTSu-.mjs";
 import path from "node:path";
 import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";

package/dist/send-CnNNW-ot.mjs

@@ -0,0 +1,105 @@
+import { U as openStore, at as scriptRefusal, it as TOO_LONG, ot as sendFromScript } from "./src-Dr_fTSu-.mjs";
+import { l as writeErr } from "./output-B1kwo0YU.mjs";
+import { u as inheritedScrubber } from "./src-DcrhgipG.mjs";
+import { defineCommand } from "citty";
+// src/commands/send.ts
+/**
+* @file `ork send` (RFC-005): a program in a tool node writes to a session on
+*   its run's bus. It prints nothing when it works, as what a program prints is
+*   its node's output, and says why on stderr, with exit 1, when it is refused:
+*   before reading a message it could not send, and for anything wrong with the
+*   command itself, which would otherwise go to stdout as usage.
+*/
+const refuse = (message) => {
+	writeErr(message);
+	process.exitCode = 1;
+};
+/** Stdin, up to the limit: past it, the rest is not worth holding. */
+const readBounded = async () => {
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of process.stdin) {
+		const part = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+		size += part.length;
+		if (size > 65536) return null;
+		chunks.push(part);
+	}
+	return Buffer.concat(chunks);
+};
+/** The message, or why it can't go. */
+const bodyOf = async (given) => {
+	if (given !== void 0) return { body: given };
+	const read = await readBounded();
+	if (read === null) return { refused: TOO_LONG };
+	try {
+		return { body: new TextDecoder("utf-8", { fatal: true }).decode(read) };
+	} catch {
+		return { refused: "The message is not UTF-8 text." };
+	}
+};
+const deliver = async (store, to, given) => {
+	const sender = {
+		run: process.env["ORK_RUN"],
+		node: process.env["ORK_NODE"],
+		to
+	};
+	const refused = scriptRefusal(store, sender);
+	if (refused !== null) {
+		refuse(refused);
+		return;
+	}
+	const message = await bodyOf(given);
+	if ("refused" in message) {
+		refuse(message.refused);
+		return;
+	}
+	if (message.body.replaceAll(/[\p{Cc}\s]/gu, "") === "") {
+		refuse("The message is empty.");
+		return;
+	}
+	const sent = await sendFromScript(store, {
+		...sender,
+		body: inheritedScrubber(process.env)(message.body)
+	});
+	if (!sent.ok) refuse(sent.error);
+};
+const send = defineCommand({
+	meta: {
+		name: "send",
+		description: "From a tool node's program: write to a session in its run"
+	},
+	args: {
+		to: {
+			type: "positional",
+			description: "The node to write to: the owner, or a channel",
+			required: false
+		},
+		message: {
+			type: "string",
+			alias: "m",
+			description: "The message"
+		},
+		stdin: {
+			type: "boolean",
+			description: "Read the message from stdin",
+			default: false
+		}
+	},
+	run: async ({ args }) => {
+		if (args.to === void 0 || args._.length !== 1) {
+			refuse("Give one node to write to: ork send <to> -m <body>.");
+			return;
+		}
+		if (args.message === void 0 === !args.stdin) {
+			refuse("Give the message with -m or --stdin, one of them.");
+			return;
+		}
+		const store = openStore();
+		try {
+			await deliver(store, args.to, args.message);
+		} finally {
+			store.close();
+		}
+	}
+});
+export { send };

package/dist/{src-CqRqsb2t.mjs → src-B9zWIVqo.mjs}

@@ -1,4 +1,5 @@
-import { En as MASK, It as lowerChild, Lt as startAt, Nr as AGENT_DRIVERS, On as maskSecrets, an as endFor, cn as FEEDBACK_TARGETS, ct as parseReport, in as END_KINDS, nn as outcomeEnd, on as FEEDBACK_KINDS, sn as FEEDBACK_SEVERITIES } from "./src-BeR6f70A.mjs";
+import { Bn as outcomeEnd, Et as parseReport, Gn as FEEDBACK_SEVERITIES, Gt as programFound, Hn as END_KINDS, Kn as FEEDBACK_TARGETS, Kt as startAt, Nn as countedTokens, Un as endFor, Wn as FEEDBACK_KINDS, Wt as lowerChild, _i as AGENT_DRIVERS, fr as maskSecrets, ur as MASK } from "./src-Dr_fTSu-.mjs";
+import { n as holdGuard, r as orphanGuard } from "./orphan-guard-BFKg8VSd.mjs";
 import path from "node:path";
 import { z } from "zod";
 import { existsSync, linkSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
@@ -8,6 +9,13 @@ import { createInterface } from "node:readline";
 import { execFile, spawn } from "node:child_process";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { createServer } from "node:http";
+// ../core/src/follow-ups/types.ts
+const FOLLOW_UP_KINDS = [
+	"change",
+	"message",
+	"task",
+	"check"
+];
 // ../runtime/src/hold.ts
 /**
 * Waits at a tool call while `hold` is held: "go" once it is released within
@@ -448,7 +456,8 @@ const classifyProviderError = (text, status) => {
 *   it can see (a turn cap, an exit code, a provider's error), and the report
 *   the session handed in decides the rest. The runner then writes the end in
 *   the node's numbers, its detail scrubbed with the feedback redactor. A
-*   session the driver could not run ends as `driverFailure` says.
+*   session the driver could not run ends as `driverFailure` says, and one that
+*   reached its token cap as `tokenCapOutcome` says.
 */
 /** The end a report gives: done, a reported failure, or none handed in. */
 const reportEnd = (report) => {
@@ -479,6 +488,36 @@ const settleEnd = (outcome, facts, scrub) => {
 	};
 };
 /**
+* What a session's end is written with: the node's limits and program, and its
+* folder and the home folder taken out of the detail.
+*/
+const scopeOf = (spec, bin, env) => ({
+	facts: {
+		...spec.maxTurns === void 0 ? {} : { maxTurns: spec.maxTurns },
+		...spec.budgetUsd === void 0 ? {} : { budgetUsd: spec.budgetUsd },
+		...spec.budgetTokens === void 0 ? {} : { budgetTokens: spec.budgetTokens },
+		program: path.basename(bin)
+	},
+	scrub: {
+		roots: [spec.cwd],
+		home: env["HOME"] ?? homedir()
+	}
+});
+/**
+* The outcome of a session stopped once its counted tokens (RFC-015) reach
+* `budgetTokens`: `budget_limit`, with what it used so far; `undefined` under
+* the cap, or with none.
+*/
+const tokenCapOutcome = ({ budgetTokens }, usage, sessionId) => budgetTokens === void 0 || usage === void 0 || countedTokens(usage) < budgetTokens ? void 0 : {
+	subtype: "error_max_budget_tokens",
+	end: endFor("budget_limit"),
+	sessionId,
+	report: null,
+	text: "",
+	usage,
+	errors: [`Reached the token budget (${String(budgetTokens)})`]
+};
+/**
 * The kind of a failure to run the driver: its program missing, else what a
 * provider's words in it say, else a crash.
 */
@@ -512,13 +551,62 @@ const driverFailure = (message, kind, scope) => ({
 		errors: [message]
 	}
 });
+// ../runtime/src/leg-spawn.ts
+/**
+* @file Starting one process (leg) of a session: at the project's priority, and
+*   off Windows in its own process group beside the orphan guard, so it and
+*   what it started end with `ork`, whatever ends `ork`. The process's pid, and
+*   the SIGINT that stops it, stay the driver's own.
+*/
+/** The fd of the orphan guard's pipe from `ork`. */
+const WATCH_FD = 3;
+/**
+* Starts the orphan guard, then becomes the driver. The pipe is closed by a
+* bare `exec`: macOS's `sh` keeps a copy of a descriptor an `exec` command
+* closes, which the driver and its leftovers would then inherit.
+*/
+const GUARDED = `${orphanGuard(WATCH_FD)}exec ${String(WATCH_FD)}<&-; exec "$0" "$@"`;
+const piped = (child) => child.stdin !== null && child.stdout !== null && child.stderr !== null;
+/**
+* Spawns the leg's process. A program that isn't there is spawned bare, so it
+* fails as spawn's ENOENT; the guard is released once the driver exits, so a
+* session that ends normally leaves its leftovers alone.
+*/
+const spawnLeg = (start) => {
+	const [bin, args] = startAt(start.priority, start.bin, start.args, start.env);
+	const guarded = process.platform !== "win32" && programFound(start.bin, start.env);
+	const child = spawn(guarded ? "/bin/sh" : bin, guarded ? [
+		"-c",
+		GUARDED,
+		bin,
+		...args
+	] : args, {
+		cwd: start.cwd,
+		detached: guarded,
+		env: { ...start.env },
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe",
+			guarded ? "pipe" : "ignore"
+		]
+	});
+	if (!piped(child)) throw new Error(`${start.bin} was started without pipes`);
+	if (guarded) {
+		const release = holdGuard(child.stdio[WATCH_FD]);
+		child.once("exit", release);
+	}
+	return child;
+};
 // ../runtime/src/session-leg.ts
 /**
 * @file One process (leg) of a session the runner drives: it writes the queued
 *   stdin lines, yields the adapter's decoded events, and says how it ended. A
 *   session is one leg, or several when a paused node's tool call was deferred
 *   or a message waits for a tool that takes none mid-session; a resumed leg
-*   carries what the legs before it spent, and its start is not news.
+*   carries what the legs before it spent, and its start is not news. Off
+*   Windows the process ends with `ork`, whatever ends `ork` (the orphan
+*   guard).
 */
 const REASON_LIMIT = 500;
 /** Marks a session's start with the driver that runs it. */
@@ -534,6 +622,15 @@ const settled = (outcome, input) => settleEnd(input.reported === void 0 ? outcom
 	...outcome,
 	report: input.reported()
 }, input.scope.facts, input.scope.scrub);
+/** The session's end at its token cap, its earlier legs' usage included. */
+const tokenCapEnd = (input, used, sessionId) => {
+	const usage = used === void 0 || input.carried === void 0 ? used : input.adapter.usage.combine(input.carried, used);
+	const capped = tokenCapOutcome(input.scope.facts, usage, sessionId);
+	return capped === void 0 ? void 0 : {
+		type: "session.finished",
+		outcome: settled(capped, input)
+	};
+};
 /** The kinds of a session that ended well, so a queued message continues it. */
 const wentWell = (kind) => kind === "done" || kind === "reported_failure" || kind === "no_report";
 /**
@@ -598,16 +695,7 @@ const failureReason = (name, stderr, code) => {
 };
 /** Runs one process of a session, yielding its events; returns how it ended. */
 const runLeg = async function* (input) {
-	const [bin, args] = startAt(input.priority, input.bin, input.args, input.env);
-	const child = spawn(bin, args, {
-		cwd: input.cwd,
-		env: { ...input.env },
-		stdio: [
-			"pipe",
-			"pipe",
-			"pipe"
-		]
-	});
+	const child = spawnLeg(input);
 	lowerChild(input.priority, child.pid);
 	const exited = new Promise((resolve) => {
 		child.on("close", (code, signal) => {
@@ -639,16 +727,26 @@ const runLeg = async function* (input) {
 	for (const line of input.pending.splice(0)) write(line);
 	if (input.adapter.command.input === void 0) child.stdin.end();
 	let outcome;
+	let sessionId = "";
 	const { decoder } = input;
 	const decode = decoder?.decode ?? input.adapter.decode;
 	try {
 		for await (const line of createInterface({ input: child.stdout })) {
-			const { events, ended } = legStep(decode(line), input);
+			const decoded = decode(line);
+			const { events, ended } = legStep(decoded, input);
+			for (const event of decoded.events) if (event.type === "session.started") sessionId = event.sessionId;
 			yield* events;
 			if (ended !== void 0) {
 				child.stdin.end();
 				outcome = ended;
 			}
+			const capped = outcome === void 0 ? tokenCapEnd(input, decoded.usage, sessionId) : void 0;
+			if (capped !== void 0) {
+				stopped = true;
+				child.kill("SIGINT");
+				yield capped;
+				return { kind: "finished" };
+			}
 		}
 		const end = await Promise.race([exited, spawnError.then((error) => error)]);
 		if (outcome !== void 0) return outcome;
@@ -834,6 +932,74 @@ const feedbackTool = defineTool({
 		return Promise.resolve(text(sent.ok ? "Recorded. Thank you; carry on with your task." : `Not recorded: ${sent.error}.`));
 	}
 });
+// ../runtime/src/tools/follow-up.ts
+/**
+* @file `follow_up`: a session's way to leave work the change leaves for later
+*   (a change for a later run, a note for another project, a message a person
+*   must send, a task or a check for the maintainer). Ork keeps it where the
+*   project's `followUps` rule says, merges duplicates, caps it per session,
+*   and never sends or runs anything on its own.
+*/
+const isFor = (value) => /^(?:agent|me|project:\S.*|person:\S.*)$/u.test(value);
+const isDue = (value) => /^(?:now|after-merge|after-deploy|\d{4}-\d{2}-\d{2})$/u.test(value);
+const followUpTool = defineTool({
+	name: "follow_up",
+	description: "Leave work this change leaves for later and that is not yours to do now: a change for a later run (for: agent), something for another registered project (for: project:<name>), a message a person must get (for: person:<name>, kind: message, with a draft), or a task or check for the maintainer (for: me, with steps). Ork keeps it, merges duplicates, and sends or runs nothing itself. Not for problems with Ork or the workflow (use feedback), nor for what you can finish now.",
+	shape: {
+		title: z.string().min(1).max(200).describe("One line."),
+		body: z.string().max(4e3).optional().describe("What and why, briefly."),
+		for: z.string().refine(isFor, "agent, me, project:<name> or person:<name>").describe("Who acts: agent, me, project:<name> or person:<name>."),
+		kind: z.enum(FOLLOW_UP_KINDS),
+		due: z.string().refine(isDue, "now, after-merge, after-deploy or YYYY-MM-DD").describe("now, after-merge, after-deploy, or a YYYY-MM-DD date."),
+		where: z.array(z.string()).max(20).optional().describe("Files it is about, relative to the project root."),
+		ref: z.string().min(1).optional().describe("The pull request or branch an after-merge follow-up waits on, when you know it."),
+		draft: z.strictObject({
+			to: z.string().min(1),
+			channel: z.string().optional().describe("github (to: an issue or PR URL), email, slack… A hint for the maintainer."),
+			text: z.string().min(1).max(4e3)
+		}).optional().describe("For a message: what the maintainer will send."),
+		steps: z.array(z.strictObject({
+			text: z.string().min(1),
+			command: z.string().optional().describe("Shown to the maintainer to copy; Ork never runs it.")
+		})).max(20).optional().describe("For a task or check: what to do, in order.")
+	},
+	available: ({ ports }) => ports.followUps !== void 0,
+	run: async ({ ports }, args) => {
+		const port = ports.followUps;
+		if (port === void 0) return text("No follow-ups here.");
+		if (!isFor(args.for) || !isDue(args.due)) return text("Not kept.");
+		const input = {
+			title: args.title,
+			for: args.for,
+			kind: args.kind,
+			due: args.due,
+			...args.body === void 0 ? {} : { body: args.body },
+			...args.where === void 0 ? {} : { where: args.where },
+			...args.ref === void 0 ? {} : { ref: args.ref },
+			...args.draft === void 0 ? {} : { draft: {
+				to: args.draft.to,
+				text: args.draft.text,
+				...args.draft.channel === void 0 ? {} : { channel: args.draft.channel }
+			} },
+			...args.steps === void 0 ? {} : { steps: args.steps.map((step) => ({
+				text: step.text,
+				...step.command === void 0 ? {} : { command: step.command }
+			})) }
+		};
+		const result = await port.add(input);
+		if (!result.ok) return {
+			...text(`Not kept: ${result.error}.`),
+			isError: true
+		};
+		const { followUp, merged, note } = result.added;
+		return text([
+			merged ? `Merged into follow-up ${followUp.id}, which was already kept.` : `Kept as follow-up ${followUp.id}.`,
+			...note === void 0 ? [] : [note],
+			...result.relayed === void 0 ? [] : [`Also sent to ${result.relayed.run}/${result.relayed.node}, a live run of that project.`],
+			"Carry on with your task."
+		].join(" "));
+	}
+});
 // ../runtime/src/tools/input.ts
 /**
 * @file `read_input`: what the workflow sent a node back with, whole. A loop's
@@ -1024,6 +1190,7 @@ const ORK_TOOLS = [
 	claimTool,
 	releaseTool,
 	feedbackTool,
+	followUpTool,
 	{
 		name: REPORT_TOOL$1,
 		bind: (context) => context.report === void 0 || checksItsReport(context.driver) ? null : bound(context.report)
@@ -1034,33 +1201,6 @@ const orkTools = (context) => ORK_TOOLS.flatMap((tool) => tool.bind(context) ??
 /** Their Claude Code names, for the session's allowed tools. */
 const preapprovedTools = (tools) => tools.filter((t) => t.preapproved).map((t) => toolId(t.name));
 // ../runtime/src/session-runner.ts
-/**
-* @file The session runner: one agent CLI session, driven through an adapter's
-*   strategies (`adapter.ts`), written once for every driver. It serves Ork's
-*   tools on a local MCP endpoint, wires the session to it, and runs the tool
-*   as one or more processes (legs). A paused node's tool call is held, and
-*   past the hold window deferred; the next leg resumes the session once the
-*   node continues (ADR-041). A tool that takes no message mid-session gets one
-*   at the next leg, which resumes the session with it. A driver that cannot
-*   hold the final answer to the report schema gets Ork's `report` tool, and
-*   the session ends with the report it accepted. Interrupting stops the
-*   running process.
-*/
-/**
-* What a session's end is written with: the node's limits and program, and its
-* folder and the home folder taken out of the detail.
-*/
-const scopeOf = (spec, bin, env) => ({
-	facts: {
-		...spec.maxTurns === void 0 ? {} : { maxTurns: spec.maxTurns },
-		...spec.budgetUsd === void 0 ? {} : { budgetUsd: spec.budgetUsd },
-		program: path.basename(bin)
-	},
-	scrub: {
-		roots: [spec.cwd],
-		home: env["HOME"] ?? homedir()
-	}
-});
 /** A spec that resumes `sessionId`; a fork's later legs continue the fork. */
 const resumed = (spec, sessionId) => ({
 	...spec,
@@ -1391,9 +1531,23 @@ const REPORT_TOOL = "StructuredOutput";
 const claudeDecoder = () => {
 	const calls = /* @__PURE__ */ new Map();
 	let accepted;
+	/** Each model response's usage, by message id: its blocks repeat it. */
+	const responses = /* @__PURE__ */ new Map();
+	/** The leg's usage so far, when `message` is a model response. */
+	const usageSoFar = (message) => {
+		const inner = get$1(message, "message");
+		const id = get$1(inner, "id");
+		if (get$1(message, "type") !== "assistant" || typeof id !== "string") return;
+		responses.set(id, {
+			...usageOf({ usage: get$1(inner, "usage") }),
+			turns: 1
+		});
+		return [...responses.values()].reduce((a, b) => addUsage(a, b));
+	};
 	return {
 		decode: (line) => {
 			const message = parseLine$2(line);
+			const usage = usageSoFar(message);
 			for (const block of blocks(message)) {
 				if (block["type"] === "tool_use" && block["name"] === REPORT_TOOL) calls.set(str$2(block["id"]), block["input"]);
 				const id = str$2(block["tool_use_id"]);
@@ -1408,7 +1562,8 @@ const claudeDecoder = () => {
 			} : message;
 			return {
 				events: normalize(kept),
-				deferred: isDeferredResult(message)
+				deferred: isDeferredResult(message),
+				...usage === void 0 ? {} : { usage }
 			};
 		},
 		exit: () => []
@@ -1941,6 +2096,26 @@ const commandCodeDecoder = () => {
 	let sessionId = "";
 	let turns = 0;
 	let held;
+	/** The leg's tokens so far, from each `model_request_end` frame. */
+	let used;
+	/** A model request's usage, added to the leg's so far. */
+	const requestEnded = (usage) => {
+		const said = isObject$1(usage) ? usage : {};
+		const own = {
+			costUsd: 0,
+			inputTokens: num$1(said["inputTokens"]),
+			outputTokens: num$1(said["outputTokens"]),
+			cacheReadTokens: num$1(said["cacheReadTokens"]),
+			cacheWriteTokens: num$1(said["cacheWriteTokens"]),
+			turns,
+			durationMs: 0
+		};
+		used = used === void 0 ? own : {
+			...addUsage(used, own),
+			turns
+		};
+		return used;
+	};
 	const frame = (event) => {
 		const type = event["type"];
 		const id = str$1(event["toolCallId"]);
@@ -2017,7 +2192,11 @@ const commandCodeDecoder = () => {
 				return { events: [] };
 			}
 			const event = message["event"];
-			return { events: message["type"] === "event" && isObject$1(event) ? frame(event) : [] };
+			if (message["type"] !== "event" || !isObject$1(event)) return { events: [] };
+			return {
+				events: frame(event),
+				...event["type"] === "model_request_end" ? { usage: requestEnded(event["usage"]) } : {}
+			};
 		},
 		exit: (code) => {
 			if (held !== void 0) return [result(held, code)];
@@ -2584,7 +2763,10 @@ const openCodeDecoder = (spec) => {
 			switch (message["type"]) {
 				case "step_finish":
 					usage = sumUsage(usage, stepUsage(message["part"]));
-					break;
+					return {
+						events,
+						usage
+					};
 				case "error":
 					errors.push(errorText(message["error"]));
 					failed ??= errorLineEnd(message["error"]);