npm - @indexnetwork/protocol - Versions diffs - 3.13.0-rc.288.1 → 4.1.1-rc.290.1 - Mend

@indexnetwork/protocol 3.13.0-rc.288.1 → 4.1.1-rc.290.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (116) hide show

package/dist/shared/agent/tool.helpers.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"tool.helpers.js","sourceRoot":"/","sources":["shared/agent/tool.helpers.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\nimport type { ModelConfig } from \"./model.config.js\";\nimport type { ProfileDocument } from \"../schemas/profile.schema.js\";\nimport type { ChatGraphCompositeDatabase, NetworkMembership, UserRecord, UserDatabase, SystemDatabase, NegotiationGraphDatabase } from \"../interfaces/database.interface.js\";\nimport type { Scraper } from \"../interfaces/scraper.interface.js\";\nimport type { Cache, HydeCache } from \"../interfaces/cache.interface.js\";\nimport type { CompiledOpportunityGraph } from \"../../opportunity/opportunity.discover.js\";\nimport type { IntegrationAdapter } from \"../interfaces/integration.interface.js\";\nimport type { ContactServiceAdapter } from \"../interfaces/contact.interface.js\";\nimport type { ProfileEnricher } from \"../interfaces/enrichment.interface.js\";\nimport type { IntentGraphQueue } from \"../interfaces/queue.interface.js\";\nimport type { ChatSessionReader } from \"../interfaces/chat-session.interface.js\";\nimport type { ChatSummaryReader } from \"../interfaces/chat-summary.interface.js\";\nimport type { ChatMessageWriter } from \"../interfaces/chat-message-writer.interface.js\";\nimport type { QuestionGeneratorReader } from \"../interfaces/question-generator.interface.js\";\nimport type { NegotiationSummaryReader } from \"../interfaces/negotiation-summary.interface.js\";\nimport type { Embedder } from \"../interfaces/embedder.interface.js\";\nimport type { AgentDatabase } from \"../interfaces/agent.interface.js\";\nimport type { NegotiationTimeoutQueue } from \"../interfaces/negotiation-events.interface.js\";\nimport type { AgentDispatcher } from \"../interfaces/agent-dispatcher.interface.js\";\nimport type { DeliveryLedger } from \"../interfaces/delivery-ledger.interface.js\";\nimport type { MintConnectLink } from \"../interfaces/connect-link.interface.js\";\nimport type { QuestionerDatabase } from \"../interfaces/questioner.interface.js\";\nimport type { QuestionerEnqueueFn } from \"../../questioner/questioner.types.js\";\nimport type { PendingQuestionSummary } from \"../schemas/pending-question.schema.js\";\nimport type { QuestionMode } from \"../schemas/question.schema.js\";\nimport type { DiscoveryRunQueue, DiscoveryRunStore } from \"../interfaces/discovery-run.interface.js\";\nimport type { ProfileRunQueue, ProfileRunStore } from \"../interfaces/profile-run.interface.js\";\n\nexport type ProfileContext = ProfileDocument \| null;\n\nexport interface ToolErrorReport {\n operation: string;\n subsystem?: string;\n toolName?: string;\n userId?: string;\n tags?: Record<string, string \| number \| boolean \| null \| undefined>;\n context?: Record<string, unknown>;\n}\n\n// ═══════════════════════════════════════════════════════════════════════════════\n// COMPILED GRAPH TYPE\n// ═══════════════════════════════════════════════════════════════════════════════\n\n/** Minimal interface for an invokable compiled LangGraph. /\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type CompiledGraph = { invoke: (input: any) => Promise<any> };\n\n// ═══════════════════════════════════════════════════════════════════════════════\n// TOOL CONTEXT TYPES\n// ═══════════════════════════════════════════════════════════════════════════════\n\n/\n Resolved context available to every tool handler.\n * Contains the current user and optional index identity, resolved from DB at init.\n * The LLM can see this context (via system prompt) but cannot change it.\n /\nexport interface ResolvedToolContext {\n // Legacy flat fields (kept for backwards compatibility in tools/prompts).\n userId: string;\n userName: string;\n userEmail: string;\n networkId?: string;\n indexName?: string;\n /* True when chat is index-scoped and the user owns the index. /\n isOwner?: boolean;\n // Rich identity context for prompt/tool orchestration.\n user: UserRecord;\n userProfile: ProfileContext;\n userNetworks: NetworkMembership[];\n /\n The set of index IDs this caller can reach in the current request.\n * For unscoped chats: every index the user is a member of.\n * For network-scoped agents: `[boundNetwork, personalIndex]`.\n * This is the same set used to clamp the DB-level systemDb.\n * Tools that filter intents/profiles default to this set; `networkId` is\n * the \"primary focus\" hint, not a read filter.\n /\n indexScope: string[];\n scopedIndex?: {\n id: string;\n title: string;\n prompt: string \| null;\n type?: string;\n metadata?: Record<string, unknown>;\n permissions?: Record<string, unknown>;\n };\n scopedMembershipRole?: \"owner\" \| \"member\";\n /* True when user has not completed onboarding (onboarding.completedAt is null). /\n isOnboarding: boolean;\n /* True when the user has a non-empty name. /\n hasName: boolean;\n /* Chat session ID when tools are used in a chat; used for draft opportunities (context.conversationId). /\n sessionId?: string;\n /* True when the request originates from an MCP transport (no interactive UI available). /\n isMcp?: boolean;\n /* Agent ID when the request originates from an API key linked to an agent. /\n agentId?: string;\n /\n Receiver's rendering surface declared by the MCP client via the\n * `x-index-surface` request header. `'telegram'` means the MCP response is\n * being rendered inside a Telegram chat; anything\n * else (including `undefined`) is treated as web. Forwarded into\n * `mintConnectLink` so the click-time redirect can branch.\n /\n clientSurface?: 'telegram' \| 'web';\n /\n True when the CONTACTS_ENABLED feature flag is on. Carried from the\n * composition root so prompt modules can gate contact-import guidance —\n * when false/unset, the contacts prompt module is not injected, so the\n * orchestrator never advertises Gmail import / add_contact (whose tools\n * are also de-registered). Fail-closed: treat only `true` as enabled.\n /\n contactsEnabled?: boolean;\n}\n\n/\n Dependencies passed when creating tools for a user session.\n * Includes DB adapters, embedder, and scraper.\n \n Note: userDb and systemDb are optional inputs - if not provided, createChatTools\n * will create them internally from the chatDatabaseAdapter singleton.\n /\nexport interface ToolContext {\n userId: string;\n /* @deprecated Use userDb or systemDb instead. Kept for backwards compatibility. /\n database: ChatGraphCompositeDatabase;\n /* Context-bound database for accessing the authenticated user's own resources. Created internally if not provided. /\n userDb?: UserDatabase;\n /* Context-bound database for LLM/system operations on cross-user resources within shared indexes. Created internally if not provided. /\n systemDb?: SystemDatabase;\n embedder: Embedder;\n scraper: Scraper;\n /* When set, chat is scoped to this index; tools use it as default for read_intents and create_intent. /\n networkId?: string;\n /\n Optional override of the resolved `indexScope`. `resolveChatContext` always\n * computes `indexScope` from the user's memberships (clamped to [bound,\n * personal] when `networkId` is set). When the caller has already computed\n * a clamped scope — notably the MCP server, which clamps via\n * `applyNetworkScopeToContext` for network-scoped agents — passing it on\n * `ToolContext.indexScope` causes `createChatTools` (in tool.factory.ts) to\n * override `resolvedContext.indexScope` with this value rather than the\n * freshly computed one. See ResolvedToolContext.indexScope for the\n * resolved-side semantics.\n /\n indexScope?: string[];\n /* Chat session ID when creating tools for a chat; enables draft opportunities with context.conversationId. /\n sessionId?: string;\n\n // ─── Protocol-level dependencies (injected by composition root) ──────────\n /* General-purpose cache (e.g. for tool results). /\n cache: Cache;\n /* Dedicated cache for HyDE graph (may be same instance as cache). /\n hydeCache: HydeCache;\n /* External integration platform adapter (OAuth, tool actions). /\n integration: IntegrationAdapter;\n /* Queue for enqueuing follow-up intent processing (HyDE generation/deletion). /\n intentQueue: IntentGraphQueue;\n /* Contact management operations. /\n contactService: ContactServiceAdapter;\n /\n When false (or unset), the contact import / manual-add tools\n * (import_contacts, add_contact, import_gmail_contacts) are not registered.\n * Injected by the composition root from CONTACTS_ENABLED. Read/remove/search\n * contact tools are always registered.\n /\n contactsEnabled?: boolean;\n /* Chat session reader for loading conversation history. /\n chatSession: ChatSessionReader;\n /* Read-through chat-session digest. Optional; consumers fall back to undefined `chatContext`. /\n chatSummary?: ChatSummaryReader;\n /* Writes user messages into the user's most-recent chat session (Slice 5 MCP elicitation). /\n chatMessageWriter?: ChatMessageWriter;\n /* Decision-question generator. Optional; consumers fall back to no `questions`. /\n questionGenerator?: QuestionGeneratorReader;\n /\n Optional async question enqueue callback. When provided, question generation\n * is dispatched asynchronously to the QuestionerQueue instead of running inline.\n * Injected by the composition root when QUESTIONER_ENABLED=true.\n /\n questionerEnqueue?: QuestionerEnqueueFn;\n /* Negotiation-digest summarizer. Optional; consumers fall back to deterministic digests. /\n negotiationSummary?: NegotiationSummaryReader;\n /* Profile enrichment from external data sources. /\n enricher: ProfileEnricher;\n /* Database adapter for negotiation/conversation operations. /\n negotiationDatabase: NegotiationGraphDatabase;\n /* Integration importer for bulk contact import from toolkits. /\n integrationImporter: {\n importContacts(userId: string, toolkit: string): Promise<{\n imported: number;\n skipped: number;\n newContacts: number;\n existingContacts: number;\n }>;\n };\n /* Factory for user-scoped database access. /\n createUserDatabase: (db: ChatGraphCompositeDatabase, userId: string) => UserDatabase;\n /* Factory for system-scoped database access. /\n createSystemDatabase: (db: ChatGraphCompositeDatabase, userId: string, indexScope: string[], embedder?: Embedder) => SystemDatabase;\n /* Optional runtime LLM config. Pass to override env vars for API key, model, etc. /\n modelConfig?: ModelConfig;\n /* Manages negotiation timeout jobs (optional — enables AI fallback on external agent timeout). /\n negotiationTimeoutQueue?: NegotiationTimeoutQueue;\n /* Agent registry database adapter (optional — absent when host does not support agents). /\n agentDatabase?: AgentDatabase;\n /* Grants the default system-agent permissions after onboarding (optional). /\n grantDefaultSystemPermissions?: (userId: string) => Promise<void>;\n /* Dispatcher for routing negotiation turns to personal agents (optional — falls back to system AI). /\n agentDispatcher?: AgentDispatcher;\n /* Enqueue a negotiate_existing job after introducer approval (optional). /\n queueNegotiateExisting?: (opportunityId: string, userId: string) => Promise<void>;\n /* Delivery ledger for committing opportunity delivery rows (optional — absent in chat context). /\n deliveryLedger?: DeliveryLedger;\n /* Persistence for async MCP discovery runs (optional — absent in non-MCP/test contexts). /\n discoveryRuns?: DiscoveryRunStore;\n /* Queue for async MCP discovery run execution (optional — absent in non-MCP/test contexts). /\n discoveryRunQueue?: DiscoveryRunQueue;\n /* Persistence for async MCP profile runs (optional — absent in non-MCP/test contexts). /\n profileRuns?: ProfileRunStore;\n /* Queue for async MCP profile run execution (optional — absent in non-MCP/test contexts). /\n profileRunQueue?: ProfileRunQueue;\n /\n Legacy direct-token minting for opportunity accept redirects.\n * Prefer `mintConnectLink` for user-facing links.\n /\n mintConnectToken?: (userId: string, opportunityId: string) => Promise<string>;\n /* Mints (or reuses) a short connect link, snapshotting the greeting (optional — absent in non-MCP contexts). /\n mintConnectLink?: MintConnectLink;\n /* Frontend base URL for building profile links (e.g. https://index.network, optional). /\n frontendUrl?: string;\n /* API base URL for building opportunity accept links (e.g. https://protocol.index.network, optional). /\n apiBaseUrl?: string;\n /* Persistence for structured questions generated by the QuestionerAgent (optional). /\n questionerDatabase?: QuestionerDatabase;\n /* Optional host-side error reporter for swallowed protocol/tool errors. /\n reportToolError?: (error: unknown, report: ToolErrorReport) => void;\n /\n Optional host-side per-principal MCP call throttle. Invoked once per MCP\n * tool dispatch (after identity resolves, before any DB work). When the\n * returned decision is `allowed: false`, the dispatch short-circuits with a\n * rate-limit error carrying `retryAfterSec`. Absent in chat/test contexts.\n /\n mcpRateLimiter?: (input: { userId: string; agentId?: string; toolName: string }) => Promise<{\n allowed: boolean;\n retryAfterSec?: number;\n limit?: number;\n scope?: 'tool' \| 'principal';\n }>;\n /* Optional premise lifecycle event callbacks. Fired by premise tools after successful operations. /\n premiseEvents?: {\n onCreated?: (premiseId: string, userId: string) => void;\n onUpdated?: (premiseId: string, userId: string) => void;\n onRetracted?: (premiseId: string, userId: string) => void;\n };\n}\n\n/\n All external dependencies needed to initialize the protocol tool engine.\n * The host application (composition root) must provide concrete implementations.\n * This is the subset of ToolContext that is NOT per-request (no userId, indexId, sessionId).\n /\nexport type ProtocolDeps = Omit<ToolContext, 'userId' \| 'indexId' \| 'sessionId' \| 'userDb' \| 'systemDb'>;\n\n/\n Thrown when a requested chat scope is invalid for the authenticated user.\n * Controllers can map this to an HTTP status code.\n /\nexport class ChatContextAccessError extends Error {\n constructor(\n message: string,\n public readonly statusCode: number,\n public readonly code: \"USER_NOT_FOUND\" \| \"INDEX_NOT_FOUND\" \| \"INDEX_MEMBERSHIP_REQUIRED\"\n ) {\n super(message);\n this.name = \"ChatContextAccessError\";\n }\n}\n\n/\n Resolve the canonical context used by chat tools and system prompt.\n * This preloads user identity, profile, index memberships, and scoped index role.\n /\nexport async function resolveChatContext(params: {\n database: Pick<\n ChatGraphCompositeDatabase,\n \"getUser\" \| \"getProfile\" \| \"getNetworkMemberships\" \| \"getNetworkMembership\" \| \"getNetwork\" \| \"isIndexOwner\" \| \"isNetworkMember\"\n >;\n userId: string;\n networkId?: string;\n /* Chat session ID for draft opportunities (stored as context.conversationId). /\n sessionId?: string;\n /* CONTACTS_ENABLED flag, forwarded onto the resolved context for prompt gating. /\n contactsEnabled?: boolean;\n}): Promise<ResolvedToolContext> {\n const { database, userId, networkId, sessionId, contactsEnabled } = params;\n\n const [user, rawProfile, userNetworks] = await Promise.all([\n database.getUser(userId),\n database.getProfile(userId),\n database.getNetworkMemberships(userId),\n ]);\n\n const userProfile: ProfileContext = rawProfile ?? null;\n\n if (!user) {\n throw new ChatContextAccessError(\n \"User not found\",\n 404,\n \"USER_NOT_FOUND\"\n );\n }\n\n let scopedIndex: ResolvedToolContext[\"scopedIndex\"] = undefined;\n let scopedMembershipRole: ResolvedToolContext[\"scopedMembershipRole\"] = undefined;\n let isOwner = false;\n let indexName: string \| undefined;\n\n if (networkId) {\n const [index, isMember, owner] = await Promise.all([\n database.getNetwork(networkId),\n database.isNetworkMember(networkId, userId),\n database.isIndexOwner(networkId, userId),\n ]);\n\n if (!index) {\n throw new ChatContextAccessError(\n \"Index not found\",\n 404,\n \"INDEX_NOT_FOUND\"\n );\n }\n\n if (!isMember) {\n throw new ChatContextAccessError(\n \"You are not a member of this index\",\n 403,\n \"INDEX_MEMBERSHIP_REQUIRED\"\n );\n }\n\n let membership = userNetworks.find((m) => m.networkId === index.id);\n if (membership === undefined) {\n membership = (await database.getNetworkMembership(index.id, userId)) ?? undefined;\n }\n scopedIndex = {\n id: index.id,\n title: index.title,\n prompt: membership?.indexPrompt ?? null,\n type: index.type ?? 'community',\n metadata: index.metadata ?? {},\n permissions: index.permissions ?? {},\n };\n isOwner = owner;\n indexName = index.title;\n scopedMembershipRole = owner ? \"owner\" : \"member\";\n }\n\n const userName = user.name ?? \"Unknown\";\n const userEmail = user.email ?? \"\";\n const hasName = !!user.name?.trim();\n\n // When scoped to an index, clamp the caller's reach to [scopedIndex, personalIndex]\n // so the chat's data model matches its \"focus\" semantic: a chat scoped to a\n // community sees that community plus the user's personal index, not their\n // other unrelated memberships. Mirrors the MCP path's clamp for network-scoped\n // agents (see applyNetworkScopeToContext / computeAgentIndexScope).\n const indexScope = networkId\n ? userNetworks\n .filter((m) => m.networkId === networkId \|\| m.isPersonal === true)\n .map((m) => m.networkId)\n : userNetworks.map((m) => m.networkId);\n\n return {\n userId,\n userName,\n userEmail,\n networkId,\n indexName,\n isOwner,\n user,\n userProfile,\n userNetworks,\n indexScope,\n scopedIndex,\n scopedMembershipRole,\n isOnboarding: !(user.onboarding?.completedAt),\n hasName,\n contactsEnabled,\n ...(sessionId !== undefined ? { sessionId } : {}),\n };\n}\n\n// ═══════════════════════════════════════════════════════════════════════════════\n// DEFINE TOOL TYPE\n// ═══════════════════════════════════════════════════════════════════════════════\n\n/\n Type for the `defineTool` closure created in `createChatTools`.\n * Auto-injects resolved context and provides uniform logging / error handling.\n /\nexport type DefineTool = <T extends z.ZodType>(opts: {\n name: string;\n description: string;\n querySchema: T;\n handler: (input: { context: ResolvedToolContext; query: z.infer<T> }) => Promise<string>;\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\n}) => any;\n\n/\n A raw tool definition before LangChain wrapping.\n * Used by the tool registry for direct HTTP invocation.\n /\nexport interface RawToolDefinition {\n name: string;\n description: string;\n schema: z.ZodType;\n handler: (input: { context: ResolvedToolContext; query: unknown }) => Promise<string>;\n}\n\n/\n Registry mapping tool names to their raw definitions.\n /\nexport type ToolRegistry = Map<string, RawToolDefinition>;\n\n// ═══════════════════════════════════════════════════════════════════════════════\n// TOOL DEPENDENCIES\n// ═══════════════════════════════════════════════════════════════════════════════\n\n/\n Shared dependencies available to all tool domain factories.\n * Passed by `createChatTools` after compiling all subgraphs.\n /\nexport interface ToolDeps {\n /* @deprecated Use userDb or systemDb instead. Kept for backwards compatibility. /\n database: ChatGraphCompositeDatabase;\n /* Context-bound database for accessing the authenticated user's own resources. /\n userDb: UserDatabase;\n /* Context-bound database for LLM/system operations on cross-user resources within shared indexes. /\n systemDb: SystemDatabase;\n scraper: Scraper;\n embedder: import('../interfaces/embedder.interface.js').Embedder;\n cache: Cache;\n integration: IntegrationAdapter;\n contactService: ContactServiceAdapter;\n /\n When false (or unset), the contact import / manual-add tools\n * (import_contacts, add_contact, import_gmail_contacts) are not registered.\n * Injected by the composition root from CONTACTS_ENABLED. Read/remove/search\n * contact tools are always registered.\n /\n contactsEnabled?: boolean;\n integrationImporter: {\n importContacts(userId: string, toolkit: string): Promise<{\n imported: number;\n skipped: number;\n newContacts: number;\n existingContacts: number;\n }>;\n };\n enricher: ProfileEnricher;\n /* Database adapter for negotiation/conversation operations. /\n negotiationDatabase: NegotiationGraphDatabase;\n /* Chat session reader for exposing the caller's past conversations as MCP tools. /\n chatSession?: ChatSessionReader;\n /* Read-through chat-session digest. Optional; consumers fall back to undefined `chatContext`. /\n chatSummary?: ChatSummaryReader;\n /\n Test seam for opportunity discovery helpers. Production compositions leave\n * this unset so tools call the real discovery module directly.\n /\n opportunityDiscovery?: {\n runDiscoverFromQuery?: (input: unknown) => Promise<unknown>;\n continueDiscovery?: (input: unknown) => Promise<unknown>;\n };\n /\n Test seam for opportunity card presentation helpers. Production\n * compositions leave this unset so tools construct the real presenter.\n /\n opportunityPresentation?: {\n createPresenter?: () => { presentHomeCard(input: unknown): Promise<unknown> };\n gatherPresenterContext?: (...args: unknown[]) => Promise<unknown>;\n };\n /* Writes user messages into the user's most-recent chat session (Slice 5 MCP elicitation). /\n chatMessageWriter?: ChatMessageWriter;\n /* Decision-question generator. Optional; consumers fall back to no `questions`. /\n questionGenerator?: QuestionGeneratorReader;\n /\n Optional async question enqueue callback. When provided, question generation\n * is dispatched asynchronously to the QuestionerQueue instead of running inline\n * via the `questionGenerator`. Injected by the composition root when\n * QUESTIONER_ENABLED=true.\n /\n questionerEnqueue?: QuestionerEnqueueFn;\n /\n Lookup pending questions for a user, optionally filtered by source,\n * detection mode, or capped by count (hosts apply `limit` SQL-side).\n * Used by tools to attach contextually relevant questions to their results.\n * Injected by the composition root — absent when question delivery is disabled.\n /\n findPendingQuestions?: (\n userId: string,\n filters?: {\n sourceType?: string;\n sourceId?: string;\n /* Restrict to questions whose detection mode is in this set. /\n modes?: QuestionMode[];\n /* Maximum rows to return; hosts should apply this in the query. /\n limit?: number;\n },\n ) => Promise<PendingQuestionSummary[]>;\n /* Negotiation-digest summarizer. Optional; consumers fall back to deterministic digests. /\n negotiationSummary?: NegotiationSummaryReader;\n /* Manages negotiation timeout jobs (optional — enables AI fallback on external agent timeout). /\n negotiationTimeoutQueue?: NegotiationTimeoutQueue;\n /* Agent registry database adapter (optional — absent when host does not support agents). /\n agentDatabase?: AgentDatabase;\n /* Grants the default system-agent permissions after onboarding (optional). /\n grantDefaultSystemPermissions?: (userId: string) => Promise<void>;\n /* Dispatcher for routing negotiation turns to personal agents (optional — falls back to system AI). /\n agentDispatcher?: AgentDispatcher;\n /* Delivery ledger for committing opportunity delivery rows (optional — absent in chat context). /\n deliveryLedger?: DeliveryLedger;\n /* Persistence for async MCP discovery runs (optional — absent in non-MCP/test contexts). /\n discoveryRuns?: DiscoveryRunStore;\n /* Queue for async MCP discovery run execution (optional — absent in non-MCP/test contexts). /\n discoveryRunQueue?: DiscoveryRunQueue;\n /* Persistence for async MCP profile runs (optional — absent in non-MCP/test contexts). /\n profileRuns?: ProfileRunStore;\n /* Queue for async MCP profile run execution (optional — absent in non-MCP/test contexts). /\n profileRunQueue?: ProfileRunQueue;\n /\n Legacy direct-token minting for opportunity accept redirects.\n * Prefer `mintConnectLink` for user-facing links.\n /\n mintConnectToken?: (userId: string, opportunityId: string) => Promise<string>;\n /* Mints (or reuses) a short connect link, snapshotting the greeting (optional — absent in non-MCP contexts). /\n mintConnectLink?: MintConnectLink;\n /* Frontend base URL for building profile links (e.g. https://index.network, optional). /\n frontendUrl?: string;\n /* API base URL for building opportunity accept links (e.g. https://protocol.index.network, optional). /\n apiBaseUrl?: string;\n /* Optional host-side error reporter for swallowed protocol/tool errors. /\n reportToolError?: (error: unknown, report: ToolErrorReport) => void;\n /\n Optional host-side per-principal MCP call throttle. Invoked once per MCP\n * tool dispatch (after identity resolves, before any DB work). When the\n * returned decision is `allowed: false`, the dispatch short-circuits with a\n * rate-limit error carrying `retryAfterSec`. Absent in chat/test contexts.\n /\n mcpRateLimiter?: (input: { userId: string; agentId?: string; toolName: string }) => Promise<{\n allowed: boolean;\n retryAfterSec?: number;\n limit?: number;\n scope?: 'tool' \| 'principal';\n }>;\n /* Optional premise lifecycle event callbacks. Fired by premise tools after successful operations. /\n premiseEvents?: {\n onCreated?: (premiseId: string, userId: string) => void;\n onUpdated?: (premiseId: string, userId: string) => void;\n onRetracted?: (premiseId: string, userId: string) => void;\n };\n graphs: {\n profile: CompiledGraph;\n intent: CompiledGraph;\n index: CompiledGraph;\n networkMembership: CompiledGraph;\n intentIndex: CompiledGraph;\n opportunity: CompiledOpportunityGraph;\n premise: CompiledGraph;\n };\n /\n Optional network ranking override for `read_networks`. Injected by tests or custom compositions.\n * When absent, defaults to `NetworkRecommender.invoke()` with a lazy module-level singleton.\n /\n networkRanker?: (input: {\n userContext: string;\n networks: Array<{ networkId: string; renderedContext: string }>;\n }) => Promise<{ rankedNetworkIds: string[] } \| null>;\n /\n Resolve a user's global user_context paragraph (profile-replacing identity text),\n * generating it on demand when absent. Injected by the backend composition root\n * (`ensureGlobalUserContext`). When absent, onboarding network ranking is skipped.\n /\n getUserContextText?: (userId: string) => Promise<string>;\n}\n\n// ═══════════════════════════════════════════════════════════════════════════════\n// TOOL RESULT HELPERS\n// ═══════════════════════════════════════════════════════════════════════════════\n\nexport function success<T>(data: T): string {\n return JSON.stringify({ success: true, data });\n}\n\nexport function error(\n message: string,\n debugSteps?: Array<{ step: string; detail?: string; data?: Record<string, unknown> }>\n): string {\n return JSON.stringify({\n success: false,\n error: message,\n ...(debugSteps?.length ? { debugSteps } : {}),\n });\n}\n\n/* Return needsClarification for missing required fields. /\nexport function needsClarification(params: {\n missingFields: string[];\n message: string;\n}): string {\n return JSON.stringify({\n success: false,\n needsClarification: true,\n ...params,\n });\n}\n\n// ═══════════════════════════════════════════════════════════════════════════════\n// CONSTANTS & UTILITIES\n// ═══════════════════════════════════════════════════════════════════════════════\n\n/* Matches http/https URLs in text; captures full URL. /\nconst URL_IN_TEXT_REGEX = /https?:\\/\\/[^\\s\"'<>)\\]]+/gi;\n\n/\n Matches bare domain URLs without protocol (e.g. github.com/foo, www.example.com).\n * Requires at least a SLD.TLD pattern followed by optional path.\n * Negative lookbehind ensures we don't double-match URLs already caught by URL_IN_TEXT_REGEX.\n /\nconst BARE_URL_REGEX = /(?<!\\w:\\/\\/)(?<![/\\w])(?:www\\.)?[a-z0-9](?:[a-z0-9-][a-z0-9])?\\.(?:com\|org\|net\|io\|dev\|co\|ai\|app\|xyz\|me\|info\|gg\|so\|sh\|cc\|ly\|fm\|tv\|to\|tech\|design\|network\|world\|edu\|gov\|mil\|int\|us\|uk\|eu\|de\|fr\|ca\|au\|jp\|cn\|in\|br\|nl\|se\|no\|fi\|dk\|ch\|at\|be\|it\|es\|pt\|pl\|cz\|ru\|kr\|tw\|hk\|sg\|nz\|za\|mx\|ar\|cl\|id\|ph\|th\|vn\|my\|ie)(?:\\/[^\\s\"'<>)\\]])?/gi;\n\n/* UUID v4 format: 8-4-4-4-12 hex chars (e.g. c2505011-2e45-426e-81dd-b9abb9b72023) /\nexport const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\n\n/\n Resolves an array of network IDs to their display titles.\n * Skips any IDs that don't resolve (deleted or invalid networks).\n /\nexport async function resolveIndexNames(\n database: { getNetwork(id: string): Promise<{ id: string; title: string } \| null> },\n networkIds: string[]\n): Promise<string[]> {\n if (networkIds.length === 0) return [];\n const results = await Promise.all(\n networkIds.map(id => database.getNetwork(id))\n );\n return results.filter(Boolean).map(idx => idx!.title);\n}\n\n/\n Normalize a URL string: if it lacks a protocol, prepend \"https://\".\n * Returns the normalized URL or null if the result is not a valid URL.\n /\nexport function normalizeUrl(raw: string): string \| null {\n let url = raw.replace(/[.,;:!?)]+$/, \"\").trim();\n if (!/^https?:\\/\\//i.test(url)) {\n url = `https://${url}`;\n }\n try {\n new URL(url);\n return url;\n } catch {\n return null;\n }\n}\n\n/\n Extract unique, valid URLs from a string (e.g. user message or details).\n * Handles both full URLs (https://...) and bare domains (github.com/...).\n /\nexport function extractUrls(text: string): string[] {\n if (!text \|\| typeof text !== \"string\") return [];\n\n const seen = new Set<string>();\n const out: string[] = [];\n\n // Pass 1: full protocol URLs\n const fullMatches = text.match(URL_IN_TEXT_REGEX) ?? [];\n for (const raw of fullMatches) {\n const url = normalizeUrl(raw);\n if (url && !seen.has(url)) {\n seen.add(url);\n out.push(url);\n }\n }\n\n // Pass 2: bare domain URLs (e.g. github.com/foo)\n const bareMatches = text.match(BARE_URL_REGEX) ?? [];\n for (const raw of bareMatches) {\n const url = normalizeUrl(raw);\n if (url && !seen.has(url)) {\n seen.add(url);\n out.push(url);\n }\n }\n\n return out;\n}\n\nconst SENSITIVE_FIELD_KEYS = new Set([\n \"secret\",\n \"webhooksecret\",\n \"password\",\n \"apikey\",\n \"token\",\n \"accesstoken\",\n \"refreshtoken\",\n \"privatekey\",\n \"authtoken\",\n \"bearertoken\",\n \"clientsecret\",\n]);\n\n/\n Recursively redacts sensitive field values from an arbitrary payload before\n * it is passed to a structured logger. Matches field names case-insensitively\n * and ignoring underscores, so `api_key`, `apiKey`, and `API_KEY` all match.\n * Non-sensitive fields are passed through unchanged. Never mutates the input —\n * returns a new value.\n \n Intended for structured-log redaction only. Do NOT use as a security\n * boundary for data in motion.\n \n @param value - Arbitrary JSON-like payload (query object, config blob, etc.)\n * @returns A new value with sensitive fields replaced by `\"[redacted]\"`.\n */\nexport function redactSensitiveFields(value: unknown): unknown {\n if (value === null \|\| typeof value !== \"object\") return value;\n if (Array.isArray(value)) {\n return value.map((item) => redactSensitiveFields(item));\n }\n const out: Record<string, unknown> = {};\n for (const [key, inner] of Object.entries(value as Record<string, unknown>)) {\n const normalized = key.toLowerCase().replace(/_/g, \"\");\n if (SENSITIVE_FIELD_KEYS.has(normalized)) {\n out[key] = \"[redacted]\";\n } else {\n out[key] = redactSensitiveFields(inner);\n }\n }\n return out;\n}\n"]}
1	+ {"version":3,"file":"tool.helpers.js","sourceRoot":"/","sources":["shared/agent/tool.helpers.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\nimport type { ModelConfig } from \"./model.config.js\";\nimport type { UserIdentity } from \"../schemas/identity.schema.js\";\nimport type { ChatGraphCompositeDatabase, NetworkMembership, UserRecord, UserDatabase, SystemDatabase, NegotiationGraphDatabase } from \"../interfaces/database.interface.js\";\nimport type { Scraper } from \"../interfaces/scraper.interface.js\";\nimport type { Cache, HydeCache } from \"../interfaces/cache.interface.js\";\nimport type { CompiledOpportunityGraph } from \"../../opportunity/opportunity.discover.js\";\nimport type { IntegrationAdapter } from \"../interfaces/integration.interface.js\";\nimport type { ContactServiceAdapter } from \"../interfaces/contact.interface.js\";\nimport type { ProfileEnricher } from \"../interfaces/enrichment.interface.js\";\nimport type { IntentGraphQueue } from \"../interfaces/queue.interface.js\";\nimport type { ChatSessionReader } from \"../interfaces/chat-session.interface.js\";\nimport type { ChatSummaryReader } from \"../interfaces/chat-summary.interface.js\";\nimport type { ChatMessageWriter } from \"../interfaces/chat-message-writer.interface.js\";\nimport type { QuestionGeneratorReader } from \"../interfaces/question-generator.interface.js\";\nimport type { NegotiationSummaryReader } from \"../interfaces/negotiation-summary.interface.js\";\nimport type { Embedder } from \"../interfaces/embedder.interface.js\";\nimport type { AgentDatabase } from \"../interfaces/agent.interface.js\";\nimport type { NegotiationTimeoutQueue } from \"../interfaces/negotiation-events.interface.js\";\nimport type { AgentDispatcher } from \"../interfaces/agent-dispatcher.interface.js\";\nimport type { DeliveryLedger } from \"../interfaces/delivery-ledger.interface.js\";\nimport type { MintConnectLink } from \"../interfaces/connect-link.interface.js\";\nimport type { QuestionerDatabase } from \"../interfaces/questioner.interface.js\";\nimport type { QuestionerEnqueueFn } from \"../../questioner/questioner.types.js\";\nimport type { PendingQuestionSummary } from \"../schemas/pending-question.schema.js\";\nimport type { QuestionMode } from \"../schemas/question.schema.js\";\nimport type { DiscoveryRunQueue, DiscoveryRunStore } from \"../interfaces/discovery-run.interface.js\";\nimport type { EnrichmentRunQueue, EnrichmentRunStore } from \"../interfaces/enrichment-run.interface.js\";\n\nexport type IdentityContext = UserIdentity \| null;\n\nexport interface ToolErrorReport {\n operation: string;\n subsystem?: string;\n toolName?: string;\n userId?: string;\n tags?: Record<string, string \| number \| boolean \| null \| undefined>;\n context?: Record<string, unknown>;\n}\n\n// ═══════════════════════════════════════════════════════════════════════════════\n// COMPILED GRAPH TYPE\n// ═══════════════════════════════════════════════════════════════════════════════\n\n/** Minimal interface for an invokable compiled LangGraph. /\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type CompiledGraph = { invoke: (input: any) => Promise<any> };\n\n// ═══════════════════════════════════════════════════════════════════════════════\n// TOOL CONTEXT TYPES\n// ═══════════════════════════════════════════════════════════════════════════════\n\n/\n Resolved context available to every tool handler.\n * Contains the current user and optional index identity, resolved from DB at init.\n * The LLM can see this context (via system prompt) but cannot change it.\n /\nexport interface ResolvedToolContext {\n // Legacy flat fields (kept for backwards compatibility in tools/prompts).\n userId: string;\n userName: string;\n userEmail: string;\n networkId?: string;\n indexName?: string;\n /* True when chat is index-scoped and the user owns the index. /\n isOwner?: boolean;\n // Rich identity context for prompt/tool orchestration.\n user: UserRecord;\n userProfile: IdentityContext;\n userNetworks: NetworkMembership[];\n /\n The set of index IDs this caller can reach in the current request.\n * For unscoped chats: every index the user is a member of.\n * For network-scoped agents: `[boundNetwork, personalIndex]`.\n * This is the same set used to clamp the DB-level systemDb.\n * Tools that filter intents/profiles default to this set; `networkId` is\n * the \"primary focus\" hint, not a read filter.\n /\n indexScope: string[];\n scopedIndex?: {\n id: string;\n title: string;\n prompt: string \| null;\n type?: string;\n metadata?: Record<string, unknown>;\n permissions?: Record<string, unknown>;\n };\n scopedMembershipRole?: \"owner\" \| \"member\";\n /* True when user has not completed onboarding (onboarding.completedAt is null). /\n isOnboarding: boolean;\n /* True when the user has a non-empty name. /\n hasName: boolean;\n /* Chat session ID when tools are used in a chat; used for draft opportunities (context.conversationId). /\n sessionId?: string;\n /* True when the request originates from an MCP transport (no interactive UI available). /\n isMcp?: boolean;\n /* Agent ID when the request originates from an API key linked to an agent. /\n agentId?: string;\n /\n Receiver's rendering surface declared by the MCP client via the\n * `x-index-surface` request header. `'telegram'` means the MCP response is\n * being rendered inside a Telegram chat; anything\n * else (including `undefined`) is treated as web. Forwarded into\n * `mintConnectLink` so the click-time redirect can branch.\n /\n clientSurface?: 'telegram' \| 'web';\n /\n True when the CONTACTS_ENABLED feature flag is on. Carried from the\n * composition root so prompt modules can gate contact-import guidance —\n * when false/unset, the contacts prompt module is not injected, so the\n * orchestrator never advertises Gmail import / add_contact (whose tools\n * are also de-registered). Fail-closed: treat only `true` as enabled.\n /\n contactsEnabled?: boolean;\n}\n\n/\n Dependencies passed when creating tools for a user session.\n * Includes DB adapters, embedder, and scraper.\n \n Note: userDb and systemDb are optional inputs - if not provided, createChatTools\n * will create them internally from the chatDatabaseAdapter singleton.\n /\nexport interface ToolContext {\n userId: string;\n /* @deprecated Use userDb or systemDb instead. Kept for backwards compatibility. /\n database: ChatGraphCompositeDatabase;\n /* Context-bound database for accessing the authenticated user's own resources. Created internally if not provided. /\n userDb?: UserDatabase;\n /* Context-bound database for LLM/system operations on cross-user resources within shared indexes. Created internally if not provided. /\n systemDb?: SystemDatabase;\n embedder: Embedder;\n scraper: Scraper;\n /* When set, chat is scoped to this index; tools use it as default for read_intents and create_intent. /\n networkId?: string;\n /\n Optional override of the resolved `indexScope`. `resolveChatContext` always\n * computes `indexScope` from the user's memberships (clamped to [bound,\n * personal] when `networkId` is set). When the caller has already computed\n * a clamped scope — notably the MCP server, which clamps via\n * `applyNetworkScopeToContext` for network-scoped agents — passing it on\n * `ToolContext.indexScope` causes `createChatTools` (in tool.factory.ts) to\n * override `resolvedContext.indexScope` with this value rather than the\n * freshly computed one. See ResolvedToolContext.indexScope for the\n * resolved-side semantics.\n /\n indexScope?: string[];\n /* Chat session ID when creating tools for a chat; enables draft opportunities with context.conversationId. /\n sessionId?: string;\n\n // ─── Protocol-level dependencies (injected by composition root) ──────────\n /* General-purpose cache (e.g. for tool results). /\n cache: Cache;\n /* Dedicated cache for HyDE graph (may be same instance as cache). /\n hydeCache: HydeCache;\n /* External integration platform adapter (OAuth, tool actions). /\n integration: IntegrationAdapter;\n /* Queue for enqueuing follow-up intent processing (HyDE generation/deletion). /\n intentQueue: IntentGraphQueue;\n /* Contact management operations. /\n contactService: ContactServiceAdapter;\n /\n When false (or unset), the contact import / manual-add tools\n * (import_contacts, add_contact, import_gmail_contacts) are not registered.\n * Injected by the composition root from CONTACTS_ENABLED. Read/remove/search\n * contact tools are always registered.\n /\n contactsEnabled?: boolean;\n /* Chat session reader for loading conversation history. /\n chatSession: ChatSessionReader;\n /* Read-through chat-session digest. Optional; consumers fall back to undefined `chatContext`. /\n chatSummary?: ChatSummaryReader;\n /* Writes user messages into the user's most-recent chat session (Slice 5 MCP elicitation). /\n chatMessageWriter?: ChatMessageWriter;\n /* Decision-question generator. Optional; consumers fall back to no `questions`. /\n questionGenerator?: QuestionGeneratorReader;\n /\n Optional async question enqueue callback. When provided, question generation\n * is dispatched asynchronously to the QuestionerQueue instead of running inline.\n * Injected by the composition root when QUESTIONER_ENABLED=true.\n /\n questionerEnqueue?: QuestionerEnqueueFn;\n /* Negotiation-digest summarizer. Optional; consumers fall back to deterministic digests. /\n negotiationSummary?: NegotiationSummaryReader;\n /* Profile enrichment from external data sources. /\n enricher: ProfileEnricher;\n /* Database adapter for negotiation/conversation operations. /\n negotiationDatabase: NegotiationGraphDatabase;\n /* Integration importer for bulk contact import from toolkits. /\n integrationImporter: {\n importContacts(userId: string, toolkit: string): Promise<{\n imported: number;\n skipped: number;\n newContacts: number;\n existingContacts: number;\n }>;\n };\n /* Factory for user-scoped database access. /\n createUserDatabase: (db: ChatGraphCompositeDatabase, userId: string) => UserDatabase;\n /* Factory for system-scoped database access. /\n createSystemDatabase: (db: ChatGraphCompositeDatabase, userId: string, indexScope: string[], embedder?: Embedder) => SystemDatabase;\n /* Optional runtime LLM config. Pass to override env vars for API key, model, etc. /\n modelConfig?: ModelConfig;\n /* Manages negotiation timeout jobs (optional — enables AI fallback on external agent timeout). /\n negotiationTimeoutQueue?: NegotiationTimeoutQueue;\n /* Agent registry database adapter (optional — absent when host does not support agents). /\n agentDatabase?: AgentDatabase;\n /* Grants the default system-agent permissions after onboarding (optional). /\n grantDefaultSystemPermissions?: (userId: string) => Promise<void>;\n /* Dispatcher for routing negotiation turns to personal agents (optional — falls back to system AI). /\n agentDispatcher?: AgentDispatcher;\n /* Enqueue a negotiate_existing job after introducer approval (optional). /\n queueNegotiateExisting?: (opportunityId: string, userId: string) => Promise<void>;\n /* Delivery ledger for committing opportunity delivery rows (optional — absent in chat context). /\n deliveryLedger?: DeliveryLedger;\n /* Persistence for async MCP discovery runs (optional — absent in non-MCP/test contexts). /\n discoveryRuns?: DiscoveryRunStore;\n /* Queue for async MCP discovery run execution (optional — absent in non-MCP/test contexts). /\n discoveryRunQueue?: DiscoveryRunQueue;\n /* Persistence for async MCP profile runs (optional — absent in non-MCP/test contexts). /\n enrichmentRuns?: EnrichmentRunStore;\n /* Queue for async MCP profile run execution (optional — absent in non-MCP/test contexts). /\n enrichmentRunQueue?: EnrichmentRunQueue;\n /\n Legacy direct-token minting for opportunity accept redirects.\n * Prefer `mintConnectLink` for user-facing links.\n /\n mintConnectToken?: (userId: string, opportunityId: string) => Promise<string>;\n /* Mints (or reuses) a short connect link, snapshotting the greeting (optional — absent in non-MCP contexts). /\n mintConnectLink?: MintConnectLink;\n /* Frontend base URL for building profile links (e.g. https://index.network, optional). /\n frontendUrl?: string;\n /* API base URL for building opportunity accept links (e.g. https://protocol.index.network, optional). /\n apiBaseUrl?: string;\n /* Persistence for structured questions generated by the QuestionerAgent (optional). /\n questionerDatabase?: QuestionerDatabase;\n /* Optional host-side error reporter for swallowed protocol/tool errors. /\n reportToolError?: (error: unknown, report: ToolErrorReport) => void;\n /\n Optional host-side per-principal MCP call throttle. Invoked once per MCP\n * tool dispatch (after identity resolves, before any DB work). When the\n * returned decision is `allowed: false`, the dispatch short-circuits with a\n * rate-limit error carrying `retryAfterSec`. Absent in chat/test contexts.\n /\n mcpRateLimiter?: (input: { userId: string; agentId?: string; toolName: string }) => Promise<{\n allowed: boolean;\n retryAfterSec?: number;\n limit?: number;\n scope?: 'tool' \| 'principal';\n }>;\n /* Optional premise lifecycle event callbacks. Fired by premise tools after successful operations. /\n premiseEvents?: {\n onCreated?: (premiseId: string, userId: string) => void;\n onUpdated?: (premiseId: string, userId: string) => void;\n onRetracted?: (premiseId: string, userId: string) => void;\n };\n}\n\n/\n All external dependencies needed to initialize the protocol tool engine.\n * The host application (composition root) must provide concrete implementations.\n * This is the subset of ToolContext that is NOT per-request (no userId, indexId, sessionId).\n /\nexport type ProtocolDeps = Omit<ToolContext, 'userId' \| 'indexId' \| 'sessionId' \| 'userDb' \| 'systemDb'>;\n\n/\n Thrown when a requested chat scope is invalid for the authenticated user.\n * Controllers can map this to an HTTP status code.\n /\nexport class ChatContextAccessError extends Error {\n constructor(\n message: string,\n public readonly statusCode: number,\n public readonly code: \"USER_NOT_FOUND\" \| \"INDEX_NOT_FOUND\" \| \"INDEX_MEMBERSHIP_REQUIRED\"\n ) {\n super(message);\n this.name = \"ChatContextAccessError\";\n }\n}\n\n/\n Resolve the canonical context used by chat tools and system prompt.\n * This preloads user identity, profile, index memberships, and scoped index role.\n /\nexport async function resolveChatContext(params: {\n database: Pick<\n ChatGraphCompositeDatabase,\n \"getUser\" \| \"getProfile\" \| \"getNetworkMemberships\" \| \"getNetworkMembership\" \| \"getNetwork\" \| \"isIndexOwner\" \| \"isNetworkMember\"\n >;\n userId: string;\n networkId?: string;\n /* Chat session ID for draft opportunities (stored as context.conversationId). /\n sessionId?: string;\n /* CONTACTS_ENABLED flag, forwarded onto the resolved context for prompt gating. /\n contactsEnabled?: boolean;\n}): Promise<ResolvedToolContext> {\n const { database, userId, networkId, sessionId, contactsEnabled } = params;\n\n const [user, rawProfile, userNetworks] = await Promise.all([\n database.getUser(userId),\n database.getProfile(userId),\n database.getNetworkMemberships(userId),\n ]);\n\n const userProfile: IdentityContext = rawProfile ?? null;\n\n if (!user) {\n throw new ChatContextAccessError(\n \"User not found\",\n 404,\n \"USER_NOT_FOUND\"\n );\n }\n\n let scopedIndex: ResolvedToolContext[\"scopedIndex\"] = undefined;\n let scopedMembershipRole: ResolvedToolContext[\"scopedMembershipRole\"] = undefined;\n let isOwner = false;\n let indexName: string \| undefined;\n\n if (networkId) {\n const [index, isMember, owner] = await Promise.all([\n database.getNetwork(networkId),\n database.isNetworkMember(networkId, userId),\n database.isIndexOwner(networkId, userId),\n ]);\n\n if (!index) {\n throw new ChatContextAccessError(\n \"Index not found\",\n 404,\n \"INDEX_NOT_FOUND\"\n );\n }\n\n if (!isMember) {\n throw new ChatContextAccessError(\n \"You are not a member of this index\",\n 403,\n \"INDEX_MEMBERSHIP_REQUIRED\"\n );\n }\n\n let membership = userNetworks.find((m) => m.networkId === index.id);\n if (membership === undefined) {\n membership = (await database.getNetworkMembership(index.id, userId)) ?? undefined;\n }\n scopedIndex = {\n id: index.id,\n title: index.title,\n prompt: membership?.indexPrompt ?? null,\n type: index.type ?? 'community',\n metadata: index.metadata ?? {},\n permissions: index.permissions ?? {},\n };\n isOwner = owner;\n indexName = index.title;\n scopedMembershipRole = owner ? \"owner\" : \"member\";\n }\n\n const userName = user.name ?? \"Unknown\";\n const userEmail = user.email ?? \"\";\n const hasName = !!user.name?.trim();\n\n // When scoped to an index, clamp the caller's reach to [scopedIndex, personalIndex]\n // so the chat's data model matches its \"focus\" semantic: a chat scoped to a\n // community sees that community plus the user's personal index, not their\n // other unrelated memberships. Mirrors the MCP path's clamp for network-scoped\n // agents (see applyNetworkScopeToContext / computeAgentIndexScope).\n const indexScope = networkId\n ? userNetworks\n .filter((m) => m.networkId === networkId \|\| m.isPersonal === true)\n .map((m) => m.networkId)\n : userNetworks.map((m) => m.networkId);\n\n return {\n userId,\n userName,\n userEmail,\n networkId,\n indexName,\n isOwner,\n user,\n userProfile,\n userNetworks,\n indexScope,\n scopedIndex,\n scopedMembershipRole,\n isOnboarding: !(user.onboarding?.completedAt),\n hasName,\n contactsEnabled,\n ...(sessionId !== undefined ? { sessionId } : {}),\n };\n}\n\n// ═══════════════════════════════════════════════════════════════════════════════\n// DEFINE TOOL TYPE\n// ═══════════════════════════════════════════════════════════════════════════════\n\n/\n Type for the `defineTool` closure created in `createChatTools`.\n * Auto-injects resolved context and provides uniform logging / error handling.\n /\nexport type DefineTool = <T extends z.ZodType>(opts: {\n name: string;\n description: string;\n querySchema: T;\n handler: (input: { context: ResolvedToolContext; query: z.infer<T> }) => Promise<string>;\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\n}) => any;\n\n/\n A raw tool definition before LangChain wrapping.\n * Used by the tool registry for direct HTTP invocation.\n /\nexport interface RawToolDefinition {\n name: string;\n description: string;\n schema: z.ZodType;\n handler: (input: { context: ResolvedToolContext; query: unknown }) => Promise<string>;\n}\n\n/\n Registry mapping tool names to their raw definitions.\n /\nexport type ToolRegistry = Map<string, RawToolDefinition>;\n\n// ═══════════════════════════════════════════════════════════════════════════════\n// TOOL DEPENDENCIES\n// ═══════════════════════════════════════════════════════════════════════════════\n\n/\n Shared dependencies available to all tool domain factories.\n * Passed by `createChatTools` after compiling all subgraphs.\n /\nexport interface ToolDeps {\n /* @deprecated Use userDb or systemDb instead. Kept for backwards compatibility. /\n database: ChatGraphCompositeDatabase;\n /* Context-bound database for accessing the authenticated user's own resources. /\n userDb: UserDatabase;\n /* Context-bound database for LLM/system operations on cross-user resources within shared indexes. /\n systemDb: SystemDatabase;\n scraper: Scraper;\n embedder: import('../interfaces/embedder.interface.js').Embedder;\n cache: Cache;\n integration: IntegrationAdapter;\n contactService: ContactServiceAdapter;\n /\n When false (or unset), the contact import / manual-add tools\n * (import_contacts, add_contact, import_gmail_contacts) are not registered.\n * Injected by the composition root from CONTACTS_ENABLED. Read/remove/search\n * contact tools are always registered.\n /\n contactsEnabled?: boolean;\n integrationImporter: {\n importContacts(userId: string, toolkit: string): Promise<{\n imported: number;\n skipped: number;\n newContacts: number;\n existingContacts: number;\n }>;\n };\n enricher: ProfileEnricher;\n /* Database adapter for negotiation/conversation operations. /\n negotiationDatabase: NegotiationGraphDatabase;\n /* Chat session reader for exposing the caller's past conversations as MCP tools. /\n chatSession?: ChatSessionReader;\n /* Read-through chat-session digest. Optional; consumers fall back to undefined `chatContext`. /\n chatSummary?: ChatSummaryReader;\n /\n Test seam for opportunity discovery helpers. Production compositions leave\n * this unset so tools call the real discovery module directly.\n /\n opportunityDiscovery?: {\n runDiscoverFromQuery?: (input: unknown) => Promise<unknown>;\n continueDiscovery?: (input: unknown) => Promise<unknown>;\n };\n /\n Test seam for opportunity card presentation helpers. Production\n * compositions leave this unset so tools construct the real presenter.\n /\n opportunityPresentation?: {\n createPresenter?: () => { presentHomeCard(input: unknown): Promise<unknown> };\n gatherPresenterContext?: (...args: unknown[]) => Promise<unknown>;\n };\n /* Writes user messages into the user's most-recent chat session (Slice 5 MCP elicitation). /\n chatMessageWriter?: ChatMessageWriter;\n /* Decision-question generator. Optional; consumers fall back to no `questions`. /\n questionGenerator?: QuestionGeneratorReader;\n /\n Optional async question enqueue callback. When provided, question generation\n * is dispatched asynchronously to the QuestionerQueue instead of running inline\n * via the `questionGenerator`. Injected by the composition root when\n * QUESTIONER_ENABLED=true.\n /\n questionerEnqueue?: QuestionerEnqueueFn;\n /\n Lookup pending questions for a user, optionally filtered by source,\n * detection mode, or capped by count (hosts apply `limit` SQL-side).\n * Used by tools to attach contextually relevant questions to their results.\n * Injected by the composition root — absent when question delivery is disabled.\n /\n findPendingQuestions?: (\n userId: string,\n filters?: {\n sourceType?: string;\n sourceId?: string;\n /* Restrict to questions whose detection mode is in this set. /\n modes?: QuestionMode[];\n /* Maximum rows to return; hosts should apply this in the query. /\n limit?: number;\n },\n ) => Promise<PendingQuestionSummary[]>;\n /* Negotiation-digest summarizer. Optional; consumers fall back to deterministic digests. /\n negotiationSummary?: NegotiationSummaryReader;\n /* Manages negotiation timeout jobs (optional — enables AI fallback on external agent timeout). /\n negotiationTimeoutQueue?: NegotiationTimeoutQueue;\n /* Agent registry database adapter (optional — absent when host does not support agents). /\n agentDatabase?: AgentDatabase;\n /* Grants the default system-agent permissions after onboarding (optional). /\n grantDefaultSystemPermissions?: (userId: string) => Promise<void>;\n /* Dispatcher for routing negotiation turns to personal agents (optional — falls back to system AI). /\n agentDispatcher?: AgentDispatcher;\n /* Delivery ledger for committing opportunity delivery rows (optional — absent in chat context). /\n deliveryLedger?: DeliveryLedger;\n /* Persistence for async MCP discovery runs (optional — absent in non-MCP/test contexts). /\n discoveryRuns?: DiscoveryRunStore;\n /* Queue for async MCP discovery run execution (optional — absent in non-MCP/test contexts). /\n discoveryRunQueue?: DiscoveryRunQueue;\n /* Persistence for async MCP profile runs (optional — absent in non-MCP/test contexts). /\n enrichmentRuns?: EnrichmentRunStore;\n /* Queue for async MCP profile run execution (optional — absent in non-MCP/test contexts). /\n enrichmentRunQueue?: EnrichmentRunQueue;\n /\n Legacy direct-token minting for opportunity accept redirects.\n * Prefer `mintConnectLink` for user-facing links.\n /\n mintConnectToken?: (userId: string, opportunityId: string) => Promise<string>;\n /* Mints (or reuses) a short connect link, snapshotting the greeting (optional — absent in non-MCP contexts). /\n mintConnectLink?: MintConnectLink;\n /* Frontend base URL for building profile links (e.g. https://index.network, optional). /\n frontendUrl?: string;\n /* API base URL for building opportunity accept links (e.g. https://protocol.index.network, optional). /\n apiBaseUrl?: string;\n /* Optional host-side error reporter for swallowed protocol/tool errors. /\n reportToolError?: (error: unknown, report: ToolErrorReport) => void;\n /\n Optional host-side per-principal MCP call throttle. Invoked once per MCP\n * tool dispatch (after identity resolves, before any DB work). When the\n * returned decision is `allowed: false`, the dispatch short-circuits with a\n * rate-limit error carrying `retryAfterSec`. Absent in chat/test contexts.\n /\n mcpRateLimiter?: (input: { userId: string; agentId?: string; toolName: string }) => Promise<{\n allowed: boolean;\n retryAfterSec?: number;\n limit?: number;\n scope?: 'tool' \| 'principal';\n }>;\n /* Optional premise lifecycle event callbacks. Fired by premise tools after successful operations. /\n premiseEvents?: {\n onCreated?: (premiseId: string, userId: string) => void;\n onUpdated?: (premiseId: string, userId: string) => void;\n onRetracted?: (premiseId: string, userId: string) => void;\n };\n graphs: {\n profile: CompiledGraph;\n intent: CompiledGraph;\n index: CompiledGraph;\n networkMembership: CompiledGraph;\n intentIndex: CompiledGraph;\n opportunity: CompiledOpportunityGraph;\n premise: CompiledGraph;\n };\n /\n Optional network ranking override for `read_networks`. Injected by tests or custom compositions.\n * When absent, defaults to `NetworkRecommender.invoke()` with a lazy module-level singleton.\n /\n networkRanker?: (input: {\n userContext: string;\n networks: Array<{ networkId: string; renderedContext: string }>;\n }) => Promise<{ rankedNetworkIds: string[] } \| null>;\n /\n Resolve a user's global user_context paragraph (profile-replacing identity text),\n * generating it on demand when absent. Injected by the backend composition root\n * (`ensureGlobalUserContext`). When absent, onboarding network ranking is skipped.\n /\n getUserContextText?: (userId: string) => Promise<string>;\n}\n\n// ═══════════════════════════════════════════════════════════════════════════════\n// TOOL RESULT HELPERS\n// ═══════════════════════════════════════════════════════════════════════════════\n\nexport function success<T>(data: T): string {\n return JSON.stringify({ success: true, data });\n}\n\nexport function error(\n message: string,\n debugSteps?: Array<{ step: string; detail?: string; data?: Record<string, unknown> }>\n): string {\n return JSON.stringify({\n success: false,\n error: message,\n ...(debugSteps?.length ? { debugSteps } : {}),\n });\n}\n\n/* Return needsClarification for missing required fields. /\nexport function needsClarification(params: {\n missingFields: string[];\n message: string;\n}): string {\n return JSON.stringify({\n success: false,\n needsClarification: true,\n ...params,\n });\n}\n\n// ═══════════════════════════════════════════════════════════════════════════════\n// CONSTANTS & UTILITIES\n// ═══════════════════════════════════════════════════════════════════════════════\n\n/* Matches http/https URLs in text; captures full URL. /\nconst URL_IN_TEXT_REGEX = /https?:\\/\\/[^\\s\"'<>)\\]]+/gi;\n\n/\n Matches bare domain URLs without protocol (e.g. github.com/foo, www.example.com).\n * Requires at least a SLD.TLD pattern followed by optional path.\n * Negative lookbehind ensures we don't double-match URLs already caught by URL_IN_TEXT_REGEX.\n /\nconst BARE_URL_REGEX = /(?<!\\w:\\/\\/)(?<![/\\w])(?:www\\.)?[a-z0-9](?:[a-z0-9-][a-z0-9])?\\.(?:com\|org\|net\|io\|dev\|co\|ai\|app\|xyz\|me\|info\|gg\|so\|sh\|cc\|ly\|fm\|tv\|to\|tech\|design\|network\|world\|edu\|gov\|mil\|int\|us\|uk\|eu\|de\|fr\|ca\|au\|jp\|cn\|in\|br\|nl\|se\|no\|fi\|dk\|ch\|at\|be\|it\|es\|pt\|pl\|cz\|ru\|kr\|tw\|hk\|sg\|nz\|za\|mx\|ar\|cl\|id\|ph\|th\|vn\|my\|ie)(?:\\/[^\\s\"'<>)\\]])?/gi;\n\n/* UUID v4 format: 8-4-4-4-12 hex chars (e.g. c2505011-2e45-426e-81dd-b9abb9b72023) /\nexport const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\n\n/\n Resolves an array of network IDs to their display titles.\n * Skips any IDs that don't resolve (deleted or invalid networks).\n /\nexport async function resolveIndexNames(\n database: { getNetwork(id: string): Promise<{ id: string; title: string } \| null> },\n networkIds: string[]\n): Promise<string[]> {\n if (networkIds.length === 0) return [];\n const results = await Promise.all(\n networkIds.map(id => database.getNetwork(id))\n );\n return results.filter(Boolean).map(idx => idx!.title);\n}\n\n/\n Normalize a URL string: if it lacks a protocol, prepend \"https://\".\n * Returns the normalized URL or null if the result is not a valid URL.\n /\nexport function normalizeUrl(raw: string): string \| null {\n let url = raw.replace(/[.,;:!?)]+$/, \"\").trim();\n if (!/^https?:\\/\\//i.test(url)) {\n url = `https://${url}`;\n }\n try {\n new URL(url);\n return url;\n } catch {\n return null;\n }\n}\n\n/\n Extract unique, valid URLs from a string (e.g. user message or details).\n * Handles both full URLs (https://...) and bare domains (github.com/...).\n /\nexport function extractUrls(text: string): string[] {\n if (!text \|\| typeof text !== \"string\") return [];\n\n const seen = new Set<string>();\n const out: string[] = [];\n\n // Pass 1: full protocol URLs\n const fullMatches = text.match(URL_IN_TEXT_REGEX) ?? [];\n for (const raw of fullMatches) {\n const url = normalizeUrl(raw);\n if (url && !seen.has(url)) {\n seen.add(url);\n out.push(url);\n }\n }\n\n // Pass 2: bare domain URLs (e.g. github.com/foo)\n const bareMatches = text.match(BARE_URL_REGEX) ?? [];\n for (const raw of bareMatches) {\n const url = normalizeUrl(raw);\n if (url && !seen.has(url)) {\n seen.add(url);\n out.push(url);\n }\n }\n\n return out;\n}\n\nconst SENSITIVE_FIELD_KEYS = new Set([\n \"secret\",\n \"webhooksecret\",\n \"password\",\n \"apikey\",\n \"token\",\n \"accesstoken\",\n \"refreshtoken\",\n \"privatekey\",\n \"authtoken\",\n \"bearertoken\",\n \"clientsecret\",\n]);\n\n/\n Recursively redacts sensitive field values from an arbitrary payload before\n * it is passed to a structured logger. Matches field names case-insensitively\n * and ignoring underscores, so `api_key`, `apiKey`, and `API_KEY` all match.\n * Non-sensitive fields are passed through unchanged. Never mutates the input —\n * returns a new value.\n \n Intended for structured-log redaction only. Do NOT use as a security\n * boundary for data in motion.\n \n @param value - Arbitrary JSON-like payload (query object, config blob, etc.)\n * @returns A new value with sensitive fields replaced by `\"[redacted]\"`.\n */\nexport function redactSensitiveFields(value: unknown): unknown {\n if (value === null \|\| typeof value !== \"object\") return value;\n if (Array.isArray(value)) {\n return value.map((item) => redactSensitiveFields(item));\n }\n const out: Record<string, unknown> = {};\n for (const [key, inner] of Object.entries(value as Record<string, unknown>)) {\n const normalized = key.toLowerCase().replace(/_/g, \"\");\n if (SENSITIVE_FIELD_KEYS.has(normalized)) {\n out[key] = \"[redacted]\";\n } else {\n out[key] = redactSensitiveFields(inner);\n }\n }\n return out;\n}\n"]}

