@nexus-aethra/dsh-box-sandbox 0.1.9 → 0.2.1-alpha.1

package/dist/index.mjs

@@ -109,7 +109,19 @@ async function waitForTask(id, options = {}) {
 * 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);
+	return followTask(await getRpc().call(method, params), options);
+}
+/**
+* Follow an already-enqueued task record to its end, with runTask's rules.
+*
+* Exists for the methods that only sometimes enqueue: the daemon answers them
+* in line when no task was needed and with a task record when one was, and the
+* caller cannot know which until the reply is in hand. A record without an id
+* is not a task and is handed back untouched — deciding that shape is the
+* caller's, since only it knows what the synchronous answer looks like.
+*/
+async function followTask(enqueued, options = {}) {
+	const { finished, task } = await waitForTask(enqueued.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;
@@ -264,21 +276,24 @@ function applyBoxTools(ctx) {
 					path: { type: "string" },
 					width: { type: "number" },
 					height: { type: "number" },
-					bytes: { type: "number" }
+					bytes: { type: "number" },
+					url: { type: "string" },
+					title: nullable
 				},
 				required: [
 					"containerId",
 					"path",
 					"width",
 					"height",
-					"bytes"
+					"bytes",
+					"url"
 				]
 			},
 			render: (_args, value) => {
 				const record = asRecord(value);
 				return [{
 					type: "text",
-					text: "Screenshot of container " + String(record.containerId) + " (" + String(record.width) + "x" + String(record.height) + ", " + String(record.bytes) + " bytes) saved to " + String(record.path) + "."
+					text: "Screenshot of container " + String(record.containerId) + " (" + String(record.width) + "x" + String(record.height) + ", " + String(record.bytes) + " bytes) saved to " + String(record.path) + ". Page: " + String(record.url) + (record.title ? " — " + String(record.title) : "") + "."
 				}];
 			}
 		},
@@ -292,7 +307,9 @@ function applyBoxTools(ctx) {
 				path,
 				width: result.width,
 				height: result.height,
-				bytes: result.bytes
+				bytes: result.bytes,
+				url: result.url,
+				title: result.title
 			};
 		}
 	});
@@ -440,6 +457,108 @@ function applyBoxTools(ctx) {
 			};
 		}
 	});
