pi-roundtable-coding 0.7.4 → 0.7.5

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [0.7.5] - 2026-10-03
+
+- Add `workerBlockText`, `limits` and `diagnosticChars`; git, gh and worker error text and the report and held-action bounds can be raised or lifted by the host.
+
 ## [0.7.4] - 2026-10-03
 
 - Add `toolText` and `presentation.list`, accept a 7–40 character sha prefix in `repo_push`, name git and gh stderr (scrubbed) in failures, carry a worker's own error text into the report, restore the earlier timeout, stop and refusal wording, stop listing declined calls as held, and report the channels the service works for.

package/README.md

@@ -121,7 +121,7 @@ Without `threads`, the resolved report channel's prompts are used.
 `timeoutMs` must be positive and finite, and at most 2,147,483,647 ms to fit the host timer.
 An approved call runs; a declined, expired, missing or failed card blocks it and instructs the worker not to retry or work around the refusal.
 Unapproved actions appear in the report rather than running later automatically.
-Worker answers are capped at 20,000 characters; the Held list keeps ten entries of at most 1,000 characters each, with explicit truncation and omission notices.
+By default worker answers are capped at 20,000 characters and the Held list keeps ten entries of at most 1,000 characters each, with explicit truncation and omission notices; `limits` changes each bound.
 Worker failures expose only a structured exit category and numeric code, never stderr or provider diagnostics.
 Card expiration is determined by the host's surface implementation, not this package.
 
@@ -172,6 +172,9 @@ The `CODING` service exposes `shelf: RepoShelf` and `desk: CodingDesk` for trust
 | `threadText` | English package text | Thread introduction, held-action notice, approval title and final report. |
 | `workerWorkspace` | individual clone | Trusted shell-policy write boundary; not an OS sandbox. |
 | `workerPrompt` | generic worker instructions | Trusted standing prompt replacement; it cannot bypass approval or cleanup. |
+| `workerBlockText` | "The owner declined / has not approved this call. Do not retry it or work around it; list it under Held in your report." | Trusted wording of what the worker reads when a call is declined or held, from `(answer, action)`; it never changes who is held, and the desk lists only unanswered calls as held. |
+| `limits` | 20,000 report characters, 10 held entries of 1,000 characters | `{ reportChars?, heldEntries?, heldChars? }`: what a report keeps of a long run; each is a whole number of at least 1, or `Infinity` for no bound. |
+| `diagnosticChars` | `600` | Longest git, gh and worker error text kept in a failure; a whole number of at least 1, or `Infinity`. |
 | `skipUnavailableCarriedSkills` | `false` | Skip and disclose unavailable implicit skills; explicit skill requests still refuse them. |
 | `workerPackages` | `[]` | Absolute installed extension paths. |
 | `agentDir` | Pi host directory | Pi credentials and model configuration. |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable-coding",
-	"version": "0.7.4",
+	"version": "0.7.5",
 	"description": "Repository shelves and owner-approved Pi coding workers for pi-roundtable",
 	"type": "module",
 	"license": "MIT",
@@ -44,7 +44,7 @@
 		"@earendil-works/pi-ai": ">=1.0.0 <2",
 		"@biomejs/biome": "2.5.15",
 		"@types/bun": "1.4.2",
-		"pi-roundtable": "0.7.4",
+		"pi-roundtable": "0.7.5",
 		"typescript": "7.0.2"
 	}
 }

package/src/coding-desk.ts

@@ -64,6 +64,26 @@ export interface CodingDeskOptions {
 	deliver(result: CodingResult): Promise<void>;
 	logger: Logger;
 	timeoutMs?: number;
+	limits?: CodingLimits;
+}
+/** What a coding report keeps of a long run; each is a count of characters or entries, or `Infinity` for no bound. */
+export interface CodingLimits {
+	/** Longest worker report, and longest thread report; default 20,000 characters. */
+	reportChars?: number;
+	/** Held actions listed in the report, the rest counted; default 10. */
+	heldEntries?: number;
+	/** Longest held-action entry; default 1,000 characters. */
+	heldChars?: number;
+}
+export function checkLimit(name: string, value: number | undefined): void {
+	if (
+		value !== undefined &&
+		value !== Number.POSITIVE_INFINITY &&
+		(!Number.isSafeInteger(value) || value < 1)
+	)
+		throw new Error(
+			`${name} must be a whole number of at least 1, or Infinity; got ${value}.`,
+		);
 }
 export const MAX_CODING_TASK_CHARS = 8_000;
 const MAX_REPORT_CHARS = 20_000;
