@indexnetwork/protocol 14.3.2-rc.477.1 → 17.0.0-rc.479.1

package/dist/intents/application/intent.graph.execute.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Intent graph, stage 4 and the read fast path.
+ */
+import { ExecutionResult } from "../domain/intent.state.js";
+import { type IntentGraphDeps, type IntentState } from "./intent.graph.shared.js";
+/**
+ * Node 4: Executor
+ * Executes reconciler actions against the database.
+ */
+export declare function executorNode(state: IntentState, deps: IntentGraphDeps): Promise<{
+    executionResults: ExecutionResult[];
+}>;
+/**
+ * Node: Query
+ * Fast-path read node — fetches intents from DB based on scope.
+ * Handles: global user intents, network-scoped (all or filtered by user).
+ * No LLM calls; no inference/verification/reconciliation.
+ */
+export declare function queryNode(state: IntentState, deps: IntentGraphDeps): Promise<{
+    readResult: {
+        count: number;
+        intents: never[];
+        message: string;
+        networkId?: undefined;
+    };
+} | {
+    readResult: {
+        count: number;
+        intents: {
+            id: string;
+            description: string;
+            summary: string | null;
+            createdAt: Date;
+        }[];
+        message?: undefined;
+        networkId?: undefined;
+    };
+} | {
+    readResult: {
+        count: number;
+        intents: never[];
+        message: string;
+        networkId: string;
+    };
+} | {
+    readResult: {
+        count: number;
+        networkId: string;
+        intents: {
+            id: string;
+            description: string;
+            summary: string | null;
+            createdAt: Date;
+            userId: string;
+            userName: string | null;
+        }[];
+        message?: undefined;
+    };
+}>;

package/dist/intents/application/intent.graph.execute.js

