pilotswarm-sdk 0.5.37 → 0.5.39

package/dist/session-proxy.js

@@ -28,6 +28,140 @@ import { createHash, randomUUID } from "node:crypto";
 import { attemptStoreRecovery, runTurnCommit, runTurnPreamble } from "./session-lifecycle.js";
 import { supportsVersionedSnapshots, writeTurnSentinel } from "./snapshot-protocol.js";
 const SYSTEM_AGENT_IDS = new Set(["pilotswarm", "sweeper", "resourcemgr", "facts-manager"]);
+/**
+ * THE agent-name resolver: FQN parsing, fuzzy matching, package privacy, and
+ * owner shadowing in one place.
+ *
+ * This used to exist twice — the resolveAgentConfig activity had the full
+ * rule set while the control bridge's inline copy had none of it, so
+ * `spawn_agent`/`create_agent_session` could bind another user's private
+ * agent, could not address `__shared:<name>`, and ignored the caller's own
+ * shadowing copy. A security rule with two implementations has one that is
+ * wrong; this is now the only one.
+ *
+ * `getCallerOwnerKey` is awaited lazily — only when a user-scope package
+ * agent is actually in play — and must resolve to the caller's owner key
+ * (`provider\u0001subject`) or null. Fail closed: null means no private
+ * agents match.
+ */
+export async function resolveAgentDefinitionForCaller(opts) {
+    const agents = [
+        ...(opts.userAgents ?? []).map(a => ({ ...a, system: false, creatable: true })),
+        ...(opts.systemAgents ?? []).map(a => ({ ...a, creatable: false })),
+    ];
+    const normalize = (value) => (value || "").toLowerCase().replace(/[^a-z0-9]+/g, "");
+    // Parse the reference. `a:b` has meant `namespace:agent` since long
+    // before FQNs existed, so the parser reports that shape as AMBIGUOUS
+    // and we keep the namespace reading first — an existing binding must
+    // not change meaning because per-user namespaces shipped.
+    const fqn = parseAgentFqn(opts.agentName);
+    let lookupNamespace;
+    let rawName = opts.agentName;
+    /** `__shared:` explicitly asks past the caller's own copy. */
+    let sharedOnly = false;
+    if (fqn.kind === "shared") {
+        rawName = fqn.name;
+        sharedOnly = true;
+    }
+    else if (fqn.kind === "bare") {
+        rawName = fqn.name;
+    }
+    else if (fqn.kind === "ambiguous" || fqn.kind === "owner") {
+        rawName = fqn.name;
+        lookupNamespace = fqn.namespaceRef ?? fqn.ownerRef;
+    }
+    else {
+        // Invalid (reserved prefix, bad semver, malformed). Fall back to
+        // the raw string so a legitimately odd agent name still resolves
+        // the way it always did; a reserved name simply will not match.
+        rawName = opts.agentName;
+    }
+    const lookup = normalize(rawName);
+    // Also try without trailing "agent" suffix for fuzzy matching
+    // (LLM often says "Sweeper agent" which normalizes to "sweeperagent", but id is "sweeper")
+    const lookupBase = lookup.replace(/agent$/, "");
+    let callerKeyResolved = false;
+    let callerKey = null;
+    const callerOwnerKeyOnce = async () => {
+        if (!callerKeyResolved) {
+            callerKeyResolved = true;
+            try {
+                callerKey = await opts.getCallerOwnerKey();
+            }
+            catch {
+                // Fail closed: an unresolvable caller gets no private agents.
+                callerKey = null;
+            }
+        }
+        return callerKey;
+    };
+    const ownerKeyOf = (owner) => owner?.provider && owner?.subject ? `${owner.provider}\u0001${owner.subject}` : null;
+    const visibleToCaller = async (agent) => {
+        const agentOwnerKey = ownerKeyOf(agent?.packageOwner);
+        if (agent?.packageScope !== "user" || !agentOwnerKey)
+            return true;
+        const key = await callerOwnerKeyOnce();
+        return key !== null && key === agentOwnerKey;
+    };
+    const candidatesFor = (a) => [a.name, a.id, a.title].map(normalize).filter(Boolean);
+    const nameMatches = (a) => {
+        const candidates = candidatesFor(a);
+        return candidates.includes(lookup) || (lookupBase && candidates.includes(lookupBase));
+    };
+    let matches = agents.filter(a => {
+        if (lookupNamespace && normalize(a.namespace) !== normalize(lookupNamespace))
+            return false;
+        return nameMatches(a);
+    });
+    // An ambiguous `a:b` that matched nothing as `namespace:agent` gets its
+    // second reading — `owner:package` — rather than just failing. Order,
+    // not guesswork: the old meaning always wins when it resolves.
+    if (matches.length === 0 && fqn.kind === "ambiguous") {
+        matches = agents.filter(nameMatches);
+    }
+    if (sharedOnly) {
+        // `__shared:x` means the deployment's copy, explicitly. This is the
+        // one thing bare-name precedence otherwise takes away: without it,
+        // a user with their own copy could never reach the shared one.
+        matches = matches.filter(a => a.packageScope !== "user");
+    }
+    else {
+        // SHADOWING, at the agent level: the caller's own copy comes first,
+        // then everything public. Same rule the registry resolver applies,
+        // so "run X" and "show me X" cannot disagree about which X.
+        const key = matches.some(a => a.packageScope === "user") ? await callerOwnerKeyOnce() : null;
+        matches = [
+            ...matches.filter(a => a.packageScope === "user" && ownerKeyOf(a.packageOwner) === key && key !== null),
+            ...matches.filter(a => !(a.packageScope === "user" && ownerKeyOf(a.packageOwner) === key && key !== null)),
+        ];
+    }
+    let agent = undefined;
+    for (const candidate of matches) {
+        if (await visibleToCaller(candidate)) {
+            agent = candidate;
+            break;
+        }
+    }
+    if (!agent)
+        return null;
+    return {
+        name: agent.name,
+        prompt: agent.prompt,
+        tools: agent.tools ?? undefined,
+        initialPrompt: agent.initialPrompt ?? undefined,
+        title: agent.title ?? undefined,
+        system: agent.system ?? undefined,
+        id: agent.id ?? undefined,
+        parent: agent.parent ?? undefined,
+        splash: agent.splash ?? undefined,
+        splashMobile: agent.splashMobile ?? undefined,
+        namespace: agent.namespace ?? undefined,
+        promptLayerKind: agent.promptLayerKind ?? undefined,
+        creatable: agent.creatable ?? !agent.system,
+        packageId: agent.packageId ?? undefined,
+        packageScope: agent.packageScope ?? undefined,
+    };
+}
 /**
  * The session canvas: one reserved artifact per ROOT session, drawn by the
  * agent with draw_canvas and rendered live in the portal. The revision is
@@ -35,6 +169,24 @@ const SYSTEM_AGENT_IDS = new Set(["pilotswarm", "sweeper", "resourcemgr", "facts
  * column — see docs/proposals/session-canvas.md.
  */
 export const CANVAS_ARTIFACT_FILENAME = "canvas.html";
