@indexnetwork/protocol 22.0.0-rc.498.1 → 64.0.0-rc.604.2

package/dist/intents/intent.tools.js

@@ -1,808 +0,0 @@
-import { z } from "zod";
-import { IntentClarifier } from "./intent.clarifier.js";
-import { DEFAULT_SPECIFICITY_WARNING, normalizeIntentDescription } from "./intent.proposal.js";
-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, focusedIntentId, focusedNetworkId, focusedNetworkLabel } from "../shared/agent/tool.scope.js";
-const logger = protocolLogger("ChatTools:Intent");
-let intentClarifier;
-function getIntentClarifier() {
-    intentClarifier ?? (intentClarifier = new IntentClarifier());
-    return intentClarifier;
-}
-async function buildTypedClarificationResult(params) {
-    const clarification = await getIntentClarifier().invoke(params.description, params.userProfile, params.activeIntentsContext ?? "");
-    if (!clarification.needsClarification)
-        return null;
-    return JSON.stringify({
-        success: false,
-        needsClarification: true,
-        underspecificationType: clarification.underspecificationType,
-        suggestedDescription: clarification.suggestedDescription,
-        clarificationMessage: clarification.clarificationMessage,
-        missingFields: [clarification.underspecificationType],
-        message: clarification.clarificationMessage,
-        debugSteps: params.debugSteps,
-    });
-}
-/** Replace the lazy clarifier in deterministic tool tests. */
-export function setIntentClarifierForTesting(clarifier) {
-    intentClarifier = clarifier ?? undefined;
-}
-/**
- * Sanitize JSON string for use inside a markdown code fence (```). Escapes backticks
- * so embedded ``` cannot close the fence prematurely.
- */
-function sanitizeJsonForCodeFence(json) {
-    return json.replace(/`/g, "\\u0060");
-}
-/** 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) {
-    const scopedNetworkId = focusedNetworkId(context);
-    if (!scopedNetworkId)
-        return null;
-    const isMember = await systemDb.isNetworkMember(scopedNetworkId, context.userId);
-    if (!isMember) {
-        return `This chat is scoped to ${focusedNetworkLabel(context)}. You are no longer a member of this community.`;
-    }
-    return null;
-}
-function buildApprovedProfileFallback(user) {
-    const bio = user?.intro?.trim();
-    if (!user || !bio)
-        return "";
-    return JSON.stringify({
-        userId: user.id,
-        identity: {
-            name: user.name ?? "",
-            bio,
-            location: user.location?.trim() ?? "",
-        },
-        narrative: { context: bio },
-        attributes: { skills: [], interests: [] },
-    });
-}
-function isBroadAttributiveIntent(intent) {
-    return intent.verification?.referential_breadth === "broad";
-}
-const NULL_LIKE_SPECIFICITY_WARNING_VALUES = new Set(["null", "undefined"]);
-function normalizeSpecificityWarning(value) {
-    const warning = value?.trim();
-    if (!warning)
-        return null;
-    return NULL_LIKE_SPECIFICITY_WARNING_VALUES.has(warning.toLowerCase()) ? null : warning;
-}
-function specificityWarningFor(intent) {
-    return normalizeSpecificityWarning(intent.verification?.specificity_warning) ?? DEFAULT_SPECIFICITY_WARNING;
-}
-/** Convert graph failures into an accurate, machine-readable update-tool error. */
-export function describeIntentUpdateFailure(result) {
-    const persistenceFailure = result.executionResults?.find((execution) => !execution.success);
-    if (persistenceFailure) {
-        return {
-            failureCategory: 'persistence_failure',
-            error: 'Intent update could not be persisted.',
-            ...(persistenceFailure.error ? { details: persistenceFailure.error } : {}),
-        };
-    }
-    const failure = result.validationFailures?.[0];
-    if (failure) {
-        const broadnessNote = failure.referentialBreadth === 'broad'
-            ? ' Referential breadth was recorded as a warning; it was not the blocking reason.'
-            : '';
-        return {
-            failureCategory: failure.category,
-            error: `${failure.message}${broadnessNote}`,
-            ...(failure.classification ? { details: `Speech act: ${failure.classification}.` } : {}),
-        };
-    }
-    return {
-        failureCategory: 'reconciliation_boundary',
-        error: 'Intent update produced no executable action after target-boundary enforcement.',
-    };
-}
-export function createIntentTools(defineTool, deps) {
-    const { graphs, userDb } = deps;
-    // ─────────────────────────────────────────────────────────────────────────────
-    // INTENT CRUD
-    // ─────────────────────────────────────────────────────────────────────────────
-    const readIntents = defineTool({
-        name: "read_intents",
-        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 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 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("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."),
-        }),
-        handler: async ({ context, query }) => {
-            const scopeErr = await ensureScopedMembership(context, deps.systemDb);
-            if (scopeErr)
-                return error(scopeErr);
-            // Distinguish "explicit network browse" from "implicit scope-aware read"
-            const scopedNetworkId = focusedNetworkId(context);
-            const scopedIntentId = focusedIntentId(context);
-            const scopedIndexLabel = focusedNetworkLabel(context);
-            const explicitNetworkId = query.networkId?.trim();
-            const explicitUserId = query.userId?.trim();
-            if (scopedIntentId && (explicitNetworkId || (explicitUserId && explicitUserId !== context.userId))) {
-                return error("This chat is scoped to one selected intent. Only that intent is available here.");
-            }
-            // Validate explicit networkId format
-            if (explicitNetworkId && !UUID_REGEX.test(explicitNetworkId)) {
-                return error("Invalid network ID format.");
-            }
-            // Strict scope enforcement: in a scoped chat, the only allowed explicit
-            // 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 ${scopedIndexLabel}. You can only read intents from members of this community.`);
-                }
-            }
-            // 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 (!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.");
-                }
-            }
-            // ── Choose the read mode ──
-            // 1. Explicit networkId (browse all members in that index) — pass networkId, optionally + queryUserId.
-            // 2. Explicit userId in a scoped chat — read that user's intents in the bound network.
-            // 3. Explicit userId in an unscoped chat — only self (cross-user rejected above); global "my intents".
-            // 4. Implicit (no explicit network/user) in scoped chat — pass indexScope, no networkId.
-            // 5. Implicit in unscoped chat — global getActiveIntents (caller's own).
-            const graphInput = {
-                userId: context.userId,
-                userProfile: "",
-                operationMode: 'read',
-            };
-            if (scopedIntentId) {
-                const intent = await deps.systemDb.getIntent(scopedIntentId);
-                if (!intent || intent.userId !== context.userId || intent.archivedAt) {
-                    return error("This selected intent is no longer available.");
-                }
-                return success({
-                    count: 1,
-                    totalCount: 1,
-                    intents: [{
-                            id: intent.id,
-                            description: intent.payload,
-                            summary: intent.summary,
-                            createdAt: intent.createdAt,
-                        }],
-                    scopeRestriction: {
-                        isScoped: true,
-                        scopedToIntent: scopedIntentId,
-                        message: "Results are restricted to the selected intent.",
-                    },
-                });
-            }
-            if (explicitNetworkId) {
-                graphInput.networkId = explicitNetworkId;
-                if (explicitUserId)
-                    graphInput.queryUserId = explicitUserId;
-            }
-            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 = scopedNetworkId;
-                graphInput.queryUserId = explicitUserId;
-            }
-            else if (explicitUserId) {
-                // Unscoped chat + userId: only allowed for self (others rejected above).
-                graphInput.queryUserId = explicitUserId;
-                graphInput.allUserIntents = true;
-            }
-            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.
-                graphInput.allUserIntents = true;
-            }
-            const _readIntentGraphStart = Date.now();
-            const result = await traceGraph("intent", () => invokeWithAbortSignal(graphs.intent, graphInput));
-            const _readIntentGraphMs = Date.now() - _readIntentGraphStart;
-            if (result.readResult) {
-                if (result.readResult.count === 0 && result.readResult.message && /not a member|Network not found/i.test(result.readResult.message)) {
-                    return error(result.readResult.message);
-                }
-                const shouldPaginate = query.limit !== undefined || query.page !== undefined;
-                if (shouldPaginate && Array.isArray(result.readResult.intents)) {
-                    const limit = query.limit ?? 20;
-                    const page = query.page ?? 1;
-                    const offset = (page - 1) * limit;
-                    const pagedIntents = result.readResult.intents.slice(offset, offset + limit);
-                    return success({
-                        ...result.readResult,
-                        count: pagedIntents.length,
-                        totalCount: result.readResult.intents.length,
-                        limit,
-                        page,
-                        totalPages: Math.ceil(result.readResult.intents.length / limit),
-                        intents: pagedIntents,
-                        _graphTimings: [{ name: 'intent', durationMs: _readIntentGraphMs, agents: result.agentTimings ?? [] }],
-                    });
-                }
-                return success({ ...result.readResult, _graphTimings: [{ name: 'intent', durationMs: _readIntentGraphMs, agents: result.agentTimings ?? [] }] });
-            }
-            return error("Failed to fetch intents.");
-        },
-    });
-    const createIntent = defineTool({
-        name: "create_intent",
-        description: "Creates a new intent (signal of interest/need) for the authenticated user. Intents drive the discovery engine — once created, " +
-            "the system automatically evaluates them against indexes the user belongs to, links them to relevant communities, and begins " +
-            "searching for matching opportunities (complementary intents from other users).\n\n" +
-            "**What to pass:** A clear, concept-based description of what the user is looking for (e.g. 'Looking for an AI/ML co-founder in Berlin', " +
-            "'Need a designer for a mobile app project'). If the user provided a URL, scrape it with scrape_url first and synthesize the content into a description.\n\n" +
-            "**What happens:** The system runs inference (extracting structured intents), verification (checking specificity and speech-act type), " +
-            "and durably stores an owner-scoped proposal containing the exact normalized description, optional network scope, and complete verifier output before returning a proposal widget. The intent itself is NOT yet persisted — the user must approve the proposal first.\n\n" +
-            "**Returns:** An intent_proposal code block that MUST be included verbatim in the response. The frontend renders it as an interactive " +
-            "card the user can approve or skip. On approval, the intent is persisted, indexed, and discovery begins.\n\n" +
-            "**Next steps after approval:** The intent is automatically linked to relevant indexes and becomes eligible for background matching. " +
-            "Background processing creates opportunities when matches are found; use list_opportunities only to review persisted results.\n\n" +
-            "**Specificity gate.** Before calling this tool, judge whether the description is concrete enough to be " +
-            "useful for matching. If the user says \"find a job\", \"meet people\", or \"learn something\", that's too " +
-            "vague — FIRST call read_user_contexts() + read_intents() to understand their context, THEN propose a " +
-            "refined version (\"Based on your background in X, did you mean 'Y'?\") and wait for confirmation before " +
-            "calling create_intent. Specific asks (\"senior UX design role at a tech company in Berlin\") can go " +
-            "directly to create_intent.\n\n" +
-            "**URL handling.** If the user pastes a URL describing the intent (e.g. a job posting), call scrape_url " +
-            "first with objective=\"Extract key details for an intent\", synthesize a conceptual description from the " +
-            "content, then call create_intent with the synthesis. Exception: profile URLs (LinkedIn, GitHub, X) passed " +
-            "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("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 }) => {
-            const scopeErr = await ensureScopedMembership(context, deps.systemDb);
-            if (scopeErr)
-                return error(scopeErr);
-            if (!query.description?.trim()) {
-                return error("Description is required.");
-            }
-            const scopedNetworkId = focusedNetworkId(context);
-            const scopedIntentId = focusedIntentId(context);
-            const scopedIndexLabel = focusedNetworkLabel(context);
-            if (scopedIntentId) {
-                return error("This chat is scoped to an existing selected intent. Update that intent instead of creating a different one here.");
-            }
-            // Strict scope enforcement
-            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 = 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();
-            const profileResult = await traceGraph("profile", () => invokeWithAbortSignal(graphs.profile, { userId: context.userId, operationMode: 'query' }));
-            const _profileGraphMs1 = Date.now() - _profileGraphStart1;
-            const latestUser = profileResult.profile ? undefined : typeof userDb.getUser === "function" ? await userDb.getUser() : context.user;
-            const approvedProfileFallback = profileResult.profile ? "" : buildApprovedProfileFallback(latestUser);
-            const userProfile = profileResult.profile ? JSON.stringify(profileResult.profile) : approvedProfileFallback;
-            // Run inference + verification only (propose mode — no DB persistence)
-            const _intentGraphStart1 = Date.now();
-            const result = await traceGraph("intent", () => invokeWithAbortSignal(graphs.intent, {
-                userId: context.userId,
-                userProfile,
-                inputContent: query.description,
-                operationMode: 'propose',
-                ...(effectiveIndexId ? { networkId: effectiveIndexId } : {}),
-                ...scopeEnvelope,
-            }));
-            const _intentGraphMs1 = Date.now() - _intentGraphStart1;
-            logger.debug("Intent graph propose response", { result });
-            const verified = result.verifiedIntents || [];
-            // MCP contexts have no interactive UI for proposal cards — default to auto-approve
-            const shouldAutoApprove = query.autoApprove ?? context.isMcp ?? false;
-            // Extract trace from graph and convert to debugSteps
-            const trace = Array.isArray(result.trace) ? result.trace : [];
-            const debugSteps = trace.map((t) => ({
-                step: t.node,
-                detail: t.detail,
-                ...(t.data ? { data: t.data } : {}),
-            }));
-            if (verified.length === 0) {
-                // Build a descriptive rejection reason from the trace so the ReACT agent
-                // can retry with a better description or ask the user for clarification.
-                // When inference produces 0 intents, propose mode exits before verification
-                // runs — so we check inference trace first.
-                const verificationTrace = debugSteps.find((s) => s.step === "verification");
-                const typedClarification = await buildTypedClarificationResult({
-                    description: query.description,
-                    userProfile,
-                    activeIntentsContext: result.activeIntents,
-                    debugSteps,
-                });
-                if (typedClarification)
-                    return typedClarification;
-                if (!verificationTrace) {
-                    const inferenceHint = debugSteps.find((s) => s.step === "inference")?.detail
-                        ?? "no intents extracted";
-                    return error(`No actionable intent was extracted (${inferenceHint}). ` +
-                        `Please retry with an explicit goal or ask the user what outcome they want.`, debugSteps);
-                }
-                const rejectionHint = verificationTrace.detail ?? "all candidate intents were filtered as invalid or too vague";
-                return error(`Intent verification failed (${rejectionHint}). ` +
-                    `The description may have been classified as a statement rather than a goal. ` +
-                    `Retry with an explicit goal or ask the user what outcome they want.`, debugSteps);
-            }
-            // ── Auto-approve path (for MCP agents or explicit opt-in) ──
-            if (shouldAutoApprove) {
-                const broadIntents = verified.filter(isBroadAttributiveIntent);
-                if (broadIntents.length > 0) {
-                    const typedClarification = await buildTypedClarificationResult({
-                        description: broadIntents[0].description,
-                        userProfile,
-                        activeIntentsContext: result.activeIntents,
-                        debugSteps,
-                    });
-                    if (typedClarification)
-                        return typedClarification;
-                    const first = broadIntents[0];
-                    const missing = first.verification?.missing_selectional_constraints ?? [];
-                    const missingHint = missing.length > 0
-                        ? ` Missing specifics: ${missing.map((m) => m.replace(/_/g, " ")).join(", ")}.`
-                        : "";
-                    return error(`${specificityWarningFor(first)}${missingHint} ` +
-                        `Please ask the user to clarify before creating this signal, or retry with a narrower description.`, debugSteps);
-                }
-                const createdIntents = [];
-                const createTimings = [];
-                for (const v of verified) {
-                    const _createGraphStart = Date.now();
-                    const createResult = await traceGraph("intent", () => invokeWithAbortSignal(graphs.intent, {
-                        userId: context.userId,
-                        userProfile,
-                        inputContent: v.description,
-                        operationMode: 'create',
-                        ...(effectiveIndexId ? { networkId: effectiveIndexId } : {}),
-                        ...scopeEnvelope,
-                    }));
-                    const _createGraphMs = Date.now() - _createGraphStart;
-                    createTimings.push({ name: 'intent-create', durationMs: _createGraphMs, agents: createResult.agentTimings ?? [] });
-                    const succeeded = createResult.executionResults?.some((r) => r.success);
-                    if (succeeded) {
-                        createdIntents.push({
-                            description: v.description,
-                            confidence: v.score != null ? Math.round(v.score * 100) / 100 : null,
-                            speechActType: v.verification?.classification ?? null,
-                        });
-                    }
-                }
-                return success({
-                    created: createdIntents.length > 0,
-                    count: createdIntents.length,
-                    intents: createdIntents,
-                    message: createdIntents.length > 0
-                        ? `Created ${createdIntents.length} intent${createdIntents.length > 1 ? 's' : ''} successfully. The system will automatically index them and begin searching for matching opportunities.`
-                        : 'Intent creation failed — the intents could not be persisted.',
-                    debugSteps,
-                    _graphTimings: [
-                        { name: 'enrichment', durationMs: _profileGraphMs1, agents: profileResult.agentTimings ?? [] },
-                        { name: 'intent-propose', durationMs: _intentGraphMs1, agents: result.agentTimings ?? [] },
-                        ...createTimings,
-                    ],
-                });
-            }
-            // ── Proposal path (for web chat with interactive cards) ──
-            // Persist complete verifier output before emitting any usable card.
-            if (!deps.intentProposalStore) {
-                return error("Verified intent proposals are unavailable because durable proposal storage is not configured.");
-            }
-            const proposals = [];
-            const proposalBlocks = [];
-            for (const v of verified) {
-                if (!v.verification) {
-                    return error("Intent verification produced no authoritative analysis; no proposal was created.", debugSteps);
-                }
-                const proposalId = crypto.randomUUID();
-                const normalizedDescription = normalizeIntentDescription(v.description);
-                const isBroad = isBroadAttributiveIntent(v);
-                proposals.push({
-                    proposalId,
-                    userId: context.userId,
-                    description: normalizedDescription,
-                    ...(effectiveIndexId ? { networkId: effectiveIndexId } : {}),
-                    analysis: {
-                        verifierOutput: v.verification,
-                        combinedScore: v.score ?? null,
-                    },
-                });
-                const data = {
-                    proposalId,
-                    description: normalizedDescription,
-                    ...(effectiveIndexId ? { networkId: effectiveIndexId } : {}),
-                    confidence: v.score != null ? Math.round(v.score * 100) / 100 : null,
-                    speechActType: v.verification?.classification ?? null,
-                    semanticEntropy: v.verification?.semantic_entropy ?? null,
-                    referentialBreadth: v.verification?.referential_breadth ?? null,
-                    missingSelectionalConstraints: v.verification?.missing_selectional_constraints ?? [],
-                    specificityWarning: isBroad ? specificityWarningFor(v) : normalizeSpecificityWarning(v.verification?.specificity_warning),
-                };
-                proposalBlocks.push("```intent_proposal\n" +
-                    sanitizeJsonForCodeFence(JSON.stringify(data)) +
-                    "\n```");
-            }
-            await deps.intentProposalStore.createProposals(proposals);
-            const blocksText = proposalBlocks.join("\n\n");
-            return success({
-                proposed: true,
-                count: verified.length,
-                message: `IMPORTANT: Include the following \`\`\`intent_proposal code blocks EXACTLY as-is in your response (they render as interactive cards for the user to approve or skip):\n\n${blocksText}`,
-                debugSteps,
-                _graphTimings: [
-                    { name: 'enrichment', durationMs: _profileGraphMs1, agents: profileResult.agentTimings ?? [] },
-                    { name: 'intent', durationMs: _intentGraphMs1, agents: result.agentTimings ?? [] },
-                ],
-            });
-        },
-    });
-    const updateIntent = defineTool({
-        name: "update_intent",
-        description: "Updates an existing intent's description. After updating, the system re-processes it through inference and verification, " +
-            "re-evaluates its index assignments, and makes the approved signal eligible for background matching.\n\n" +
-            "**When to use:** When the user wants to refine or change what they're looking for — e.g. narrowing scope, adding specificity, " +
-            "or pivoting to a different need. Prefer updating over delete+create to preserve the intent's history and existing index links.\n\n" +
-            "**Returns:** Updated `intentId` and `description`, plus a confirmation message. The intent's embeddings and index relevancy scores are recalculated automatically.",
-        querySchema: z.object({
-            intentId: z.string().describe("The UUID of the intent to update. Get this from read_intents results."),
-            description: z.string().describe("The updated description of what the user is looking for. Same guidelines as create_intent — should be clear and specific."),
-        }),
-        handler: async ({ context, query }) => {
-            const scopeErr = await ensureScopedMembership(context, deps.systemDb);
-            if (scopeErr)
-                return error(scopeErr);
-            const intentId = query.intentId?.trim() ?? "";
-            if (!UUID_REGEX.test(intentId)) {
-                return error("Invalid intent ID format.");
-            }
-            const scopedIntentId = focusedIntentId(context);
-            if (scopedIntentId && scopedIntentId !== intentId) {
-                return error("This chat is scoped to one selected intent. You can only update that intent here.");
-            }
-            // Ownership guard: caller must own the intent
-            const intent = await deps.systemDb.getIntent(intentId);
-            if (!intent || intent.userId !== context.userId) {
-                return error("Intent not found or you can only update your own intents.");
-            }
-            if (intent.archivedAt) {
-                return error("This intent is archived and cannot be updated. Create a new intent instead.");
-            }
-            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(scopedNetworkId)) {
-                    return error(`This chat is scoped to ${scopedIndexLabel}. You can only update intents linked to this community.`);
-                }
-            }
-            const _profileGraphStart2 = Date.now();
-            const profileResult = await traceGraph("profile", () => invokeWithAbortSignal(graphs.profile, { userId: context.userId, operationMode: 'query' }));
-            const _profileGraphMs2 = Date.now() - _profileGraphStart2;
-            const latestUser = profileResult.profile ? undefined : typeof userDb.getUser === "function" ? await userDb.getUser() : context.user;
-            const approvedProfileFallback = profileResult.profile ? "" : buildApprovedProfileFallback(latestUser);
-            const userProfile = profileResult.profile ? JSON.stringify(profileResult.profile) : approvedProfileFallback;
-            const _intentGraphStart2 = Date.now();
-            const result = await traceGraph("intent", () => invokeWithAbortSignal(graphs.intent, {
-                userId: context.userId,
-                userProfile,
-                operationMode: 'update',
-                inputContent: query.description,
-                targetIntentIds: [intentId],
-                ...(scopedNetworkId && { networkId: scopedNetworkId, scopeType: 'network', scopeId: scopedNetworkId }),
-            }));
-            const _intentGraphMs2 = Date.now() - _intentGraphStart2;
-            if (!result.executionResults?.some((r) => r.success)) {
-                return JSON.stringify({
-                    success: false,
-                    ...describeIntentUpdateFailure(result),
-                });
-            }
-            return success({
-                message: "Intent updated.",
-                intentId,
-                description: query.description,
-                _graphTimings: [
-                    { name: 'enrichment', durationMs: _profileGraphMs2, agents: profileResult.agentTimings ?? [] },
-                    { name: 'intent', durationMs: _intentGraphMs2, agents: result.agentTimings ?? [] },
-                ],
-            });
-        },
-    });
-    const deleteIntent = defineTool({
-        name: "delete_intent",
-        description: "Archives (soft-deletes) an intent, removing it from active discovery. The intent is not permanently deleted — it is marked as archived " +
-            "and no longer participates in opportunity matching or index evaluation.\n\n" +
-            "**When to use:** When the user's need has been fulfilled, is no longer relevant, or was created by mistake. " +
-            "If the user wants to change the description instead, use update_intent to preserve history.\n\n" +
-            "**Returns:** Confirmation that the intent was archived. Previously created opportunities from this intent remain but won't generate new ones.",
-        querySchema: z.object({
-            intentId: z.string().describe("The UUID of the intent to archive. Get this from read_intents results."),
-        }),
-        handler: async ({ context, query }) => {
-            const scopeErr = await ensureScopedMembership(context, deps.systemDb);
-            if (scopeErr)
-                return error(scopeErr);
-            const intentId = query.intentId?.trim() ?? "";
-            if (!UUID_REGEX.test(intentId)) {
-                return error("Invalid intent ID format.");
-            }
-            // Ownership guard: caller must own the intent
-            const intent = await deps.systemDb.getIntent(intentId);
-            if (!intent || intent.userId !== context.userId) {
-                return error("Intent not found or you can only delete your own intents.");
-            }
-            const scopedNetworkId = focusedNetworkId(context);
-            const scopedIntentId = focusedIntentId(context);
-            const scopedIndexLabel = focusedNetworkLabel(context);
-            if (scopedIntentId && scopedIntentId !== intentId) {
-                return error("This chat is scoped to one selected intent. You can only delete that intent here.");
-            }
-            // 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(scopedNetworkId)) {
-                    return error(`This chat is scoped to ${scopedIndexLabel}. You can only delete intents linked to this community.`);
-                }
-            }
-            const _deleteIntentGraphStart = Date.now();
-            const result = await traceGraph("intent", () => invokeWithAbortSignal(graphs.intent, {
-                userId: context.userId,
-                userProfile: "",
-                operationMode: 'delete',
-                targetIntentIds: [intentId],
-                ...(scopedNetworkId && { networkId: scopedNetworkId, scopeType: 'network', scopeId: scopedNetworkId }),
-            }));
-            const _deleteIntentGraphMs = Date.now() - _deleteIntentGraphStart;
-            if (result.executionResults?.some((r) => !r.success)) {
-                return error("Failed to delete intent.");
-            }
-            return success({
-                message: "Intent archived successfully.",
-                _graphTimings: [{ name: 'intent', durationMs: _deleteIntentGraphMs, agents: result.agentTimings ?? [] }],
-            });
-        },
-    });
-    // ─────────────────────────────────────────────────────────────────────────────
-    // INTENT–INDEX JUNCTION (link / list / unlink)
-    // ─────────────────────────────────────────────────────────────────────────────
-    const createIntentIndex = defineTool({
-        name: "create_intent_index",
-        description: "Manually links an intent to a network (community), making the approved signal eligible for background matching 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 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 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 scopedIntentId = focusedIntentId(context);
-            const scopedIndexLabel = focusedNetworkLabel(context);
-            const intentId = query.intentId?.trim() ?? "";
-            const networkId = query.networkId?.trim() || scopedNetworkId || "";
-            if (scopedIntentId && intentId !== scopedIntentId) {
-                return error("This chat is scoped to one selected intent. You can only link that intent here.");
-            }
-            if (!UUID_REGEX.test(intentId) || !UUID_REGEX.test(networkId)) {
-                return error("Invalid ID format. Both must be UUIDs.");
-            }
-            // 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, {
-                userId: context.userId,
-                networkId,
-                intentId,
-                operationMode: 'create',
-                skipEvaluation: true,
-            }));
-            const _createIntentIndexGraphMs = Date.now() - _createIntentIndexGraphStart;
-            if (result.mutationResult) {
-                if (result.mutationResult.success) {
-                    const alreadyExisted = result.mutationResult.message?.includes('already in this network') ?? false;
-                    return success({
-                        created: !alreadyExisted,
-                        message: result.mutationResult.message,
-                        _graphTimings: [{ name: 'intent_network', durationMs: _createIntentIndexGraphMs, agents: result.agentTimings ?? [] }],
-                    });
-                }
-                return error(result.mutationResult.error || "Failed to link intent to network.");
-            }
-            return error("Failed to link intent to network.");
-        },
-    });
-    const readIntentIndexes = defineTool({
-        name: "read_intent_indexes",
-        description: "Reads the many-to-many links between intents and indexes. Use this to understand which intents are shared in which communities, " +
-            "and which indexes a specific intent belongs to.\n\n" +
-            "**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 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-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("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 scopedIntentId = focusedIntentId(context);
-            const scopedIndexLabel = focusedNetworkLabel(context);
-            const intentId = query.intentId?.trim() || scopedIntentId || undefined;
-            let networkId = query.networkId?.trim() || scopedNetworkId || undefined;
-            const queryUserId = query.userId?.trim() || undefined;
-            if (scopedIntentId && query.intentId?.trim() && query.intentId.trim() !== scopedIntentId) {
-                return error("This chat is scoped to one selected intent. You can only read links for that intent here.");
-            }
-            if (scopedIntentId && queryUserId && queryUserId !== context.userId) {
-                return error("This chat is scoped to one selected intent. Other users' intent links are not available here.");
-            }
-            if (intentId && !UUID_REGEX.test(intentId)) {
-                return error("Invalid intent ID format.");
-            }
-            if (networkId && !UUID_REGEX.test(networkId)) {
-                return error("Invalid network ID format.");
-            }
-            if (!intentId && !networkId) {
-                return error("Provide networkId or intentId.");
-            }
-            // 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 (scopedNetworkId) {
-                    // When scoped, only check if intent is linked to the scoped network
-                    networkId = scopedNetworkId;
-                }
-                else {
-                    // 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.");
-                }
-            }
-            const _readIntentIndexGraphStart = Date.now();
-            const result = await traceGraph("intent_network", () => invokeWithAbortSignal(graphs.intentIndex, {
-                userId: context.userId,
-                networkId,
-                intentId,
-                operationMode: 'read',
-                queryUserId,
-            }));
-            const _readIntentIndexGraphMs = Date.now() - _readIntentIndexGraphStart;
-            if (result.error) {
-                return error(result.error);
-            }
-            if (result.readResult) {
-                return success({ ...result.readResult, _graphTimings: [{ name: 'intent_network', durationMs: _readIntentIndexGraphMs, agents: result.agentTimings ?? [] }] });
-            }
-            return error("Failed to fetch intent-network links.");
-        },
-    });
-    const deleteIntentIndex = defineTool({
-        name: "delete_intent_index",
-        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 is no longer eligible for background matching 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 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 scopedIntentId = focusedIntentId(context);
-            const scopedIndexLabel = focusedNetworkLabel(context);
-            const intentId = query.intentId?.trim() ?? "";
-            const networkId = query.networkId?.trim() || scopedNetworkId || "";
-            if (scopedIntentId && intentId !== scopedIntentId) {
-                return error("This chat is scoped to one selected intent. You can only unlink that intent here.");
-            }
-            if (!UUID_REGEX.test(intentId) || !UUID_REGEX.test(networkId)) {
-                return error("Invalid ID format. Both must be UUIDs.");
-            }
-            // 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, {
-                userId: context.userId,
-                networkId,
-                intentId,
-                operationMode: 'delete',
-            }));
-            const _deleteIntentIndexGraphMs = Date.now() - _deleteIntentIndexGraphStart;
-            if (result.mutationResult) {
-                if (result.mutationResult.success) {
-                    return success({
-                        deleted: true,
-                        message: result.mutationResult.message,
-                        _graphTimings: [{ name: 'intent_network', durationMs: _deleteIntentIndexGraphMs, agents: result.agentTimings ?? [] }],
-                    });
-                }
-                return error(result.mutationResult.error || "Failed to unlink.");
-            }
-            return error("Failed to unlink intent from network.");
-        },
-    });
-    const searchIntents = defineTool({
-        name: "search_intents",
-        description: "Text-searches the authenticated user's own active signals by description. Case-insensitive substring " +
-            "match over the signal's payload and summary. Use when the user references a past signal they wrote " +
-            '("find my signal about React mentorship") or wants to audit what they\'ve posted.\n\n' +
-            "Approved signals are matched in the background. Use list_opportunities only to review persisted opportunities after background matching has produced them.\n\n" +
-            "**Returns:** `intents: [{ id, payload, summary, createdAt }]`, most recent first, up to `limit` (default 25).",
-        querySchema: z.object({
-            query: z.string().min(1).describe("Text to match against payload and summary (case-insensitive)."),
-            limit: z
-                .number()
-                .int()
-                .positive()
-                .max(100)
-                .optional()
-                .describe("Maximum intents to return (default 25, max 100)."),
-        }),
-        handler: async ({ context, query }) => {
-            const rows = await userDb.searchOwnIntents(query.query, query.limit ?? 25);
-            logger.verbose("search_intents", { userId: context.userId, query: query.query, matched: rows.length });
-            return success({ intents: rows });
-        },
-    });
-    return [readIntents, createIntent, updateIntent, deleteIntent, createIntentIndex, readIntentIndexes, deleteIntentIndex, searchIntents];
-}