@indexnetwork/protocol 22.0.0-rc.499.1 → 64.0.0

package/dist/contacts/contact.tools.js

@@ -1,108 +0,0 @@
-/**
- * contacts — createContactTools canonical implementation.
- *
- * Creates contact management tools for the chat agent. Enables listing,
- * removing, and searching the user's personal network.
- *
- * Contacts are established by accepting an opportunity — opportunity accept
- * and start-chat write the mutual `contact` memberships. There is no import or
- * manual-add path, and no ghost users: every contact is a real account.
- */
-import { z } from 'zod';
-import { success, error } from '../shared/agent/tool.helpers.js';
-import { protocolLogger } from '../shared/observability/protocol.logger.js';
-const logger = protocolLogger('ChatTools:Contact');
-/**
- * Creates contact management tools for the chat agent.
- * Enables listing, searching, and removing entries in the user's network.
- */
-export function createContactTools(defineTool, deps) {
-    const { contactService } = deps;
-    const list_contacts = defineTool({
-        name: 'list_contacts',
-        description: "Lists all contacts in the authenticated user's personal network. Contacts are people the user has " +
-            "accepted an opportunity with, stored as members of their personal network.\n\n" +
-            "**When to use:** To see who's in the user's network, find a contact's userId for other operations, " +
-            "or check if a specific person is already a contact.\n\n" +
-            "**Returns:** Array of contacts, each with userId (use with read_user_contexts), name, email, and avatar URL. " +
-            "Use read_user_contexts(userId) to get the full profile. " +
-            "Approved signals are matched in the background; list_opportunities only reviews persisted results.",
-        querySchema: z.object({
-            limit: z.number().optional().describe('Maximum number of contacts to return. Omit to return all contacts. Use for large networks to paginate results.'),
-        }),
-        handler: async ({ context, query }) => {
-            try {
-                let contacts = await contactService.listContacts(context.userId);
-                if (query.limit && query.limit > 0) {
-                    contacts = contacts.slice(0, query.limit);
-                }
-                return success({
-                    count: contacts.length,
-                    contacts: contacts.map(c => ({
-                        userId: c.userId,
-                        name: c.user.name,
-                        email: c.user.email,
-                        avatar: c.user.avatar,
-                    })),
-                });
-            }
-            catch (err) {
-                logger.error('Failed to list contacts', { err });
-                return error('Failed to list contacts. Please try again.');
-            }
-        },
-    });
-    const remove_contact = defineTool({
-        name: 'remove_contact',
-        description: "Removes a contact from the authenticated user's personal network. The contact relationship is deleted — " +
-            "the person is no longer a member of the user's personal network and their signals are no longer eligible for matching there.\n\n" +
-            "**When to use:** When the user wants to remove someone from their network (e.g. 'remove John from my contacts').\n\n" +
-            "**Note:** This only removes the contact relationship. If the contact is a real user (not a ghost), " +
-            "they still exist on the platform and their approved signals may remain eligible in shared networks.\n\n" +
-            "**Returns:** Confirmation that the contact was removed.",
-        querySchema: z.object({
-            contactUserId: z.string().describe('The userId of the contact to remove. Get this from list_contacts results.'),
-        }),
-        handler: async ({ context, query }) => {
-            try {
-                await contactService.removeContact(context.userId, query.contactUserId);
-                return success({ removed: true, message: 'Contact removed from your network.' });
-            }
-            catch (err) {
-                logger.error('Failed to remove contact', { err });
-                return error('Failed to remove contact. Please try again.');
-            }
-        },
-    });
-    const search_contacts = defineTool({
-        name: 'search_contacts',
-        description: "Searches the authenticated user's personal network by name or email (case-insensitive substring). " +
-            "Use when the user refers to a contact by partial name or email and you need their userId for another tool " +
-            "(e.g. read_user_contexts).\n\n" +
-            "**When to use:** Before list_contacts when the network is large — returns only matching contacts, bounded by limit.\n\n" +
-            "**Returns:** Array of matching contacts: userId, name, email, avatar.",
-        querySchema: z.object({
-            query: z.string().trim().min(1).describe('Free-text query matched against contact name and email (case-insensitive, substring).'),
-            limit: z.number().int().positive().max(100).optional().describe('Maximum rows to return. Defaults to 25.'),
-        }),
-        handler: async ({ context, query }) => {
-            try {
-                const rows = await contactService.searchContacts(context.userId, query.query, query.limit ?? 25);
-                return success({
-                    count: rows.length,
-                    contacts: rows.map(r => ({
-                        userId: r.contactId,
-                        name: r.name,
-                        email: r.email,
-                        avatar: r.avatar,
-                    })),
-                });
-            }
-            catch (err) {
-                logger.error('Failed to search contacts', { err });
-                return error('Failed to search contacts. Please try again.');
-            }
-        },
-    });
-    return [list_contacts, remove_contact, search_contacts];
-}

