@indexnetwork/protocol 4.3.4-rc.309.1 → 4.3.4-rc.310.1

package/dist/shared/agent/tool.scope.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool.scope.js","sourceRoot":"/","sources":["shared/agent/tool.scope.ts"],"names":[],"mappings":"AAuBA,SAAS,gBAAgB,CAAC,GAAa;IACrC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,SAAoC;IACrE,MAAM,OAAO,GAAG,SAAS,EAAE,IAAI,EAAE,CAAC;IAClC,OAAO,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAwB;IACtD,OAAO,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAC/G,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAwB;IACvD,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AACnE,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,mBAAmB,CAAC,KAAiD;IACnF,OAAO,KAAK,CAAC,SAAS,IAAI,gBAAgB,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,KAA8B;IACpE,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,gBAAgB,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;IACvF,CAAC;IAED,OAAO,gBAAgB,CACrB,KAAK,CAAC,WAAW;SACd,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,KAAK,KAAK,CAAC,OAAO,IAAI,UAAU,CAAC,UAAU,KAAK,IAAI,CAAC;SAChG,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAC7C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,KAA8B;IACtE,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,gBAAgB,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;IACvF,CAAC;IAED,OAAO,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,KAAK,KAAK,CAAC,OAAO,CAAC;QACnF,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;QACjB,CAAC,CAAC,EAAE,CAAC;AACT,CAAC","sourcesContent":["/**\n * Request scope primitives for protocol tools.\n *\n * `scopeType`/`scopeId` describe the user's focused scope, not the full set of\n * networks a caller may read or write. Helper functions derive concrete network\n * id sets from the focused scope plus the caller's memberships.\n */\nexport type ToolScopeType = 'network';\n\nexport interface ToolScopeEnvelope {\n  scopeType?: ToolScopeType;\n  scopeId?: string;\n}\n\nexport interface ScopeMembership {\n  networkId: string;\n  isPersonal?: boolean | null;\n}\n\nexport interface DeriveNetworkScopeInput extends ToolScopeEnvelope {\n  memberships: ScopeMembership[];\n}\n\nfunction uniqueNetworkIds(ids: string[]): string[] {\n  return [...new Set(ids.map((id) => id.trim()).filter(Boolean))];\n}\n\nexport function scopeFromNetworkId(networkId: string | null | undefined): ToolScopeEnvelope {\n  const scopeId = networkId?.trim();\n  return scopeId ? { scopeType: 'network', scopeId } : {};\n}\n\nexport function hasNetworkScope(scope: ToolScopeEnvelope): scope is { scopeType: 'network'; scopeId: string } {\n  return scope.scopeType === 'network' && typeof scope.scopeId === 'string' && scope.scopeId.trim().length > 0;\n}\n\n/**\n * Returns the focused network id from the canonical scope envelope.\n *\n * This intentionally does not inspect legacy `networkId` fields; callers that\n * still need a transition fallback should pass `scopeFromNetworkId(networkId)`\n * at the boundary so tool logic remains envelope-driven.\n */\nexport function focusedNetworkId(scope: ToolScopeEnvelope): string | undefined {\n  return hasNetworkScope(scope) ? scope.scopeId.trim() : undefined;\n}\n\n/** Human-readable label for a focused scope, used in scope-restriction notes. */\nexport function focusedNetworkLabel(scope: ToolScopeEnvelope & { indexName?: string }): string {\n  return scope.indexName ?? focusedNetworkId(scope) ?? 'this index';\n}\n\nexport function deriveAllowedNetworkIds(input: DeriveNetworkScopeInput): string[] {\n  if (!hasNetworkScope(input)) {\n    return uniqueNetworkIds(input.memberships.map((membership) => membership.networkId));\n  }\n\n  return uniqueNetworkIds(\n    input.memberships\n      .filter((membership) => membership.networkId === input.scopeId || membership.isPersonal === true)\n      .map((membership) => membership.networkId),\n  );\n}\n\nexport function deriveDiscoveryNetworkIds(input: DeriveNetworkScopeInput): string[] {\n  if (!hasNetworkScope(input)) {\n    return uniqueNetworkIds(input.memberships.map((membership) => membership.networkId));\n  }\n\n  return input.memberships.some((membership) => membership.networkId === input.scopeId)\n    ? [input.scopeId]\n    : [];\n}\n"]}
+{"version":3,"file":"tool.scope.js","sourceRoot":"/","sources":["shared/agent/tool.scope.ts"],"names":[],"mappings":"AAuBA,SAAS,gBAAgB,CAAC,GAAa;IACrC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,SAAoC;IACrE,MAAM,OAAO,GAAG,SAAS,EAAE,IAAI,EAAE,CAAC;IAClC,OAAO,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAwB;IACtD,OAAO,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAC/G,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAwB;IACvD,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AACnE,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,mBAAmB,CAAC,KAAiD;IACnF,OAAO,KAAK,CAAC,SAAS,IAAI,gBAAgB,CAAC,KAAK,CAAC,IAAI,cAAc,CAAC;AACtE,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,KAA8B;IACpE,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,gBAAgB,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;IACvF,CAAC;IAED,OAAO,gBAAgB,CACrB,KAAK,CAAC,WAAW;SACd,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,KAAK,KAAK,CAAC,OAAO,IAAI,UAAU,CAAC,UAAU,KAAK,IAAI,CAAC;SAChG,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAC7C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,KAA8B;IACtE,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,gBAAgB,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;IACvF,CAAC;IAED,OAAO,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,KAAK,KAAK,CAAC,OAAO,CAAC;QACnF,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;QACjB,CAAC,CAAC,EAAE,CAAC;AACT,CAAC","sourcesContent":["/**\n * Request scope primitives for protocol tools.\n *\n * `scopeType`/`scopeId` describe the user's focused scope, not the full set of\n * networks a caller may read or write. Helper functions derive concrete network\n * id sets from the focused scope plus the caller's memberships.\n */\nexport type ToolScopeType = 'network';\n\nexport interface ToolScopeEnvelope {\n  scopeType?: ToolScopeType;\n  scopeId?: string;\n}\n\nexport interface ScopeMembership {\n  networkId: string;\n  isPersonal?: boolean | null;\n}\n\nexport interface DeriveNetworkScopeInput extends ToolScopeEnvelope {\n  memberships: ScopeMembership[];\n}\n\nfunction uniqueNetworkIds(ids: string[]): string[] {\n  return [...new Set(ids.map((id) => id.trim()).filter(Boolean))];\n}\n\nexport function scopeFromNetworkId(networkId: string | null | undefined): ToolScopeEnvelope {\n  const scopeId = networkId?.trim();\n  return scopeId ? { scopeType: 'network', scopeId } : {};\n}\n\nexport function hasNetworkScope(scope: ToolScopeEnvelope): scope is { scopeType: 'network'; scopeId: string } {\n  return scope.scopeType === 'network' && typeof scope.scopeId === 'string' && scope.scopeId.trim().length > 0;\n}\n\n/**\n * Returns the focused network id from the canonical scope envelope.\n *\n * This intentionally does not inspect legacy `networkId` fields; callers that\n * still need a transition fallback should pass `scopeFromNetworkId(networkId)`\n * at the boundary so tool logic remains envelope-driven.\n */\nexport function focusedNetworkId(scope: ToolScopeEnvelope): string | undefined {\n  return hasNetworkScope(scope) ? scope.scopeId.trim() : undefined;\n}\n\n/** Human-readable label for a focused scope, used in scope-restriction notes. */\nexport function focusedNetworkLabel(scope: ToolScopeEnvelope & { indexName?: string }): string {\n  return scope.indexName ?? focusedNetworkId(scope) ?? 'this network';\n}\n\nexport function deriveAllowedNetworkIds(input: DeriveNetworkScopeInput): string[] {\n  if (!hasNetworkScope(input)) {\n    return uniqueNetworkIds(input.memberships.map((membership) => membership.networkId));\n  }\n\n  return uniqueNetworkIds(\n    input.memberships\n      .filter((membership) => membership.networkId === input.scopeId || membership.isPersonal === true)\n      .map((membership) => membership.networkId),\n  );\n}\n\nexport function deriveDiscoveryNetworkIds(input: DeriveNetworkScopeInput): string[] {\n  if (!hasNetworkScope(input)) {\n    return uniqueNetworkIds(input.memberships.map((membership) => membership.networkId));\n  }\n\n  return input.memberships.some((membership) => membership.networkId === input.scopeId)\n    ? [input.scopeId]\n    : [];\n}\n"]}

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

