pi-roundtable-coding 0.27.0 → 0.28.0

package/src/coding-plugin.ts

@@ -22,9 +22,11 @@ import {
 } from "pi-roundtable/kit";
 import { Type } from "typebox";
 import {
+	type CodingAutonomy,
 	CodingDesk,
 	type CodingJob,
 	type CodingLimits,
+	type CodingModes,
 	type CodingResult,
 	type CodingThreadText,
 	type CodingWorker,
@@ -76,6 +78,12 @@ export interface CodingPresentation {
 		direct: boolean,
 	): { post: string; result: string };
 	taskStarted?(job: CodingJob, skippedSkills: string[]): string;
+	/** The repo_task result for a task waiting for a worker slot, at `position` (from 1) in the queue. */
+	taskQueued?(
+		job: CodingJob,
+		position: number,
+		skippedSkills: string[],
+	): string;
 }
 export interface CodingOptions {
 	shelfDir: string;
@@ -122,6 +130,18 @@ export interface CodingOptions {
 	workerPackages?: string[];
 	agentDir?: string;
 	timeoutMs?: number;
+	/** Workers running at once on the host; default 4. More tasks wait in a queue. */
+	maxWorkers?: number;
+	/** Tasks waiting for a worker slot, first in first out; one more is refused. Default 16. */
+	maxQueued?: number;
+	/**
+	 * The conversations' modes, such as `context.services.find(MODES)`: a worker then follows the
+	 * yolo and long-running modes of the conversation whose owner turn started it, read live.
+	 * Without them a worker asks a card for every held call and stops at `timeoutMs`.
+	 */
+	modes?: CodingModes;
+	/** The host's resolved `autonomy` limits, which the worker's yolo and long-running modes follow. */
+	autonomy?: CodingAutonomy;
 	/** Optional additional worker rules; linked host rules also apply. */
 	holds?: HoldCheck;
 	/** A different Git host or an offline clone implementation. */
@@ -131,6 +151,35 @@ export interface CodingOptions {
 	/** Override report delivery, for example to schedule a background conversation turn. */
 	onResult?: (result: CodingResult) => Promise<void>;
 }
+/**
+ * The worker's host hold check: the plugin's extra rules, else the linked host rules, with the
+ * classes of every check that holds a call so yolo mode can judge it; a check that holds a call
+ * without telling its classes leaves the call unclassed.
+ */
+function workerHolds(
+	extra: HoldCheck | undefined,
+	linked: () => HoldCheck,
+): HoldCheck {
+	const check: HoldCheck = (tool, input, scope) =>
+		extra?.(tool, input, scope) ?? linked()(tool, input, scope);
+	check.classesOf = (tool, input, scope) => {
+		const found: string[] = [];
+		for (const holds of extra ? [extra, linked()] : [linked()]) {
+			if (holds(tool, input, scope) === undefined) continue;
+			const classes = holds.classesOf?.(tool, input, scope);
+			if (!classes?.length) return undefined;
+			found.push(...classes);
+		}
+		return found.length ? [...new Set(found)] : undefined;
+	};
+	return check;
+}
+function checkCount(name: string, value: number | undefined, least: number) {
+	if (value !== undefined && (!Number.isSafeInteger(value) || value < least))
+		throw new Error(
+			`${name} must be a whole number of at least ${least}; got ${value}.`,
+		);
+}
 async function refusal<T>(operation: () => Promise<T>): Promise<T> {
 	try {
 		return await operation();
@@ -150,6 +199,18 @@ export function coding(options: CodingOptions) {
 		checkLimit("limits.heldEntries", options.limits?.heldEntries);
 		checkLimit("limits.heldChars", options.limits?.heldChars);
 		checkLimit("diagnosticChars", options.diagnosticChars);
+		checkCount("maxWorkers", options.maxWorkers, 1);
+		checkCount("maxQueued", options.maxQueued, 0);
+		const longRunning = options.autonomy?.longRunningMaxMs;
+		if (
+			longRunning !== undefined &&
+			(!Number.isFinite(longRunning) ||
+				longRunning <= 0 ||
+				longRunning > 2_147_483_647)
+		)
+			throw new Error(
+				"autonomy.longRunningMaxMs must be positive, finite and at most 2147483647.",
+			);
 	} catch (error) {
 		throw new PluginError(
 			error instanceof Error ? error.message : String(error),
@@ -185,14 +246,20 @@ export function coding(options: CodingOptions) {
 					prompt: options.workerPrompt,
 					blockText: options.workerBlockText,
 					diagnosticChars: options.diagnosticChars,
-					holds: (tool, input, scope) =>
-						options.holds?.(tool, input, scope) ??
-						context.sessions().holds(tool, input, scope),
+					holds: workerHolds(options.holds, () => context.sessions().holds),
 				});
 			const desk = new CodingDesk({
 				shelf,
 				worker,
 				timeoutMs: options.timeoutMs,
+				...(options.maxWorkers !== undefined
+					? { maxWorkers: options.maxWorkers }
+					: {}),
+				...(options.maxQueued !== undefined
+					? { maxQueued: options.maxQueued }
+					: {}),
+				...(options.modes ? { modes: options.modes } : {}),
+				...(options.autonomy ? { autonomy: options.autonomy } : {}),
 				limits: options.limits,
 				logger: context.logger,
 				threads: options.threads,
@@ -215,23 +282,8 @@ export function coding(options: CodingOptions) {
 						});
 					}),
 			});
-			const shipping = new Set<string>();
-			async function ship<T>(
-				repo: string,
-				operation: () => Promise<T>,
-			): Promise<T> {
-				desk.checkIdle(repo);
-				if (shipping.has(repo))
-					throw new AgentError(
-						"A report or push is already in progress for this repository.",
-					);
-				shipping.add(repo);
-				try {
-					return await operation();
-				} finally {
-					shipping.delete(repo);
-				}
-			}
+			const ship = <T>(repo: string, operation: () => Promise<T>) =>
+				desk.ship(repo, operation);
 			context.services.provide(CODING, { shelf, desk });
 			// Whether the principal holds the owner role; no identity service, or a failed lookup,
 			// tells of no one holding it.
@@ -427,7 +479,7 @@ export function coding(options: CodingOptions) {
 						minTier: "owner",
 						description: describe(
 							"repo_task",
-							"Start one background Pi coding worker in a clone. The worker reads repository instructions, edits, checks and commits; shipping uses a separate report and approval. Report returns to this channel.",
+							"Start a background Pi coding worker on a clone. Each worker has its own worktree and branch, so several may work on one repository; when it finishes, its commits are rebased onto the clone and fast-forwarded, and a conflict keeps the branch and is reported. When every worker slot is taken the task waits in a queue. The worker reads repository instructions, edits, checks and commits; shipping uses a separate report and approval. Report returns to this channel.",
 						),
 						parameters: Type.Object({
 							repo: repoSchema("repo_task"),
@@ -447,7 +499,7 @@ export function coding(options: CodingOptions) {
 									throw new AgentError(
 										"the host's own turns, such as a report's, start no coding tasks; ask the owner to start it",
 									);
-								if (shipping.has(repo))
+								if (desk.shipping(repo))
 									throw new AgentError(
 										"A report or push is in progress for this repository.",
 									);
@@ -472,23 +524,48 @@ export function coding(options: CodingOptions) {
 									model: options.model,
 									thinking: options.thinking ?? "medium",
 								};
-								if (shipping.has(repo))
+								if (desk.shipping(repo))
 									throw new AgentError(
 										"A report or push is in progress for this repository.",
 									);
+								const { speaker } = turn;
 								const job = await desk.start({
 									...run,
+									// Its modes follow the conversation this turn runs in, as the turn's own would.
+									...(speaker
+										? {
+												starter: {
+													channel: turn.channel,
+													speaker: {
+														id: speaker.id,
+														principalId: speaker.principalId,
+														...(speaker.name ? { name: speaker.name } : {}),
+														tier: speaker.tier,
+													},
+												},
+											}
+										: {}),
 									repo,
 									task,
 									skillFiles: set?.skills.map((skill) => skill.file) ?? [],
 									skillNames: set?.skills.map((skill) => skill.name) ?? [],
 								});
+								const skipped = set?.missing.map((item) => item.name) ?? [];
+								const skippedText = skipped.length
+									? ` Unavailable implicit skills skipped: ${skipped.join(", ")}.`
+									: "";
+								if (job.queuePosition !== undefined)
+									return (
+										options.presentation?.taskQueued?.(
+											job,
+											job.queuePosition,
+											skipped,
+										) ??
+										`Queued coding task #${job.id} in ${repo} at position ${job.queuePosition}: every worker slot is taken, and it starts on ${job.model} when one frees. Its report returns to ${job.channel}.${skippedText}`
+									);
 								return (
-									options.presentation?.taskStarted?.(
-										job,
-										set?.missing.map((item) => item.name) ?? [],
-									) ??
-									`Started coding task #${job.id} in ${repo} on ${job.model}; its report returns to ${job.channel}.${set?.missing.length ? ` Unavailable implicit skills skipped: ${set.missing.map((item) => item.name).join(", ")}.` : ""}`
+									options.presentation?.taskStarted?.(job, skipped) ??
+									`Started coding task #${job.id} in ${repo} on ${job.model}; its report returns to ${job.channel}.${skippedText}`
 								);
 							}),
 					}),

package/src/index.ts

@@ -1,14 +1,19 @@
 export type {
+	CodingAutonomy,
 	CodingDeskOptions,
 	CodingJob,
 	CodingLimits,
+	CodingModes,
 	CodingProgress,
 	CodingResult,
+	CodingSpeaker,
+	CodingStart,
+	CodingStarter,
 	CodingThreadText,
 	CodingWorker,
 	HeldCallAnswer,
 } from "./coding-desk.ts";
-export { CodingDesk, codingReport } from "./coding-desk.ts";
+export { CodingDesk, codingReport, integrationText } from "./coding-desk.ts";
 export type {
 	CodingOptions,
 	CodingPresentation,
@@ -23,9 +28,16 @@ export { PiCodingWorker } from "./pi-coding-worker.ts";
 export type {
 	ChangeReport,
 	CloneCommand,
+	Integration,
 	RepoState,
 	RepoSummary,
+	WorkerTree,
+} from "./repo-shelf.ts";
+export {
+	ghClone,
+	RepoShelf,
+	reportPost,
+	WORKTREES_DIR,
 } from "./repo-shelf.ts";
-export { ghClone, RepoShelf, reportPost } from "./repo-shelf.ts";
 export { REPO_TOOLS } from "./repo-tools.ts";
 export { CodingWorkerFailure } from "./worker-failure.ts";

package/src/pi-coding-worker.ts

@@ -1,7 +1,12 @@
 import { fileURLToPath } from "node:url";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { HeldCall, HoldCheck } from "pi-roundtable";
-import { AgentError, canonicalJson, shellHoldRule } from "pi-roundtable/kit";
+import {
+	AgentError,
+	canonicalJson,
+	holdChain,
+	shellHoldRule,
+} from "pi-roundtable/kit";
 import type {
 	CodingJob,
 	CodingProgress,
@@ -55,6 +60,28 @@ function isMessage(value: unknown): value is WorkerMessage {
 	);
 }
 
+/** The worker's own shell rule as a check, for the classes of the calls it holds. */
+const SHELL_CHECK: HoldCheck = holdChain([shellHoldRule]);
+
+/**
+ * The hold classes of a held call, from every check that held it, as the host's gate records them
+ * for yolo mode; undefined when a holding check tells none, which leaves the call unclassed.
+ */
+function classesOf(
+	tool: string,
+	input: Record<string, unknown>,
+	context: { workspace: string; scratchDir?: string },
+	holding: readonly HoldCheck[],
+): string[] | undefined {
+	const found: string[] = [];
+	for (const check of holding) {
+		const classes = check.classesOf?.(tool, input, context);
+		if (!classes?.length) return undefined;
+		found.push(...classes);
+	}
+	return found.length ? [...new Set(found)] : undefined;
+}
+
 /** A fresh Bun process per task; only the host decides whether a held call may run. */
 export class PiCodingWorker implements CodingWorker {
 	readonly #options: PiCodingWorkerOptions;
@@ -149,15 +176,24 @@ export class PiCodingWorker implements CodingWorker {
 										? { scratchDir: this.#options.scratchDir }
 										: {}),
 								};
-								const action =
-									shellHoldRule.describe(tool, input, context) ??
-									this.#options.holds?.(tool, input, context);
+								// Every check is asked once, so the classes cover each reason the call is held.
+								const shell = shellHoldRule.describe(tool, input, context);
+								const { holds } = this.#options;
+								const host = holds?.(tool, input, context);
+								const action = shell ?? host;
 								if (!signal.aborted) {
+									const holdClasses = action
+										? classesOf(tool, input, context, [
+												...(shell === undefined ? [] : [SHELL_CHECK]),
+												...(host === undefined || !holds ? [] : [holds]),
+											])
+										: undefined;
 									answer = action
 										? await review({
 												tool,
 												input: canonicalJson(input),
 												action,
+												...(holdClasses ? { holdClasses } : {}),
 											})
 										: "approved";
 									if (action && answer !== "approved")

package/src/repo-shelf.ts

@@ -10,6 +10,7 @@ import {
 	readSync,
 	realpathSync,
 	renameSync,
+	rmSync,
 } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { AgentError, checkRepoName, scrubDiagnostic } from "pi-roundtable/kit";
@@ -54,6 +55,36 @@ export interface RepoState {
 
 export type CloneCommand = (repo: string, dir: string) => Promise<void>;
 
+/** A coding worker's own checkout: a linked worktree on its own branch, cut from the clone's HEAD. */
+export interface WorkerTree {
+	repo: string;
+	/** The worktree's real path, outside the shelf's list of managed repositories. */
+	dir: string;
+	/** The worker's branch, such as `worker/3`. */
+	branch: string;
+	/** The clone's full HEAD the branch was cut from. */
+	base: string;
+}
+
+/** What bringing a worker's branch back into its clone did. */
+export type Integration =
+	/** The branch had no commits beyond the clone; the worktree and branch are gone. */
+	| { status: "nothing" }
+	/** Rebased onto the clone's branch and fast-forwarded it; the worktree and branch are gone. */
+	| { status: "merged"; branch: string; commits: string[] }
+	/** The rebase stopped on these files; it was aborted, and the branch and worktree are kept. */
+	| { status: "conflict"; branch: string; dir: string; files: string[] }
+	/** The clone or the worktree had uncommitted changes, or the clone moved; nothing was touched. */
+	| {
+			status: "refused";
+			branch: string;
+			dir: string;
+			reason: string;
+	  };
+
+/** The folder under the shelf that holds worker worktrees; the shelf lists no repository there. */
+export const WORKTREES_DIR = ".worktrees";
+
 const GIT_TIMEOUT_MS = 60_000;
 const MAX_STAT_FILES = 40;
 const MAX_SUMMARY_CHARS = 120;
@@ -218,7 +249,7 @@ export class RepoShelf {
 		if (!existsSync(this.dir)) return [];
 		// pi-lens-ignore: no-sort-without-comparator — the names are strings, and code-unit order gives the same list on every machine
 		return readdirSync(this.dir, { withFileTypes: true })
-			.filter((owner) => owner.isDirectory())
+			.filter((owner) => owner.isDirectory() && !owner.name.startsWith("."))
 			.flatMap((owner) =>
 				readdirSync(join(this.dir, owner.name), {
 					withFileTypes: true,
@@ -235,6 +266,7 @@ export class RepoShelf {
 	/** A managed repository's folder, or an error naming the managed ones. */
 	dirOf(repo: string): string {
 		checkRepoName(repo);
+		refuseHidden(repo);
 		const dir = join(this.dir, repo);
 		if (!existsSync(join(dir, ".git")))
 			throw new AgentError(
@@ -262,6 +294,7 @@ export class RepoShelf {
 	/** Clones a repository into the shelf (behavior 2). */
 	async add(repo: string): Promise<string> {
 		checkRepoName(repo);
+		refuseHidden(repo);
 		const dir = join(this.dir, repo);
 		if (existsSync(dir) || this.#adding.has(repo))
 			throw new AgentError(`${repo} is already present or being cloned.`);
@@ -398,6 +431,176 @@ export class RepoShelf {
 		return log ? log.split("\n") : [];
 	}
 
+	/**
+	 * Cuts a worktree for coding job `id` from the clone's HEAD, on a fresh branch `worker/<id>`
+	 * (with a suffix when an earlier run kept one of that name), under `<shelf>/.worktrees/`.
+	 */
+	async addWorktree(repo: string, id: number): Promise<WorkerTree> {
+		const clone = this.dirOf(repo);
+		const base = await this.#git(clone, "rev-parse", "HEAD");
+		const parent = join(this.dir, WORKTREES_DIR, repo);
+		mkdirSync(parent, { recursive: true });
+		const rel = relative(realpathSync(this.dir), realpathSync(parent));
+		if (rel.startsWith("..") || isAbsolute(rel))
+			throw new AgentError("The worktree folder escapes the shelf.");
+		for (let attempt = 1; ; attempt++) {
+			const name = attempt === 1 ? `${id}` : `${id}-${attempt}`;
+			const branch = `worker/${name}`;
+			const dir = join(parent, name);
+			const taken =
+				existsSync(dir) ||
+				(
+					await run([
+						"git",
+						"-C",
+						clone,
+						"rev-parse",
+						"--verify",
+						"--quiet",
+						`refs/heads/${branch}`,
+					])
+				).code === 0;
+			if (taken) continue;
+			await this.#git(
+				clone,
+				"worktree",
+				"add",
+				"--quiet",
+				"-b",
+				branch,
+				dir,
+				base,
+			);
+			return { repo, dir: realpathSync(dir), branch, base };
+		}
+	}
+
+	/**
+	 * Rebases the worker's branch onto the clone's current HEAD inside its worktree and
+	 * fast-forwards the clone, then removes the worktree and branch. The clone is never left
+	 * mid-rebase: a conflict aborts the rebase in the worktree and keeps both. A clone or worktree
+	 * with uncommitted changes is not touched. The caller serializes integrations of one clone.
+	 */
+	async integrate(tree: WorkerTree): Promise<Integration> {
+		const clone = this.dirOf(tree.repo);
+		const kept = { branch: tree.branch, dir: tree.dir };
+		const dirty = await this.#git(clone, "status", "--porcelain");
+		if (dirty)
+			return {
+				status: "refused",
+				...kept,
+				reason: `the clone has uncommitted changes, so it was left as it is:\n${dirty}`,
+			};
+		const head = await this.#git(clone, "rev-parse", "HEAD");
+		const ahead = Number(
+			await this.#git(clone, "rev-list", "--count", `${head}..${tree.branch}`),
+		);
+		if (ahead === 0) {
+			await this.removeWorktree(tree);
+			return { status: "nothing" };
+		}
+		const treeDir = this.#treeDir(tree);
+		const treeDirty = await this.#git(treeDir, "status", "--porcelain");
+		if (treeDirty)
+			return {
+				status: "refused",
+				...kept,
+				reason: `the worker left uncommitted changes in its worktree:\n${treeDirty}`,
+			};
+		const rebase = await run(["git", "-C", treeDir, "rebase", "--quiet", head]);
+		if (rebase.code !== 0) {
+			const conflicted = await run([
+				"git",
+				"-C",
+				treeDir,
+				"diff",
+				"--name-only",
+				"--diff-filter=U",
+			]);
+			await run(["git", "-C", treeDir, "rebase", "--abort"]);
+			return {
+				status: "conflict",
+				...kept,
+				files: conflicted.out ? conflicted.out.split("\n") : [],
+			};
+		}
+		const merge = await run([
+			"git",
+			"-C",
+			clone,
+			"merge",
+			"--ff-only",
+			"--quiet",
+			tree.branch,
+		]);
+		if (merge.code !== 0)
+			return {
+				status: "refused",
+				...kept,
+				reason: `the clone could not fast-forward to the branch: ${scrubDiagnostic(merge.err, this.#diagnosticChars) || `exit ${merge.code}`}`,
+			};
+		const log = await this.#git(
+			clone,
+			"log",
+			"--format=%h %s",
+			"--abbrev=12",
+			`${head}..HEAD`,
+		);
+		await this.removeWorktree(tree);
+		return {
+			status: "merged",
+			branch: tree.branch,
+			commits: log ? log.split("\n") : [],
+		};
+	}
+
+	/** A worker worktree's state, as `state` reads a clone's. */
+	async treeState(tree: WorkerTree): Promise<RepoState> {
+		const dir = this.#treeDir(tree);
+		const status = await this.#git(dir, "status", "--porcelain");
+		return {
+			branch: await this.#git(dir, "rev-parse", "--abbrev-ref", "HEAD"),
+			head: await this.#git(dir, "rev-parse", "--short=12", "HEAD"),
+			uncommitted: status ? status.split("\n") : [],
+		};
+	}
+
+	/** `<short sha> <subject>` of each commit on the worker's branch after its base, newest first. */
+	async treeCommits(tree: WorkerTree): Promise<string[]> {
+		const log = await this.#git(
+			this.#treeDir(tree),
+			"log",
+			"--format=%h %s",
+			"--abbrev=12",
+			`${tree.base}..HEAD`,
+		);
+		return log ? log.split("\n") : [];
+	}
+
+	/** Removes a worker's worktree and its branch; what is already gone is skipped. */
+	async removeWorktree(tree: WorkerTree): Promise<void> {
+		const clone = this.dirOf(tree.repo);
+		this.#treeDir(tree, false);
+		await run(["git", "-C", clone, "worktree", "remove", "--force", tree.dir]);
+		if (existsSync(tree.dir))
+			rmSync(tree.dir, { recursive: true, force: true });
+		await run(["git", "-C", clone, "worktree", "prune"]);
+		await run(["git", "-C", clone, "branch", "-D", "--quiet", tree.branch]);
+	}
+
+	/** A worktree path, refused unless it lies in this repository's worktree folder. */
+	#treeDir(tree: WorkerTree, mustExist = true): string {
+		const parent = resolve(this.dir, WORKTREES_DIR, tree.repo);
+		const path = mustExist ? realpathSync(tree.dir) : resolve(tree.dir);
+		const root = existsSync(parent) ? realpathSync(parent) : parent;
+		const rel = relative(root, path);
+		if (!rel || rel.startsWith("..") || isAbsolute(rel) || rel.includes("/"))
+			throw new AgentError(
+				"The worktree lies outside the shelf's worktree folder.",
+			);
+		return path;
+	}
+
 	async #summary(repo: string, fetch: boolean): Promise<RepoSummary> {
 		const dir = this.dirOf(repo);
 		const summary = summaryOf(dir);
@@ -499,6 +702,14 @@ export class RepoShelf {
 	}
 }
 
+/** Owners starting with a dot are the shelf's own folders, such as its worktrees. */
+function refuseHidden(repo: string): void {
+	if (repo.startsWith("."))
+		throw new AgentError(
+			`"${repo}" is not a repository: owners starting with a dot are reserved for the shelf.`,
+		);
+}
+
 /** The report as posted for the owner. */
 export function reportPost(report: ChangeReport, direct = false): string {
 	return [

package/src/worker-entry.ts

@@ -34,6 +34,7 @@ export function codingWorkerPrompt(dir: string): string {
 	return [
 		`You are a coding worker in ${dir}. The next message is your approved task. Read this repository's AGENTS.md.`,
 		"Work with the shell and file tools available. Complete and verify the contract, stage files by name and commit using repository conventions, without tool attribution.",
+		"You work in your own worktree on its own branch: commit there and stay on it, without switching branches or rebasing; the host merges your branch back when you finish.",
 		"Do not push or ship. The calling agent reviews your commits and requests the owner's approval through repo_change_report and repo_push.",
 		"Risky calls wait for the owner's approval. An approved call runs; a declined or held call must not be retried or worked around.",
 		"Resolve decisions settled by the task or repository. Put remaining owner decisions and held actions in your report instead of guessing.",