pi-task-dispatcher 3.1.0 → 3.1.2

package/README.md

@@ -67,6 +67,8 @@ Every role tool requires:
 - `tools`: the smallest exact allowlist selected from Pi's built-in tools and active for the main agent;
 - `workload`: semantic estimates used by the deterministic budget formula.
 
+When `codemode` is active and delegated work materially benefits from JavaScript orchestration, batched/parallel/filtering of selected tools, or classifier/image models, include it in the delegated allowlist rather than reserving it for the manager. Also include each direct tool its script must call; otherwise omit `codemode`.
+
 ```json
 {
   "task": "Inspect the parser cache, correct its invalidation, and run the focused tests.",

package/extensions/task-dispatcher.ts

@@ -283,9 +283,12 @@ const WorkloadSchema = Type.Object({
 	expectedLongRunningSeconds: Type.Integer({ minimum: 0, maximum: 3_600 }),
 });
 
+/** Tell managers when a codemode delegation grant is warranted without granting it automatically. */
+const CODEMODE_SELECTION_GUIDANCE = "When codemode is active and delegated work materially benefits from JavaScript orchestration, batched/parallel/filtering of selected tools, or classifier/image models, include codemode in the delegated allowlist rather than reserving it for the manager; also include each direct tool the codemode script must call; otherwise omit it.";
+
 const DelegateParams = Type.Object({
 	task: Type.String({ minLength: 1, maxLength: 12_000 }),
-	tools: Type.Array(Type.String({ minLength: 1 }), { maxItems: 32 }),
+	tools: Type.Array(Type.String({ minLength: 1 }), { maxItems: 32, description: CODEMODE_SELECTION_GUIDANCE }),
 	workload: WorkloadSchema,
 });
 
@@ -1644,6 +1647,7 @@ function registerDelegate(pi: ExtensionAPI, role: Role): void {
 			...(role === "assistant"
 				? ["When no other worker role applies, use delegate_assistant for the user-requested work instead of performing it directly. Retain delegation decisions, worker supervision, result integration, and the final response."]
 				: []),
+			CODEMODE_SELECTION_GUIDANCE,
 			"Supply semantic workload units rather than raw turn or timeout values.",
 			"Inspect every paused state and choose continue, revise, recalculate, compact, checkpoint, cancel, or take over.",
 			"Worker reports remain evidence to review, not proof of correctness.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-task-dispatcher",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "description": "Run configurable Pi worker models as supervised, observable, resumable jobs.",
   "type": "module",
   "keywords": [
@@ -26,7 +26,7 @@
   "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"
+    "check": "node tests/static-check.mjs && node tests/strict-jsonl-check.mjs && node tests/fake-rpc-check.mjs"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/tests/fake-rpc-check.mjs

@@ -70,6 +70,14 @@ try {
 	const control = tools.get("delegate_control");
 	assert(start && designerStart && control, "Expected supervised tools to register.");
 	assert(tools.has("delegate_mechanical") && tools.has("delegate_assistant"), "Expected every worker role to register.");
+	// Validate the shared least-privilege codemode guidance through every registered delegation surface.
+	const schemaGuidance = tools.get("delegate_mechanical").parameters.properties.tools.description;
+	assert.match(schemaGuidance, /codemode.*allowlist.*direct tool.*otherwise omit/i, "Schema guidance no longer describes the codemode delegation rule.");
+	for (const name of ["delegate_mechanical", "delegate_assistant", "delegate_engineering", "delegate_designer"]) {
+		const delegate = tools.get(name);
+		assert.equal(delegate.parameters.properties.tools.description, schemaGuidance, `${name} does not expose the shared codemode guidance in its tools schema.`);
+		assert(delegate.promptGuidelines.includes(schemaGuidance), `${name} does not expose the schema codemode guidance in its manager prompt metadata.`);
+	}
 	const theme = { fg(_color, text) { return text; }, bold(text) { return text; } };
 	let rendererInvalidations = 0;
 	const renderContext = { args: {}, state: {}, invalidate() { rendererInvalidations++; }, cwd: projectRoot };

package/tests/fake-rpc-worker.mjs

@@ -1,7 +1,7 @@
 /** Deterministic JSONL/IPC worker used only by the dispatcher's lifecycle tests. */
 
 import { appendFile, readFile } from "node:fs/promises";
-import readline from "node:readline";
+import { readStrictJsonl } from "./strict-jsonl.mjs";
 
 const scenario = process.env.PI_TASK_DISPATCHER_FAKE_SCENARIO ?? "normal";
 const markerPath = process.env.PI_TASK_DISPATCHER_FAKE_PROMPT_MARKER;
@@ -22,7 +22,8 @@ function usage(input, output) {
 	};
 }
 
-readline.createInterface({ input: process.stdin }).on("line", async (line) => {
+// Process strict LF-framed RPC commands in order, including asynchronous scenario handlers.
+await readStrictJsonl(process.stdin, async (line) => {
 	if (!line.trim()) return;
 	const command = JSON.parse(line);
 	if (command.type === "set_auto_compaction") {

package/tests/gate-probe.mjs

@@ -6,7 +6,7 @@ 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";
+import { readStrictJsonl } from "./strict-jsonl.mjs";
 
 // Resolve the managed Pi release without embedding a machine-specific installation path.
 async function resolvePiCli() {
@@ -25,6 +25,7 @@ const gatePath = path.join(temporaryDirectory, "gate.ts");
 const codemodeOnlyPath = path.join(temporaryDirectory, "codemode-only.ts");
 const readProbePath = path.join(temporaryDirectory, "codemode-read-probe.txt");
 let child;
+let stdoutRecords;
 
 try {
 	// Abort the active worker run only after its complete tool batch has been persisted.
@@ -96,13 +97,18 @@ export default function codemodeOnlyExtension(pi: ExtensionAPI): void {
 		settledResolve = resolve;
 	});
 
-	// Collect public RPC events independently from the private boundary signal.
-	readline.createInterface({ input: child.stdout }).on("line", (line) => {
+	// Collect public LF-framed RPC events independently from the private boundary signal.
+	stdoutRecords = readStrictJsonl(child.stdout, (line) => {
 		if (!line.trim()) return;
 		const event = JSON.parse(line);
 		events.push(event);
 		if (event.type === "agent_settled") settledResolve();
 	});
+	// Surface malformed or unterminated child output during either gated wait without unhandled rejections.
+	const stdoutFramingFailure = new Promise((_, reject) => {
+		void stdoutRecords.catch(reject);
+	});
+	void stdoutFramingFailure.catch(() => undefined);
 	child.stderr.on("data", (chunk) => {
 		stderr += chunk.toString();
 	});
@@ -116,6 +122,7 @@ export default function codemodeOnlyExtension(pi: ExtensionAPI): void {
 	})}\n`);
 	await Promise.race([
 		settled,
+		stdoutFramingFailure,
 		new Promise((_, reject) => setTimeout(() => reject(new Error("First gated run did not settle.")), 120_000)),
 	]);
 
