@indexnetwork/protocol 6.12.1-rc.404.1 → 6.13.22-rc.405.1

package/dist/network/network.tools.d.ts

@@ -1,3 +1,5 @@
-import type { DefineTool, ToolDeps } from "../shared/agent/tool.helpers.js";
-export declare function createNetworkTools(defineTool: DefineTool, deps: ToolDeps): readonly [any, any, any, any, any, any, any];
-//# sourceMappingURL=network.tools.d.ts.map
+/**
+ * @deprecated Canonical location: communities/application/network.tools — retained
+ * for backward compatibility (IND-546).
+ */
+export { createNetworkTools } from "../communities/application/index.js";

package/dist/network/network.tools.js

@@ -1,566 +1,5 @@
-import { z } from "zod";
-import { requestContext } from "../shared/observability/request-context.js";
-import { log } from "../shared/observability/log.js";
-import { renderNetworkContext } from '../shared/network/metadata.renderer.js';
-import { success, error, UUID_REGEX } from "../shared/agent/tool.helpers.js";
-import { NetworkRecommender } from "./network.recommender.js";
-// Lazy singleton — only instantiated on first onboarding ranking call so that
-// importing this module does not require OPENROUTER_API_KEY at load time.
-let recommender;
-const logger = log.protocol.from("ChatTools:Network");
-export function createNetworkTools(defineTool, deps) {
-    const { graphs, userDb, systemDb } = deps;
-    const enrichWithContext = (networks) => networks.map((n) => ({
-        ...n,
-        renderedContext: renderNetworkContext({
-            type: n.type ?? 'community',
-            title: n.title ?? '',
-            prompt: n.prompt,
-            metadata: n.metadata ?? {},
-        }),
-    }));
-    const readIndexes = defineTool({
-        name: "read_networks",
-        description: "Lists the authenticated user's networks (communities), including ones they own and public communities they can join.\n\n" +
-            "**When to use:** To find network IDs for scoping other operations (read_intents, discover_opportunities, read_network_memberships), " +
-            "or to show the user which communities they belong to.\n\n" +
-            "**Returns:** Up to three lists — `memberOf` (networks the user joined), `owns` (networks the user created), and `publicNetworks` " +
-            "(publicly joinable communities the user is not yet a member of). Entries in `memberOf` include `isPersonal` set to `true` for the user's " +
-            "personal network.\n\n" +
-            "**Note:** In network-scoped chats, only the scoped network is returned. During onboarding, `orderedNetworkIds` " +
-            "may be returned alongside `publicNetworks` \u2014 a ranked array of network IDs ordered by relevance to the user's profile (omitted when ranking is unavailable or fails).",
-        querySchema: z.object({
-            userId: z.string().optional().describe("Must be the current user's ID or omitted. Cannot list another user's indexes."),
-        }),
-        handler: async ({ context, query }) => {
-            if (query.userId && query.userId.trim() !== context.userId) {
-                return error("You can only list your own indexes. Omit userId to see the current user's indexes.");
-            }
-            const _readIndexGraphStart = Date.now();
-            const _readIndexTraceEmitter = requestContext.getStore()?.traceEmitter;
-            _readIndexTraceEmitter?.({ type: "graph_start", name: "index" });
-            const result = await graphs.index.invoke({
-                userId: context.userId,
-                networkId: context.networkId || undefined,
-                operationMode: 'read',
-                showAll: false, // Never allow bypass - strict scope enforcement
-            });
-            const _readIndexGraphMs = Date.now() - _readIndexGraphStart;
-            _readIndexTraceEmitter?.({ type: "graph_end", name: "index", durationMs: _readIndexGraphMs });
-            if (result.error) {
-                return error(result.error);
-            }
-            if (result.readResult) {
-                const rr = result.readResult;
-                const enriched = {
-                    ...rr,
-                    ...(Array.isArray(rr.memberOf) ? { memberOf: enrichWithContext(rr.memberOf) } : {}),
-                    ...(Array.isArray(rr.owns) ? { owns: enrichWithContext(rr.owns) } : {}),
-                    ...(Array.isArray(rr.publicNetworks) ? { publicNetworks: enrichWithContext(rr.publicNetworks) } : {}),
-                };
-                // When scoped, add clear metadata so model knows results are limited
-                if (context.networkId) {
-                    return success({
-                        ...enriched,
-                        scopeRestriction: {
-                            isScoped: true,
-                            scopedToIndex: context.indexName ?? context.networkId,
-                            message: `Results are limited to "${context.indexName ?? 'this network'}" because this chat is scoped to that community. The user may belong to other communities not shown here.`,
-                        },
-                        _graphTimings: [{ name: 'index', durationMs: _readIndexGraphMs, agents: result.agentTimings ?? [] }],
-                    });
-                }
-                // Onboarding-only: rank public networks by relevance to the user's global
-                // user_context paragraph (the profile-replacing identity text). Guard: only
-                // when isOnboarding, not scoped, there are public networks to rank, and a
-                // user_context is resolvable (generated on demand by the injected resolver).
-                let orderedNetworkIds;
-                const userContext = deps.getUserContextText ? await deps.getUserContextText(context.userId) : "";
-                if (context.isOnboarding &&
-                    userContext &&
-                    Array.isArray(enriched.publicNetworks) &&
-                    enriched.publicNetworks.length > 0) {
-                    // Cap at 50 to bound LLM context window usage (matches the UI's discoverPublicIndexes(1, 50)).
-                    const publicNetworksForRanking = enriched.publicNetworks
-                        .slice(0, 50)
-                        .map((n) => ({
-                        networkId: n.networkId,
-                        renderedContext: n.renderedContext ?? `## ${n.title}`,
-                    }));
-                    const rankFn = deps.networkRanker ?? (async (input) => {
-                        try {
-                            recommender ?? (recommender = new NetworkRecommender());
-                            return await recommender.invoke(input);
-                        }
-                        catch (err) {
-                            // e.g. missing OPENROUTER_API_KEY — degrade gracefully, omit orderedNetworkIds
-                            logger.warn("read_networks: NetworkRecommender unavailable, skipping ranking", { error: err });
-                            return null;
-                        }
-                    });
-                    const rankingResult = await rankFn({
-                        userContext,
-                        networks: publicNetworksForRanking,
-                    }).catch((err) => {
-                        // Catches errors from a custom deps.networkRanker (the default fallback
-                        // handles its own errors internally). Degrade gracefully: omit orderedNetworkIds.
-                        logger.warn("read_networks: networkRanker threw, skipping ranking", { error: err });
-                        deps.reportToolError?.(err, { operation: "network-ranking", toolName: "read_networks", userId: context.userId });
-                        return null;
-                    });
-                    if (rankingResult) {
-                        // Normalize LLM output against the ranked slice (top 50):
-                        // keep only IDs from the input set, de-dupe preserving order, then
-                        // append any slice IDs the model omitted. Networks beyond the top-50
-                        // slice are not in orderedNetworkIds and will sort to the tail in the
-                        // frontend (consistent with the UI's own 50-item page size).
-                        const inputIds = publicNetworksForRanking.map((n) => n.networkId);
-                        const inputIdSet = new Set(inputIds);
-                        const seen = new Set();
-                        const normalized = [];
-                        for (const id of rankingResult.rankedNetworkIds) {
-                            if (inputIdSet.has(id) && !seen.has(id)) {
-                                normalized.push(id);
-                                seen.add(id);
-                            }
-                        }
-                        for (const id of inputIds) {
-                            if (!seen.has(id))
-                                normalized.push(id);
-                        }
-                        orderedNetworkIds = normalized;
-                    }
-                }
-                return success({
-                    ...enriched,
-                    ...(orderedNetworkIds !== undefined ? { orderedNetworkIds } : {}),
-                    _graphTimings: [{ name: 'index', durationMs: _readIndexGraphMs, agents: result.agentTimings ?? [] }],
-                });
-            }
-            return error("Failed to fetch index information.");
-        },
-    });
-    const readIndexMemberships = defineTool({
-        name: "read_network_memberships",
-        description: "Reads network membership information — who is in which community. Essential for understanding the social graph before " +
-            "creating introductions or exploring intents.\n\n" +
-            "**Usage modes:**\n" +
-            "- With `networkId` only: lists ALL members of that index — returns userId, name, avatar, permissions (owner/member), intentCount, and joinedAt. " +
-            "Use this to see who's in a community before browsing their intents or creating introductions.\n" +
-            "- With `userId` only (or omit for self): lists all networks that user belongs to — returns networkId, networkTitle, permissions, joinedAt.\n" +
-            "- With both `networkId` and `userId`: checks whether that specific user is a member of that specific index (returns isMember boolean).\n\n" +
-            "**When to use:** Before creating introductions (need to verify shared network membership), to explore community members, " +
-            "or to check if a user belongs to a specific index.\n\n" +
-            "**Returns:** Member list with user details, or membership list with index details, or a membership check result.\n\n" +
-            "**Personal network semantics.** The personal network (`isPersonal: true` on the membership) is the user's " +
-            "contact list — members of that index are the user's contacts. For another user, this tool only reveals the " +
-            "indexes you already share with them.\n\n" +
-            "**Shared-context pattern.** To find overlap with another user: (1) omit `userId` to read your own " +
-            "memberships, (2) call this tool with the other person's actual `userId` to get the shared networks, " +
-            "(3) call read_intents for each shared network to see what each is looking for there, (4) call " +
-            "read_user_contexts for the other party. That sequence gives you enough to decide whether to propose a " +
-            "direct connection or an introduction.",
-        querySchema: z.object({
-            networkId: z.string().optional().describe("Network UUID — lists all members of this network. Get from read_networks. In network-scoped chats, only the scoped index can be queried."),
-            userId: z.string().optional().describe("User ID — lists that user's network memberships. Omit to get the current user's memberships. When combined with networkId, checks if this user is in that specific index."),
-        }),
-        handler: async ({ context, query }) => {
-            const networkId = query.networkId?.trim() || undefined;
-            const userId = query.userId?.trim() || undefined;
-            if (networkId && !UUID_REGEX.test(networkId)) {
-                return error("Invalid network ID format. Use the exact UUID from read_networks.");
-            }
-            // Mode 1: list members of an index
-            if (networkId && !userId) {
-                // Enforce strict scope: when chat is network-scoped, only allow querying that index
-                if (context.networkId && networkId !== context.networkId) {
-                    return error(`This chat is scoped to ${context.indexName ?? 'this network'}. You can only query members of this network.`);
-                }
-                const _readMembersGraphStart = Date.now();
-                const _readMembersTraceEmitter = requestContext.getStore()?.traceEmitter;
-                _readMembersTraceEmitter?.({ type: "graph_start", name: "network_membership" });
-                const result = await graphs.networkMembership.invoke({
-                    userId: context.userId,
-                    networkId,
-                    operationMode: 'read',
-                });
-                const _readMembersGraphMs = Date.now() - _readMembersGraphStart;
-                _readMembersTraceEmitter?.({ type: "graph_end", name: "network_membership", durationMs: _readMembersGraphMs });
-                if (result.error) {
-                    return error(result.error);
-                }
-                if (result.readResult) {
-                    return success({ ...result.readResult, _graphTimings: [{ name: 'network_membership', durationMs: _readMembersGraphMs, agents: result.agentTimings ?? [] }] });
-                }
-                return error("Failed to fetch network members.");
-            }
-            // Mode 2: list a user's memberships (indexes they belong to)
-            const targetUserId = userId || context.userId;
-            // Use userDb for own memberships, but systemDb access is implicit through shared network scope
-            let memberships;
-            if (targetUserId !== context.userId) {
-                // Cross-user access: systemDb will validate shared network membership
-                const callerMemberships = await userDb.getNetworkMemberships();
-                if (networkId) {
-                    // Strict scope enforcement: when chat is network-scoped, only allow querying that index
-                    if (context.networkId && networkId !== context.networkId) {
-                        return error(`This chat is scoped to ${context.indexName ?? 'this network'}. You can only query membership in this community.`);
-                    }
-                    const callerInIndex = callerMemberships.some((m) => m.networkId === networkId);
-                    if (!callerInIndex) {
-                        return error("Unauthorized: you can only view another user's membership in an index you belong to. Provide your own userId or omit userId for your memberships.");
-                    }
-                    // Check if target user is in the index (systemDb validates scope)
-                    const isMember = await systemDb.isNetworkMember(networkId, targetUserId);
-                    if (isMember) {
-                        return success({ isMember: true, userId: targetUserId, networkId });
-                    }
-                    return success({ isMember: false, userId: targetUserId, networkId, message: "User is not a member of this network." });
-                }
-                else {
-                    // Strict scope enforcement: when chat is network-scoped, only check the scoped index
-                    if (context.networkId) {
-                        const isMember = await systemDb.isNetworkMember(context.networkId, targetUserId);
-                        if (isMember) {
-                            return success({
-                                isMember: true,
-                                userId: targetUserId,
-                                networkId: context.networkId,
-                                scopeRestriction: {
-                                    isScoped: true,
-                                    scopedToIndex: context.indexName ?? context.networkId,
-                                    message: `This chat is scoped to "${context.indexName ?? 'this network'}". Only membership in this community is shown.`,
-                                },
-                            });
-                        }
-                        return success({
-                            isMember: false,
-                            userId: targetUserId,
-                            networkId: context.networkId,
-                            message: "User is not a member of this community.",
-                            scopeRestriction: {
-                                isScoped: true,
-                                scopedToIndex: context.indexName ?? context.networkId,
-                                message: `This chat is scoped to "${context.indexName ?? 'this network'}". Only membership in this community was checked.`,
-                            },
-                        });
-                    }
-                    // Unscoped chat: show overlap with shared networks (intersection of caller and target memberships)
-                    const sharedIndexes = [];
-                    for (const m of callerMemberships) {
-                        if (await systemDb.isNetworkMember(m.networkId, targetUserId)) {
-                            sharedIndexes.push(m);
-                        }
-                    }
-                    if (sharedIndexes.length === 0) {
-                        return error("Unauthorized: you can only view another user's memberships if you share at least one index, or request your own memberships.");
-                    }
-                    // Return only the indexes that are shared
-                    return success({
-                        userId: targetUserId,
-                        count: sharedIndexes.length,
-                        memberships: sharedIndexes.map((m) => ({
-                            networkId: m.networkId,
-                            networkTitle: m.networkTitle,
-                        })),
-                        note: "Only showing shared networks.",
-                    });
-                }
-            }
-            else {
-                // Own memberships - use userDb
-                memberships = await userDb.getNetworkMemberships();
-                // NOTE: context.networkId here is the *focus* of the scoped chat — it filters
-                // what we show, not what we can reach. indexScope is the reach; the bound
-                // network is one element of it. See IND-306 for the equivalent in read_intents.
-                // Strict scope enforcement: when chat is network-scoped, only return the scoped network membership
-                if (context.networkId && !networkId) {
-                    memberships = memberships.filter((m) => m.networkId === context.networkId);
-                }
-            }
-            // If both networkId and userId: filter to that specific membership
-            if (networkId) {
-                // Strict scope enforcement: when chat is network-scoped, only allow querying that index
-                if (context.networkId && networkId !== context.networkId) {
-                    return error(`This chat is scoped to ${context.indexName ?? 'this network'}. You can only query membership in this community.`);
-                }
-                const callerMemberships = await userDb.getNetworkMemberships();
-                const callerInIndex = targetUserId === context.userId ||
-                    callerMemberships.some((m) => m.networkId === networkId);
-                if (!callerInIndex) {
-                    return error("Unauthorized: you can only view membership in an index you belong to.");
-                }
-                const match = memberships.find((m) => m.networkId === networkId);
-                if (!match) {
-                    return success({ isMember: false, userId: targetUserId, networkId, message: "User is not a member of this network." });
-                }
-                return success({
-                    isMember: true,
-                    userId: targetUserId,
-                    networkId,
-                    networkTitle: match.networkTitle,
-                    permissions: match.permissions,
-                    joinedAt: match.joinedAt,
-                });
-            }
-            // When scoped, add clear metadata so model knows results are limited
-            if (context.networkId && targetUserId === context.userId) {
-                return success({
-                    userId: targetUserId,
-                    count: memberships.length,
-                    memberships: memberships.map((m) => ({
-                        networkId: m.networkId,
-                        networkTitle: m.networkTitle,
-                        permissions: m.permissions,
-                        joinedAt: m.joinedAt,
-                    })),
-                    scopeRestriction: {
-                        isScoped: true,
-                        scopedToIndex: context.indexName ?? context.networkId,
-                        message: `Results are limited to "${context.indexName ?? 'this network'}" because this chat is scoped to that community. The user may belong to other communities not shown here.`,
-                    },
-                });
-            }
-            return success({
-                userId: targetUserId,
-                count: memberships.length,
-                memberships: memberships.map((m) => ({
-                    networkId: m.networkId,
-                    networkTitle: m.networkTitle,
-                    permissions: m.permissions,
-                    joinedAt: m.joinedAt,
-                })),
-            });
-        },
-    });
-    const updateNetworkSettingsSchema = z.object({
-        title: z.string().optional(),
-        prompt: z.string().nullable().optional(),
-        imageUrl: z.string().url().nullable().optional(),
-        joinPolicy: z.enum(['anyone', 'invite_only']).optional(),
-        allowGuestVibeCheck: z.boolean().optional(),
-    }).strict();
-    const updateNetwork = defineTool({
-        name: "update_network",
-        description: "Updates settings of an existing network (community). Only the network owner can perform updates.\n\n" +
-            "**Updatable fields:** title (display name), prompt (purpose description used for intent auto-assignment), " +
-            "imageUrl (community avatar), joinPolicy ('anyone' for open or 'invite_only'), allowGuestVibeCheck (allow non-members to preview).\n\n" +
-            "**When to use:** When a network owner wants to change their community's settings — e.g. update the purpose description, " +
-            "change from invite-only to open, or update the community image.\n\n" +
-            "**Important:** Changing the prompt affects how future intents are evaluated for auto-assignment to this network. " +
-            "Existing intent-network links are not re-evaluated automatically.\n\n" +
-            "**Returns:** Confirmation with the list of settings that were updated.",
-        querySchema: z.object({
-            networkId: z.string().optional().describe("Network UUID to update. Get from read_networks. Defaults to the scoped index in network-scoped chats."),
-            settings: updateNetworkSettingsSchema.describe("Object with fields to update. All fields are optional — only include the ones to change. title: display name. prompt: purpose description (used for intent auto-assignment). imageUrl: community image URL (null to remove). joinPolicy: 'anyone' or 'invite_only'. allowGuestVibeCheck: boolean."),
-        }),
-        handler: async ({ context, query }) => {
-            const effectiveIndexId = (query.networkId?.trim() || context.networkId) ?? null;
-            if (!effectiveIndexId || !UUID_REGEX.test(effectiveIndexId)) {
-                return error("Valid networkId required.");
-            }
-            // Strict scope enforcement: when chat is network-scoped, only allow updating that index
-            if (context.networkId && effectiveIndexId !== context.networkId) {
-                return error(`This chat is scoped to ${context.indexName ?? 'this network'}. You can only update this community's settings.`);
-            }
-            const _updateNetworkGraphStart = Date.now();
-            const _updateNetworkTraceEmitter = requestContext.getStore()?.traceEmitter;
-            _updateNetworkTraceEmitter?.({ type: "graph_start", name: "index" });
-            const result = await graphs.index.invoke({
-                userId: context.userId,
-                networkId: effectiveIndexId,
-                operationMode: 'update',
-                updateInput: query.settings,
-            });
-            const _updateNetworkGraphMs = Date.now() - _updateNetworkGraphStart;
-            _updateNetworkTraceEmitter?.({ type: "graph_end", name: "index", durationMs: _updateNetworkGraphMs });
-            if (result.mutationResult && !result.mutationResult.success) {
-                return error(result.mutationResult.error || "Failed to update index.");
-            }
-            return success({ message: "Index updated.", settings: Object.keys(query.settings), _graphTimings: [{ name: 'index', durationMs: _updateNetworkGraphMs, agents: result.agentTimings ?? [] }] });
-        },
-    });
-    const createNetwork = defineTool({
-        name: "create_network",
-        description: "Creates a new network (community/group). The authenticated user becomes the owner with full control over settings and membership.\n\n" +
-            "**What is a network?** A shared space where members post intents (what they're looking for) and the system discovers opportunities " +
-            "(complementary matches) between members. The network's prompt guides what kinds of intents belong.\n\n" +
-            "**When to use:** When the user wants to create a new community — e.g. a professional network, interest group, or project team.\n\n" +
-            "**Returns:** The new network's networkId (UUID) and title. Use the networkId to add members (create_network_membership), " +
-            "link intents (create_intent_index), or run discovery (discover_opportunities with networkId).",
-        querySchema: z.object({
-            title: z.string().describe("Display name of the network (e.g. 'AI Founders Berlin', 'Design Co-op'). Required."),
-            prompt: z.string().optional().describe("Description of what this community is about (e.g. 'Early-stage AI/ML founders in Berlin looking for co-founders, advisors, and investors'). Used by the system to evaluate which intents belong in this network. Highly recommended for better auto-assignment."),
-            imageUrl: z.string().url().optional().describe("URL for the community's avatar/image. Optional."),
-            joinPolicy: z.enum(['anyone', 'invite_only']).optional().describe("'anyone' = open (any user can self-join), 'invite_only' = only the owner can add members. Defaults to 'invite_only'."),
-        }),
-        handler: async ({ context, query }) => {
-            if (!query.title?.trim()) {
-                return error("Title is required.");
-            }
-            const _createNetworkGraphStart = Date.now();
-            const _createNetworkTraceEmitter = requestContext.getStore()?.traceEmitter;
-            _createNetworkTraceEmitter?.({ type: "graph_start", name: "index" });
-            const result = await graphs.index.invoke({
-                userId: context.userId,
-                operationMode: 'create',
-                createInput: {
-                    title: query.title.trim(),
-                    prompt: query.prompt?.trim() || undefined,
-                    imageUrl: query.imageUrl || undefined,
-                    joinPolicy: query.joinPolicy,
-                },
-            });
-            const _createNetworkGraphMs = Date.now() - _createNetworkGraphStart;
-            _createNetworkTraceEmitter?.({ type: "graph_end", name: "index", durationMs: _createNetworkGraphMs });
-            if (result.mutationResult) {
-                if (result.mutationResult.success) {
-                    return success({
-                        created: true,
-                        networkId: result.mutationResult.networkId,
-                        title: result.mutationResult.title,
-                        message: result.mutationResult.message,
-                        _graphTimings: [{ name: 'index', durationMs: _createNetworkGraphMs, agents: result.agentTimings ?? [] }],
-                    });
-                }
-                return error(result.mutationResult.error || "Failed to create network.");
-            }
-            return error("Failed to create network.");
-        },
-    });
-    const deleteNetwork = defineTool({
-        name: "delete_network",
-        description: "Permanently deletes a network (community). Only the owner can delete, and the network must have no other members " +
-            "(remove all members first with delete_network_membership). Personal networks cannot be deleted.\n\n" +
-            "**When to use:** When the owner wants to disband a community. This is irreversible — all intent-network links to this network are removed.\n\n" +
-            "**Prerequisites:** Must be the owner. Must be the sole remaining member (remove others first).\n\n" +
-            "**Returns:** Confirmation that the network was deleted.",
-        querySchema: z.object({
-            networkId: z.string().optional().describe("Network UUID to delete. Get from read_networks. Defaults to the scoped index in network-scoped chats. Cannot be a personal network."),
-        }),
-        handler: async ({ context, query }) => {
-            const networkId = query.networkId?.trim() || context.networkId;
-            if (!networkId || !UUID_REGEX.test(networkId)) {
-                return error("Valid networkId required.");
-            }
-            // Strict scope enforcement: when chat is network-scoped, only allow deleting that index
-            if (context.networkId && networkId !== context.networkId) {
-                return error(`This chat is scoped to ${context.indexName ?? 'this network'}. You can only delete this community.`);
-            }
-            const _deleteNetworkGraphStart = Date.now();
-            const _deleteNetworkTraceEmitter = requestContext.getStore()?.traceEmitter;
-            _deleteNetworkTraceEmitter?.({ type: "graph_start", name: "index" });
-            const result = await graphs.index.invoke({
-                userId: context.userId,
-                networkId,
-                operationMode: 'delete',
-            });
-            const _deleteNetworkGraphMs = Date.now() - _deleteNetworkGraphStart;
-            _deleteNetworkTraceEmitter?.({ type: "graph_end", name: "index", durationMs: _deleteNetworkGraphMs });
-            if (result.mutationResult && !result.mutationResult.success) {
-                return error(result.mutationResult.error || "Failed to delete network.");
-            }
-            return success({ message: "Network deleted.", _graphTimings: [{ name: 'index', durationMs: _deleteNetworkGraphMs, agents: result.agentTimings ?? [] }] });
-        },
-    });
-    const createNetworkMembership = defineTool({
-        name: "create_network_membership",
-        description: "Adds a user as a member of a network (community). Membership enables the user to post intents in the network and be discovered " +
-            "by other members through opportunity matching.\n\n" +
-            "**Usage modes:**\n" +
-            "- Omit userId: self-join (only works for networks with joinPolicy 'anyone').\n" +
-            "- With userId: add another user (only the network owner can do this for 'invite_only' indexes).\n\n" +
-            "**When to use:** When the user wants to join an open community, or when a network owner wants to invite someone.\n\n" +
-            "**Returns:** Confirmation that the member was added (or a note that they were already a member). " +
-            "After joining, the user's existing intents with autoAssign=true may be evaluated against the new network.",
-        querySchema: z.object({
-            userId: z.string().optional().describe("User ID to add as a member. Omit to join the network yourself. Get user IDs from read_user_contexts(query=name) or read_network_memberships."),
-            networkId: z.string().optional().describe("Network UUID to add the member to. Get from read_networks. Defaults to the scoped index in network-scoped chats."),
-        }),
-        handler: async ({ context, query }) => {
-            const networkId = query.networkId?.trim() || context.networkId;
-            const targetUserId = query.userId?.trim() || context.userId;
-            if (!networkId || !UUID_REGEX.test(networkId)) {
-                return error("Invalid network ID format. Use the exact UUID from read_networks.");
-            }
-            // Strict scope enforcement: when chat is network-scoped, only allow adding to that index
-            if (context.networkId && networkId !== context.networkId) {
-                return error(`This chat is scoped to ${context.indexName ?? 'this network'}. You can only add members to this community.`);
-            }
-            const _createMembershipGraphStart = Date.now();
-            const _createMembershipTraceEmitter = requestContext.getStore()?.traceEmitter;
-            _createMembershipTraceEmitter?.({ type: "graph_start", name: "network_membership" });
-            const result = await graphs.networkMembership.invoke({
-                userId: context.userId,
-                networkId,
-                targetUserId,
-                operationMode: 'create',
-            });
-            const _createMembershipGraphMs = Date.now() - _createMembershipGraphStart;
-            _createMembershipTraceEmitter?.({ type: "graph_end", name: "network_membership", durationMs: _createMembershipGraphMs });
-            if (result.mutationResult) {
-                if (result.mutationResult.success) {
-                    const alreadyMember = result.mutationResult.message?.includes("already");
-                    return success({
-                        created: !alreadyMember,
-                        message: result.mutationResult.message,
-                        _graphTimings: [{ name: 'network_membership', durationMs: _createMembershipGraphMs, agents: result.agentTimings ?? [] }],
-                    });
-                }
-                return error(result.mutationResult.error || "Failed to add member.");
-            }
-            return error("Failed to add member.");
-        },
-    });
-    const deleteNetworkMembership = defineTool({
-        name: "delete_network_membership",
-        description: "Removes a user from a network (community). After removal, the user's intents are unlinked from this network " +
-            "and they can no longer participate in opportunity discovery within it.\n\n" +
-            "**Permissions:** Only the network owner can remove members. The owner themselves cannot be removed (delete the network instead).\n\n" +
-            "**When to use:** When a network owner wants to remove a member from the community. " +
-            "Use read_network_memberships(networkId) first to get the userId of the member to remove.\n\n" +
-            "**Returns:** Confirmation that the member was removed.",
-        querySchema: z.object({
-            userId: z.string().describe("User ID of the member to remove. Get from read_network_memberships(networkId). Cannot be the network owner."),
-            networkId: z.string().optional().describe("Network UUID to remove the member from. Get from read_networks. Defaults to the scoped index in network-scoped chats."),
-        }),
-        handler: async ({ context, query }) => {
-            const networkId = query.networkId?.trim() || context.networkId;
-            const targetUserId = query.userId?.trim();
-            if (!networkId || !UUID_REGEX.test(networkId)) {
-                return error("Valid networkId required. Use the exact UUID from read_networks.");
-            }
-            if (!targetUserId) {
-                return error("userId is required.");
-            }
-            // Strict scope enforcement: when chat is network-scoped, only allow that index
-            if (context.networkId && networkId !== context.networkId) {
-                return error(`This chat is scoped to ${context.indexName ?? 'this network'}. You can only manage members of this community.`);
-            }
-            const _deleteMembershipGraphStart = Date.now();
-            const _deleteMembershipTraceEmitter = requestContext.getStore()?.traceEmitter;
-            _deleteMembershipTraceEmitter?.({ type: "graph_start", name: "network_membership" });
-            const result = await graphs.networkMembership.invoke({
-                userId: context.userId,
-                networkId,
-                targetUserId,
-                operationMode: 'delete',
-            });
-            const _deleteMembershipGraphMs = Date.now() - _deleteMembershipGraphStart;
-            _deleteMembershipTraceEmitter?.({ type: "graph_end", name: "network_membership", durationMs: _deleteMembershipGraphMs });
-            if (result.mutationResult) {
-                if (result.mutationResult.success) {
-                    return success({
-                        removed: true,
-                        message: result.mutationResult.message,
-                        _graphTimings: [{ name: 'network_membership', durationMs: _deleteMembershipGraphMs, agents: result.agentTimings ?? [] }],
-                    });
-                }
-                return error(result.mutationResult.error || "Failed to remove member.");
-            }
-            return error("Failed to remove member.");
-        },
-    });
-    return [readIndexes, readIndexMemberships, updateNetwork, createNetwork, deleteNetwork, createNetworkMembership, deleteNetworkMembership];
-}
-//# sourceMappingURL=network.tools.js.map
+/**
+ * @deprecated Canonical location: communities/application/network.tools — retained
+ * for backward compatibility (IND-546).
+ */
+export { createNetworkTools } from "../communities/application/index.js";

