@indexnetwork/protocol 6.12.1-rc.404.1 → 6.13.22-rc.405.1

package/dist/contact/contact.inviter.js

@@ -1,62 +1,9 @@
 /**
- * Invite Generator Agent
+ * @deprecated Canonical location: contacts/application/contact.inviter
+ * Retained for backward compatibility during IND-549 migration.
+ * Import generateInviteMessage from contacts/application or via
+ * capabilities/contacts.facade.ts instead.
  *
- * Generates contextual, editable invite messages for ghost users.
- * Produces warm, concise messages (~3-5 sentences) referencing why two
- * users were matched, with optional referrer mention.
+ * IND-549: migrated to src/contacts/application/contact.inviter.ts.
  */
-import { HumanMessage, SystemMessage } from "@langchain/core/messages";
-import { z } from "zod";
-import { createStructuredModel } from "../shared/agent/model.config.js";
-import { stripUnsupportedOpportunityClaims } from "../opportunity/opportunity.claim-safety.js";
-const InviteInputSchema = z.object({
-    recipientName: z.string(),
-    senderName: z.string(),
-    opportunityInterpretation: z.string(),
-    senderIntents: z.array(z.string()),
-    recipientIntents: z.array(z.string()),
-    referrerName: z.string().optional(),
-});
-const InviteOutputSchema = z.object({
-    message: z.string().describe("The invite message text, ready to edit and send"),
-});
-const SYSTEM_PROMPT = `You generate brief, casual invite messages for a discovery platform called Index.
-
-The sender wants to reach out to someone they were matched with. Write a short, human message (2-3 sentences max) that:
-- Sounds like a real person texting, not a LinkedIn outreach or AI email
-- References one concrete, specific detail from the opportunity context — something actual, like a specific project, technology, or goal they share. Not "we have similar interests" or "I noticed we're both in this space" — name the actual thing.
-- If a referrer is provided, casually drops that they were introduced
-- Ends naturally — no formal CTAs, no "Would you be open to..." closings
-
-Tone: casual, direct, human. Think how you'd actually message someone you just got introduced to.
-Do NOT use a generic opener like "Hi [Name], I'm [Sender]." Just get to the point.
-Do NOT summarize the person's background. Pick one real, specific overlap from the context and mention it.
-Do NOT include a subject line. This is a chat message.
-Do NOT use placeholder brackets like [Name]. Use the actual names provided.
-Network assignment, network title/type, and event/network metadata are retrieval context only. They are NEVER proof that either person attended or will attend, belongs to a group, resides in a place, knows anyone from the network, or shared a session, time, place, or location. Do not make co-attendance, membership, residence, shared-session, or same-place/same-time claims from network co-membership.`;
-/**
- * Generates a contextual invite message for a ghost user.
- * @param input - Context about sender, recipient, and opportunity
- * @returns Generated invite message text
- */
-export async function generateInviteMessage(input) {
-    const validated = InviteInputSchema.parse(input);
-    const structuredModel = createStructuredModel("inviteGenerator", InviteOutputSchema);
-    const safeInterpretation = stripUnsupportedOpportunityClaims(validated.opportunityInterpretation) ||
-        "Their current goals may be relevant to each other.";
-    const userPrompt = `Generate an invite message with this context:
-- Sender: ${validated.senderName}
-- Recipient: ${validated.recipientName}
-- Why they matched: ${safeInterpretation}
-- Sender's interests: ${validated.senderIntents.join(', ') || 'Not specified'}
-- Recipient's interests: ${validated.recipientIntents.join(', ') || 'Not specified'}${validated.referrerName ? `\n- Referred by: ${validated.referrerName}` : ''}`;
-    const result = InviteOutputSchema.parse(await structuredModel.invoke([
-        new SystemMessage(SYSTEM_PROMPT),
-        new HumanMessage(userPrompt),
-    ]));
-    const safeMessage = stripUnsupportedOpportunityClaims(result.message);
-    return {
-        message: safeMessage || "Thought it could be useful for us to compare notes on what we're working on.",
-    };
-}
-//# sourceMappingURL=contact.inviter.js.map
+export { generateInviteMessage } from "../contacts/application/index.js";

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

@@ -1,7 +1,9 @@
-import type { DefineTool, ToolDeps } from '../shared/agent/tool.helpers.js';
 /**
- * Creates contact management tools for the chat agent.
- * Enables importing, listing, and managing the user's network.
+ * @deprecated Canonical location: contacts/application/contact.tools
+ * Retained for backward compatibility during IND-549 migration.
+ * Import createContactTools from contacts/application or via
+ * capabilities/contacts.facade.ts instead.
+ *
+ * IND-549: migrated to src/contacts/application/contact.tools.ts.
  */