@@ -62,30 +62,30 @@ export function createUtilityTools(defineTool, deps) {
 
 - **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.
 - **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.
-- **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.
-- **Index Members**: Junction between Users and Indexes. Tracks permissions (owner, member, contact), join date, auto-assign setting, and optional member prompt.
+- **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 network** (isPersonal=true) stores their contacts.
+- **Network Members**: Junction between Users and Indexes. Tracks permissions (owner, member, contact), join date, auto-assign setting, and optional member prompt.
 - **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.
 - **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.
-- **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.
-- **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).
+- **Opportunities**: Discovered connections between users based on complementary intents within shared networks. Have actors with roles (introducer, party), status lifecycle, match reasoning, confidence score, and presentation data.
+- **Contacts**: People in a user's personal network, stored as network members with 'contact' permission on the personal network. Can be real users or ghost users (placeholder accounts enriched from public data).
 - **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.
 
 ### Key Relationships
 - Users → Profiles (1:1)
-- Users → Indexes (many:many via Index Members)
+- Users → Indexes (many:many via Network Members)
 - Users → Intents (1:many, user owns intents)
 - Intents → Indexes (many:many via IntentNetworks with relevancyScore)
 - Opportunities → Users (many:many via actors with roles)
-- Opportunities → Indexes (scoped to shared index context)
-- Contacts → Personal Index (stored as members with 'contact' permission)`,
+- Opportunities → Indexes (scoped to shared network context)
+- Contacts → Personal Network (stored as members with 'contact' permission)`,
                 intents: `## Intent Lifecycle
 
 Intents are the core unit of discovery — they represent what users are seeking and drive semantic matching.
 
 1. **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.
 2. **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).
-3. **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).
-4. **Discovery Trigger**: Creating an intent triggers background opportunity detection — the system searches for other users in shared indexes whose intents complement this one.
+3. **Index Assignment**: After creation, the intent is automatically evaluated against all networks the user belongs to. The index's prompt is used as criteria. Matching indexes get linked via IntentNetworks with a relevancyScore (0-1).
+4. **Discovery Trigger**: Creating an intent triggers background opportunity detection — the system searches for other users in shared networks whose intents complement this one.
 5. **Source Tracking**: Intents track their origin via sourceType (file, integration, link, discovery_form, enrichment) and sourceId.
 6. **Update** (update_intent): Re-processes through inference/verification, recalculates embeddings and index assignments.
 7. **Archive** (delete_intent): Soft-deletes the intent. It stops participating in discovery but is not permanently removed.
@@ -98,7 +98,7 @@ Intents are the core unit of discovery — they represent what users are seeking
 
 Opportunities represent discovered connections between users — potential matches worth pursuing.
 
-1. **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.
+1. **Detection** (discover_opportunities): The opportunity graph finds users whose intents semantically complement each other within shared networks. Uses HyDE embeddings for retrieval and an LLM evaluator for scoring.
 2. **Roles**: Each opportunity assigns roles to actors:
    - **introducer**: The person who triggered the introduction (may be the system or another user)
    - **party**: The people being connected (typically 2)
@@ -122,11 +122,11 @@ Opportunities represent discovered connections between users — potential match
 
 Indexes (also called "networks") are communities where members share what they're looking for and the system discovers connections between them.
 
-- **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).
+- **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. Networks without prompts accept all intents (relevancyScore defaults to 1.0).
 - **Join policy**: "anyone" (open — any user can self-join) or "invite_only" (only the owner can add members).
-- **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.
+- **Personal network**: Each user has exactly one personal network (isPersonal=true) created on registration. It stores their contacts. Cannot be deleted, renamed, or listed publicly.
 - **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.
-- **Owner permissions**: Index owners can update settings (title, prompt, joinPolicy), add/remove members, and delete the index (if sole member).
+- **Owner permissions**: Network owners can update settings (title, prompt, joinPolicy), add/remove members, and delete the network (if sole member).
 - **Discovery scope**: Opportunities are discovered within index boundaries — the system matches intents of members who share at least one index.
 
 ### Index Workflow
@@ -154,11 +154,11 @@ Profiles are the user's identity on the platform, used for semantic matching in
 - Profiles are recalculated when updated, which may surface new matches`,
                 contacts: `## Contact Management
 
-Contacts are people in a user's personal network, stored as members of their personal index with 'contact' permission.
+Contacts are people in a user's personal network, stored as members of their personal network with 'contact' permission.
 
 - **Adding contacts**: Via import_contacts (bulk), add_contact (single email), or import_gmail_contacts (Google integration).
 - **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.
-- **Personal index scope**: Pass the personal index networkId to discover_opportunities to scope discovery to just the user's contacts.
+- **Personal network scope**: Pass the personal network networkId to discover_opportunities to scope discovery to just the user's contacts.
 - **Contact data**: Each contact has userId, name, email, avatar, and isGhost flag.
 
 ### Contact Workflow
@@ -212,7 +212,7 @@ Discovery is the process of finding meaningful connections between users based o
 3. discover_opportunities(networkId=personalIndexId) → find matches among contacts
 
 ### Creating a Community
-1. create_network(title, prompt) → create index
+1. create_network(title, prompt) → create network
 2. create_network_membership(networkId, userId) → invite members
 3. Members create intents → auto-indexed
 4. discover_opportunities(networkId) → discover connections within community`,
