pi-roundtable-sandbox 0.7.3 → 0.7.4

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.7.4
+
+- Let `SandboxResearchWorker` run the host's own web tools (`tools`, `scope`, `aborted`), and make `ScopedSandboxDelegator` refuse and fail with readable reasons (scrubbed) instead of generic text, with no title limit.
+
 ## 0.7.3
 
 - Add the opt-in Pi subscription mode (`PiSandboxRuntime`, `PiSandboxBroker`, `PiDockerContainerDriver`), worker-initiated transport, controlled `safeFetch`, bounded media in and reply files out, scoped delegation and a research worker, with the sealed default unchanged.

package/README.md

@@ -312,14 +312,19 @@ Allowed ranges are 1 millisecond–120 seconds, 0–10 redirects and 1 byte–32
 `assertPublicUrl(url)` refuses a URL that is not credential-free HTTP(S) or does not resolve only to public addresses. Use it before handing a model-supplied URL to a third-party reader; it does not pin a later connection, so host-side fetches of that URL should still use `safeFetch`.
 
 `ScopedSandboxDelegator` fixes one declared target, channel-local report destination and host-bound author, with no owner/agent dispatcher or origin thread.
-Its default limit is two jobs per channel, 4,000 task characters, 200 title characters, 80,000 report characters and ten minutes.
+Its default limit is two jobs per channel, 4,000 task characters, 80,000 report characters and ten minutes.
+A refusal reads "title and task are required", "the task is N characters; keep it within 4000" or "this channel already has N delegated tasks running; wait for one to report back".
+A failed job reports its error message scrubbed of credentials and bounded with `scrubDiagnostic`, or "the worker ran out of time" after the deadline.
 Configure `maxRunning` (1–10) and `timeoutMs` (1–1,200 seconds) explicitly when preserving an application's existing limits.
 `run(task, context)` receives only bound channel/author/signal, and `deliver(job, result)` posts through the application's background-report adapter.
 `runningChannels`, `idle` and `dispose` support host lifecycle handling; jobs are process-local and are cancelled on disposal.
 `SandboxResearchWorker` is an optional host subscription adapter with explicit `modelRuntime`, `agentDir`, `workDir`, `model`, `thinking`, `search`, and `extractFetched` options.
 It creates an unsaved Pi session with only `web_search` and controlled `fetch_content`, no shell, host memory, skills/context discovery or owner tools.
 `extractFetched` receives already bounded, pinned-fetch bytes and must not re-fetch their URL.
-Alternatively `fetchContent(url, signal)` replaces the built-in fetch plus `extractFetched` with a host-owned fetch-and-extract; the host is then responsible for refusing unsafe and private addresses and for bounding time and size. One of the two is required.
+Alternatively `fetchContent(url, signal)` replaces the built-in fetch plus `extractFetched` with a host-owned fetch-and-extract; the host is then responsible for refusing unsafe and private addresses and for bounding time and size.
+Or `tools` replaces both built-in tools with the host's own: `extensionPaths` (installed Pi extension packages, such as `pi-web-access`), `extensionFactories` (for example a guard that vets each call before it runs), the `toolNames` that stay active, and an optional `prompt`; `search`, `fetchContent` and `extractFetched` are then unused.
+`scope(run)` wraps the whole session so a host can bind a fetch guard to this run, and `aborted` words a deadline stop (default "the worker ran out of time").
+One of `search` with a fetch option, or `tools`, is required.
 Host search/model credentials stay in the trusted host process, and report delivery must remain in the declared guest channel.
 These hooks broaden the sealed threat model: review every adapter, apply provider spend limits and host quotas, and never substitute an unrestricted default delegation worker.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable-sandbox",
-	"version": "0.7.3",
+	"version": "0.7.4",
 	"description": "Sealed guest channels and an allow-listed credential broker for pi-roundtable",
 	"type": "module",
 	"license": "MIT",
@@ -52,7 +52,7 @@
 		"@biomejs/biome": "2.5.15",
 		"@types/bun": "1.4.2",
 		"discord.js": "14.27.0",
-		"pi-roundtable": "0.7.3",
+		"pi-roundtable": "0.7.4",
 		"typebox": "1.3.34",
 		"typescript": "7.0.2"
 	}