-export declare function createContactTools(defineTool: DefineTool, deps: ToolDeps): any[];
-//# sourceMappingURL=contact.tools.d.ts.map
+export { createContactTools } from "../contacts/application/index.js";

package/dist/contact/contact.tools.js

@@ -1,179 +1,9 @@
-import { z } from 'zod';
-import { success, error } from '../shared/agent/tool.helpers.js';
-import { protocolLogger } from '../shared/observability/protocol.logger.js';
-const logger = protocolLogger('ChatTools:Contact');
 /**
- * Creates contact management tools for the chat agent.
- * Enables importing, listing, and managing the user's network.
+ * @deprecated Canonical location: contacts/application/contact.tools
+ * Retained for backward compatibility during IND-549 migration.
+ * Import createContactTools from contacts/application or via
+ * capabilities/contacts.facade.ts instead.
+ *
+ * IND-549: migrated to src/contacts/application/contact.tools.ts.
  */
-export function createContactTools(defineTool, deps) {
-    const { contactService } = deps;
-    // Contact import / manual-add create ghost users. These are gated behind the
-    // CONTACTS_ENABLED flag (injected as deps.contactsEnabled). Read/remove/search
-    // tools below are always available so existing contacts stay manageable.
-    const contactsEnabled = deps.contactsEnabled === true;
-    // Only register when enabled: in the registry path defineTool registers as a
-    // side effect, so the call itself must be gated, not just the returned array.
-    const import_contacts = contactsEnabled ? defineTool({
-        name: 'import_contacts',
-        description: "Bulk-imports contacts into the authenticated user's personal network (personal network). Contacts become members of the user's " +
-            "personal network 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('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 {
-                const result = await contactService.importContacts(context.userId, query.contacts);
-                return success({
-                    message: `Imported ${result.imported} contacts to your network.`,
-                    imported: result.imported,
-                    skipped: result.skipped,
-                    newContacts: result.newContacts,
-                    existingContacts: result.existingContacts,
-                });
-            }
-            catch (err) {
-                logger.error('Failed to import contacts', { err });
-                return error('Failed to import contacts. Please try again.');
-            }
-        },
-    }) : null;
-    const list_contacts = defineTool({
-        name: 'list_contacts',
-        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 network.\n\n" +
-            "**When to use:** To see who's in the user's network, find a contact's userId for other operations, " +
-            "or check if a specific person is already a contact.\n\n" +
-            "**Returns:** Array of contacts, each with: userId (use with read_user_contexts or discover_opportunities), " +
-            "name, email, avatar URL, and isGhost (true = no account yet, profile enriched from public data). " +
-            "Use the userId with read_user_contexts(userId) to get the full profile, or with discover_opportunities(targetUserId) to connect.",
-        querySchema: z.object({
-            limit: z.number().optional().describe('Maximum number of contacts to return. Omit to return all contacts. Use for large networks to paginate results.'),
-        }),
-        handler: async ({ context, query }) => {
-            try {
-                let contacts = await contactService.listContacts(context.userId);
-                if (query.limit && query.limit > 0) {
-                    contacts = contacts.slice(0, query.limit);
-                }
-                return success({
-                    count: contacts.length,
-                    contacts: contacts.map(c => ({
-                        userId: c.userId,
-                        name: c.user.name,
-                        email: c.user.email,
-                        avatar: c.user.avatar,
-                        isGhost: c.user.isGhost,
-                    })),
-                });
-            }
-            catch (err) {
-                logger.error('Failed to list contacts', { err });
-                return error('Failed to list contacts. Please try again.');
-            }
-        },
-    });
-    const add_contact = contactsEnabled ? defineTool({
-        name: 'add_contact',
-        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 network.\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 discover_opportunities(targetUserId) to find connection opportunities.",
-        querySchema: z.object({
-            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 {
-                const result = await contactService.addContact(context.userId, query.email, { name: query.name, restore: true });
-                return success({
-                    added: true,
-                    message: result.isNew
-                        ? `Added ${query.name || query.email} to your network. Their profile is being enriched.`
-                        : `Added ${query.name || query.email} to your network.`,
-                    userId: result.userId,
-                    isNewGhost: result.isNew,
-                });
-            }
-            catch (err) {
-                logger.error('Failed to add contact', { err });
-                return error('Failed to add contact. Please try again.');
-            }
-        },
-    }) : null;
-    const remove_contact = defineTool({
-        name: 'remove_contact',
-        description: "Removes a contact from the authenticated user's personal network. The contact relationship is deleted — " +
-            "the person is no longer a member of the user's personal network and won't appear in personal-network-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 network discovery.\n\n" +
-            "**Returns:** Confirmation that the contact was removed.",
-        querySchema: z.object({
-            contactUserId: z.string().describe('The userId of the contact to remove. Get this from list_contacts results.'),
-        }),
-        handler: async ({ context, query }) => {
-            try {
-                await contactService.removeContact(context.userId, query.contactUserId);
-                return success({ removed: true, message: 'Contact removed from your network.' });
-            }
-            catch (err) {
-                logger.error('Failed to remove contact', { err });
-                return error('Failed to remove contact. Please try again.');
-            }
-        },
-    });
-    const search_contacts = defineTool({
-        name: 'search_contacts',
-        description: "Searches the authenticated user's personal network by name or email (case-insensitive substring). " +
-            "Use when the user refers to a contact by partial name or email and you need their userId for another tool " +
-            "(e.g. read_user_contexts, discover_opportunities).\n\n" +
-            "**When to use:** Before list_contacts when the network is large — returns only matching contacts, bounded by limit.\n\n" +
-            "**Returns:** Array of matching contacts: userId, name, email, avatar, isGhost.",
-        querySchema: z.object({
-            query: z.string().trim().min(1).describe('Free-text query matched against contact name and email (case-insensitive, substring).'),
-            limit: z.number().int().positive().max(100).optional().describe('Maximum rows to return. Defaults to 25.'),
-        }),
-        handler: async ({ context, query }) => {
-            try {
-                const rows = await contactService.searchContacts(context.userId, query.query, query.limit ?? 25);
-                return success({
-                    count: rows.length,
-                    contacts: rows.map(r => ({
-                        userId: r.contactId,
-                        name: r.name,
-                        email: r.email,
-                        avatar: r.avatar,
-                        isGhost: r.isGhost,
-                    })),
-                });
-            }
-            catch (err) {
-                logger.error('Failed to search contacts', { err });
-                return error('Failed to search contacts. Please try again.');
-            }
-        },
-    });
-    return [
-        ...(import_contacts ? [import_contacts] : []),
-        ...(add_contact ? [add_contact] : []),
-        list_contacts,
-        remove_contact,
-        search_contacts,
-    ];
-}
-//# sourceMappingURL=contact.tools.js.map
+export { createContactTools } from "../contacts/application/index.js";