package/dist/contacts/contact.tools.port.d.ts

@@ -1,20 +0,0 @@
-/**
- * contacts — ContactToolDeps tool host port.
- *
- * Narrow port type consumed by createContactTools. The host provides a
- * ContactServiceAdapter.
- *
- * NOTE: This type is intentionally defined inline rather than derived from
- * ToolRegistryCompositionDeps, keeping the capability port independent from
- * the all-capability composition contract.
- *
- * Its shape remains structurally equivalent to the matching
- * ToolRegistryCompositionDeps fields.
- *
- * This root-level contract keeps the capability dependency surface compact.
- */
-import type { ContactServiceAdapter } from "./contact.repository.port.js";
-/** Host capabilities consumed by contact tools. */
-export type ContactToolDeps = {
-    contactService: ContactServiceAdapter;
-};

package/dist/contacts/contact.tools.port.js

@@ -1,16 +0,0 @@
-/**
- * contacts — ContactToolDeps tool host port.
- *
- * Narrow port type consumed by createContactTools. The host provides a
- * ContactServiceAdapter.
- *
- * NOTE: This type is intentionally defined inline rather than derived from
- * ToolRegistryCompositionDeps, keeping the capability port independent from
- * the all-capability composition contract.
- *
- * Its shape remains structurally equivalent to the matching
- * ToolRegistryCompositionDeps fields.
- *
- * This root-level contract keeps the capability dependency surface compact.
- */
-export {};

package/dist/contacts/contact.types.d.ts

@@ -1,24 +0,0 @@
-/**
- * contacts — pure contact entity value types.
- *
- * No application logic, no LLM calls, no cross-capability imports.
- *
- * Canonical contact types for the contacts capability.
- */
-/** Contact with user details, as returned by listContacts. */
-export interface ContactEntry {
-    userId: string;
-    user: {
-        id: string;
-        name: string;
-        email: string;
-        avatar: string | null;
-    };
-}
-/** Flat contact row returned by searchContacts. */
-export interface ContactSearchResult {
-    contactId: string;
-    name: string;
-    email: string;
-    avatar: string | null;
-}

package/dist/contacts/contact.types.js

@@ -1,8 +0,0 @@
-/**
- * contacts — pure contact entity value types.
- *
- * No application logic, no LLM calls, no cross-capability imports.
- *
- * Canonical contact types for the contacts capability.
- */
-export {};

package/dist/contexts/context.generator.d.ts

