@indexnetwork/protocol 0.3.3 → 0.4.0-rc.13.1

package/README.md

@@ -99,13 +99,18 @@ const server = createMcpServer(
 
 ## Publishing
 
-Publishing is handled via CI. Tag a release to trigger the workflow:
+Publishing is handled via CI:
 
 ```bash
-git tag protocol-vX.Y.Z
-git push upstream protocol-vX.Y.Z
+# dev pushes publish an rc prerelease
+git push <remote> dev
+
+# main pushes publish the stable release if the package version is new
+git push <remote> main
 ```
 
+`dev` publishes prerelease versions derived from `package.json` using npm's `rc` tag, for example `0.4.0-rc.123.1`. `main` publishes the base version from `package.json` to `latest`.
+
 Or publish manually from `packages/protocol/`:
 
 ```bash

package/dist/agent/agent.tools.d.ts

@@ -0,0 +1,3 @@
+import type { DefineTool, ToolDeps } from '../shared/agent/tool.helpers.js';
+export declare function createAgentTools(defineTool: DefineTool, deps: ToolDeps): never[] | readonly [any, any, any, any, any, any];
+//# sourceMappingURL=agent.tools.d.ts.map

package/dist/agent/agent.tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.tools.d.ts","sourceRoot":"","sources":["../../src/agent/agent.tools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AA4D5E,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,qDAmTtE"}

package/dist/agent/agent.tools.js

@@ -0,0 +1,330 @@
+import { z } from 'zod';
+import { error, success } from '../shared/agent/tool.helpers.js';
+const AGENT_ACTIONS = [
+    'manage:profile',
+    'manage:intents',
+    'manage:networks',
+    'manage:contacts',
+    'manage:negotiations',
+];
+function invalidActionMessage(action) {
+    return `Invalid action: ${action}. Valid actions: ${AGENT_ACTIONS.join(', ')}`;
+}
+function isValidAction(action) {
+    return AGENT_ACTIONS.includes(action);
+}
+function requireAgentDatabase(deps) {
+    if (!deps.agentDatabase) {
+        return null;
+    }
+    return deps.agentDatabase;
+}
+function ensureAgentScopedAccess(context, requestedAgentId) {
+    if (context.agentId && context.agentId !== requestedAgentId) {
+        return 'This agent can only manage its own registration.';
+    }
+    return null;
+}
+function sanitizeAgentForOutput(agent) {
+    return {
+        ...agent,
+        transports: agent.transports?.map((transport) => ({
+            ...transport,
+            config: transport.channel === 'webhook'
+                ? Object.fromEntries(Object.entries(transport.config).filter(([key]) => key !== 'secret'))
+                : transport.config,
+        })),
+    };
+}
+function normalizeWebhookEvents(events) {
+    return [...new Set((events ?? []).map((event) => event.trim()).filter(Boolean))];
+}
+function sanitizeAgentName(name) {
+    const cleanName = name.trim();
+    return cleanName ? cleanName : null;
+}
+function normalizePermissions(permissions) {
+    return [...new Set((permissions ?? []).map((action) => action.trim()).filter(Boolean))];
+}
+export function createAgentTools(defineTool, deps) {
+    const agentDb = requireAgentDatabase(deps);
+    if (!agentDb) {
+        return [];
+    }
+    const registerAgent = defineTool({
+        name: 'register_agent',
+        description: 'Register a new personal agent for the current user. Optionally configure a webhook transport and initial permissions. ' +
+            'Use this when connecting an external agent to Index.',
+        querySchema: z.object({
+            name: z.string().min(1).describe('Display name for the agent.'),
+            description: z.string().optional().describe('What the agent does.'),
+            webhook_url: z.string().optional().describe('Optional webhook URL for deliveries.'),
+            webhook_secret: z.string().optional().describe('Optional webhook secret stored in transport config.'),
+            webhook_events: z.array(z.string()).optional().describe('Subscribed webhook event names.'),
+            permissions: z.array(z.string()).optional().describe('Optional initial permission actions to grant.'),
+        }),
+        handler: async ({ context, query }) => {
+            if (context.agentId) {
+                return error('This agent can only manage its own registration.');
+            }
+            try {
+                const name = sanitizeAgentName(query.name);
+                if (!name) {
+                    return error('Agent name is required.');
+                }
+                const permissions = normalizePermissions(query.permissions);
+                for (const permission of permissions) {
+                    if (!isValidAction(permission)) {
+                        return error(invalidActionMessage(permission));
+                    }
+                }
+                let transportConfig;
+                if (query.webhook_url?.trim()) {
+                    const webhookEvents = normalizeWebhookEvents(query.webhook_events);
+                    if (webhookEvents.length === 0) {
+                        return error('Webhook events are required.');
+                    }
+                    let parsedUrl;
+                    try {
+                        parsedUrl = new URL(query.webhook_url);
+                    }
+                    catch {
+                        return error('Invalid webhook URL.');
+                    }
+                    if (parsedUrl.protocol !== 'https:' && process.env.NODE_ENV === 'production') {
+                        return error('Webhook URL must use HTTPS in production.');
+                    }
+                    transportConfig = {
+                        url: parsedUrl.toString(),
+                        events: webhookEvents,
+                        ...(query.webhook_secret?.trim() ? { secret: query.webhook_secret.trim() } : {}),
+                    };
+                }
+                const agent = await agentDb.createAgent({
+                    ownerId: context.userId,
+                    name,
+                    description: query.description?.trim() || undefined,
+                    type: 'personal',
+                });
+                try {
+                    if (transportConfig) {
+                        await agentDb.createTransport({
+                            agentId: agent.id,
+                            channel: 'webhook',
+                            config: transportConfig,
+                        });
+                    }
+                    if (permissions.length > 0) {
+                        await agentDb.grantPermission({
+                            agentId: agent.id,
+                            userId: context.userId,
+                            scope: 'global',
+                            actions: permissions,
+                        });
+                    }
+                }
+                catch (setupError) {
+                    try {
+                        await agentDb.deleteAgent(agent.id);
+                    }
+                    catch {
+                        // Best-effort cleanup to avoid leaving partially registered agents behind.
+                    }
+                    throw setupError;
+                }
+                const fullAgent = await agentDb.getAgentWithRelations(agent.id);
+                return success({
+                    message: `Agent "${agent.name}" registered successfully.`,
+                    agent: sanitizeAgentForOutput(fullAgent ?? ({ ...agent, transports: [], permissions: [] })),
+                });
+            }
+            catch (err) {
+                return error(`Failed to register agent: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
+    });
+    const listAgents = defineTool({
+        name: 'list_agents',
+        description: 'List all agents the current user owns or has authorized.',
+        querySchema: z.object({}),
+        handler: async ({ context }) => {
+            try {
+                const agents = await agentDb.listAgentsForUser(context.userId);
+                const filteredAgents = context.agentId
+                    ? agents.filter((agent) => agent.id === context.agentId)
+                    : agents;
+                return success({
+                    agents: filteredAgents.map((agent) => sanitizeAgentForOutput(agent)),
+                    count: filteredAgents.length,
+                });
+            }
+            catch (err) {
+                return error(`Failed to list agents: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
+    });
+    const updateAgent = defineTool({
+        name: 'update_agent',
+        description: 'Update an agent name, description, or status.',
+        querySchema: z.object({
+            agent_id: z.string().min(1).describe('The agent ID to update.'),
+            name: z.string().optional().describe('Updated display name.'),
+            description: z.string().optional().describe('Updated description.'),
+            status: z.enum(['active', 'inactive']).optional().describe('Updated status.'),
+        }),
+        handler: async ({ context, query }) => {
+            const scopeError = ensureAgentScopedAccess(context, query.agent_id);
+            if (scopeError) {
+                return error(scopeError);
+            }
+            try {
+                const agent = await agentDb.getAgent(query.agent_id);
+                if (!agent || agent.ownerId !== context.userId) {
+                    return error('Agent not found');
+                }
+                if (agent.type === 'system') {
+                    return error('System agents cannot be modified');
+                }
+                const updates = {};
+                if (query.name !== undefined) {
+                    const name = query.name.trim();
+                    if (!name) {
+                        return error('Agent name is required');
+                    }
+                    updates.name = name;
+                }
+                if (query.description !== undefined) {
+                    updates.description = query.description.trim() || null;
+                }
+                if (query.status) {
+                    updates.status = query.status;
+                }
+                if (Object.keys(updates).length === 0) {
+                    return error('At least one field is required.');
+                }
+                const updated = await agentDb.updateAgent(query.agent_id, updates);
+                if (!updated) {
+                    return error('Agent not found');
+                }
+                const fullAgent = await agentDb.getAgentWithRelations(query.agent_id);
+                return success({
+                    message: 'Agent updated.',
+                    agent: sanitizeAgentForOutput(fullAgent ?? ({ ...updated, transports: [], permissions: [] })),
+                });
+            }
+            catch (err) {
+                return error(`Failed to update agent: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
+    });
+    const deleteAgent = defineTool({
+        name: 'delete_agent',
+        description: 'Soft-delete a personal agent and deactivate its transports.',
+        querySchema: z.object({
+            agent_id: z.string().min(1).describe('The agent ID to delete.'),
+        }),
+        handler: async ({ context, query }) => {
+            const scopeError = ensureAgentScopedAccess(context, query.agent_id);
+            if (scopeError) {
+                return error(scopeError);
+            }
+            try {
+                const agent = await agentDb.getAgent(query.agent_id);
+                if (!agent || agent.ownerId !== context.userId) {
+                    return error('Agent not found');
+                }
+                if (agent.type === 'system') {
+                    return error('System agents cannot be deleted');
+                }
+                await agentDb.deleteAgent(query.agent_id);
+                return success({ message: `Agent "${agent.name}" deleted.` });
+            }
+            catch (err) {
+                return error(`Failed to delete agent: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
+    });
+    const grantAgentPermission = defineTool({
+        name: 'grant_agent_permission',
+        description: 'Grant one or more permissions to an agent for the current user.',
+        querySchema: z.object({
+            agent_id: z.string().min(1).describe('The agent ID to grant permissions to.'),
+            actions: z.array(z.string()).min(1).describe('Permission actions to grant.'),
+            scope: z.enum(['global', 'node', 'network']).optional().describe('Optional permission scope.'),
+            scope_id: z.string().optional().describe('Scope target ID for node/network scopes.'),
+        }),
+        handler: async ({ context, query }) => {
+            const scopeError = ensureAgentScopedAccess(context, query.agent_id);
+            if (scopeError) {
+                return error(scopeError);
+            }
+            const actions = [...new Set(query.actions.map((action) => action.trim()).filter(Boolean))];
+            if (actions.length === 0) {
+                return error('At least one non-empty action is required.');
+            }
+            for (const action of actions) {
+                if (!isValidAction(action)) {
+                    return error(invalidActionMessage(action));
+                }
+            }
+            if ((query.scope === 'network' || query.scope === 'node') && !query.scope_id?.trim()) {
+                return error(`scope_id is required for ${query.scope} permissions.`);
+            }
+            try {
+                const agent = await agentDb.getAgent(query.agent_id);
+                if (!agent || agent.ownerId !== context.userId) {
+                    return error('Agent not found');
+                }
+                const permission = await agentDb.grantPermission({
+                    agentId: query.agent_id,
+                    userId: context.userId,
+                    scope: query.scope,
+                    scopeId: query.scope === 'global' || query.scope === undefined ? undefined : query.scope_id?.trim(),
+                    actions,
+                });
+                return success({ message: 'Permission granted.', permission });
+            }
+            catch (err) {
+                return error(`Failed to grant permission: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
+    });
+    const revokeAgentPermission = defineTool({
+        name: 'revoke_agent_permission',
+        description: 'Revoke a specific permission from an agent.',
+        querySchema: z.object({
+            agent_id: z.string().min(1).describe('The agent ID that owns the permission.'),
+            permission_id: z.string().min(1).describe('The permission ID to revoke.'),
+        }),
+        handler: async ({ context, query }) => {
+            const scopeError = ensureAgentScopedAccess(context, query.agent_id);
+            if (scopeError) {
+                return error(scopeError);
+            }
+            try {
+                const agent = await agentDb.getAgentWithRelations(query.agent_id);
+                if (!agent || agent.ownerId !== context.userId) {
+                    return error('Agent not found');
+                }
+                const permission = agent.permissions.find((item) => item.id === query.permission_id);
+                if (!permission) {
+                    return error('Permission not found');
+                }
+                await agentDb.revokePermission(query.permission_id);
+                return success({ message: 'Permission revoked.' });
+            }
+            catch (err) {
+                return error(`Failed to revoke permission: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
+    });
+    return [
+        registerAgent,
+        listAgents,
+        updateAgent,
+        deleteAgent,
+        grantAgentPermission,
+        revokeAgentPermission,
+    ];
+}
+//# sourceMappingURL=agent.tools.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent.tools.js","sourceRoot":"","sources":["../../src/agent/agent.tools.ts"],"names":[],"mappings":"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"}

package/dist/contact/contact.tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contact.tools.d.ts","sourceRoot":"","sources":["../../src/contact/contact.tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAG5E;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,SAkHxE"}
+{"version":3,"file":"contact.tools.d.ts","sourceRoot":"","sources":["../../src/contact/contact.tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAG5E;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,SAqIxE"}

package/dist/contact/contact.tools.js

@@ -8,17 +8,20 @@ export function createContactTools(defineTool, deps) {
     const { contactService } = deps;
     const import_contacts = defineTool({
         name: 'import_contacts',
-        description: `Import contacts into the user's network from any integration or manual input.
-
-Each contact needs a name and email. Contacts without existing accounts become "ghost users"
-that are enriched with public profile data and can be matched in opportunity discovery.
-
-Returns import statistics including how many were imported, skipped, and how many new ghost users were created.`,
+        description: "Bulk-imports contacts into the authenticated user's personal network (personal index). Contacts become members of the user's " +
+            "personal index with 'contact' permission, making them available for opportunity discovery.\n\n" +
+            "**What happens:** Each contact is matched by email. If the email belongs to an existing user, they're linked directly. " +
+            "If not, a 'ghost user' is created — a placeholder account enriched with public profile data (from LinkedIn, GitHub, etc.) " +
+            "that participates in opportunity matching even before the person joins the platform.\n\n" +
+            "**When to use:** When the user provides a list of contacts to add (from CSV, manual input, or any source other than Gmail). " +
+            "For Gmail specifically, use import_gmail_contacts instead.\n\n" +
+            "**Returns:** Import statistics: imported (total processed), skipped (invalid), newContacts (ghost users created), " +
+            "existingContacts (already in network). Use list_contacts to see all contacts after import.",
         querySchema: z.object({
             contacts: z.array(z.object({
-                name: z.string().describe('Contact name'),
-                email: z.string().describe('Contact email address'),
-            })).describe('Array of contacts to import'),
+                name: z.string().describe('Full name of the contact (e.g. "Jane Smith")'),
+                email: z.string().describe('Email address — used as the unique identifier for matching existing users'),
+            })).describe('Array of contact objects to import. Each must have name and email. Duplicates (by email) are skipped.'),
         }),
         handler: async ({ context, query }) => {
             try {
@@ -38,12 +41,15 @@ Returns import statistics including how many were imported, skipped, and how man
     });
     const list_contacts = defineTool({
         name: 'list_contacts',
-        description: `List the user's network contacts. Returns all contacts with their details.
-Each contact includes userId, name, email, avatar, and isGhost flag.
-Ghost users (contacts without accounts) are marked with isGhost: true.
-Use the userId field with read_user_profiles to look up a contact's full profile.`,
+        description: "Lists all contacts in the authenticated user's personal network. Contacts are people the user has added " +
+            "(via import_contacts, add_contact, or import_gmail_contacts) stored as members of their personal index.\n\n" +
+            "**When to use:** To see who's in the user's network, find a contact's userId for other operations, " +
+            "or check if a specific person is already a contact.\n\n" +
+            "**Returns:** Array of contacts, each with: userId (use with read_user_profiles or create_opportunities), " +
+            "name, email, avatar URL, and isGhost (true = no account yet, profile enriched from public data). " +
+            "Use the userId with read_user_profiles(userId) to get the full profile, or with create_opportunities(targetUserId) to connect.",
         querySchema: z.object({
-            limit: z.number().optional().describe('Maximum number of contacts to return (default: all)'),
+            limit: z.number().optional().describe('Maximum number of contacts to return. Omit to return all contacts. Use for large networks to paginate results.'),
         }),
         handler: async ({ context, query }) => {
             try {
@@ -69,12 +75,17 @@ Use the userId field with read_user_profiles to look up a contact's full profile
     });
     const add_contact = defineTool({
         name: 'add_contact',
-        description: `Manually add a single contact to the user's network by email.
-Use this when the user wants to add a specific person to their network.
-If no account exists for that email, a ghost user is created and enriched with public data.`,
+        description: "Adds a single contact to the authenticated user's personal network by email address. " +
+            "For bulk imports, use import_contacts instead.\n\n" +
+            "**What happens:** Looks up the email. If an account exists, links that user as a contact. " +
+            "If not, creates a ghost user (placeholder enriched with public profile data) and adds them. " +
+            "The contact can then appear in opportunity discovery within the user's personal index.\n\n" +
+            "**When to use:** When the user wants to add a specific person (e.g. 'add john@example.com to my network').\n\n" +
+            "**Returns:** Confirmation with the contact's userId and whether a new ghost user was created (isNewGhost). " +
+            "Use the userId with create_opportunities(targetUserId) to find connection opportunities.",
         querySchema: z.object({
-            email: z.string().describe('Email address of the contact to add'),
-            name: z.string().optional().describe('Name of the contact (optional, will use email prefix if not provided)'),
+            email: z.string().describe('Email address of the person to add. Used as unique identifier — if already a contact, the operation is idempotent.'),
+            name: z.string().optional().describe('Full name of the contact. Optional — if omitted, the email prefix is used as name. Provide when known for better profile enrichment.'),
         }),
         handler: async ({ context, query }) => {
             try {
@@ -95,10 +106,14 @@ If no account exists for that email, a ghost user is created and enriched with p
     });
     const remove_contact = defineTool({
         name: 'remove_contact',
-        description: `Remove a contact from the user's network.
-Use the contact's userId from list_contacts. This removes the contact relationship.`,
+        description: "Removes a contact from the authenticated user's personal network. The contact relationship is deleted — " +
+            "the person is no longer a member of the user's personal index and won't appear in personal-index-scoped discovery.\n\n" +
+            "**When to use:** When the user wants to remove someone from their network (e.g. 'remove John from my contacts').\n\n" +
+            "**Note:** This only removes the contact relationship. If the contact is a real user (not a ghost), " +
+            "they still exist on the platform and may appear in shared index discovery.\n\n" +
+            "**Returns:** Confirmation that the contact was removed.",
         querySchema: z.object({
-            contactUserId: z.string().describe('The user ID of the contact to remove (from list_contacts)'),
+            contactUserId: z.string().describe('The userId of the contact to remove. Get this from list_contacts results.'),
         }),
         handler: async ({ context, query }) => {
             try {

package/dist/contact/contact.tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"contact.tools.js","sourceRoot":"","sources":["../../src/contact/contact.tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contact.tools.js","sourceRoot":"","sources":["../../src/contact/contact.tools.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -15,6 +15,10 @@ export type * from "./shared/interfaces/integration.interface.js";
 export type * from "./shared/interfaces/queue.interface.js";
 export type * from "./shared/interfaces/scraper.interface.js";
 export type * from "./shared/interfaces/storage.interface.js";
+export type * from "./shared/interfaces/webhook.interface.js";
+export type * from "./shared/interfaces/negotiation-events.interface.js";
+export type { AgentRecord, AgentTransportRecord, AgentPermissionRecord, AgentWithRelations, CreateAgentInput, CreateTransportInput, GrantPermissionInput, AgentDatabase, } from './shared/interfaces/agent.interface.js';
+export { SYSTEM_AGENT_IDS } from './shared/interfaces/agent.interface.js';
 export { ChatGraphFactory } from "./chat/chat.graph.js";
 export { HomeGraphFactory } from "./opportunity/feed/feed.graph.js";
 export { HydeGraphFactory } from "./shared/hyde/hyde.graph.js";
@@ -54,9 +58,10 @@ export { presentOpportunity } from "./opportunity/opportunity.presentation.js";
 export type { UserInfo } from "./opportunity/opportunity.presentation.js";
 export { stripUuids, stripIntroducerMentions } from "./opportunity/opportunity.presentation.js";
 export { createToolRegistry } from "./shared/agent/tool.registry.js";
+export { createAgentTools } from './agent/agent.tools.js';
 export { createMcpServer } from "./mcp/mcp.server.js";
 export type { ScopedDepsFactory } from "./mcp/mcp.server.js";
-export type { UserNegotiationContext, NegotiationTurn, SeedAssessment, NegotiationGraphLike, } from "./negotiation/negotiation.state.js";
+export type { UserNegotiationContext, NegotiationTurn, NegotiationOutcome, SeedAssessment, NegotiationGraphLike, } from "./negotiation/negotiation.state.js";
 export { ChatStreamer } from "./chat/chat.streamer.js";
 export { ResponseStreamer } from "./shared/agent/response.streamer.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -2,6 +2,7 @@
 export { createChatTools } from "./shared/agent/tool.factory.js";
 export { configureProtocol } from "./shared/agent/model.config.js";
 export { ChatContextAccessError, resolveChatContext } from "./shared/agent/tool.helpers.js";
+export { SYSTEM_AGENT_IDS } from './shared/interfaces/agent.interface.js';
 // ─── Graph factories ──────────────────────────────────────────────────────────
 export { ChatGraphFactory } from "./chat/chat.graph.js";
 export { HomeGraphFactory } from "./opportunity/feed/feed.graph.js";
@@ -36,6 +37,7 @@ export { presentOpportunity } from "./opportunity/opportunity.presentation.js";
 export { stripUuids, stripIntroducerMentions } from "./opportunity/opportunity.presentation.js";
 // ─── Tools ────────────────────────────────────────────────────────────────────
 export { createToolRegistry } from "./shared/agent/tool.registry.js";
+export { createAgentTools } from './agent/agent.tools.js';
 // ─── MCP ──────────────────────────────────────────────────────────────────────
 export { createMcpServer } from "./mcp/mcp.server.js";
 // ─── Streamers ────────────────────────────────────────────────────────────────

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAEjF,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAYnE,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAgB5F,iFAAiF;AAEjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,6BAA6B,EAAE,MAAM,0CAA0C,CAAC;AACzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,yBAAyB,EAAE,MAAM,oCAAoC,CAAC;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAM7E,OAAO,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AACjI,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE,iFAAiF;AAEjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,EAAE,4BAA4B,EAAE,MAAM,iDAAiD,CAAC;AAE/F,OAAO,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAK9E,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAGtG,iFAAiF;AAEjF,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,EACzB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAEtE,OAAO,EACL,0BAA0B,EAC1B,4BAA4B,EAC5B,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,yCAAyC,CAAC;AAMjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAC;AAE/E,OAAO,EAAE,UAAU,EAAE,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AAEhG,iFAAiF;AAEjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAErE,iFAAiF;AAEjF,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAYtD,iFAAiF;AAEjF,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAEjF,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAYnE,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AA2B5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAC;AAE1E,iFAAiF;AAEjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,6BAA6B,EAAE,MAAM,0CAA0C,CAAC;AACzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,yBAAyB,EAAE,MAAM,oCAAoC,CAAC;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAM7E,OAAO,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AACjI,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE,iFAAiF;AAEjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,EAAE,4BAA4B,EAAE,MAAM,iDAAiD,CAAC;AAE/F,OAAO,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAK9E,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAGtG,iFAAiF;AAEjF,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,EACzB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAEtE,OAAO,EACL,0BAA0B,EAC1B,4BAA4B,EAC5B,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,yCAAyC,CAAC;AAMjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAC;AAE/E,OAAO,EAAE,UAAU,EAAE,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AAEhG,iFAAiF;AAEjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,iFAAiF;AAEjF,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAatD,iFAAiF;AAEjF,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC"}

package/dist/integration/integration.tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"integration.tools.d.ts","sourceRoot":"","sources":["../../src/integration/integration.tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAO5E;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,SAmE5E"}
+{"version":3,"file":"integration.tools.d.ts","sourceRoot":"","sources":["../../src/integration/integration.tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAO5E;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,SAsE5E"}

package/dist/integration/integration.tools.js

@@ -17,14 +17,16 @@ export function createIntegrationTools(defineTool, deps) {
     const { integration, integrationImporter } = deps;
     const import_gmail_contacts = defineTool({
         name: 'import_gmail_contacts',
-        description: `Import contacts from the user's Gmail/Google account into their network.
-
-If the user hasn't connected their Gmail account yet, returns an auth URL they need to visit first.
-
-After successful import, contacts are added to the user's network as ghost users
-(enriched with public profile data) and can be matched in opportunity discovery.
-
-Returns import statistics or an auth URL if authentication is needed.`,
+        description: "Imports contacts from the user's connected Gmail/Google account into their personal network. " +
+            "This is the preferred method for importing Google Contacts — handles OAuth authentication, pagination, and deduplication automatically.\n\n" +
+            "**Authentication flow:** If Gmail is not yet connected, returns an `authUrl` the user must visit to grant access. " +
+            "After they complete OAuth, call this tool again to perform the actual import.\n\n" +
+            "**What happens on import:** All Gmail contacts with valid name+email are imported. " +
+            "Contacts without existing platform accounts become ghost users (enriched with public profile data from LinkedIn, GitHub, etc.). " +
+            "All imported contacts are added to the user's personal index for opportunity discovery.\n\n" +
+            "**When to use:** When the user asks to import or sync their Gmail/Google contacts. No parameters needed.\n\n" +
+            "**Returns:** Either `{ requiresAuth: true, authUrl }` (user needs to authenticate) or import statistics: " +
+            "imported (total), newContacts (ghost users created), existingContacts (already in network), skipped (invalid entries).",
         querySchema: z.object({}),
         handler: async ({ context }) => {
             try {