@krapht/ork 0.1.0 → 0.3.0

package/dist/pause-DKACDfV1.mjs

@@ -0,0 +1,65 @@
+import { B as requestContinue, V as requestPause } from "./src-Cz1yOUTg.mjs";
+import { t as findRun } from "./find-BcvhT6UN.mjs";
+import { a as write, c as openStore, i as style, o as writeErr } from "./output-Q2EdeVUt.mjs";
+import { r as continueRefusal } from "./in-a-run-BbLhZOFW.mjs";
+import { defineCommand } from "citty";
+// src/commands/pause.ts
+/**
+* @file `ork pause` and `ork continue`: pause a live run, or one of its nodes,
+*   from any terminal, and let it go on (ADR-041). Nothing new starts while a
+*   run is paused, and a running session waits before its next tool call;
+*   nothing it is doing is cut short. Both write to the store, then wake the
+*   run on its socket (specs/messaging.md).
+*/
+const args = {
+	run: {
+		type: "positional",
+		description: "A run id or a prefix (default: this project's newest)",
+		required: false
+	},
+	node: {
+		type: "string",
+		description: "Only this node, not the whole run"
+	}
+};
+/** Finds the run, asks it, and says what happens next. */
+const ask = async (runArg, request, done) => {
+	const store = openStore();
+	try {
+		const found = findRun(store, runArg, process.cwd());
+		const asked = found.ok ? await request(store, found.run) : found;
+		if (!asked.ok) {
+			writeErr(asked.error);
+			process.exitCode = 1;
+			return;
+		}
+		if (found.ok) write(`${style("green", "✓")} ${done(found.run)}`);
+	} finally {
+		store.close();
+	}
+};
+const pause = defineCommand({
+	meta: {
+		name: "pause",
+		description: "Pause a live run, or one node, before its next tool call"
+	},
+	args,
+	run: ({ args: given }) => ask(given.run, (store, run) => requestPause(store, run, void 0, given.node), (run) => given.node === void 0 ? `Run ${run.id} pauses: nothing new starts, and running sessions wait before their next tool call. Go on with: ork continue ${run.id}` : `${given.node} in run ${run.id} pauses before its next tool call. Go on with: ork continue ${run.id} --node ${given.node}`)
+});
+const continueRun = defineCommand({
+	meta: {
+		name: "continue",
+		description: "Let a paused run, or one paused node, go on"
+	},
+	args,
+	run: async ({ args: given }) => {
+		const refused = continueRefusal();
+		if (refused !== null) {
+			writeErr(refused);
+			process.exitCode = 1;
+			return;
+		}
+		await ask(given.run, (store, run) => requestContinue(store, run, void 0, given.node), (run) => given.node === void 0 ? `Run ${run.id} goes on.` : `${given.node} in run ${run.id} goes on.`);
+	}
+});
+export { continueRun, pause };

package/dist/relay-CbK-Wme9.mjs