+	registerTool(ctx, {
+		name: "box_hover",
+		description: "Park the pointer on a control and report what the hover revealed. Use it when a control exists only while hovered — row actions in this UI are display:none until :hover, so box_page_text does not list them and box_click_element cannot find them: hover the row first, then list or click. Target it the same way as box_click_element (role and name, or x,y when there is no name). The pointer stays where this leaves it until the next move or click, and the reply names what ended up under it, so a hover that landed on something else is visible immediately.",
+		parameters: {
+			type: "object",
+			properties: {
+				containerId: {
+					type: "string",
+					description: "Container whose page to hover."
+				},
+				name: {
+					type: "string",
+					description: "Accessible name of the control to hover, matched exactly, e.g. the row name box_page_text reported."
+				},
+				role: {
+					type: "string",
+					description: "Role to require alongside the name, e.g. row or button."
+				},
+				nth: {
+					type: "number",
+					description: "Zero-based index among controls sharing the name. Omit for the first."
+				},
+				within: {
+					type: "string",
+					description: "Container name to scope the search to, when the same name appears in more than one place."
+				},
+				x: {
+					type: "number",
+					description: "Horizontal viewport coordinate, from the left edge. Use with y instead of name."
+				},
+				y: {
+					type: "number",
+					description: "Vertical viewport coordinate, from the top edge. Use with x instead of name."
+				}
+			},
+			required: ["containerId"]
+		},
+		timeoutMs: WARM_BUDGET_MS,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					containerId: { type: "string" },
+					url: { type: "string" },
+					x: { type: "number" },
+					y: { type: "number" },
+					landed: { type: "boolean" },
+					hitTag: nullable,
+					hitText: nullable,
+					matched: nullable,
+					occludedBy: nullable
+				},
+				required: [
+					"containerId",
+					"url",
+					"x",
+					"y",
+					"landed"
+				]
+			},
+			render: (_args, value) => {
+				const record = asRecord(value);
+				const at = "at (" + String(record.x) + ", " + String(record.y) + ")";
+				if (record.landed === false) {
+					const cover = record.occludedBy ? " it was covered by <" + String(record.occludedBy) + ">" + (record.hitText ? " " + JSON.stringify(record.hitText) : "") : " nothing is under that point";
+					return [{
+						type: "text",
+						text: "The hover " + at + " in container " + String(record.containerId) + " did NOT land:" + cover + "." + nextHint("hover the row or control by name, then call box_page_text to list what appeared")
+					}];
+				}
+				const under = record.hitTag ? " over <" + String(record.hitTag) + ">" : "";
+				return [{
+					type: "text",
+					text: "Pointer parked " + at + " in container " + String(record.containerId) + under + "." + (record.matched ? " Target: " + JSON.stringify(record.matched) + "." : "") + nextHint("call box_page_text again to list what the hover revealed, or box_click_element to act on it")
+				}];
+			}
+		},
+		async execute(args) {
+			const containerId = containerIdOf(args);
+			const record = asRecord(args);
+			const hasName = typeof record.name === "string" && record.name.trim() !== "";
+			const hasPoint = typeof record.x === "number" && typeof record.y === "number";
+			if (!hasName && !hasPoint) throw new Error("give a name (with optional role, nth, within) or both x and y");
+			if (hasName) return {
+				containerId,
+				...await withSession(containerId, "debug_hover", {
+					name: record.name,
+					role: typeof record.role === "string" ? record.role : void 0,
+					nth: typeof record.nth === "number" ? record.nth : void 0,
+					within: typeof record.within === "string" ? record.within : void 0
+				})
+			};
+			return {
+				containerId,
+				...await withSession(containerId, "debug_hover", {
+					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.",
@@ -456,7 +575,7 @@ function applyBoxTools(ctx) {
 				},
 				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."
+					description: "Name of a container to scope the listing to, such as a dialog. Use it when a name is ambiguous: a settings dialog and the chat screen behind it can both offer the same one, and acting on the wrong element still looks like it worked."
 				},
 				limit: {
 					type: "number",
@@ -475,6 +594,8 @@ function applyBoxTools(ctx) {
 					count: { type: "number" },
 					truncated: { type: "boolean" },
 					belowFold: { type: "number" },
+					url: { type: "string" },
+					title: nullable,
 					elements: {
 						type: "array",
 						items: { type: "object" }
@@ -485,6 +606,7 @@ function applyBoxTools(ctx) {
 					"count",
 					"truncated",
 					"belowFold",
+					"url",
 					"elements"
 				]
 			},
@@ -493,7 +615,7 @@ function applyBoxTools(ctx) {
 				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)." : "."));
+				lines.push("Page of container " + String(record.containerId) + " at " + String(record.url) + (record.title ? " — " + String(record.title) : "") + ": " + 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)"));
@@ -761,6 +883,111 @@ function applyBoxTools(ctx) {
 			};
 		}
 	});
+	registerTool(ctx, {
+		name: "box_navigate",
+		description: "Point the debugged page at a URL, or bring it back to the container app. With no url it navigates to the container's own live address — this is the recovery after a container restart: the host binds a fresh port on every start, so a page opened before the restart can never answer again, and every page tool against it fails or hangs. The reply reports where the page actually ended up (the app may redirect), not where it was asked to go.",
+		parameters: {
+			type: "object",
+			properties: {
+				containerId: {
+					type: "string",
+					description: "Container whose page to move."
+				},
+				url: {
+					type: "string",
+					description: "Absolute URL to open. Omit to go back to the container app itself."
+				}
+			},
+			required: ["containerId"]
+		},
+		timeoutMs: WARM_BUDGET_MS,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					containerId: { type: "string" },
+					url: { type: "string" },
+					title: nullable,
+					navigatedTo: { type: "string" }
+				},
+				required: [
+					"containerId",
+					"url",
+					"navigatedTo"
+				]
+			},
+			render: (_args, value) => {
+				const record = asRecord(value);
+				return [{
+					type: "text",
+					text: "Page of container " + String(record.containerId) + " now at " + String(record.url) + (record.title ? " — " + String(record.title) : "") + " (asked for " + String(record.navigatedTo) + ")." + nextHint("call box_page_text to see what the page shows now")
+				}];
+			}
+		},
+		async execute(args) {
+			const containerId = containerIdOf(args);
+			const record = asRecord(args);
+			const result = await withSession(containerId, "debug_navigate", { url: typeof record.url === "string" && record.url.trim() !== "" ? record.url.trim() : void 0 });
+			return {
+				containerId,
+				url: result.url,
+				title: result.title,
+				navigatedTo: result.navigatedTo
+			};
+		}
+	});
+	registerTool(ctx, {
+		name: "box_evaluate",
+		description: "Run one JavaScript expression in the debugged page and return its value. Use it for facts the other tools do not answer for: an attribute, a computed style, whether a selector matches, a value React keeps out of the accessibility tree. Non-string values come back JSON-encoded, so objects and arrays stay readable. The expression runs inside the page with the page's own scope — it can do anything the page's own scripts could, and no more.",
+		parameters: {
+			type: "object",
+			properties: {
+				containerId: {
+					type: "string",
+					description: "Container whose page to evaluate in."
+				},
+				expression: {
+					type: "string",
+					description: "JavaScript to evaluate, e.g. document.title or Boolean(document.querySelector(\".row-actions\"))."
+				}
+			},
+			required: ["containerId", "expression"]
+		},
+		timeoutMs: WARM_BUDGET_MS,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					containerId: { type: "string" },
+					url: { type: "string" },
+					result: { type: "string" }
+				},
+				required: [
+					"containerId",
+					"url",
+					"result"
+				]
+			},
+			render: (_args, value) => {
+				const record = asRecord(value);
+				return [{
+					type: "text",
+					text: "Evaluated in container " + String(record.containerId) + " at " + String(record.url) + ":\n" + String(record.result)
+				}];
+			}
+		},
+		async execute(args) {
+			const containerId = containerIdOf(args);
+			const record = asRecord(args);
+			if (typeof record.expression !== "string" || record.expression.trim() === "") throw new Error("expression is required and must be non-empty");
+			return {
+				containerId,
+				...await withSession(containerId, "debug_evaluate", { expression: record.expression })
+			};
+		}
+	});
 	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.",