@@ -1,95 +0,0 @@
-/**
- * User Context Generator
- *
- * Synthesizes context paragraphs from user premises for storage in the
- * user_contexts table. Two scopes:
- *  - network-scoped: who the person is through the lens of a given network
- *  - global (networkId = null): a cohesive, network-agnostic identity paragraph
- *    that replaces the legacy synthesized user_profile projection.
- * Each scope supports cold-start (all premises at once) and incremental
- * (single premise change applied to an existing context).
- * Returns { text, embedding } for storage.
- */
-import type { EmbeddingGenerator } from "../shared/interfaces/embedder.interface.js";
-/** Input for cold-start context generation from a full set of premises. */
-export interface UserContextInput {
-    premises: Array<{
-        text: string;
-    }>;
-    networkPrompt: string | null;
-    networkTitle: string;
-}
-/** Input for incremental context update from a single premise change. */
-export interface IncrementalContextInput {
-    currentContext: string;
-    changeType: 'added' | 'updated' | 'retracted' | 'expired';
-    premiseText: string;
-    previousPremiseText?: string;
-    networkPrompt: string | null;
-    networkTitle: string;
-}
-/** Input for cold-start global (network-agnostic) context generation. */
-export interface GlobalContextInput {
-    premises: Array<{
-        text: string;
-    }>;
-}
-/** Input for incremental global context update from a single premise change. */
-export interface GlobalIncrementalContextInput {
-    currentContext: string;
-    changeType: 'added' | 'updated' | 'retracted' | 'expired';
-    premiseText: string;
-    previousPremiseText?: string;
-}
-/** Generated context paragraph with its embedding vector. */
-export interface UserContextResult {
-    text: string;
-    embedding: number[];
-}
-/**
- * Generates network-scoped context paragraphs from user premises.
- * Uses LLM synthesis to produce focused context and an embedding vector.
- */
-export declare class UserContextGenerator {
-    private embeddingGenerator;
-    private model;
-    constructor(embeddingGenerator: EmbeddingGenerator);
-    /**
-     * Generate a context paragraph from the full set of premises (cold-start).
-     *
-     * @param input - Premises, network prompt, and network title
-     * @returns Synthesized context text with embedding vector
-     */
-    generateColdStart(input: UserContextInput): Promise<UserContextResult>;
-    /**
-     * Update an existing context paragraph after a single premise change.
-     *
-     * @param input - Current context, change details, network metadata
-     * @returns Updated context text with embedding vector
-     */
-    generateIncremental(input: IncrementalContextInput): Promise<UserContextResult>;
-    /**
-     * Generate a global (network-agnostic) identity paragraph from the full set
-     * of premises (cold-start). This is the profile-replacing projection stored
-     * as the user's global user_context row (networkId = null).
-     *
-     * @param input - The user's active premises
-     * @returns Synthesized global identity text with embedding vector
-     */
-    generateGlobalColdStart(input: GlobalContextInput): Promise<UserContextResult>;
-    /**
-     * Update the global identity paragraph after a single premise change.
-     *
-     * @param input - Current global context and change details
-     * @returns Updated global identity text with embedding vector
-     */
-    generateGlobalIncremental(input: GlobalIncrementalContextInput): Promise<UserContextResult>;
-    /** Normalize an LLM message content into a plain string. */
-    private extractText;
-    /** Format the network context header for LLM prompts. */
-    private formatNetworkContext;
-    /** Describe the premise change for the incremental prompt. */
-    private describeChange;
-    /** Generate embedding from text, normalizing the return type. */
-    private embed;
-}

package/dist/contexts/context.generator.js