package/dist/contacts/application/contact.inviter.d.ts

@@ -0,0 +1,49 @@
+/**
+ * contacts/application — generateInviteMessage canonical implementation.
+ *
+ * Invite Generator Agent: generates contextual, editable invite messages for
+ * ghost users. Produces warm, concise messages (~2-3 sentences) referencing
+ * why two users were matched, with optional referrer mention.
+ *
+ * IND-549: moved from contact/contact.inviter.ts into the canonical
+ * contacts/application layer.
+ */
+import { z } from "zod";
+declare const InviteInputSchema: z.ZodObject<{
+    recipientName: z.ZodString;
+    senderName: z.ZodString;
+    opportunityInterpretation: z.ZodString;
+    senderIntents: z.ZodArray<z.ZodString, "many">;
+    recipientIntents: z.ZodArray<z.ZodString, "many">;
+    referrerName: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    recipientName: string;
+    senderName: string;
+    opportunityInterpretation: string;
+    senderIntents: string[];
+    recipientIntents: string[];
+    referrerName?: string | undefined;
+}, {
+    recipientName: string;
+    senderName: string;
+    opportunityInterpretation: string;
+    senderIntents: string[];
+    recipientIntents: string[];
+    referrerName?: string | undefined;
+}>;
+declare const InviteOutputSchema: z.ZodObject<{
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+}, {
+    message: string;
+}>;
+export type InviteInput = z.infer<typeof InviteInputSchema>;
+export type InviteOutput = z.infer<typeof InviteOutputSchema>;
+/**
+ * Generates a contextual invite message for a ghost user.
+ * @param input - Context about sender, recipient, and opportunity
+ * @returns Generated invite message text
+ */
+export declare function generateInviteMessage(input: InviteInput): Promise<InviteOutput>;
+export {};

package/dist/contacts/application/contact.inviter.js

