@krapht/ork 1.0.0-alpha.14 → 1.0.0-alpha.16

package/dist/{run-D8divGCs.mjs → run-D_u9V_Ve.mjs}

@@ -1,4 +1,4 @@
-import { dn as git, fn as gitOk } from "./src-tsuZRu0H.mjs";
+import { $t as gitOk, Qt as git } from "./src-DN-RPsil.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-CXv8bx0i.mjs → send-qBxj0JbJ.mjs}

@@ -1,6 +1,6 @@
-import { U as openStore, at as scriptRefusal, it as TOO_LONG, ot as sendFromScript } from "./src-tsuZRu0H.mjs";
+import { $ as sendFromScript, L as openStore, Q as scriptRefusal, Z as TOO_LONG } from "./src-DN-RPsil.mjs";
 import { l as writeErr } from "./output-B1kwo0YU.mjs";
-import { u as inheritedScrubber } from "./src-C7z_6fhn.mjs";
+import { u as inheritedScrubber } from "./src-DHDQ0itC.mjs";
 import { defineCommand } from "citty";
 // src/commands/send.ts
 /**

package/dist/{src-njdtejgZ.mjs → src-CXBmaGwS.mjs}

@@ -1,4 +1,5 @@
-import { $n as maskSecrets, $t as countedTokens, An as END_KINDS, Mn as FEEDBACK_KINDS, Nn as FEEDBACK_SEVERITIES, On as outcomeEnd, Pn as FEEDBACK_TARGETS, Pt as parseReport, Zn as MASK, ii as AGENT_DRIVERS, jn as endFor, ln as lowerChild, un as startAt } from "./src-tsuZRu0H.mjs";
+import { It as lowerChild, Jn as END_KINDS, Kn as outcomeEnd, Lt as programFound, Qn as FEEDBACK_TARGETS, Rt as startAt, Xn as FEEDBACK_KINDS, Yn as endFor, Zn as FEEDBACK_SEVERITIES, gr as MASK, un as FOLLOW_UP_KINDS, vr as maskSecrets, vt as parseReport, wi as AGENT_DRIVERS, zn as countedTokens } from "./src-DN-RPsil.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";
@@ -448,8 +449,10 @@ 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, and one that
-*   reached its token cap as `tokenCapOutcome` says.
+*   session the driver could not run (or that was stopped, with what it had
+*   spent) ends as `driverFailure` says, one whose process died as
+*   `failureReason` explains, 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) => {
@@ -474,9 +477,15 @@ const errorEnd = (text, fallback = "unknown", status) => endFor(classifyProvider
 */
 const settleEnd = (outcome, facts, scrub) => {
 	const end = outcome.report === null ? outcome.end ?? outcomeEnd(outcome) : reportEnd(outcome.report);
+	const { usage } = outcome;
+	const used = {
+		...facts,
+		usedTokens: countedTokens(usage),
+		...usage.costUsd > 0 ? { usedUsd: usage.costUsd } : {}
+	};
 	return {
 		...outcome,
-		end: endFor(end.kind, facts, end.detail, scrub)
+		end: endFor(end.kind, used, end.detail, scrub)
 	};
 };
 /**
@@ -509,6 +518,17 @@ const tokenCapOutcome = ({ budgetTokens }, usage, sessionId) => budgetTokens ===
 	usage,
 	errors: [`Reached the token budget (${String(budgetTokens)})`]
 };
+const REASON_LIMIT = 500;
+/** Noise a Node crash ends stderr with, or a stack frame: never the reason. */
+const isNoise = (line) => /^Node\.js v\d/u.test(line) || /^\s+at /u.test(line);
+/**
+* Why a process ended without a result: the last block of its stderr as one
+* masked, capped line (the reason reaches the terminal, which is not masked).
+*/
+const failureReason = (name, stderr, code) => {
+	const block = stderr.split("\n").filter((line) => !isNoise(line)).join("\n").split(/\n\s*\n/u).map((text) => text.trim().replaceAll(/\s*\n\s*/gu, " ")).findLast((text) => text !== "");
+	return block === void 0 ? `${name} exited with code ${String(code)}` : maskSecrets(block).slice(0, REASON_LIMIT);
+};
 /**
 * The kind of a failure to run the driver: its program missing, else what a
 * provider's words in it say, else a crash.
@@ -519,39 +539,92 @@ const failureKind = (error) => {
 	if (/\bENOENT\b/u.test(text)) return "tool_missing";
 	return classifyProviderError(text)?.kind ?? "driver_crashed";
 };
+const NOTHING_SPENT = {
+	usage: {
+		costUsd: 0,
+		inputTokens: 0,
+		outputTokens: 0,
+		cacheReadTokens: 0,
+		cacheWriteTokens: 0,
+		turns: 0,
+		durationMs: 0
+	},
+	sessionId: ""
+};
 /**
 * A finished event for a session the driver could not run, ended as `kind` with
-* `message` (Ork's words or the tool's, masked) as its detail.
+* `message` (Ork's words or the tool's, masked) as its detail; a stopped one
+* keeps what it had `spent` (its tokens decoded so far, dollars $0).
 */