@@ -226,10 +226,10 @@ Discovery is the process of finding meaningful connections between users based o
 
 ### Key Constraints
 - Users can only read their own intents globally, or intents in indexes they belong to
-- Users can only read profiles of people in shared indexes
-- Index-scoped operations are restricted to that index
-- Personal indexes cannot be deleted or renamed
-- Only index owners can update settings, add/remove members (for invite_only indexes)
+- Users can only read profiles of people in shared networks
+- Network-scoped operations are restricted to that index
+- Personal networks cannot be deleted or renamed
+- Only network owners can update settings, add/remove members (for invite_only networks)
 
 ### Rate Limits & Best Practices
 - Avoid unnecessary read_intents/read_networks calls — cache results within a conversation

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

@@ -1 +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\n**IMPORTANT: 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"]}
+{"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 network** (isPersonal=true) stores their contacts.\n- **Network 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 networks. 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 network members with 'contact' permission on the personal network. 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 Network 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 network context)\n- Contacts → Personal Network (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 networks 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 networks 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 networks. 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. Networks 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 network**: Each user has exactly one personal network (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**: Network owners can update settings (title, prompt, joinPolicy), add/remove members, and delete the network (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 network 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 network scope**: Pass the personal network 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 network\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 networks\n- Network-scoped operations are restricted to that index\n- Personal networks cannot be deleted or renamed\n- Only network owners can update settings, add/remove members (for invite_only networks)\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\n**IMPORTANT: 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"]}