+/** Slot 1 keeps the historical name; 2-5 are canvas2.html .. canvas5.html. */
+export function canvasArtifactFilename(slot) {
+    return slot <= 1 ? CANVAS_ARTIFACT_FILENAME : `canvas${slot}.html`;
+}
+/** 1-5, defaulting absent to 1. Returns null for anything else. */
+function normalizeCanvasSlot(value) {
+    if (value === undefined || value === null || value === "")
+        return 1;
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1 || n > 5)
+        return null;
+    return n;
+}
+/** Event rows predate slots; a missing slot means slot 1. */
+function eventSlot(row) {
+    const n = Number(row?.data?.slot);
+    return Number.isInteger(n) && n >= 1 && n <= 5 ? n : 1;
+}
 /**
  * The current canvas revision, from the durable event log — the single
  * authority. Reads a small window rather than exactly one row and takes the
@@ -45,14 +197,20 @@ export const CANVAS_ARTIFACT_FILENAME = "canvas.html";
 // Latest canvas draw's full data (rev + armed contract) — same bounded event
 // query as latestCanvasRev; used by read_canvas(manifestOnly) so an inheriting
 // agent learns what the browser is currently enforcing.
-async function latestCanvasEventData(catalog, sessionId) {
+async function latestCanvasEventData(catalog, sessionId, slot = 1) {
     // No empty-coerce on failure: a transient read error that reads as "no
     // canvas" would mint rev 1 over a live rev-12 canvas (clients' monotonic
     // guards then discard the draw while the tool reports success). Callers
     // route the throw to a structured { error }.
-    const rows = await catalog.getSessionEventsBefore(sessionId, Number.MAX_SAFE_INTEGER, 5, ["session.canvas_updated"]);
+    //
+    // Window 30, not 5: five interleaved slots can push one slot's latest
+    // draw well past a five-event window. The session_canvases table is the
+    // fast path; this scan is the durable fallback.
+    const rows = await catalog.getSessionEventsBefore(sessionId, Number.MAX_SAFE_INTEGER, 30, ["session.canvas_updated"]);
     let latest = { rev: 0 };
     for (const row of rows || []) {
+        if (eventSlot(row) !== slot)
+            continue;
         const rev = Number(row?.data?.rev);
         if (Number.isFinite(rev) && Number.isInteger(rev) && rev > latest.rev) {
             latest = { rev, responseContract: row?.data?.responseContract };
@@ -60,10 +218,21 @@ async function latestCanvasEventData(catalog, sessionId) {
     }
     return latest;
 }
-async function latestCanvasRev(catalog, sessionId) {
-    const rows = await catalog.getSessionEventsBefore(sessionId, Number.MAX_SAFE_INTEGER, 5, ["session.canvas_updated"]);
+async function latestCanvasRev(catalog, sessionId, slot = 1) {
+    // Table first (migration 0045); event scan as the durable fallback for
+    // rows the table has not seen (legacy sessions, a missed upsert).
+    try {
+        const rows = await catalog.getSessionCanvases?.(sessionId);
+        const hit = (rows || []).find((r) => Number(r.slot) === slot);
+        if (hit && Number(hit.latestRev) > 0)
+            return Number(hit.latestRev);
+    }
+    catch { /* fall through to the event scan */ }
+    const rows = await catalog.getSessionEventsBefore(sessionId, Number.MAX_SAFE_INTEGER, 30, ["session.canvas_updated"]);
     let latest = 0;
     for (const row of rows || []) {
+        if (eventSlot(row) !== slot)
+            continue;
         const rev = Number(row?.data?.rev);
         if (Number.isFinite(rev) && rev > latest && Number.isInteger(rev))
             latest = rev;
@@ -1021,28 +1190,24 @@ artifactStore) {
                         return sanitized;
                     };
                     const isReadOnlyTuner = () => runConfig.agentIdentity === "agent-tuner";
