@nexus-aethra/dsh-box-sandbox 0.1.0

package/dist/index.mjs

@@ -0,0 +1,2231 @@
+import { DshboxRpc, DshboxUnavailableError, discoveryPath, getRpc, resetRpc } from "./rpc.mjs";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/tasks.ts
+/**
+* Following a dshbox background task to its outcome.
+*
+* Most of what an agent wants to do to a box -- start a container, build a
+* template, inject a resource -- is not an operation but a *task*: the daemon
+* answers with a task record and then does the work. That split is right for a
+* UI, which can watch a progress bar. For a caller with no other channel it
+* means one call returns an id and no outcome, and the next thing to write is
+* the polling loop. That loop is the learning cost this removes.
+*
+* So the tools enqueue and wait together, and hand back the finished record:
+* state, progress, the log path, and the error when there was one.
+*
+* The state machine is the part worth being careful about. A task that fails
+* may still be running: it rolls back first, and only then is finished. So
+* `failed` alone does not mean done -- treating it as terminal returns while
+* rollback is still releasing locks, and the caller then starts the next
+* operation against a store that is still being unwound.
+*
+* @module dsh-box-sandbox/tasks
+*/
+/**
+* The daemon's wire form for a task state.
+*
+* `TaskState` is declared in Rust with `#[serde(rename_all = "lowercase")]`, so
+* what crosses the wire is `succeeded`, `rolledback`, `cancelled` -- not the
+* PascalCase the enum spells in source. Comparing against the Rust spelling
+* matches nothing: a finished task is not recognised as finished, so a poll
+* runs to its full budget and then reports a task that is sitting at 100%
+* successful as one that did not finish. Normalising here rather than at each
+* call site is also what makes the two separators irrelevant, so a future
+* `rolling_back` cannot reintroduce the same silence a different way.
+*/
+function state(task) {
+	return task.status.trim().toLowerCase().replace(/[\s_-]/g, "");
+}
+/** States the daemon will not move out of. */
+const TERMINAL = /* @__PURE__ */ new Set([
+	"succeeded",
+	"cancelled",
+	"interrupted",
+	"rolledback"
+]);
+/**
+* True once a task will not change again.
+*
+* `Failed` is the exception the daemon's own docs call out: a failed task rolls
+* back, and only a failed *rollback* ends it. So `failed` on its own is not
+* the end of a task -- polling on it alone waits out the budget and then reports
+* a task that stopped as one that never stopped.
+*
+* What actually says the failure is over is the daemon's own `finishedAt`: it is
+* stamped when the task, rollback included, is done, and it stays null while a
+* rollback is still releasing locks. A task carrying one will not be handed to a
+* worker again, so treating it as finished is not a guess about the state
+* machine -- it is reading the same field the scheduler writes.
+*/
+function isFinished(task) {
+	const current = state(task);
+	if (TERMINAL.has(current)) return true;
+	if (current === "failed") {
+		const rollback = task.rollbackError;
+		if (typeof rollback === "string" && rollback.length > 0) return true;
+		return typeof task.finishedAt === "number" && task.finishedAt > 0;
+	}
+	return false;
+}
+/** True when the task stopped without doing what was asked. */
+function failed(task) {
+	const current = state(task);
+	return current === "failed" || current === "interrupted" || current === "rolledback";
+}
+/**
+* Poll a task until it finishes.
+*
+* A timeout is reported as such rather than as a result: handing back a task
+* that is still Queued, under a heading that reads like an outcome, is how a
+* caller goes on to assume something that has not happened yet. The last
+* known state comes back with it so the caller can say where it got to.
+*/
+async function waitForTask(id, options = {}) {
+	const timeoutMs = options.timeoutMs ?? 6e5;
+	const intervalMs = options.intervalMs ?? 700;
+	const deadline = Date.now() + timeoutMs;
+	const rpc = getRpc();
+	for (;;) {
+		const task = await rpc.call("task_status", { id });
+		if (isFinished(task)) return {
+			finished: true,
+			task
+		};
+		if (Date.now() >= deadline) return {
+			finished: false,
+			task
+		};
+		await new Promise((resolve) => setTimeout(resolve, intervalMs));
+	}
+}
+/**
+* Enqueue a task and follow it to the end.
+*
+* Returns the finished record, or throws with the daemon's own error text once
+* the task is finished and failed. The log path rides along in the message
+* because that is where the detail is, and an agent that has to go looking for
+* it is an agent that will not.
+*/
+async function runTask(method, params, options = {}) {
+	const { finished, task } = await waitForTask((await getRpc().call(method, params)).id, options);
+	if (!finished) throw new Error(`the ${task.kind} task did not finish within the budget; it is still ${task.status} at ${task.progress}%. Watch it with box_task, or read ${task.logPath ?? "its log"}.`);
+	if (failed(task)) throw new Error(`the ${task.kind} task ended ${task.status}` + (task.error ? `: ${task.error}` : "") + (task.rollbackError ? ` (rollback also failed: ${task.rollbackError})` : "") + (task.logPath ? `. Full detail in ${task.logPath}` : "."));
+	return task;
+}
+//#endregion
+//#region src/tools.ts
+/**
+* Reach the two host services this plugin needs.
+*
+* This is the only place the structural contract touches cordis. Keeping the
+* assertion here means the rest of the file is checked against the transcribed
+* types, so a shape change surfaces as one cast rather than a scatter of them.
+*/
+function hostServices(ctx) {
+	return ctx;
+}
+/** Long enough for a cold browser launch on the first call of a session. */
+const LAUNCH_BUDGET_MS = 9e4;
+/** A click or a query against an already-warm session is fast. */
+const WARM_BUDGET_MS = 3e4;
+function containerIdOf(args) {
+	const id = args?.containerId;
+	if (typeof id !== "string" || id.trim() === "") throw new Error("containerId is required");
+	return id;
+}
+function asRecord(value) {
+	return typeof value === "object" && value !== null ? value : {};
+}
+function textOf(value) {
+	const raw = asRecord(value).text;
+	return typeof raw === "string" ? raw : void 0;
+}
+/**
+* Call a debug RPC, opening the container's headless session if needed.
+*
+* The daemon keeps one session per container, so a missing session is the
+* normal first-call state rather than an error worth surfacing. Re-opening
+* is idempotent, which also recovers a session whose browser died.
+*/
+async function withSession(id, method, params) {
+	const rpc = getRpc();
+	try {
+		return await rpc.call(method, {
+			id,
+			...params
+		});
+	} catch (error) {
+		if (!/no debug session/i.test(String(error))) throw error;
+		await rpc.call("debug_open", { id });
+		return await rpc.call(method, {
+			id,
+			...params
+		});
+	}
+}
+function base64Of(value) {
+	const data = asRecord(value).data;
+	if (typeof data !== "string") throw new Error("screenshot result carried no image data");
+	return data;
+}
+/**
+* Register one tool against the host registry.
+*
+* Kept as a named function so each definition is typed as ToolDefinition at the
+* call site, which is what makes a missing field a compile error here rather
+* than a silent failure the first time the model calls the tool.
+*/
+function registerTool(ctx, definition) {
+	hostServices(ctx).tools.register(definition);
+}
+function renderPageElements(elements) {
+	if (elements.length === 0) return "No elements on this page.";
+	return elements.map((element, index) => {
+		const role = element.role ?? "?";
+		const name = element.name ?? "";
+		const value = element.value ? " value=" + JSON.stringify(element.value) : "";
+		const at = Math.round(element.x ?? 0) + "," + Math.round(element.y ?? 0);
+		const size = element.width !== void 0 && element.height !== void 0 ? " " + Math.round(element.width) + "x" + Math.round(element.height) : "";
+		const off = element.inViewport === false ? " [BELOW FOLD - scroll first]" : "";
+		const state = [
+			element.disabled === true ? "DISABLED" : "",
+			element.required === true ? "required" : "",
+			element.invalid === true ? "invalid" : "",
+			element.checked === true ? "checked" : "",
+			element.expanded === false ? "collapsed" : ""
+		].filter((flag) => flag !== "").join(",");
+		const marks = state === "" ? "" : " [" + state + "]";
+		return "[" + index + "] " + role + " " + JSON.stringify(name) + value + size + " at (" + at + ")" + off + marks;
+	}).join("\n");
+}
+/**
+* The one line that keeps a response self-teaching.
+*
+* An agent meeting this toolset for the first time should learn the next
+* move from the response it already has, not from a manual it will never
+* read. So every tool ends by naming the call that usually follows.
+*/
+function nextHint(next) {
+	return "\nnext: " + next;
+}
+/**
+* Render a click, distinguishing the two outcomes an agent must not confuse.
+*
+* A dispatched event is not a delivered one. When something covers the target
+* -- an overlay, a cookie bar, an extension injected into the page -- the click
+* reaches that instead and the page appears to do nothing, which reads as a
+* broken app rather than a blocked click. Naming the cover turns a dead end
+* into a decision: scroll, dismiss, or target the overlay itself.
+*/
+function renderClick(value, target) {
+	const record = asRecord(value);
+	if (record.landed === false) {
+		const cover = record.occludedBy ? " it was covered by <" + String(record.occludedBy) + ">" + (record.hitText ? " " + JSON.stringify(record.hitText) : "") : " something else was on top of it";
+		return [{
+			type: "text",
+			text: "The click on " + target + " in container " + String(record.containerId) + " did NOT land:" + cover + "." + nextHint("scroll with box_scroll, or dismiss the covering element, then click again")
+		}];
+	}
+	return [{
+		type: "text",
+		text: "Clicked " + target + " in container " + String(record.containerId) + "." + nextHint("call box_page_text to see what the page looks like now")
+	}];
+}
+function applyBoxTools(ctx) {
+	registerTool(ctx, {
+		name: "box_screenshot",
+		description: "Save what a running dshbox container currently renders as a PNG, and report where.This is the one tool whose picture you do not get: a tool result is assistant-side contentand the host sends text only on that side, so you receive the dimensions and nothing else.Asking yourself to look at the image asks for something that cannot arrive, and re-readingthe file path does not change that. So take one to leave something a person can look at,and use box_page_text to find out what is on the page. In practice: describe the page inyour answer, and save a PNG when the layout or a rendering is what is worth showingrather than describing.",
+		parameters: {
+			type: "object",
+			properties: {
+				containerId: {
+					type: "string",
+					description: "Container id to look at, e.g. from a container list."
+				},
+				fullPage: {
+					type: "boolean",
+					description: "Capture the whole scrollable page instead of the viewport. Defaults to false."
+				}
+			},
+			required: ["containerId"]
+		},
+		timeoutMs: LAUNCH_BUDGET_MS,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					containerId: { type: "string" },
+					attachment: { type: "object" }
+				},
+				required: ["containerId", "attachment"]
+			},
+			render: (_args, value) => {
+				const record = asRecord(value);
+				const shot = asRecord(record.attachment);
+				return [{
+					type: "text",
+					text: "Screenshot of container " + String(record.containerId) + " at " + String(shot.width) + "x" + String(shot.height) + "."
+				}, {
+					type: "image",
+					attachment: record.attachment
+				}];
+			}
+		},
+		async execute(args) {
+			const containerId = containerIdOf(args);
+			const raw = await withSession(containerId, "debug_capture_screenshot", {
+				format: "png",
+				fullPage: asRecord(args).fullPage === true
+			});
+			const data = Buffer.from(base64Of(raw), "base64");
+			return {
+				containerId,
+				attachment: await hostServices(ctx).attachments.saveImage({
+					data: new Uint8Array(data),
+					mediaType: "image/png"
+				})
+			};
+		}
+	});
+	registerTool(ctx, {
+		name: "box_click_element",
+		description: "Click a control on a running dshbox container page, at its centre, and report whether the click landed. Identify the target either by the role and name box_page_text returned, or by a CSS selector. Prefer role and name: a name is already in hand from the listing, while a selector has to be guessed and a guessed selector that happens to match hits the wrong control and still reports success. Add within when the same name appears both in a dialog and on the page behind it. Prefer this over box_click_at, which needs you to compute a point yourself.",
+		parameters: {
+			type: "object",
+			properties: {
+				containerId: {
+					type: "string",
+					description: "Container id to click in."
+				},
+				name: {
+					type: "string",
+					description: "Accessible name of the control, matched exactly, e.g. the one box_page_text reported."
+				},
+				role: {
+					type: "string",
+					description: "Role to require alongside the name, e.g. button or textbox."
+				},
+				within: {
+					type: "string",
+					description: "Container name to scope the search to, when the same name appears in more than one place."
+				},
+				selector: {
+					type: "string",
+					description: "CSS selector instead of a name, e.g. button.submit or [role=button]."
+				}
+			},
+			required: ["containerId"]
+		},
+		timeoutMs: WARM_BUDGET_MS,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					containerId: { type: "string" },
+					name: { type: "string" },
+					matched: { type: "string" },
+					landed: { type: "boolean" },
+					hitTag: { type: "string" },
+					hitText: { type: "string" },
+					occludedBy: { type: "string" },
+					selector: { type: "string" },
+					x: { type: "number" },
+					y: { type: "number" },
+					tag: { type: "string" },
+					text: { type: "string" }
+				},
+				required: [
+					"containerId",
+					"x",
+					"y",
+					"landed"
+				]
+			},
+			render: (_args, value) => {
+				const record = asRecord(value);
+				const label = textOf(record.text);
+				return renderClick(value, (typeof record.name === "string" && record.name !== "" ? JSON.stringify(record.name) : "<" + String(record.tag) + "> matching " + String(record.selector)) + (label ? " labelled " + JSON.stringify(label) : ""));
+			}
+		},
+		async execute(args) {
+			const containerId = containerIdOf(args);
+			const record = asRecord(args);
+			const name = record.name;
+			const selector = record.selector;
+			const hasName = typeof name === "string" && name.trim() !== "";
+			const hasSelector = typeof selector === "string" && selector.trim() !== "";
+			if (!hasName && !hasSelector) throw new Error("give a name, a selector, or both");
+			if (hasName) return {
+				containerId,
+				...await withSession(containerId, "debug_click_by_name", {
+					name,
+					role: typeof record.role === "string" ? record.role : void 0,
+					within: typeof record.within === "string" ? record.within : void 0
+				})
+			};
+			return {
+				containerId,
+				...await withSession(containerId, "debug_click_element", { selector })
+			};
+		}
+	});
+	registerTool(ctx, {
+		name: "box_click_at",
+		description: "Click a viewport point. Use it only when the target has no accessible name: coordinates come from box_page_text or from box_screenshot. Prefer box_click_element whenever a name was listed.",
+		parameters: {
+			type: "object",
+			properties: {
+				containerId: {
+					type: "string",
+					description: "Container id to click in."
+				},
+				x: {
+					type: "number",
+					description: "Horizontal viewport coordinate, from the left edge."
+				},
+				y: {
+					type: "number",
+					description: "Vertical viewport coordinate, from the top edge."
+				}
+			},
+			required: [
+				"containerId",
+				"x",
+				"y"
+			]
+		},
+		timeoutMs: WARM_BUDGET_MS,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					containerId: { type: "string" },
+					x: { type: "number" },
+					y: { type: "number" }
+				},
+				required: [
+					"containerId",
+					"x",
+					"y"
+				]
+			},
+			render: (_args, value) => renderClick(value, "at (" + String(asRecord(value).x) + ", " + String(asRecord(value).y) + ")")
+		},
+		async execute(args) {
+			const containerId = containerIdOf(args);
+			const record = asRecord(args);
+			if (typeof record.x !== "number" || typeof record.y !== "number") throw new Error("x and y are required numbers");
+			return {
+				containerId,
+				...await withSession(containerId, "debug_click_at", {
+					x: record.x,
+					y: record.y
+				})
+			};
+		}
+	});
+	registerTool(ctx, {
+		name: "box_page_text",
+		description: "CALL THIS FIRST when you need to know what is on a page. It renders the whole page as text: every control and region with its role, name, on-screen position, and whether it is currently visible, and whether it is disabled. It needs no selector, and it is the only listing: there is no second way to ask what is on a page. Then hand the role+name it returns straight back to box_click_element. Anything marked BELOW FOLD needs box_scroll before you can act on it.",
+		parameters: {
+			type: "object",
+			properties: {
+				containerId: {
+					type: "string",
+					description: "Container id to read."
+				},
+				role: {
+					type: "string",
+					description: "Only roles containing this text, e.g. button or textbox. Omit for everything."
+				},
+				within: {
+					type: "string",
+					description: "NaNname is ambiguous: a settings dialog and the chat screen behind it canboth offer the same one, and acting on the wrong element still looks likeit worked."
+				},
+				limit: {
+					type: "number",
+					description: "Maximum entries to return. Defaults to 200."
+				}
+			},
+			required: ["containerId"]
+		},
+		timeoutMs: WARM_BUDGET_MS,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					containerId: { type: "string" },
+					count: { type: "number" },
+					truncated: { type: "boolean" },
+					belowFold: { type: "number" },
+					elements: {
+						type: "array",
+						items: { type: "object" }
+					}
+				},
+				required: [
+					"containerId",
+					"count",
+					"truncated",
+					"belowFold",
+					"elements"
+				]
+			},
+			render: (_args, value) => {
+				const record = asRecord(value);
+				const elements = Array.isArray(record.elements) ? record.elements : [];
+				const below = Number(record.belowFold ?? 0);
+				const lines = [];
+				lines.push("Page of container " + String(record.containerId) + ": " + String(record.count) + " entr" + (record.count === 1 ? "y" : "ies") + (record.truncated === true ? " (truncated at the limit)." : "."));
+				if (below > 0) lines.push(below + " entr" + (below === 1 ? "y is" : "ies are") + " below the fold; call box_scroll to reach them.");
+				lines.push(renderPageElements(elements));
+				lines.push(nextHint("act on an entry with box_click_element (role+name) or box_click_at (x,y)"));
+				return [{
+					type: "text",
+					text: lines.join("\n")
+				}];
+			}
+		},
+		async execute(args) {
+			const containerId = containerIdOf(args);
+			const record = asRecord(args);
+			return {
+				containerId,
+				...await withSession(containerId, "debug_page_text", {
+					role: typeof record.role === "string" ? record.role : void 0,
+					limit: typeof record.limit === "number" ? record.limit : void 0,
+					within: typeof record.within === "string" ? record.within : void 0
+				})
+			};
+		}
+	});
+	registerTool(ctx, {
+		name: "box_scroll",
+		description: "How far a page extends, and optionally scroll it. With no coordinates it reports how many screens are below the fold, which is how you learn a control exists but is not reachable yet; an absolute pixel offset moves. Coordinates are viewport pixels, so a listed position is used as-is.",
+		parameters: {
+			type: "object",
+			properties: {
+				containerId: {
+					type: "string",
+					description: "Container id to scroll."
+				},
+				to: {
+					type: "number",
+					description: "Absolute scroll offset in pixels. Omit to only report the extent."
+				}
+			},
+			required: ["containerId"]
+		},
+		timeoutMs: WARM_BUDGET_MS,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					containerId: { type: "string" },
+					scrollTop: { type: "number" },
+					scrollHeight: { type: "number" },
+					viewportHeight: { type: "number" },
+					screensBelow: { type: "number" },
+					moved: { type: "boolean" }
+				},
+				required: [
+					"containerId",
+					"scrollTop",
+					"scrollHeight",
+					"viewportHeight",
+					"screensBelow",
+					"moved"
+				]
+			},
+			render: (_args, value) => {
+				const record = asRecord(value);
+				const below = Number(record.screensBelow ?? 0);
+				return [{
+					type: "text",
+					text: "Scroll of container " + String(record.containerId) + ": at " + String(record.scrollTop) + " of " + String(record.scrollHeight) + " px, viewport " + String(record.viewportHeight) + " px." + (record.moved === true ? " Moved." : "") + (below > 0 ? " " + below + " screen(s) still below." : " Nothing below the fold.") + nextHint("call box_page_text again to see the newly reachable entries")
+				}];
+			}
+		},
+		async execute(args) {
+			const containerId = containerIdOf(args);
+			const record = asRecord(args);
+			return {
+				containerId,
+				...await withSession(containerId, "debug_scroll", { to: typeof record.to === "number" ? record.to : void 0 })
+			};
+		}
+	});
+	registerTool(ctx, {
+		name: "box_type_text",
+		description: "Type into whatever has focus. Click the field with box_click_element first. It reports which element held focus, so a value that landed nowhere reads as a failure rather than a silent no-op. For a submit use box_press_key with Enter.",
+		parameters: {
+			type: "object",
+			properties: {
+				containerId: {
+					type: "string",
+					description: "Container id to type into."
+				},
+				text: {
+					type: "string",
+					description: "Text to insert at the focused field."
+				}
+			},
+			required: ["containerId", "text"]
+		},
+		timeoutMs: WARM_BUDGET_MS,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					containerId: { type: "string" },
+					inserted: { type: "number" },
+					focused: { type: "string" },
+					landed: { type: "boolean" }
+				},
+				required: [
+					"containerId",
+					"inserted",
+					"landed"
+				]
+			},
+			render: (_args, value) => {
+				const record = asRecord(value);
+				return [{
+					type: "text",
+					text: record.landed === true ? "Typed " + String(record.inserted) + " character(s) into <" + String(record.focused ?? "input") + "> in container " + String(record.containerId) + "." + nextHint("press Enter with box_press_key to submit, or click the submit control") : "Nothing was focused, so the " + String(record.inserted) + " character(s) went nowhere." + nextHint("click the field with box_click_element first, then type again")
+				}];
+			}
+		},
+		async execute(args) {
+			const containerId = containerIdOf(args);
+			const record = asRecord(args);
+			if (typeof record.text !== "string" || record.text === "") throw new Error("text is required and must be non-empty");
+			return {
+				containerId,
+				...await withSession(containerId, "debug_type_text", { text: record.text })
+			};
+		}
+	});
+	registerTool(ctx, {
+		name: "box_press_key",
+		description: "Press and release one named key. Enter submits a form and nothing that is not a form, so when a click on submit reports landed:false, try Enter. Names: Enter, Tab, Escape, Backspace, Delete, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown, Shift, Control, Alt. An unknown name is an error, never a guess.",
+		parameters: {
+			type: "object",
+			properties: {
+				containerId: {
+					type: "string",
+					description: "Container id to press in."
+				},
+				key: {
+					type: "string",
+					description: "Key name, e.g. Enter or PageDown."
+				}
+			},
+			required: ["containerId", "key"]
+		},
+		timeoutMs: WARM_BUDGET_MS,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					containerId: { type: "string" },
+					key: { type: "string" }
+				},
+				required: ["containerId", "key"]
+			},
+			render: (_args, value) => {
+				const record = asRecord(value);
+				return [{
+					type: "text",
+					text: "Pressed " + String(record.key) + " in container " + String(record.containerId) + "." + nextHint("call box_page_text to see what the page looks like now")
+				}];
+			}
+		},
+		async execute(args) {
+			const containerId = containerIdOf(args);
+			const record = asRecord(args);
+			if (typeof record.key !== "string" || record.key.trim() === "") throw new Error("key is required");
+			return {
+				containerId,
+				...await withSession(containerId, "debug_press_key", { key: record.key.trim() })
+			};
+		}
+	});
+	registerTool(ctx, {
+		name: "box_set_browser",
+		description: "Choose which browser the other box_* tools drive, and report the one in use. Call it when a page tool fails to launch a browser, or when auto-detection picks a browser you would rather not use. Pass an absolute path to a Chrome or Edge executable to pin it; pass an empty string to go back to auto-detection. The path is validated before it is saved, so a typo is rejected here rather than surfacing later as a failed launch.",
+		parameters: {
+			type: "object",
+			properties: { path: {
+				type: "string",
+				description: "Absolute path to a browser executable, or an empty string to return to auto-detection."
+			} },
+			required: []
+		},
+		timeoutMs: WARM_BUDGET_MS,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					available: { type: "boolean" },
+					kind: { type: "string" },
+					path: { type: "string" },
+					configured: { type: "boolean" },
+					configuredPath: { type: "string" },
+					problem: { type: "string" }
+				},
+				required: ["available"]
+			},
+			render: (_args, value) => {
+				const record = asRecord(value);
+				if (record.available === false) return [{
+					type: "text",
+					text: "No browser is available: " + String(record.problem ?? "unknown reason") + (record.configuredPath ? " (configured: " + String(record.configuredPath) + ")" : "") + nextHint("pass a browser executable path to box_set_browser, then retry the page tool")
+				}];
+				const pinned = record.configured === true;
+				return [{
+					type: "text",
+					text: "Using " + String(record.kind ?? "browser") + " at " + String(record.path ?? "unknown") + (pinned ? " (pinned by you)." : " (auto-detected).") + nextHint("call box_page_text to see what the page looks like now")
+				}];
+			}
+		},
+		async execute(args) {
+			const record = asRecord(args);
+			const path = typeof record.path === "string" ? record.path : "";
+			return path === "" && record.path === void 0 ? getRpc().call("debug_browser_status", {}) : getRpc().call("debug_set_browser_path", { path });
+		}
+	});
+	registerTool(ctx, {
+		name: "box_close",
+		description: "Release the headless browser. For tidying up after a long debugging session, not for making something work: sessions also close on their own, and the next page tool opens a fresh one.",
+		parameters: {
+			type: "object",
+			properties: { containerId: {
+				type: "string",
+				description: "Container whose browser session to close."
+			} },
+			required: ["containerId"]
+		},
+		timeoutMs: WARM_BUDGET_MS,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					containerId: { type: "string" },
+					closed: { type: "boolean" }
+				},
+				required: ["containerId", "closed"]
+			},
+			render: (_args, value) => {
+				const record = asRecord(value);
+				return [{
+					type: "text",
+					text: (record.closed === true ? "Closed" : "There was no open session to close for") + " the browser of container " + String(record.containerId) + "."
+				}];
+			}
+		},
+		async execute(args) {
+			const containerId = containerIdOf(args);
+			return {
+				containerId,
+				...await getRpc().call("debug_close", { id: containerId })
+			};
+		}
+	});
+}
+//#endregion
+//#region src/manage.ts
+/** A long operation; a container start can sit on a prepare for minutes. */
+const LONG_BUDGET_MS = 9e5;
+/** Read a value that must be a non-empty string, or fail naming the field. */
+function required(args, field) {
+	const value = args[field];
+	if (typeof value !== "string" || value.trim() === "") throw new Error(`${field} is required and must be a non-empty string.`);
+	return value.trim();
+}
+/** Read an optional string, treating blank as absent. */
+function optional(args, field) {
+	const value = args[field];
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
+}
+/** Read an optional boolean that only an explicit `true` turns on. */
+function flag(args, field) {
+	return args[field] === true;
+}
+/** Reject an action a tool does not implement, listing the ones it does. */
+function badAction(tool, given, allowed) {
+	throw new Error(`${String(given)} is not a ${tool} action. Use one of: ${allowed.join(", ")}.`);
+}
+/** Shared shape for the JSON Schema of a single-property action. */
+function actionProperty(tool, allowed) {
+	return {
+		type: "string",
+		enum: [...allowed],
+		description: `What to do. One of: ${allowed.join(", ")} (${tool}).`
+	};
+}
+/** A text-only result with a schema that names what the caller can read. */
+function textOutput(properties, required, render) {
+	return {
+		schema: {
+			type: "object",
+			additionalProperties: false,
+			properties,
+			required
+		},
+		render: (_args, value) => [{
+			type: "text",
+			text: render(value)
+		}]
+	};
+}
+/** Register one tool against the host's tools service, the same path the
+*  page-debugging tools take, so both halves live in one namespace.
+*/
+function register(ctx, definition) {
+	hostServices(ctx).tools.register(definition);
+}
+/** Register the dshbox management tools. */
+function registerManageTools(ctx) {
+	register(ctx, {
+		name: "box_lifecycle",
+		description: "Start, stop, restart, rebuild or remove a dshbox container, and wait for it to finish. This is the tool for anything that changes whether a container runs. It blocks until the operation completes and returns the outcome, so a restart that failed comes back as a failure with the reason rather than a task id and silence. Use it instead of running dshbox on a shell: a start that quietly did not start is the failure this removes. Rebuild re-materialises plugins and resources before starting; restart does not. After a start, box_overview reports the new state. Every action is refused when the target is the container this agent is itself running in, because it restarts or stops the host running the call and the result can never come back. Watch progress with box_task and confirm with box_overview instead.",
+		parameters: {
+			type: "object",
+			properties: {
+				action: actionProperty("lifecycle", [
+					"start",
+					"stop",
+					"stop-now",
+					"restart",
+					"rebuild",
+					"remove"
+				]),
+				containerId: {
+					type: "string",
+					description: "Container to act on. box_overview lists the ids."
+				}
+			},
+			required: ["action", "containerId"]
+		},
+		timeoutMs: LONG_BUDGET_MS,
+		output: textOutput({
+			action: { type: "string" },
+			containerId: { type: "string" },
+			kind: { type: "string" }
+		}, [
+			"action",
+			"containerId",
+			"kind"
+		], (value) => `Container ${String(value.containerId)}: ${String(value.action)} finished as ${String(value.kind)}.`),
+		async execute(args) {
+			const record = args;
+			const containerId = required(record, "containerId");
+			const action = required(record, "action");
+			const rpc = getRpc();
+			const methods = {
+				start: "enqueue_container_start",
+				stop: "enqueue_container_stop",
+				restart: "enqueue_container_restart",
+				rebuild: "enqueue_container_rebuild",
+				remove: "delete_container"
+			};
+			if (action === "stop-now") {
+				if (runsInside(containerId)) throw new Error("This agent is running inside " + containerId + ", so stopping it would end the call before it could report a result.");
+				return {
+					action,
+					containerId,
+					kind: await rpc.call("stop_container", { id: containerId })
+				};
+			}
+			const method = methods[action];
+			if (method === void 0) badAction("lifecycle", action, Object.keys(methods));
+			if (runsInside(containerId)) throw new Error(`This agent is running inside ${containerId}, and ${action} would restart or stop the host running this call, so the result could never be reported -- the session reconnects and the call is simply lost. Cycle the container from outside it (the Box UI, or a dshbox command in a separate terminal), then call box_task to watch the work, or box_overview to confirm the state.`);
+			return {
+				action,
+				containerId,
+				kind: (await runTask(method, { id: containerId })).kind
+			};
+		}
+	});
+	register(ctx, {
+		name: "box_overview",
+		description: "What dshbox currently holds: its containers, its templates and the plugins it knows. Call this first when you do not know what exists, and after any change that could have added or removed something. It answers from the store, so the container ids it prints are the ones box_lifecycle and box_resources accept.",
+		parameters: {
+			type: "object",
+			properties: { include: {
+				type: "string",
+				description: "Comma-separated: box, containers, templates, plugins. Defaults to all four."
+			} },
+			required: []
+		},
+		timeoutMs: 6e4,
+		output: textOutput({
+			box: { type: "object" },
+			containers: {
+				type: "array",
+				items: { type: "object" }
+			},
+			templates: {
+				type: "array",
+				items: { type: "object" }
+			},
+			plugins: {
+				type: "array",
+				items: { type: "object" }
+			}
+		}, [
+			"box",
+			"containers",
+			"templates",
+			"plugins"
+		], (value) => {
+			const lines = [];
+			const box = value.box ?? {};
+			const containers = value.containers ?? [];
+			const templates = value.templates ?? [];
+			const plugins = value.plugins ?? [];
+			const stamp = box.buildStamp !== void 0 ? ` (build ${String(box.buildStamp)})` : "";
+			lines.push(`Box${stamp}: ` + Object.entries(box).filter(([key]) => key !== "buildStamp").map(([key, entry]) => `${key}=${typeof entry === "object" ? JSON.stringify(entry) : String(entry)}`).join("  "));
+			lines.push(`Containers (${containers.length}):`, ...containers.map((row) => `  ${String(row.id)}  ${String(row.name ?? "")}  ${String(row.status ?? "")}`));
+			lines.push(`Templates (${templates.length}):`, ...templates.map((row) => `  ${String(row.name)}  ${String(row.kind ?? "")}`));
+			lines.push(`Plugins (${plugins.length}):`, ...plugins.map((row) => `  ${String(row.name ?? row.id)}`));
+			return lines.join("\n");
+		}),
+		async execute(args) {
+			const want = (optional(args, "include") ?? "box,containers,templates,plugins").split(",").map((part) => part.trim()).filter((part) => part !== "");
+			const rpc = getRpc();
+			const result = {
+				box: {},
+				containers: [],
+				templates: [],
+				plugins: []
+			};
+			if (want.includes("box")) result.box = asObject(await rpc.call("get_info"));
+			if (want.includes("containers")) result.containers = asArray(await rpc.call("list_containers"));
+			if (want.includes("templates")) result.templates = asArray(await rpc.call("list_templates"));
+			if (want.includes("plugins")) result.plugins = asArray(await rpc.call("list_repository_extensions"));
+			return result;
+		}
+	});
+	register(ctx, {
+		name: "box_resources",
+		description: "The state a container persists, and the tools to move it: list what is there, read one file as a YAML tree, write a block, or extract and inject it as a reusable resource. Everything that changes a container waits for the operation to finish and reports the result, so an injection that was refused arrives as a refusal. Reading is the cheapest way to see what a container actually has, including provider credentials -- a secret's existence and size, never its contents.",
+		parameters: {
+			type: "object",
+			properties: {
+				action: actionProperty("resources", [
+					"list",
+					"read",
+					"write",
+					"extract",
+					"inject",
+					"rm",
+					"rm-view",
+					"prune",
+					"types",
+					"views"
+				]),
+				containerId: {
+					type: "string",
+					description: "Container to act on."
+				},
+				path: {
+					type: "string",
+					description: "Container-relative file. Required for read and write, and names the resource kind's default location for extract."
+				},
+				kind: {
+					type: "string",
+					description: "Resource kind, e.g. sessions or credentials. Required by action types."
+				},
+				section: {
+					type: "string",
+					description: "YAML key path to read or write at, e.g. llm-pi-ai. Empty means the whole file."
+				},
+				text: {
+					type: "string",
+					description: "The YAML block to place at --section."
+				},
+				resourceId: {
+					type: "string",
+					description: "Which stored resource to inject or remove."
+				},
+				viewId: {
+					type: "string",
+					description: "Which resource view to remove."
+				},
+				name: {
+					type: "string",
+					description: "Name for an extracted resource."
+				},
+				merge: {
+					type: "boolean",
+					description: "Merge into an existing destination instead of refusing."
+				},
+				overwrite: {
+					type: "boolean",
+					description: "Replace the destination first."
+				},
+				restart: {
+					type: "boolean",
+					description: "Stop a running container, act, then start it again."
+				}
+			},
+			required: ["action", "containerId"]
+		},
+		timeoutMs: LONG_BUDGET_MS,
+		output: textOutput({
+			action: { type: "string" },
+			containerId: { type: "string" },
+			result: { type: "object" }
+		}, [
+			"action",
+			"containerId",
+			"result"
+		], (value) => {
+			const payload = value.result;
+			return `Container ${String(value.containerId)}: ${String(value.action)}.\n` + JSON.stringify(payload, null, 2).slice(0, 6e3);
+		}),
+		async execute(args) {
+			const record = args;
+			const containerId = required(record, "containerId");
+			const action = required(record, "action");
+			const rpc = getRpc();
+			const base = { id: containerId };
+			const carry = (extra) => {
+				const params = {
+					...base,
+					...extra
+				};
+				if (flag(record, "merge")) params.merge = true;
+				if (flag(record, "overwrite")) params.overwrite = true;
+				if (flag(record, "restart")) params.restart = true;
+				return params;
+			};
+			switch (action) {
+				case "list": {
+					const request = { ...base };
+					const kind = optional(record, "kind");
+					if (kind !== void 0) request.plugin = kind;
+					return {
+						action,
+						containerId,
+						result: await rpc.call("list_container_resources", request)
+					};
+				}
+				case "read": return {
+					action,
+					containerId,
+					result: await rpc.call("read_resource_tree", carry({
+						path: required(record, "path"),
+						section: optional(record, "section") ?? ""
+					}))
+				};
+				case "write": {
+					const task = await runTask("enqueue_resource_write", carry({
+						path: required(record, "path"),
+						section: optional(record, "section") ?? "",
+						text: required(record, "text")
+					}));
+					return {
+						action,
+						containerId,
+						result: {
+							kind: task.kind,
+							logPath: task.logPath ?? ""
+						}
+					};
+				}
+				case "extract": {
+					const task = await runTask("enqueue_resource_extract", carry({
+						kind: required(record, "kind"),
+						name: optional(record, "name"),
+						path: optional(record, "path")
+					}));
+					return {
+						action,
+						containerId,
+						result: {
+							kind: task.kind,
+							logPath: task.logPath ?? ""
+						}
+					};
+				}
+				case "inject": {
+					const task = await runTask("enqueue_resource_inject", carry({ resourceId: required(record, "resourceId") }));
+					return {
+						action,
+						containerId,
+						result: {
+							kind: task.kind,
+							logPath: task.logPath ?? ""
+						}
+					};
+				}
+				case "rm": return {
+					action,
+					containerId,
+					result: asObject(await rpc.call("delete_resource", { resourceId: required(record, "resourceId") }))
+				};
+				case "rm-view": return {
+					action,
+					containerId,
+					result: asObject(await rpc.call("delete_resource_view", { id: required(record, "viewId") }))
+				};
+				case "prune": return {
+					action,
+					containerId,
+					result: { removed: await rpc.call("prune_orphaned_data") }
+				};
+				case "types": {
+					const request = {
+						id: containerId,
+						kind: required(record, "kind")
+					};
+					return {
+						action,
+						containerId,
+						result: { types: await rpc.call("list_resource_type", request) }
+					};
+				}
+				case "views": {
+					const request = { id: containerId };
+					const kind = optional(record, "kind");
+					if (kind !== void 0) request.kind = kind;
+					return {
+						action,
+						containerId,
+						result: { views: await rpc.call("list_resource_views", request) }
+					};
+				}
+				default: badAction("resources", action, [
+					"list",
+					"read",
+					"write",
+					"extract",
+					"inject",
+					"rm",
+					"rm-view",
+					"prune",
+					"types",
+					"views"
+				]);
+			}
+		}
+	});
+	register(ctx, {
+		name: "box_build",
+		description: "Build a template from a boxfile, and wait for the build to finish. A template is what you then create a container from. The path is read from the host, so give an absolute one. Applying a resource document is deliberately not here: the daemon has no single method for it, it is a sequence the CLI drives, and re-implementing that sequence in a tool is how two copies drift apart. Use box_resources for moving state.",
+		parameters: {
+			type: "object",
+			properties: {
+				mode: {
+					type: "string",
+					enum: ["build", "apply"],
+					description: "`build` compiles a boxfile into a template. `apply` makes a resource layer match a document."
+				},
+				file: {
+					type: "string",
+					description: "Absolute path to the boxfile, or to the apply document."
+				},
+				document: {
+					type: "string",
+					description: "An apply document as YAML or JSON, given inline instead of a file."
+				},
+				containerId: {
+					type: "string",
+					description: "Which container to apply to. Not used by build."
+				},
+				dryRun: {
+					type: "boolean",
+					description: "Report what apply would change without changing it."
+				}
+			},
+			required: ["mode"]
+		},
+		timeoutMs: LONG_BUDGET_MS,
+		output: textOutput({
+			mode: { type: "string" },
+			file: { type: "string" },
+			result: { type: "object" }
+		}, [
+			"mode",
+			"file",
+			"result"
+		], (value) => `${String(value.mode)} ${String(value.file)}:\n` + JSON.stringify(value.result, null, 2).slice(0, 4e3)),
+		async execute(args) {
+			const record = args;
+			const mode = required(record, "mode");
+			const file = optional(record, "file") ?? "";
+			if (mode === "build") {
+				const task = await runTask("enqueue_build", {
+					path: file,
+					name: optional(record, "containerId")
+				});
+				return {
+					mode,
+					file,
+					result: {
+						kind: task.kind,
+						logPath: task.logPath ?? ""
+					}
+				};
+			}
+			if (mode === "apply") {
+				const rpc = getRpc();
+				const params = { dryRun: flag(record, "dryRun") };
+				const document = optional(record, "document");
+				if (document !== void 0) params.document = document;
+				if (file !== "") params.file = file;
+				return {
+					mode,
+					file,
+					result: await rpc.call("apply_document", params)
+				};
+			}
+			badAction("build", mode, ["build", "apply"]);
+		}
+	});
+	register(ctx, {
+		name: "box_workspace",
+		description: "The directories a container opens its sessions in. add registers one from a path with no file dialog, which is the point: the picker the UI uses opens on the host desktop and nothing driving the app from a script or a tool call can answer it. Add refuses while the container runs, because the running host rewrites its own registry; pass restart to stop, register and start again in that order. Adding a path that is already registered reports it as such rather than failing.",
+		parameters: {
+			type: "object",
+			properties: {
+				action: actionProperty("workspace", ["list", "add"]),
+				containerId: {
+					type: "string",
+					description: "Container whose workspaces to list or extend."
+				},
+				path: {
+					type: "string",
+					description: "Absolute path of an existing directory. Required for add."
+				},
+				title: {
+					type: "string",
+					description: "Name for it. Defaults to the directory's own name."
+				},
+				restart: {
+					type: "boolean",
+					description: "Stop the container, add, then start it again."
+				}
+			},
+			required: ["action", "containerId"]
+		},
+		timeoutMs: LONG_BUDGET_MS,
+		output: textOutput({
+			action: { type: "string" },
+			containerId: { type: "string" },
+			workspaces: {
+				type: "array",
+				items: { type: "object" }
+			},
+			created: { type: "boolean" }
+		}, [
+			"action",
+			"containerId",
+			"workspaces"
+		], (value) => {
+			const rows = value.workspaces ?? [];
+			return [`Workspaces of ${String(value.containerId)} (${rows.length}):`, ...rows.map((row) => `  ${String(row.title)}  ${String(row.path)}  ${String(row.sessions ?? 0)} sessions`)].join("\n");
+		}),
+		async execute(args) {
+			const record = args;
+			const containerId = required(record, "containerId");
+			const action = required(record, "action");
+			const rpc = getRpc();
+			if (action === "list") return {
+				action,
+				containerId,
+				workspaces: (await rpc.call("list_container_workspaces", { id: containerId }))?.workspaces ?? [],
+				created: false
+			};
+			if (action === "add") {
+				const params = {
+					id: containerId,
+					path: required(record, "path")
+				};
+				const title = optional(record, "title");
+				if (title !== void 0) params.title = title;
+				const added = await rpc.call("add_container_workspace", params);
+				return {
+					action,
+					containerId,
+					workspaces: (await rpc.call("list_container_workspaces", { id: containerId })).workspaces ?? [],
+					created: added?.created === true
+				};
+			}
+			badAction("workspace", action, ["list", "add"]);
+		}
+	});
+	register(ctx, {
+		name: "box_set_viewport",
+		description: "Resize the page an agent is looking at, and report the size now in effect. The page opens at 1600x1200, which fits most applications on one screen, but a wide table or a tall form may still fold. A fold is not cosmetic: box_page_text marks anything below the fold, so a control that is in fact visible reads as something to scroll for, and box_click_element on it is a wasted round trip. Make it taller, or wider when a row is being cut off on the right, then read the page again. Resizing keeps the page where it is, so a session survives the change.",
+		parameters: {
+			type: "object",
+			properties: {
+				containerId: {
+					type: "string",
+					description: "Which debug session to resize."
+				},
+				width: {
+					type: "number",
+					description: "Width in CSS pixels. 320-7680. Omit to read the current size."
+				},
+				height: {
+					type: "number",
+					description: "Height in CSS pixels. 240-4320. Omit to read the current size."
+				}
+			},
+			required: ["containerId"]
+		},
+		timeoutMs: 6e4,
+		output: textOutput({
+			width: { type: "number" },
+			height: { type: "number" },
+			clamped: { type: "boolean" }
+		}, ["width", "height"], (value) => `Viewport is now ${String(value.width)}x${String(value.height)}` + (value.clamped === true ? ". That is smaller than it was asked for: the browser has a maximum." : ".")),
+		async execute(args) {
+			const record = args;
+			const containerId = required(record, "containerId");
+			const rpc = getRpc();
+			const params = { id: containerId };
+			const width = number(record, "width");
+			const height = number(record, "height");
+			if (width === void 0 && height === void 0) {
+				const metrics = await rpc.call("debug_set_viewport", params);
+				return {
+					width: Number(metrics.width),
+					height: Number(metrics.height),
+					clamped: false
+				};
+			}
+			if (width === void 0 || height === void 0) throw new Error("Give both width and height to resize the viewport.");
+			const result = await rpc.call("debug_set_viewport", {
+				...params,
+				width,
+				height
+			});
+			return {
+				width: Number(result.width),
+				height: Number(result.height),
+				clamped: result.clamped === true
+			};
+		}
+	});
+	register(ctx, {
+		name: "box_task",
+		description: "Watch, read or cancel dshbox background work. Most box_* calls already wait for their own operation, so reach for this when something is already running, when you want to see what a previous call left behind, or to stop work that should not continue. A task log is a file, and its path comes back with the record.",
+		parameters: {
+			type: "object",
+			properties: {
+				action: actionProperty("task", [
+					"list",
+					"status",
+					"cancel",
+					"delete"
+				]),
+				taskId: {
+					type: "string",
+					description: "Which task. Required for status, cancel and delete."
+				},
+				kind: {
+					type: "string",
+					description: "Only list tasks of this kind, e.g. container-start. Omit for all."
+				}
+			},
+			required: ["action"]
+		},
+		timeoutMs: 6e4,
+		output: textOutput({
+			action: { type: "string" },
+			tasks: {
+				type: "array",
+				items: { type: "object" }
+			}
+		}, ["action", "tasks"], (value) => {
+			const rows = value.tasks ?? [];
+			return [`Tasks (${rows.length}):`, ...rows.map((row) => `  ${String(row.id)}  ${String(row.status)}  ${String(row.progress)}%  ${String(row.kind)}` + (row.error ? `  error: ${String(row.error)}` : ""))].join("\n");
+		}),
+		async execute(args) {
+			const record = args;
+			const action = required(record, "action");
+			const rpc = getRpc();
+			const one = async () => {
+				const task = await rpc.call("task_status", { id: required(record, "taskId") });
+				return {
+					action,
+					tasks: [task]
+				};
+			};
+			switch (action) {
+				case "list": {
+					const all = asArray(await rpc.call("list_tasks"));
+					const kind = optional(record, "kind");
+					return {
+						action,
+						tasks: kind === void 0 ? all : all.filter((row) => String(row.kind) === kind)
+					};
+				}
+				case "status": return one();
+				case "cancel": return {
+					action,
+					tasks: [await rpc.call("cancel_task", { id: required(record, "taskId") })]
+				};
+				case "delete":
+					await rpc.call("delete_task", { id: required(record, "taskId") });
+					return {
+						action,
+						tasks: []
+					};
+				default: badAction("task", action, [
+					"list",
+					"status",
+					"cancel",
+					"delete"
+				]);
+			}
+		}
+	});
+	/**
+	* The arguments one action needs, checked here rather than at the call site.
+	*
+	* The parameter schema is a flat union of every action's fields, so a field
+	* that only one action uses reads as a requirement for all of them, and a
+	* caller that omits it gets whichever branch's complaint fires first --
+	* "extensionId is required" from an action that never wanted it. Naming the
+	* action and its own list turns that into something a caller can act on
+	* without reading the source, which is the whole reason the union is there.
+	*/
+	function needs(record, action, spec) {
+		const missing = (spec[action] ?? []).filter((field) => typeof record[field] !== "string" || record[field].trim() === "");
+		if (missing.length > 0) throw new Error(`box_plugins ${action} needs ${missing.join(" and ")}. For this action the arguments are: ${(spec[action] ?? []).join(", ")}. Actions that need none: list, installed, container, prune, bundle (list).`);
+	}
+	register(ctx, {
+		name: "box_plugins",
+		description: "Plugins a box has, and the ones it can have: the repository, a container, install, import, export, bundles, and the dependency graph. Installing and importing are waited on, so a call ends with a result rather than a task id. One containerId covers all of it: the daemon names that argument differently per method, which is a detail of its wire format and not something a caller should have to remember per verb.",
+		parameters: {
+			type: "object",
+			properties: {
+				action: actionProperty("plugins", [
+					"list",
+					"installed",
+					"container",
+					"add",
+					"add-extension",
+					"copy",
+					"remove-plugin",
+					"import",
+					"export",
+					"export-installed",
+					"import-workspace",
+					"install-bundle",
+					"bundle",
+					"prune",
+					"graph"
+				]),
+				containerId: {
+					type: "string",
+					description: "Container to read, install into, or graph."
+				},
+				profile: {
+					type: "string",
+					description: "Profile inside the container. Defaults to web."
+				},
+				spec: {
+					type: "string",
+					description: "For add, what to install; for import, the directory to import."
+				},
+				extensionId: {
+					type: "string",
+					description: "A repository row id (img-...). For copy, export, install-bundle."
+				},
+				name: {
+					type: "string",
+					description: "A plugin package name for remove-plugin, e.g. @scope/name. Also a bundle name."
+				},
+				path: {
+					type: "string",
+					description: "Absolute path, for importing from or exporting to the workspace."
+				},
+				destination: {
+					type: "string",
+					description: "Absolute path to write an export to."
+				},
+				overwrite: {
+					type: "boolean",
+					description: "Install a bundle, replacing what is there instead of keeping it."
+				},
+				ids: {
+					type: "array",
+					items: { type: "string" },
+					description: "Repository row ids that make up a bundle."
+				},
+				subaction: {
+					type: "string",
+					enum: [
+						"list",
+						"create",
+						"import",
+						"export",
+						"delete"
+					],
+					description: "What to do with a bundle."
+				}
+			},
+			required: ["action"]
+		},
+		timeoutMs: LONG_BUDGET_MS,
+		output: textOutput({
+			action: { type: "string" },
+			result: { type: "object" }
+		}, ["action", "result"], (value) => "box_plugins " + String(value.action) + ":\n" + JSON.stringify(value.result, null, 2).slice(0, 6e3)),
+		async execute(args) {
+			const record = args;
+			const action = required(record, "action");
+			const rpc = getRpc();
+			needs(record, action, {
+				add: ["containerId", "spec"],
+				"add-extension": ["containerId", "spec"],
+				copy: ["containerId", "extensionId"],
+				"remove-plugin": ["containerId", "name"],
+				import: ["spec"],
+				export: ["extensionId"],
+				"export-installed": [
+					"containerId",
+					"path",
+					"destination"
+				],
+				"import-workspace": ["containerId", "path"],
+				"install-bundle": ["containerId", "extensionId"],
+				container: ["containerId"],
+				graph: ["containerId"]
+			});
+			const containerId = optional(record, "containerId");
+			const profile = optional(record, "profile") ?? "web";
+			const needContainer = (what) => {
+				if (containerId === void 0) throw new Error(action + " " + what + " needs a containerId. box_overview lists them.");
+				return containerId;
+			};
+			switch (action) {
+				case "list": return {
+					action,
+					result: { repository: asArray(await rpc.call("list_repository_extensions")) }
+				};
+				case "installed": return {
+					action,
+					result: asObject(await rpc.call("list_installed_plugins"))
+				};
+				case "container": return {
+					action,
+					result: { plugins: await rpc.call("container_list_plugins", {
+						containerId: needContainer("listing"),
+						profile
+					}) }
+				};
+				case "add": {
+					const spec = required(record, "spec");
+					const task = await runTask("container_plugin_add", {
+						containerId: needContainer("installing into"),
+						profile,
+						spec
+					});
+					return {
+						action,
+						result: {
+							kind: task.kind,
+							logPath: task.logPath ?? ""
+						}
+					};
+				}
+				case "import": {
+					const task = await runTask("import_repository_extension", { source: required(record, "spec") });
+					return {
+						action,
+						result: {
+							kind: task.kind,
+							logPath: task.logPath ?? ""
+						}
+					};
+				}
+				case "export": return {
+					action,
+					result: asObject(await rpc.call("export_repository_extension", { repositoryId: required(record, "extensionId") }))
+				};
+				case "remove": return {
+					action,
+					result: asObject(await rpc.call("remove_repository_extension", { id: required(record, "extensionId") }))
+				};
+				case "add-extension": {
+					const task = await runTask("enqueue_container_extension_add", {
+						id: needContainer("adding to"),
+						profile,
+						source: required(record, "spec")
+					});
+					return {
+						action,
+						result: {
+							kind: task.kind,
+							logPath: task.logPath ?? ""
+						}
+					};
+				}
+				case "copy": {
+					const task = await runTask("enqueue_container_extension_copy", {
+						id: needContainer("copying into"),
+						profile,
+						repositoryId: required(record, "extensionId")
+					});
+					return {
+						action,
+						result: {
+							kind: task.kind,
+							logPath: task.logPath ?? ""
+						}
+					};
+				}
+				case "remove-plugin": return {
+					action,
+					result: asObject(await rpc.call("remove_repository_plugin", {
+						id: needContainer("removing from"),
+						profile,
+						name: required(record, "name")
+					}))
+				};
+				case "export-installed": {
+					const task = await runTask("enqueue_plugin_export", {
+						sourceContainerId: needContainer("exporting from"),
+						sourcePath: required(record, "path"),
+						destination: required(record, "destination")
+					});
+					return {
+						action,
+						result: {
+							kind: task.kind,
+							logPath: task.logPath ?? ""
+						}
+					};
+				}
+				case "import-workspace": {
+					const task = await runTask("enqueue_workspace_extension_import", {
+						id: needContainer("importing into"),
+						relativePath: required(record, "path")
+					});
+					return {
+						action,
+						result: {
+							kind: task.kind,
+							logPath: task.logPath ?? ""
+						}
+					};
+				}
+				case "install-bundle": {
+					const task = await runTask("enqueue_container_bundle_install", {
+						id: needContainer("installing into"),
+						profile,
+						bundleId: required(record, "extensionId"),
+						conflict: flag(record, "overwrite") ? "overwrite" : "keep"
+					});
+					return {
+						action,
+						result: {
+							kind: task.kind,
+							logPath: task.logPath ?? ""
+						}
+					};
+				}
+				case "prune": return {
+					action,
+					result: { removed: asArray(await rpc.call("prune_repository_extensions")) }
+				};
+				case "bundle": {
+					const name = optional(record, "name");
+					const ids = Array.isArray(record.ids) ? record.ids.filter((e) => typeof e === "string") : [];
+					const sub = optional(record, "subaction") ?? (name === void 0 ? "list" : ids.length === 0 ? "create" : "export");
+					if (sub === "list") return {
+						action,
+						result: { bundles: asArray(await rpc.call("list_bundles")) }
+					};
+					if (name === void 0 && ids.length === 0) throw new Error("bundle " + sub + " needs a name or ids.");
+					if (sub === "create") return {
+						action,
+						result: asObject(await rpc.call("create_extension_bundle", {
+							name,
+							repositoryIds: ids
+						}))
+					};
+					if (sub === "export") return {
+						action,
+						result: asObject(await rpc.call("export_bundle", {
+							bundleId: name,
+							destination: required(record, "destination"),
+							mode: "archive"
+						}))
+					};
+					if (sub === "delete") return {
+						action,
+						result: asObject(await rpc.call("delete_extension_bundle", { id: name }))
+					};
+					return {
+						action,
+						result: asObject(await rpc.call("import_bundle", {
+							archive: required(record, "destination"),
+							conflict: flag(record, "overwrite") ? "overwrite" : "keep"
+						}))
+					};
+				}
+				case "graph": return {
+					action,
+					result: asObject(await rpc.call("plugin_dependency_graph", {
+						id: needContainer("graphing"),
+						kind: "container"
+					}))
+				};
+				default: badAction("plugins", action, [
+					"list",
+					"installed",
+					"container",
+					"add",
+					"add-extension",
+					"copy",
+					"remove-plugin",
+					"import",
+					"export",
+					"export-installed",
+					"import-workspace",
+					"install-bundle",
+					"bundle",
+					"prune",
+					"graph"
+				]);
+			}
+		}
+	});
+	register(ctx, {
+		name: "box_create",
+		description: "Make a container, and look at one in full. An agent that can start and stop containers but not create them is doing half the job: create from a template, create from a DSH version, describe what exists, get the URL a running one is serving, or list the directories a container can open. Creating from a template starts the container and returns its id, so the next call can act on it. A plain create materialises the tree without starting anything; start it with box_lifecycle. The name has to be safe for a path, and is not the id.",
+		parameters: {
+			type: "object",
+			properties: {
+				action: actionProperty("create", [
+					"from-template",
+					"from-version",
+					"describe",
+					"url",
+					"browse"
+				]),
+				name: {
+					type: "string",
+					description: "Name for a new container, or which one to describe."
+				},
+				template: {
+					type: "string",
+					description: "Template to create from. Defaults to the one box_templates reports."
+				},
+				version: {
+					type: "string",
+					description: "DSH version to create from, for from-version."
+				},
+				containerId: {
+					type: "string",
+					description: "Which container, for describe, url and browse."
+				},
+				profile: {
+					type: "string",
+					description: "Profile to create with. Defaults to web."
+				},
+				start: {
+					type: "boolean",
+					description: "Start it after creating. Only from-version; from-template always starts."
+				}
+			},
+			required: ["action"]
+		},
+		timeoutMs: LONG_BUDGET_MS,
+		output: textOutput({
+			action: { type: "string" },
+			result: { type: "object" }
+		}, ["action", "result"], (value) => "box_create " + String(value.action) + ":\n" + JSON.stringify(value.result, null, 2).slice(0, 6e3)),
+		async execute(args) {
+			const record = args;
+			const action = required(record, "action");
+			const rpc = getRpc();
+			const profile = optional(record, "profile") ?? "web";
+			const needId = () => {
+				const id = optional(record, "containerId");
+				if (id === void 0) throw new Error("create " + action + " needs a containerId. box_overview lists them.");
+				return id;
+			};
+			switch (action) {
+				case "from-template": {
+					const name = required(record, "name");
+					const template = optional(record, "template");
+					if (template === void 0) throw new Error("from-template needs a template name; box_templates with action list reports what exists.");
+					const task = await runTask("create_container_from_template", {
+						name,
+						template,
+						profile
+					});
+					return {
+						action,
+						result: {
+							kind: task.kind,
+							name,
+							logPath: task.logPath ?? ""
+						}
+					};
+				}
+				case "from-version": {
+					const name = required(record, "name");
+					const version = optional(record, "version");
+					if (version === void 0) throw new Error("from-version needs a DSH version; box_templates with action catalog reports what exists.");
+					const created = await rpc.call("create_container", {
+						name,
+						version,
+						profile
+					});
+					const id = created && created.id !== void 0 ? String(created.id) : "";
+					if (id !== "" && flag(record, "start")) await runTask("enqueue_container_start", { id });
+					return {
+						action,
+						result: {
+							...created,
+							started: id !== "" && flag(record, "start")
+						}
+					};
+				}
+				case "describe": return {
+					action,
+					result: asObject(await rpc.call("describe_container", { id: needId() }))
+				};
+				case "url": return {
+					action,
+					result: asObject(await rpc.call("container_url", { id: needId() }))
+				};
+				case "browse": return {
+					action,
+					result: asObject(await rpc.call("browse_container_paths", { id: needId() }))
+				};
+				default: badAction("create", action, [
+					"from-template",
+					"from-version",
+					"describe",
+					"url",
+					"browse"
+				]);
+			}
+		}
+	});
+	register(ctx, {
+		name: "box_templates",
+		description: "The templates a box can create containers from, and the DSH versions behind them: list them, read one, pull a newer one, import an archive, export one out, or remove one. Pulling and importing are waited on. A template is the shape a new container starts from, so this is what you look at before box_create from-template. Removing one is refused while a container was built from it.",
+		parameters: {
+			type: "object",
+			properties: {
+				action: actionProperty("templates", [
+					"list",
+					"show",
+					"pull",
+					"import",
+					"export",
+					"remove",
+					"prune",
+					"catalog"
+				]),
+				name: {
+					type: "string",
+					description: "Which template, or which DSH version to pull."
+				},
+				archive: {
+					type: "string",
+					description: "Absolute path of an archive to import."
+				},
+				destination: {
+					type: "string",
+					description: "Where to write an export. Defaults to a temp file."
+				},
+				versions: {
+					type: "boolean",
+					description: "With list, also report installed DSH versions."
+				}
+			},
+			required: ["action"]
+		},
+		timeoutMs: LONG_BUDGET_MS,
+		output: textOutput({
+			action: { type: "string" },
+			result: { type: "object" }
+		}, ["action", "result"], (value) => "box_templates " + String(value.action) + ":\n" + JSON.stringify(value.result, null, 2).slice(0, 6e3)),
+		async execute(args) {
+			const record = args;
+			const action = required(record, "action");
+			const rpc = getRpc();
+			switch (action) {
+				case "list": {
+					const result = { templates: asArray(await rpc.call("list_templates")) };
+					if (flag(record, "versions")) result.dshVersions = asObject(await rpc.call("list_installed_dsh_versions"));
+					return {
+						action,
+						result
+					};
+				}
+				case "show": return {
+					action,
+					result: asObject(await rpc.call("read_template", { name: required(record, "name") }))
+				};
+				case "catalog": return {
+					action,
+					result: asObject(await rpc.call("list_dsh_catalog"))
+				};
+				case "pull": {
+					const task = await runTask("pull_template", { name: required(record, "name") });
+					return {
+						action,
+						result: {
+							kind: task.kind,
+							logPath: task.logPath ?? ""
+						}
+					};
+				}
+				case "import": {
+					const params = { archive: required(record, "archive") };
+					const name = optional(record, "name");
+					if (name !== void 0) params.name = name;
+					return {
+						action,
+						result: asObject(await rpc.call("import_template", params))
+					};
+				}
+				case "export": {
+					const params = { name: required(record, "name") };
+					const destination = optional(record, "destination");
+					if (destination !== void 0) params.destination = destination;
+					return {
+						action,
+						result: asObject(await rpc.call("export_template", params))
+					};
+				}
+				case "remove": return {
+					action,
+					result: asObject(await rpc.call("remove_template", { name: required(record, "name") }))
+				};
+				case "prune": return {
+					action,
+					result: { removed: asArray(await rpc.call("prune_template_snapshots")) }
+				};
+				default: badAction("templates", action, [
+					"list",
+					"show",
+					"pull",
+					"import",
+					"export",
+					"remove",
+					"prune",
+					"catalog"
+				]);
+			}
+		}
+	});
+	register(ctx, {
+		name: "box_settings",
+		description: "The box itself rather than anything in it: the toolchains and DSH versions it can use, the catalogue of versions available, the mirrors and runtime directory it is configured with, and the templates behind them. The read actions need nothing. The ones that change the box for everything on this machine -- moving where its data lives, changing the mirrors, removing an installed DSH version -- need confirm true, so they cannot happen by accident from a half-remembered argument. Moving the runtime directory rebuilds the plugin set and asks for a restart; the reply says so.",
+		parameters: {
+			type: "object",
+			properties: {
+				action: actionProperty("settings", [
+					"toolchains",
+					"installed",
+					"catalog",
+					"refresh-catalog",
+					"data",
+					"references",
+					"template-info",
+					"template-list",
+					"save-mirrors",
+					"set-runtime-directory",
+					"uninstall-dsh"
+				]),
+				version: {
+					type: "string",
+					description: "Which DSH version, for uninstall-dsh or template-info."
+				},
+				runtimeDirectory: {
+					type: "string",
+					description: "Absolute path to move the box data to."
+				},
+				githubMirror: {
+					type: "string",
+					description: "GitHub mirror URL. Omit to clear it."
+				},
+				npmRegistry: {
+					type: "string",
+					description: "npm registry URL. Omit to clear it."
+				},
+				confirm: {
+					type: "boolean",
+					description: "Required true for the three actions that change the box itself."
+				}
+			},
+			required: ["action"]
+		},
+		timeoutMs: LONG_BUDGET_MS,
+		output: textOutput({
+			action: { type: "string" },
+			result: { type: "object" }
+		}, ["action", "result"], (value) => "box_settings " + String(value.action) + ":\n" + JSON.stringify(value.result, null, 2).slice(0, 6e3)),
+		async execute(args) {
+			const record = args;
+			const action = required(record, "action");
+			const rpc = getRpc();
+			const what = {
+				"save-mirrors": "changing the mirrors every install goes through",
+				"set-runtime-directory": "moving where all box data lives",
+				"uninstall-dsh": "removing an installed DSH version"
+			}[action];
+			if (what !== void 0 && !flag(record, "confirm")) throw new Error(action + " means " + what + ", and it affects every container and every future session, not just this one. Pass confirm true when that is what you want.");
+			switch (action) {
+				case "toolchains": return {
+					action,
+					result: asObject(await rpc.call("detect_toolchains"))
+				};
+				case "installed": return {
+					action,
+					result: asObject(await rpc.call("list_installed_dsh_versions"))
+				};
+				case "catalog": return {
+					action,
+					result: asObject(await rpc.call("list_dsh_catalog"))
+				};
+				case "refresh-catalog": {
+					const task = await runTask("refresh_dsh_catalog", {});
+					return {
+						action,
+						result: {
+							kind: task.kind,
+							logPath: task.logPath ?? ""
+						}
+					};
+				}
+				case "data": return {
+					action,
+					result: { entries: asArray(await rpc.call("list_data_entries")) }
+				};
+				case "references": return {
+					action,
+					result: asObject(await rpc.call("list_repository_reference_counts"))
+				};
+				case "template-info": return {
+					action,
+					result: asObject(await rpc.call("template_info", { name: required(record, "version") }))
+				};
+				case "template-list": return {
+					action,
+					result: asObject(await rpc.call("read_template_list", { name: required(record, "version") }))
+				};
+				case "save-mirrors": {
+					const params = {};
+					params.githubMirror = optional(record, "githubMirror") ?? null;
+					params.npmRegistry = optional(record, "npmRegistry") ?? null;
+					return {
+						action,
+						result: asObject(await rpc.call("save_mirror_settings", params))
+					};
+				}
+				case "set-runtime-directory": return {
+					action,
+					result: asObject(await rpc.call("save_runtime_directory", { runtimeDirectory: required(record, "runtimeDirectory") }))
+				};
+				case "uninstall-dsh": return {
+					action,
+					result: asObject(await rpc.call("uninstall_dsh_version", { version: required(record, "version") }))
+				};
+				default: badAction("settings", action, [
+					"toolchains",
+					"installed",
+					"catalog",
+					"refresh-catalog",
+					"data",
+					"references",
+					"template-info",
+					"template-list",
+					"save-mirrors",
+					"set-runtime-directory",
+					"uninstall-dsh"
+				]);
+			}
+		}
+	});
+}
+/** Keep a structured RPC reply an object, so rendering never sees an array. */
+function asObject(value) {
+	if (typeof value === "object" && value !== null && !Array.isArray(value)) return value;
+	return { value };
+}
+/**
+* True when this plugin is running inside the container it was asked about.
+*
+* Nothing hands a plugin its own container id -- the host process is told which
+* container it is, but not the plugins it mounts -- so it is read back out of
+* where the plugin is installed, which is always
+* `<instance>/profile/profiles/<p>/node_modules/...`: the container id is a
+* directory name on the way to it.
+*
+* Comparing path segments to the id that was passed in, rather than testing the
+* id's shape, is the point. An earlier version matched a UUID 8-4-4-4-12 and
+* silently never matched anything: real ids are `container-<10 digits>-<uuid>`,
+* with a unix timestamp in front. A guard that quietly does not fire is worse
+* than no guard, because the code reads as though the case is handled.
+*/
+function runsInside(containerId) {
+	let here;
+	try {
+		here = dirname(fileURLToPath(import.meta.url));
+	} catch {
+		return false;
+	}
+	return here.split(/[\\/]/).includes(containerId);
+}
+/** Read an optional finite number, treating blank and NaN as absent. */
+function number(args, field) {
+	const value = args[field];
+	if (typeof value !== "number" || !Number.isFinite(value)) return void 0;
+	return Math.round(value);
+}
+/** The daemon answers list-shaped methods with a bare array; guard that here. */
+function asArray(value) {
+	if (Array.isArray(value)) return value;
+	if (typeof value === "object" && value !== null) for (const key of [
+		"containers",
+		"templates",
+		"plugins",
+		"items",
+		"rows"
+	]) {
+		const nested = value[key];
+		if (Array.isArray(nested)) return nested;
+	}
+	return [];
+}
+//#endregion
+//#region src/index.ts
+/** Cordis plugin name used by loader diagnostics and the patch overlay. */
+const name = "dsh-box-sandbox";
+/**
+* Services this plugin depends on. Empty for now: the client is pure
+* transport and needs no host service. Tools built on top of it will
+* declare their own.
+*/
+const inject = [
+	"tools",
+	"attachments",
+	"systemPrompt"
+];
+/**
+* Effective configuration after defaults.
+*
+* Deliberately not a schemastery schema. A schema would make this entry
+* import `@deepseek-ai/schemastery` at module load, and a bare import that
+* cannot be resolved from wherever the plugin was installed is a *load*
+* failure -- DSH reports it as "failed to import" and the tool never mounts.
+* The two knobs are read from the environment instead, which costs a schema
+* nobody has to keep in sync and makes the bundle import nothing but node:*.
+*/
+function resolveConfig(config) {
+	const fromEnv = process.env.DSHBOX_RPC_TIMEOUT_MS;
+	const parsed = fromEnv === void 0 ? NaN : Number(fromEnv);
+	return {
+		configDir: config?.configDir ?? process.env.DSHBOX_CONFIG_DIR ?? "",
+		timeoutMs: config?.timeoutMs ?? (Number.isFinite(parsed) ? parsed : 3e4)
+	};
+}
+/**
+* Probe the daemon without throwing.
+*
+* Returns the discovery record when the daemon answers, or the reason it
+* could not be reached. A ping failure is reported rather than raised so
+* that a status surface can render "dshbox is not running" without every
+* caller having to catch.
+*/
+async function status(config) {
+	const rpc = getRpc(resolveConfig(config));
+	const path = discoveryPath(rpc.configDir);
+	try {
+		const record = rpc.discovery();
+		await rpc.ping();
+		return {
+			discoveryPath: path,
+			endpoint: record,
+			problem: null
+		};
+	} catch (error) {
+		const problem = error instanceof DshboxUnavailableError ? error.message : "dshbox daemon answered but failed its liveness probe";
+		return {
+			discoveryPath: path,
+			endpoint: null,
+			problem: error instanceof Error ? error.message + " (" + problem + ")" : problem
+		};
+	}
+}
+/**
+* Cross-tool guidance, contributed once as a prompt section.
+*
+* Each tool's description already says what that one tool does. What no single
+* description can carry is the order, and getting the order wrong is what costs an
+* agent the most: reading a page, acting on a control that was never on screen, and
+* treating a blocked click as a broken app.
+*
+* Registered inside a cordis effect so the section is removed when this mount is
+* disposed. A duplicate name throws in the host, which would turn a re-apply into a
+* load failure; scoping the registration to the effect is what makes that impossible.
+*
+* Deliberately short. It earns its place by carrying what no tool response repeats;
+* anything a tool already reports belongs in that tool.
+*/
+const WORKFLOW_PROMPT_SECTION = "dsh-box-sandbox:page-workflow";
+const WORKFLOW_PROMPT_ORDER = 3050;
+function pageWorkflowPrompt() {
+	return [
+		"Debugging a page with the box_* tools:",
+		"Start with box_page_text. It needs no selector and returns every control with its role,",
+		"name and position, so it replaces guessing at selectors.",
+		"Check the in-viewport flag before acting. A control marked below the fold exists; scroll to",
+		"it with box_scroll rather than concluding it is missing.",
+		"Act on what box_page_text returned: pass the role and name back to box_click_element rather",
+		NaN,
+		NaN,
+		"landed, so believe that field, not the fact that you dispatched a click: when landed is",
+		"false something covered the target, and a page that looks unchanged is not a broken app.",
+		"Before typing, click the field. box_type_text reports the focused element and inserts nothing",
+		"when no editable field holds focus.",
+		"If a page tool cannot find a browser, box_set_browser reports which one is in use and pins a",
+		"different one."
+	].join("\n");
+}
+/** Register the plugin against a freshly mounted Cordis context. */
+function apply(ctx, config) {
+	resetRpc();
+	getRpc(resolveConfig(config));
+	applyBoxTools(ctx);
+	registerManageTools(ctx);
+	ctx.effect(() => () => resetRpc(), "dsh-box-sandbox.client()");
+	ctx.effect(() => hostServices(ctx).systemPrompt.section({
+		name: WORKFLOW_PROMPT_SECTION,
+		order: WORKFLOW_PROMPT_ORDER,
+		text: pageWorkflowPrompt
+	}), "dsh-box-sandbox.systemPrompt()");
+}
+//#endregion
+export { DshboxRpc, DshboxUnavailableError, apply, discoveryPath, getRpc, inject, name, resetRpc, status };