@@ -987,14 +1214,29 @@ function registerManageTools(ctx) {
 			plugins: {
 				type: "array",
 				items: { type: "object" }
+			},
+			self: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					role: {
+						type: "string",
+						enum: ["container", "external"]
+					},
+					containerId: { oneOf: [{ type: "string" }, { type: "null" }] }
+				},
+				required: ["role", "containerId"]
 			}
 		}, [
 			"box",
 			"containers",
 			"templates",
-			"plugins"
+			"plugins",
+			"self"
 		], (value) => {
 			const lines = [];
+			const self = value.self ?? {};
+			lines.push(`Self: ${self.role === "container" ? `inside container ${String(self.containerId)} — lifecycle verbs on it are refused` : "external (not inside a Box container)"}.`);
 			const box = value.box ?? {};
 			const containers = value.containers ?? [];
 			const templates = value.templates ?? [];
@@ -1013,7 +1255,8 @@ function registerManageTools(ctx) {
 				box: {},
 				containers: [],
 				templates: [],
-				plugins: []
+				plugins: [],
+				self: selfIdentity()
 			};
 			if (want.includes("box")) result.box = asObject(await rpc.call("get_info"));
 			if (want.includes("containers")) result.containers = asArray(await rpc.call("list_containers"));
@@ -1036,6 +1279,8 @@ function registerManageTools(ctx) {
 					"inject",
 					"rm",
 					"rm-view",
+					"view-on",
+					"view-off",
 					"prune",
 					"types",
 					"views"
@@ -1066,7 +1311,7 @@ function registerManageTools(ctx) {
 				},
 				viewId: {
 					type: "string",
-					description: "Which resource view to remove."
+					description: "Which resource view to act on: the type a Resources tab stands for. Required by rm-view, view-on and view-off."
 				},
 				name: {
 					type: "string",
@@ -1184,8 +1429,20 @@ function registerManageTools(ctx) {
 				case "rm-view": return {
 					action,
 					containerId,
-					result: asObject(await rpc.call("delete_resource_view", { id: required(record, "viewId") }))
+					result: asObject(await rpc.call("delete_resource_view", { viewId: required(record, "viewId") }))
 				};
+				case "view-on":
+				case "view-off": {
+					const enabled = action === "view-on";
+					return {
+						action,
+						containerId,
+						result: asObject(await rpc.call("set_resource_view_enabled", {
+							viewId: required(record, "viewId"),
+							enabled
+						}))
+					};
+				}
 				case "prune": return {
 					action,
 					containerId,
@@ -1220,6 +1477,8 @@ function registerManageTools(ctx) {
 					"inject",
 					"rm",
 					"rm-view",
+					"view-on",
+					"view-off",
 					"prune",
 					"types",
 					"views"
@@ -1363,11 +1622,12 @@ function registerManageTools(ctx) {
 				if (title !== void 0) params.title = title;
 				if (flag(record, "restart")) params.restart = true;
 				const added = await rpc.call("add_container_workspace", params);
+				if (added !== null && typeof added === "object" && typeof added.id === "string" && typeof added.status === "string") await followTask(added, { timeoutMs: 84e4 });
 				return {
 					action,
 					containerId,
 					workspaces: (await rpc.call("list_container_workspaces", { id: containerId })).workspaces ?? [],
-					created: added?.created === true
+					created: added !== null && !("status" in added) && added.created === true
 				};
 			}
 			badAction("workspace", action, ["list", "add"]);
@@ -2178,28 +2438,48 @@ function asObject(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
+* The daemon stamps `DSHBOX_CONTAINER_ID` onto the host process it spawns, so
+* a mounted plugin can name its own container without guessing. The stamp is
+* the authority; the install-path parse below is the fallback for hosts
+* started by older daemons, before the stamp existed — there, nothing hands a
+* plugin its own container id, 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.
+* The fallback matches the segment's prefix, not the id's full shape. An
+* earlier version matched a UUID 8-4-4-4-12 and silently never matched
+* anything: ids are `container-<unix timestamp>...`, and 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) {
+function selfIdentity() {
+	const stamped = process.env.DSHBOX_CONTAINER_ID?.trim();
+	if (stamped) return {
+		role: "container",
+		containerId: stamped
+	};
 	let here;
 	try {
 		here = dirname(fileURLToPath(import.meta.url));
 	} catch {
-		return false;
+		return {
+			role: "external",
+			containerId: null
+		};
 	}
-	return here.split(/[\\/]/).includes(containerId);
+	const own = here.split(/[\\/]/).find((part) => /^container-\d/.test(part));
+	return own ? {
+		role: "container",
+		containerId: own
+	} : {
+		role: "external",
+		containerId: null
+	};
+}
+/** True when this plugin is running inside the container it was asked about. */
+function runsInside(containerId) {
+	return selfIdentity().containerId === containerId;
 }
 /** Read an optional finite number, treating blank and NaN as absent. */
 function number(args, field) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexus-aethra/dsh-box-sandbox",
-  "version": "0.1.9",
+  "version": "0.2.1-alpha.1",
   "description": "Host-side bridge from a DSH session to the DSH Box daemon: typed box_* tools an agent can call without a shell.",
   "keywords": [
     "dsh",
@@ -37,6 +37,7 @@
   },
   "files": [
     "dist/",
+    "skills/",
     "cordis.patch.yml",
     "README.md",
     "LICENSE"

package/skills/dsh-box-tools/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: dsh-box-tools
+description: Use when you need to inspect, start, or change DSH Box containers, templates, plugins or resources from inside a container session — cover box_overview, box_lifecycle, box_create, box_resources, box_plugins, box_templates, box_settings, box_task and the browser page tools.
+---
+
+# Driving DSH Box with the `box_*` tools
+
+You run inside a DSH Box container, and this profile mounts the sandbox plugin
+(`@nexus-aethra/dsh-box-sandbox`) that bridges to the `dshboxd` daemon on the host.
+It registers a typed `box_*` tool surface, so you never have to shell out to `dshbox`
+or parse its stdout. Every tool is one JSON call; every answer is the daemon's own
+result, not a summary.
+
+## Read this first
+
+- **`box_overview` before anything else.** It is the only listing tool: containers,
+  templates, and the plugins the box knows. Acting on an id you guessed is the
+  failure this tool removes.
+- **Check `self` in the same `box_overview` answer.** It says where you sit:
+  `role: container` with the container id you are running in, or `external` when
+  you watch the box from outside (a desktop or web DSH). A `container` agent
+  must not stop, restart, rebuild or remove its own container — `box_lifecycle`
+  refuses, because the call could never report back.
+- **Anything that changes state through a task needs `box_task`.** Call it with
+  `action: 'status'` and the task id the action returned, or `action: 'list'` to
+  find what is already running. A task that has not finished has not happened.
+- **A call that disappears is an outage, not an answer.** When the daemon is down
+  every tool fails with a message naming the discovery record it looked for; that
+  means "the box is not running", not "the thing does not exist".
+
+## The tool surface
+
+| Tool | What it does |
+|---|---|
+| `box_overview` | Containers, templates, plugins, and where you sit (`self`). Start here. |
+| `box_lifecycle` | start / stop / stop-now / restart / rebuild / remove a container |
+| `box_create` | from-template, from-version, describe, url, browse-paths |
+| `box_resources` | list, read, write, extract, inject, rm, rm-view, view-on, view-off, prune, types, views |
+| `box_plugins` | list, installed, container, add, add-extension, copy, remove-plugin, import, export, export-installed, import-workspace, install-bundle, bundle, prune, graph |
+| `box_templates` | list, show, pull, import, export, remove, prune, catalog |
+| `box_settings` | toolchains, installed, catalog, refresh-catalog, data, references, template-info, template-list, save-mirrors, set-runtime-directory, uninstall-dsh |
+| `box_task` | list, status, cancel, delete |
+| `box_workspace` | list, add (restart: true stops the container, adds, starts it again) |
+| `box_build` | build a template from a boxfile; apply a resource document |
+
+## Rules that are easy to get wrong
+
+1. **This container cannot be restarted from inside it.** `box_lifecycle` refuses
+   when the target is the container you are running in — stopping it kills the host
+   that is executing your call, so the result can never come back. Use `box_task`
+   to watch, and let a person or the CLI act on that container.
+2. **`add`, `import` and `pull` are tasks.** They return a task id, not a finished
+   object. `box_task` with `action: 'status'` is how you learn whether it worked;
+   the task's `logPath` is where the daemon writes the step-by-step log.
+3. **Closing a resource type is not deleting it.** `box_resources` with
+   `view-off` hides the type's tab and keeps its row and every copy taken under it;
+   `rm-view` removes the type itself and leaves the copies alone. Choose deliberately.
+4. **Injection refuses rather than overwrites.** `inject` will not replace an
+   existing destination without `overwrite`, and will not touch a running container
+   without `restart`. That refusal is the safety property, not an error to work around.
+5. **Three actions change the whole box and need `confirm: true`.**
+   `save-mirrors`, `set-runtime-directory`, `uninstall-dsh` affect every container
+   and every future session. The tool refuses without the flag.
+
+## Debugging a page (separate tool family)
+
+The same plugin also registers browser tools against a headless Chromium session:
+`box_page_text`, `box_click_element`, `box_click_at`, `box_hover`, `box_type_text`, `box_press_key`,
+`box_scroll`, `box_navigate`, `box_evaluate`, `box_screenshot`, `box_console`, `box_set_viewport`,
+`box_set_browser`, `box_close`.
+
+When using them, always start with the observation tool and act only on what it
+returned. The tool descriptions carry the full workflow; follow them.
+
+## Worked example: take a resource copy and check it landed
+
+1. `box_overview` -> find the container id, e.g. `container-<timestamp>`.
+2. `box_resources` with `action: 'list'` and that `containerId` -> see which kinds
+   exist and where.
+3. `box_resources` with `action: 'extract'`, `kind: 'sessions'` -> returns a task id.
+4. `box_task` with `action: 'status'`, that id -> `succeeded` means the copy exists.
+5. `box_resources` with `action: 'stored'` -> confirm the new copy is listed.
+
+If a step fails, the daemon's message names what it refused and why. Read it; do not
+retry with a different flag to see if that works.