@@ -0,0 +1,301 @@
+/**
+ * Intent graph, stage 4 and the read fast path.
+ */
+import { normalizeIntentDescription } from "../domain/intent.proposal.js";
+import { timed } from "../../shared/observability/performance.js";
+import { enforceIntentActionBoundary, generateIntentEmbedding, logger, toSpeechActType } from "./intent.graph.shared.js";
+/**
+ * Node 4: Executor
+ * Executes reconciler actions against the database.
+ */
+export async function executorNode(state, deps) {
+    return timed("IntentGraph.executor", async () => {
+        const actions = enforceIntentActionBoundary(state.operationMode, state.targetIntentIds, state.actions ?? []);
+        if (actions.length === 0) {
+            return { executionResults: [] };
+        }
+        logger.verbose('Executing actions', { count: actions.length });
+        const results = [];
+        const scopeEnvelope = state.scopeType && state.scopeId
+            ? { scopeType: state.scopeType, scopeId: state.scopeId }
+            : {};
+        const verifiedIntentByPayload = new Map();
+        for (const verifiedIntent of state.verifiedIntents) {
+            verifiedIntentByPayload.set(verifiedIntent.description, verifiedIntent);
+            verifiedIntentByPayload.set(normalizeIntentDescription(verifiedIntent.description), verifiedIntent);
+        }
+        for (const action of actions) {
+            const actionType = action.type.toLowerCase();
+            try {
+                if (actionType === 'create') {
+                    const createAction = action;
+                    const sanitizedPayload = normalizeIntentDescription(createAction.payload);
+                    const matchedVerifiedIntent = verifiedIntentByPayload.get(createAction.payload) ||
+                        verifiedIntentByPayload.get(sanitizedPayload);
+                    // Generate embedding for the intent payload
+                    const flatEmbedding = await generateIntentEmbedding(deps, sanitizedPayload);
+                    const created = await deps.database.createIntent({
+                        userId: state.userId,
+                        payload: sanitizedPayload,
+                        confidence: createAction.score ? createAction.score / 100 : 1.0,
+                        inferenceType: 'explicit',
+                        sourceType: 'discovery_form',
+                        embedding: flatEmbedding,
+                        semanticEntropy: createAction.semanticEntropy ??
+                            matchedVerifiedIntent?.verification?.semantic_entropy ??
+                            null,
+                        referentialAnchor: createAction.referentialAnchor ??
+                            matchedVerifiedIntent?.verification?.referential_anchor ??
+                            null,
+                        felicityAuthority: matchedVerifiedIntent?.verification?.felicity_scores.authority ?? null,
+                        felicitySincerity: matchedVerifiedIntent?.verification?.felicity_scores.sincerity ?? null,
+                        felicityClarity: matchedVerifiedIntent?.verification?.felicity_scores.clarity ?? null,
+                        intentMode: createAction.intentMode ?? null,
+                        speechActType: toSpeechActType(matchedVerifiedIntent?.verification?.classification),
+                    });
+                    results.push({ actionType: 'create', success: true, intentId: created.id, payload: sanitizedPayload });
+                    logger.verbose('Created intent', { intentId: created.id });
+                    deps.intentQueue?.addGenerateHydeJob({
+                        intentId: created.id,
+                        userId: state.userId,
+                        ...scopeEnvelope,
+                    }).catch((err) => logger.error('Failed to enqueue intent HyDE job', { intentId: created.id, error: err }));
+                    if (deps.questionerEnqueue) {
+                        const userContext = (await deps.database.getUserContext(state.userId, null))?.text ?? '';
+                        deps.questionerEnqueue({
+                            mode: 'intent',
+                            userId: state.userId,
+                            sourceType: 'intent',
+                            sourceId: created.id,
+                            ...scopeEnvelope,
+                            context: {
+                                intentId: created.id,
+                                payload: sanitizedPayload,
+                                userContext,
+                            },
+                        }).catch((err) => logger.error('Failed to enqueue intent question generation', { intentId: created.id, error: err }));
+                    }
+                }
+                else if (actionType === 'update') {
+                    const updateAction = action;
+                    const sanitizedPayload = normalizeIntentDescription(updateAction.payload);
+                    const matchedVerifiedIntent = verifiedIntentByPayload.get(updateAction.payload) ||
+                        verifiedIntentByPayload.get(sanitizedPayload);
+                    // Regenerate embedding for the updated payload
+                    const flatEmbedding = await generateIntentEmbedding(deps, sanitizedPayload, updateAction.id);
+                    const updated = await deps.database.updateIntent(updateAction.id, {
+                        payload: sanitizedPayload,
+                        embedding: flatEmbedding,
+                        semanticEntropy: matchedVerifiedIntent?.verification?.semantic_entropy ??
+                            null,
+                        referentialAnchor: matchedVerifiedIntent?.verification?.referential_anchor ??
+                            null,
+                        felicityAuthority: matchedVerifiedIntent?.verification?.felicity_scores.authority ?? null,
+                        felicitySincerity: matchedVerifiedIntent?.verification?.felicity_scores.sincerity ?? null,
+                        felicityClarity: matchedVerifiedIntent?.verification?.felicity_scores.clarity ?? null,
+                        intentMode: updateAction.intentMode ?? null,
+                        speechActType: toSpeechActType(matchedVerifiedIntent?.verification?.classification),
+                        ...(state.expectedIntentFingerprint !== undefined ? {
+                            expectedIntentFingerprint: state.expectedIntentFingerprint,
+                            expectedIntentUserId: state.userId,
+                        } : {}),
+                    });
+                    results.push({
+                        actionType: 'update',
+                        success: !!updated,
+                        intentId: updateAction.id,
+                        payload: sanitizedPayload,
+                        error: updated ? undefined : 'Intent not found'
+                    });
+                    logger.verbose('Updated intent', { intentId: updateAction.id });
+                    if (updated) {
+                        deps.intentQueue?.addGenerateHydeJob({
+                            intentId: updateAction.id,
+                            userId: state.userId,
+                            ...scopeEnvelope,
+                        }).catch((err) => logger.error('Failed to enqueue intent HyDE job', { intentId: updateAction.id, error: err }));
+                    }
+                }
+                else if (actionType === 'expire') {
+                    const expireAction = action;
+                    const result = await deps.database.archiveIntent(expireAction.id);
+                    results.push({
+                        actionType: 'expire',
+                        success: result.success,
+                        intentId: expireAction.id,
+                        error: result.error
+                    });
+                    logger.verbose('Archived intent', { intentId: expireAction.id });
+                    if (result.success) {
+                        deps.intentQueue?.addDeleteHydeJob({ intentId: expireAction.id }).catch((err) => logger.error('Failed to enqueue intent HyDE delete job', { intentId: expireAction.id, error: err }));
+                    }
+                }
+            }
+            catch (error) {
+                logger.error('Failed to execute action', { actionType: action.type, error });
+                results.push({
+                    actionType,
+                    success: false,
+                    intentId: 'id' in action ? action.id : undefined,
+                    error: error instanceof Error ? error.message : 'Unknown error'
+                });
+            }
+        }
+        return { executionResults: results };
+    });
+}
+/**
+ * Node: Query
+ * Fast-path read node — fetches intents from DB based on scope.
+ * Handles: global user intents, network-scoped (all or filtered by user).
+ * No LLM calls; no inference/verification/reconciliation.
+ */
+export async function queryNode(state, deps) {
+    return timed("IntentGraph.query", async () => {
+        logger.verbose("Starting query (read mode)", {
+            userId: state.userId,
+            networkId: state.networkId,
+            queryUserId: state.queryUserId,
+            allUserIntents: state.allUserIntents,
+        });
+        try {
+            // Scope-aware default: caller's intents across all reachable networks.
+            // Triggered when the tool layer passed indexScope and did not pick a
+            // specific networkId or queryUserId — i.e. "my intents" in a chat
+            // where the agent's reach is more than one index.
+            if (!state.queryUserId &&
+                !state.networkId &&
+                state.indexScope &&
+                state.indexScope.length > 0) {
+                const intents = await deps.database.getActiveIntentsAcrossIndexes(state.userId, state.indexScope);
+                if (intents.length === 0) {
+                    return {
+                        readResult: {
+                            count: 0,
+                            intents: [],
+                            message: "You don't have any active intents yet. Share what you're looking for.",
+                        },
+                    };
+                }
+                return {
+                    readResult: {
+                        count: intents.length,
+                        intents: intents.map((i) => ({
+                            id: i.id,
+                            description: i.payload,
+                            summary: i.summary,
+                            createdAt: i.createdAt,
+                        })),
+                    },
+                };
+            }
+            // When allUserIntents is true, ignore network scope and return all
+            const effectiveIndexId = state.allUserIntents ? undefined : state.networkId;
+            if (effectiveIndexId) {
+                // Verify membership
+                const isMember = await deps.database.isNetworkMember(effectiveIndexId, state.userId);
+                if (!isMember) {
+                    return {
+                        readResult: {
+                            count: 0,
+                            intents: [],
+                            message: "Index not found or you are not a member.",
+                        },
+                    };
+                }
+                // Network-scoped read
+                if (!state.queryUserId) {
+                    // All intents in the index (any member can see)
+                    const intents = await deps.database.getNetworkIntentsForMember(effectiveIndexId, state.userId, { limit: 50, offset: 0 });
+                    if (intents.length === 0) {
+                        return {
+                            readResult: {
+                                count: 0,
+                                intents: [],
+                                message: "No intents in this network yet.",
+                                networkId: effectiveIndexId,
+                            },
+                        };
+                    }
+                    return {
+                        readResult: {
+                            count: intents.length,
+                            networkId: effectiveIndexId,
+                            intents: intents.map((i) => ({
+                                id: i.id,
+                                description: i.payload,
+                                summary: i.summary,
+                                createdAt: i.createdAt,
+                                userId: i.userId,
+                                userName: i.userName,
+                            })),
+                        },
+                    };
+                }
+                // Specific user's intents in the index
+                const effectiveUserId = state.queryUserId;
+                const intents = await deps.database.getIntentsInIndexForMember(effectiveUserId, effectiveIndexId);
+                if (intents.length === 0) {
+                    return {
+                        readResult: {
+                            count: 0,
+                            intents: [],
+                            message: effectiveUserId === state.userId
+                                ? "You don't have any intents in this network yet."
+                                : "No intents for that user in this network.",
+                            networkId: effectiveIndexId,
+                        },
+                    };
+                }
+                const user = await deps.database.getUser(effectiveUserId);
+                const userName = user?.name ?? null;
+                return {
+                    readResult: {
+                        count: intents.length,
+                        networkId: effectiveIndexId,
+                        intents: intents.map((i) => ({
+                            id: i.id,
+                            description: i.payload,
+                            summary: i.summary,
+                            createdAt: i.createdAt,
+                            userId: effectiveUserId,
+                            userName,
+                        })),
+                    },
+                };
+            }
+            // Global (no network scope): return user's own active intents
+            const intents = await deps.database.getActiveIntents(state.userId);
+            if (intents.length === 0) {
+                return {
+                    readResult: {
+                        count: 0,
+                        intents: [],
+                        message: "You don't have any active intents yet. Share what you're looking for.",
+                    },
+                };
+            }
+            return {
+                readResult: {
+                    count: intents.length,
+                    intents: intents.map((i) => ({
+                        id: i.id,
+                        description: i.payload,
+                        summary: i.summary,
+                        createdAt: i.createdAt,
+                    })),
+                },
+            };
+        }
+        catch (err) {
+            logger.error("Query node failed", { error: err });
+            return {
+                readResult: {
+                    count: 0,
+                    intents: [],
+                    message: "Failed to fetch intents. Please try again.",
+                },
+            };
+        }
+    });
+}