@@ -182,6 +202,10 @@ export class CodingDesk {
 		const slot = promptSlot();
 		const held: string[] = [];
 		let omittedHeld = 0;
+		const maxReport = this.#options.limits?.reportChars ?? MAX_REPORT_CHARS;
+		const maxHeldEntries =
+			this.#options.limits?.heldEntries ?? MAX_HELD_ENTRIES;
+		const maxHeldChars = this.#options.limits?.heldChars ?? MAX_HELD_CHARS;
 		let cancel = () => {};
 		let timedOut = false;
 		let outcome: CodingResult["outcome"];
@@ -232,10 +256,10 @@ export class CodingDesk {
 				}
 				// A call the owner declined is settled, not held for the report.
 				if (answer === "held") {
-					if (held.length < MAX_HELD_ENTRIES) {
+					if (held.length < maxHeldEntries) {
 						const entry = bounded(
 							`${call.action}: ${call.tool} ${call.input}`,
-							MAX_HELD_CHARS,
+							maxHeldChars,
 						);
 						held.push(entry);
 						try {
@@ -256,7 +280,7 @@ export class CodingDesk {
 			);
 			if (controller.signal.aborted)
 				throw new AgentError("the worker was stopped");
-			outcome = { ok: true, report: bounded(report, MAX_REPORT_CHARS) };
+			outcome = { ok: true, report: bounded(report, maxReport) };
 		} catch (error) {
 			// The host's own refusals and the worker's scrubbed, bounded error text reach the report.
 			let message =
@@ -302,7 +326,7 @@ export class CodingDesk {
 				bounded(
 					threadText?.report?.(result) ??
 						codingReport(result, job.startedAt.toISOString()),
-					MAX_REPORT_CHARS,
+					maxReport,
 				),
 			);
 		} catch {

package/src/coding-plugin.ts

@@ -21,9 +21,11 @@ import { Type } from "typebox";
 import {
 	CodingDesk,
 	type CodingJob,
+	type CodingLimits,
 	type CodingResult,
 	type CodingThreadText,
 	type CodingWorker,
+	checkLimit,
 	codingReport,
 	MAX_CODING_TASK_CHARS,
 } from "./coding-desk.ts";
@@ -97,6 +99,12 @@ export interface CodingOptions {
 	threadText?: CodingThreadText;
 	workerWorkspace?: string;
 	workerPrompt?: (dir: string) => string;
+	/** How much of a long run a report keeps; see `CodingLimits`. */
+	limits?: CodingLimits;
+	/** Longest git, gh and worker error text kept in a failure, in characters; default 600. */
+	diagnosticChars?: number;
+	/** Trusted wording of what the worker reads when a call is declined or held; see `PiCodingWorkerOptions.blockText`. */
+	workerBlockText?: (answer: "declined" | "held", action: string) => string;
 	/** Opt in to skipping unavailable implicit skills; explicit requests always fail closed. */
 	skipUnavailableCarriedSkills?: boolean;
 	/** Absolute installed extension package paths. Default: none. */
@@ -126,6 +134,16 @@ export function coding(options: CodingOptions) {
 	if (!options.shelfDir.trim()) throw new PluginError("shelfDir is required.");
 	if (!/^[^/\s]+\/\S+$/.test(options.model))
 		throw new PluginError("model must be provider/model-id.");
+	try {
+		checkLimit("limits.reportChars", options.limits?.reportChars);
+		checkLimit("limits.heldEntries", options.limits?.heldEntries);
+		checkLimit("limits.heldChars", options.limits?.heldChars);
+		checkLimit("diagnosticChars", options.diagnosticChars);
+	} catch (error) {
+		throw new PluginError(
+			error instanceof Error ? error.message : String(error),
+		);
+	}
 	const ownerRepos = new Set(options.ownerRepos ?? []);
 	for (const repo of ownerRepos) checkRepoName(repo);
 	const ownerOwned = (repo: string): boolean => {
@@ -136,7 +154,9 @@ export function coding(options: CodingOptions) {
 		name: "coding",
 		provides: [CODING],
 		setup(context) {
-			const shelf = new RepoShelf(options.shelfDir, options.clone);
+			const shelf = new RepoShelf(options.shelfDir, options.clone, {
+				diagnosticChars: options.diagnosticChars,
+			});
 			for (const adoption of options.adoptClones ?? [])
 				shelf.adopt(adoption.from, adoption.repo);
 			const skills = context.services.find(SKILLS);
@@ -147,6 +167,8 @@ export function coding(options: CodingOptions) {
 					agentDir: options.agentDir,
 					workspace: options.workerWorkspace,
 					prompt: options.workerPrompt,
+					blockText: options.workerBlockText,
+					diagnosticChars: options.diagnosticChars,
 					holds: (tool, input, scope) =>
 						options.holds?.(tool, input, scope) ??
 						context.sessions().holds(tool, input, scope),
@@ -155,6 +177,7 @@ export function coding(options: CodingOptions) {
 				shelf,
 				worker,
 				timeoutMs: options.timeoutMs,
+				limits: options.limits,
 				logger: context.logger,
 				threads: options.threads,
 				threadText: options.threadText,

package/src/index.ts

@@ -1,6 +1,7 @@
 export type {
 	CodingDeskOptions,
 	CodingJob,
+	CodingLimits,
 	CodingResult,
 	CodingThreadText,
 	CodingWorker,

package/src/pi-coding-worker.ts

@@ -16,6 +16,13 @@ export interface PiCodingWorkerOptions {
 	workspace?: string;
 	/** Trusted host standing prompt, replacing the generic worker instructions. */
 	prompt?: (dir: string) => string;
+	/**
+	 * Trusted wording of what the worker reads when a call is not approved, given what the call
+	 * would do. Default: the owner declined or has not approved it; list it under Held in the report.
+	 */
+	blockText?: (answer: "declined" | "held", action: string) => string;
+	/** Longest worker error text kept for the report, in characters; default 600. */
+	diagnosticChars?: number;
 }
 interface WorkerMessage {
 	type: string;
@@ -82,7 +89,12 @@ export class PiCodingWorker implements CodingWorker {
 						value.type === "failure" &&
 						typeof value.message === "string"
 					) {
-						failure = value.message.slice(0, 2_000);
+						failure = value.message.slice(
+							0,
+							this.#options.diagnosticChars === undefined
+								? 2_000
+								: this.#options.diagnosticChars * 4,
+						);
 					} else if (
 						value.type === "call" &&
 						Number.isSafeInteger(value.id) &&
@@ -93,6 +105,7 @@ export class PiCodingWorker implements CodingWorker {
 						const { id, tool, input } = value;
 						void (async () => {
 							let answer: HeldCallAnswer = "held";
+							let reason: string | undefined;
 							try {
 								const context = {
 									workspace: this.#options.workspace ?? job.dir,
@@ -108,12 +121,19 @@ export class PiCodingWorker implements CodingWorker {
 												action,
 											})
 										: "approved";
+									if (action && answer !== "approved")
+										reason = this.#options.blockText?.(answer, action);
 								}
 							} catch {
 								/* Fail closed. */
 							}
 							if (!signal.aborted && child.exitCode === null)
-								proc.send({ type: "answer", id, answer });
+								proc.send({
+									type: "answer",
+									id,
+									answer,
+									...(reason ? { reason } : {}),
+								});
 						})();
 					}
 				},
@@ -131,7 +151,13 @@ export class PiCodingWorker implements CodingWorker {
 			if (signal.aborted) kill();
 			const code = await child.exited;
 			if (signal.aborted) throw new CodingWorkerFailure("stopped");
-			if (code !== 0) throw new CodingWorkerFailure("exit", code, failure);
+			if (code !== 0)
+				throw new CodingWorkerFailure(
+					"exit",
+					code,
+					failure,
+					this.#options.diagnosticChars,
+				);
 			if (!report?.trim()) throw new CodingWorkerFailure("missing-report");
 			return report;
 		} finally {

package/src/repo-shelf.ts

@@ -87,25 +87,28 @@ async function run(
 	return { out: out.trimEnd(), err: err.trim(), code };
 }
 
-/** Clones with gh, which authenticates with the host's GH_TOKEN. */
-export const ghClone: CloneCommand = async (repo, dir) => {
-	checkRepoName(repo);
-	if (repo.startsWith("-"))
-		throw new AgentError("Repository owner cannot start with a dash.");
-	const { err, code } = await run([
-		"gh",
-		"repo",
-		"clone",
-		repo,
-		dir,
-		"--",
-		"--quiet",
-	]);
-	if (code !== 0)
-		throw new AgentError(
-			`Cloning ${repo} failed: ${scrubDiagnostic(err) || `exit ${code}`}`,
-		);
-};
+/** Clones with gh, which authenticates with the host's GH_TOKEN; a failure's stderr is cut at `diagnosticChars`. */
+const ghCloneWith =
+	(diagnosticChars?: number): CloneCommand =>
+	async (repo, dir) => {
+		checkRepoName(repo);
+		if (repo.startsWith("-"))
+			throw new AgentError("Repository owner cannot start with a dash.");
+		const { err, code } = await run([
+			"gh",
+			"repo",
+			"clone",
+			repo,
+			dir,
+			"--",
+			"--quiet",
+		]);
+		if (code !== 0)
+			throw new AgentError(
+				`Cloning ${repo} failed: ${scrubDiagnostic(err, diagnosticChars) || `exit ${code}`}`,
+			);
+	};
+export const ghClone: CloneCommand = ghCloneWith();
 
 const MAX_METADATA_BYTES = 65_536;
 
@@ -175,9 +178,16 @@ export class RepoShelf {
 	readonly #reports = new Map<string, ChangeReport>();
 	readonly #adding = new Set<string>();
 
-	constructor(dir: string, clone: CloneCommand = ghClone) {
+	readonly #diagnosticChars: number | undefined;
+
+	constructor(
+		dir: string,
+		clone?: CloneCommand,
+		options: { diagnosticChars?: number | undefined } = {},
+	) {
 		this.dir = resolve(dir);
-		this.#clone = clone;
+		this.#diagnosticChars = options.diagnosticChars;
+		this.#clone = clone ?? ghCloneWith(options.diagnosticChars);
 	}
 
 	/** Adopt an existing standalone clone at startup; an existing destination is never replaced. */
@@ -483,7 +493,7 @@ export class RepoShelf {
 		const { out, err, code } = await run(["git", "-C", dir, ...args]);
 		if (code !== 0)
 			throw new AgentError(
-				`git ${args[0]} failed in ${dir}: ${scrubDiagnostic(err) || `exit ${code}`}`,
+				`git ${args[0]} failed in ${dir}: ${scrubDiagnostic(err, this.#diagnosticChars) || `exit ${code}`}`,
 			);
 		return out;
 	}

package/src/worker-entry.ts

@@ -31,7 +31,10 @@ export function codingWorkerPrompt(dir: string): string {
 		"Report changes and reasons, commits, checks and outcomes, held actions, and remaining work.",
 	].join("\n\n");
 }
-const answers = new Map<number, (answer: HeldCallAnswer) => void>();
+const answers = new Map<
+	number,
+	(answer: HeldCallAnswer, reason?: string) => void
+>();
 let nextId = 1;
 let started = false;
 async function run({
@@ -76,8 +79,11 @@ async function run({
 				factory: (pi) => {
 					pi.on("tool_call", async (event) => {
 						const id = nextId++;
-						const answer = await new Promise<HeldCallAnswer>((resolve) => {
-							answers.set(id, resolve);
+						const { answer, reason } = await new Promise<{
+							answer: HeldCallAnswer;
+							reason?: string | undefined;
+						}>((resolve) => {
+							answers.set(id, (answer, reason) => resolve({ answer, reason }));
 							process.send?.({
 								type: "call",
 								id,
@@ -88,7 +94,9 @@ async function run({
 						if (answer !== "approved")
 							return {
 								block: true,
-								reason: `The owner ${answer === "declined" ? "declined" : "has not approved"} this call. Do not retry it or work around it; list it under Held in your report.`,
+								reason:
+									reason ??
+									`The owner ${answer === "declined" ? "declined" : "has not approved"} this call. Do not retry it or work around it; list it under Held in your report.`,
 							};
 						return undefined;
 					});
@@ -128,7 +136,12 @@ if (process.send) {
 				message.answer === "declined" ||
 				message.answer === "held")
 		) {
-			answers.get(message.id)?.(message.answer);
+			answers.get(message.id)?.(
+				message.answer,
+				"reason" in message && typeof message.reason === "string"
+					? message.reason
+					: undefined,
+			);
 			answers.delete(message.id);
 		} else if (message.type === "start" && !started) {
 			started = true;

package/src/worker-failure.ts

@@ -6,8 +6,9 @@ export class CodingWorkerFailure extends AgentError {
 		readonly category: "stopped" | "exit" | "missing-report",
 		readonly exitCode?: number,
 		detail?: string,
+		diagnosticChars?: number,
 	) {
-		const reason = detail ? scrubDiagnostic(detail) : "";
+		const reason = detail ? scrubDiagnostic(detail, diagnosticChars) : "";
 		let message = "the worker was stopped";
 		if (category === "exit")
 			message =