@@ -0,0 +1,122 @@
+import { F as linkNodes, M as addressOf, R as unlinkNodes } from "./src-Cz1yOUTg.mjs";
+import { a as write, c as openStore, i as style, o as writeErr } from "./output-Q2EdeVUt.mjs";
+import { defineCommand } from "citty";
+// src/commands/relay.ts
+/**
+* @file `ork relay`: introduce two running nodes of different runs so they can
+*   message each other, end that, and list what is linked (RFC-003,
+*   specs/messaging.md). Each side's session is told at its next step, through
+*   the store and its run's socket. Not `ork link`, which points tools' folders
+*   at `.ork/`. A node's address always has a slash, so `end` and `list` cannot
+*   be taken for one.
+*/
+const relayAction = (first, second, third) => {
+	if (first === "list") return second === void 0 ? { kind: "list" } : {
+		kind: "list",
+		run: second
+	};
+	if (first === "end") return second === void 0 || third === void 0 ? { kind: "usage" } : {
+		kind: "end",
+		a: second,
+		b: third
+	};
+	return first === void 0 || second === void 0 ? { kind: "usage" } : {
+		kind: "link",
+		a: first,
+		b: second
+	};
+};
+const USAGE = `Name two nodes of different runs as <run>/<node>:
+  ork relay <a> <b>       let them message each other
+  ork relay end <a> <b>   end that
+  ork relay list [run]    list what is linked`;
+/** The link's two ends, its count, and whether it is over. */
+const formatLink = (link) => `${addressOf(link.a)} <-> ${addressOf(link.b)}  ${String(link.messages)}/${String(link.maxMessages)} messages${link.endedAt === void 0 ? "" : style("dim", "  (ended)")}`;
+const refuse = (error) => {
+	writeErr(error);
+	process.exitCode = 1;
+};
+/** A whole number above zero, `undefined` when not given, `null` when wrong. */
+const maxMessagesOf = (given) => {
+	if (given === void 0) return void 0;
+	const limit = Number(given);
+	return Number.isInteger(limit) && limit > 0 ? limit : null;
+};
+const relay = defineCommand({
+	meta: {
+		name: "relay",
+		description: "Let two running nodes of different runs message each other; `end` and `list` too"
+	},
+	args: {
+		first: {
+			type: "positional",
+			description: "A node as <run>/<node>, or `end`, or `list`",
+			required: false
+		},
+		second: {
+			type: "positional",
+			description: "The other node",
+			required: false
+		},
+		third: {
+			type: "positional",
+			description: "With `end`: the other node",
+			required: false
+		},
+		"max-messages": {
+			type: "string",
+			description: `Ask you whether to go on after this many messages (default ${String(100)})`
+		},
+		all: {
+			type: "boolean",
+			description: "With `list`: include links that have ended",
+			default: false
+		},
+		json: {
+			type: "boolean",
+			description: "With `list`: print JSON",
+			default: false
+		}
+	},
+	run: async ({ args }) => {
+		const action = relayAction(args.first, args.second, args.third);
+		if (action.kind === "usage") {
+			refuse(USAGE);
+			return;
+		}
+		const store = openStore();
+		try {
+			if (action.kind === "list") {
+				const found = store.links({
+					...action.run === void 0 ? {} : { run: action.run },
+					live: !args.all
+				});
+				if (args.json) write(JSON.stringify(found));
+				else if (found.length === 0) write("No links.");
+				else for (const one of found) write(formatLink(one));
+				return;
+			}
+			if (action.kind === "end") {
+				const ended = await unlinkNodes(store, action.a, action.b);
+				if (ended.ok) write(`${style("green", "✓")} Ended the link. Both are told.`);
+				else refuse(ended.error);
+				return;
+			}
+			const maxMessages = maxMessagesOf(args["max-messages"]);
+			if (maxMessages === null) {
+				refuse("--max-messages takes a whole number above zero.");
+				return;
+			}
+			const linked = await linkNodes(store, action.a, action.b, { maxMessages });
+			if (!linked.ok) {
+				refuse(linked.error);
+				return;
+			}
+			const [a, b] = [addressOf(linked.link.a), addressOf(linked.link.b)];
+			write(linked.already ? `${a} and ${b} are already linked.` : `${style("green", "✓")} Linked ${a} and ${b}. Both are told at their next step.`);
+		} finally {
+			store.close();
+		}
+	}
+});
+export { relay };

package/dist/report-DK4LGqwF.mjs