package/dist/intents/application/intent.graph.infer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Intent graph, stages 0-1: load the user's signals, then infer new ones.
+ */
+import type { DebugMetaAgent } from "../../agents/index.js";
+import { type IntentGraphDeps, type IntentState } from "./intent.graph.shared.js";
+/**
+ * Node 0: Prep
+ * Always fetches ALL of the user's active intents from the DB via getActiveIntents(userId).
+ * This ensures reconciliation can detect duplicates and modifications globally,
+ * regardless of network scope.
+ */
+export declare function prepNode(state: IntentState, deps: IntentGraphDeps): Promise<{
+    error: string;
+    activeIntents?: undefined;
+    activeIntentIds?: undefined;
+    trace?: undefined;
+} | {
+    activeIntents: string;
+    activeIntentIds: string[];
+    trace: {
+        node: string;
+        detail: string;
+    }[];
+    error?: undefined;
+}>;
+/**
+ * Node 1: Inference
+ * Extracts intents from raw content.
+ * Phase 4: Uses operation mode to control behavior and determine if node should execute.
+ * Phase 5: Passes conversation context for anaphoric resolution.
+ */
+export declare function inferenceNode(state: IntentState, deps: IntentGraphDeps): Promise<{
+    inferredIntents: {
+        reasoning: string;
+        type: "goal" | "tombstone";
+        confidence: "low" | "medium" | "high";
+        description: string;
+    }[];
+    agentTimings: DebugMetaAgent[];
+    trace: {
+        node: string;
+        detail: string;
+    }[];
+}>;

