@indexnetwork/protocol 4.3.3-rc.308.1 → 4.3.4-rc.310.1

package/dist/intent/intent.tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intent.tools.d.ts","sourceRoot":"/","sources":["intent/intent.tools.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AA4D5E,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,qDAorBvE"}
+{"version":3,"file":"intent.tools.d.ts","sourceRoot":"/","sources":["intent/intent.tools.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AA8D5E,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,qDAssBvE"}

package/dist/intent/intent.tools.js

@@ -4,6 +4,7 @@ import { protocolLogger } from "../shared/observability/protocol.logger.js";
 import { traceGraph } from "../shared/observability/trace.js";
 import { success, error, UUID_REGEX } from "../shared/agent/tool.helpers.js";
 import { invokeWithAbortSignal } from "../shared/agent/model-signal.js";
+import { deriveAllowedNetworkIds, focusedNetworkId, focusedNetworkLabel } from "../shared/agent/tool.scope.js";
 const logger = protocolLogger("ChatTools:Intent");
 /**
  * Sanitize JSON string for use inside a markdown code fence (```). Escapes backticks
@@ -12,13 +13,14 @@ const logger = protocolLogger("ChatTools:Intent");
 function sanitizeJsonForCodeFence(json) {
     return json.replace(/`/g, "\\u0060");
 }
-/** When context is index-scoped, verifies the caller is still a member of that index. Returns error message or null. */
+/** When context is network-scoped, verifies the caller is still a member of that index. Returns error message or null. */
 async function ensureScopedMembership(context, systemDb) {
-    if (!context.networkId)
+    const scopedNetworkId = focusedNetworkId(context);
+    if (!scopedNetworkId)
         return null;
-    const isMember = await systemDb.isNetworkMember(context.networkId, context.userId);
+    const isMember = await systemDb.isNetworkMember(scopedNetworkId, context.userId);
     if (!isMember) {
-        return `This chat is scoped to ${context.indexName ?? 'this index'}. You are no longer a member of this community.`;
+        return `This chat is scoped to ${focusedNetworkLabel(context)}. You are no longer a member of this community.`;
     }
     return null;
 }
@@ -60,17 +62,17 @@ export function createIntentTools(defineTool, deps) {
         description: "Retrieves intents (signals of interest/need, e.g. 'Looking for a React developer in Berlin'). " +
             "Intents are the core unit of discovery — they represent what users are seeking and drive semantic matching for opportunities.\n\n" +
             "**Usage modes:**\n" +
-            "- No parameters: returns the **caller's own** active intents. In an index-scoped chat the result is clamped to the reachable indexes (the bound index plus the user's personal index). In an unscoped chat the result spans all of the user's active intents. There is no implicit default to the scoped index — to browse the bound community's intents, pass `networkId` explicitly.\n" +
+            "- No parameters: returns the **caller's own** active intents. In an network-scoped chat the result is clamped to the reachable networks (the bound network plus the user's personal network). In an unscoped chat the result spans all of the user's active intents. There is no implicit default to the scoped network — to browse the bound community's intents, pass `networkId` explicitly.\n" +
             "- With networkId: returns **all members'** intents in that index (community browse path). Add userId to filter to one member.\n" +
-            "- With userId in an index-scoped chat: reads that member's intents in the bound index. The target user must be a member of that index.\n" +
-            "- With userId in an unscoped chat: only works for the current user (cannot read another user's global intents without an index scope).\n\n" +
-            "**Workflow:** To explore what members of an index are looking for, first call read_network_memberships(networkId) to list members, " +
+            "- With userId in an network-scoped chat: reads that member's intents in the bound network. The target user must be a member of that index.\n" +
+            "- With userId in an unscoped chat: only works for the current user (cannot read another user's global intents without an network scope).\n\n" +
+            "**Workflow:** To explore what members of a network are looking for, first call read_network_memberships(networkId) to list members, " +
             "then read_intents(networkId) to see all intents in that community. " +
             "Each intent includes: id, description (payload), summary, confidence (0-1), inferenceType (explicit/implicit), status, and linked indexes.\n\n" +
             "**Returns:** Paginated list of intents with count. Use the intent IDs in subsequent calls to update_intent, delete_intent, or create_intent_index.",
         querySchema: z.object({
-            networkId: z.string().optional().describe("Index UUID — filters intents to this index (community browse path: returns all members' intents). There is no implicit default in index-scoped chats; omit to get caller-owned intents across the reachable indexes, or pass the scoped index UUID to browse community members. Get index IDs from read_networks."),
-            userId: z.string().optional().describe("User ID — filters to this user's intents. In an index-scoped chat, this reads that member's intents in the bound index (no networkId required). In an unscoped chat, only the current user is allowed without networkId; cross-user reads require an index scope. Omit for caller-owned intents."),
+            networkId: z.string().optional().describe("Network UUID — filters intents to this network (community browse path: returns all members' intents). There is no implicit default in network-scoped chats; omit to get caller-owned intents across the reachable networks, or pass the scoped network UUID to browse community members. Get network IDs from read_networks."),
+            userId: z.string().optional().describe("User ID — filters to this user's intents. In an network-scoped chat, this reads that member's intents in the bound network (no networkId required). In an unscoped chat, only the current user is allowed without networkId; cross-user reads require an network scope. Omit for caller-owned intents."),
             limit: z.number().int().min(1).max(100).optional().describe("Page size (1-100). Defaults to returning all results if omitted."),
             page: z.number().int().min(1).optional().describe("Page number (1-based). Only used when limit is also provided."),
         }),
@@ -79,6 +81,8 @@ export function createIntentTools(defineTool, deps) {
             if (scopeErr)
                 return error(scopeErr);
             // Distinguish "explicit network browse" from "implicit scope-aware read"
+            const scopedNetworkId = focusedNetworkId(context);
+            const scopedIndexLabel = focusedNetworkLabel(context);
             const explicitNetworkId = query.networkId?.trim();
             const explicitUserId = query.userId?.trim();
             // Validate explicit networkId format
@@ -86,25 +90,24 @@ export function createIntentTools(defineTool, deps) {
                 return error("Invalid network ID format.");
             }
             // Strict scope enforcement: in a scoped chat, the only allowed explicit
-            // networkId is context.networkId itself. The chat's focus is the bound
-            // network; cross-network browse must happen in a separate (unscoped)
-            // chat or a chat scoped to that other network.
-            if (context.networkId && explicitNetworkId && explicitNetworkId !== context.networkId) {
-                return error(`This chat is scoped to ${context.indexName ?? 'this index'}. You can only read intents from this community.`);
-            }
-            // Cross-user read in scoped chat: target user must be a member of the scoped index
-            if (context.networkId && explicitUserId && explicitUserId !== context.userId) {
-                const isInScopedIndex = await deps.systemDb.isNetworkMember(context.networkId, explicitUserId);
+            // networkId is the envelope's scoped network. Cross-network browse must
+            // happen in a separate unscoped chat or a chat scoped to that network.
+            if (scopedNetworkId && explicitNetworkId && explicitNetworkId !== scopedNetworkId) {
+                return error(`This chat is scoped to ${scopedIndexLabel}. You can only read intents from this community.`);
+            }
+            // Cross-user read in scoped chat: target user must be a member of the scoped network
+            if (scopedNetworkId && explicitUserId && explicitUserId !== context.userId) {
+                const isInScopedIndex = await deps.systemDb.isNetworkMember(scopedNetworkId, explicitUserId);
                 if (!isInScopedIndex) {
-                    return error(`This chat is scoped to ${context.indexName ?? 'this index'}. You can only read intents from members of this community.`);
+                    return error(`This chat is scoped to ${scopedIndexLabel}. You can only read intents from members of this community.`);
                 }
             }
-            // Cross-user global read is disallowed without an index scope
-            if (!explicitNetworkId && !context.networkId && explicitUserId && explicitUserId !== context.userId) {
+            // Cross-user global read is disallowed without an network scope
+            if (!explicitNetworkId && !scopedNetworkId && explicitUserId && explicitUserId !== context.userId) {
                 return error("Cannot read another user's global intents. Use networkId to scope to a shared network.");
             }
             // Membership check for explicit cross-network reads in unscoped chats
-            if (!context.networkId && explicitNetworkId) {
+            if (!scopedNetworkId && explicitNetworkId) {
                 const callerIsMember = await deps.systemDb.isNetworkMember(explicitNetworkId, context.userId);
                 if (!callerIsMember) {
                     return error("You can only read intents from indexes you are a member of.");
@@ -126,10 +129,10 @@ export function createIntentTools(defineTool, deps) {
                 if (explicitUserId)
                     graphInput.queryUserId = explicitUserId;
             }
-            else if (explicitUserId && context.networkId) {
+            else if (explicitUserId && scopedNetworkId) {
                 // Scoped chat + userId: implicit network is the chat's bound network.
                 // Membership of the target user was verified above.
-                graphInput.networkId = context.networkId;
+                graphInput.networkId = scopedNetworkId;
                 graphInput.queryUserId = explicitUserId;
             }
             else if (explicitUserId) {
@@ -137,9 +140,13 @@ export function createIntentTools(defineTool, deps) {
                 graphInput.queryUserId = explicitUserId;
                 graphInput.allUserIntents = true;
             }
-            else if (context.indexScope && context.indexScope.length > 0 && context.networkId) {
-                // Scoped chat, implicit read: caller-only across reachable indexes.
-                graphInput.indexScope = context.indexScope;
+            else if (scopedNetworkId) {
+                // Scoped chat, implicit read: caller-only across reachable networks.
+                graphInput.indexScope = deriveAllowedNetworkIds({
+                    memberships: context.userNetworks,
+                    scopeType: 'network',
+                    scopeId: scopedNetworkId,
+                });
             }
             else {
                 // Unscoped, implicit read: caller's global intents.
@@ -199,7 +206,7 @@ export function createIntentTools(defineTool, deps) {
             "to create_user_context are handled by that tool directly — do not scrape first.",
         querySchema: z.object({
             description: z.string().describe("A clear, specific description of what the user is looking for. Should be concept-based, not a raw URL. If the user shared a URL, scrape it first with scrape_url and pass the synthesized content here. Vague descriptions will be rejected — include what kind, what for, and/or timeframe."),
-            networkId: z.string().optional().describe("Index UUID to link the intent to upon creation. Defaults to the scoped index in index-scoped chats. Get index IDs from read_networks. If omitted, the system auto-assigns to relevant indexes based on their prompts."),
+            networkId: z.string().optional().describe("Network UUID to link the intent to upon creation. Defaults to the scoped network in network-scoped chats. Get network IDs from read_networks. If omitted, the system auto-assigns to relevant networks based on their prompts."),
             autoApprove: z.boolean().optional().describe("When true, automatically persists all verified intents without returning proposal cards for manual approval. MCP agents SHOULD set this to true since there is no UI for card-based approval. Web chat agents should omit or set to false to get interactive proposal cards."),
         }),
         handler: async ({ context, query }) => {
@@ -209,13 +216,15 @@ export function createIntentTools(defineTool, deps) {
             if (!query.description?.trim()) {
                 return error("Description is required.");
             }
+            const scopedNetworkId = focusedNetworkId(context);
+            const scopedIndexLabel = focusedNetworkLabel(context);
             // Strict scope enforcement
-            if (context.networkId && query.networkId?.trim() && query.networkId.trim() !== context.networkId) {
-                return error(`This chat is scoped to ${context.indexName ?? 'this index'}. You can only create intents in this community.`);
+            if (scopedNetworkId && query.networkId?.trim() && query.networkId.trim() !== scopedNetworkId) {
+                return error(`This chat is scoped to ${scopedIndexLabel}. You can only create intents in this community.`);
             }
-            const effectiveIndexId = context.networkId || query.networkId?.trim() || undefined;
-            const scopeEnvelope = context.scopeType && context.scopeId
-                ? { scopeType: context.scopeType, scopeId: context.scopeId }
+            const effectiveIndexId = scopedNetworkId || query.networkId?.trim() || undefined;
+            const scopeEnvelope = scopedNetworkId
+                ? { scopeType: 'network', scopeId: scopedNetworkId }
                 : {};
             // Fetch profile (the intent graph needs it for inference)
             const _profileGraphStart1 = Date.now();
@@ -375,12 +384,14 @@ export function createIntentTools(defineTool, deps) {
             if (intent.archivedAt) {
                 return error("This intent is archived and cannot be updated. Create a new intent instead.");
             }
-            // Strict scope enforcement: when chat is index-scoped, verify intent is linked to that index
-            if (context.networkId) {
+            const scopedNetworkId = focusedNetworkId(context);
+            const scopedIndexLabel = focusedNetworkLabel(context);
+            // Strict scope enforcement: when chat is network-scoped, verify intent is linked to that index
+            if (scopedNetworkId) {
                 const db = deps.userDb;
                 const intentNetworks = await db.getNetworkIdsForIntent(intentId);
-                if (!intentNetworks.includes(context.networkId)) {
-                    return error(`This chat is scoped to ${context.indexName ?? 'this index'}. You can only update intents linked to this community.`);
+                if (!intentNetworks.includes(scopedNetworkId)) {
+                    return error(`This chat is scoped to ${scopedIndexLabel}. You can only update intents linked to this community.`);
                 }
             }
             const _profileGraphStart2 = Date.now();
@@ -396,8 +407,7 @@ export function createIntentTools(defineTool, deps) {
                 operationMode: 'update',
                 inputContent: query.description,
                 targetIntentIds: [intentId],
-                ...(context.networkId && { networkId: context.networkId }),
-                ...(context.scopeType && context.scopeId ? { scopeType: context.scopeType, scopeId: context.scopeId } : {}),
+                ...(scopedNetworkId && { networkId: scopedNetworkId, scopeType: 'network', scopeId: scopedNetworkId }),
             }));
             const _intentGraphMs2 = Date.now() - _intentGraphStart2;
             if (result.executionResults?.some((r) => !r.success)) {
@@ -440,12 +450,14 @@ export function createIntentTools(defineTool, deps) {
             if (!intent || intent.userId !== context.userId) {
                 return error("Intent not found or you can only delete your own intents.");
             }
-            // Strict scope enforcement: when chat is index-scoped, verify intent is linked to that index
-            if (context.networkId) {
+            const scopedNetworkId = focusedNetworkId(context);
+            const scopedIndexLabel = focusedNetworkLabel(context);
+            // Strict scope enforcement: when chat is network-scoped, verify intent is linked to that index
+            if (scopedNetworkId) {
                 const db = deps.userDb;
                 const intentNetworks = await db.getNetworkIdsForIntent(intentId);
-                if (!intentNetworks.includes(context.networkId)) {
-                    return error(`This chat is scoped to ${context.indexName ?? 'this index'}. You can only delete intents linked to this community.`);
+                if (!intentNetworks.includes(scopedNetworkId)) {
+                    return error(`This chat is scoped to ${scopedIndexLabel}. You can only delete intents linked to this community.`);
                 }
             }
             const _deleteIntentGraphStart = Date.now();
@@ -454,8 +466,7 @@ export function createIntentTools(defineTool, deps) {
                 userProfile: "",
                 operationMode: 'delete',
                 targetIntentIds: [intentId],
-                ...(context.networkId && { networkId: context.networkId }),
-                ...(context.scopeType && context.scopeId ? { scopeType: context.scopeType, scopeId: context.scopeId } : {}),
+                ...(scopedNetworkId && { networkId: scopedNetworkId, scopeType: 'network', scopeId: scopedNetworkId }),
             }));
             const _deleteIntentGraphMs = Date.now() - _deleteIntentGraphStart;
             if (result.executionResults?.some((r) => !r.success)) {
@@ -472,27 +483,29 @@ export function createIntentTools(defineTool, deps) {
     // ─────────────────────────────────────────────────────────────────────────────
     const createIntentIndex = defineTool({
         name: "create_intent_index",
-        description: "Manually links an intent to an index (community), making it visible to other members and eligible for opportunity discovery within that index. " +
+        description: "Manually links an intent to a network (community), making it visible to other members and eligible for opportunity discovery within that index. " +
             "Normally intents are auto-assigned to relevant indexes on creation, but use this to explicitly add an intent to an additional index.\n\n" +
             "**When to use:** When the user wants to share an existing intent with a specific community they belong to, " +
-            "or when auto-assignment missed an index the user considers relevant.\n\n" +
+            "or when auto-assignment missed a network the user considers relevant.\n\n" +
             "**Returns:** Confirmation that the link was created. The intent will now appear in that index's intent list and participate in discovery within that community.",
         querySchema: z.object({
             intentId: z.string().describe("The UUID of the intent to link. Get this from read_intents results."),
-            networkId: z.string().optional().describe("The UUID of the index to link the intent to. Get this from read_networks. Defaults to the scoped index in index-scoped chats."),
+            networkId: z.string().optional().describe("The UUID of the network to link the intent to. Get this from read_networks. Defaults to the scoped network in network-scoped chats."),
         }),
         handler: async ({ context, query }) => {
             const scopeErr = await ensureScopedMembership(context, deps.systemDb);
             if (scopeErr)
                 return error(scopeErr);
+            const scopedNetworkId = focusedNetworkId(context);
+            const scopedIndexLabel = focusedNetworkLabel(context);
             const intentId = query.intentId?.trim() ?? "";
-            const networkId = query.networkId?.trim() || context.networkId || "";
+            const networkId = query.networkId?.trim() || scopedNetworkId || "";
             if (!UUID_REGEX.test(intentId) || !UUID_REGEX.test(networkId)) {
                 return error("Invalid ID format. Both must be UUIDs.");
             }
-            // Strict scope enforcement: when chat is index-scoped, only allow linking to that index
-            if (context.networkId && networkId !== context.networkId) {
-                return error(`This chat is scoped to ${context.indexName ?? 'this index'}. You can only link intents to this community.`);
+            // Strict scope enforcement: when chat is network-scoped, only allow linking to that index
+            if (scopedNetworkId && networkId !== scopedNetworkId) {
+                return error(`This chat is scoped to ${scopedIndexLabel}. You can only link intents to this community.`);
             }
             const _createIntentIndexGraphStart = Date.now();
             const result = await traceGraph("intent_network", () => invokeWithAbortSignal(graphs.intentIndex, {
@@ -524,21 +537,23 @@ export function createIntentTools(defineTool, deps) {
             "**Usage modes:**\n" +
             "- With networkId: lists all intents linked to that index. Add userId to filter to one member's intents in that index.\n" +
             "- With intentId + networkId: checks whether a specific intent is linked to a specific index.\n" +
-            "- intentId alone requires a networkId (the system won't reveal all indexes an intent is in).\n\n" +
+            "- intentId alone requires a networkId (the system won't reveal all networks an intent is in).\n\n" +
             "**When to use:** To audit which intents are active in a community, verify an intent's index assignment before unlinking, " +
             "or check if a newly created intent was auto-assigned to the expected index.\n\n" +
-            "**Returns:** List of intent-index links with relevancy scores (0-1, how well the intent fits the index's purpose).",
+            "**Returns:** List of intent-network links with relevancy scores (0-1, how well the intent fits the network's purpose).",
         querySchema: z.object({
             intentId: z.string().optional().describe("Intent UUID — check if this specific intent is linked to the specified index. Must be combined with networkId."),
-            networkId: z.string().optional().describe("Index UUID — list all intents linked to this index. Get this from read_networks. Defaults to scoped index in index-scoped chats."),
+            networkId: z.string().optional().describe("Network UUID — list all intents linked to this network. Get this from read_networks. Defaults to scoped network in network-scoped chats."),
             userId: z.string().optional().describe("Filter results to this user's intents within the specified index. Omit to see all members' intents."),
         }),
         handler: async ({ context, query }) => {
             const scopeErr = await ensureScopedMembership(context, deps.systemDb);
             if (scopeErr)
                 return error(scopeErr);
+            const scopedNetworkId = focusedNetworkId(context);
+            const scopedIndexLabel = focusedNetworkLabel(context);
             const intentId = query.intentId?.trim() || undefined;
-            let networkId = query.networkId?.trim() || context.networkId || undefined;
+            let networkId = query.networkId?.trim() || scopedNetworkId || undefined;
             const queryUserId = query.userId?.trim() || undefined;
             if (intentId && !UUID_REGEX.test(intentId)) {
                 return error("Invalid intent ID format.");
@@ -549,18 +564,18 @@ export function createIntentTools(defineTool, deps) {
             if (!intentId && !networkId) {
                 return error("Provide networkId or intentId.");
             }
-            // Strict scope enforcement: when chat is index-scoped, only allow querying that index
-            if (context.networkId && networkId && networkId !== context.networkId) {
-                return error(`This chat is scoped to ${context.indexName ?? 'this index'}. You can only read intent links from this community.`);
+            // Strict scope enforcement: when chat is network-scoped, only allow querying that index
+            if (scopedNetworkId && networkId && networkId !== scopedNetworkId) {
+                return error(`This chat is scoped to ${scopedIndexLabel}. You can only read intent links from this community.`);
             }
             // When only intentId is provided, enforce scope - don't reveal all linked indexes
             if (intentId && !networkId) {
-                if (context.networkId) {
-                    // When scoped, only check if intent is linked to the scoped index
-                    networkId = context.networkId;
+                if (scopedNetworkId) {
+                    // When scoped, only check if intent is linked to the scoped network
+                    networkId = scopedNetworkId;
                 }
                 else {
-                    // When unscoped, still don't reveal all indexes - require explicit networkId
+                    // When unscoped, still don't reveal all networks - require explicit networkId
                     return error("Please provide a networkId to check if the intent is linked to a specific network. Listing all linked networks is not supported.");
                 }
             }
@@ -584,27 +599,29 @@ export function createIntentTools(defineTool, deps) {
     });
     const deleteIntentIndex = defineTool({
         name: "delete_intent_index",
-        description: "Removes the link between an intent and an index. The intent itself is NOT deleted — it just stops being visible in that community " +
+        description: "Removes the link between an intent and a network. The intent itself is NOT deleted — it just stops being visible in that community " +
             "and no longer participates in opportunity discovery within that index. The intent may still be linked to other indexes.\n\n" +
             "**When to use:** When the user wants to withdraw an intent from a specific community without archiving it entirely. " +
             "Use read_intent_indexes first to verify the link exists.\n\n" +
             "**Returns:** Confirmation that the link was removed. To fully remove an intent, use delete_intent instead.",
         querySchema: z.object({
             intentId: z.string().describe("The UUID of the intent to unlink. Get this from read_intents or read_intent_indexes."),
-            networkId: z.string().optional().describe("The UUID of the index to unlink from. Get this from read_networks. Defaults to the scoped index in index-scoped chats."),
+            networkId: z.string().optional().describe("The UUID of the network to unlink from. Get this from read_networks. Defaults to the scoped network in network-scoped chats."),
         }),
         handler: async ({ context, query }) => {
             const scopeErr = await ensureScopedMembership(context, deps.systemDb);
             if (scopeErr)
                 return error(scopeErr);
+            const scopedNetworkId = focusedNetworkId(context);
+            const scopedIndexLabel = focusedNetworkLabel(context);
             const intentId = query.intentId?.trim() ?? "";
-            const networkId = query.networkId?.trim() || context.networkId || "";
+            const networkId = query.networkId?.trim() || scopedNetworkId || "";
             if (!UUID_REGEX.test(intentId) || !UUID_REGEX.test(networkId)) {
                 return error("Invalid ID format. Both must be UUIDs.");
             }
-            // Strict scope enforcement: when chat is index-scoped, only allow unlinking from that index
-            if (context.networkId && networkId !== context.networkId) {
-                return error(`This chat is scoped to ${context.indexName ?? 'this index'}. You can only unlink intents from this community.`);
+            // Strict scope enforcement: when chat is network-scoped, only allow unlinking from that index
+            if (scopedNetworkId && networkId !== scopedNetworkId) {
+                return error(`This chat is scoped to ${scopedIndexLabel}. You can only unlink intents from this community.`);
             }
             const _deleteIntentIndexGraphStart = Date.now();
             const result = await traceGraph("intent_network", () => invokeWithAbortSignal(graphs.intentIndex, {