@@ -1,127 +0,0 @@
-/**
- * User Context Generator
- *
- * Synthesizes context paragraphs from user premises for storage in the
- * user_contexts table. Two scopes:
- *  - network-scoped: who the person is through the lens of a given network
- *  - global (networkId = null): a cohesive, network-agnostic identity paragraph
- *    that replaces the legacy synthesized user_profile projection.
- * Each scope supports cold-start (all premises at once) and incremental
- * (single premise change applied to an existing context).
- * Returns { text, embedding } for storage.
- */
-import { HumanMessage, SystemMessage } from "@langchain/core/messages";
-import { createResilientModel } from "../shared/agent/model.config.js";
-import { getAbortSignalConfig, invokeWithAbortSignal } from "../shared/agent/model-signal.js";
-const COLD_START_SYSTEM_PROMPT = `You synthesize user context paragraphs for community matching. Given a list of premises (atomic facts about a person) and a network description, write a focused paragraph (3-6 sentences) that captures who this person is through the lens of that network's purpose. Highlight what is most relevant to the network. Write in third person. Be specific and concrete, not generic.`;
-const INCREMENTAL_SYSTEM_PROMPT = `You maintain user context paragraphs for community matching. You will receive the current context paragraph, a change that occurred, and the network description. Update the context paragraph to reflect the change while preserving all other information. Keep the same style: 3-6 sentences, third person, specific and concrete. For retractions/expirations, remove the relevant information. For additions/updates, integrate the new information naturally.`;
-const GLOBAL_COLD_START_SYSTEM_PROMPT = `You synthesize a person's global identity profile from premises (atomic facts about them). Write a cohesive paragraph (4-8 sentences) capturing who this person is overall — their identity, work, expertise, and interests — independent of any single community or network. This is their canonical self-description, not lensed toward any particular purpose. Write in third person. Be specific and concrete, not generic. Do not invent facts beyond the premises.`;
-const GLOBAL_INCREMENTAL_SYSTEM_PROMPT = `You maintain a person's global identity profile. You will receive the current profile paragraph and a change that occurred. Update the paragraph to reflect the change while preserving all other information. Keep the same style: 4-8 sentences, third person, specific and concrete, network-agnostic. For retractions/expirations, remove the relevant information. For additions/updates, integrate the new information naturally.`;
-/**
- * Generates network-scoped context paragraphs from user premises.
- * Uses LLM synthesis to produce focused context and an embedding vector.
- */
-export class UserContextGenerator {
-    constructor(embeddingGenerator) {
-        this.embeddingGenerator = embeddingGenerator;
-        this.model = createResilientModel('userContextGenerator');
-    }
-    /**
-     * Generate a context paragraph from the full set of premises (cold-start).
-     *
-     * @param input - Premises, network prompt, and network title
-     * @returns Synthesized context text with embedding vector
-     */
-    async generateColdStart(input) {
-        const premiseBlock = input.premises.map(p => `- ${p.text}`).join('\n');
-        const networkContext = this.formatNetworkContext(input.networkPrompt, input.networkTitle);
-        const response = await invokeWithAbortSignal(this.model, [
-            new SystemMessage(COLD_START_SYSTEM_PROMPT),
-            new HumanMessage(`${networkContext}\n\nPremises:\n${premiseBlock}\n\nWrite a focused context paragraph for this person in this network.`),
-        ]);
-        const text = this.extractText(response.content);
-        const embedding = await this.embed(text);
-        return { text, embedding };
-    }
-    /**
-     * Update an existing context paragraph after a single premise change.
-     *
-     * @param input - Current context, change details, network metadata
-     * @returns Updated context text with embedding vector
-     */
-    async generateIncremental(input) {
-        const networkContext = this.formatNetworkContext(input.networkPrompt, input.networkTitle);
-        const changeDescription = this.describeChange(input);
-        const response = await invokeWithAbortSignal(this.model, [
-            new SystemMessage(INCREMENTAL_SYSTEM_PROMPT),
-            new HumanMessage(`${networkContext}\n\nCurrent context:\n${input.currentContext}\n\nChange:\n${changeDescription}\n\nWrite the updated context paragraph.`),
-        ]);
-        const text = this.extractText(response.content);
-        const embedding = await this.embed(text);
-        return { text, embedding };
-    }
-    /**
-     * Generate a global (network-agnostic) identity paragraph from the full set
-     * of premises (cold-start). This is the profile-replacing projection stored
-     * as the user's global user_context row (networkId = null).
-     *
-     * @param input - The user's active premises
-     * @returns Synthesized global identity text with embedding vector
-     */
-    async generateGlobalColdStart(input) {
-        const premiseBlock = input.premises.map(p => `- ${p.text}`).join('\n');
-        const response = await invokeWithAbortSignal(this.model, [
-            new SystemMessage(GLOBAL_COLD_START_SYSTEM_PROMPT),
-            new HumanMessage(`Premises:\n${premiseBlock}\n\nWrite a cohesive global identity paragraph for this person.`),
-        ]);
-        const text = this.extractText(response.content);
-        const embedding = await this.embed(text);
-        return { text, embedding };
-    }
-    /**
-     * Update the global identity paragraph after a single premise change.
-     *
-     * @param input - Current global context and change details
-     * @returns Updated global identity text with embedding vector
-     */
-    async generateGlobalIncremental(input) {
-        const changeDescription = this.describeChange(input);
-        const response = await invokeWithAbortSignal(this.model, [
-            new SystemMessage(GLOBAL_INCREMENTAL_SYSTEM_PROMPT),
-            new HumanMessage(`Current profile:\n${input.currentContext}\n\nChange:\n${changeDescription}\n\nWrite the updated global identity paragraph.`),
-        ]);
-        const text = this.extractText(response.content);
-        const embedding = await this.embed(text);
-        return { text, embedding };
-    }
-    /** Normalize an LLM message content into a plain string. */
-    extractText(content) {
-        return typeof content === 'string'
-            ? content
-            : String(content ?? '').trim();
-    }
-    /** Format the network context header for LLM prompts. */
-    formatNetworkContext(prompt, title) {
-        return prompt
-            ? `Network "${title}": ${prompt}`
-            : `Network: ${title}`;
-    }
-    /** Describe the premise change for the incremental prompt. */
-    describeChange(input) {
-        switch (input.changeType) {
-            case 'added':
-                return `A new fact was learned about this person:\n"${input.premiseText}"`;
-            case 'updated':
-                return `A fact was updated.\nOld: "${input.previousPremiseText}"\nNew: "${input.premiseText}"`;
-            case 'retracted':
-                return `A fact was retracted (no longer true):\n"${input.premiseText}"`;
-            case 'expired':
-                return `A fact has expired (time-bound, no longer current):\n"${input.premiseText}"`;
-        }
-    }
-    /** Generate embedding from text, normalizing the return type. */
-    async embed(text) {
-        const result = await this.embeddingGenerator.generate(text, undefined, getAbortSignalConfig());
-        return Array.isArray(result[0]) ? result[0] : result;
-    }
-}