@@ -0,0 +1,129 @@
+// ../core/src/usage/report.ts
+const USAGE_DIMENSIONS = [
+	"day",
+	"week",
+	"month",
+	"workflow",
+	"node",
+	"model",
+	"driver",
+	"project"
+];
+const pad = (value) => String(value).padStart(2, "0");
+/** `2026-11-03`, in the machine's own time zone. */
+const dayOf = (date) => `${String(date.getFullYear())}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+/** The Monday of a time's week. */
+const weekOf = (date) => {
+	const monday = new Date(date);
+	monday.setDate(date.getDate() - (date.getDay() + 6) % 7);
+	return dayOf(monday);
+};
+const KEYS = {
+	day: (row) => dayOf(new Date(row.at)),
+	week: (row) => weekOf(new Date(row.at)),
+	month: (row) => dayOf(new Date(row.at)).slice(0, 7),
+	workflow: (row) => row.workflow,
+	node: (row) => `${row.workflow}/${row.template ?? row.node}`,
+	model: (row) => row.model ?? "unknown",
+	driver: (row) => row.driver ?? "unknown",
+	project: (row) => row.project
+};
+const TIMES = /* @__PURE__ */ new Set([
+	"day",
+	"week",
+	"month"
+]);
+const totalsOf = (rows) => {
+	const totals = {
+		costUsd: 0,
+		inputTokens: 0,
+		outputTokens: 0,
+		cacheReadTokens: 0,
+		cacheWriteTokens: 0,
+		turns: 0,
+		durationMs: 0,
+		sessions: rows.length,
+		runs: new Set(rows.map((row) => row.runId)).size,
+		failedUsd: 0,
+		reworkUsd: 0,
+		chatUsd: 0,
+		cacheHitRate: 0
+	};
+	for (const row of rows) {
+		totals.costUsd += row.costUsd;
+		totals.inputTokens += row.inputTokens;
+		totals.outputTokens += row.outputTokens;
+		totals.cacheReadTokens += row.cacheReadTokens;
+		totals.cacheWriteTokens += row.cacheWriteTokens;
+		totals.turns += row.turns;
+		totals.durationMs += row.durationMs;
+		if (row.failed) totals.failedUsd += row.costUsd;
+		if (row.kind === "chat") totals.chatUsd += row.costUsd;
+		else if (row.round > 1) totals.reworkUsd += row.costUsd;
+	}
+	const read = totals.inputTokens + totals.cacheReadTokens + totals.cacheWriteTokens;
+	totals.cacheHitRate = read === 0 ? 0 : totals.cacheReadTokens / read;
+	return totals;
+};
+const groupBy = (rows, dimension) => {
+	const buckets = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const key = KEYS[dimension](row);
+		const bucket = buckets.get(key);
+		if (bucket === void 0) buckets.set(key, [row]);
+		else bucket.push(row);
+	}
+	const groups = [...buckets].map(([key, bucket]) => Object.assign(totalsOf(bucket), { key }));
+	return TIMES.has(dimension) ? groups.toSorted((a, b) => a.key.localeCompare(b.key)) : groups.toSorted((a, b) => b.costUsd - a.costUsd);
+};
+/** Below this, a percentage says nothing worth acting on. */
+const MIN_SPEND_USD = .5;
+const REWORK_SHARE = .2;
+const FAILED_SHARE = .1;
+const CONCENTRATED_SHARE = .5;
+const LOW_CACHE_RATE = .5;
+const MIN_CACHE_TOKENS = 1e5;
+const percent = (share) => `${String(Math.round(share * 100))}%`;
+const hintsOf = (totals, nodes) => {
+	const spend = totals.costUsd;
+	if (spend < MIN_SPEND_USD) return [];
+	const hints = [];
+	if (totals.reworkUsd / spend >= REWORK_SHARE) hints.push({
+		code: "rework",
+		message: `${percent(totals.reworkUsd / spend)} of the spend went to loop rounds after the first. Sharper briefs or an earlier check can stop work coming back.`
+	});
+	if (totals.failedUsd / spend >= FAILED_SHARE) hints.push({
+		code: "failed",
+		message: `${percent(totals.failedUsd / spend)} of the spend went to sessions that failed. A cheap check before them, or a lower budget per session, can stop them sooner.`
+	});
+	const top = nodes[0];
+	if (top !== void 0 && nodes.length > 1 && top.costUsd / spend >= CONCENTRATED_SHARE) hints.push({
+		code: "concentrated",
+		message: `${top.key} took ${percent(top.costUsd / spend)} of the spend. It is the first place to try a smaller model, a lower effort or a tighter brief.`
+	});
+	if (totals.inputTokens + totals.cacheReadTokens + totals.cacheWriteTokens >= MIN_CACHE_TOKENS && totals.cacheHitRate < LOW_CACHE_RATE) hints.push({
+		code: "cache",
+		message: `Only ${percent(totals.cacheHitRate)} of input tokens came from the prompt cache. Long runs of fresh sessions cost more than resumed ones.`
+	});
+	return hints;
+};
+/** Everything a report shows, from the ledger's rows. */
+const usageReport = (rows) => {
+	const totals = totalsOf(rows);
+	const groups = {
+		day: groupBy(rows, "day"),
+		week: groupBy(rows, "week"),
+		month: groupBy(rows, "month"),
+		workflow: groupBy(rows, "workflow"),
+		node: groupBy(rows, "node"),
+		model: groupBy(rows, "model"),
+		driver: groupBy(rows, "driver"),
+		project: groupBy(rows, "project")
+	};
+	return {
+		totals,
+		groups,
+		hints: hintsOf(totals, groups.node)
+	};
+};
+export { usageReport as n, USAGE_DIMENSIONS as t };

package/dist/send-C6yr04Fe.mjs

@@ -0,0 +1,163 @@
+import { Ft as socketPath, It as wakeRun, gt as scriptContactsOf, rt as liveStatus } from "./src-Cz1yOUTg.mjs";
+import { c as openStore, o as writeErr } from "./output-Q2EdeVUt.mjs";
+import { u as inheritedScrubber } from "./src-DtN1k-B3.mjs";
+import { defineCommand } from "citty";
+// ../core/src/remote/send.ts
+/**
+* @file `ork send` (RFC-005): a program in a tool node writes to a session on
+*   its run's bus. The check is on the sender's side, as a refusal must be an
+*   exit code a script can act on; then a row in the store and a wake, as for a
+*   message between linked runs. `ORK_RUN` and `ORK_NODE` say who it is, and
+*   they are attribution, not proof: the check stops mistakes, not a program
+*   running as the same user.
+*/
+/** A first value, as for links; real use will show whether it is the right one. */
+const DEFAULT_SCRIPT_MESSAGES = 100;
+/**
+* Why this sender may not write to this node; `null` when it may. The body is
+* not needed, so a program is told before it pipes a whole message in.
+*/
+const scriptRefusal = (store, send) => {
+	const { run: runId, node, to } = send;
+	if (runId === void 0 || node === void 0) return "`ork send` runs inside a tool node of a run: `ORK_RUN` and `ORK_NODE` are not set.";
+	if (runId.startsWith("node-")) return `Run ${runId} runs one node, which has no message bus; run the whole workflow.`;
+	const run = store.lookup(runId).find((found) => found.id === runId);
+	if (run === void 0) return `There is no run ${runId}.`;
+	const status = liveStatus(run);
+	if (status !== "running") return `Run ${runId} is not running (${status}).`;
+	const started = store.events(runId).map((stored) => stored.event).findLast((event) => event.type === "run.started");
+	if (started === void 0) return `Run ${runId} has not started yet.`;
+	const own = started.nodes.find((found) => found.id === node);
+	if (own === void 0 || !own.type.startsWith("tool.")) return `${node} is not a tool node of run ${runId}.`;
+	const contacts = scriptContactsOf(node, started.nodes, started.channels ?? []);
+	if (contacts.includes(to)) return null;
+	return contacts.length === 0 ? `\`${node}\` has no one to write to: give it an owner, or a channel under \`messages:\`.` : `\`${to}\` is not a contact of \`${node}\`, which can write to \`${contacts.join("`, `")}\` (its owner and its channels).`;
+};
+/** Reading all of it would cost as much as sending it. */
+const TOO_LONG = "The message is over 64 KiB. Write it to a file and send the file's path.";
+/** Checks the message, writes it for the run, and wakes it. */
+const sendFromScript = async (store, send, home) => {
+	const refused = scriptRefusal(store, send);
+	if (refused !== null) return {
+		ok: false,
+		error: refused
+	};
+	if (Buffer.byteLength(send.body) > 65536) return {
+		ok: false,
+		error: TOO_LONG
+	};
+	const run = String(send.run);
+	const node = String(send.node);
+	if (!store.scriptCommand(run, {
+		kind: "script",
+		node: send.to,
+		from: node,
+		body: send.body
+	}, DEFAULT_SCRIPT_MESSAGES)) return {
+		ok: false,
+		error: `\`${node}\` has sent ${String(DEFAULT_SCRIPT_MESSAGES)} messages in this run, which is the most it may.`
+	};
+	await wakeRun(socketPath(run, home));
+	return { ok: true };
+};
+// 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 };