package/dist/shared/agent/tool.registry.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"tool.registry.d.ts","sourceRoot":"/","sources":["shared/agent/tool.registry.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAmC,QAAQ,EAAqB,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAmBpH;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,GAAG,YAAY,~~CA6D~~/D"}
1	+ {"version":3,"file":"tool.registry.d.ts","sourceRoot":"/","sources":["shared/agent/tool.registry.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAmC,QAAQ,EAAqB,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAmBpH;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,GAAG,YAAY,CAwF/D"}

package/dist/shared/agent/tool.registry.js CHANGED Viewed

@@ -1,5 +1,5 @@
 import { error, redactSensitiveFields } from './tool.helpers.js';
-import { createProfileTools } from '../../profile/profile.tools.js';
+import { createEnrichmentTools } from '../../enrichment/enrichment.tools.js';
 import { createIntentTools } from '../../intent/intent.tools.js';
 import { createNetworkTools } from '../../network/network.tools.js';
 import { createOpportunityTools } from '../../opportunity/opportunity.tools.js';
@@ -59,7 +59,7 @@ export function createToolRegistry(deps) {
     // Create all tool domains -- each one calls defineTool() which populates the registry.
     // The local defineTool is compatible with DefineTool (which returns any).
     const dt = defineTool;
-    createProfileTools(dt, deps);
+    createEnrichmentTools(dt, deps);
     createIntentTools(dt, deps);
     createNetworkTools(dt, deps);
     createOpportunityTools(dt, deps);
@@ -73,6 +73,32 @@ export function createToolRegistry(deps) {
     if (deps.chatSession) {
         createChatTools(dt, deps);
     }
+    // Deprecated tool-name aliases (IND-371). The canonical implementations are now
+    // registered under their *_user_context / *_enrichment_run names; we expose the
+    // legacy *_user_profile / *_profile_run names as thin aliases that delegate to the
+    // exact same handler + schema, so existing MCP clients keep working while they
+    // migrate. The old names are removed in IND-373.
+    const DEPRECATED_TOOL_ALIASES = [
+        ["read_user_profiles", "read_user_contexts"],
+        ["create_user_profile", "create_user_context"],
+        ["update_user_profile", "update_user_context"],
+        ["confirm_user_profile", "confirm_user_context"],
+        ["preview_user_profile", "preview_user_context"],
+        ["get_profile_run", "get_enrichment_run"],
+        ["cancel_profile_run", "cancel_enrichment_run"],
+    ];
+    for (const [oldName, canonicalName] of DEPRECATED_TOOL_ALIASES) {
+        const canonical = registry.get(canonicalName);
+        if (!canonical) {
+            logger.warn(`Cannot register deprecated alias ${oldName}: canonical ${canonicalName} not found`);
+            continue;
+        }
+        registry.set(oldName, {
+            ...canonical,
+            name: oldName,
+            description: `[DEPRECATED — use \`${canonicalName}\` instead; this alias is retained for backward compatibility and will be removed.] ${canonical.description}`,
+        });
+    }
     logger.verbose(`Tool registry created with ${registry.size} tools`);
     return registry;
 }

package/dist/shared/agent/tool.registry.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"tool.registry.js","sourceRoot":"/","sources":["shared/agent/tool.registry.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,~~kBAAkB~~,EAAE,MAAM,~~gCAAgC~~,CAAC;~~AACpE~~,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAErE,MAAM,MAAM,GAAG,cAAc,CAAC,cAAc,CAAC,CAAC;AAE9C;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAc;IAC/C,MAAM,QAAQ,GAAiB,IAAI,GAAG,EAAE,CAAC;IAEzC,0DAA0D;IAC1D,SAAS,UAAU,CAAsB,IAKxC;QACC,MAAM,KAAK,GAAsB;YAC/B,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,MAAM,EAAE,IAAI,CAAC,WAAW;YACxB,OAAO,EAAE,KAAK,EAAE,KAAuD,EAAE,EAAE;gBACzE,MAAM,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,IAAI,EAAE,EAAE;oBACnC,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE;oBAC7E,KAAK,EAAE,qBAAqB,CAAC,KAAK,CAAC,KAAK,CAAC;iBAC1C,CAAC,CAAC;gBACH,IAAI,CAAC;oBACH,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAmB,EAAE,CAAC,CAAC;gBAC1F,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,WAAW,GAAG,cAAc,CAAC,QAAQ,EAAE,EAAE,WAAW,CAAC;oBAC3D,IAAI,WAAW,EAAE,OAAO,EAAE,CAAC;wBACzB,MAAM,GAAG,CAAC;oBACZ,CAAC;oBACD,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,SAAS,EAAE;wBAClC,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;qBACxD,CAAC,CAAC;oBACH,OAAO,KAAK,CAAC,qBAAqB,IAAI,CAAC,IAAI,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACtG,CAAC;YACH,CAAC;SACF,CAAC;QAEF,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAE/B,6EAA6E;QAC7E,qEAAqE;QACrE,OAAO,IAAe,CAAC;IACzB,CAAC;IAED,uFAAuF;IACvF,0EAA0E;IAC1E,MAAM,EAAE,GAAG,UAAwB,CAAC;IACpC,~~kBAAkB~~,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;~~IAC7B~~,iBAAiB,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC5B,kBAAkB,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC7B,sBAAsB,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACjC,kBAAkB,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC7B,sBAAsB,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACjC,kBAAkB,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC7B,gBAAgB,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC3B,sBAAsB,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACjC,kBAAkB,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC7B,qBAAqB,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAChC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,eAAe,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,MAAM,CAAC,OAAO,CAAC,8BAA8B,QAAQ,CAAC,IAAI,QAAQ,CAAC,CAAC;IACpE,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["import { z } from 'zod';\n\nimport type { DefineTool, ResolvedToolContext, ToolDeps, RawToolDefinition, ToolRegistry } from './tool.helpers.js';\nimport { error, redactSensitiveFields } from './tool.helpers.js';\nimport { ~~createProfileTools~~ } from '../../~~profile~~/~~profile~~.tools.js';\nimport { createIntentTools } from '../../intent/intent.tools.js';\nimport { createNetworkTools } from '../../network/network.tools.js';\nimport { createOpportunityTools } from '../../opportunity/opportunity.tools.js';\nimport { createUtilityTools } from './utility.tools.js';\nimport { createIntegrationTools } from '../../integration/integration.tools.js';\nimport { createContactTools } from '../../contact/contact.tools.js';\nimport { createAgentTools } from '../../agent/agent.tools.js';\nimport { createNegotiationTools } from '../../negotiation/negotiation.tools.js';\nimport { createChatTools } from '../../chat/chat.tools.js';\nimport { createPremiseTools } from '../../premise/premise.tools.js';\nimport { createQuestionerTools } from '../../questioner/questioner.tools.js';\nimport { protocolLogger } from '../observability/protocol.logger.js';\nimport { requestContext } from '../observability/request-context.js';\n\nconst logger = protocolLogger('ToolRegistry');\n\n/*\n Creates a tool registry containing all tool handlers indexed by name.\n * Handlers are raw async functions (not LangChain tool() wrappers) that\n * accept { context, query } and return a JSON string.\n \n @param deps - Shared tool dependencies (graphs, database, embedder, etc.)\n * @param context - Resolved user context for this request.\n * @returns Map of tool name to raw tool definition.\n /\nexport function createToolRegistry(deps: ToolDeps): ToolRegistry {\n const registry: ToolRegistry = new Map();\n\n // defineTool that captures raw handlers into the registry\n function defineTool<T extends z.ZodType>(opts: {\n name: string;\n description: string;\n querySchema: T;\n handler: (input: { context: ResolvedToolContext; query: z.infer<T> }) => Promise<string>;\n }) {\n const entry: RawToolDefinition = {\n name: opts.name,\n description: opts.description,\n schema: opts.querySchema,\n handler: async (input: { context: ResolvedToolContext; query: unknown }) => {\n logger.verbose(`Tool: ${opts.name}`, {\n context: { userId: input.context.userId, networkId: input.context.networkId },\n query: redactSensitiveFields(input.query),\n });\n try {\n return await opts.handler({ context: input.context, query: input.query as z.infer<T> });\n } catch (err) {\n const abortSignal = requestContext.getStore()?.abortSignal;\n if (abortSignal?.aborted) {\n throw err;\n }\n logger.error(`${opts.name} failed`, {\n error: err instanceof Error ? err.message : String(err),\n });\n return error(`Failed to execute ${opts.name}: ${err instanceof Error ? err.message : String(err)}`);\n }\n },\n };\n\n registry.set(opts.name, entry);\n\n // Return a dummy — createTools functions collect return values into arrays,\n // but for the registry path we only need the side-effect on the Map.\n return null as unknown;\n }\n\n // Create all tool domains -- each one calls defineTool() which populates the registry.\n // The local defineTool is compatible with DefineTool (which returns any).\n const dt = defineTool as DefineTool;\n ~~createProfileTools~~(dt, deps);\n createIntentTools(dt, deps);\n createNetworkTools(dt, deps);\n createOpportunityTools(dt, deps);\n createUtilityTools(dt, deps);\n createIntegrationTools(dt, deps);\n createContactTools(dt, deps);\n createAgentTools(dt, deps);\n createNegotiationTools(dt, deps);\n createPremiseTools(dt, deps);\n createQuestionerTools(dt, deps);\n if (deps.chatSession) {\n createChatTools(dt, deps);\n }\n\n logger.verbose(`Tool registry created with ${registry.size} tools`);\n return registry;\n}\n"]}
1	+ {"version":3,"file":"tool.registry.js","sourceRoot":"/","sources":["shared/agent/tool.registry.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\n\nimport type { DefineTool, ResolvedToolContext, ToolDeps, RawToolDefinition, ToolRegistry } from './tool.helpers.js';\nimport { error, redactSensitiveFields } from './tool.helpers.js';\nimport { createEnrichmentTools } from '../../enrichment/enrichment.tools.js';\nimport { createIntentTools } from '../../intent/intent.tools.js';\nimport { createNetworkTools } from '../../network/network.tools.js';\nimport { createOpportunityTools } from '../../opportunity/opportunity.tools.js';\nimport { createUtilityTools } from './utility.tools.js';\nimport { createIntegrationTools } from '../../integration/integration.tools.js';\nimport { createContactTools } from '../../contact/contact.tools.js';\nimport { createAgentTools } from '../../agent/agent.tools.js';\nimport { createNegotiationTools } from '../../negotiation/negotiation.tools.js';\nimport { createChatTools } from '../../chat/chat.tools.js';\nimport { createPremiseTools } from '../../premise/premise.tools.js';\nimport { createQuestionerTools } from '../../questioner/questioner.tools.js';\nimport { protocolLogger } from '../observability/protocol.logger.js';\nimport { requestContext } from '../observability/request-context.js';\n\nconst logger = protocolLogger('ToolRegistry');\n\n/*\n Creates a tool registry containing all tool handlers indexed by name.\n * Handlers are raw async functions (not LangChain tool() wrappers) that\n * accept { context, query } and return a JSON string.\n \n @param deps - Shared tool dependencies (graphs, database, embedder, etc.)\n * @param context - Resolved user context for this request.\n * @returns Map of tool name to raw tool definition.\n /\nexport function createToolRegistry(deps: ToolDeps): ToolRegistry {\n const registry: ToolRegistry = new Map();\n\n // defineTool that captures raw handlers into the registry\n function defineTool<T extends z.ZodType>(opts: {\n name: string;\n description: string;\n querySchema: T;\n handler: (input: { context: ResolvedToolContext; query: z.infer<T> }) => Promise<string>;\n }) {\n const entry: RawToolDefinition = {\n name: opts.name,\n description: opts.description,\n schema: opts.querySchema,\n handler: async (input: { context: ResolvedToolContext; query: unknown }) => {\n logger.verbose(`Tool: ${opts.name}`, {\n context: { userId: input.context.userId, networkId: input.context.networkId },\n query: redactSensitiveFields(input.query),\n });\n try {\n return await opts.handler({ context: input.context, query: input.query as z.infer<T> });\n } catch (err) {\n const abortSignal = requestContext.getStore()?.abortSignal;\n if (abortSignal?.aborted) {\n throw err;\n }\n logger.error(`${opts.name} failed`, {\n error: err instanceof Error ? err.message : String(err),\n });\n return error(`Failed to execute ${opts.name}: ${err instanceof Error ? err.message : String(err)}`);\n }\n },\n };\n\n registry.set(opts.name, entry);\n\n // Return a dummy — createTools functions collect return values into arrays,\n // but for the registry path we only need the side-effect on the Map.\n return null as unknown;\n }\n\n // Create all tool domains -- each one calls defineTool() which populates the registry.\n // The local defineTool is compatible with DefineTool (which returns any).\n const dt = defineTool as DefineTool;\n createEnrichmentTools(dt, deps);\n createIntentTools(dt, deps);\n createNetworkTools(dt, deps);\n createOpportunityTools(dt, deps);\n createUtilityTools(dt, deps);\n createIntegrationTools(dt, deps);\n createContactTools(dt, deps);\n createAgentTools(dt, deps);\n createNegotiationTools(dt, deps);\n createPremiseTools(dt, deps);\n createQuestionerTools(dt, deps);\n if (deps.chatSession) {\n createChatTools(dt, deps);\n }\n\n // Deprecated tool-name aliases (IND-371). The canonical implementations are now\n // registered under their _user_context / _enrichment_run names; we expose the\n // legacy _user_profile / _profile_run names as thin aliases that delegate to the\n // exact same handler + schema, so existing MCP clients keep working while they\n // migrate. The old names are removed in IND-373.\n const DEPRECATED_TOOL_ALIASES: ReadonlyArray<readonly [oldName: string, canonicalName: string]> = [\n [\"read_user_profiles\", \"read_user_contexts\"],\n [\"create_user_profile\", \"create_user_context\"],\n [\"update_user_profile\", \"update_user_context\"],\n [\"confirm_user_profile\", \"confirm_user_context\"],\n [\"preview_user_profile\", \"preview_user_context\"],\n [\"get_profile_run\", \"get_enrichment_run\"],\n [\"cancel_profile_run\", \"cancel_enrichment_run\"],\n ];\n for (const [oldName, canonicalName] of DEPRECATED_TOOL_ALIASES) {\n const canonical = registry.get(canonicalName);\n if (!canonical) {\n logger.warn(`Cannot register deprecated alias ${oldName}: canonical ${canonicalName} not found`);\n continue;\n }\n registry.set(oldName, {\n ...canonical,\n name: oldName,\n description: `[DEPRECATED — use \\`${canonicalName}\\` instead; this alias is retained for backward compatibility and will be removed.] ${canonical.description}`,\n });\n }\n\n logger.verbose(`Tool registry created with ${registry.size} tools`);\n return registry;\n}\n"]}

package/dist/shared/agent/tool.runtime.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"tool.runtime.d.ts","sourceRoot":"/","sources":["shared/agent/tool.runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAGxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAEhF,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,cAAc,GAAG,iBAAiB,CAAC;AAC3E,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG,gBAAgB,GAAG,uBAAuB,CAAC;AAE/F,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,gBAAgB,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,IAAI,CAAC,iBAAiB,EAAE,SAAS,CAAC,CAAC;IACzC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;~~AAmED~~,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CA0BxE;AAED,qBAAa,gBAAiB,SAAQ,KAAK;aAEvB,IAAI,EAAE,oBAAoB;aAE1B,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,iBAAiB;gBAHzB,IAAI,EAAE,oBAAoB,EAC1C,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,iBAAiB;CAK5C;AA+CD,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAE1F;AA4DD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAapE"}
1	+ {"version":3,"file":"tool.runtime.d.ts","sourceRoot":"/","sources":["shared/agent/tool.runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAGxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAEhF,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,cAAc,GAAG,iBAAiB,CAAC;AAC3E,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG,gBAAgB,GAAG,uBAAuB,CAAC;AAE/F,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,gBAAgB,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,IAAI,CAAC,iBAAiB,EAAE,SAAS,CAAC,CAAC;IACzC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAyED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CA0BxE;AAED,qBAAa,gBAAiB,SAAQ,KAAK;aAEvB,IAAI,EAAE,oBAAoB;aAE1B,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,iBAAiB;gBAHzB,IAAI,EAAE,oBAAoB,EAC1C,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,iBAAiB;CAK5C;AA+CD,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAE1F;AA4DD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAapE"}

package/dist/shared/agent/tool.runtime.js CHANGED Viewed

@@ -31,6 +31,12 @@ const FAST_TOOLS = new Set([
     "retract_premise",
 ]);
 const ASYNC_CANDIDATE_TOOLS = new Set([
+    // Canonical *_user_context names (IND-371)
+    "read_user_contexts",
+    "preview_user_context",
+    "create_user_context",
+    "update_user_context",
+    // Deprecated *_user_profile aliases (kept until IND-373 retires them)
     "read_user_profiles",
     "preview_user_profile",
     "create_user_profile",

package/dist/shared/agent/tool.runtime.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"tool.runtime.js","sourceRoot":"/","sources":["shared/agent/tool.runtime.ts"],"names":[],"mappings":"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","sourcesContent":["import { timed } from \"../observability/performance.js\";\nimport type { TraceEmitter } from \"../observability/request-context.js\";\nimport { requestContext } from \"../observability/request-context.js\";\n\nimport type { RawToolDefinition, ResolvedToolContext } from \"./tool.helpers.js\";\n\nexport type ToolTimeoutClass = \"fast\" \| \"bounded_slow\" \| \"async_candidate\";\nexport type ToolRuntimeErrorCode = \"TOOL_TIMEOUT\" \| \"TOOL_CANCELLED\" \| \"TOOL_OUTPUT_TOO_LARGE\";\n\nexport interface ToolTimeoutPolicy {\n class: ToolTimeoutClass;\n timeoutMs: number;\n maxOutputBytes: number;\n}\n\nexport interface ToolInvocationRuntimeInput {\n toolName: string;\n tool: Pick<RawToolDefinition, \"handler\">;\n context: ResolvedToolContext;\n query: unknown;\n signal?: AbortSignal;\n traceEmitter?: TraceEmitter;\n timeoutMs?: number;\n maxOutputBytes?: number;\n}\n\nconst FAST_TIMEOUT_MS = 10_000;\nconst BOUNDED_SLOW_TIMEOUT_MS = 45_000;\nconst ASYNC_CANDIDATE_TIMEOUT_MS = 50_000;\nconst DEFAULT_MAX_OUTPUT_BYTES = 1_000_000;\n\nconst FAST_TOOLS = new Set([\n \"record_onboarding_privacy_consent\",\n \"create_intent_index\",\n \"delete_intent_index\",\n \"search_intents\",\n \"read_networks\",\n \"update_network\",\n \"create_network\",\n \"delete_network\",\n \"create_network_membership\",\n \"delete_network_membership\",\n \"confirm_opportunity_delivery\",\n \"read_docs\",\n \"get_discovery_run\",\n \"cancel_discovery_run\",\n \"get_profile_run\",\n \"cancel_profile_run\",\n \"remove_contact\",\n \"register_agent\",\n \"list_agents\",\n \"update_agent\",\n \"delete_agent\",\n \"grant_agent_permission\",\n \"revoke_agent_permission\",\n \"retract_premise\",\n]);\n\nconst ASYNC_CANDIDATE_TOOLS = new Set([\n \"read_user_profiles\",\n \"preview_user_profile\",\n \"create_user_profile\",\n \"update_user_profile\",\n \"create_intent\",\n \"update_intent\",\n \"discover_opportunities\",\n \"scrape_url\",\n \"import_gmail_contacts\",\n \"import_contacts\",\n \"respond_to_negotiation\",\n \"create_premise\",\n \"update_premise\",\n]);\n\nfunction parsePositiveIntEnv(name: string, fallback: number): number {\n const raw = process.env[name];\n if (!raw) return fallback;\n const parsed = Number.parseInt(raw, 10);\n return Number.isFinite(parsed) && parsed > 0 && parsed <= Number.MAX_SAFE_INTEGER\n ? parsed\n : fallback;\n}\n\nfunction toolNameEnv(toolName: string): string {\n return `MCP_TOOL_TIMEOUT_${toolName.toUpperCase().replace(/[^A-Z0-9]+/g, \"_\")}_MS`;\n}\n\nfunction toolNameOutputEnv(toolName: string): string {\n return `MCP_TOOL_MAX_OUTPUT_${toolName.toUpperCase().replace(/[^A-Z0-9]+/g, \"_\")}_BYTES`;\n}\n\nexport function getToolTimeoutPolicy(toolName: string): ToolTimeoutPolicy {\n const classification: ToolTimeoutClass = FAST_TOOLS.has(toolName)\n ? \"fast\"\n : ASYNC_CANDIDATE_TOOLS.has(toolName)\n ? \"async_candidate\"\n : \"bounded_slow\";\n\n let classDefault: number;\n switch (classification) {\n case \"fast\":\n classDefault = parsePositiveIntEnv(\"MCP_TOOL_TIMEOUT_FAST_MS\", FAST_TIMEOUT_MS);\n break;\n case \"async_candidate\":\n classDefault = parsePositiveIntEnv(\"MCP_TOOL_TIMEOUT_ASYNC_CANDIDATE_MS\", ASYNC_CANDIDATE_TIMEOUT_MS);\n break;\n default:\n classDefault = parsePositiveIntEnv(\"MCP_TOOL_TIMEOUT_BOUNDED_SLOW_MS\", BOUNDED_SLOW_TIMEOUT_MS);\n }\n\n const defaultMaxOutputBytes = parsePositiveIntEnv(\"MCP_TOOL_MAX_OUTPUT_BYTES\", DEFAULT_MAX_OUTPUT_BYTES);\n\n return {\n class: classification,\n timeoutMs: parsePositiveIntEnv(toolNameEnv(toolName), classDefault),\n maxOutputBytes: parsePositiveIntEnv(toolNameOutputEnv(toolName), defaultMaxOutputBytes),\n };\n}\n\nexport class ToolRuntimeError extends Error {\n constructor(\n public readonly code: ToolRuntimeErrorCode,\n message: string,\n public readonly toolName: string,\n public readonly policy: ToolTimeoutPolicy,\n ) {\n super(message);\n this.name = \"ToolRuntimeError\";\n }\n}\n\n/** Builds the typed timeout/cancellation error shared by the abort race and catch paths. */\nfunction makeAbortError(timedOut: boolean, toolName: string, policy: ToolTimeoutPolicy): ToolRuntimeError {\n const code: ToolRuntimeErrorCode = timedOut ? \"TOOL_TIMEOUT\" : \"TOOL_CANCELLED\";\n return new ToolRuntimeError(\n code,\n code === \"TOOL_TIMEOUT\"\n ? `Tool ${toolName} timed out after ${policy.timeoutMs}ms.`\n : `Tool ${toolName} was cancelled before it completed.`,\n toolName,\n policy,\n );\n}\n\nfunction combineSignals(signals: Array<AbortSignal \| undefined>): {\n signal: AbortSignal;\n abort: (reason?: unknown) => void;\n cleanup: () => void;\n} {\n const controller = new AbortController();\n const listeners: Array<() => void> = [];\n\n for (const source of signals) {\n if (!source) continue;\n if (source.aborted) {\n controller.abort(source.reason);\n break;\n }\n const onAbort = () => {\n if (!controller.signal.aborted) controller.abort(source.reason);\n };\n source.addEventListener(\"abort\", onAbort, { once: true });\n listeners.push(() => source.removeEventListener(\"abort\", onAbort));\n }\n\n return {\n signal: controller.signal,\n abort: (reason?: unknown) => {\n if (!controller.signal.aborted) controller.abort(reason);\n },\n cleanup: () => {\n for (const cleanup of listeners) cleanup();\n },\n };\n}\n\nexport async function invokeToolRuntime(input: ToolInvocationRuntimeInput): Promise<string> {\n return timed(`ToolRuntime.${input.toolName}`, () => invokeToolRuntimeInner(input));\n}\n\nasync function invokeToolRuntimeInner(input: ToolInvocationRuntimeInput): Promise<string> {\n const basePolicy = getToolTimeoutPolicy(input.toolName);\n const policy = {\n ...basePolicy,\n ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),\n ...(input.maxOutputBytes !== undefined ? { maxOutputBytes: input.maxOutputBytes } : {}),\n };\n const inherited = requestContext.getStore();\n const combined = combineSignals([input.signal, inherited?.abortSignal]);\n let timedOut = false;\n const timer = setTimeout(() => {\n timedOut = true;\n combined.abort(new Error(`Tool ${input.toolName} timed out after ${policy.timeoutMs}ms`));\n }, policy.timeoutMs);\n\n let removeAbortListener = () => {};\n const abortPromise = new Promise<never>((_, reject) => {\n const onAbort = () => {\n reject(makeAbortError(timedOut, input.toolName, policy));\n };\n combined.signal.addEventListener(\"abort\", onAbort, { once: true });\n removeAbortListener = () => combined.signal.removeEventListener(\"abort\", onAbort);\n });\n\n try {\n const run = () => input.tool.handler({ context: input.context, query: input.query });\n const toolPromise = requestContext.run(\n {\n ...inherited,\n abortSignal: combined.signal,\n traceEmitter: input.traceEmitter ?? inherited?.traceEmitter,\n },\n run,\n );\n const result = await Promise.race([toolPromise, abortPromise]);\n const outputBytes = new TextEncoder().encode(result).byteLength;\n if (outputBytes > policy.maxOutputBytes) {\n throw new ToolRuntimeError(\n \"TOOL_OUTPUT_TOO_LARGE\",\n `Tool ${input.toolName} returned ${outputBytes} bytes, exceeding the ${policy.maxOutputBytes} byte limit.`,\n input.toolName,\n policy,\n );\n }\n return result;\n } catch (err) {\n if (err instanceof ToolRuntimeError) throw err;\n if (combined.signal.aborted) {\n throw makeAbortError(timedOut, input.toolName, policy);\n }\n throw err;\n } finally {\n clearTimeout(timer);\n removeAbortListener();\n combined.cleanup();\n }\n}\n\nexport function toolRuntimeErrorToResult(err: unknown): string \| null {\n if (!(err instanceof ToolRuntimeError)) return null;\n return JSON.stringify({\n success: false,\n code: err.code,\n error: err.message,\n data: {\n tool: err.toolName,\n timeoutClass: err.policy.class,\n timeoutMs: err.policy.timeoutMs,\n maxOutputBytes: err.policy.maxOutputBytes,\n },\n });\n}\n"]}
1	+ {"version":3,"file":"tool.runtime.js","sourceRoot":"/","sources":["shared/agent/tool.runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAC;AAExD,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAwBrE,MAAM,eAAe,GAAG,KAAM,CAAC;AAC/B,MAAM,uBAAuB,GAAG,KAAM,CAAC;AACvC,MAAM,0BAA0B,GAAG,KAAM,CAAC;AAC1C,MAAM,wBAAwB,GAAG,OAAS,CAAC;AAE3C,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;IACzB,mCAAmC;IACnC,qBAAqB;IACrB,qBAAqB;IACrB,gBAAgB;IAChB,eAAe;IACf,gBAAgB;IAChB,gBAAgB;IAChB,gBAAgB;IAChB,2BAA2B;IAC3B,2BAA2B;IAC3B,8BAA8B;IAC9B,WAAW;IACX,mBAAmB;IACnB,sBAAsB;IACtB,iBAAiB;IACjB,oBAAoB;IACpB,gBAAgB;IAChB,gBAAgB;IAChB,aAAa;IACb,cAAc;IACd,cAAc;IACd,wBAAwB;IACxB,yBAAyB;IACzB,iBAAiB;CAClB,CAAC,CAAC;AAEH,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC;IACpC,2CAA2C;IAC3C,oBAAoB;IACpB,sBAAsB;IACtB,qBAAqB;IACrB,qBAAqB;IACrB,sEAAsE;IACtE,oBAAoB;IACpB,sBAAsB;IACtB,qBAAqB;IACrB,qBAAqB;IACrB,eAAe;IACf,eAAe;IACf,wBAAwB;IACxB,YAAY;IACZ,uBAAuB;IACvB,iBAAiB;IACjB,wBAAwB;IACxB,gBAAgB;IAChB,gBAAgB;CACjB,CAAC,CAAC;AAEH,SAAS,mBAAmB,CAAC,IAAY,EAAE,QAAgB;IACzD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACxC,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,IAAI,MAAM,IAAI,MAAM,CAAC,gBAAgB;QAC/E,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,QAAQ,CAAC;AACf,CAAC;AAED,SAAS,WAAW,CAAC,QAAgB;IACnC,OAAO,oBAAoB,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,KAAK,CAAC;AACrF,CAAC;AAED,SAAS,iBAAiB,CAAC,QAAgB;IACzC,OAAO,uBAAuB,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,QAAQ,CAAC;AAC3F,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,QAAgB;IACnD,MAAM,cAAc,GAAqB,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC;QAC/D,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,qBAAqB,CAAC,GAAG,CAAC,QAAQ,CAAC;YACnC,CAAC,CAAC,iBAAiB;YACnB,CAAC,CAAC,cAAc,CAAC;IAErB,IAAI,YAAoB,CAAC;IACzB,QAAQ,cAAc,EAAE,CAAC;QACvB,KAAK,MAAM;YACT,YAAY,GAAG,mBAAmB,CAAC,0BAA0B,EAAE,eAAe,CAAC,CAAC;YAChF,MAAM;QACR,KAAK,iBAAiB;YACpB,YAAY,GAAG,mBAAmB,CAAC,qCAAqC,EAAE,0BAA0B,CAAC,CAAC;YACtG,MAAM;QACR;YACE,YAAY,GAAG,mBAAmB,CAAC,kCAAkC,EAAE,uBAAuB,CAAC,CAAC;IACpG,CAAC;IAED,MAAM,qBAAqB,GAAG,mBAAmB,CAAC,2BAA2B,EAAE,wBAAwB,CAAC,CAAC;IAEzG,OAAO;QACL,KAAK,EAAE,cAAc;QACrB,SAAS,EAAE,mBAAmB,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;QACnE,cAAc,EAAE,mBAAmB,CAAC,iBAAiB,CAAC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;KACxF,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC,YACkB,IAA0B,EAC1C,OAAe,EACC,QAAgB,EAChB,MAAyB;QAEzC,KAAK,CAAC,OAAO,CAAC,CAAC;QALC,SAAI,GAAJ,IAAI,CAAsB;QAE1B,aAAQ,GAAR,QAAQ,CAAQ;QAChB,WAAM,GAAN,MAAM,CAAmB;QAGzC,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED,4FAA4F;AAC5F,SAAS,cAAc,CAAC,QAAiB,EAAE,QAAgB,EAAE,MAAyB;IACpF,MAAM,IAAI,GAAyB,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,gBAAgB,CAAC;IAChF,OAAO,IAAI,gBAAgB,CACzB,IAAI,EACJ,IAAI,KAAK,cAAc;QACrB,CAAC,CAAC,QAAQ,QAAQ,oBAAoB,MAAM,CAAC,SAAS,KAAK;QAC3D,CAAC,CAAC,QAAQ,QAAQ,qCAAqC,EACzD,QAAQ,EACR,MAAM,CACP,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,OAAuC;IAK7D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,SAAS,GAAsB,EAAE,CAAC;IAExC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC,MAAM;YAAE,SAAS;QACtB,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAChC,MAAM;QACR,CAAC;QACD,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO;gBAAE,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAClE,CAAC,CAAC;QACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IACrE,CAAC;IAED,OAAO;QACL,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,KAAK,EAAE,CAAC,MAAgB,EAAE,EAAE;YAC1B,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO;gBAAE,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC3D,CAAC;QACD,OAAO,EAAE,GAAG,EAAE;YACZ,KAAK,MAAM,OAAO,IAAI,SAAS;gBAAE,OAAO,EAAE,CAAC;QAC7C,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAAiC;IACvE,OAAO,KAAK,CAAC,eAAe,KAAK,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC;AACrF,CAAC;AAED,KAAK,UAAU,sBAAsB,CAAC,KAAiC;IACrE,MAAM,UAAU,GAAG,oBAAoB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG;QACb,GAAG,UAAU;QACb,GAAG,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,GAAG,CAAC,KAAK,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,KAAK,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxF,CAAC;IACF,MAAM,SAAS,GAAG,cAAc,CAAC,QAAQ,EAAE,CAAC;IAC5C,MAAM,QAAQ,GAAG,cAAc,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IACxE,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;QAC5B,QAAQ,GAAG,IAAI,CAAC;QAChB,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,KAAK,CAAC,QAAQ,oBAAoB,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC;IAC5F,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IAErB,IAAI,mBAAmB,GAAG,GAAG,EAAE,GAAE,CAAC,CAAC;IACnC,MAAM,YAAY,GAAG,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;QACpD,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;QAC3D,CAAC,CAAC;QACF,QAAQ,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,mBAAmB,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACpF,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QACrF,MAAM,WAAW,GAAG,cAAc,CAAC,GAAG,CACpC;YACE,GAAG,SAAS;YACZ,WAAW,EAAE,QAAQ,CAAC,MAAM;YAC5B,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,SAAS,EAAE,YAAY;SAC5D,EACD,GAAG,CACJ,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC;QAC/D,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,UAAU,CAAC;QAChE,IAAI,WAAW,GAAG,MAAM,CAAC,cAAc,EAAE,CAAC;YACxC,MAAM,IAAI,gBAAgB,CACxB,uBAAuB,EACvB,QAAQ,KAAK,CAAC,QAAQ,aAAa,WAAW,yBAAyB,MAAM,CAAC,cAAc,cAAc,EAC1G,KAAK,CAAC,QAAQ,EACd,MAAM,CACP,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,gBAAgB;YAAE,MAAM,GAAG,CAAC;QAC/C,IAAI,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAC5B,MAAM,cAAc,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACzD,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,mBAAmB,EAAE,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,CAAC;IACrB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,GAAY;IACnD,IAAI,CAAC,CAAC,GAAG,YAAY,gBAAgB,CAAC;QAAE,OAAO,IAAI,CAAC;IACpD,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,OAAO,EAAE,KAAK;QACd,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,KAAK,EAAE,GAAG,CAAC,OAAO;QAClB,IAAI,EAAE;YACJ,IAAI,EAAE,GAAG,CAAC,QAAQ;YAClB,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK;YAC9B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS;YAC/B,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,cAAc;SAC1C;KACF,CAAC,CAAC;AACL,CAAC","sourcesContent":["import { timed } from \"../observability/performance.js\";\nimport type { TraceEmitter } from \"../observability/request-context.js\";\nimport { requestContext } from \"../observability/request-context.js\";\n\nimport type { RawToolDefinition, ResolvedToolContext } from \"./tool.helpers.js\";\n\nexport type ToolTimeoutClass = \"fast\" \| \"bounded_slow\" \| \"async_candidate\";\nexport type ToolRuntimeErrorCode = \"TOOL_TIMEOUT\" \| \"TOOL_CANCELLED\" \| \"TOOL_OUTPUT_TOO_LARGE\";\n\nexport interface ToolTimeoutPolicy {\n class: ToolTimeoutClass;\n timeoutMs: number;\n maxOutputBytes: number;\n}\n\nexport interface ToolInvocationRuntimeInput {\n toolName: string;\n tool: Pick<RawToolDefinition, \"handler\">;\n context: ResolvedToolContext;\n query: unknown;\n signal?: AbortSignal;\n traceEmitter?: TraceEmitter;\n timeoutMs?: number;\n maxOutputBytes?: number;\n}\n\nconst FAST_TIMEOUT_MS = 10_000;\nconst BOUNDED_SLOW_TIMEOUT_MS = 45_000;\nconst ASYNC_CANDIDATE_TIMEOUT_MS = 50_000;\nconst DEFAULT_MAX_OUTPUT_BYTES = 1_000_000;\n\nconst FAST_TOOLS = new Set([\n \"record_onboarding_privacy_consent\",\n \"create_intent_index\",\n \"delete_intent_index\",\n \"search_intents\",\n \"read_networks\",\n \"update_network\",\n \"create_network\",\n \"delete_network\",\n \"create_network_membership\",\n \"delete_network_membership\",\n \"confirm_opportunity_delivery\",\n \"read_docs\",\n \"get_discovery_run\",\n \"cancel_discovery_run\",\n \"get_profile_run\",\n \"cancel_profile_run\",\n \"remove_contact\",\n \"register_agent\",\n \"list_agents\",\n \"update_agent\",\n \"delete_agent\",\n \"grant_agent_permission\",\n \"revoke_agent_permission\",\n \"retract_premise\",\n]);\n\nconst ASYNC_CANDIDATE_TOOLS = new Set([\n // Canonical _user_context names (IND-371)\n \"read_user_contexts\",\n \"preview_user_context\",\n \"create_user_context\",\n \"update_user_context\",\n // Deprecated _user_profile aliases (kept until IND-373 retires them)\n \"read_user_profiles\",\n \"preview_user_profile\",\n \"create_user_profile\",\n \"update_user_profile\",\n \"create_intent\",\n \"update_intent\",\n \"discover_opportunities\",\n \"scrape_url\",\n \"import_gmail_contacts\",\n \"import_contacts\",\n \"respond_to_negotiation\",\n \"create_premise\",\n \"update_premise\",\n]);\n\nfunction parsePositiveIntEnv(name: string, fallback: number): number {\n const raw = process.env[name];\n if (!raw) return fallback;\n const parsed = Number.parseInt(raw, 10);\n return Number.isFinite(parsed) && parsed > 0 && parsed <= Number.MAX_SAFE_INTEGER\n ? parsed\n : fallback;\n}\n\nfunction toolNameEnv(toolName: string): string {\n return `MCP_TOOL_TIMEOUT_${toolName.toUpperCase().replace(/[^A-Z0-9]+/g, \"_\")}_MS`;\n}\n\nfunction toolNameOutputEnv(toolName: string): string {\n return `MCP_TOOL_MAX_OUTPUT_${toolName.toUpperCase().replace(/[^A-Z0-9]+/g, \"_\")}_BYTES`;\n}\n\nexport function getToolTimeoutPolicy(toolName: string): ToolTimeoutPolicy {\n const classification: ToolTimeoutClass = FAST_TOOLS.has(toolName)\n ? \"fast\"\n : ASYNC_CANDIDATE_TOOLS.has(toolName)\n ? \"async_candidate\"\n : \"bounded_slow\";\n\n let classDefault: number;\n switch (classification) {\n case \"fast\":\n classDefault = parsePositiveIntEnv(\"MCP_TOOL_TIMEOUT_FAST_MS\", FAST_TIMEOUT_MS);\n break;\n case \"async_candidate\":\n classDefault = parsePositiveIntEnv(\"MCP_TOOL_TIMEOUT_ASYNC_CANDIDATE_MS\", ASYNC_CANDIDATE_TIMEOUT_MS);\n break;\n default:\n classDefault = parsePositiveIntEnv(\"MCP_TOOL_TIMEOUT_BOUNDED_SLOW_MS\", BOUNDED_SLOW_TIMEOUT_MS);\n }\n\n const defaultMaxOutputBytes = parsePositiveIntEnv(\"MCP_TOOL_MAX_OUTPUT_BYTES\", DEFAULT_MAX_OUTPUT_BYTES);\n\n return {\n class: classification,\n timeoutMs: parsePositiveIntEnv(toolNameEnv(toolName), classDefault),\n maxOutputBytes: parsePositiveIntEnv(toolNameOutputEnv(toolName), defaultMaxOutputBytes),\n };\n}\n\nexport class ToolRuntimeError extends Error {\n constructor(\n public readonly code: ToolRuntimeErrorCode,\n message: string,\n public readonly toolName: string,\n public readonly policy: ToolTimeoutPolicy,\n ) {\n super(message);\n this.name = \"ToolRuntimeError\";\n }\n}\n\n/** Builds the typed timeout/cancellation error shared by the abort race and catch paths. */\nfunction makeAbortError(timedOut: boolean, toolName: string, policy: ToolTimeoutPolicy): ToolRuntimeError {\n const code: ToolRuntimeErrorCode = timedOut ? \"TOOL_TIMEOUT\" : \"TOOL_CANCELLED\";\n return new ToolRuntimeError(\n code,\n code === \"TOOL_TIMEOUT\"\n ? `Tool ${toolName} timed out after ${policy.timeoutMs}ms.`\n : `Tool ${toolName} was cancelled before it completed.`,\n toolName,\n policy,\n );\n}\n\nfunction combineSignals(signals: Array<AbortSignal \| undefined>): {\n signal: AbortSignal;\n abort: (reason?: unknown) => void;\n cleanup: () => void;\n} {\n const controller = new AbortController();\n const listeners: Array<() => void> = [];\n\n for (const source of signals) {\n if (!source) continue;\n if (source.aborted) {\n controller.abort(source.reason);\n break;\n }\n const onAbort = () => {\n if (!controller.signal.aborted) controller.abort(source.reason);\n };\n source.addEventListener(\"abort\", onAbort, { once: true });\n listeners.push(() => source.removeEventListener(\"abort\", onAbort));\n }\n\n return {\n signal: controller.signal,\n abort: (reason?: unknown) => {\n if (!controller.signal.aborted) controller.abort(reason);\n },\n cleanup: () => {\n for (const cleanup of listeners) cleanup();\n },\n };\n}\n\nexport async function invokeToolRuntime(input: ToolInvocationRuntimeInput): Promise<string> {\n return timed(`ToolRuntime.${input.toolName}`, () => invokeToolRuntimeInner(input));\n}\n\nasync function invokeToolRuntimeInner(input: ToolInvocationRuntimeInput): Promise<string> {\n const basePolicy = getToolTimeoutPolicy(input.toolName);\n const policy = {\n ...basePolicy,\n ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),\n ...(input.maxOutputBytes !== undefined ? { maxOutputBytes: input.maxOutputBytes } : {}),\n };\n const inherited = requestContext.getStore();\n const combined = combineSignals([input.signal, inherited?.abortSignal]);\n let timedOut = false;\n const timer = setTimeout(() => {\n timedOut = true;\n combined.abort(new Error(`Tool ${input.toolName} timed out after ${policy.timeoutMs}ms`));\n }, policy.timeoutMs);\n\n let removeAbortListener = () => {};\n const abortPromise = new Promise<never>((_, reject) => {\n const onAbort = () => {\n reject(makeAbortError(timedOut, input.toolName, policy));\n };\n combined.signal.addEventListener(\"abort\", onAbort, { once: true });\n removeAbortListener = () => combined.signal.removeEventListener(\"abort\", onAbort);\n });\n\n try {\n const run = () => input.tool.handler({ context: input.context, query: input.query });\n const toolPromise = requestContext.run(\n {\n ...inherited,\n abortSignal: combined.signal,\n traceEmitter: input.traceEmitter ?? inherited?.traceEmitter,\n },\n run,\n );\n const result = await Promise.race([toolPromise, abortPromise]);\n const outputBytes = new TextEncoder().encode(result).byteLength;\n if (outputBytes > policy.maxOutputBytes) {\n throw new ToolRuntimeError(\n \"TOOL_OUTPUT_TOO_LARGE\",\n `Tool ${input.toolName} returned ${outputBytes} bytes, exceeding the ${policy.maxOutputBytes} byte limit.`,\n input.toolName,\n policy,\n );\n }\n return result;\n } catch (err) {\n if (err instanceof ToolRuntimeError) throw err;\n if (combined.signal.aborted) {\n throw makeAbortError(timedOut, input.toolName, policy);\n }\n throw err;\n } finally {\n clearTimeout(timer);\n removeAbortListener();\n combined.cleanup();\n }\n}\n\nexport function toolRuntimeErrorToResult(err: unknown): string \| null {\n if (!(err instanceof ToolRuntimeError)) return null;\n return JSON.stringify({\n success: false,\n code: err.code,\n error: err.message,\n data: {\n tool: err.toolName,\n timeoutClass: err.policy.class,\n timeoutMs: err.policy.timeoutMs,\n maxOutputBytes: err.policy.maxOutputBytes,\n },\n });\n}\n"]}

package/dist/shared/agent/utility.tools.js CHANGED Viewed

@@ -9,7 +9,7 @@ export function createUtilityTools(defineTool, deps) {
             "Returns the page's text content (up to 10,000 characters) for use in subsequent tool calls.\n\n" +
             "**When to use:**\n" +
             "- Before create_intent: when the user shares a URL and wants to create an intent from it. Scrape first, then synthesize into a description.\n" +
-            "- Before create_user_profile or update_user_profile: when the user shares a profile URL to update their profile from.\n" +
+            "- Before create_user_context or update_user_context: when the user shares a profile URL to update their profile from.\n" +
             "- When the user asks about content at a URL.\n\n" +
             "**URL format:** Bare domains work fine (e.g. 'github.com/user/repo') — protocol (https://) is added automatically.\n\n" +
             "**Returns:** `{ url, contentLength, content }`. Content is truncated at 10,000 chars. " +
@@ -145,8 +145,8 @@ Profiles are the user's identity on the platform, used for semantic matching in
   - Mirror: self-description of the person
   - Reciprocal: what this person would look for in others
   - Neighborhood: related community context
-- **Onboarding flow**: create_user_profile() → preview → create_user_profile(confirm=true) → complete_onboarding()
-- **Updates**: Use update_user_profile for targeted changes, create_user_profile for full regeneration.
+- **Onboarding flow**: create_user_context() → preview → create_user_context(confirm=true) → complete_onboarding()
+- **Updates**: Use update_user_context for targeted changes, create_user_context for full regeneration.
 ### Profile Best Practices
 - Richer profiles produce better opportunity matches
@@ -188,7 +188,7 @@ Discovery is the process of finding meaningful connections between users based o
                 workflows: `## Common Tool Workflows
 ### New User Setup
-1. create_user_profile(linkedinUrl/githubUrl) → generate profile from social data
+1. create_user_context(linkedinUrl/githubUrl) → generate profile from social data
 2. complete_onboarding() → unlock full access
 3. read_networks() → see available communities
 4. create_network_membership(networkId) → join a community
@@ -202,7 +202,7 @@ Discovery is the process of finding meaningful connections between users based o
 ### Making an Introduction
 1. read_network_memberships(networkId) → find members in shared community
-2. read_user_profiles(userId) → get profiles of both parties
+2. read_user_contexts(userId) → get profiles of both parties
 3. read_intents(networkId, userId) → get intents of both parties
 4. discover_opportunities(partyUserIds=[id1,id2], entities=[...], hint="reason") → create introduction

package/dist/shared/agent/utility.tools.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"utility.tools.js","sourceRoot":"/","sources":["shared/agent/utility.tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAGrE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjE,MAAM,UAAU,kBAAkB,CAAC,UAAsB,EAAE,IAAc;IACvE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAEzB,MAAM,SAAS,GAAG,UAAU,CAAC;QAC3B,IAAI,EAAE,YAAY;QAClB,WAAW,EACT,gHAAgH;YAChH,iGAAiG;YACjG,oBAAoB;YACpB,+IAA+I;YAC/I,yHAAyH;YACzH,kDAAkD;YAClD,wHAAwH;YACxH,wFAAwF;YACxF,yFAAyF;QAC3F,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;YACpB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6IAA6I,CAAC;YACvK,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sRAAsR,CAAC;SAClU,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE;YAC9C,MAAM,aAAa,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC9C,IAAI,CAAC,aAAa,EAAE,CAAC;gBACnB,OAAO,KAAK,CAAC,wGAAwG,CAAC,CAAC;YACzH,CAAC;YAED,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,iBAAiB,CAAC,aAAa,EAAE;gBAC7D,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,SAAS;gBAC/C,MAAM,EAAE,cAAc,CAAC,QAAQ,EAAE,EAAE,WAAW;aAC/C,CAAC,CAAC;YAEH,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,KAAK,CAAC,wGAAwG,CAAC,CAAC;YACzH,CAAC;YAED,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,GAAG,KAAK;gBAC7C,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,4BAA4B;gBAC5D,CAAC,CAAC,OAAO,CAAC;YAEZ,OAAO,OAAO,CAAC;gBACb,GAAG,EAAE,aAAa;gBAClB,aAAa,EAAE,OAAO,CAAC,MAAM;gBAC7B,OAAO,EAAE,gBAAgB;aAC1B,CAAC,CAAC;QACL,CAAC;KACF,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,UAAU,CAAC;QAC1B,IAAI,EAAE,WAAW;QACjB,WAAW,EACT,4IAA4I;YAC5I,6FAA6F;YAC7F,kNAAkN;YAClN,0CAA0C;YAC1C,mGAAmG;YACnG,+DAA+D;YAC/D,wDAAwD;YACxD,uCAAuC;YACvC,kHAAkH;YAClH,gKAAgK;QAClK,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;YACpB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2LAA2L,CAAC;SACnO,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE;YAC9C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YAEhD,MAAM,QAAQ,GAA2B;gBACvC,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;0EAmBwD;gBAElE,OAAO,EAAE;;;;;;;;;;;;;;;uDAesC;gBAE/C,aAAa,EAAE;;;;;;;;;;;;;;;;;;;;;;;4FAuBqE;gBAEpF,OAAO,EAAE;;;;;;;;;;;;;;;8EAe6D;gBAEtE,QAAQ,EAAE;;;;;;;;;;;;;;;;;wEAiBsD;gBAEhE,QAAQ,EAAE;;;;;;;;;;;;;;uDAcqC;gBAE/C,SAAS,EAAE;;;;;;;;;;;;;;;;;2FAiBwE;gBAEnF,SAAS,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6EA8B0D;gBAErE,cAAc,EAAE;;;;;;;;;;;;;;;;;;4DAkBoC;gBAEpD,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;iGAyBwE;aAC1F,CAAC;YAEF,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;gBACrG,IAAI,OAAO,EAAE,CAAC;oBACZ,OAAO,OAAO,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBAC7D,CAAC;gBACD,iCAAiC;YACnC,CAAC;YAED,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrD,OAAO,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QACvC,CAAC;KACF,CAAC,CAAC;IAEH,OAAO,CAAC,SAAS,EAAE,QAAQ,CAAU,CAAC;AACxC,CAAC","sourcesContent":["import { z } from \"zod\";\n\nimport { requestContext } from \"../observability/request-context.js\";\n\nimport type { DefineTool, ToolDeps } from \"./tool.helpers.js\";\nimport { success, error, normalizeUrl } from \"./tool.helpers.js\";\n\nexport function createUtilityTools(defineTool: DefineTool, deps: ToolDeps) {\n const { scraper } = deps;\n\n const scrapeUrl = defineTool({\n name: \"scrape_url\",\n description:\n \"Extracts text content from a web URL — articles, LinkedIn/GitHub profiles, documentation, project pages, etc. \" +\n \"Returns the page's text content (up to 10,000 characters) for use in subsequent tool calls.\\n\\n\" +\n \"When to use:\\n\" +\n \"- Before create_intent: when the user shares a URL and wants to create an intent from it. Scrape first, then synthesize into a description.\\n\" +\n \"- Before create_user_profile or update_user_profile: when the user shares a profile URL to update their profile from.\\n\" +\n \"- When the user asks about content at a URL.\\n\\n\" +\n \"URL format: Bare domains work fine (e.g. 'github.com/user/repo') — protocol (https://) is added automatically.\\n\\n\" +\n \"Returns: `{ url, contentLength, content }`. Content is truncated at 10,000 chars. \" +\n \"Returns an error if the URL is unreachable, requires login, or has no extractable text.\",\n querySchema: z.object({\n url: z.string().describe(\"The URL to extract content from. Protocol is optional — 'github.com/user/repo', 'linkedin.com/in/name', and 'https://example.com' all work.\"),\n objective: z.string().optional().describe(\"Why you're scraping — guides content extraction for better results. Examples: 'User wants to create an intent from this project page', 'User wants to update their profile from this LinkedIn page', 'Extract key information about this company'. Omit for generic text extraction.\"),\n }),\n handler: async ({ context: _context, query }) => {\n const normalizedUrl = normalizeUrl(query.url);\n if (!normalizedUrl) {\n return error(\"Invalid URL format. Please provide a valid URL (e.g. 'github.com/user/repo' or 'https://example.com').\");\n }\n\n const content = await scraper.extractUrlContent(normalizedUrl, {\n objective: query.objective?.trim() \|\| undefined,\n signal: requestContext.getStore()?.abortSignal,\n });\n\n if (!content) {\n return error(\"Couldn't extract content from that URL. It may be blocked, require login, or have no extractable text.\");\n }\n\n const truncatedContent = content.length > 10000\n ? content.substring(0, 10000) + \"\\n\\n[Content truncated...]\"\n : content;\n\n return success({\n url: normalizedUrl,\n contentLength: content.length,\n content: truncatedContent,\n });\n },\n });\n\n const readDocs = defineTool({\n name: \"read_docs\",\n description:\n \"Returns comprehensive documentation about the Index Network protocol — entity model, workflows, tool usage guidance, and domain concepts. \" +\n \"This is the primary way for an external agent to bootstrap understanding of the system.\\n\\n\" +\n \"When to use: Call this FIRST when starting a new session. MCP agents MUST call read_docs(topic='mcp_agent_guide') at the start of every conversation to learn proper output formatting and workflow rules.\\n\" +\n \"Also call when you need to understand:\\n\" +\n \"- What entities exist and how they relate (intents, indexes, opportunities, profiles, contacts)\\n\" +\n \"- The discovery workflow (how intents become opportunities)\\n\" +\n \"- Which tools to call in what order for common tasks\\n\" +\n \"- Authentication and API patterns\\n\\n\" +\n \"Returns: Markdown documentation. Pass `topic` to get a specific section, or omit for the full reference.\\n\\n\" +\n \"Available topics: 'entities', 'intents', 'opportunities', 'indexes', 'profiles', 'contacts', 'discovery', 'workflows', 'authentication', 'mcp_agent_guide'\",\n querySchema: z.object({\n topic: z.string().optional().describe(\"Narrow to a specific topic: 'entities', 'intents', 'opportunities', 'indexes', 'profiles', 'contacts', 'discovery', 'workflows', or 'authentication'. Omit to get the full documentation.\"),\n }),\n handler: async ({ context: _context, query }) => {\n const topic = query.topic?.trim().toLowerCase();\n\n const sections: Record<string, string> = {\n entities: `## Entity Model & Relationships\n\n- Users: People on the platform. Authenticated via API key (X-API-Key header) for MCP/external agents, or session-based (Better Auth) for the web app.\n- Profiles: A user's identity — name, bio, skills, interests, location, social links. Generated from account data or social URLs via enrichment. One profile per user.\n- Indexes (also called \"networks\"): Communities or groups where members share intents and discover opportunities. Each has a title, optional prompt (purpose description), join policy (anyone or invite_only), and an owner. The user's personal index (isPersonal=true) stores their contacts.\n- Index Members: Junction between Users and Indexes. Tracks permissions (owner, member, contact), join date, auto-assign setting, and optional member prompt.\n- Intents: Signals of interest/need — what a user is looking for (e.g. \"Looking for a React developer in Berlin\"). Each has a description (payload), summary, confidence score (0-1), inferenceType (explicit/implicit), source tracking, and vector embedding.\n- IntentNetworks: Many-to-many junction between Intents and Indexes. An intent can be in multiple indexes. Has a relevancyScore (0-1) indicating how well the intent fits the index's purpose.\n- Opportunities: Discovered connections between users based on complementary intents within shared indexes. Have actors with roles (introducer, party), status lifecycle, match reasoning, confidence score, and presentation data.\n- Contacts: People in a user's personal network, stored as index members with 'contact' permission on the personal index. Can be real users or ghost users (placeholder accounts enriched from public data).\n- Ghost Users: Placeholder accounts created for contacts who aren't on the platform yet. Enriched with public profile data (LinkedIn, GitHub) and participate in opportunity matching.\n\n### Key Relationships\n- Users → Profiles (1:1)\n- Users → Indexes (many:many via Index Members)\n- Users → Intents (1:many, user owns intents)\n- Intents → Indexes (many:many via IntentNetworks with relevancyScore)\n- Opportunities → Users (many:many via actors with roles)\n- Opportunities → Indexes (scoped to shared index context)\n- Contacts → Personal Index (stored as members with 'contact' permission)`,\n\n intents: `## Intent Lifecycle\n\nIntents are the core unit of discovery — they represent what users are seeking and drive semantic matching.\n\n1. Creation (create_intent): User describes what they're looking for. The system runs inference (extracting structured intents from free text) and verification (checking specificity, speech-act type). Returns a proposal for user approval.\n2. Confidence & Classification: Each intent gets a confidence score (0-1), inferenceType (explicit = user stated directly, implicit = system inferred), and speech act classification (commissive, directive, assertive).\n3. Index Assignment: After creation, the intent is automatically evaluated against all indexes the user belongs to. The index's prompt is used as criteria. Matching indexes get linked via IntentNetworks with a relevancyScore (0-1).\n4. Discovery Trigger: Creating an intent triggers background opportunity detection — the system searches for other users in shared indexes whose intents complement this one.\n5. Source Tracking: Intents track their origin via sourceType (file, integration, link, discovery_form, enrichment) and sourceId.\n6. Update (update_intent): Re-processes through inference/verification, recalculates embeddings and index assignments.\n7. Archive (delete_intent): Soft-deletes the intent. It stops participating in discovery but is not permanently removed.\n\n### Intent Best Practices\n- Be specific: \"Looking for a senior React developer for a 3-month contract in Berlin\" > \"Need a developer\"\n- One intent per need: don't combine multiple requests into one intent\n- Update rather than delete+create to preserve history`,\n\n opportunities: `## Opportunity Lifecycle\n\nOpportunities represent discovered connections between users — potential matches worth pursuing.\n\n1. Detection (discover_opportunities): The opportunity graph finds users whose intents semantically complement each other within shared indexes. Uses HyDE embeddings for retrieval and an LLM evaluator for scoring.\n2. Roles: Each opportunity assigns roles to actors:\n - introducer: The person who triggered the introduction (may be the system or another user)\n - party: The people being connected (typically 2)\n3. Status Flow: draft → pending → accepted/rejected/expired\n - draft: Created but not sent. Only the creator/introducer sees it.\n - pending: Sent to the other party. They're notified and can respond.\n - accepted: Both parties agreed to connect.\n - rejected: One party declined.\n - expired: Timed out without response.\n4. Creation Modes:\n - Discovery: Automatic — system finds matches based on intent overlap (discover_opportunities with searchQuery)\n - Introduction: Manual — a user introduces two specific people (discover_opportunities with partyUserIds + entities)\n - Direct: One-to-one — connect with a specific person (discover_opportunities with targetUserId)\n5. Presentation: Each opportunity includes personalized match reasoning, confidence score, and suggested next action.\n\n### Opportunity Workflow\n1. discover_opportunities(searchQuery=\"AI engineers\") → returns draft opportunity cards\n2. update_opportunity(opportunityId, status=\"pending\") → sends to other party\n3. Other party sees opportunity → calls update_opportunity(status=\"accepted\" or \"rejected\")`,\n\n indexes: `## Index Mechanics\n\nIndexes (also called \"networks\") are communities where members share what they're looking for and the system discovers connections between them.\n\n- Purpose prompt: Each index has an optional prompt describing its purpose (e.g. \"AI/ML co-founders in Berlin\"). This prompt is used by the intent indexer to evaluate whether an intent belongs in this community. Indexes without prompts accept all intents (relevancyScore defaults to 1.0).\n- Join policy: \"anyone\" (open — any user can self-join) or \"invite_only\" (only the owner can add members).\n- Personal index: Each user has exactly one personal index (isPersonal=true) created on registration. It stores their contacts. Cannot be deleted, renamed, or listed publicly.\n- Membership: Members can see all intents in the index. The auto-assign setting on a membership means new intents by that user are automatically evaluated against the index.\n- Owner permissions: Index owners can update settings (title, prompt, joinPolicy), add/remove members, and delete the index (if sole member).\n- Discovery scope: Opportunities are discovered within index boundaries — the system matches intents of members who share at least one index.\n\n### Index Workflow\n1. create_network(title, prompt) → creates new community, you become owner\n2. create_network_membership(networkId, userId) → invite members\n3. Members create intents → auto-assigned to the index based on prompt\n4. discover_opportunities(networkId) → discover matches within this community`,\n\n profiles: `## Profile System\n\nProfiles are the user's identity on the platform, used for semantic matching in opportunity discovery.\n\n- Structure: name, bio, location, skills[], interests[], social links (LinkedIn, GitHub, Twitter, websites)\n- Generation: Auto-generated from account data (name, email, social links) via web enrichment. Can also be created from explicit user input (bioOrDescription).\n- Enrichment: The system scrapes public profiles (LinkedIn, GitHub, Twitter) to build a rich identity with skills, interests, and narrative context.\n- Embeddings: HyDE (Hypothetical Document Embedding) generates synthetic documents for semantic matching:\n - Mirror: self-description of the person\n - Reciprocal: what this person would look for in others\n - Neighborhood: related community context\n- Onboarding flow: create_user_profile() → preview → create_user_profile(confirm=true) → complete_onboarding()\n- Updates: Use update_user_profile for targeted changes, create_user_profile for full regeneration.\n\n### Profile Best Practices\n- Richer profiles produce better opportunity matches\n- Social links enable enrichment — encourage users to add LinkedIn/GitHub\n- Profiles are recalculated when updated, which may surface new matches`,\n\n contacts: `## Contact Management\n\nContacts are people in a user's personal network, stored as members of their personal index with 'contact' permission.\n\n- Adding contacts: Via import_contacts (bulk), add_contact (single email), or import_gmail_contacts (Google integration).\n- Ghost users: When a contact email doesn't match an existing account, a ghost user is created. Ghost users are enriched with public profile data and participate in opportunity matching — they can be discovered even before joining the platform.\n- Personal index scope: Pass the personal index networkId to discover_opportunities to scope discovery to just the user's contacts.\n- Contact data: Each contact has userId, name, email, avatar, and isGhost flag.\n\n### Contact Workflow\n1. import_contacts or import_gmail_contacts → bulk add to network\n2. list_contacts → view all contacts with userId\n3. discover_opportunities(networkId=personalIndexId) → find matches among contacts\n4. add_contact(email) → add individual contact\n5. remove_contact(contactUserId) → remove from network`,\n\n discovery: `## Discovery Mechanics\n\nDiscovery is the process of finding meaningful connections between users based on their intents and profiles.\n\n### How Discovery Works\n1. Trigger: Runs automatically when an intent is created, or explicitly when discover_opportunities is called.\n2. Pipeline: Preparation (gather user context) → Scope (determine which indexes to search) → Candidate retrieval (semantic matching via HyDE embeddings) → Evaluation (LLM scores relevance and complementarity) → Ranking → Persist as opportunities.\n3. Semantic matching: Uses HyDE (Hypothetical Document Embeddings) to find candidate intents that complement the source. This goes beyond keyword matching — it understands conceptual relationships.\n4. Evaluation: An LLM evaluator agent scores each candidate match on relevance, complementarity, and actionability. Low-scoring matches are filtered out.\n5. Results: Persisted as draft opportunities with roles, reasoning, and confidence scores.\n6. Background processing: After intent creation, a queue job continues looking for matches asynchronously.\n7. Pagination: Large result sets are paginated. Use continueFrom with the discoveryId to evaluate more candidates.\n\n### Discovery Best Practices\n- More specific intents produce more relevant matches\n- Richer profiles improve matching quality\n- Scope to a specific index (networkId) for more targeted results\n- After discovery returns no results, suggest creating an intent to attract future matches`,\n\n workflows: `## Common Tool Workflows\n\n### New User Setup\n1. create_user_profile(linkedinUrl/githubUrl) → generate profile from social data\n2. complete_onboarding() → unlock full access\n3. read_networks() → see available communities\n4. create_network_membership(networkId) → join a community\n5. create_intent(description) → post what you're looking for\n6. discover_opportunities(searchQuery) → find matches\n\n### Finding Connections\n1. read_networks() → list user's communities (get networkId)\n2. discover_opportunities(searchQuery, networkId) → discover matches\n3. Review opportunity cards → update_opportunity(opportunityId, status=\"pending\") to send\n\n### Making an Introduction\n1. read_network_memberships(networkId) → find members in shared community\n2. read_user_profiles(userId) → get profiles of both parties\n3. read_intents(networkId, userId) → get intents of both parties\n4. discover_opportunities(partyUserIds=[id1,id2], entities=[...], hint=\"reason\") → create introduction\n\n### Managing Contacts\n1. import_gmail_contacts() or import_contacts([...]) → add contacts\n2. list_contacts() → view network\n3. discover_opportunities(networkId=personalIndexId) → find matches among contacts\n\n### Creating a Community\n1. create_network(title, prompt) → create index\n2. create_network_membership(networkId, userId) → invite members\n3. Members create intents → auto-indexed\n4. discover_opportunities(networkId) → discover connections within community`,\n\n authentication: `## Authentication & API Access\n\n### For External AI Agents (MCP)\n- Authenticate via X-API-Key header with a valid API key\n- The API key is tied to a specific user account\n- All operations execute in the context of the authenticated user\n- Base URL: protocol.index.network/mcp\n\n### Key Constraints\n- Users can only read their own intents globally, or intents in indexes they belong to\n- Users can only read profiles of people in shared indexes\n- Index-scoped operations are restricted to that index\n- Personal indexes cannot be deleted or renamed\n- Only index owners can update settings, add/remove members (for invite_only indexes)\n\n### Rate Limits & Best Practices\n- Avoid unnecessary read_intents/read_networks calls — cache results within a conversation\n- Use pagination (limit/page) for large result sets\n- Call read_docs once at the start to understand the domain`,\n\n mcp_agent_guide: `## MCP Agent Integration Guide\n\nIMPORTANT: Read this section if you are an AI agent accessing Index Network via MCP tools.\n\n### Output Formatting\n- Tool results often contain structured JSON data (proposals, opportunities, cards). Do NOT dump raw JSON to the user. Parse the JSON and present information in natural language with clear formatting.\n- Some tool results contain interactive card markup (code blocks with \\`intent_proposal\\`, \\`opportunity_card\\` language tags). These are designed for the Index Network web UI. As an MCP agent, ignore card markup. Instead, extract the meaningful data from the JSON and present it conversationally.\n- When presenting opportunities or intents, use bullet points or short paragraphs — not raw JSON objects.\n\n### Intent Creation Workflow\n- Always pass \\`autoApprove: true\\` when calling \\`create_intent\\`. This persists intents directly without returning proposal cards that require manual UI approval.\n- The tool will return a list of created intents with their descriptions and confidence scores. Present these in natural language.\n- Do not tell the user to \"click on cards\" or \"approve above\" — there is no UI. Intents are created immediately with autoApprove.\n- After creating intents, proactively suggest or run discovery to find matches.\n\n### Discovery Workflow\n- After creating intents, proactively suggest running discovery: \\`discover_opportunities(searchQuery=...)\\`\n- Present discovered opportunities in natural language with the counterpart's name, match reasoning, and suggested next steps.\n- Do not reference \"cards\", \"panels\", or any web UI elements.\n\n### General MCP Agent Rules\n- You are operating via API tools, not a web interface. Never reference clicking, scrolling, cards, panels, or any visual UI elements.\n- Be proactive: if a logical next step exists (e.g., running discovery after creating intents), suggest or execute it.\n- Use \\`list_opportunities\\` to check existing matches, \\`list_negotiations\\` for ongoing negotiations.\n- Use \\`read_networks\\` to understand which communities the user belongs to before scoping operations.\n- When errors occur, provide clear technical context rather than vague \"backend issue\" messages.`,\n };\n\n if (topic) {\n const matched = Object.entries(sections).find(([key]) => key.includes(topic) \|\| topic.includes(key));\n if (matched) {\n return success({ topic: matched[0], content: matched[1] });\n }\n // If topic not found, return all\n }\n\n const fullDoc = Object.values(sections).join(\"\\n\\n\");\n return success({ content: fullDoc });\n },\n });\n\n return [scrapeUrl, readDocs] as const;\n}\n"]}
1	+ {"version":3,"file":"utility.tools.js","sourceRoot":"/","sources":["shared/agent/utility.tools.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\n\nimport { requestContext } from \"../observability/request-context.js\";\n\nimport type { DefineTool, ToolDeps } from \"./tool.helpers.js\";\nimport { success, error, normalizeUrl } from \"./tool.helpers.js\";\n\nexport function createUtilityTools(defineTool: DefineTool, deps: ToolDeps) {\n const { scraper } = deps;\n\n const scrapeUrl = defineTool({\n name: \"scrape_url\",\n description:\n \"Extracts text content from a web URL — articles, LinkedIn/GitHub profiles, documentation, project pages, etc. \" +\n \"Returns the page's text content (up to 10,000 characters) for use in subsequent tool calls.\\n\\n\" +\n \"When to use:\\n\" +\n \"- Before create_intent: when the user shares a URL and wants to create an intent from it. Scrape first, then synthesize into a description.\\n\" +\n \"- Before create_user_context or update_user_context: when the user shares a profile URL to update their profile from.\\n\" +\n \"- When the user asks about content at a URL.\\n\\n\" +\n \"URL format: Bare domains work fine (e.g. 'github.com/user/repo') — protocol (https://) is added automatically.\\n\\n\" +\n \"Returns: `{ url, contentLength, content }`. Content is truncated at 10,000 chars. \" +\n \"Returns an error if the URL is unreachable, requires login, or has no extractable text.\",\n querySchema: z.object({\n url: z.string().describe(\"The URL to extract content from. Protocol is optional — 'github.com/user/repo', 'linkedin.com/in/name', and 'https://example.com' all work.\"),\n objective: z.string().optional().describe(\"Why you're scraping — guides content extraction for better results. Examples: 'User wants to create an intent from this project page', 'User wants to update their profile from this LinkedIn page', 'Extract key information about this company'. Omit for generic text extraction.\"),\n }),\n handler: async ({ context: _context, query }) => {\n const normalizedUrl = normalizeUrl(query.url);\n if (!normalizedUrl) {\n return error(\"Invalid URL format. Please provide a valid URL (e.g. 'github.com/user/repo' or 'https://example.com').\");\n }\n\n const content = await scraper.extractUrlContent(normalizedUrl, {\n objective: query.objective?.trim() \|\| undefined,\n signal: requestContext.getStore()?.abortSignal,\n });\n\n if (!content) {\n return error(\"Couldn't extract content from that URL. It may be blocked, require login, or have no extractable text.\");\n }\n\n const truncatedContent = content.length > 10000\n ? content.substring(0, 10000) + \"\\n\\n[Content truncated...]\"\n : content;\n\n return success({\n url: normalizedUrl,\n contentLength: content.length,\n content: truncatedContent,\n });\n },\n });\n\n const readDocs = defineTool({\n name: \"read_docs\",\n description:\n \"Returns comprehensive documentation about the Index Network protocol — entity model, workflows, tool usage guidance, and domain concepts. \" +\n \"This is the primary way for an external agent to bootstrap understanding of the system.\\n\\n\" +\n \"When to use: Call this FIRST when starting a new session. MCP agents MUST call read_docs(topic='mcp_agent_guide') at the start of every conversation to learn proper output formatting and workflow rules.\\n\" +\n \"Also call when you need to understand:\\n\" +\n \"- What entities exist and how they relate (intents, indexes, opportunities, profiles, contacts)\\n\" +\n \"- The discovery workflow (how intents become opportunities)\\n\" +\n \"- Which tools to call in what order for common tasks\\n\" +\n \"- Authentication and API patterns\\n\\n\" +\n \"Returns: Markdown documentation. Pass `topic` to get a specific section, or omit for the full reference.\\n\\n\" +\n \"Available topics: 'entities', 'intents', 'opportunities', 'indexes', 'profiles', 'contacts', 'discovery', 'workflows', 'authentication', 'mcp_agent_guide'\",\n querySchema: z.object({\n topic: z.string().optional().describe(\"Narrow to a specific topic: 'entities', 'intents', 'opportunities', 'indexes', 'profiles', 'contacts', 'discovery', 'workflows', or 'authentication'. Omit to get the full documentation.\"),\n }),\n handler: async ({ context: _context, query }) => {\n const topic = query.topic?.trim().toLowerCase();\n\n const sections: Record<string, string> = {\n entities: `## Entity Model & Relationships\n\n- Users: People on the platform. Authenticated via API key (X-API-Key header) for MCP/external agents, or session-based (Better Auth) for the web app.\n- Profiles: A user's identity — name, bio, skills, interests, location, social links. Generated from account data or social URLs via enrichment. One profile per user.\n- Indexes (also called \"networks\"): Communities or groups where members share intents and discover opportunities. Each has a title, optional prompt (purpose description), join policy (anyone or invite_only), and an owner. The user's personal index (isPersonal=true) stores their contacts.\n- Index Members: Junction between Users and Indexes. Tracks permissions (owner, member, contact), join date, auto-assign setting, and optional member prompt.\n- Intents: Signals of interest/need — what a user is looking for (e.g. \"Looking for a React developer in Berlin\"). Each has a description (payload), summary, confidence score (0-1), inferenceType (explicit/implicit), source tracking, and vector embedding.\n- IntentNetworks: Many-to-many junction between Intents and Indexes. An intent can be in multiple indexes. Has a relevancyScore (0-1) indicating how well the intent fits the index's purpose.\n- Opportunities: Discovered connections between users based on complementary intents within shared indexes. Have actors with roles (introducer, party), status lifecycle, match reasoning, confidence score, and presentation data.\n- Contacts: People in a user's personal network, stored as index members with 'contact' permission on the personal index. Can be real users or ghost users (placeholder accounts enriched from public data).\n- Ghost Users: Placeholder accounts created for contacts who aren't on the platform yet. Enriched with public profile data (LinkedIn, GitHub) and participate in opportunity matching.\n\n### Key Relationships\n- Users → Profiles (1:1)\n- Users → Indexes (many:many via Index Members)\n- Users → Intents (1:many, user owns intents)\n- Intents → Indexes (many:many via IntentNetworks with relevancyScore)\n- Opportunities → Users (many:many via actors with roles)\n- Opportunities → Indexes (scoped to shared index context)\n- Contacts → Personal Index (stored as members with 'contact' permission)`,\n\n intents: `## Intent Lifecycle\n\nIntents are the core unit of discovery — they represent what users are seeking and drive semantic matching.\n\n1. Creation (create_intent): User describes what they're looking for. The system runs inference (extracting structured intents from free text) and verification (checking specificity, speech-act type). Returns a proposal for user approval.\n2. Confidence & Classification: Each intent gets a confidence score (0-1), inferenceType (explicit = user stated directly, implicit = system inferred), and speech act classification (commissive, directive, assertive).\n3. Index Assignment: After creation, the intent is automatically evaluated against all indexes the user belongs to. The index's prompt is used as criteria. Matching indexes get linked via IntentNetworks with a relevancyScore (0-1).\n4. Discovery Trigger: Creating an intent triggers background opportunity detection — the system searches for other users in shared indexes whose intents complement this one.\n5. Source Tracking: Intents track their origin via sourceType (file, integration, link, discovery_form, enrichment) and sourceId.\n6. Update (update_intent): Re-processes through inference/verification, recalculates embeddings and index assignments.\n7. Archive (delete_intent): Soft-deletes the intent. It stops participating in discovery but is not permanently removed.\n\n### Intent Best Practices\n- Be specific: \"Looking for a senior React developer for a 3-month contract in Berlin\" > \"Need a developer\"\n- One intent per need: don't combine multiple requests into one intent\n- Update rather than delete+create to preserve history`,\n\n opportunities: `## Opportunity Lifecycle\n\nOpportunities represent discovered connections between users — potential matches worth pursuing.\n\n1. Detection (discover_opportunities): The opportunity graph finds users whose intents semantically complement each other within shared indexes. Uses HyDE embeddings for retrieval and an LLM evaluator for scoring.\n2. Roles: Each opportunity assigns roles to actors:\n - introducer: The person who triggered the introduction (may be the system or another user)\n - party: The people being connected (typically 2)\n3. Status Flow: draft → pending → accepted/rejected/expired\n - draft: Created but not sent. Only the creator/introducer sees it.\n - pending: Sent to the other party. They're notified and can respond.\n - accepted: Both parties agreed to connect.\n - rejected: One party declined.\n - expired: Timed out without response.\n4. Creation Modes:\n - Discovery: Automatic — system finds matches based on intent overlap (discover_opportunities with searchQuery)\n - Introduction: Manual — a user introduces two specific people (discover_opportunities with partyUserIds + entities)\n - Direct: One-to-one — connect with a specific person (discover_opportunities with targetUserId)\n5. Presentation: Each opportunity includes personalized match reasoning, confidence score, and suggested next action.\n\n### Opportunity Workflow\n1. discover_opportunities(searchQuery=\"AI engineers\") → returns draft opportunity cards\n2. update_opportunity(opportunityId, status=\"pending\") → sends to other party\n3. Other party sees opportunity → calls update_opportunity(status=\"accepted\" or \"rejected\")`,\n\n indexes: `## Index Mechanics\n\nIndexes (also called \"networks\") are communities where members share what they're looking for and the system discovers connections between them.\n\n- Purpose prompt: Each index has an optional prompt describing its purpose (e.g. \"AI/ML co-founders in Berlin\"). This prompt is used by the intent indexer to evaluate whether an intent belongs in this community. Indexes without prompts accept all intents (relevancyScore defaults to 1.0).\n- Join policy: \"anyone\" (open — any user can self-join) or \"invite_only\" (only the owner can add members).\n- Personal index: Each user has exactly one personal index (isPersonal=true) created on registration. It stores their contacts. Cannot be deleted, renamed, or listed publicly.\n- Membership: Members can see all intents in the index. The auto-assign setting on a membership means new intents by that user are automatically evaluated against the index.\n- Owner permissions: Index owners can update settings (title, prompt, joinPolicy), add/remove members, and delete the index (if sole member).\n- Discovery scope: Opportunities are discovered within index boundaries — the system matches intents of members who share at least one index.\n\n### Index Workflow\n1. create_network(title, prompt) → creates new community, you become owner\n2. create_network_membership(networkId, userId) → invite members\n3. Members create intents → auto-assigned to the index based on prompt\n4. discover_opportunities(networkId) → discover matches within this community`,\n\n profiles: `## Profile System\n\nProfiles are the user's identity on the platform, used for semantic matching in opportunity discovery.\n\n- Structure: name, bio, location, skills[], interests[], social links (LinkedIn, GitHub, Twitter, websites)\n- Generation: Auto-generated from account data (name, email, social links) via web enrichment. Can also be created from explicit user input (bioOrDescription).\n- Enrichment: The system scrapes public profiles (LinkedIn, GitHub, Twitter) to build a rich identity with skills, interests, and narrative context.\n- Embeddings: HyDE (Hypothetical Document Embedding) generates synthetic documents for semantic matching:\n - Mirror: self-description of the person\n - Reciprocal: what this person would look for in others\n - Neighborhood: related community context\n- Onboarding flow: create_user_context() → preview → create_user_context(confirm=true) → complete_onboarding()\n- Updates: Use update_user_context for targeted changes, create_user_context for full regeneration.\n\n### Profile Best Practices\n- Richer profiles produce better opportunity matches\n- Social links enable enrichment — encourage users to add LinkedIn/GitHub\n- Profiles are recalculated when updated, which may surface new matches`,\n\n contacts: `## Contact Management\n\nContacts are people in a user's personal network, stored as members of their personal index with 'contact' permission.\n\n- Adding contacts: Via import_contacts (bulk), add_contact (single email), or import_gmail_contacts (Google integration).\n- Ghost users: When a contact email doesn't match an existing account, a ghost user is created. Ghost users are enriched with public profile data and participate in opportunity matching — they can be discovered even before joining the platform.\n- Personal index scope: Pass the personal index networkId to discover_opportunities to scope discovery to just the user's contacts.\n- Contact data: Each contact has userId, name, email, avatar, and isGhost flag.\n\n### Contact Workflow\n1. import_contacts or import_gmail_contacts → bulk add to network\n2. list_contacts → view all contacts with userId\n3. discover_opportunities(networkId=personalIndexId) → find matches among contacts\n4. add_contact(email) → add individual contact\n5. remove_contact(contactUserId) → remove from network`,\n\n discovery: `## Discovery Mechanics\n\nDiscovery is the process of finding meaningful connections between users based on their intents and profiles.\n\n### How Discovery Works\n1. Trigger: Runs automatically when an intent is created, or explicitly when discover_opportunities is called.\n2. Pipeline: Preparation (gather user context) → Scope (determine which indexes to search) → Candidate retrieval (semantic matching via HyDE embeddings) → Evaluation (LLM scores relevance and complementarity) → Ranking → Persist as opportunities.\n3. Semantic matching: Uses HyDE (Hypothetical Document Embeddings) to find candidate intents that complement the source. This goes beyond keyword matching — it understands conceptual relationships.\n4. Evaluation: An LLM evaluator agent scores each candidate match on relevance, complementarity, and actionability. Low-scoring matches are filtered out.\n5. Results: Persisted as draft opportunities with roles, reasoning, and confidence scores.\n6. Background processing: After intent creation, a queue job continues looking for matches asynchronously.\n7. Pagination: Large result sets are paginated. Use continueFrom with the discoveryId to evaluate more candidates.\n\n### Discovery Best Practices\n- More specific intents produce more relevant matches\n- Richer profiles improve matching quality\n- Scope to a specific index (networkId) for more targeted results\n- After discovery returns no results, suggest creating an intent to attract future matches`,\n\n workflows: `## Common Tool Workflows\n\n### New User Setup\n1. create_user_context(linkedinUrl/githubUrl) → generate profile from social data\n2. complete_onboarding() → unlock full access\n3. read_networks() → see available communities\n4. create_network_membership(networkId) → join a community\n5. create_intent(description) → post what you're looking for\n6. discover_opportunities(searchQuery) → find matches\n\n### Finding Connections\n1. read_networks() → list user's communities (get networkId)\n2. discover_opportunities(searchQuery, networkId) → discover matches\n3. Review opportunity cards → update_opportunity(opportunityId, status=\"pending\") to send\n\n### Making an Introduction\n1. read_network_memberships(networkId) → find members in shared community\n2. read_user_contexts(userId) → get profiles of both parties\n3. read_intents(networkId, userId) → get intents of both parties\n4. discover_opportunities(partyUserIds=[id1,id2], entities=[...], hint=\"reason\") → create introduction\n\n### Managing Contacts\n1. import_gmail_contacts() or import_contacts([...]) → add contacts\n2. list_contacts() → view network\n3. discover_opportunities(networkId=personalIndexId) → find matches among contacts\n\n### Creating a Community\n1. create_network(title, prompt) → create index\n2. create_network_membership(networkId, userId) → invite members\n3. Members create intents → auto-indexed\n4. discover_opportunities(networkId) → discover connections within community`,\n\n authentication: `## Authentication & API Access\n\n### For External AI Agents (MCP)\n- Authenticate via X-API-Key header with a valid API key\n- The API key is tied to a specific user account\n- All operations execute in the context of the authenticated user\n- Base URL: protocol.index.network/mcp\n\n### Key Constraints\n- Users can only read their own intents globally, or intents in indexes they belong to\n- Users can only read profiles of people in shared indexes\n- Index-scoped operations are restricted to that index\n- Personal indexes cannot be deleted or renamed\n- Only index owners can update settings, add/remove members (for invite_only indexes)\n\n### Rate Limits & Best Practices\n- Avoid unnecessary read_intents/read_networks calls — cache results within a conversation\n- Use pagination (limit/page) for large result sets\n- Call read_docs once at the start to understand the domain`,\n\n mcp_agent_guide: `## MCP Agent Integration Guide\n\nIMPORTANT: Read this section if you are an AI agent accessing Index Network via MCP tools.\n\n### Output Formatting\n- Tool results often contain structured JSON data (proposals, opportunities, cards). Do NOT dump raw JSON to the user. Parse the JSON and present information in natural language with clear formatting.\n- Some tool results contain interactive card markup (code blocks with \\`intent_proposal\\`, \\`opportunity_card\\` language tags). These are designed for the Index Network web UI. As an MCP agent, ignore card markup. Instead, extract the meaningful data from the JSON and present it conversationally.\n- When presenting opportunities or intents, use bullet points or short paragraphs — not raw JSON objects.\n\n### Intent Creation Workflow\n- Always pass \\`autoApprove: true\\` when calling \\`create_intent\\`. This persists intents directly without returning proposal cards that require manual UI approval.\n- The tool will return a list of created intents with their descriptions and confidence scores. Present these in natural language.\n- Do not tell the user to \"click on cards\" or \"approve above\" — there is no UI. Intents are created immediately with autoApprove.\n- After creating intents, proactively suggest or run discovery to find matches.\n\n### Discovery Workflow\n- After creating intents, proactively suggest running discovery: \\`discover_opportunities(searchQuery=...)\\`\n- Present discovered opportunities in natural language with the counterpart's name, match reasoning, and suggested next steps.\n- Do not reference \"cards\", \"panels\", or any web UI elements.\n\n### General MCP Agent Rules\n- You are operating via API tools, not a web interface. Never reference clicking, scrolling, cards, panels, or any visual UI elements.\n- Be proactive: if a logical next step exists (e.g., running discovery after creating intents), suggest or execute it.\n- Use \\`list_opportunities\\` to check existing matches, \\`list_negotiations\\` for ongoing negotiations.\n- Use \\`read_networks\\` to understand which communities the user belongs to before scoping operations.\n- When errors occur, provide clear technical context rather than vague \"backend issue\" messages.`,\n };\n\n if (topic) {\n const matched = Object.entries(sections).find(([key]) => key.includes(topic) \|\| topic.includes(key));\n if (matched) {\n return success({ topic: matched[0], content: matched[1] });\n }\n // If topic not found, return all\n }\n\n const fullDoc = Object.values(sections).join(\"\\n\\n\");\n return success({ content: fullDoc });\n },\n });\n\n return [scrapeUrl, readDocs] as const;\n}\n"]}