-const driverFailure = (message, kind, scope) => ({
+const driverFailure = (message, kind, scope, spent = NOTHING_SPENT) => ({
 	type: "session.finished",
 	outcome: {
 		subtype: "error_driver",
 		end: endFor(kind, scope.facts, kind === "interrupted" ? void 0 : message, scope.scrub),
-		sessionId: "",
+		sessionId: spent.sessionId,
 		report: null,
 		text: "",
-		usage: {
-			costUsd: 0,
-			inputTokens: 0,
-			outputTokens: 0,
-			cacheReadTokens: 0,
-			cacheWriteTokens: 0,
-			turns: 0,
-			durationMs: 0
-		},
+		usage: spent.usage,
 		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. */
 const withDriver = (event, driver) => event.type === "session.started" ? {
 	...event,
@@ -565,10 +638,11 @@ const settled = (outcome, input) => settleEnd(input.reported === void 0 ? outcom
 	...outcome,
 	report: input.reported()
 }, input.scope.facts, input.scope.scrub);
+/** What this leg `used`, with what the legs before it spent. */
+const withCarried = (input, used) => used === void 0 || input.carried === void 0 ? used ?? input.carried : input.adapter.usage.combine(input.carried, used);
 /** 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);
+	const capped = tokenCapOutcome(input.scope.facts, used === void 0 ? void 0 : withCarried(input, used), sessionId);
 	return capped === void 0 ? void 0 : {
 		type: "session.finished",
 		outcome: settled(capped, input)
@@ -588,37 +662,36 @@ const legStep = (decoded, input) => {
 	const events = [];
 	let ended;
 	for (const said of decoded.events) {
-		const event = said.type === "session.finished" ? {
+		if (said.type === "session.started" && carried !== void 0) continue;
+		if (said.type !== "session.finished") {
+			events.push(withDriver(said, adapter.driver));
+			continue;
+		}
+		const own = said.outcome.usage;
+		const usage = carried === void 0 ? own : adapter.usage.combine(carried, own);
+		const last = {
 			...said,
-			outcome: settled(said.outcome, input)
-		} : said;
-		if (event.type === "session.started" && carried !== void 0) continue;
-		if (event.type !== "session.finished") events.push(withDriver(event, adapter.driver));
-		else if (deferred) ended = {
+			outcome: settled({
+				...said.outcome,
+				usage
+			}, input)
+		};
+		const { sessionId, end } = last.outcome;
+		if (deferred) ended = {
 			kind: "deferred",
-			sessionId: event.outcome.sessionId,
-			usage: event.outcome.usage,
-			last: event
+			sessionId,
+			usage: own,
+			last
+		};
+		else if (input.withhold() && wentWell(end?.kind)) ended = {
+			kind: "continued",
+			sessionId,
+			usage: own,
+			last
 		};
 		else {
-			const usage = carried === void 0 ? event.outcome.usage : adapter.usage.combine(carried, event.outcome.usage);
-			const last = {
-				...event,
-				outcome: {
-					...event.outcome,
-					usage
-				}
-			};
-			if (input.withhold() && wentWell(event.outcome.end?.kind)) ended = {
-				kind: "continued",
-				sessionId: event.outcome.sessionId,
-				usage: event.outcome.usage,
-				last
-			};
-			else {
-				events.push(last);
-				ended = { kind: "finished" };
-			}
+			events.push(last);
+			ended = { kind: "finished" };
 		}
 	}
 	return ended === void 0 ? { events } : {
@@ -626,28 +699,9 @@ const legStep = (decoded, input) => {
 		ended
 	};
 };
-/** Noise a Node crash ends stderr with, or a stack frame: never the reason. */
-const isNoise = (line) => /^Node\.js v\d/u.test(line) || /^\s+at /u.test(line);
-/**
-* Why a process ended without a result: the last block of its stderr as one
-* masked, capped line (the reason reaches the terminal, which is not masked).
-*/
-const failureReason = (name, stderr, code) => {
-	const block = stderr.split("\n").filter((line) => !isNoise(line)).join("\n").split(/\n\s*\n/u).map((text) => text.trim().replaceAll(/\s*\n\s*/gu, " ")).findLast((text) => text !== "");
-	return block === void 0 ? `${name} exited with code ${String(code)}` : maskSecrets(block).slice(0, REASON_LIMIT);
-};
 /** 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) => {
@@ -680,11 +734,14 @@ const runLeg = async function* (input) {
 	if (input.adapter.command.input === void 0) child.stdin.end();
 	let outcome;
 	let sessionId = "";
+	/** What this leg has used so far, as the last usage step said. */
+	let used;
 	const { decoder } = input;
 	const decode = decoder?.decode ?? input.adapter.decode;
 	try {
 		for await (const line of createInterface({ input: child.stdout })) {
 			const decoded = decode(line);
+			used = decoded.usage ?? used;
 			const { events, ended } = legStep(decoded, input);
 			for (const event of decoded.events) if (event.type === "session.started") sessionId = event.sessionId;
 			yield* events;
@@ -712,11 +769,18 @@ const runLeg = async function* (input) {
 			reason: `could not start ${input.bin}: ${end.message}`,
 			end: failureKind(end)
 		};
-		if (stopped || end.signal !== null) return {
-			kind: "failed",
-			reason: "interrupted",
-			end: "interrupted"
-		};
+		if (stopped || end.signal !== null) {
+			const usage = withCarried(input, used);
+			return {
+				kind: "failed",
+				reason: "interrupted",
+				end: "interrupted",
+				...usage === void 0 ? {} : { spent: {
+					usage,
+					sessionId
+				} }
+			};
+		}
 		const reason = failureReason(input.adapter.command.bin, stderr, end.code);
 		return {
 			kind: "failed",
@@ -802,6 +866,7 @@ const releaseTool = defineTool({
 });
 // ../runtime/src/tools/delegate.ts
 const BRIEF = z.string().min(1).describe("Self-contained: the goal, the files that matter, and what done looks like. The child does not see your conversation.");
+const DESCRIPTION = z.string().exactOptional().describe("A few words naming this task; shown as the child's label.");
 /** What the leader reads back: each report without the usage details. */
 const reportLine = (report) => {
 	const { usage, ...output } = report.output;
@@ -827,7 +892,8 @@ const delegateTool = defineTool({
 		const ids = ports.ownership?.children.map((child) => child.id) ?? [];
 		return { tasks: z.array(z.strictObject({
 			child: z.enum(ids).describe(`The id of a node you own: ${ids.join(", ")}.`),
-			brief: BRIEF
+			brief: BRIEF,
+			description: DESCRIPTION
 		})).min(1) };
 	},
 	available: ({ ports }) => (ports.ownership?.children.length ?? 0) > 0,
@@ -843,7 +909,8 @@ const spawnWorkerTool = defineTool({
 		const ids = ports.ownership?.templates ?? [];
 		return { tasks: z.array(z.strictObject({
 			template: z.enum(ids).describe(`The id of a child worker you own: ${ids.join(", ")}.`),
-			brief: BRIEF
+			brief: BRIEF,
+			description: DESCRIPTION
 		})).min(1) };
 	},
 	available: ({ ports }) => ports.ownership !== void 0 && ports.ownership.templates.length > 0 && ports.ownership.workersLeft() > 0,
@@ -884,6 +951,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().trim().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
@@ -1074,6 +1209,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)
@@ -1218,7 +1354,9 @@ const createSessionRuntime = (adapter, options = {}) => ({
 					}
 					const leg = yield* runLeg(legOf(legSpec, spent));
 					if (leg.kind === "failed") {
-						yield driverFailure(leg.reason, leg.end, scope);
+						const { spent: stopped } = leg;
+						if (stopped?.sessionId === "") stopped.sessionId = legSpec.resume ?? "";
+						yield driverFailure(leg.reason, leg.end, scope, stopped);
 						return;
 					}
 					if (leg.kind === "finished") return;