@indexnetwork/protocol 6.12.1-rc.404.1 → 6.14.0-rc.406.1

package/dist/communities/application/network.graph.js

@@ -0,0 +1,303 @@
+import { StateGraph, START, END } from "@langchain/langgraph";
+import { protocolLogger } from "../../shared/observability/protocol.logger.js";
+import { timed } from "../../shared/observability/performance.js";
+import { NetworkGraphState } from "../domain/index.js";
+const logger = protocolLogger("NetworkGraphFactory");
+/**
+ * Factory class to build and compile the Network (community) lifecycle graph.
+ *
+ * Handles create, read, update, and delete operations for networks.
+ * Membership and intent–network assignment operations are delegated to
+ * NetworkMembershipGraphFactory and IntentNetworkGraphFactory respectively.
+ *
+ * ## Ownership policy
+ *
+ * - `create`: the calling user becomes the sole owner.  The owner–membership
+ *   write is performed atomically after the network row is created; on failure
+ *   the network is soft-deleted (rollback).  Rollback failures are logged but
+ *   do NOT mutate the error response — the caller always receives the first
+ *   meaningful failure, not a noisy rollback message.
+ * - `update`: owner-only.  Any member field may be updated in one call.
+ * - `delete`: owner-only; the network must have no other members.
+ *
+ * ## Scope semantics (read mode)
+ *
+ * When `networkId` is set and `showAll` is false, only the focused network and
+ * the user's personal network (contacts) are returned.  This is the strict-scope
+ * invariant for network-bound agents.  Set `showAll: true` to bypass.
+ *
+ * Flow:
+ * START → routerNode → {createNode | readNode | updateNode | deleteNode} → END
+ *
+ * IND-546: canonical home — previously network/network.graph.ts.
+ */
+export class NetworkGraphFactory {
+    constructor(database) {
+        this.database = database;
+    }
+    createGraph() {
+        // --- NODE DEFINITIONS ---
+        /**
+         * Read Node: List networks the user belongs to and owns.
+         */
+        const readNode = async (state) => {
+            return timed("NetworkGraph.read", async () => {
+                logger.verbose("Read networks", { userId: state.userId, networkId: state.networkId, showAll: state.showAll });
+                // Shared projections for both the scoped and unscoped read paths.
+                const projectMembership = (m) => ({
+                    networkId: m.networkId,
+                    title: m.networkTitle,
+                    prompt: m.indexPrompt,
+                    autoAssign: m.autoAssign,
+                    isPersonal: m.isPersonal,
+                    joinedAt: m.joinedAt,
+                });
+                const projectOwned = (o) => ({
+                    networkId: o.id,
+                    title: o.title,
+                    prompt: o.prompt,
+                    memberCount: o.memberCount,
+                    intentCount: o.intentCount,
+                    joinPolicy: o.permissions.joinPolicy,
+                });
+                try {
+                    const [allMemberships, ownedIndexes, publicIndexesResult] = await Promise.all([
+                        this.database.getNetworkMemberships(state.userId),
+                        this.database.getOwnedIndexes(state.userId),
+                        this.database.getPublicIndexesNotJoined(state.userId),
+                    ]);
+                    // If network-scoped and not showAll, return just that network plus the
+                    // user's personal network (their contacts).  The personal network is part
+                    // of every allowed-network reach calculation for network-bound agents,
+                    // and a user in a community-scoped chat still owns their contact list —
+                    // so surfacing it here keeps contact tools discoverable.  Other community
+                    // memberships are still hidden, and `publicNetworks` is omitted.
+                    const scopeToCurrentNetwork = state.networkId && !state.showAll;
+                    if (scopeToCurrentNetwork) {
+                        const networkId = state.networkId;
+                        const isMember = await this.database.isNetworkMember(networkId, state.userId);
+                        if (!isMember) {
+                            return {
+                                readResult: {
+                                    memberOf: [],
+                                    owns: [],
+                                    stats: { memberOfCount: 0, ownsCount: 0, scopeNote: "Network not found or you are not a member." },
+                                },
+                            };
+                        }
+                        const scopedMembership = allMemberships.find((m) => m.networkId === networkId);
+                        const personalMembership = scopedMembership?.isPersonal
+                            ? undefined
+                            : allMemberships.find((m) => m.isPersonal);
+                        const scopedOwned = ownedIndexes.find((o) => o.id === networkId);
+                        const personalOwned = personalMembership
+                            ? ownedIndexes.find((o) => o.id === personalMembership.networkId)
+                            : undefined;
+                        const memberOf = [
+                            ...(scopedMembership ? [projectMembership(scopedMembership)] : []),
+                            ...(personalMembership ? [projectMembership(personalMembership)] : []),
+                        ];
+                        const owns = [
+                            ...(scopedOwned ? [projectOwned(scopedOwned)] : []),
+                            ...(personalOwned ? [projectOwned(personalOwned)] : []),
+                        ];
+                        return {
+                            readResult: {
+                                memberOf,
+                                owns,
+                                stats: {
+                                    memberOfCount: memberOf.length,
+                                    ownsCount: owns.length,
+                                    scopeNote: "Showing current network and your personal network. Use showAll: true for all networks.",
+                                },
+                            },
+                        };
+                    }
+                    // Include public networks available to join
+                    const publicNetworks = publicIndexesResult.networks.map((idx) => ({
+                        networkId: idx.id,
+                        title: idx.title,
+                        prompt: idx.prompt,
+                        memberCount: idx.memberCount,
+                        owner: idx.owner,
+                    }));
+                    return {
+                        readResult: {
+                            memberOf: allMemberships.map(projectMembership),
+                            owns: ownedIndexes.map(projectOwned),
+                            publicNetworks,
+                            stats: { memberOfCount: allMemberships.length, ownsCount: ownedIndexes.length, publicNetworksCount: publicNetworks.length },
+                        },
+                    };
+                }
+                catch (err) {
+                    logger.error("Read networks failed", { error: err });
+                    return { error: "Failed to fetch network information." };
+                }
+            });
+        };
+        /**
+         * Create Node: Create a new network and add user as owner.
+         *
+         * Atomicity contract:
+         * 1. Create the network row.
+         * 2. Add the calling user as owner.
+         * 3. On step-2 failure: soft-delete the network (rollback).
+         * 4. Rollback failures are logged at error level but never override the
+         *    primary failure message returned to the caller.
+         */
+        const createNode = async (state) => {
+            return timed("NetworkGraph.create", async () => {
+                logger.verbose("Create network", { userId: state.userId, createInput: state.createInput });
+                if (!state.createInput?.title?.trim()) {
+                    return { mutationResult: { success: false, error: "Title is required." } };
+                }
+                let createdNetworkId;
+                try {
+                    const network = await this.database.createNetwork({
+                        title: state.createInput.title.trim(),
+                        prompt: state.createInput.prompt?.trim() || undefined,
+                        imageUrl: state.createInput.imageUrl ?? undefined,
+                        joinPolicy: state.createInput.joinPolicy,
+                    });
+                    createdNetworkId = network.id;
+                    const added = await this.database.addMemberToNetwork(network.id, state.userId, 'owner');
+                    if (!added.success) {
+                        logger.error("addMemberToNetwork failed; cleaning up orphaned network", { networkId: network.id });
+                        try {
+                            await this.database.softDeleteNetwork(network.id);
+                        }
+                        catch (rollbackError) {
+                            logger.error("Network create rollback failed", {
+                                networkId: network.id,
+                                rollbackFor: "owner_membership",
+                                rollbackErrorKind: rollbackError instanceof Error ? "error" : "non_error",
+                            });
+                        }
+                        return { mutationResult: { success: false, error: "Failed to set you as owner. Network was not created." } };
+                    }
+                    return {
+                        mutationResult: {
+                            success: true,
+                            networkId: network.id,
+                            title: network.title,
+                            message: `Network "${network.title}" created. You are the owner.`,
+                        },
+                    };
+                }
+                catch (err) {
+                    logger.error("Create network failed", { error: err });
+                    if (createdNetworkId) {
+                        try {
+                            await this.database.softDeleteNetwork(createdNetworkId);
+                        }
+                        catch (rollbackError) {
+                            logger.error("Network create rollback failed", {
+                                networkId: createdNetworkId,
+                                rollbackFor: "create_operation",
+                                rollbackErrorKind: rollbackError instanceof Error ? "error" : "non_error",
+                            });
+                        }
+                    }
+                    return {
+                        mutationResult: {
+                            success: false,
+                            error: err instanceof Error ? err.message : "Failed to create network.",
+                        },
+                    };
+                }
+            });
+        };
+        /**
+         * Update Node: Update network settings (owner only).
+         */
+        const updateNode = async (state) => {
+            return timed("NetworkGraph.update", async () => {
+                const networkId = state.networkId;
+                logger.verbose("Update network", { userId: state.userId, networkId, updateInput: state.updateInput });
+                if (!networkId) {
+                    return { mutationResult: { success: false, error: "networkId is required for update." } };
+                }
+                try {
+                    const isOwner = await this.database.isIndexOwner(networkId, state.userId);
+                    if (!isOwner) {
+                        return { mutationResult: { success: false, error: "You can only modify networks you own." } };
+                    }
+                    await this.database.updateIndexSettings(networkId, state.userId, state.updateInput ?? {});
+                    return {
+                        mutationResult: {
+                            success: true,
+                            networkId,
+                            message: "Network settings updated.",
+                        },
+                    };
+                }
+                catch (err) {
+                    logger.error("Update network failed", { error: err });
+                    return { mutationResult: { success: false, error: "Failed to update network." } };
+                }
+            });
+        };
+        /**
+         * Delete Node: Soft-delete a network (owner only, sole member).
+         */
+        const deleteNode = async (state) => {
+            return timed("NetworkGraph.delete", async () => {
+                const networkId = state.networkId;
+                logger.verbose("Delete network", { userId: state.userId, networkId });
+                if (!networkId) {
+                    return { mutationResult: { success: false, error: "networkId is required for delete." } };
+                }
+                try {
+                    const isOwner = await this.database.isIndexOwner(networkId, state.userId);
+                    if (!isOwner) {
+                        return { mutationResult: { success: false, error: "You can only delete networks you own." } };
+                    }
+                    const count = await this.database.getNetworkMemberCount(networkId);
+                    if (count > 1) {
+                        return { mutationResult: { success: false, error: "Cannot delete network with other members. Remove members first." } };
+                    }
+                    await this.database.softDeleteNetwork(networkId);
+                    return {
+                        mutationResult: {
+                            success: true,
+                            networkId,
+                            message: "Network deleted.",
+                        },
+                    };
+                }
+                catch (err) {
+                    logger.error("Delete network failed", { error: err });
+                    return { mutationResult: { success: false, error: "Failed to delete network." } };
+                }
+            });
+        };
+        // --- CONDITIONAL ROUTING ---
+        const routeByMode = (state) => {
+            switch (state.operationMode) {
+                case 'create': return 'create';
+                case 'read': return 'read';
+                case 'update': return 'update';
+                case 'delete': return 'delete_idx';
+                default: return 'read';
+            }
+        };
+        // --- GRAPH ASSEMBLY ---
+        const workflow = new StateGraph(NetworkGraphState)
+            .addNode("read", readNode)
+            .addNode("create", createNode)
+            .addNode("update", updateNode)
+            .addNode("delete_idx", deleteNode)
+            .addConditionalEdges(START, routeByMode, {
+            read: "read",
+            create: "create",
+            update: "update",
+            delete_idx: "delete_idx",
+        })
+            .addEdge("read", END)
+            .addEdge("create", END)
+            .addEdge("update", END)
+            .addEdge("delete_idx", END);
+        return workflow.compile();
+    }
+}

