pi-task-dispatcher 1.0.0 → 3.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-task-dispatcher",
-  "version": "1.0.0",
-  "description": "Delegate bounded mechanical and engineering tasks to configurable Pi worker models.",
+  "version": "3.0.0",
+  "description": "Run configurable Pi worker models as supervised, observable, resumable jobs.",
   "type": "module",
   "keywords": [
     "pi-package",
@@ -23,8 +23,14 @@
   "engines": {
     "node": ">=22.19.0"
   },
+  "scripts": {
+    "test:gate": "node tests/gate-probe.mjs",
+    "test:fake-rpc": "node tests/fake-rpc-check.mjs",
+    "check": "node tests/static-check.mjs && node tests/fake-rpc-check.mjs"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "pi": {
@@ -34,6 +40,8 @@
   },
   "files": [
     "extensions",
+    "tests",
+    "README.md",
     "LICENSE"
   ],
   "publishConfig": {

package/tests/fake-rpc-check.mjs

@@ -0,0 +1,172 @@
+/** Exercise WorkerJob lifecycle transitions against a deterministic fake JSONL/IPC child. */
+
+import assert from "node:assert/strict";
+import { access, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { homedir, tmpdir } from "node:os";
+import path from "node:path";
+
+// Resolve jiti from the installed Pi runtime so this package does not duplicate Pi's TypeScript loader.
+const installRoot = process.env.PI_MANAGED_INSTALL_ROOT ?? path.join(homedir(), ".pi", "agent", "install");
+const piVersion = (await readFile(path.join(installRoot, "current-version"), "utf8")).trim();
+const piRoot = path.join(installRoot, "releases", piVersion, "node_modules", "@earendil-works", "pi-coding-agent");
+const requireFromPi = createRequire(path.join(piRoot, "package.json"));
+const { createJiti } = requireFromPi("jiti");
+
+const projectRoot = path.resolve(import.meta.dirname, "..");
+const temporaryDirectory = await mkdtemp(path.join(tmpdir(), "pi-task-dispatcher-fake-rpc-"));
+const configPath = path.join(temporaryDirectory, "task-dispatcher.json");
+const promptMarker = path.join(temporaryDirectory, "prompts.txt");
+const inheritedWorkerRole = process.env.PI_TASK_DISPATCHER_WORKER;
+
+// The test loads the parent extension even when invoked from a delegated review worker.
+delete process.env.PI_TASK_DISPATCHER_WORKER;
+process.env.PI_TASK_DISPATCHER_TEST_MODE = "1";
+process.env.PI_TASK_DISPATCHER_CONFIG_PATH = configPath;
+process.env.PI_TASK_DISPATCHER_CLI_OVERRIDE = path.join(projectRoot, "tests", "fake-rpc-worker.mjs");
+process.env.PI_TASK_DISPATCHER_FAKE_PROMPT_MARKER = promptMarker;
+
+try {
+	await writeFile(configPath, "{}\n", "utf8");
+	const jiti = createJiti(import.meta.url, {
+		interopDefault: true,
+		alias: {
+			"@earendil-works/pi-coding-agent": path.join(piRoot, "dist", "index.js"),
+			"@earendil-works/pi-tui": requireFromPi.resolve("@earendil-works/pi-tui"),
+			typebox: requireFromPi.resolve("typebox"),
+		},
+	});
+	const loaded = await jiti.import(path.join(projectRoot, "extensions", "task-dispatcher.ts"));
+	const register = loaded.default ?? loaded;
+	const tools = new Map();
+	const handlers = new Map();
+	const pi = {
+		registerTool(tool) { tools.set(tool.name, tool); },
+		getActiveTools() { return ["read", "bash", "edit", "write"]; },
+		on(event, handler) { handlers.set(event, handler); },
+	};
+	register(pi);
+
+	const activeModel = { provider: "fake-provider", id: "active-model", contextWindow: 272_000, maxTokens: 128_000 };
+	const context = {
+		cwd: projectRoot,
+		hasUI: false,
+		model: activeModel,
+		thinkingLevel: "medium",
+		ui: { setWidget() {}, setStatus() {} },
+		modelRegistry: {
+			find(provider, id) { return { provider, id, contextWindow: 272_000, maxTokens: 128_000 }; },
+			hasConfiguredAuth() { return true; },
+		},
+	};
+	const workload = { investigationUnits: 1, changeUnits: 0, verificationUnits: 1, expectedLongRunningSeconds: 0 };
+	const start = tools.get("delegate_engineering");
+	const control = tools.get("delegate_control");
+	assert(start && control, "Expected supervised tools to register.");
+	const theme = { fg(_color, text) { return text; }, bold(text) { return text; } };
+	let rendererInvalidations = 0;
+	const renderContext = { args: {}, state: {}, invalidate() { rendererInvalidations++; }, cwd: projectRoot };
+	const callComponent = start.renderCall({}, theme, renderContext);
+	assert.doesNotThrow(() => callComponent.render(80), "Partial streamed arguments must never crash the renderer.");
+
+	// A normal fake job must pause, account assistant and tool-result usage once, then resume to completion.
+	process.env.PI_TASK_DISPATCHER_FAKE_SCENARIO = "normal";
+	let result = await start.execute("start-normal", { task: "fake normal job", tools: ["read"], workload }, undefined, undefined, context);
+	assert.equal(result.isError, false);
+	assert.equal(result.details.status, "paused");
+	assert.equal(result.details.jobId, "engineer-1");
+	assert.equal(result.details.model, "fake-provider/active-model");
+	assert.equal(result.details.sequence, 1);
+	assert.equal(result.details.turns, 1);
+	assert.equal(result.details.actionLedger.length, 1);
+	assert.equal(result.usage.input, 13);
+	assert.equal(result.usage.output, 3);
+	assert.equal(result.usage.totalTokens, 16);
+	const partialRender = start.renderResult(result, { expanded: false, isPartial: true }, theme, renderContext).render(100).join("\n");
+	assert.match(partialRender, /Elapsed:/);
+	const resultComponent = start.renderResult(result, { expanded: false, isPartial: false }, theme, renderContext);
+	const firstRender = resultComponent.render(100).join("\n");
+	assert.match(firstRender, /Took:/);
+	assert.doesNotMatch(firstRender, /Elapsed:/);
+	for (let index = 0; index < 1_000; index++) {
+		const repeatedComponent = start.renderResult(result, { expanded: false, isPartial: false }, theme, renderContext);
+		assert.equal(repeatedComponent.render(100).join("\n"), firstRender, "Repeated render output changed.");
+		assert.match(callComponent.render(100).join("\n"), /engineer-1: paused/);
+	}
+	assert.equal(rendererInvalidations, 0, "A renderer invalidated its own render pass, risking an infinite loop.");
+	assert.match(callComponent.render(100).join("\n"), /engineer-1: paused/, "The shared call header did not update to paused.");
+	const normalJobId = result.details.jobId;
+	const managerArgs = { jobId: normalJobId, action: "continue", actionBatches: 1 };
+	const managerRenderContext = { args: managerArgs, state: {}, invalidate() { rendererInvalidations++; }, cwd: projectRoot };
+	const managerCall = control.renderCall(managerArgs, theme, managerRenderContext);
+	assert.match(managerCall.render(100).join("\n"), /manager: engineer-1 → continue/);
+	assert.doesNotMatch(managerCall.render(100).join("\n"), /continue\//);
+
+	result = await control.execute("continue-normal", managerArgs, undefined, undefined, context);
+	assert.equal(result.isError, false);
+	assert.equal(result.details.status, "completed");
+	assert.equal(result.details.turns, 2);
+	assert.equal(result.details.workerText, "deterministic worker complete");
+	assert.equal(result.usage.input, 5, "Continuation must return only newly observed usage.");
+	assert.equal(result.usage.totalTokens, 8);
+	control.renderResult(result, { expanded: false, isPartial: false }, theme, managerRenderContext).render(100);
+	assert.match(managerCall.render(100).join("\n"), /manager: engineer-1 → completed/);
+	assert.doesNotMatch(managerCall.render(100).join("\n"), /continue\/completed/);
+
+	// A handled prompt starts no agent run and must fail promptly rather than waiting for settlement.
+	process.env.PI_TASK_DISPATCHER_FAKE_SCENARIO = "handled";
+	const handledStartedAt = Date.now();
+	result = await start.execute("start-handled", { task: "fake handled job", tools: ["read"], workload }, undefined, undefined, context);
+	assert.equal(result.isError, true);
+	assert.equal(result.details.status, "hard_stopped");
+	assert.match(result.content[0].text, /intercepted by an input handler/i);
+	assert(Date.now() - handledStartedAt < 5_000, "Handled prompt should not wait for agent settlement.");
+
+	// A tool-use turn without the private IPC signal must fail closed instead of being mistaken for completion.
+	process.env.PI_TASK_DISPATCHER_FAKE_SCENARIO = "missing-boundary";
+	result = await start.execute("start-missing-boundary", { task: "fake missing boundary job", tools: ["read"], workload }, undefined, undefined, context);
+	assert.equal(result.isError, true);
+	assert.equal(result.details.status, "hard_stopped");
+	assert.match(result.content[0].text, /without an enforced IPC boundary/i);
+
+	// A stats timeout after a valid boundary must remain terminal rather than resurrecting as paused.
+	await writeFile(configPath, JSON.stringify({ policy: { absoluteMaxSeconds: 5, noProgressSeconds: 1 } }), "utf8");
+	process.env.PI_TASK_DISPATCHER_FAKE_SCENARIO = "stats-timeout";
+	result = await start.execute("start-stats-timeout", { task: "fake stats timeout job", tools: ["read"], workload }, undefined, undefined, context);
+	assert.equal(result.isError, true);
+	assert.equal(result.details.status, "hard_stopped");
+	assert.notEqual(result.details.status, "paused");
+
+	// A silent prompt must terminate the worker at the configured active-time ceiling.
+	await writeFile(configPath, JSON.stringify({ policy: { absoluteMaxSeconds: 1, noProgressSeconds: 1 } }), "utf8");
+	process.env.PI_TASK_DISPATCHER_FAKE_SCENARIO = "timeout";
+	const timeoutStartedAt = Date.now();
+	result = await start.execute("start-timeout", { task: "fake timeout job", tools: ["read"], workload }, undefined, undefined, context);
+	assert.equal(result.isError, true);
+	assert.equal(result.details.status, "hard_stopped");
+	assert.match(result.content[0].text, /(deadline|timed out|closed)/i);
+	assert(Date.now() - timeoutStartedAt < 5_000, "Silent prompt should be bounded by test policy.");
+
+	// An already-aborted parent operation may initialize the child but must never submit task work.
+	await writeFile(configPath, "{}\n", "utf8");
+	await rm(promptMarker, { force: true });
+	process.env.PI_TASK_DISPATCHER_FAKE_SCENARIO = "normal";
+	const controller = new AbortController();
+	controller.abort();
+	result = await start.execute("start-aborted", { task: "must not be submitted", tools: ["read"], workload }, controller.signal, undefined, context);
+	assert.equal(result.isError, true);
+	assert.equal(result.details.status, "cancelled");
+	await assert.rejects(access(promptMarker), /ENOENT/, "An already-aborted operation submitted a prompt.");
+
+	await handlers.get("session_shutdown")?.({}, context);
+	console.log("Deterministic fake-RPC lifecycle checks passed.");
+} finally {
+	delete process.env.PI_TASK_DISPATCHER_TEST_MODE;
+	delete process.env.PI_TASK_DISPATCHER_CONFIG_PATH;
+	delete process.env.PI_TASK_DISPATCHER_CLI_OVERRIDE;
+	delete process.env.PI_TASK_DISPATCHER_FAKE_PROMPT_MARKER;
+	delete process.env.PI_TASK_DISPATCHER_FAKE_SCENARIO;
+	if (inheritedWorkerRole === undefined) delete process.env.PI_TASK_DISPATCHER_WORKER;
+	else process.env.PI_TASK_DISPATCHER_WORKER = inheritedWorkerRole;
+	await rm(temporaryDirectory, { recursive: true, force: true });
+}

package/tests/fake-rpc-worker.mjs

@@ -0,0 +1,91 @@
+/** Deterministic JSONL/IPC worker used only by the dispatcher's lifecycle tests. */
+
+import { appendFile } from "node:fs/promises";
+import readline from "node:readline";
+
+const scenario = process.env.PI_TASK_DISPATCHER_FAKE_SCENARIO ?? "normal";
+const markerPath = process.env.PI_TASK_DISPATCHER_FAKE_PROMPT_MARKER;
+let promptCount = 0;
+
+function send(event) {
+	process.stdout.write(`${JSON.stringify(event)}\n`);
+}
+
+function usage(input, output) {
+	return {
+		input,
+		output,
+		cacheRead: 0,
+		cacheWrite: 0,
+		totalTokens: input + output,
+		cost: { input: input / 1000, output: output / 1000, cacheRead: 0, cacheWrite: 0, total: (input + output) / 1000 },
+	};
+}
+
+readline.createInterface({ input: process.stdin }).on("line", async (line) => {
+	if (!line.trim()) return;
+	const command = JSON.parse(line);
+	if (command.type === "set_auto_compaction") {
+		send({ type: "response", id: command.id, command: command.type, success: true });
+		return;
+	}
+	if (command.type === "get_session_stats") {
+		if (scenario === "stats-timeout") return;
+		send({
+			type: "response",
+			id: command.id,
+			command: command.type,
+			success: true,
+			data: { contextUsage: { tokens: 100 + promptCount, contextWindow: 1000, percent: 10 + promptCount } },
+		});
+		return;
+	}
+	if (command.type === "compact") {
+		send({ type: "response", id: command.id, command: command.type, success: false, error: "Nothing to compact (fake session)" });
+		return;
+	}
+	if (command.type !== "prompt") return;
+
+	promptCount++;
+	if (markerPath) await appendFile(markerPath, `${promptCount}\n`, "utf8");
+	if (scenario === "timeout") return;
+	if (scenario === "handled") {
+		send({ type: "response", id: command.id, command: command.type, success: true, disposition: "handled" });
+		return;
+	}
+
+	send({ type: "response", id: command.id, command: command.type, success: true, disposition: "started" });
+	if (promptCount === 1) {
+		send({
+			type: "message_end",
+			message: { role: "assistant", stopReason: "toolUse", content: [], usage: usage(10, 2) },
+		});
+		send({ type: "tool_execution_start", toolCallId: "fake-read-1", toolName: "read", args: { path: "package.json" } });
+		send({ type: "tool_execution_end", toolCallId: "fake-read-1", toolName: "read", isError: false, result: { usage: usage(3, 1) } });
+		if (scenario === "missing-boundary") {
+			send({
+				type: "message_end",
+				message: { role: "assistant", stopReason: "stop", content: [{ type: "text", text: "unsafe final response after tool" }], usage: usage(2, 2) },
+			});
+		} else {
+			process.send?.({ type: "task_dispatcher_boundary", turnIndex: 0, toolResults: 1 });
+			send({
+				type: "message_end",
+				message: { role: "assistant", stopReason: "error", errorMessage: "This operation was aborted", content: [] },
+			});
+		}
+		send({ type: "agent_settled" });
+		return;
+	}
+
+	send({
+		type: "message_end",
+		message: {
+			role: "assistant",
+			stopReason: "stop",
+			content: [{ type: "text", text: "deterministic worker complete" }],
+			usage: usage(5, 3),
+		},
+	});
+	send({ type: "agent_settled" });
+});

package/tests/gate-probe.mjs

@@ -0,0 +1,150 @@
+/**
+ * Verify that a worker-side turn boundary can abort Pi after a completed tool batch while keeping the RPC child reusable.
+ */
+
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+
+// Resolve the managed Pi release without embedding a machine-specific installation path.
+async function resolvePiCli() {
+	const installRoot = process.env.PI_MANAGED_INSTALL_ROOT ?? path.join(homedir(), ".pi", "agent", "install");
+	const version = (await readFile(path.join(installRoot, "current-version"), "utf8")).trim();
+	const packageRoot = path.join(installRoot, "releases", version, "node_modules", "@earendil-works", "pi-coding-agent");
+	const packageJson = JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8"));
+	const declaredBin = typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin?.pi;
+	if (!declaredBin) throw new Error("The managed Pi package does not declare its CLI entry point.");
+	return path.resolve(packageRoot, declaredBin);
+}
+
+const cliPath = await resolvePiCli();
+const temporaryDirectory = await mkdtemp(path.join(tmpdir(), "pi-task-dispatcher-gate-probe-"));
+const gatePath = path.join(temporaryDirectory, "gate.ts");
+let child;
+
+try {
+	// Abort the active worker run only after its complete tool batch has been persisted.
+	await writeFile(
+		gatePath,
+		`import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function (pi: ExtensionAPI): void {
+	pi.on("turn_end", async (event, ctx) => {
+		if (event.toolResults.length === 0) return;
+		if (typeof process.send === "function") process.send({
+			type: "task_dispatcher_boundary",
+			turnIndex: event.turnIndex,
+			toolResults: event.toolResults.length,
+		});
+		ctx.abort();
+	});
+}
+`,
+		"utf8",
+	);
+
+	// Prefer explicit test overrides, then the active parent Pi model exported in PI_* variables.
+	const activeModel = process.env.PI_TASK_DISPATCHER_GATE_MODEL
+		?? (process.env.PI_PROVIDER && process.env.PI_MODEL ? `${process.env.PI_PROVIDER}/${process.env.PI_MODEL}` : undefined);
+	const activeThinking = process.env.PI_TASK_DISPATCHER_GATE_THINKING ?? process.env.PI_REASONING_LEVEL;
+	const workerArgs = [
+		cliPath,
+		"--mode",
+		"rpc",
+		"--no-session",
+		"--no-extensions",
+		"--tools",
+		"read",
+		"--extension",
+		gatePath,
+	];
+	if (activeModel) workerArgs.push("--model", activeModel);
+	if (activeThinking) workerArgs.push("--thinking", activeThinking);
+
+	child = spawn(
+		process.execPath,
+		workerArgs,
+		{
+			cwd: path.resolve(import.meta.dirname, ".."),
+			stdio: ["pipe", "pipe", "pipe", "ipc"],
+			env: { ...process.env, PI_TASK_DISPATCHER_WORKER: "probe" },
+		},
+	);
+
+	const events = [];
+	const boundaries = [];
+	let stderr = "";
+	let settledResolve;
+	let settled = new Promise((resolve) => {
+		settledResolve = resolve;
+	});
+
+	// Collect public RPC events independently from the private boundary signal.
+	readline.createInterface({ input: child.stdout }).on("line", (line) => {
+		if (!line.trim()) return;
+		const event = JSON.parse(line);
+		events.push(event);
+		if (event.type === "agent_settled") settledResolve();
+	});
+	child.stderr.on("data", (chunk) => {
+		stderr += chunk.toString();
+	});
+	child.on("message", (message) => boundaries.push(message));
+
+	// Run one tool batch and require the gate to settle the run before a productive follow-up turn.
+	child.stdin.write(`${JSON.stringify({
+		id: "probe-1",
+		type: "prompt",
+		message: "Read package.json exactly once. Do not use any other tool. After reading it, report only its package name.",
+	})}\n`);
+	await Promise.race([
+		settled,
+		new Promise((_, reject) => setTimeout(() => reject(new Error("First gated run did not settle.")), 120_000)),
+	]);
+
+	const firstAssistantMessages = events.filter((event) => event.type === "message_end" && event.message?.role === "assistant");
+	const firstBoundaryCount = boundaries.filter((message) => message?.type === "task_dispatcher_boundary").length;
+	if (firstBoundaryCount !== 1) throw new Error(`Expected one private boundary, observed ${firstBoundaryCount}.`);
+	if (!firstAssistantMessages.some((event) => event.message?.stopReason === "toolUse")) {
+		throw new Error("The first run did not execute the expected tool-use turn.");
+	}
+
+	// Continue in the same in-memory RPC session and require a normal final answer without another tool batch.
+	events.length = 0;
+	settled = new Promise((resolve) => {
+		settledResolve = resolve;
+	});
+	child.stdin.write(`${JSON.stringify({
+		id: "probe-2",
+		type: "prompt",
+		message: "Continue from the completed read. Do not call tools. Report only the package name.",
+	})}\n`);
+	await Promise.race([
+		settled,
+		new Promise((_, reject) => setTimeout(() => reject(new Error("Continuation run did not settle.")), 120_000)),
+	]);
+
+	const finalText = events
+		.filter((event) => event.type === "message_end" && event.message?.role === "assistant")
+		.flatMap((event) => event.message.content ?? [])
+		.filter((part) => part.type === "text")
+		.map((part) => part.text)
+		.join("\n")
+		.trim();
+	if (!finalText.includes("pi-task-dispatcher")) throw new Error(`Unexpected continuation output: ${finalText}`);
+
+	console.log(JSON.stringify({ firstBoundaryCount, firstAssistantMessages: firstAssistantMessages.length, finalText }, null, 2));
+	if (stderr.trim()) console.error(stderr.trim());
+} finally {
+	// Close the reusable child and remove only the runtime-controlled probe directory.
+	if (child && child.exitCode === null && child.signalCode === null) {
+		child.stdin?.end();
+		await Promise.race([
+			new Promise((resolve) => child.once("close", resolve)),
+			new Promise((resolve) => setTimeout(resolve, 5_000)),
+		]);
+		if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+	}
+	await rm(temporaryDirectory, { recursive: true, force: true });
+}

package/tests/static-check.mjs

@@ -0,0 +1,38 @@
+/**
+ * Check release invariants that do not require a configured worker model or network request.
+ */
+
+import { readFile } from "node:fs/promises";
+
+const packageJson = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+const source = await readFile(new URL("../extensions/task-dispatcher.ts", import.meta.url), "utf8");
+const gateProbe = await readFile(new URL("./gate-probe.mjs", import.meta.url), "utf8");
+
+// Keep task budgets formula-owned and prevent accidental restoration of the v2 role limits.
+for (const forbidden of ["checkpointGraceSeconds", "timeoutSeconds", "maxTurns"]) {
+	if (source.includes(forbidden)) throw new Error(`Removed v2 task-budget field remains in source: ${forbidden}`);
+}
+
+// Keep runtime and live tests provider/model agnostic unless the caller explicitly supplies an override.
+for (const forbidden of ["gpt-5.6-luna", "gpt-5.6-terra", "openai-codex/"]) {
+	if (`${source}\n${gateProbe}`.includes(forbidden)) throw new Error(`Hardcoded model assumption remains: ${forbidden}`);
+}
+if (!source.includes("let model = ctx.model")) throw new Error("Role defaults no longer inherit the active model.");
+
+// Require the supervised protocol and its externally enforced gate in every v3 candidate.
+for (const required of [
+	"delegate_control",
+	"delegate_status",
+	"task_dispatcher_boundary",
+	"without an enforced IPC boundary",
+	"--no-extensions",
+	"ctx.abort()",
+	"set_auto_compaction",
+	"get_session_stats",
+	"renderResult",
+]) {
+	if (!source.includes(required)) throw new Error(`Missing supervised-protocol marker: ${required}`);
+}
+
+if (!String(packageJson.version).startsWith("3.")) throw new Error(`Expected a v3 package version, found ${packageJson.version}`);
+console.log(`Static supervised-protocol checks passed for ${packageJson.name}@${packageJson.version}.`);