@@ -147,6 +154,7 @@ export default function codemodeOnlyExtension(pi: ExtensionAPI): void {
 	})}\n`);
 	await Promise.race([
 		settled,
+		stdoutFramingFailure,
 		new Promise((_, reject) => setTimeout(() => reject(new Error("Continuation run did not settle.")), 120_000)),
 	]);
 
@@ -162,14 +170,19 @@ export default function codemodeOnlyExtension(pi: ExtensionAPI): void {
 	console.log(JSON.stringify({ firstBoundaryCount, firstAssistantMessages: firstAssistantMessages.length, finalText, nativeCodemodeOnly: true }, 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");
+	try {
+		// Close the reusable child before validating that its final stdout tail was LF-framed.
+		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");
+		}
+		if (stdoutRecords) await stdoutRecords;
+	} finally {
+		// Remove only the runtime-controlled probe directory, even when stdout framing failed.
+		await rm(temporaryDirectory, { recursive: true, force: true });
 	}
-	await rm(temporaryDirectory, { recursive: true, force: true });
 }

package/tests/static-check.mjs

@@ -5,8 +5,11 @@
 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");
+const [source, gateProbe, fakeRpcWorker] = await Promise.all([
+	readFile(new URL("../extensions/task-dispatcher.ts", import.meta.url), "utf8"),
+	readFile(new URL("./gate-probe.mjs", import.meta.url), "utf8"),
+	readFile(new URL("./fake-rpc-worker.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"]) {
@@ -49,7 +52,11 @@ for (const required of [
 	if (!source.includes(required)) throw new Error(`Missing supervised-protocol marker: ${required}`);
 }
 
-if (packageJson.version !== "3.1.0") throw new Error(`Expected release version 3.1.0, found ${packageJson.version}`);
+if (packageJson.version !== "3.1.1") throw new Error(`Expected release version 3.1.1, found ${packageJson.version}`);
+// Keep test-side RPC framing independent from readline's broader line-separator behavior.
+for (const [name, reader] of [["fake RPC worker", fakeRpcWorker], ["gate probe", gateProbe]]) {
+	if (reader.includes("node:readline")) throw new Error(`${name} still imports node:readline.`);
+}
 if (source.includes("builtin:codemode")) throw new Error("The dispatcher must not load codemode through a built-in extension selector.");
 if (!gateProbe.includes("createCodemodeExtension") || !gateProbe.includes('mode: "only"')) {
 	throw new Error("The live gate probe does not exercise the native codemode-only extension.");

package/tests/strict-jsonl-check.mjs

@@ -0,0 +1,48 @@
+/**
+ * Verify the strict UTF-8 JSONL framing contract used by RPC-oriented test readers.
+ */
+
+import assert from "node:assert/strict";
+import { Readable } from "node:stream";
+import { readStrictJsonl } from "./strict-jsonl.mjs";
+
+const encoder = new TextEncoder();
+
+/** Collect records from deliberately controlled byte chunks. */
+async function collectRecords(chunks) {
+	const records = [];
+	await readStrictJsonl(Readable.from(chunks), async (record) => {
+		records.push(record);
+	});
+	return records;
+}
+
+// Keep raw JSON string separators as payload instead of treating them as record boundaries.
+const rawSeparatorValue = `before${String.fromCodePoint(0x2028)}middle${String.fromCodePoint(0x2029)}after`;
+const rawSeparatorRecord = `{"value":"${rawSeparatorValue}"}`;
+const separatorRecords = await collectRecords([encoder.encode(`${rawSeparatorRecord}\n`)]);
+assert.deepEqual(separatorRecords, [rawSeparatorRecord]);
+assert.equal(JSON.parse(separatorRecords[0]).value, rawSeparatorValue);
+assert.doesNotMatch(rawSeparatorRecord, /\\u2028|\\u2029/);
+
+// Split a four-byte character mid-sequence to require streaming UTF-8 decoding.
+const multibyteRecord = JSON.stringify({ value: "split 🧪 UTF-8" });
+const multibyteBytes = encoder.encode(`${multibyteRecord}\n`);
+const multibyteStart = multibyteBytes.indexOf(0xf0);
+assert.notEqual(multibyteStart, -1, "Expected the test record to contain a four-byte UTF-8 character.");
+assert.deepEqual(
+	await collectRecords([multibyteBytes.subarray(0, multibyteStart + 1), multibyteBytes.subarray(multibyteStart + 1)]),
+	[multibyteRecord],
+);
+
+// Accept CRLF transport framing while returning the JSON record without its framing CR.
+const crlfRecord = JSON.stringify({ framing: "crlf" });
+assert.deepEqual(await collectRecords([encoder.encode(`${crlfRecord}\r\n`)]), [crlfRecord]);
+
+// Reject a final record that has bytes but no LF terminator.
+await assert.rejects(
+	collectRecords([encoder.encode('{"unfinished":true}')]),
+	/unterminated tail/,
+);
+
+console.log("Strict JSONL framing checks passed.");

package/tests/strict-jsonl.mjs

@@ -0,0 +1,32 @@
+/**
+ * Decode UTF-8 JSONL test streams with LF as the only record delimiter.
+ */
+
+/** Deliver complete LF-framed records while preserving raw Unicode JSON string content. */
+export async function readStrictJsonl(input, onRecord) {
+	const decoder = new TextDecoder("utf-8", { fatal: true });
+	let tail = "";
+
+	/** Emit buffered records and remove at most one CR from each LF terminator. */
+	const emitRecords = async () => {
+		let lineFeed = tail.indexOf("\n");
+		// Drain complete LF-framed records before retaining an incomplete tail.
+		while (lineFeed !== -1) {
+			const record = tail.slice(0, lineFeed);
+			tail = tail.slice(lineFeed + 1);
+			await onRecord(record.endsWith("\r") ? record.slice(0, -1) : record);
+			lineFeed = tail.indexOf("\n");
+		}
+	};
+
+	// Decode chunks incrementally so an incomplete multibyte character cannot become replacement text.
+	for await (const chunk of input) {
+		tail += decoder.decode(chunk, { stream: true });
+		await emitRecords();
+	}
+	// Flush pending decoder bytes before deciding whether the final record was properly framed.
+	tail += decoder.decode();
+	await emitRecords();
+	// Reject a nonempty EOF tail instead of accepting an ambiguous partial JSON record.
+	if (tail !== "") throw new Error("Strict JSONL input ended with an unterminated tail.");
+}