package/src/index.ts

@@ -86,6 +86,7 @@ export {
 } from "./plugin.ts";
 export type { SandboxReply, SandboxTurn, ToolSpec } from "./protocol.ts";
 export {
+	type ResearchTools,
 	type SandboxResearchOptions,
 	SandboxResearchWorker,
 } from "./research-worker.ts";

package/src/research-worker.ts

@@ -1,4 +1,7 @@
-import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import type {
+	ExtensionFactory,
+	ModelRuntime,
+} from "@earendil-works/pi-coding-agent";
 import {
 	activeToolsExtension,
 	runWorkerTask,
@@ -6,13 +9,24 @@ import {
 } from "pi-roundtable/kit";
 import { type SafeFetchResult, safeFetch } from "./safe-fetch.ts";
 
+/** A host's own web tools, for example pi-web-access, in place of the built-in `web_search` and `fetch_content`. */
+export interface ResearchTools {
+	/** Installed Pi extension packages that register the tools. */
+	extensionPaths?: string[];
+	/** Extensions the host builds itself, such as a guard that vets each call before it runs. */
+	extensionFactories?: { name: string; factory: ExtensionFactory }[];
+	/** The only tools active in the session. */
+	toolNames: string[];
+	/** Replaces the standing research prompt. */
+	prompt?: string;
+}
 export interface SandboxResearchOptions {
 	modelRuntime: ModelRuntime;
 	agentDir: string;
 	workDir: string;
 	model: string;
 	thinking: "low" | "medium" | "high" | "xhigh";
-	search(query: string, signal: AbortSignal): Promise<string>;
+	search?(query: string, signal: AbortSignal): Promise<string>;
 	/** Parse only these already-bounded fetched bytes; never re-fetch the URL. */
 	extractFetched?(
 		result: SafeFetchResult,
@@ -24,14 +38,31 @@ export interface SandboxResearchOptions {
 	 * (see `assertPublicUrl` and `safeFetch`) and for bounding time and size.
 	 */
 	fetchContent?(url: string, signal: AbortSignal): Promise<string>;
+	/**
+	 * The host's own web tools replace the built-in two, and `search`, `fetchContent` and
+	 * `extractFetched` are unused. The host then vets the tools' network use itself.
+	 */
+	tools?: ResearchTools;
+	/** Wraps the whole session, for example to scope a fetch guard to this run. */
+	scope?<T>(run: () => Promise<T>): Promise<T>;
+	/** The message of a run stopped by its deadline; default: "the worker ran out of time". */
+	aborted?: string;
 }
 /** Host subscription research with no built-in tools, host memory, discovery, or shell. */
 export class SandboxResearchWorker {
 	constructor(readonly options: SandboxResearchOptions) {
-		if (!options.fetchContent && !options.extractFetched)
-			throw new Error("Research needs fetchContent or extractFetched");
+		if (!options.tools && !options.fetchContent && !options.extractFetched)
+			throw new Error("Research needs tools, fetchContent or extractFetched");
+		if (!options.tools && !options.search)
+			throw new Error("Research needs search unless it has its own tools");
 	}
-	async run(task: string, signal: AbortSignal): Promise<string> {
+	run(task: string, signal: AbortSignal): Promise<string> {
+		const scope = this.options.scope;
+		return scope
+			? scope(() => this.#run(task, signal))
+			: this.#run(task, signal);
+	}
+	async #run(task: string, signal: AbortSignal): Promise<string> {
 		signal.throwIfAborted();
 		const {
 			createAgentSession,
@@ -41,6 +72,61 @@ export class SandboxResearchWorker {
 		} = await import("@earendil-works/pi-coding-agent");
 		const { Type } = await import("typebox");
 		const options = this.options;
+		const tools = options.tools as ResearchTools;
+		const search = options.search as NonNullable<typeof options.search>;
+		const builtin: { name: string; factory: ExtensionFactory }[] = [
+			{
+				name: "research-tools",
+				factory: (pi) => {
+					pi.registerTool({
+						name: "web_search",
+						label: "Search",
+						description: "Search public sources and return a sourced answer.",
+						parameters: Type.Object({
+							query: Type.String({ minLength: 1, maxLength: 4000 }),
+						}),
+						execute: async (_id, input, callSignal) =>
+							toolText(
+								await search(
+									input.query,
+									AbortSignal.any([
+										signal,
+										...(callSignal ? [callSignal] : []),
+									]),
+								),
+							),
+					});
+					pi.registerTool({
+						name: "fetch_content",
+						label: "Fetch page",
+						description:
+							"Read a public HTTP(S) page. Private addresses are refused.",
+						parameters: Type.Object({
+							url: Type.String({ maxLength: 8000 }),
+						}),
+						execute: async (_id, input, callSignal) => {
+							const bound = AbortSignal.any([
+								signal,
+								...(callSignal ? [callSignal] : []),
+							]);
+							if (options.fetchContent)
+								return toolText(await options.fetchContent(input.url, bound));
+							return toolText(
+								await (
+									options.extractFetched as NonNullable<
+										typeof options.extractFetched
+									>
+								)(await safeFetch(input.url, { signal: bound }), bound),
+							);
+						},
+					});
+				},
+			},
+			{
+				name: "research-only",
+				factory: activeToolsExtension(() => ["web_search", "fetch_content"]),
+			},
+		];
 		const loader = new DefaultResourceLoader({
 			cwd: options.workDir,
 			agentDir: options.agentDir,
@@ -52,61 +138,21 @@ export class SandboxResearchWorker {
 			noPromptTemplates: true,
 			noThemes: true,
 			noContextFiles: true,
-			extensionFactories: [
-				{
-					name: "research-tools",
-					factory: (pi) => {
-						pi.registerTool({
-							name: "web_search",
-							label: "Search",
-							description: "Search public sources and return a sourced answer.",
-							parameters: Type.Object({
-								query: Type.String({ minLength: 1, maxLength: 4000 }),
-							}),
-							execute: async (_id, input, callSignal) =>
-								toolText(
-									await options.search(
-										input.query,
-										AbortSignal.any([
-											signal,
-											...(callSignal ? [callSignal] : []),
-										]),
-									),
-								),
-						});
-						pi.registerTool({
-							name: "fetch_content",
-							label: "Fetch page",
-							description:
-								"Read a public HTTP(S) page. Private addresses are refused.",
-							parameters: Type.Object({
-								url: Type.String({ maxLength: 8000 }),
-							}),
-							execute: async (_id, input, callSignal) => {
-								const bound = AbortSignal.any([
-									signal,
-									...(callSignal ? [callSignal] : []),
-								]);
-								if (options.fetchContent)
-									return toolText(await options.fetchContent(input.url, bound));
-								return toolText(
-									await (
-										options.extractFetched as NonNullable<
-											typeof options.extractFetched
-										>
-									)(await safeFetch(input.url, { signal: bound }), bound),
-								);
-							},
-						});
-					},
-				},
-				{
-					name: "research-only",
-					factory: activeToolsExtension(() => ["web_search", "fetch_content"]),
-				},
-			],
+			...(options.tools?.extensionPaths
+				? { additionalExtensionPaths: options.tools.extensionPaths }
+				: {}),
+			extensionFactories: options.tools
+				? [
+						...(options.tools.extensionFactories ?? []),
+						{
+							name: "research-only",
+							factory: activeToolsExtension(() => tools.toolNames),
+						},
+					]
+				: builtin,
 			appendSystemPrompt: [
-				"You are a research worker. Research the task using public sources. Report in the task's language, self-contained, with source links; state what could not be verified. You have no host shell, owner data, memory, or agent tools.",
+				options.tools?.prompt ??
+					"You are a research worker. Research the task using public sources. Report in the task's language, self-contained, with source links; state what could not be verified. You have no host shell, owner data, memory, or agent tools.",
 			],
 		});
 		await loader.reload();
@@ -126,7 +172,7 @@ export class SandboxResearchWorker {
 			model: options.model,
 			task,
 			signal,
-			aborted: "Research deadline exceeded",
+			aborted: options.aborted ?? "the worker ran out of time",
 		});
 	}
 }

package/src/scoped-delegator.ts

@@ -5,6 +5,9 @@ import type {
 	Logger,
 } from "pi-roundtable";
 import { DelegationError } from "pi-roundtable";
+import { scrubDiagnostic } from "pi-roundtable/kit";
+
+const MAX_TASK_CHARS = 4_000;
 
 export interface ScopedDelegatorOptions {
 	target: string;
@@ -53,25 +56,27 @@ export class ScopedSandboxDelegator {
 			request.author.tier
 		)
 			throw new DelegationError("Delegation scope refused");
-		if (
-			!request.title.trim() ||
-			request.title.length > 200 ||
-			!request.task.trim() ||
-			request.task.length > 4000
-		)
-			throw new DelegationError("Invalid delegation title/task");
-		if (
-			[...this.#jobs.values()].filter((job) => job.channel === request.channel)
-				.length >= (this.#options.maxRunning ?? 2)
-		)
-			throw new DelegationError("This channel has too many running tasks");
+		const task = request.task.trim();
+		if (!request.title.trim() || !task)
+			throw new DelegationError("title and task are required");
+		if (task.length > MAX_TASK_CHARS)
+			throw new DelegationError(
+				`the task is ${task.length} characters; keep it within ${MAX_TASK_CHARS}`,
+			);
+		const busy = [...this.#jobs.values()].filter(
+			(job) => job.channel === request.channel,
+		).length;
+		if (busy >= (this.#options.maxRunning ?? 2))
+			throw new DelegationError(
+				`this channel already has ${busy} delegated tasks running; wait for one to report back`,
+			);
 		const job: DelegationJob = {
 			id: this.#next++,
 			channel: request.channel,
 			target: this.#options.target,
 			author: { id: request.author.id, name: request.author.name },
 			title: request.title.trim(),
-			task: request.task.trim(),
+			task,
 			startedAt: new Date(),
 		};
 		const controller = new AbortController();
@@ -91,8 +96,14 @@ export class ScopedSandboxDelegator {
 				if (typeof report !== "string" || report.length > 80_000)
 					throw new Error("Research report too large");
 				result = { ok: true, report };
-			} catch {
-				result = { ok: false, error: "Sandbox task failed" };
+			} catch (error) {
+				// The worker's own reason reaches the asking agent, scrubbed of credentials and bounded.
+				const reason = signal.aborted
+					? "the worker ran out of time"
+					: scrubDiagnostic(
+							error instanceof Error ? error.message : String(error),
+						);
+				result = { ok: false, error: reason || "the task failed" };
 			}
 			await this.#options.deliver(job, result);
 		})()

package/src/testing/faux-research.ts

@@ -0,0 +1,47 @@
+import {
+	createFauxCore,
+	fauxAssistantMessage,
+	fauxToolCall,
+} from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { toolText } from "pi-roundtable/kit";
+
+/** A model that calls the host's fetch tool, then a tool the host left inactive, and reports both results. */
+export default function fauxResearch(pi: ExtensionAPI) {
+	const core = createFauxCore({ provider: "faux", models: [{ id: "worker" }] });
+	core.setResponses([
+		fauxAssistantMessage(
+			fauxToolCall("fetch_content", { url: "https://example.invalid/page" }),
+			{ stopReason: "toolUse" },
+		),
+		fauxAssistantMessage(fauxToolCall("host_secret_tool", {}), {
+			stopReason: "toolUse",
+		}),
+		(context) =>
+			fauxAssistantMessage(
+				`results=${JSON.stringify(context.messages.filter((message) => message.role === "toolResult"))}`,
+			),
+	]);
+	for (const name of ["web_search", "fetch_content", "get_search_content"])
+		pi.registerTool({
+			name,
+			label: name,
+			description: `host ${name}`,
+			parameters: { type: "object", properties: {} } as never,
+			execute: async () => toolText(`HOST ${name} ran`),
+		});
+	pi.registerTool({
+		name: "host_secret_tool",
+		label: "secret",
+		description: "must stay inactive",
+		parameters: { type: "object", properties: {} } as never,
+		execute: async () => toolText("no"),
+	});
+	pi.registerProvider("faux", {
+		api: core.api,
+		apiKey: "offline",
+		baseUrl: "http://faux.invalid",
+		streamSimple: core.streamSimple,
+		models: core.models,
+	});
+}