package/dist/intents/application/intent.graph.infer.js

@@ -0,0 +1,97 @@
+/**
+ * Intent graph, stages 0-1: load the user's signals, then infer new ones.
+ */
+import { timed } from "../../shared/observability/performance.js";
+import { requestContext } from "../../shared/observability/request-context.js";
+import { logger } from "./intent.graph.shared.js";
+/**
+ * Node 0: Prep
+ * Always fetches ALL of the user's active intents from the DB via getActiveIntents(userId).
+ * This ensures reconciliation can detect duplicates and modifications globally,
+ * regardless of network scope.
+ */
+export async function prepNode(state, deps) {
+    return timed("IntentGraph.prep", async () => {
+        logger.verbose("Starting preparation phase", {
+            operationMode: state.operationMode,
+            hasContent: !!state.inputContent,
+            targetIntentIds: state.targetIntentIds,
+            networkId: state.networkId,
+        });
+        // Gate: write operations require an existing profile
+        if (state.operationMode !== 'read') {
+            const profile = await deps.database.getProfile(state.userId);
+            if (!profile) {
+                const msg = "You need to create a profile before creating intents. Please set up your profile first.";
+                logger.error("Prep failed: no profile for user", { userId: state.userId });
+                return { error: msg };
+            }
+        }
+        const activeIntents = await deps.database.getActiveIntents(state.userId);
+        const formattedActiveIntents = activeIntents
+            .map(i => `ID: ${i.id}, Description: ${i.payload}, Summary: ${i.summary || 'N/A'}`)
+            .join('\n') || "No active intents.";
+        logger.verbose("Fetched active intents", {
+            count: activeIntents.length,
+            operationMode: state.operationMode
+        });
+        return {
+            activeIntents: formattedActiveIntents,
+            activeIntentIds: activeIntents.map((intent) => intent.id),
+            trace: [{
+                    node: "prep",
+                    detail: `Fetched ${activeIntents.length} active intent(s)`,
+                }],
+        };
+    });
+}
+/**
+ * Node 1: Inference
+ * Extracts intents from raw content.
+ * Phase 4: Uses operation mode to control behavior and determine if node should execute.
+ * Phase 5: Passes conversation context for anaphoric resolution.
+ */
+export async function inferenceNode(state, deps) {
+    return timed("IntentGraph.inference", async () => {
+        logger.verbose("Starting inference", {
+            operationMode: state.operationMode,
+            hasContent: !!state.inputContent,
+            contentPreview: state.inputContent?.substring(0, 50),
+            hasConversationContext: !!state.conversationContext,
+            conversationMessagesCount: state.conversationContext?.length || 0
+        });
+        const agentTimingsAccum = [];
+        // Phase 4: Control profile fallback based on operation mode
+        // Only allow for create operations without explicit content
+        const allowProfileFallback = state.operationMode === 'create' && !state.inputContent;
+        // Cast operationMode: 'read' and 'propose' map to 'create' for the deps.inferrer
+        // (inference node is never called in read mode; propose behaves like create for inference)
+        const inferrerMode = (state.operationMode === 'read' || state.operationMode === 'propose') ? 'create' : state.operationMode;
+        const _traceEmitterInferrer = requestContext.getStore()?.traceEmitter;
+        const inferrerStart = Date.now();
+        _traceEmitterInferrer?.({ type: "agent_start", name: "intent-inferrer" });
+        const result = await deps.inferrer.invoke(state.inputContent || null, state.userProfile, {
+            allowProfileFallback,
+            operationMode: inferrerMode,
+            conversationContext: state.conversationContext // Phase 5: Pass conversation history
+        });
+        agentTimingsAccum.push({ name: 'intent.inferrer', durationMs: Date.now() - inferrerStart });
+        _traceEmitterInferrer?.({ type: "agent_end", name: "intent-inferrer", durationMs: Date.now() - inferrerStart, summary: result.intents.length > 0 ? `Extracted ${result.intents.length} intent(s)` : "intent-inferrer completed" });
+        logger.verbose("Inference complete", {
+            inferredCount: result.intents.length,
+            operationMode: state.operationMode
+        });
+        const descriptions = result.intents.map(i => i.description).slice(0, 3);
+        const truncated = result.intents.length > 3 ? `... +${result.intents.length - 3} more` : "";
+        return {
+            inferredIntents: result.intents,
+            agentTimings: agentTimingsAccum,
+            trace: [{
+                    node: "inference",
+                    detail: result.intents.length === 0
+                        ? "No intents extracted"
+                        : `Extracted ${result.intents.length}: ${descriptions.map(d => `"${d.slice(0, 50)}${d.length > 50 ? '...' : ''}"`).join(", ")}${truncated}`,
+                }],
+        };
+    });
+}