package/dist/communities/application/network.recommender.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+export declare const NetworkRecommenderOutputSchema: z.ZodObject<{
+    rankedNetworkIds: z.ZodArray<z.ZodString, "many">;
+    reasoning: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reasoning: string;
+    rankedNetworkIds: string[];
+}, {
+    reasoning: string;
+    rankedNetworkIds: string[];
+}>;
+export type NetworkRecommenderOutput = z.infer<typeof NetworkRecommenderOutputSchema>;
+export interface NetworkRecommenderNetwork {
+    networkId: string;
+    renderedContext: string;
+}
+export interface NetworkRecommenderInput {
+    /** The user's global user_context paragraph (synthesized identity text). */
+    userContext: string;
+    networks: NetworkRecommenderNetwork[];
+}
+/**
+ * LLM-based agent that ranks public communities against a user's profile.
+ * Used during onboarding step 6 to surface the most relevant communities first.
+ *
+ * Follows the IntentIndexer pattern: `withStructuredOutput`, `invokeWithAbortSignal`,
+ * null-on-error fallback.  `createStructuredModel` is called inside the constructor
+ * (not at module level) so that importing this module does not require
+ * OPENROUTER_API_KEY to be set — tests that import communities tools without a
+ * live LLM env are unaffected.
+ *
+ * IND-546: canonical home — previously network/network.recommender.ts.
+ */
+export declare class NetworkRecommender {
+    private model;
+    constructor();
+    /**
+     * Ranks the provided networks by relevance to the user's profile.
+     *
+     * @param input - User profile and list of networks with rendered context.
+     * @returns Ranked network IDs and one-sentence reasoning, or null on error.
+     */
+    invoke(input: NetworkRecommenderInput): Promise<NetworkRecommenderOutput | null>;
+}

