@krapht/ork 0.3.0 → 1.0.0-alpha.0

package/dist/{src-DtN1k-B3.mjs → src-C38BPzit.mjs}

@@ -1,4 +1,4 @@
-import { A as declaredProblem, An as integrationFor, At as evaluate, Cn as beforeOf, Dn as timeoutMs, E as planNodeSession, En as programsRunBy, Mt as renderTemplate, On as INTEGRATIONS, Tn as isToolNode, _n as markValue, _t as calledWorkflows, bt as declaredOutputOf, ht as runScope, jt as parseTemplate, kn as TOOL_PREFIX, mt as heldTimeout, s as planReason, vt as envReadsOf } from "./src-Cz1yOUTg.mjs";
+import { $n as timeoutMs, $t as parseTemplate, At as runScope, F as declaredProblem, Jn as beforeOf, Mt as envReadsOf, Ot as heldTimeout, Pt as declaredOutputOf, Qt as evaluate, Vn as markValue, Xn as isToolNode, Zn as programsRunBy, en as renderTemplate, er as INTEGRATIONS, ft as sessionDriver, jt as calledWorkflows, mt as reportSchemaFor, nr as integrationFor, s as planReason, tr as TOOL_PREFIX, ut as planNodeSession } from "./src-DHvWU4tX.mjs";
 import path from "node:path";
 import { accessSync, constants, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
@@ -123,6 +123,196 @@ const resultOf = (outcome, declared) => {
 	if (!result.ok) result.error = report.summary;
 	return result;
 };
+/** The only built-in tools a fork has: it reads, and reports. */
+const FORK_TOOLS = [
+	"Read",
+	"Grep",
+	"Glob"
+];
+/**
+* The option that passes a question on: `ask-user`, or the first free
+* `ask-user-<n>`.
+*/
+const passOnId = (options) => {
+	let id = "ask-user";
+	for (let n = 2; options.some((option) => option.id === id); n += 1) id = `ask-user-${String(n)}`;
+	return id;
+};
+const optionLine = (option) => [
+	`- \`${option.id}\``,
+	option.label === void 0 ? "" : `: ${option.label}`,
+	option.description === void 0 ? "" : ` (${option.description})`
+].join("");
+/** What the fork is asked. */
+const forkPrompt = (question, passOn) => [
+	`[ork] \`${question.nodeId}\`, which you own, asks a question (ask_user). You take its questions before the user does.`,
+	"",
+	`Question: ${question.question}`,
+	...question.context === void 0 ? [] : [`Context: ${question.context}`],
+	"Options:",
+	...question.options.map(optionLine),
+	...question.recommended === void 0 ? [] : [`It recommends \`${question.recommended}\`.`],
+	"",
+	`If your task, and what was agreed with the user, already settle it, report that option as \`choice\`. If they don't, or it is the user's to decide, report \`${passOn}\` to pass it on to the user. Either way, say why in \`note\`, in a sentence or two: it goes to \`${question.nodeId}\` with your answer, or to the user with the question. This is a side conversation: change nothing, and your own session goes on as it was.`
+].join("\n");
+/** The fork's report: one of the options or the pass-on, and a note. */
+const forkReportSchema = (ids) => {
+	const node = {
+		type: "claude.worker",
+		prompt: "",
+		output: { schema: {
+			choice: [...ids],
+			note: "string"
+		} }
+	};
+	return reportSchemaFor(node);
+};
+/** A fork can't ask anyone: it answers or passes the question on. */
+const NO_ONE = {
+	permit: () => Promise.resolve({
+		allow: false,
+		message: "A fork answering a question can't ask for permission."
+	}),
+	ask: () => Promise.reject(/* @__PURE__ */ new Error("a fork can't ask the user"))
+};
+/** The fork's session spec, from the leader's own plan; `null` if it can't. */
+const forkSpec = (context, owner, question, passOn, deps) => {
+	const session = owner.session();
+	const left = owner.budgetLeftUsd();
+	if (session === void 0 || left !== void 0 && left <= 0) return null;
+	const plan = planNodeSession(context.workflow, owner.id, {
+		cwd: session.cwd,
+		inputs: context.inputs,
+		outputs: context.outputs,
+		inPlace: deps.inPlace,
+		workflowDir: context.workflowDir,
+		projectRoot: context.projectRoot,
+		...context.orkDir === void 0 ? {} : { orkDir: context.orkDir },
+		...left === void 0 ? {} : { budgetLeftUsd: left }
+	});
+	if (!plan.ok) return null;
+	const driver = session.driver ?? sessionDriver({
+		override: deps.driver,
+		named: plan.driver,
+		ready: deps.readyDriver
+	});
+	if (driver === void 0) return null;
+	const ids = [...question.options.map((option) => option.id), passOn];
+	const spec = {
+		...plan.spec,
+		cwd: session.cwd,
+		prompt: forkPrompt(question, passOn),
+		resume: session.sessionId,
+		fork: true,
+		maxTurns: 3,
+		tools: {
+			allow: [...FORK_TOOLS],
+			deny: [...plan.spec.tools.deny, "mcp__ork__ask_user"],
+			only: [...FORK_TOOLS],
+			strictMcp: true
+		},
+		reportSchema: forkReportSchema(ids)
+	};
+	delete spec.promptCache;
+	delete spec.agents;
+	delete spec.plugins;
+	return {
+		driver,
+		spec
+	};
+};
+/** The choice a fork's outcome gives, if it is a valid one. */
+const answerOf = (outcome, ids) => {
+	const { choice, note } = outcome?.report?.fields ?? {};
+	if (outcome?.subtype !== "success" || typeof choice !== "string") return null;
+	if (!ids.includes(choice)) return null;
+	return typeof note === "string" && note.trim() !== "" ? {
+		choice,
+		note: note.trim()
+	} : { choice };
+};
+/**
+* Asks a fork of the owner's latest session; `null` when it can't answer: no
+* session yet, nothing left to spend, the node stopped, or a fork that fails,
+* runs out of time or gives no valid choice. A paused run or node starts no
+* fork until it goes on; one already started isn't paused, as it is bounded by
+* its turns and `timeoutMs`. Its events are the owner's, each marked as a fork,
+* and its spend the run's.
+*/
+const askFork = async (context, owner, question, deps) => {
+	const passOn = passOnId(question.options);
+	await context.hold?.wait("start", context.signal);
+	if (context.signal.aborted) return null;
+	const planned = forkSpec(context, owner, question, passOn, deps);
+	if (planned === null) return null;
+	const signal = AbortSignal.any([context.signal, AbortSignal.timeout(deps.timeoutMs ?? 3e5)]);
+	let outcome = null;
+	try {
+		const session = (await deps.runtimeFor(planned.driver)).start(planned.spec, { human: NO_ONE });
+		const stop = () => {
+			session.interrupt();
+		};
+		signal.addEventListener("abort", stop, { once: true });
+		if (signal.aborted) stop();
+		try {
+			for await (const event of session.events) {
+				if (event.type === "session.finished") {
+					({outcome} = event);
+					owner.charge(outcome.sessionId, outcome.usage);
+				}
+				owner.emit({
+					...event,
+					fork: true
+				});
+			}
+		} finally {
+			signal.removeEventListener("abort", stop);
+		}
+	} catch {
+		return null;
+	}
+	if (signal.aborted) return null;
+	return answerOf(outcome, [...question.options.map((option) => option.id), passOn]);
+};
+/** What the person sees of a question its asker's owner passed on. */
+const passedOnContext = (context, owner, note) => [...context === void 0 ? [] : [context, ""], note === void 0 ? `${owner} passed this on.` : `${owner} passed this on: ${note}`].join("\n");
+/**
+* The child's channel when its owner takes its questions first: a question goes
+* to a fork of the owner's session, then to the person if the fork passes it on
+* or can't answer. Permission prompts go to the person as before.
+*/
+const ownerFirst = (context, owner, deps) => {
+	const { human } = context;
+	return {
+		permit: (request) => human.permit(request),
+		ask: async (question) => {
+			const answered = await askFork(context, owner, question, deps);
+			if (context.signal.aborted) throw new Error(`${context.id} was stopped`);
+			const signal = question.signal === void 0 ? context.signal : AbortSignal.any([question.signal, context.signal]);
+			if (answered === null) return human.ask({
+				...question,
+				signal
+			});
+			if (answered.choice === passOnId(question.options)) return human.ask({
+				...question,
+				signal,
+				owner: owner.id,
+				context: passedOnContext(question.context, owner.id, answered.note)
+			});
+			const { note } = answered;
+			human.settled?.({
+				...question,
+				answer: answered.choice,
+				owner: owner.id,
+				...note === void 0 ? {} : { note }
+			});
+			question.onOwner?.(owner.id);
+			if (note !== void 0) question.onNote?.(note);
+			return answered.choice;
+		},
+		...human.settled === void 0 ? {} : { settled: human.settled }
+	};
+};
 // ../nodes/src/session-turns.ts
 /**
 * @file One session over several processes: the outcome after another turn, and
@@ -235,7 +425,8 @@ const notStarted = (reason, limited) => ({
 *   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.
+*   run clears when it starts and ends. A long field is kept in the run's
+*   files, named for the node, its round, and its step and try.
 */
 /** The run's private folder for results not yet read. */
 const OUTPUT_FOLDER = ".output";
@@ -278,8 +469,14 @@ const prepareOutputFile = (runDir, id, round) => {
 	removeOutputFile(file);
 	return file;
 };
+/**
+* A node's activation, and the step and its try when it is one, as a file
+* name's start: `review.1`, `review.1.before-1`, `review.1.verify-2`. Two
+* steps, or two tries of a check, never share a file.
+*/
+const keptStem = ({ id, round, step }) => `${id}.${String(round)}${step === void 0 ? "" : `.${step.name}-${String(step.try)}`}`;
 /** 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`);
+const keptFile = (context, field) => path.join(context.runDir, `${keptStem(context)}.${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 });
@@ -1168,11 +1365,15 @@ const TAIL_LIMIT = 8192;
 */
 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 runStep = async (tool, given, { timeout, ...fields }, step) => {
 	const node = {
 		type: "tool.shell",
 		...fields
 	};
+	const context = {
+		...given,
+		step
+	};
 	const ms = timeoutMs(timeout);
 	if (ms === void 0) return tool({
 		...context,
@@ -1225,7 +1426,7 @@ const tailOf = (check, context) => {
 	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`);
+	const file = path.join(context.runDir, `${keptStem(context)}.txt`);
 	writeFileSync(file, said);
 	return `The end of what it printed, with all of it in ${file}:\n\n\`\`\`\n${said.slice(-8192)}\n\`\`\``;
 };
@@ -1362,7 +1563,10 @@ const claudeExecutor = (options) => async (context) => {
 	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);
+		const ran = await runStep(options.steps ?? noSteps, context, before, {
+			name: "before",
+			try: 1
+		});
 		if (!ran.ok) return beforeFailed(ran);
 		await context.hold?.wait("start", context.signal);
 		if (context.signal.aborted) return beforeFailed({
@@ -1386,8 +1590,19 @@ const claudeExecutor = (options) => async (context) => {
 		error: plan.error
 	};
 	const spec = specFor(plan.spec, context);
-	const runtime = await options.runtimeFor(options.driver ?? plan.driver);
-	const ports = { human: context.human };
+	const driver = sessionDriver({
+		override: options.driver,
+		named: plan.driver,
+		ready: options.readyDriver
+	});
+	if (driver === void 0) return notStarted("no Claude driver is ready; see `ork doctor`");
+	const runtime = await options.runtimeFor(driver);
+	const ports = { human: context.owner === void 0 ? context.human : ownerFirst(context, context.owner, {
+		runtimeFor: options.runtimeFor,
+		driver: options.driver,
+		readyDriver: options.readyDriver,
+		inPlace: options.inPlace
+	}) };
 	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;
@@ -1447,26 +1662,38 @@ const claudeExecutor = (options) => async (context) => {
 	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)));
+	let tries = 0;
+	const step = () => ({
+		name: "verify",
+		try: tries
+	});
 	const checked = await checkReport({
 		verify,
 		first: outcome,
 		signal: context.signal,
-		check: () => runStep(options.steps ?? noSteps, context, verify),
+		check: () => {
+			tries += 1;
+			return runStep(options.steps ?? noSteps, context, verify, step());
+		},
 		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 context.signal.aborted ? null : resumeWith(current, checkFailedMessage(check, {
+				...context,
+				step: step()
+			}), 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).
+* @file The `human.gate` node type: asks the human the rendered question,
+*   outputs their choice with the note they gave, 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(() => {});
@@ -1478,8 +1705,8 @@ const choiceOf = (option) => {
 	return choice;
 };
 /**
-* Asks the human and outputs `choice` and `answeredBy`. With `timeout`, the
-* `default` answers when no one has.
+* Asks the human and outputs `choice`, `answeredBy` and `note` (empty when they
+* said nothing). With `timeout`, the `default` answers when no one has.
 */
 const gateExecutor = async (context) => {
 	const { node } = context;
@@ -1495,16 +1722,21 @@ const gateExecutor = async (context) => {
 	context.signal.addEventListener("abort", () => {
 		withdraw.abort();
 	});
+	let note = "";
 	const asked = {
 		nodeId: context.id,
 		question,
 		options,
-		signal: withdraw.signal
+		signal: withdraw.signal,
+		onNote: (given) => {
+			note = given;
+		}
 	};
 	if (node.recommended !== void 0) asked.recommended = node.recommended;
 	const answer = context.human.ask(asked).then((choice) => ({
 		choice,
-		answeredBy: "user"
+		answeredBy: "user",
+		note
 	}));
 	const ms = timeoutMs(node.timeout);
 	const answered = new AbortController();
@@ -1513,7 +1745,8 @@ const gateExecutor = async (context) => {
 		withdraw.abort();
 		return {
 			choice: node.default ?? "",
-			answeredBy: "timeout"
+			answeredBy: "timeout",
+			note: ""
 		};
 	})];
 	try {