@@ -0,0 +1,64 @@
+/**
+ * contacts/application — generateInviteMessage canonical implementation.
+ *
+ * Invite Generator Agent: generates contextual, editable invite messages for
+ * ghost users. Produces warm, concise messages (~2-3 sentences) referencing
+ * why two users were matched, with optional referrer mention.
+ *
+ * IND-549: moved from contact/contact.inviter.ts into the canonical
+ * contacts/application layer.
+ */
+import { HumanMessage, SystemMessage } from "@langchain/core/messages";
+import { z } from "zod";
+import { createStructuredModel } from "../../shared/agent/model.config.js";
+import { stripUnsupportedOpportunityClaims } from "../../capabilities/opportunities.safety.facade.js";
+const InviteInputSchema = z.object({
+    recipientName: z.string(),
+    senderName: z.string(),
+    opportunityInterpretation: z.string(),
+    senderIntents: z.array(z.string()),
+    recipientIntents: z.array(z.string()),
+    referrerName: z.string().optional(),
+});
+const InviteOutputSchema = z.object({
+    message: z.string().describe("The invite message text, ready to edit and send"),
+});
+const SYSTEM_PROMPT = `You generate brief, casual invite messages for a discovery platform called Index.
+
+The sender wants to reach out to someone they were matched with. Write a short, human message (2-3 sentences max) that:
+- Sounds like a real person texting, not a LinkedIn outreach or AI email
+- References one concrete, specific detail from the opportunity context — something actual, like a specific project, technology, or goal they share. Not "we have similar interests" or "I noticed we're both in this space" — name the actual thing.
+- If a referrer is provided, casually drops that they were introduced
+- Ends naturally — no formal CTAs, no "Would you be open to..." closings
+
+Tone: casual, direct, human. Think how you'd actually message someone you just got introduced to.
+Do NOT use a generic opener like "Hi [Name], I'm [Sender]." Just get to the point.
+Do NOT summarize the person's background. Pick one real, specific overlap from the context and mention it.
+Do NOT include a subject line. This is a chat message.
+Do NOT use placeholder brackets like [Name]. Use the actual names provided.
+Network assignment, network title/type, and event/network metadata are retrieval context only. They are NEVER proof that either person attended or will attend, belongs to a group, resides in a place, knows anyone from the network, or shared a session, time, place, or location. Do not make co-attendance, membership, residence, shared-session, or same-place/same-time claims from network co-membership.`;
+/**
+ * Generates a contextual invite message for a ghost user.
+ * @param input - Context about sender, recipient, and opportunity
+ * @returns Generated invite message text
+ */
+export async function generateInviteMessage(input) {
+    const validated = InviteInputSchema.parse(input);
+    const structuredModel = createStructuredModel("inviteGenerator", InviteOutputSchema);
+    const safeInterpretation = stripUnsupportedOpportunityClaims(validated.opportunityInterpretation) ||
+        "Their current goals may be relevant to each other.";
+    const userPrompt = `Generate an invite message with this context:
+- Sender: ${validated.senderName}
+- Recipient: ${validated.recipientName}
+- Why they matched: ${safeInterpretation}
+- Sender's interests: ${validated.senderIntents.join(', ') || 'Not specified'}
+- Recipient's interests: ${validated.recipientIntents.join(', ') || 'Not specified'}${validated.referrerName ? `\n- Referred by: ${validated.referrerName}` : ''}`;
+    const result = InviteOutputSchema.parse(await structuredModel.invoke([
+        new SystemMessage(SYSTEM_PROMPT),
+        new HumanMessage(userPrompt),
+    ]));
+    const safeMessage = stripUnsupportedOpportunityClaims(result.message);
+    return {
+        message: safeMessage || "Thought it could be useful for us to compare notes on what we're working on.",
+    };
+}

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

@@ -0,0 +1,20 @@
+/**
+ * contacts/application — createContactTools canonical implementation.
+ *
+ * Creates contact management tools for the chat agent. Enables importing,
+ * listing, adding, removing, and searching the user's personal network.
+ *
+ * Feature gating: import_contacts and add_contact are gated behind the
+ * CONTACTS_ENABLED flag (deps.contactsEnabled). List, remove, and search
+ * tools are always registered so existing contacts stay manageable.
+ *
+ * IND-549: moved from contact/contact.tools.ts into the canonical
+ * contacts/application layer.
+ */
+import type { DefineTool } from '../../shared/agent/tool.helpers.js';
+import type { ContactToolDeps } from '../ports/index.js';
+/**
+ * Creates contact management tools for the chat agent.
+ * Enables importing, listing, and managing the user's network.
+ */
+export declare function createContactTools(defineTool: DefineTool, deps: ContactToolDeps): any[];

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