package/dist/communities/application/network.recommender.js

@@ -0,0 +1,113 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { HumanMessage, SystemMessage } from "@langchain/core/messages";
+import { z } from "zod";
+import { log } from "../../shared/observability/log.js";
+import { Timed } from "../../shared/observability/performance.js";
+import { createStructuredModel } from "../../shared/agent/model.config.js";
+import { invokeWithAbortSignal } from "../../shared/agent/model-signal.js";
+// ─── Response schema ───────────────────────────────────────────────────────────
+export const NetworkRecommenderOutputSchema = z.object({
+    rankedNetworkIds: z
+        .array(z.string())
+        .describe("Network IDs ordered from most to least relevant for this user. Include all provided network IDs."),
+    reasoning: z
+        .string()
+        .describe("One-sentence explanation of the top recommendation."),
+});
+// ─── Logger ───────────────────────────────────────────────────────────────────
+const logger = log.lib.from("NetworkRecommender");
+const invokeLog = log.lib.from("NetworkRecommender:invoke");
+// ─── System prompt ────────────────────────────────────────────────────────────
+const systemPrompt = `
+You are a community matching agent for a social discovery network.
+
+TASK:
+Given a user's profile and a list of communities, rank the communities from most to least relevant for this user.
+Return ALL provided community IDs in ranked order.
+
+INPUTS:
+1. User Context: a synthesized paragraph describing the user (background, interests, skills, location, goals).
+2. Communities: a list of communities, each with an ID and a description.
+
+SCORING FACTORS (in priority order):
+1. Thematic alignment — do the community's topics match the user's interests and skills?
+2. Geographic relevance — does the user's location match the community's focus (if any)?
+3. Professional fit — does the community's purpose match the user's professional background?
+
+OUTPUT RULES:
+- Return ALL community IDs in your ranked list (no omissions).
+- If context is insufficient to differentiate, preserve original order.
+- Keep reasoning brief (one sentence about the top recommendation).
+`;
+// ─── Agent class ──────────────────────────────────────────────────────────────
+/**
+ * LLM-based agent that ranks public communities against a user's profile.
+ * Used during onboarding step 6 to surface the most relevant communities first.
+ *
+ * Follows the IntentIndexer pattern: `withStructuredOutput`, `invokeWithAbortSignal`,
+ * null-on-error fallback.  `createStructuredModel` is called inside the constructor
+ * (not at module level) so that importing this module does not require
+ * OPENROUTER_API_KEY to be set — tests that import communities tools without a
+ * live LLM env are unaffected.
+ *
+ * IND-546: canonical home — previously network/network.recommender.ts.
+ */
+export class NetworkRecommender {
+    constructor() {
+        this.model = createStructuredModel("networkRecommender", NetworkRecommenderOutputSchema, {
+            name: "network_recommender",
+        });
+    }
+    /**
+     * Ranks the provided networks by relevance to the user's profile.
+     *
+     * @param input - User profile and list of networks with rendered context.
+     * @returns Ranked network IDs and one-sentence reasoning, or null on error.
+     */
+    async invoke(input) {
+        if (input.networks.length === 0)
+            return null;
+        invokeLog.verbose("Ranking communities", {
+            networkCount: input.networks.length,
+        });
+        const networkList = input.networks
+            .map((n, i) => `### Community ${i + 1} (ID: ${n.networkId})\n${n.renderedContext}`)
+            .join("\n\n");
+        const userSection = input.userContext.trim() || "(not provided)";
+        const prompt = `## User Context\n${userSection}\n\n## Communities to Rank\n${networkList}`;
+        const messages = [
+            new SystemMessage(systemPrompt),
+            new HumanMessage(prompt),
+        ];
+        try {
+            const result = await invokeWithAbortSignal(this.model, messages);
+            const parsed = NetworkRecommenderOutputSchema.safeParse(result);
+            if (!parsed.success) {
+                logger.error("Schema validation failed", { error: parsed.error });
+                return null;
+            }
+            invokeLog.verbose("Ranking complete", {
+                top: parsed.data.rankedNetworkIds[0],
+            });
+            return parsed.data;
+        }
+        catch (error) {
+            logger.error("Error during execution", { error });
+            return null;
+        }
+    }
+}
+__decorate([
+    Timed(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], NetworkRecommender.prototype, "invoke", null);

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

@@ -0,0 +1,35 @@
+import type { DefineTool } from "../../shared/agent/tool.helpers.js";
+import type { NetworkToolDeps } from "../../capabilities/communities.tools.port.js";
+/**
+ * Creates all community (network) lifecycle and membership tools.
+ *
+ * ## Exposed tools
+ *
+ * Foreground (participant-directed):
+ * - `read_networks` — list joined networks, owned networks, and public networks.
+ * - `read_network_memberships` — query membership: list members, check membership, or
+ *   list the user's memberships.
+ * - `create_network` — create a new network; caller becomes owner.
+ * - `update_network` — update settings (title, prompt, imageUrl, joinPolicy); owner-only.
+ * - `delete_network` — soft-delete (owner-only; network must have no other members).
+ * - `create_network_membership` — add a member (self-join or owner-invite).
+ * - `delete_network_membership` — remove a member (owner-only).
+ *
+ * Automatic assignment of intents to networks is handled by IntentNetworkGraphFactory
+ * (ambient) — these foreground tools only manage network and membership lifecycle.
+ *
+ * ## Scope enforcement
+ *
+ * In network-scoped chats, all tools validate that the requested networkId matches
+ * the scoped network.  Cross-scope mutations are rejected with a clear error.
+ *
+ * ## Onboarding ranking
+ *
+ * `read_networks` includes an onboarding-only `orderedNetworkIds` list when
+ * `context.isOnboarding` is true and public networks are available.  Ranking is
+ * performed by `NetworkRecommender` (ambient LLM agent) or a `deps.networkRanker`
+ * override, with graceful degradation if ranking fails.
+ *
+ * IND-546: canonical home — previously network/network.tools.ts.
+ */
+export declare function createNetworkTools(defineTool: DefineTool, deps: NetworkToolDeps): readonly [any, any, any, any, any, any, any];