package/dist/opportunity/application/delivery-card.cache.d.ts

@@ -0,0 +1,25 @@
+import type { Cache } from '../../shared/interfaces/cache.interface.js';
+import type { OpportunityPresenter, PresenterDatabase } from './opportunity.presenter.js';
+export interface CachedDeliveryCard {
+    opportunityId: string;
+    headline: string;
+    personalizedSummary: string;
+    suggestedAction: string;
+    narratorRemark: string;
+    /** Empty string means presenter did not generate one (LLM error / fallback path). */
+    greeting: string;
+}
+export interface OpportunityWithContext {
+    id: string;
+    status: string;
+    actors: Array<{
+        userId: string;
+        role: string;
+    }>;
+    interpretation?: unknown;
+    detection?: unknown;
+}
+export declare const DELIVERY_CARD_CACHE_TTL: number;
+export declare function getOrCreateDeliveryCardBatch(cache: Cache, presenter: OpportunityPresenter, presenterDb: PresenterDatabase, opportunities: OpportunityWithContext[], viewerId: string, options?: {
+    ttl?: number;
+}): Promise<Map<string, CachedDeliveryCard>>;

package/dist/opportunity/application/delivery-card.cache.js

@@ -0,0 +1,43 @@
+import { gatherPresenterContext } from './opportunity.presenter.js';
+import { buildDeliveryCardPresentationCacheKey } from '../domain/opportunity.presentation-cache.js';
+export const DELIVERY_CARD_CACHE_TTL = 24 * 60 * 60; // 24 hours
+export async function getOrCreateDeliveryCardBatch(cache, presenter, presenterDb, opportunities, viewerId, options) {
+    if (opportunities.length === 0) {
+        return new Map();
+    }
+    const ttl = options?.ttl ?? DELIVERY_CARD_CACHE_TTL;
+    const keys = opportunities.map((opp) => buildDeliveryCardPresentationCacheKey(opp.id, opp.status, viewerId));
+    const cached = await cache.mget(keys);
+    const result = new Map();
+    const misses = [];
+    for (let i = 0; i < opportunities.length; i++) {
+        const item = cached[i];
+        if (item) {
+            result.set(opportunities[i].id, item);
+        }
+        else {
+            misses.push({ opp: opportunities[i], index: i });
+        }
+    }
+    // Generate cards for cache misses
+    await Promise.all(misses.map(async ({ opp, index }) => {
+        const presenterInput = await gatherPresenterContext(presenterDb, opp, viewerId);
+        presenterInput.opportunityStatus = opp.status;
+        const presented = await presenter.presentHomeCard(presenterInput);
+        const card = {
+            opportunityId: opp.id,
+            headline: presented.headline,
+            personalizedSummary: presented.personalizedSummary,
+            suggestedAction: presented.suggestedAction,
+            narratorRemark: presented.narratorRemark,
+            greeting: presented.greeting ?? '',
+        };
+        result.set(opp.id, card);
+        // Presenter fallbacks are safe for this request but are deliberately not
+        // persisted for 24 hours; a later request should retry genuine copy.
+        if (!presented.isFallback) {
+            await cache.set(keys[index], card, { ttl });
+        }
+    }));
+    return result;
+}