package/dist/contexts/context.module.d.ts

@@ -1,13 +0,0 @@
-/**
- * contexts — the capability's sole cross-capability surface.
- *
- * Enrichment, premises, generated participant context, and HyDE representations
- * are one capability; only orchestration entry points and the read-model
- * generator cross its edge.
- */
-export { createEnrichmentTools } from "../enrichment/enrichment.tools.js";
-export { createPremiseTools } from "../premises/premise.tools.js";
-export { EnrichmentGraphFactory } from "../enrichment/enrichment.graph.js";
-export { PremiseGraphFactory } from "../premises/premise.graph.js";
-export { UserContextGenerator } from "./context.generator.js";
-export type { EnrichmentToolDeps, PremiseToolDeps } from "./context.tools.port.js";

package/dist/contexts/context.module.js

@@ -1,12 +0,0 @@
-/**
- * contexts — the capability's sole cross-capability surface.
- *
- * Enrichment, premises, generated participant context, and HyDE representations
- * are one capability; only orchestration entry points and the read-model
- * generator cross its edge.
- */
-export { createEnrichmentTools } from "../enrichment/enrichment.tools.js";
-export { createPremiseTools } from "../premises/premise.tools.js";
-export { EnrichmentGraphFactory } from "../enrichment/enrichment.graph.js";
-export { PremiseGraphFactory } from "../premises/premise.graph.js";
-export { UserContextGenerator } from "./context.generator.js";

package/dist/contexts/context.tools.port.d.ts

@@ -1,9 +0,0 @@
-import type { ToolRegistryCompositionDeps } from "../shared/agent/tool.helpers.js";
-/** Host capabilities consumed by enrichment and premise-derived identity tools. */
-export type EnrichmentToolDeps = Pick<ToolRegistryCompositionDeps, "userDb" | "systemDb" | "enricher" | "grantDefaultSystemPermissions" | "reportToolError" | "getUserContextText" | "enrichmentRuns" | "enrichmentRunQueue"> & {
-    graphs: Pick<ToolRegistryCompositionDeps["graphs"], "profile">;
-};
-/** Host capabilities consumed by premise mutation tools. */
-export type PremiseToolDeps = Pick<ToolRegistryCompositionDeps, "database"> & {
-    graphs: Pick<ToolRegistryCompositionDeps["graphs"], "premise">;
-};

package/dist/discovery/hyde.documents.d.ts

