@rubytech/create-maxy-code 0.1.183 → 0.1.185

package/payload/platform/plugins/browser/mcp/dist/lib/cdp-render.js

@@ -0,0 +1,248 @@
+/**
+ * Render a JS-heavy page in the device's existing Chromium and return its DOM.
+ *
+ * The brand's VNC Chromium is launched by platform/scripts/vnc.sh with
+ * `--remote-debugging-port=${CDP_PORT}`, so CDP is already listening on
+ * 127.0.0.1:<port>. This module attaches to that running browser — it never
+ * launches its own — which is why no external browser package ships on device.
+ *
+ * Lifecycle (HTTP for target create/close, WebSocket for page control):
+ *
+ *   PUT /json/new                  create a blank target, get its WS URL
+ *        │
+ *        ▼
+ *   ws://…/devtools/page/<id>      Page.enable → Page.navigate(url)
+ *        │                         await Page.loadEventFired (load-timeout)
+ *        ▼
+ *   Runtime.evaluate               outerHTML + body.innerText (returnByValue)
+ *        │
+ *        ▼
+ *   PUT /json/close/<id>           always, even on the error paths above
+ *
+ * `fetch` and `WebSocket` are injected so the unit tests drive every branch
+ * without a real browser; production passes the Node 22 globals.
+ */
+const DEFAULT_LOAD_TIMEOUT_MS = 30_000;
+const DEFAULT_COMMAND_TIMEOUT_MS = 15_000;
+/** Create a blank target via the CDP HTTP surface. Maps every transport
+ *  failure to a structured outcome rather than throwing. */
+async function createTarget(deps, timeoutMs) {
+    const endpoint = `http://${deps.cdpHost}:${deps.cdpPort}/json/new`;
+    let res;
+    try {
+        res = await deps.fetchImpl(endpoint, { method: "PUT", signal: AbortSignal.timeout(timeoutMs) });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed") || msg.includes("ENOTFOUND")) {
+            return { outcome: "cdp-unreachable", detail: msg };
+        }
+        return { outcome: "error", detail: msg };
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => "<unreadable>");
+        return { outcome: "error", detail: `CDP /json/new returned ${res.status}: ${body.slice(0, 200)}` };
+    }
+    let parsed;
+    try {
+        parsed = (await res.json());
+    }
+    catch (err) {
+        return { outcome: "error", detail: `CDP /json/new response not JSON: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (!parsed.id || !parsed.webSocketDebuggerUrl) {
+        return { outcome: "error", detail: `CDP /json/new missing id/webSocketDebuggerUrl: ${JSON.stringify(parsed).slice(0, 200)}` };
+    }
+    return { target: { id: parsed.id, webSocketDebuggerUrl: parsed.webSocketDebuggerUrl } };
+}
+/** Best-effort target close. Failure is logged, never surfaced as the render
+ *  outcome — the DOM was already captured by the time this runs. */
+async function closeTarget(deps, targetId) {
+    const endpoint = `http://${deps.cdpHost}:${deps.cdpPort}/json/close/${encodeURIComponent(targetId)}`;
+    try {
+        await deps.fetchImpl(endpoint, { method: "PUT", signal: AbortSignal.timeout(5_000) });
+    }
+    catch (err) {
+        deps.log(`[browser-render] target-close-failed id=${targetId} err=${JSON.stringify(err instanceof Error ? err.message : String(err))}`);
+    }
+}
+/** Drives one CDP WebSocket session: correlates command ids to results and
+ *  resolves a named event. Kept inside renderPage's closure scope so the
+ *  socket, pending map, and event waiters share one lifetime. */
+class CdpSession {
+    ws;
+    nextId = 1;
+    pending = new Map();
+    eventWaiters = new Map();
+    closed = false;
+    constructor(ws) {
+        this.ws = ws;
+        ws.addEventListener("message", (ev) => this.onMessage(ev.data));
+        ws.addEventListener("close", () => {
+            this.closed = true;
+            for (const { reject } of this.pending.values())
+                reject(new Error("websocket closed"));
+            this.pending.clear();
+        });
+    }
+    onMessage(data) {
+        if (typeof data !== "string")
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(data);
+        }
+        catch {
+            return;
+        }
+        if (typeof msg.id === "number") {
+            const waiter = this.pending.get(msg.id);
+            if (!waiter)
+                return;
+            this.pending.delete(msg.id);
+            if (msg.error)
+                waiter.reject(new Error(msg.error.message ?? "CDP command error"));
+            else
+                waiter.resolve(msg.result);
+            return;
+        }
+        if (msg.method) {
+            const waiter = this.eventWaiters.get(msg.method);
+            if (waiter) {
+                this.eventWaiters.delete(msg.method);
+                waiter(msg.params);
+            }
+        }
+    }
+    command(method, params, timeoutMs) {
+        if (this.closed)
+            return Promise.reject(new Error("websocket closed"));
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`CDP ${method} timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: (v) => { clearTimeout(timer); resolve(v); },
+                reject: (e) => { clearTimeout(timer); reject(e); },
+            });
+            this.ws.send(JSON.stringify({ id, method, params }));
+        });
+    }
+    waitForEvent(method, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.eventWaiters.delete(method);
+                reject(new Error(`event ${method} not received within ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.eventWaiters.set(method, () => { clearTimeout(timer); resolve(); });
+        });
+    }
+}
+function openSocket(WebSocketImpl, url, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let ws;
+        try {
+            ws = new WebSocketImpl(url);
+        }
+        catch (err) {
+            resolve({ error: err instanceof Error ? err.message : String(err) });
+            return;
+        }
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                ws.close();
+            }
+            catch { /* ignore */ }
+            resolve({ error: `websocket open timed out after ${timeoutMs}ms` });
+        }, timeoutMs);
+        ws.addEventListener("open", () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ ws });
+        });
+        ws.addEventListener("error", (ev) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const detail = ev && typeof ev === "object" && "message" in ev ? String(ev.message) : "websocket error";
+            resolve({ error: detail });
+        });
+    });
+}
+/** Render `url` in the device Chromium and return its rendered DOM text.
+ *  Always returns a structured RenderResult — never throws, never returns a
+ *  silent empty page. */
+export async function renderPage(url, opts, deps) {
+    const loadTimeoutMs = opts.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS;
+    const commandTimeoutMs = opts.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+    const fail = (outcome, detail) => {
+        deps.log(`[browser-render] url=${url} rendered=false outcome=${outcome} detail=${JSON.stringify(detail)}`);
+        return { url, rendered: false, outcome, domBytes: 0, text: "", html: "", detail };
+    };
+    if (!deps.WebSocketImpl) {
+        return fail("websocket-unavailable", "global WebSocket is not available on this runtime (Node < 22.4)");
+    }
+    if (!deps.cdpPort || Number.isNaN(deps.cdpPort)) {
+        return fail("cdp-unreachable", `CDP_PORT not set or invalid (got ${JSON.stringify(deps.cdpPort)})`);
+    }
+    const created = await createTarget(deps, commandTimeoutMs);
+    if ("outcome" in created)
+        return fail(created.outcome, created.detail);
+    const target = created.target;
+    const opened = await openSocket(deps.WebSocketImpl, target.webSocketDebuggerUrl, commandTimeoutMs);
+    if ("error" in opened) {
+        await closeTarget(deps, target.id);
+        return fail("cdp-unreachable", `websocket connect failed: ${opened.error}`);
+    }
+    const session = new CdpSession(opened.ws);
+    try {
+        await session.command("Page.enable", {}, commandTimeoutMs);
+        const loadPromise = session.waitForEvent("Page.loadEventFired", loadTimeoutMs);
+        try {
+            await session.command("Page.navigate", { url }, commandTimeoutMs);
+        }
+        catch (err) {
+            await closeTarget(deps, target.id);
+            return fail("navigate-failed", err instanceof Error ? err.message : String(err));
+        }
+        try {
+            await loadPromise;
+        }
+        catch (err) {
+            await closeTarget(deps, target.id);
+            return fail("load-timeout", err instanceof Error ? err.message : String(err));
+        }
+        let html = "";
+        let text = "";
+        try {
+            const htmlRes = (await session.command("Runtime.evaluate", { expression: "document.documentElement.outerHTML", returnByValue: true }, commandTimeoutMs));
+            html = typeof htmlRes?.result?.value === "string" ? htmlRes.result.value : "";
+            const textRes = (await session.command("Runtime.evaluate", { expression: "document.body && document.body.innerText || ''", returnByValue: true }, commandTimeoutMs));
+            text = typeof textRes?.result?.value === "string" ? textRes.result.value : "";
+        }
+        catch (err) {
+            await closeTarget(deps, target.id);
+            return fail("evaluate-failed", err instanceof Error ? err.message : String(err));
+        }
+        const domBytes = Buffer.byteLength(html, "utf8");
+        deps.log(`[browser-render] url=${url} rendered=true domBytes=${domBytes}`);
+        await closeTarget(deps, target.id);
+        return { url, rendered: true, outcome: "ok", domBytes, text, html };
+    }
+    finally {
+        try {
+            opened.ws.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+//# sourceMappingURL=cdp-render.js.map

package/payload/platform/plugins/browser/mcp/dist/lib/cdp-render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp-render.js","sourceRoot":"","sources":["../../src/lib/cdp-render.ts"],"names":[],"mappings":"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"}

package/payload/platform/plugins/browser/mcp/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@maxy/browser",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/payload/platform/plugins/docs/references/internals.md

@@ -451,7 +451,7 @@ For subagents, the same spawn pushes `--add-dir` for every bundled plugin agents
 
 A boot gate refuses to start the manager when any admin-allowlisted tool `mcp__<plugin>__*` lacks a registered server. The signal is `boot-failed reason=mcp-allowlist-without-server plugin=<p> tool=<t>` followed by `process.exit(1)`. The remediation is a one-line edit to the named `PLUGIN.md`: add the `mcp:` block. The complementary observability emit `mcp-config-allowlist-coverage admin-tools=A admin-registered=R` (where `A === R`) confirms the invariant per boot.
 
-A second boot gate walks every specialist `.md` under `platform/templates/specialists/agents/`, every bundled `<plugin>/agents/` directory, and the per-account `<accountDir>/specialists/agents/` directory, parses each file's `tools:` frontmatter line, and classifies every tool name as one of: CC-native (Read, Bash, …), bridge-namespace (`mcp__plugin_playwright_*`, `mcp__graph__*`), a tool the loaded `PLUGIN.md` set actually serves, `unknown-tool-in-plugin` (namespace served but tool name absent), `unknown-plugin-namespace` (namespace served by nothing), `brand-excluded-plugin` (namespace served by nothing on this brand, **but** the brand's `brand.json#plugins.excluded` list names it), or `malformed-name` (not CC-native and not `mcp__<plugin>__<tool>`-shaped). The first three pass. The next two refuse boot with one `boot-failed reason=specialist-tool-drift specialist=<name> tool=<t> drift=<class> path=<…>` line per defect, then `process.exit(1)`. `brand-excluded-plugin` is a structural pass: it lands in a per-specialist strip-list, the manager continues to boot, and at spawn time `pty-spawner` removes those tool names from the `--agent <name>` spawn's `--allowed-tools` argv. The complementary observability emit `specialist-tool-strip specialist=<name> plugin=<p> tools=<csv> reason=brand-excluded` fires one line per stripped (specialist, plugin) pair so an operator who reads `server.log` sees the brand filter doing work without cross-referencing `brand.json` against the template. The startup-self-test line `startup-self-test specialist-tool-drift=ok inspected=<N> stripped-specialists=<M>` confirms the gate ran and how many specialists carry strip-lists.
+A second boot gate walks every specialist `.md` under `platform/templates/specialists/agents/`, every bundled `<plugin>/agents/` directory, and the per-account `<accountDir>/specialists/agents/` directory, parses each file's `tools:` frontmatter line, and classifies every tool name as one of: CC-native (Read, Bash, …), bridge-namespace (`mcp__plugin_*`, `mcp__graph__*`), a tool the loaded `PLUGIN.md` set actually serves, `unknown-tool-in-plugin` (namespace served but tool name absent), `unknown-plugin-namespace` (namespace served by nothing), `brand-excluded-plugin` (namespace served by nothing on this brand, **but** the brand's `brand.json#plugins.excluded` list names it), or `malformed-name` (not CC-native and not `mcp__<plugin>__<tool>`-shaped). The first three pass. The next two refuse boot with one `boot-failed reason=specialist-tool-drift specialist=<name> tool=<t> drift=<class> path=<…>` line per defect, then `process.exit(1)`. `brand-excluded-plugin` is a structural pass: it lands in a per-specialist strip-list, the manager continues to boot, and at spawn time `pty-spawner` removes those tool names from the `--agent <name>` spawn's `--allowed-tools` argv. The complementary observability emit `specialist-tool-strip specialist=<name> plugin=<p> tools=<csv> reason=brand-excluded` fires one line per stripped (specialist, plugin) pair so an operator who reads `server.log` sees the brand filter doing work without cross-referencing `brand.json` against the template. The startup-self-test line `startup-self-test specialist-tool-drift=ok inspected=<N> stripped-specialists=<M>` confirms the gate ran and how many specialists carry strip-lists.
 
 This gate was Task 173. The `brand-excluded` branch closes the recurring crash-restart loop on brands that ship without a plugin the shared `personal-assistant.md` template references (e.g. `realagent-code` excludes `telegram` while the template hard-codes `mcp__telegram__*`). The brand-agnostic template stays a single file; the brand-aware filter expresses what the specialist *may* do on this install while the template expresses what it *can* do across brands. Tool typos and renamed plugins still refuse to boot — only namespaces explicitly named in `plugins.excluded` are demoted to strip-and-warn.
 

package/payload/platform/plugins/docs/references/plugins-guide.md

@@ -16,6 +16,7 @@ These are part of {{productName}}'s foundation and cannot be disabled:
 |--------|-------------|
 | `admin` | Platform management — system status, account settings, logs, session control. Also hosts the cross-cutting `plainly` skill: every text-producing agent (admin, public, every specialist) applies a plain-English precision pass to prose returned to humans, as a prime-directive prerogative. Agent-to-machine payloads (image-generate prompts, memory-write arguments, cypher) pass through verbatim. Enforced mechanically by `.claude/hooks/precision-check.sh`. |
 | `memory` | Graph memory — search, write, reindex, and ingest knowledge |
+| `browser` | Headless browser rendering — `browser-render` runs a JavaScript-heavy page in the device's Chromium and returns its rendered DOM. The JS-rendering leg of retrieval: WebFetch (summary) / `url-get` (verbatim, server-rendered) / `browser-render` (JS-rendered). |
 | `maxy-guide` | User guide and platform documentation (this plugin) |
 | `cloudflare` | Cloudflare Tunnel — remote access via your custom domain |
 | `scheduling` | Calendar and scheduling — events, appointments, recurring triggers. Any activity involving time (date, timestamp, day of week, month, duration) routes through `time-resolve` first. Two read-only tools (`current-datetime`, `time-resolve`) are always available to every public agent regardless of enabled plugins. |
@@ -23,6 +24,8 @@ These are part of {{productName}}'s foundation and cannot be disabled:
 | `tasks` | Task lifecycle — create, update, list, relate, complete |
 | `workflows` | Persistent named workflows — reusable instruction sets |
 | `contacts` | CRM contact management — create, lookup, update, list |
+| `prompt-optimiser` | Prompt optimiser — turns a rough draft or task description into a single finished, copy-pasteable prompt tuned for Opus 4.7 adaptive thinking in the chat app (claude.ai, Mac, iOS) |
+| `url-get` | Faithful page retrieval — fetches a server-rendered page, writes a verbatim markdown copy to an account-scoped reference file (no model in the path, so no copyright refusal), and returns a transformative summary plus the file path. Use instead of WebFetch when a faithful copy is needed (e.g. ingesting your own published writing). |
 
 ### {{productName}} Plugins (user-selectable)
 

package/payload/platform/plugins/docs/references/troubleshooting.md

@@ -8,13 +8,13 @@
 
 **Diagnose if it ever recurs:** run `bash platform/scripts/__tests__/first-token-creates-stream-log.test.sh` from the install. Pass = invariant holds; any other exit = the writer-side existence contract is broken and one `[log-tee] missing-on-resolve sessionKey=<8> surface=<…>` line on `server.log` is the operator-visible signal (P0). For the duplicate-file class specifically (the 2026-05-14 recurrence trigger), `bash platform/scripts/log-adherence-check.sh` returns non-zero whenever any sessionKey has more than one `claude-agent-stream-<sk>.log` across account dirs.
 
-## Browser navigation to a local file (`file://`) used to time out for two minutes
+## A JavaScript-rendered page comes back empty from WebFetch or `url-get`
 
-**Symptom:** Older versions of the platform's admin agent would attempt `browser_navigate file:///path/to.html`, hit Playwright's silent two-minute timeout, then guess fixed ports (8080 / 3000 / 8000 / 9000) and report `ERR_CONNECTION_REFUSED` for each before someone manually started a local HTTP server.
+**Symptom:** A page that needs JavaScript to show its content returns empty or a shell document from `WebFetch` (summary) or `url-get` (verbatim, server-rendered).
 
-**Resolution shipped:** The `playwright-file-guard` PreToolUse hook (admin plugin) intercepts `file://` URLs, picks a free loopback port, backgrounds `python3 -m http.server` rooted at the file's parent directory, connect-verifies the server within one second, and rewrites the tool call's URL to `http://127.0.0.1:<port>/<basename>` before Playwright sees it. The agent never sees the rewrite. Stale server processes are reaped opportunistically on every hook invocation (1 h threshold, gated by a `ps` cmdline check that won't kill a reused PID).
+**Resolution:** Use the `browser` core plugin's `browser-render` tool. It renders the page in the device's per-brand Chromium over the Chrome DevTools Protocol (the same browser the VNC viewer shows) and returns the rendered HTML plus visible text. It attaches to the already-running Chromium on `127.0.0.1:${CDP_PORT}` — nothing is downloaded or installed mid-session.
 
-**Diagnose if it ever recurs:** grep the per-conversation stream log for `[playwright-file-guard] action=`. One `action=rewrite original=file://… port=<n> pid=<m>` line per file:// navigate is the healthy signal. `action=fail reason=<r>` indicates the hook tried to rewrite but failed open (Playwright handled the original URL); the reason field names the cause (`python3-missing`, `port-pick-failed`, `server-not-ready`, `file-not-found`, `spawn-failed`). The `cleanup` argv on the hook script can be invoked manually to sweep `/tmp/playwright-file-guard.*.pid`; the suite at `platform/plugins/admin/hooks/__tests__/playwright-file-guard.test.sh` exercises every path.
+**Diagnose if it ever recurs:** grep the per-conversation stream log for `[browser-render]`. `rendered=true domBytes=<n>` is the healthy signal. `rendered=false outcome=cdp-unreachable` means no Chromium is listening on the brand's CDP port — confirm with `curl 127.0.0.1:<cdpPort>/json/version`. Other outcomes (`navigate-failed`, `load-timeout`, `evaluate-failed`) name the failed CDP step.
 
 ## First user-domain write rejected by `[graph-write-gate] reject reason=no-admin-user`
 

package/payload/platform/plugins/memory/PLUGIN.md

@@ -144,6 +144,7 @@ mcp:
     ACCOUNT_ID: ${ACCOUNT_ID}
     SESSION_ID: ${SESSION_ID}
     AGENT_SLUG: ${AGENT_SLUG}
+    AGENT_SLUG_SCOPE: ${AGENT_SLUG_SCOPE}
 mcp-manifest: auto
 ---
 

package/payload/platform/plugins/memory/mcp/dist/index.js

@@ -67,11 +67,12 @@ const readOnly = process.env.READ_ONLY === "true";
 // Module-init must never throw; plugin-system spawn enumerates tools/list
 // before ACCOUNT_ID is set. Per-call refusal preserves account isolation.
 const accountId = process.env.ACCOUNT_ID ?? null;
-// Task 476 — extended boot signal: sessionId and agentSlug land here too
-// so a stale spawn-env contract is visible at the first byte of stderr.
-// `sessionId === accountId`, or `agentSlug` empty on a specialist spawn,
-// are the two regression shapes.
-process.stderr.write(`[memory] boot accountId=${accountId ?? "null"} sessionId=${process.env.SESSION_ID || "-"} agentSlug=${process.env.AGENT_SLUG || "-"}\n`);
+// Task 476/487 — extended boot signal: sessionId, agentSlug (provenance),
+// and agentScope (read-scope) land here so a stale spawn-env contract is
+// visible at the first byte of stderr. Regression shapes: `sessionId ===
+// accountId`; `agentSlug` empty on a specialist spawn (provenance lost);
+// `agentScope` non-empty on the admin operator spawn (search wrongly scoped).
+process.stderr.write(`[memory] boot accountId=${accountId ?? "null"} sessionId=${process.env.SESSION_ID || "-"} agentSlug=${process.env.AGENT_SLUG || "-"} agentScope=${process.env.AGENT_SLUG_SCOPE || "-"}\n`);
 function refuseNoAccount(toolName) {
     process.stderr.write(`[memory] tool=${toolName} refuse reason=no-account-context\n`);
     return {
@@ -165,10 +166,17 @@ function resolveSessionId(override) {
     const fromEnv = process.env.SESSION_ID;
     return fromEnv && fromEnv.trim() ? fromEnv.trim() : undefined;
 }
-// Per-agent knowledge scoping: when set, memory-search only returns nodes whose
-// `agents` array contains this slug. For public agents, set via env var (server-level
-// enforcement). For admin queries, passed as an optional tool param.
+// Provenance stamp: AGENT_SLUG is the agent identity recorded as
+// `createdByAgent` on every write. The admin operator gets the 'admin'
+// sentinel (Task 487); specialists/public get their slug.
 const envAgentSlug = process.env.AGENT_SLUG || undefined;
+// Per-agent knowledge scoping (Task 487 split this off AGENT_SLUG): when set,
+// memory-search only returns nodes whose `agents` array contains this slug.
+// Specialists/public get their slug here (server-level enforcement); the admin
+// operator gets EMPTY so search stays wide-open. For admin, an optional tool
+// param can still scope a single query. Read-scope and provenance are now
+// independent — admin writes stamp 'admin' while admin reads stay unscoped.
+const envAgentScopeSlug = process.env.AGENT_SLUG_SCOPE || undefined;
 // Keyword subscriptions: comma-separated list of keywords for BM25-based reactive
 // knowledge inclusion. When set, memory-search runs a BM25 query per keyword and
 // unions results with directly-tagged nodes. Capped at 5 for Pi performance.
@@ -239,8 +247,10 @@ eagerTool(server, "memory-search", "Search the knowledge graph using semantic ve
 }, async ({ query, labels, limit, expandHops, keywords, keywordMatch, agentSlug: toolAgentSlug, fields, retrievalClass }) => {
     if (!accountId)
         return refuseNoAccount("memory-search");
-    // Env var takes precedence over tool param (security: public agent server-level enforcement)
-    const effectiveAgentSlug = envAgentSlug ?? toolAgentSlug;
+    // AGENT_SLUG_SCOPE takes precedence over the tool param (security: public
+    // agent server-level enforcement). Empty for the admin operator, so admin
+    // falls through to the optional tool param (default: unscoped).
+    const effectiveAgentSlug = envAgentScopeSlug ?? toolAgentSlug;
     try {
         const results = await memorySearch({
             query,