pi-roundtable-coding 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.7.0] - Unreleased
+
+Prepared for the first npm publication.
+The earlier `0.1.0` was local-only and was never published on npm.
+
+### Changed
+
+- Move into the pi-roundtable workspace with preserved Git history and lockstep version `0.7.0`.
+  CI checks the core and all packages; the shared `publish.yml` releases them from one `v*` tag.
+
+### Added
+
+- Add a managed repository shelf with clone, list, change-report and exact-commit push tools.
+- Add background out-of-process Pi coding workers with host-side owner cards and a work timeout that excludes approval waits.
+- Hold every repository push by default, with an explicit owner-repository allowlist.
+- Add configurable Git host cloning, model, Pi extension packages, skill selection and result delivery.
+- Document the host security boundary and provide offline integration tests and release workflows.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wayne930242
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# pi-roundtable-coding
+
+A repository shelf and an out-of-process Pi coding desk for [pi-roundtable][roundtable].
+Agents and owner sessions get five repository tools; coding jobs commit locally and report back, while shipping stays behind the owner's approval.
+This package is a reference for the plugin guide's [Helpers for a Pi session of your own][helpers].
+
+## Requirements
+
+- Bun 1.4.2 or newer on a POSIX host (Linux or macOS).
+- pi-roundtable `>=0.7.0 <0.8.0` as a peer dependency; this package uses only its public main, kit and testing entries.
+- Pi `>=1.0.0 <2`, shared with the host's core dependencies.
+  A core-only host still pinned to Pi 0.99.x must update its Pi dependencies before adding coding, so cross-package extension and session types resolve to one Pi version.
+- Git, plus GitHub CLI (`gh`) for the default clone implementation.
+- A Git host token with read access to repositories being cloned and write access to those being pushed, or a host login holding that token.
+- Pi model credentials available through the host's Pi login or the provider's environment variables.
+
+The default clone uses `gh repo clone owner/repo` and inherits `GH_TOKEN` or the host's `gh auth login` credentials.
+Configure Git's credential helper for later `git fetch` and `git push` (for GitHub, `gh auth setup-git`).
+Use a least-privilege token and restrict its repositories; tokens are never package options, tool arguments or remote URLs.
+The package does not print subprocess output or Git authentication diagnostics and never logs credentials.
+The coding worker inherits the host environment and can read files accessible to that host user: do not give it credentials you would not give a trusted coding agent.
+A custom `clone(repo, destination)` can use another Git host's CLI, credential helper or SSH login, and must create a Git clone with an `origin` remote.
+No network calls are needed by the offline test suite.
+
+## Setup
+
+```sh
+bun add pi-roundtable-coding pi-roundtable
+```
+
+```ts
+// roundtable.config.ts
+import { coding } from "pi-roundtable-coding";
+
+export default {
+  // ...the settings created by pi-roundtable init...
+  plugins: [
+    coding({
+      shelfDir: "/srv/roundtable/repos",
+      model: "anthropic/claude-sonnet-4-6",
+      thinking: "medium",
+      timeoutMs: 60 * 60_000,
+      // Default []: every repo_push is held for approval.
+      ownerRepos: [],
+    }),
+  ],
+};
+```
+
+The model is an explicit `provider/model-id` available on this host, not selected by this package.
+`agentDir` defaults to Pi's host login directory and controls its `auth.json` and `models.json` locations.
+No automatic extension, skill, prompt-template or theme discovery is enabled for workers.
+Only repository context files within the clone are included as standing instructions.
+
+To load installed Pi extension packages (for example a model provider), pass their absolute package directories in `workerPackages`.
+Resolve them from your configuration rather than from a core checkout:
+
+```ts
+import { packageDir } from "pi-roundtable/kit";
+
+const workerPackages = [packageDir("your-provider-package", import.meta.url)];
+```
+
+Install the provider package on the host first and pass `workerPackages` to `coding`.
+Workers activate only `SHELL_TOOLS` (`bash`, `read`, `edit`, `write`); extension packages are trusted executable code, not a way to grant extra model tools.
+
+## Tools and flow
+
+| Tool | Parameters | Behavior |
+| --- | --- | --- |
+| `repo_add` | `repo` | Clone `owner/repo` into `shelfDir/owner/repo`; refuse invalid names and existing clones. |
+| `repo_list` | `fetch?` | List paths, branches, upstream ahead/behind counts, dirty files, last commits, prose summaries, CI hints and linked skills. |
+| `repo_task` | `repo`, `task`, `skills?` | Start a background worker, returning its job number immediately. |
+| `repo_change_report` | `repo` | Fetch and post the commits and diffstat ahead of the default branch; return its full SHA. |
+| `repo_push` | `repo`, `sha` | Push the exact reported SHA to the reported default branch, without force, after the hold gate permits it. |
+
+All five tools have `minTier: "owner"` and are contributed through `defineTool` for agent and owner session selections.
+The operator remains responsible for any tool-tier overrides.
+A custom owner claim with a restricted `ToolSelection` must include the exported `REPO_TOOLS` names; include `skill_list` separately when the host skills addon is enabled.
+The host's skills addon resolves explicit skills, or the calling agent's carried skills when omitted; an owner call carries none unless it names them.
+Missing or unknown skills refuse the task; requesting skills while the addon is off also refuses it.
+Sessions with kind `owner` get the public `skillListExtension`; agent sessions keep the core's existing `skill_list` instead of registering it twice.
+
+A worker reads the repository's instructions, edits and checks the work, and commits using repository conventions.
+One worker may use a repository at a time, with up to three per channel.
+Reports and pushes refuse a repository while its coding worker is still running.
+The plugin also reserves repositories during report and push operations, refusing concurrent shipping calls and new coding tasks.
+The worker's report includes its final answer, declined or unanswered actions, branch, HEAD, new commits and uncommitted files.
+Failures and timeouts also report the final Git state when it can be read.
+By default reports are sent to the caller's surface; `onResult(result)` can instead enqueue a background conversation turn through your host integration.
+Dates are formatted using `context.env.timeZone`, not a process-wide zone.
+
+Shipping is separate from coding:
+
+1. Review the worker's changes and verification evidence.
+2. Call `repo_change_report`; the clone must be clean, ahead of `origin/HEAD`, and missing none of its commits.
+3. Call `repo_push` with the full SHA from that report.
+4. The host holds the push and asks the owner before running it.
+
+`ownerRepos` is an exact list of `owner/repo` names, not a prefix or wildcard; its default is empty.
+Listed repositories skip the plugin's `repo_push` hold, though other host hold rules can still hold the call.
+They do not exempt shell pushes or risky worker actions.
+The report and approval card name the full SHA, current default branch and credential-free push destination.
+The clone must have exactly one push destination; HTTP remote URLs with user information, query strings or fragments are refused before fetching.
+A changed HEAD, dirty clone, changed remote default branch, changed push destination, missing report or non-fast-forward remote causes refusal.
+Report receipts live in memory, so request a fresh report after restarting the host.
+
+## Approvals and work time
+
+Every worker tool call crosses a private Bun IPC channel to the parent process before execution.
+The parent consults `shellHoldRule`, additional `holds`, and the host's linked hold rules; a recognized risky action asks the owner's surface prompts using `approvalCard`.
+`promptSlot` tracks these cards and `workTimeout` excludes their waiting time from the worker's budget (one hour by default).
+`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.
+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.
+
+The worker runs in a fresh Bun child process with an unsaved Pi session and uses the public `runWorkerTask` helper.
+Timeout and shutdown kill its POSIX process group and wait for exit; normal completion also removes shell descendants left in that group.
+The service advertises running jobs through `busy()` so the host can drain them before shutdown.
+Jobs are in memory; they do not resume after a crash.
+The injectable `worker` runner must observe aborts and settle its run; this is a trusted test/integration seam.
+
+## Security model
+
+This is a host coding desk, **not a sandbox**.
+The worker can run local checks, read the host's accessible files, use the network and commit changes.
+Its standing instructions delegate shipping to the calling agent; repository tools and extra package tools are not activated inside the worker.
+`repo_push` is the supported shipping route and always uses a previously reported full SHA and a non-force push.
+The public shell rule holds recognized shell pushes, destructive commands, privileged commands and recognized writes outside the clone, even for `ownerRepos`.
+It is a heuristic guard: scripts, interpreters, symlinks, Git hooks, package extensions and detached grandchildren are not an OS isolation boundary.
+A trusted package or arbitrary shell program can bypass heuristic detection; only run code and repositories you trust, under a dedicated low-privilege host user.
+Use an isolated container or VM when host access is unacceptable.
+
+The shelf validates names with the public `checkRepoName` helper and checks real paths before operating on a clone, refusing paths that escape the shelf or Git directories that escape a clone.
+Metadata discovery skips symlinks, directories and special files, reads at most 64 KiB per file, and refuses symlinked workflow directories.
+Git commands use argument arrays, not interpolated shell commands.
+Host-side Git operations disable repository hooks and fsmonitor; the coding worker's own Git operations retain repository conventions.
+Local Git credential helpers and other executable Git configuration still run as the host user and can be written by a worker, so repository configuration is a trusted boundary, not an approval boundary.
+Keep external processes from changing shelf paths or Git refs during approval and push; these checks do not serialize unrelated host writers.
+Model output, diffs and tool inputs can contain sensitive repository content, so report channels and approval cards must remain owner-trusted.
+
+## API and options
+
+`coding(options)` is the plugin factory.
+The `CODING` service exposes `shelf: RepoShelf` and `desk: CodingDesk` for trusted owner integrations; direct service calls are not the host tool approval gate.
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `shelfDir` | required | Managed clone directory. |
+| `model` | required | Worker provider/model ID. |
+| `thinking` | `medium` | Pi thinking level. |
+| `ownerRepos` | `[]` | Exact push-hold exemptions. |
+| `workerPackages` | `[]` | Absolute installed extension paths. |
+| `agentDir` | Pi host directory | Pi credentials and model configuration. |
+| `timeoutMs` | `3600000` | Work-time limit in ms, excluding owner wait; 0 < value <= 2147483647. |
+| `holds` | none | Additional worker hold check. |
+| `clone` | `ghClone` | Git-host clone implementation. |
+| `worker` | `PiCodingWorker` | Trusted worker runner replacement. |
+| `onResult` | surface reply | Report delivery integration. |
+
+`RepoShelf`, `CodingDesk`, `PiCodingWorker`, `CodingWorkerFailure`, `REPO_TOOLS`, `codingReport`, `reportPost` and their option/result types are exported for testing and host integrations.
+No database or Discord-specific types are required.
+
+## Development and publishing
+
+This package lives in `packages/coding` in the pi-roundtable workspace.
+Run these commands from the repository root:
+
+```sh
+bun install --frozen-lockfile
+bun run --cwd packages/coding test
+bun run --cwd packages/coding typecheck
+bun run --cwd packages/coding lint
+```
+
+Tests use temporary bare Git origins, `testPlugin`, fake workers and a real child Pi session with an offline faux provider.
+They cover cloning/listing, reports, push holds and approved pushes, owner exceptions, work-time exclusion, bad names, closed approval paths and child-process exit.
+CI runs those checks.
+The shared `publish.yml` workflow repeats them, checks that every workspace version and core peer range match the single `v*` tag, then uses npm trusted publishing with provenance.
+The owner performs the initial npm publication and configures this package's trust against `publish.yml`; no separate repository or package-specific tag is needed.
+
+## License
+
+MIT; see [LICENSE](LICENSE).
+
+[roundtable]: https://www.npmjs.com/package/pi-roundtable
+[helpers]: https://github.com/wayne930242/pi-roundtable/blob/master/docs/plugins.md#helpers-for-a-pi-session-of-your-own

package/examples/plugin.ts

@@ -0,0 +1,10 @@
+import { coding } from "../src/index.ts";
+
+/** Add this plugin to the host's roundtable.config.ts plugins list. */
+export const codingDesk = coding({
+	shelfDir: "/srv/roundtable/repos",
+	model: "anthropic/claude-sonnet-4-6",
+	thinking: "medium",
+	timeoutMs: 3_600_000,
+	ownerRepos: [],
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "pi-roundtable-coding",
+	"version": "0.7.0",
+	"description": "Repository shelves and owner-approved Pi coding workers for pi-roundtable",
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/wayne930242/pi-roundtable.git",
+		"directory": "packages/coding"
+	},
+	"engines": {
+		"bun": ">=1.4.2"
+	},
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"files": [
+		"src",
+		"!src/**/*.test.ts",
+		"!src/testing",
+		"examples",
+		"LICENSE",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"scripts": {
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check ."
+	},
+	"dependencies": {
+		"@earendil-works/pi-coding-agent": ">=1.0.0 <2",
+		"typebox": "1.3.34"
+	},
+	"peerDependencies": {
+		"pi-roundtable": ">=0.7.0 <0.8.0"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-ai": ">=1.0.0 <2",
+		"@biomejs/biome": "2.5.15",
+		"@types/bun": "1.4.2",
+		"pi-roundtable": "0.7.0",
+		"typescript": "7.0.2"
+	}
+}

package/src/coding-desk.ts

@@ -0,0 +1,251 @@
+import type {
+	ChannelKey,
+	HeldCall,
+	Logger,
+	OwnerPrompts,
+	ThinkingLevel,
+} from "pi-roundtable";
+import {
+	AgentError,
+	approvalCard,
+	promptSlot,
+	workTimeout,
+} from "pi-roundtable/kit";
+import type { RepoShelf, RepoState } from "./repo-shelf.ts";
+import { CodingWorkerFailure } from "./worker-failure.ts";
+
+export type HeldCallAnswer = "approved" | "declined" | "held";
+export interface CodingJob {
+	id: number;
+	repo: string;
+	task: string;
+	channel: ChannelKey;
+	model: string;
+	thinking: ThinkingLevel;
+	skillFiles: string[];
+	startedAt: Date;
+	startHead: string;
+}
+export interface CodingWorker {
+	run(
+		job: CodingJob & { dir: string },
+		signal: AbortSignal,
+		review: (call: HeldCall) => Promise<HeldCallAnswer>,
+	): Promise<string>;
+}
+export interface CodingResult {
+	job: CodingJob;
+	outcome: { ok: true; report: string } | { ok: false; error: string };
+	held: string[];
+	state?: RepoState;
+	commits: string[];
+}
+export interface CodingDeskOptions {
+	shelf: Pick<RepoShelf, "dirOf" | "state" | "commitsSince">;
+	worker: CodingWorker;
+	prompts(channel: ChannelKey): OwnerPrompts | undefined;
+	deliver(result: CodingResult): Promise<void>;
+	logger: Logger;
+	timeoutMs?: number;
+}
+export const MAX_CODING_TASK_CHARS = 8_000;
+const MAX_REPORT_CHARS = 20_000;
+const MAX_HELD_ENTRIES = 10;
+const MAX_HELD_CHARS = 1_000;
+function bounded(text: string, max: number): string {
+	const suffix = "\n[truncated]";
+	return text.length > max
+		? `${text.slice(0, max - suffix.length)}${suffix}`
+		: text;
+}
+
+/** One worker per repository, at most three per channel; results and jobs are in memory. */
+export class CodingDesk {
+	readonly #options: CodingDeskOptions;
+	readonly #running = new Map<
+		number,
+		{ job: CodingJob; controller: AbortController; done?: Promise<void> }
+	>();
+	#nextId = 1;
+	#stopped = false;
+	constructor(options: CodingDeskOptions) {
+		if (
+			!Number.isFinite(options.timeoutMs ?? 3_600_000) ||
+			(options.timeoutMs ?? 3_600_000) <= 0 ||
+			(options.timeoutMs ?? 3_600_000) > 2_147_483_647
+		)
+			throw new AgentError(
+				"timeoutMs must be positive, finite and at most 2147483647.",
+			);
+		this.#options = options;
+	}
+	busy(): string[] {
+		return [...this.#running.values()].map(
+			({ job }) => `Coding #${job.id} in ${job.repo}`,
+		);
+	}
+	checkIdle(repo: string): void {
+		if ([...this.#running.values()].some(({ job }) => job.repo === repo))
+			throw new AgentError(`A coding worker is still using ${repo}.`);
+	}
+	async idle(): Promise<void> {
+		await Promise.all([...this.#running.values()].map((run) => run.done));
+	}
+	async stop(): Promise<void> {
+		this.#stopped = true;
+		for (const run of this.#running.values()) run.controller.abort();
+		await this.idle();
+	}
+	async start(
+		request: Omit<CodingJob, "id" | "startedAt" | "startHead">,
+	): Promise<CodingJob> {
+		if (this.#stopped) throw new AgentError("The coding desk is stopped.");
+		const task = request.task.trim();
+		if (!task || task.length > MAX_CODING_TASK_CHARS)
+			throw new AgentError(
+				`The task must contain 1–${MAX_CODING_TASK_CHARS} characters.`,
+			);
+		const dir = this.#options.shelf.dirOf(request.repo);
+		this.checkIdle(request.repo);
+		if (
+			[...this.#running.values()].filter(
+				({ job }) => job.channel === request.channel,
+			).length >= 3
+		)
+			throw new AgentError("This channel already has three coding workers.");
+		const job: CodingJob = {
+			...request,
+			task,
+			id: this.#nextId++,
+			startedAt: new Date(),
+			startHead: "",
+		};
+		const run = {
+			job,
+			controller: new AbortController(),
+			done: undefined as Promise<void> | undefined,
+		};
+		this.#running.set(job.id, run);
+		// Reserve before the first await, including startup state reads.
+		run.done = this.#run(job, dir, run.controller)
+			.catch(() => {
+				this.#options.logger.error(
+					{ job: job.id },
+					"Coding report delivery failed.",
+				);
+			})
+			.finally(() => this.#running.delete(job.id));
+		return job;
+	}
+	async #run(
+		job: CodingJob,
+		dir: string,
+		controller: AbortController,
+	): Promise<void> {
+		const {
+			shelf,
+			worker,
+			prompts,
+			deliver,
+			timeoutMs = 3_600_000,
+		} = this.#options;
+		const slot = promptSlot();
+		const held: string[] = [];
+		let omittedHeld = 0;
+		let cancel = () => {};
+		let timedOut = false;
+		let outcome: CodingResult["outcome"];
+		try {
+			job.startHead = (await shelf.state(job.repo)).head;
+			if (controller.signal.aborted)
+				throw new AgentError("The worker was stopped.");
+			slot.bind(prompts(job.channel), `Coding worker #${job.id}`);
+			cancel = workTimeout(timeoutMs, slot, () => {
+				timedOut = true;
+				controller.abort();
+			});
+			const review = async (call: HeldCall): Promise<HeldCallAnswer> => {
+				let answer: HeldCallAnswer = "held";
+				try {
+					const decision = await slot.prompts?.confirm(
+						`${slot.asker} requests approval`,
+						approvalCard(call),
+						controller.signal,
+					);
+					if (decision === "approved" || decision === "declined")
+						answer = decision;
+				} catch {
+					/* A failed card never authorizes the call. */
+				}
+				if (answer !== "approved") {
+					if (held.length < MAX_HELD_ENTRIES)
+						held.push(
+							bounded(
+								`${answer}: ${call.action}: ${call.tool} ${call.input}`,
+								MAX_HELD_CHARS,
+							),
+						);
+					else omittedHeld++;
+				}
+				return answer;
+			};
+			const report = await worker.run(
+				{ ...job, dir },
+				controller.signal,
+				review,
+			);
+			if (controller.signal.aborted)
+				throw new AgentError("The worker was stopped.");
+			outcome = { ok: true, report: bounded(report, MAX_REPORT_CHARS) };
+		} catch (error) {
+			// Only structured, fixed diagnostics can cross the worker boundary.
+			let message =
+				"The worker failed; inspect the clone and worker configuration on the host.";
+			if (error instanceof CodingWorkerFailure) {
+				message = error.message;
+				this.#options.logger.warn(
+					{ job: job.id, category: error.category, exitCode: error.exitCode },
+					"Coding worker failed.",
+				);
+			}
+			if (controller.signal.aborted) message = "The worker was stopped.";
+			if (timedOut)
+				message = `Work timeout after ${timeoutMs} ms (owner wait excluded).`;
+			outcome = { ok: false, error: message };
+		} finally {
+			cancel();
+			slot.unbind();
+		}
+		let state: RepoState | undefined;
+		let commits: string[] = [];
+		try {
+			state = await shelf.state(job.repo);
+			if (job.startHead)
+				commits = await shelf.commitsSince(job.repo, job.startHead);
+		} catch {
+			this.#options.logger.warn(
+				{ job: job.id },
+				"Repository state unreadable.",
+			);
+		}
+		if (omittedHeld)
+			held.push(`[${omittedHeld} more unapproved actions omitted]`);
+		await deliver({ job, outcome, held, ...(state ? { state } : {}), commits });
+	}
+}
+
+export function codingReport(result: CodingResult, started: string): string {
+	const { job, outcome, state, commits, held } = result;
+	return [
+		`## Coding task #${job.id}: ${job.repo}`,
+		`Started: ${started}`,
+		outcome.ok ? outcome.report : outcome.error,
+		"### Held",
+		held.length ? held.join("\n") : "None.",
+		"### Repository",
+		state
+			? `Branch ${state.branch}, HEAD ${state.head} (was ${job.startHead}).\nNew commits:\n${commits.join("\n") || "None."}\nUncommitted:\n${state.uncommitted.join("\n") || "None."}`
+			: "Unreadable.",
+		"Review the changes and checks, then use repo_change_report before repo_push.",
+	].join("\n\n");
+}