@@ -1,9 +0,0 @@
-import type { HydeDocument } from '../shared/interfaces/database.interface.js';
-import { type HydeGenerationMode } from './hyde.env.js';
-/** Hash source text without persisting the source itself in frame metadata. */
-export declare function computeHydeSourceTextHash(sourceText: string): string;
-/**
- * Select persisted documents that belong to the currently active generation
- * mode and, for frame-v1, the newest generation marker group.
- */
-export declare function selectHydeDocumentsForGeneration(documents: HydeDocument[], mode: HydeGenerationMode, sourceText: string): HydeDocument[];

package/dist/discovery/hyde.documents.js

@@ -1,49 +0,0 @@
-import { createHash } from 'crypto';
-import { HYDE_FRAME_GENERATION_VERSION } from './hyde.env.js';
-/** Hash source text without persisting the source itself in frame metadata. */
-export function computeHydeSourceTextHash(sourceText) {
-    return createHash('sha256').update(sourceText).digest('hex');
-}
-function isFrameStrategy(strategy) {
-    return strategy.startsWith(`${HYDE_FRAME_GENERATION_VERSION}:`);
-}
-function hasFrameMetadataForSource(document, sourceTextHash) {
-    const context = document.context;
-    return isFrameStrategy(document.strategy)
-        && context?.hydeGenerationVersion === HYDE_FRAME_GENERATION_VERSION
-        && context.validationStatus === 'valid'
-        && typeof context.lensLabel === 'string'
-        && context.lensLabel.length > 0
-        && typeof context.frameFingerprint === 'string'
-        && context.frameFingerprint.length > 0
-        && context.sourceTextHash === sourceTextHash
-        && typeof context.generatedAt === 'string'
-        && Number.isFinite(Date.parse(context.generatedAt));
-}
-/**
- * Select persisted documents that belong to the currently active generation
- * mode and, for frame-v1, the newest generation marker group.
- */
-export function selectHydeDocumentsForGeneration(documents, mode, sourceText) {
-    if (mode === 'legacy') {
-        return documents.filter((document) => !isFrameStrategy(document.strategy)
-            && document.context?.hydeGenerationVersion !== HYDE_FRAME_GENERATION_VERSION);
-    }
-    const sourceTextHash = computeHydeSourceTextHash(sourceText);
-    const eligible = documents.filter((document) => hasFrameMetadataForSource(document, sourceTextHash));
-    let newestGeneratedAt;
-    let newestTimestamp = Number.NEGATIVE_INFINITY;
-    for (const document of eligible) {
-        const generatedAt = document.context?.generatedAt;
-        if (typeof generatedAt !== 'string')
-            continue;
-        const timestamp = Date.parse(generatedAt);
-        if (timestamp > newestTimestamp) {
-            newestTimestamp = timestamp;
-            newestGeneratedAt = generatedAt;
-        }
-    }
-    return newestGeneratedAt
-        ? eligible.filter((document) => document.context?.generatedAt === newestGeneratedAt)
-        : [];
-}

package/dist/discovery/hyde.env.d.ts

@@ -1,8 +0,0 @@
-/** HyDE generation modes. */
-export declare const HYDE_FRAME_GENERATION_VERSION: "frame-v1";
-export type HydeGenerationMode = 'legacy' | typeof HYDE_FRAME_GENERATION_VERSION;
-/**
- * Resolve the HyDE generation mode from the feature flag.
- * Only the exact literal `true` enables frame-constrained generation.
- */
-export declare function getHydeGenerationMode(value?: string | undefined): HydeGenerationMode;

package/dist/discovery/hyde.env.js

@@ -1,9 +0,0 @@
-/** HyDE generation modes. */
-export const HYDE_FRAME_GENERATION_VERSION = 'frame-v1';
-/**
- * Resolve the HyDE generation mode from the feature flag.
- * Only the exact literal `true` enables frame-constrained generation.
- */
-export function getHydeGenerationMode(value = process.env.HYDE_FRAME_CONSTRAINTS_ENABLED) {
-    return value === 'true' ? HYDE_FRAME_GENERATION_VERSION : 'legacy';
-}