@@ -0,0 +1,191 @@
+/**
+ * contacts/application — createContactTools canonical implementation.
+ *
+ * Creates contact management tools for the chat agent. Enables importing,
+ * listing, adding, removing, and searching the user's personal network.
+ *
+ * Feature gating: import_contacts and add_contact are gated behind the
+ * CONTACTS_ENABLED flag (deps.contactsEnabled). List, remove, and search
+ * tools are always registered so existing contacts stay manageable.
+ *
+ * IND-549: moved from contact/contact.tools.ts into the canonical
+ * contacts/application layer.
+ */
+import { z } from 'zod';
+import { success, error } from '../../shared/agent/tool.helpers.js';
+import { protocolLogger } from '../../shared/observability/protocol.logger.js';
+const logger = protocolLogger('ChatTools:Contact');
+/**
+ * Creates contact management tools for the chat agent.
+ * Enables importing, listing, and managing the user's network.
+ */
+export function createContactTools(defineTool, deps) {
+    const { contactService } = deps;
+    // Contact import / manual-add create ghost users. These are gated behind the
+    // CONTACTS_ENABLED flag (injected as deps.contactsEnabled). Read/remove/search
+    // tools below are always available so existing contacts stay manageable.
+    const contactsEnabled = deps.contactsEnabled === true;
+    // Only register when enabled: in the registry path defineTool registers as a
+    // side effect, so the call itself must be gated, not just the returned array.
+    const import_contacts = contactsEnabled ? defineTool({
+        name: 'import_contacts',
+        description: "Bulk-imports contacts into the authenticated user's personal network (personal network). Contacts become members of the user's " +
+            "personal network 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('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 {
+                const result = await contactService.importContacts(context.userId, query.contacts);
+                return success({
+                    message: `Imported ${result.imported} contacts to your network.`,
+                    imported: result.imported,
+                    skipped: result.skipped,
+                    newContacts: result.newContacts,
+                    existingContacts: result.existingContacts,
+                });
+            }
+            catch (err) {
+                logger.error('Failed to import contacts', { err });
+                return error('Failed to import contacts. Please try again.');
+            }
+        },
+    }) : null;
+    const list_contacts = defineTool({
+        name: 'list_contacts',
+        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 network.\n\n" +
+            "**When to use:** To see who's in the user's network, find a contact's userId for other operations, " +
+            "or check if a specific person is already a contact.\n\n" +
+            "**Returns:** Array of contacts, each with: userId (use with read_user_contexts or discover_opportunities), " +
+            "name, email, avatar URL, and isGhost (true = no account yet, profile enriched from public data). " +
+            "Use the userId with read_user_contexts(userId) to get the full profile, or with discover_opportunities(targetUserId) to connect.",
+        querySchema: z.object({
+            limit: z.number().optional().describe('Maximum number of contacts to return. Omit to return all contacts. Use for large networks to paginate results.'),
+        }),
+        handler: async ({ context, query }) => {
+            try {
+                let contacts = await contactService.listContacts(context.userId);
+                if (query.limit && query.limit > 0) {
+                    contacts = contacts.slice(0, query.limit);
+                }
+                return success({
+                    count: contacts.length,
+                    contacts: contacts.map(c => ({
+                        userId: c.userId,
+                        name: c.user.name,
+                        email: c.user.email,
+                        avatar: c.user.avatar,
+                        isGhost: c.user.isGhost,
+                    })),
+                });
+            }
+            catch (err) {
+                logger.error('Failed to list contacts', { err });
+                return error('Failed to list contacts. Please try again.');
+            }
+        },
+    });
+    const add_contact = contactsEnabled ? defineTool({
+        name: 'add_contact',
+        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 network.\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 discover_opportunities(targetUserId) to find connection opportunities.",
+        querySchema: z.object({
+            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 {
+                const result = await contactService.addContact(context.userId, query.email, { name: query.name, restore: true });
+                return success({
+                    added: true,
+                    message: result.isNew
+                        ? `Added ${query.name || query.email} to your network. Their profile is being enriched.`
+                        : `Added ${query.name || query.email} to your network.`,
+                    userId: result.userId,
+                    isNewGhost: result.isNew,
+                });
+            }
+            catch (err) {
+                logger.error('Failed to add contact', { err });
+                return error('Failed to add contact. Please try again.');
+            }
+        },
+    }) : null;
+    const remove_contact = defineTool({
+        name: 'remove_contact',
+        description: "Removes a contact from the authenticated user's personal network. The contact relationship is deleted — " +
+            "the person is no longer a member of the user's personal network and won't appear in personal-network-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 network discovery.\n\n" +
+            "**Returns:** Confirmation that the contact was removed.",
+        querySchema: z.object({
+            contactUserId: z.string().describe('The userId of the contact to remove. Get this from list_contacts results.'),
+        }),
+        handler: async ({ context, query }) => {
+            try {
+                await contactService.removeContact(context.userId, query.contactUserId);
+                return success({ removed: true, message: 'Contact removed from your network.' });
+            }
+            catch (err) {
+                logger.error('Failed to remove contact', { err });
+                return error('Failed to remove contact. Please try again.');
+            }
+        },
+    });
+    const search_contacts = defineTool({
+        name: 'search_contacts',
+        description: "Searches the authenticated user's personal network by name or email (case-insensitive substring). " +
+            "Use when the user refers to a contact by partial name or email and you need their userId for another tool " +
+            "(e.g. read_user_contexts, discover_opportunities).\n\n" +
+            "**When to use:** Before list_contacts when the network is large — returns only matching contacts, bounded by limit.\n\n" +
+            "**Returns:** Array of matching contacts: userId, name, email, avatar, isGhost.",
+        querySchema: z.object({
+            query: z.string().trim().min(1).describe('Free-text query matched against contact name and email (case-insensitive, substring).'),
+            limit: z.number().int().positive().max(100).optional().describe('Maximum rows to return. Defaults to 25.'),
+        }),
+        handler: async ({ context, query }) => {
+            try {
+                const rows = await contactService.searchContacts(context.userId, query.query, query.limit ?? 25);
+                return success({
+                    count: rows.length,
+                    contacts: rows.map(r => ({
+                        userId: r.contactId,
+                        name: r.name,
+                        email: r.email,
+                        avatar: r.avatar,
+                        isGhost: r.isGhost,
+                    })),
+                });
+            }
+            catch (err) {
+                logger.error('Failed to search contacts', { err });
+                return error('Failed to search contacts. Please try again.');
+            }
+        },
+    });
+    return [
+        ...(import_contacts ? [import_contacts] : []),
+        ...(add_contact ? [add_contact] : []),
+        list_contacts,
+        remove_contact,
+        search_contacts,
+    ];
+}