-                    const normalizeAgentLookup = (value) => (value || "").toLowerCase().replace(/[^a-z0-9]+/g, "");
-                    const resolveAgentConfigInline = (agentName) => {
-                        const agents = [
-                            ...(userAgents ?? []).map(a => ({ ...a, system: false, creatable: true })),
-                            ...(systemAgents ?? []).map(a => ({ ...a, creatable: false })),
-                        ];
-                        let lookupNamespace;
-                        let rawName = agentName;
-                        if (agentName.includes(":")) {
-                            const parts = agentName.split(":");
-                            lookupNamespace = parts[0];
-                            rawName = parts.slice(1).join(":");
-                        }
-                        const lookup = normalizeAgentLookup(rawName);
-                        const lookupBase = lookup.replace(/agent$/, "");
-                        return agents.find(a => {
-                            if (lookupNamespace && normalizeAgentLookup(a.namespace) !== normalizeAgentLookup(lookupNamespace))
-                                return false;
-                            const candidates = [a.name, a.id, a.title].map(normalizeAgentLookup).filter(Boolean);
-                            return candidates.includes(lookup) || (lookupBase && candidates.includes(lookupBase));
-                        }) ?? null;
-                    };
+                    // The one shared resolver — FQN parsing (`__shared:` works here too),
+                    // package privacy, and the caller's own-copy shadowing included. The
+                    // previous inline copy had none of that: it could hand another user's
+                    // private agent to this session and could not address the shared copy
+                    // of a shadowed name.
+                    const resolveAgentConfigInline = (agentName) => resolveAgentDefinitionForCaller({
+                        agentName,
+                        userAgents,
+                        systemAgents,
+                        getCallerOwnerKey: async () => {
+                            const owner = catalog
+                                ? await resolveEffectiveSpawnOwner((id) => catalog.getSession(id), input.sessionId).catch(() => null)
+                                : null;
+                            return owner?.provider && owner?.subject
+                                ? `${owner.provider}\u0001${owner.subject}`
+                                : null;
+                        },
+                    });
                     const loadDirectChildSessions = async () => {
                         const sdkClient = await getInlineClient();
                         const sessions = await sdkClient.listSessions();
@@ -1120,10 +1285,12 @@ artifactStore) {
                     // Same-turn draw serialization: parallel draw_canvas calls in one
                     // assistant message would otherwise race the derive-write-record
                     // section and mint duplicate revisions.
-                    async function latestCanvasDataRev(catalog, sessionId) {
-                        const rows = await catalog.getSessionEventsBefore(sessionId, Number.MAX_SAFE_INTEGER, 5, ["session.canvas_data"]);
+                    async function latestCanvasDataRev(catalog, sessionId, slot = 1) {
+                        const rows = await catalog.getSessionEventsBefore(sessionId, Number.MAX_SAFE_INTEGER, 30, ["session.canvas_data"]);
                         let latest = 0;
                         for (const row of rows || []) {
+                            if (eventSlot(row) !== slot)
+                                continue;
                             const rev = Number(row?.data?.dataRev);
                             if (Number.isFinite(rev) && rev > latest && Number.isInteger(rev))
                                 latest = rev;
@@ -1248,7 +1415,7 @@ artifactStore) {
                                 const agentName = String(args.agent_name || "").trim();
                                 if (!agentName)
                                     return "Error: agent_name is required.";
-                                const agentDef = resolveAgentConfigInline(agentName);
+                                const agentDef = await resolveAgentConfigInline(agentName);
                                 if (!agentDef) {
                                     return `[SYSTEM: create_agent_session failed — agent "${agentName}" not found. Use list_agent_packages / ps_list_agents to see what is installed.]`;
                                 }
@@ -1373,7 +1540,7 @@ artifactStore) {
                                             : "app-agent");
                                 };
                                 if (resolvedAgentName) {
-                                    const agentDef = resolveAgentConfigInline(resolvedAgentName);
+                                    const agentDef = await resolveAgentConfigInline(resolvedAgentName);
                                     if (!agentDef) {
                                         return `[SYSTEM: spawn_agent failed — agent "${resolvedAgentName}" not found. Use ps_list_agents to see available agents.]`;
                                     }
@@ -1894,18 +2061,25 @@ artifactStore) {
                         // session-proxy's generic onEvent persister treats
                         // canvas_updated as already-persisted (see EPHEMERAL_TYPES); the
                         // handler's opts.onEvent emit is the live-push half only.
-                        ...(input.parentSessionId ? {} : {
+                        // Every session gets the canvas bridge — root, sub-agent, and
+                        // sub-sub-agent alike. Each draws its OWN canvases; there is no
+                        // cross-session canvas access here, so a child cannot touch its
+                        // parent's surface any more than a stranger's.
+                        ...({
                             drawCanvas: async (args) => {
                                 if (!artifactStore)
                                     return { error: "this worker has no artifact store" };
                                 if (!catalog)
                                     return { error: "canvas requires the CMS catalog" };
+                                const slot = normalizeCanvasSlot(args.slot);
+                                if (slot === null)
+                                    return { error: "slot must be an integer 1-5" };
+                                const rawName = args.name === undefined ? undefined : String(args.name).trim();
+                                if (rawName !== undefined && rawName.length > 60) {
+                                    return { error: "name must be 60 characters or fewer" };
+                                }
                                 const run = canvasDrawChain.then(async () => {
-                                    const row = await catalog.getSession(input.sessionId).catch(() => null);
-                                    if (row?.parentSessionId) {
-                                        return { error: "the canvas is only available on root sessions" };
-                                    }
-                                    const rev = (await latestCanvasRev(catalog, input.sessionId)) + 1;
+                                    const rev = (await latestCanvasRev(catalog, input.sessionId, slot)) + 1;
                                     // Source resolution. fromArtifact pulls bytes store-side —
                                     // the same trust stance as read_artifact/write_artifact's
                                     // cross-session paths (the artifact layer is worker-trusted);
@@ -1969,7 +2143,7 @@ artifactStore) {
                                     }
                                     const app = canvasAppCard(extraction.manifest);
                                     const note = args.note ? String(args.note) : undefined;
-                                    await artifactStore.uploadArtifact(input.sessionId, CANVAS_ARTIFACT_FILENAME, html, "text/html", 
+                                    await artifactStore.uploadArtifact(input.sessionId, canvasArtifactFilename(slot), html, "text/html", 
                                     // Pinned on EVERY draw, not just the first: uploads
                                     // replace artifact metadata wholesale, so a pin set
                                     // once at rev 1 was silently erased by rev 2.
@@ -1984,14 +2158,27 @@ artifactStore) {
                                             eventType: "session.canvas_updated",
                                             data: {
                                                 rev,
+                                                slot,
+                                                ...(rawName !== undefined ? { name: rawName } : {}),
                                                 sizeBytes,
                                                 ...(note ? { note } : {}),
                                                 ...(effectiveContract ? { responseContract: effectiveContract } : {}),
                                                 ...(source ? { source } : {}),
                                             },
                                         }], workerNodeId);
+                                    // The per-slot cache (migration 0045). Non-fatal on
+                                    // purpose: the event above is durable, and the next
+                                    // draw falls back to the event scan if this row is
+                                    // missing — failing the draw over a cache write would
+                                    // invert the dependency.
+                                    try {
+                                        await catalog.upsertSessionCanvas?.(input.sessionId, slot, rawName ?? null, rev, sizeBytes);
+                                    }
+                                    catch { /* self-heals on the next draw */ }
                                     return {
                                         rev,
+                                        slot,
+                                        ...(rawName !== undefined ? { name: rawName } : {}),
                                         sizeBytes,
                                         ...(source ? { source } : {}),
                                         ...(app ? { app } : {}),
@@ -2005,15 +2192,14 @@ artifactStore) {
                             updateCanvas: async (args) => {
                                 if (!catalog)
                                     return { error: "canvas requires the CMS catalog" };
+                                const slot = normalizeCanvasSlot(args.slot);
+                                if (slot === null)
+                                    return { error: "slot must be an integer 1-5" };
                                 const run = canvasDrawChain.then(async () => {
-                                    const row = await catalog.getSession(input.sessionId).catch(() => null);
-                                    if (row?.parentSessionId) {
-                                        return { error: "the canvas is only available on root sessions" };
-                                    }
-                                    if ((await latestCanvasRev(catalog, input.sessionId)) === 0) {
-                                        return { error: "no canvas has been drawn on this session — draw_canvas first; ticks patch an existing page" };
+                                    if ((await latestCanvasRev(catalog, input.sessionId, slot)) === 0) {
+                                        return { error: `no canvas has been drawn in slot ${slot} — draw_canvas first; ticks patch an existing page` };
                                     }
-                                    const dataRev = (await latestCanvasDataRev(catalog, input.sessionId)) + 1;
+                                    const dataRev = (await latestCanvasDataRev(catalog, input.sessionId, slot)) + 1;
                                     const sizeBytes = Buffer.byteLength(JSON.stringify(args.data), "utf8");
                                     // The payload rides the durable event — it IS the
                                     // replay source for cold loads; no artifact write.
@@ -2021,21 +2207,45 @@ artifactStore) {
                                             eventType: "session.canvas_data",
                                             data: {
                                                 dataRev,
+                                                slot,
                                                 sizeBytes,
                                                 payload: args.data,
                                                 ...(args.note ? { note: String(args.note) } : {}),
                                             },
                                         }], workerNodeId);
-                                    return { dataRev, sizeBytes };
+                                    return { dataRev, slot, sizeBytes };
                                 }).catch((err) => ({ error: err?.message || String(err) }));
                                 canvasDrawChain = run.then(() => undefined, () => undefined);
                                 return run;
                             },
+                            // Bring an ALREADY-DRAWN canvas to the user's screen without
+                            // redrawing it: no bytes, no new rev, nothing marked unseen.
+                            // The portal routes the event through the same flip guards a
+                            // draw uses (active session, freshness, per-slot opt-out).
+                            showCanvas: async (args) => {
+                                if (!catalog)
+                                    return { error: "canvas requires the CMS catalog" };
+                                const slot = normalizeCanvasSlot(args.slot);
+                                if (slot === null)
+                                    return { error: "slot must be an integer 1-5" };
+                                const rev = await latestCanvasRev(catalog, input.sessionId, slot);
+                                if (rev === 0) {
+                                    return { error: `nothing has been drawn in slot ${slot} — draw_canvas first; show_canvas only presents an existing canvas` };
+                                }
+                                await catalog.recordEvents(input.sessionId, [{
+                                        eventType: "session.canvas_presented",
+                                        data: { slot, rev },
+                                    }], workerNodeId);
+                                return { presented: true, slot, rev };
+                            },
                             readCanvas: async (args) => {
                                 if (!artifactStore)
                                     return { error: "this worker has no artifact store" };
                                 if (!catalog)
                                     return { error: "canvas requires the CMS catalog" };
+                                const slot = normalizeCanvasSlot(args.slot);
+                                if (slot === null)
+                                    return { error: "slot must be an integer 1-5" };
                                 try {
                                     // Log FIRST: the event log is the single authority on
                                     // whether a canvas exists. Orphan bytes from a crashed
@@ -2051,10 +2261,10 @@ artifactStore) {
                                         // ARMED contract from the latest draw event — the
                                         // pair an inheriting agent needs to interpret
                                         // canvas-action messages and author ticks.
-                                        const latest = await latestCanvasEventData(catalog, input.sessionId);
+                                        const latest = await latestCanvasEventData(catalog, input.sessionId, slot);
                                         if (latest.rev === 0)
                                             return { exists: false };
-                                        const docText = await artifactStore.downloadArtifactText(input.sessionId, CANVAS_ARTIFACT_FILENAME);
+                                        const docText = await artifactStore.downloadArtifactText(input.sessionId, canvasArtifactFilename(slot));
                                         const extraction = extractCanvasAppManifest(docText);
                                         const card = canvasAppCard(extraction.manifest);
                                         // Events are writable via send_session_event with no
@@ -2071,10 +2281,10 @@ artifactStore) {
                                             ...(extraction.error ? { manifestError: extraction.error } : {}),
                                         };
                                     }
-                                    const rev = await latestCanvasRev(catalog, input.sessionId);
+                                    const rev = await latestCanvasRev(catalog, input.sessionId, slot);
                                     if (rev === 0)
                                         return { exists: false };
-                                    const text = await artifactStore.downloadArtifactText(input.sessionId, CANVAS_ARTIFACT_FILENAME);
+                                    const text = await artifactStore.downloadArtifactText(input.sessionId, canvasArtifactFilename(slot));
                                     const offset = Math.max(0, Math.floor(Number(args.offset) || 0));
                                     const maxChars = Math.min(262_144, Math.max(1, Math.floor(Number(args.maxBytes) || 65_536)));
                                     const content = text.slice(offset, offset + maxChars);
@@ -2134,6 +2344,9 @@ artifactStore) {
                         // handler's emit is the live-push half only; recording it here
                         // too would double-insert every revision.
                         "session.canvas_updated",
+                        // Same contract as canvas_updated: the showCanvas bridge
+                        // records it durably itself; the emit is live-push only.
+                        "session.canvas_presented",
                         // Same contract for data ticks: the updateCanvas bridge method
                         // records the event (payload inline) inside the serialized
                         // section — the generic path must not double-insert it.
@@ -3066,143 +3279,42 @@ artifactStore) {
     // Resolves a loaded agent definition by name. User-creatable agents return
     // creatable=true. Worker-managed system agents return creatable=false so
     // callers can surface a clear error instead of spawning them.
+    //
+    // Matching, package privacy, and owner shadowing all live in
+    // resolveAgentDefinitionForCaller — shared with the control bridge so
+    // spawn_agent/create_agent_session and this activity can never disagree
+    // about which agent a name means.
     runtime.registerActivity("resolveAgentConfig", async (_activityCtx, input) => {
-        const agents = [
-            ...(userAgents ?? []).map(a => ({ ...a, system: false, creatable: true })),
-            ...(systemAgents ?? []).map(a => ({ ...a, creatable: false })),
-        ];
-        const normalize = (value) => (value || "").toLowerCase().replace(/[^a-z0-9]+/g, "");
-        // Parse the reference. `a:b` has meant `namespace:agent` since long
-        // before FQNs existed, so the parser reports that shape as AMBIGUOUS
-        // and we keep the namespace reading first — an existing binding must
-        // not change meaning because per-user namespaces shipped.
-        const fqn = parseAgentFqn(input.agentName);
-        let lookupNamespace;
-        let rawName = input.agentName;
-        /** `__shared:` explicitly asks past the caller's own copy. */
-        let sharedOnly = false;
-        if (fqn.kind === "shared") {
-            rawName = fqn.name;
-            sharedOnly = true;
-        }
-        else if (fqn.kind === "bare") {
-            rawName = fqn.name;
-        }
-        else if (fqn.kind === "ambiguous" || fqn.kind === "owner") {
-            rawName = fqn.name;
-            lookupNamespace = fqn.namespaceRef ?? fqn.ownerRef;
-        }
-        else {
-            // Invalid (reserved prefix, bad semver, malformed). Fall back to
-            // the raw string so a legitimately odd agent name still resolves
-            // the way it always did; a reserved name simply will not match.
-            rawName = input.agentName;
-        }
-        const lookup = normalize(rawName);
-        // Also try without trailing "agent" suffix for fuzzy matching
-        // (LLM often says "Sweeper agent" which normalizes to "sweeperagent", but id is "sweeper")
-        const lookupBase = lookup.replace(/agent$/, "");
-        /**
-         * PACKAGE PRIVACY, enforced at RESOLUTION rather than at creation.
-         *
-         * Workers install every enabled package, including other users'
-         * user-scope ones, so `userAgents` is a fleet-wide list with no
-         * tenancy in it. The Web API filters package agents when a session is
-         * created (`_authorizePackageAgentCreate`), but `spawn_agent` reaches
-         * this activity directly and never passes through that filter — so a
-         * name match alone would hand Alice's private agent, prompt and all,
-         * to Bob's session.
-         *
-         * It has to be enforced HERE and not at spawn time: the return value
-         * carries the agent's full prompt, and merely returning it writes that
-         * prompt into the caller's orchestration history.
-         *
-         * Deployment-owned plugin agents carry no package owner and stay
-         * public, exactly as before.
-         */
-        let callerOwnerKey = null;
-        let callerResolved = false;
-        const ownerKeyOf = (owner) => owner?.provider && owner?.subject ? `${owner.provider}\u0001${owner.subject}` : null;
-        /** Resolve the caller's owner once per invocation, memoized and fail-closed. */
-        const callerOwnerKeyOnce = async () => {
-            if (!callerResolved) {
-                callerResolved = true;
-                try {
-                    const row = input.callerSessionId
-                        ? await catalog?.getSession(input.callerSessionId)
-                        : null;
-                    callerOwnerKey = ownerKeyOf(row?.owner);
-                }
-                catch {
-                    // Fail closed: an unresolvable caller gets no private agents.
-                    callerOwnerKey = null;
-                }
-            }
-            return callerOwnerKey;
-        };
-        const visibleToCaller = async (agent) => {
-            const agentOwnerKey = ownerKeyOf(agent?.packageOwner);
-            if (agent?.packageScope !== "user" || !agentOwnerKey)
-                return true;
-            const key = await callerOwnerKeyOnce();
-            return key !== null && key === agentOwnerKey;
-        };
-        const candidatesFor = (a) => [a.name, a.id, a.title].map(normalize).filter(Boolean);
-        const nameMatches = (a) => {
-            const candidates = candidatesFor(a);
-            return candidates.includes(lookup) || (lookupBase && candidates.includes(lookupBase));
-        };
-        let matches = agents.filter(a => {
-            if (lookupNamespace && normalize(a.namespace) !== normalize(lookupNamespace))
-                return false;
-            return nameMatches(a);
+        return resolveAgentDefinitionForCaller({
+            agentName: input.agentName,
+            userAgents,
+            systemAgents,
+            // PACKAGE PRIVACY, enforced at RESOLUTION rather than at creation.
+            //
+            // Workers install every enabled package, including other users'
+            // user-scope ones, so `userAgents` is a fleet-wide list with no
+            // tenancy in it. The Web API filters package agents when a session
+            // is created (`_authorizePackageAgentCreate`), but `spawn_agent`
+            // reaches this activity directly and never passes through that
+            // filter — so a name match alone would hand Alice's private agent,
+            // prompt and all, to Bob's session.
+            //
+            // It has to be enforced HERE and not at spawn time: the return
+            // value carries the agent's full prompt, and merely returning it
+            // writes that prompt into the caller's orchestration history.
+            //
+            // Deployment-owned plugin agents carry no package owner and stay
+            // public, exactly as before.
+            getCallerOwnerKey: async () => {
+                const row = input.callerSessionId
+                    ? await catalog?.getSession(input.callerSessionId)
+                    : null;
+                const owner = row?.owner;
+                return owner?.provider && owner?.subject
+                    ? `${owner.provider}\u0001${owner.subject}`
+                    : null;
+            },
         });
-        // An ambiguous `a:b` that matched nothing as `namespace:agent` gets its
-        // second reading — `owner:package` — rather than just failing. Order,
-        // not guesswork: the old meaning always wins when it resolves.
-        if (matches.length === 0 && fqn.kind === "ambiguous") {
-            matches = agents.filter(nameMatches);
-        }
-        if (sharedOnly) {
-            // `__shared:x` means the deployment's copy, explicitly. This is the
-            // one thing bare-name precedence otherwise takes away: without it,
-            // a user with their own copy could never reach the shared one.
-            matches = matches.filter(a => a.packageScope !== "user");
-        }
-        else {
-            // SHADOWING, at the agent level: the caller's own copy comes first,
-            // then everything public. Same rule the registry resolver applies,
-            // so "run X" and "show me X" cannot disagree about which X.
-            const callerKey = await callerOwnerKeyOnce();
-            matches = [
-                ...matches.filter(a => a.packageScope === "user" && ownerKeyOf(a.packageOwner) === callerKey && callerKey !== null),
-                ...matches.filter(a => !(a.packageScope === "user" && ownerKeyOf(a.packageOwner) === callerKey && callerKey !== null)),
-            ];
-        }
-        let agent = undefined;
-        for (const candidate of matches) {
-            if (await visibleToCaller(candidate)) {
-                agent = candidate;
-                break;
-            }
-        }
-        if (!agent)
-            return null;
-        return {
-            name: agent.name,
-            prompt: agent.prompt,
-            tools: agent.tools ?? undefined,
-            initialPrompt: agent.initialPrompt ?? undefined,
-            title: agent.title ?? undefined,
-            system: agent.system ?? undefined,
-            id: agent.id ?? undefined,
-            parent: agent.parent ?? undefined,
-            splash: agent.splash ?? undefined,
-            splashMobile: agent.splashMobile ?? undefined,
-            namespace: agent.namespace ?? undefined,
-            promptLayerKind: agent.promptLayerKind ?? undefined,
-            creatable: agent.creatable ?? !agent.system,
-        };
     });
     // ── spawnChildSession ─────────────────────────────────────
     // Creates a child session via the PilotSwarmClient SDK.