mc8yp 2.6.0 → 2.6.2

package/README.md

@@ -276,11 +276,13 @@ There is deliberately no raw-request escape hatch — the typed namespaces are t
 
 Operations can be hidden from derivation and discovery by annotating them in the OpenAPI spec with the vendor extension `x-mc8yp-exclude: true` — with no escape hatch, exclusion is absolute for the sandbox.
 
-### Sandbox surface (`sandbox`) — microservice mode only
+### Sandbox surface (`sandbox`) — microservice mode only, opt-in
 
-> **Experimental.** Available in deployed microservice mode; not exposed in the local CLI (agent harnesses there bring their own file I/O).
+> **Experimental.** Available in deployed microservice mode only, and **disabled by default**; not exposed in the local CLI (agent harnesses there bring their own file I/O).
 
-In microservice mode, codemode has one more global — `sandbox` — an in-memory shell with a virtual filesystem for wrangling data you fetched from the API (`jq`, `awk`, `sed`, `grep`, `sort`, `uniq`, `cut`, `sqlite3`, …). It has **no network access and no host filesystem access** — it never reaches Cumulocity. Fetch with `c8y`/service namespaces, process in the sandbox, read the result back.
+In microservice mode, codemode has one more optional global — `sandbox` — an in-memory shell with a virtual filesystem for wrangling data you fetched from the API (`jq`, `awk`, `sed`, `grep`, `sort`, `uniq`, `cut`, `sqlite3`, …). It has **no network access and no host filesystem access** — it never reaches Cumulocity. Fetch with `c8y`/service namespaces, process in the sandbox, read the result back.
+
+**It is off unless you turn it on.** Enable it per connection with the `mc8yp-enable-sandbox` header or the `enableSandbox` query param (any of empty, `*`, or `true`). Without it, `sandbox` is absent — same as CLI mode.
 
 ```js
 async () => {

package/dist/cli.mjs

@@ -1546,7 +1546,7 @@ const consola = createConsola();
 //#endregion
 //#region package.json
 var name = "mc8yp";
-var version = "2.6.0";
+var version = "2.6.2";
 var description$1 = "Cumulocity IoT MCP Server - Model Context Protocol integration for IoT device management";
 //#endregion
 //#region \0virtual:core-openapi
@@ -58667,7 +58667,7 @@ function createCodeModeGuidePrompt() {
 		const namespaceNames = resolvedSpecs ? buildNamespaces(resolvedSpecs, restrictions, allowRules).map((ns) => ns.name) : ["c8y"];
 		const policyLines = [...restrictions.map((rule) => `- deny: \`${rule.source}\``), ...allowRules.map((rule) => `- allow: \`${rule.source}\``)];
 		const restrictionSection = policyLines.length > 0 ? `\n## Current Connection Access Policy\n${policyLines.join("\n")}\n\nOperations blocked by these rules are omitted from discovery (search/describe) entirely, and any live request that matches a deny rule (or misses the allow list) fails before reaching the tenant.\n` : "";