package/dist/contacts/application/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * contacts/application — foreground adapters and application services.
+ *
+ * ## Exports
+ *
+ * ### Tool factory
+ * - `createContactTools` — creates contact management MCP tools (import,
+ *   list, add, remove, search). Write-path tools are gated behind
+ *   deps.contactsEnabled; read/remove/search are always registered.
+ *
+ * ### Invite generator
+ * - `generateInviteMessage` — LLM-based invite message generator for ghost
+ *   users; produces short, contextual messages referencing the opportunity.
+ *
+ * IND-549: canonical application layer for the contacts capability.
+ * Legacy paths:
+ *   - contact/contact.tools.ts → thin compatibility shim pointing here
+ *   - contact/contact.inviter.ts → thin compatibility shim pointing here
+ */
+export { createContactTools } from "./contact.tools.js";
+export { generateInviteMessage } from "./contact.inviter.js";
+export type { InviteInput, InviteOutput } from "./contact.inviter.js";

package/dist/contacts/application/index.js

@@ -0,0 +1,21 @@
+/**
+ * contacts/application — foreground adapters and application services.
+ *
+ * ## Exports
+ *
+ * ### Tool factory
+ * - `createContactTools` — creates contact management MCP tools (import,
+ *   list, add, remove, search). Write-path tools are gated behind
+ *   deps.contactsEnabled; read/remove/search are always registered.
+ *
+ * ### Invite generator
+ * - `generateInviteMessage` — LLM-based invite message generator for ghost
+ *   users; produces short, contextual messages referencing the opportunity.
+ *
+ * IND-549: canonical application layer for the contacts capability.
+ * Legacy paths:
+ *   - contact/contact.tools.ts → thin compatibility shim pointing here
+ *   - contact/contact.inviter.ts → thin compatibility shim pointing here
+ */
+export { createContactTools } from "./contact.tools.js";
+export { generateInviteMessage } from "./contact.inviter.js";