-		const sandboxSection = c8yMcpServer.ctx.custom?.env === "server" ? `\n## Sandbox (scratch compute)
+		const sandboxSection = c8yMcpServer.ctx.custom?.env === "server" && c8yMcpServer.ctx.custom?.enableSandbox ? `\n## Sandbox (scratch compute)
 
 \`sandbox\` is your workspace: a persistent in-memory filesystem + Unix shell, separate from the API. It is where you keep files and process data. When the user asks to save or write a file, write it here (\`sandbox.writeFile\`) — never dump a file into the chat instead. Use the shell for text/data processing that is awkward in plain JS — \`jq\`, \`awk\`, \`sed\`, \`grep\`, \`sort\`, \`uniq\`, \`cut\`, \`sqlite3\`, etc. via \`sandbox.exec\`. It has NO network access and NO host filesystem access; it never reaches Cumulocity. Fetch data with \`c8y\`/namespaces, write it into the sandbox, process it, read the result back.
 
@@ -77814,7 +77814,7 @@ function armIdleTimer(sessionId) {
 	const session = sessions.get(sessionId);
 	if (!session) return;
 	if (session.timer) clearTimeout(session.timer);
-	session.timer = setTimeout(() => evictSandboxSession(sessionId), IDLE_TTL_MS);
+	session.timer = setTimeout(() => evictSandboxSession(sessionId, "idle-timeout"), IDLE_TTL_MS);
 	session.timer.unref?.();
 }
 function getSessionAdapter(sessionId) {
@@ -77833,22 +77833,24 @@ function resetSessionAdapter(sessionId) {
 	armIdleTimer(sessionId);
 }
 /**
-* Drop a session's sandbox and its timer. Exported for a future clean-close
-* (DELETE) hook and used by the process-exit teardown.
+* Drop a session's sandbox and its timer. Called by the clean-close (DELETE)
+* hook, the idle timer, and the process-exit teardown.
 * @param sessionId - MCP session id.
+* @param reason - Why the sandbox is being dropped; included in the eviction log line.
 */
-function evictSandboxSession(sessionId) {
+function evictSandboxSession(sessionId, reason) {
 	const session = sessions.get(sessionId);
 	if (!session) return;
 	if (session.timer) clearTimeout(session.timer);
 	session.adapter.dispose?.();
 	sessions.delete(sessionId);
+	consola.info(`[sandbox] evicted workspace for session ${sessionId} (reason: ${reason})`);
 }
 /**
 * Evict every session (process exit, test cleanup).
 */
 function disposeAllSandboxSessions() {
-	for (const sessionId of [...sessions.keys()]) evictSandboxSession(sessionId);
+	for (const sessionId of [...sessions.keys()]) evictSandboxSession(sessionId, "shutdown");
 }
 /**
 * Build the `sandbox` host-module leaf for one codemode run: the full Flue
@@ -135160,7 +135162,7 @@ async function execute(functionCode) {
 		live = createUnauthenticatedCalls(error instanceof Error ? error.message : String(error));
 	}
 	const sessionId = c8yMcpServer.ctx.sessionId;
-	const sandboxApi = c8yMcpServer.ctx.custom?.env === "server" && sessionId ? buildSandboxApi(sessionId) : void 0;
+	const sandboxApi = c8yMcpServer.ctx.custom?.env === "server" && sessionId && c8yMcpServer.ctx.custom?.enableSandbox ? buildSandboxApi(sessionId) : void 0;
 	const result = await (await getSandbox()).run({
 		code: ENTRY_SOURCE,
 		filename: EXECUTE_ENTRY_PATH,
@@ -135185,16 +135187,19 @@ function getSafetyPreface(env) {
 	].join("\n");
 }
 /**
-* Purpose framing for the `sandbox` workspace. Server-only: deployed sessions
-* always have it, so the always-read tool description can state it plainly. CLI
-* has no sandbox. This is deliberately about PURPOSE (files/data processing
-* live here), not procedure — the observed failure was the agent not realizing
-* the sandbox is where files go and dumping output to chat.
+* Purpose framing for the `sandbox` workspace. Server-only, and disabled by
+* default — a connection must opt in (`mc8yp-enable-sandbox` header /
+* `enableSandbox` query param) before the `sandbox` global exists, so this
+* always-read tool description cannot assert it is present the way it can
+* for `codemode`/`docs`. CLI never has a sandbox regardless. This is
+* deliberately about PURPOSE (files/data processing live here), not
+* procedure — the observed failure was the agent not realizing the sandbox
+* is where files go and dumping output to chat.
 * @param env - execution environment.
 */
 function getSandboxNote(env) {
 	if (env !== "server") return "";
-	return "\nYour workspace — `sandbox`: this session has a persistent in-memory filesystem + Unix shell, separate from the API. It is where you keep files and process data. When the user asks to save or write a file, or when you need to filter/transform/aggregate fetched data (jq, awk, grep, sort, sqlite), do it here — `sandbox.writeFile(path, text)`, `sandbox.readFile(path)`, `sandbox.exec(command)` — never dump a file into the chat instead. Files persist across codemode calls in this session. Full method list: `codemode.describe(\"sandbox\")`.\n";
+	return "\nYour workspace — `sandbox`: if this connection has it enabled (check `typeof sandbox !== 'undefined'`), it is a persistent in-memory filesystem + Unix shell, separate from the API, for keeping files and processing data. When the user asks to save or write a file, or when you need to filter/transform/aggregate fetched data (jq, awk, grep, sort, sqlite), do it here — `sandbox.writeFile(path, text)`, `sandbox.readFile(path)`, `sandbox.exec(command)` — never dump a file into the chat instead. Files persist across codemode calls in this session. Full method list: `codemode.describe(\"sandbox\")`.\n";
 }
 function createCodemodeTool(env) {
 	return defineTool({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mc8yp",
-  "version": "2.6.0",
+  "version": "2.6.2",
   "type": "module",
   "description": "Cumulocity IoT MCP Server - Model Context Protocol integration for IoT device management",
   "keywords": [