@indexnetwork/protocol 6.15.0-rc.407.1 → 8.0.2-rc.418.1

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

@@ -1,9 +1,20 @@
 import { z } from "zod";
 import { requestContext } from "../observability/request-context.js";
+import { ActivitySummaryResponseSchema, McpActivityCallerSchema, activitySummaryNetworkId, projectActivitySummary } from "./activity-projection.js";
+import { CANONICAL_GUIDANCE_SUMMARY, CANONICAL_GUIDANCE_TOPICS, CANONICAL_GUIDANCE_TOPICS_CONTENT } from "./canonical-guidance.js";
 import { success, error, normalizeUrl } from "./tool.helpers.js";
-export function createUtilityTools(defineTool, deps) {
+/** Owner-trusted surfaces (REST/chat) receive the full owner view. */
+const HUMAN_OWNER_CALLER = {
+    kind: "human",
+    permissions: [],
+    networkScopeId: null,
+};
+export function createUtilityTools(defineTool, deps, options = {}) {
     const { scraper } = deps;
-    const scrapeUrl = defineTool({
+    const isMcpSurface = options.surface === "mcp";
+    // scrape_url is omitted from the MCP tool surface (IND-597). It remains
+    // available via the direct HTTP Tool API and the chat agent.
+    const scrapeUrl = isMcpSurface ? null : defineTool({
         name: "scrape_url",
         description: "Extracts text content from a web URL — articles, LinkedIn/GitHub profiles, documentation, project pages, etc. " +
             "Returns the page's text content (up to 10,000 characters) for use in subsequent tool calls.\n\n" +
@@ -44,20 +55,65 @@ export function createUtilityTools(defineTool, deps) {
         name: "read_docs",
         description: "Returns comprehensive documentation about the Index Network protocol — entity model, workflows, tool usage guidance, and domain concepts. " +
             "This is the primary way for an external agent to bootstrap understanding of the system.\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" +
-            "Also call when you need to understand:\n" +
-            "- What entities exist and how they relate (intents, indexes, opportunities, profiles, contacts)\n" +
-            "- The discovery workflow (how intents become opportunities)\n" +
-            "- Which tools to call in what order for common tasks\n" +
-            "- Authentication and API patterns\n\n" +
-            "**Returns:** Markdown documentation. Pass `topic` to get a specific section, or omit for the full reference.\n\n" +
-            "**Available topics:** 'entities', 'intents', 'opportunities', 'indexes', 'profiles', 'contacts', 'discovery', 'workflows', 'authentication', 'mcp_agent_guide'",
+            "**When to use:** Call this FIRST when starting a new session.\n" +
+            "Also call when you need to understand identity, context, premises, signals, communities, networks, opportunities, or negotiations.\n\n" +
+            "**Returns:** Markdown documentation. Pass `topic` to get a specific section, or omit for the summary.\n\n" +
+            `**Available canonical topics:** ${CANONICAL_GUIDANCE_TOPICS.join(", ")}`,
         querySchema: z.object({
-            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."),
+            topic: z.string().optional().describe(`Narrow to a canonical topic: ${CANONICAL_GUIDANCE_TOPICS.join(", ")}. Omit to get the summary.`),
         }),
         handler: async ({ context: _context, query }) => {
             const topic = query.topic?.trim().toLowerCase();
+            // Canonical guidance is the MCP read_docs foundation. When on MCP surface,
+            // legacy supplemental topics (entities, intents, opportunities, etc.) are
+            // omitted to avoid repeating the canonical source (IND-602/603).
+            // REST/chat surfaces retain full topic coverage for backwards compatibility.
+            if (isMcpSurface) {
+                // MCP surface: use canonical guidance only.
+                if (!topic) {
+                    // Return summary of canonical guidance
+                    return success({ content: CANONICAL_GUIDANCE_SUMMARY });
+                }
+                // Try to match canonical topic
+                const normalizedTopic = topic.replace(/_/g, "-").toLowerCase();
+                for (const canonicalTopic of CANONICAL_GUIDANCE_TOPICS) {
+                    if (canonicalTopic === normalizedTopic || normalizedTopic.includes(canonicalTopic.split("-")[0])) {
+                        return success({ topic: canonicalTopic, content: CANONICAL_GUIDANCE_TOPICS_CONTENT[canonicalTopic] });
+                    }
+                }
+                // Unknown topic on MCP surface
+                return success({
+                    content: `Unknown canonical topic "${topic}". Available topics: ${CANONICAL_GUIDANCE_TOPICS.join(", ")}. Request summary for full canonical guidance.`,
+                });
+            }
+            // REST/chat surfaces: provide full legacy documentation alongside canonical.
+            // Contact management tools are not exposed on the MCP surface (IND-596), so
+            // full guidance includes contact workflows. This is for REST/chat only.
+            const contactsSection = `## Contact Management
+
+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 network scope**: Approved signals from personal-network contacts are matched in the background. Use list_opportunities only to review persisted results.
+- **Contact data**: Each contact has userId, name, email, avatar, and isGhost flag.
+
+### Contact Workflow
+1. import_contacts or import_gmail_contacts → bulk add to network
+2. list_contacts → view all contacts with userId
+3. create_intent or update_intent → create or refine an approved signal for background matching
+4. list_opportunities → review persisted results when background processing finds matches
+5. add_contact(email) → add individual contact
+6. remove_contact(contactUserId) → remove from network`;
+            const managingContactsWorkflow = `### Managing Contacts
+1. import_gmail_contacts() or import_contacts([...]) → add contacts
+2. list_contacts() → view network
+3. create_intent or update_intent → create or refine an approved signal for background matching
+4. list_opportunities → review persisted results
+
+`;
             const sections = {
+                // Legacy topics (REST/chat only)
                 entities: `## Entity Model & Relationships
 
 - **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.
@@ -98,7 +154,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 networks. Uses HyDE embeddings for retrieval and an LLM evaluator for scoring.
+1. **Background matching**: The opportunity graph evaluates approved signals whose intents semantically complement each other within shared networks. It 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)
@@ -108,16 +164,15 @@ Opportunities represent discovered connections between users — potential match
    - **accepted**: Both parties agreed to connect.
    - **rejected**: One party declined.
    - **expired**: Timed out without response.
-4. **Creation Modes**:
-   - **Discovery**: Automatic — system finds matches based on intent overlap (discover_opportunities with searchQuery)
-   - **Introduction**: Manual — a user introduces two specific people (discover_opportunities with partyUserIds + entities)
-   - **Direct**: One-to-one — connect with a specific person (discover_opportunities with targetUserId)
+4. **Creation**: Opportunities are created by background matching after approved signals are created or refined. list_opportunities only reviews persisted cards; it never starts matching or targets a person.
 5. **Presentation**: Each opportunity includes personalized match reasoning, confidence score, and suggested next action.
 
 ### Opportunity Workflow
-1. discover_opportunities(searchQuery="AI engineers") → returns draft opportunity cards
-2. update_opportunity(opportunityId, status="pending") → sends to other party
-3. Other party sees opportunity → calls update_opportunity(status="accepted" or "rejected")`,
+1. create_intent(description) or update_intent(intentId, description) → create or refine an approved signal
+2. background matching → persists opportunity cards when matches are found
+3. list_opportunities() → review persisted cards
+4. update_opportunity(opportunityId, status="pending") → sends to other party
+5. Other party sees opportunity → calls update_opportunity(status="accepted" or "rejected")`,
                 indexes: `## Index Mechanics
 
 Indexes (also called "networks") are communities where members share what they're looking for and the system discovers connections between them.
@@ -133,7 +188,7 @@ Indexes (also called "networks") are communities where members share what they'r
 1. create_network(title, prompt) → creates new community, you become owner
 2. create_network_membership(networkId, userId) → invite members
 3. Members create intents → auto-assigned to the index based on prompt
-4. discover_opportunities(networkId) → discover matches within this community`,
+4. Members' approved signals are matched in the background; list_opportunities only reviews persisted results`,
                 profiles: `## Profile System
 
 Profiles are the user's identity on the platform, used for semantic matching in opportunity discovery.
@@ -152,33 +207,19 @@ Profiles are the user's identity on the platform, used for semantic matching in
 - Richer profiles produce better opportunity matches
 - Social links enable enrichment — encourage users to add LinkedIn/GitHub
 - 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 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 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
-1. import_contacts or import_gmail_contacts → bulk add to network
-2. list_contacts → view all contacts with userId
-3. discover_opportunities(networkId=personalIndexId) → find matches among contacts
-4. add_contact(email) → add individual contact
-5. remove_contact(contactUserId) → remove from network`,
+                contacts: contactsSection,
                 discovery: `## Discovery Mechanics
 
 Discovery is the process of finding meaningful connections between users based on their intents and profiles.
 
 ### How Discovery Works
-1. **Trigger**: Runs automatically when an intent is created, or explicitly when discover_opportunities is called.
+1. **Trigger**: Runs automatically when an approved signal is created or refined.
 2. **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.
 3. **Semantic matching**: Uses HyDE (Hypothetical Document Embeddings) to find candidate intents that complement the source. This goes beyond keyword matching — it understands conceptual relationships.
 4. **Evaluation**: An LLM evaluator agent scores each candidate match on relevance, complementarity, and actionability. Low-scoring matches are filtered out.
 5. **Results**: Persisted as draft opportunities with roles, reasoning, and confidence scores.
 6. **Background processing**: After intent creation, a queue job continues looking for matches asynchronously.
-7. **Pagination**: Large result sets are paginated. Use continueFrom with the discoveryId to evaluate more candidates.
+7. **Review**: Use list_opportunities to review persisted actionable cards; it does not run matching.
 
 ### Discovery Best Practices
 - More specific intents produce more relevant matches
@@ -193,29 +234,25 @@ Discovery is the process of finding meaningful connections between users based o
 3. read_networks() → see available communities
 4. create_network_membership(networkId) → join a community
 5. create_intent(description) → post what you're looking for
-6. discover_opportunities(searchQuery) → find matches
+6. Background matching evaluates the approved signal; list_opportunities reviews persisted results
 
 ### Finding Connections
 1. read_networks() → list user's communities (get networkId)
-2. discover_opportunities(searchQuery, networkId) → discover matches
-3. Review opportunity cards → update_opportunity(opportunityId, status="pending") to send
+2. create_intent(description) or update_intent(intentId, description) → create or refine an approved signal in the relevant network
+3. Background matching persists eligible cards; list_opportunities reviews them
+4. update_opportunity(opportunityId, status="pending") → send a persisted card
 
-### Making an Introduction
-1. read_network_memberships(networkId) → find members in shared community
-2. read_user_contexts(userId) → get profiles of both parties
-3. read_intents(networkId, userId) → get intents of both parties
-4. discover_opportunities(partyUserIds=[id1,id2], entities=[...], hint="reason") → create introduction
+### Helping Connections Emerge
+1. read_network_memberships(networkId) → understand the shared community
+2. create_intent(description) or update_intent(intentId, description) → capture or refine an approved signal
+3. Background matching evaluates approved signals
+4. list_opportunities() → review persisted results
 
-### Managing Contacts
-1. import_gmail_contacts() or import_contacts([...]) → add contacts
-2. list_contacts() → view network
-3. discover_opportunities(networkId=personalIndexId) → find matches among contacts
-
-### Creating a Community
+${managingContactsWorkflow}### Creating a Community
 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`,
+4. Members' approved signals are matched in the background; list_opportunities only reviews persisted results`,
                 authentication: `## Authentication & API Access
 
 ### For External AI Agents (MCP)
@@ -235,57 +272,56 @@ Discovery is the process of finding meaningful connections between users based o
 - Avoid unnecessary read_intents/read_networks calls — cache results within a conversation
 - Use pagination (limit/page) for large result sets
 - Call read_docs once at the start to understand the domain`,
-                mcp_agent_guide: `## MCP Agent Integration Guide
-
-**IMPORTANT: Read this section if you are an AI agent accessing Index Network via MCP tools.**
-
-### Output Formatting
-- 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.
-- 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.
-- When presenting opportunities or intents, use bullet points or short paragraphs — not raw JSON objects.
-
-### Intent Creation Workflow
-- **Always pass \`autoApprove: true\` when calling \`create_intent\`.** This persists intents directly without returning proposal cards that require manual UI approval.
-- The tool will return a list of created intents with their descriptions and confidence scores. Present these in natural language.
-- Do not tell the user to "click on cards" or "approve above" — there is no UI. Intents are created immediately with autoApprove.
-- After creating intents, proactively suggest or run discovery to find matches.
-
-### Discovery Workflow
-- After creating intents, proactively suggest running discovery: \`discover_opportunities(searchQuery=...)\`
-- Present discovered opportunities in natural language with the counterpart's name, match reasoning, and suggested next steps.
-- Do not reference "cards", "panels", or any web UI elements.
-
-### General MCP Agent Rules
-- You are operating via API tools, not a web interface. Never reference clicking, scrolling, cards, panels, or any visual UI elements.
-- Be proactive: if a logical next step exists (e.g., running discovery after creating intents), suggest or execute it.
-- Use \`list_opportunities\` to check existing matches, \`list_negotiations\` for ongoing negotiations.
-- Use \`read_networks\` to understand which communities the user belongs to before scoping operations.
-- When errors occur, provide clear technical context rather than vague "backend issue" messages.`,
+                // Canonical topics (on REST/chat for completeness)
+                "identity-context": CANONICAL_GUIDANCE_TOPICS_CONTENT["identity-context"],
+                premises: CANONICAL_GUIDANCE_TOPICS_CONTENT.premises,
+                signals: CANONICAL_GUIDANCE_TOPICS_CONTENT.signals,
+                "communities-networks": CANONICAL_GUIDANCE_TOPICS_CONTENT["communities-networks"],
+                negotiations: CANONICAL_GUIDANCE_TOPICS_CONTENT.negotiations,
             };
             if (topic) {
-                const matched = Object.entries(sections).find(([key]) => key.includes(topic) || topic.includes(key));
+                const normalizedTopic = topic.replace(/_/g, "-").toLowerCase();
+                const matched = Object.entries(sections).find(([key]) => key === normalizedTopic || key.includes(normalizedTopic) || normalizedTopic.includes(key));
                 if (matched) {
                     return success({ topic: matched[0], content: matched[1] });
                 }
-                // If topic not found, return all
             }
-            const fullDoc = Object.values(sections).join("\n\n");
+            // Return full documentation (summary + all topics)
+            const fullDoc = [CANONICAL_GUIDANCE_SUMMARY, ...Object.values(sections)].join("\n\n");
             return success({ content: fullDoc });
         },
     });
-    const reportAgentActivity = defineTool({
-        name: "report_agent_activity",
-        description: "Reports grounded, aggregate-only activity for the authenticated user's agent over a recent time window. " +
-            "It includes live signal count, opportunities surfaced by the user's own signals, pending/answered question counts, " +
-            "and negotiation totals. It never returns counterpart identities, transcripts, or per-counterparty rows.",
+    const readActivitySummary = defineTool({
+        name: "read_activity_summary",
+        description: "Returns grounded, aggregate-only activity for the authenticated user's agent over a recent time window.\n\n" +
+            "**Response domains (permission-projected for agent callers):**\n" +
+            "- signals (`liveSignalsWatched`, `opportunitiesBySignal` with signal IDs/titles) — requires manage:intents.\n" +
+            "- opportunities (`opportunitiesSurfaced`) — requires manage:opportunities.\n" +
+            "- questions (`pendingQuestionsByDomain`, `answeredQuestionsByDomain`) — meta-network counts grouped by the question's affected domain; " +
+            "each domain's counts require that domain's manage:identity/premises/intents/opportunities/negotiations permission; conversational chat-mode counts are human-owner-only.\n" +
+            "- negotiations (`negotiationsStarted`, `negotiationsCompleted`) — requires manage:negotiations.\n" +
+            "Human owners receive every domain. Agent callers receive only the domains their permissions authorize; " +
+            "a network agent's network-bound aggregates are narrowed to its bound community at the query layer.\n\n" +
+            "**Privacy:** the response never returns counterparty identities, chats, turns, transcripts, per-counterparty rows, " +
+            "or any private content — only aggregate counts and (with manage:intents) the owner's own signal IDs/titles.",
         querySchema: z.object({
             sinceHours: z.number().int().optional().default(24).describe("Look back this many hours; values are clamped to 1-168 (default 24)."),
         }).strict(),
-        handler: async ({ query }) => {
+        handler: async ({ context, query }) => {
             const sinceHours = Math.max(1, Math.min(168, query.sinceHours));
-            const summary = await deps.userDb.getAgentActivitySummary({ sinceHours });
-            return success(summary);
+            // Absent on owner-trusted REST/chat surfaces → full owner view. On MCP the
+            // server binds the typed resolved caller context and the centralized
+            // projection decides every visible domain.
+            const caller = context.mcpCaller
+                ? McpActivityCallerSchema.parse(context.mcpCaller)
+                : HUMAN_OWNER_CALLER;
+            const networkId = activitySummaryNetworkId(caller);
+            const summary = await deps.userDb.getAgentActivitySummary({
+                sinceHours,
+                ...(networkId ? { networkId } : {}),
+            });
+            return success(ActivitySummaryResponseSchema.parse(projectActivitySummary(caller, summary)));
         },
     });
-    return [scrapeUrl, readDocs, reportAgentActivity];
+    return [scrapeUrl, readDocs, readActivitySummary].filter((tool) => tool !== null);
 }

package/dist/shared/interfaces/auth.interface.d.ts

@@ -1,4 +1,4 @@
-import type { McpAuthInput } from '../schemas/mcp-auth.schema.js';
+import type { McpAuthInput, McpResolvedIdentity } from '../schemas/mcp-auth.schema.js';
 /**
  * Resolves the authenticated MCP identity from an auth input DTO.
  * The DTO is extracted from the transport at the edge (e.g. from HTTP Request
@@ -29,13 +29,7 @@ export interface McpAuthResolver {
      *
      * @throws Error if authentication fails (no token, invalid token, etc.)
      */
-    resolveIdentity(input: McpAuthInput): Promise<{
-        userId: string;
-        agentId?: string;
-        isSessionAuth?: boolean;
-        networkScopeId?: string | null;
-        clientSurface?: 'telegram' | 'web';
-    }>;
+    resolveIdentity(input: McpAuthInput): Promise<McpResolvedIdentity>;
     /**
      * Deprecated HTTP Request bridge retained for compatibility with older
      * callers. New transport code must extract `McpAuthInput` at the edge and

package/dist/shared/interfaces/chat-session.interface.js

@@ -9,5 +9,10 @@
 //     there is nothing to return.
 //   • `limit` / `messageLimit`, when provided, cap the most-recent N rows; when
 //     omitted the adapter applies its own sane default.
+//   • Category contract (IND-600): `listSessions` / `getSession` expose ONLY H2A
+//     conversations (orchestrator-persona sessions with the system agent as a
+//     participant). H2H DMs are never exposed through this port, and A2A
+//     negotiation conversations are reachable only through the negotiation
+//     tools; non-H2A session IDs behave exactly like nonexistent ones.
 // ═══════════════════════════════════════════════════════════════════════════════
 export {};

package/dist/shared/interfaces/database.interface.d.ts

@@ -1599,10 +1599,10 @@ export interface AgentActivitySummary {
         title: string;
         count: number;
     }>;
-    /** Current, non-expired questions waiting for the user. */
-    pendingQuestionCount: number;
-    /** Questions answered by the user during the window. */
-    questionsAnswered: number;
+    /** Current, non-expired questions waiting for the user, grouped by affected mode (QuestionMode values). Meta-network. */
+    pendingQuestionsByMode: Record<string, number>;
+    /** Questions answered by the user during the window, grouped by affected mode (QuestionMode values). Meta-network. */
+    answeredQuestionsByMode: Record<string, number>;
     /** Distinct opportunity negotiations started during the window. */
     negotiationsStarted: number;
     /** Distinct opportunity negotiations completed during the window. */
@@ -1729,9 +1729,16 @@ export interface UserDatabase {
         success: boolean;
         alreadyMember?: boolean;
     }>;
-    /** Summarize the authenticated user's own agent activity without counterparty rows. */
+    /**
+     * Summarize the authenticated user's own agent activity without counterparty rows.
+     * When `networkId` is present (a network agent's bound community), the
+     * network-bound aggregates (opportunity and negotiation counts) are narrowed
+     * to that community inside the query; own-signal and question aggregates are
+     * meta-network and stay global.
+     */
     getAgentActivitySummary(input: {
         sinceHours: number;
+        networkId?: string;
     }): Promise<AgentActivitySummary>;
     /** Get opportunities where the authenticated user is an actor. */
     getOpportunitiesForUser(options?: OpportunityQueryOptions): Promise<Opportunity[]>;

package/dist/shared/observability/request-context.d.ts

@@ -1,18 +1,8 @@
-import type { Opportunity } from "../interfaces/database.interface.js";
 import { AsyncLocalStorage } from "async_hooks";
 /**
- * Callback for streaming trace / domain events from deep inside graph nodes
- * back to the caller (typically chat.agent's stream pipeline).
- *
- * Carries two flavors of event:
- * - Trace events (`graph_start | graph_end | agent_start | agent_end`) — used
- *   by the chat TRACE panel to visualize what the agent is doing.
- * - Domain events (`opportunity_draft_ready`) — emitted by the orchestrator
- *   branch of OpportunityGraph.negotiateNode so the frontend can render each
- *   accepted draft card progressively as its negotiation resolves.
- *
- * Kept as a single emitter rather than splitting into two to minimize plumbing
- * through AsyncLocalStorage; the chat.agent relay branches on event.type.
+ * Callback for streaming trace events from deep inside graph nodes back to
+ * the caller (typically chat.agent's stream pipeline). Kept as a single emitter
+ * to minimize AsyncLocalStorage plumbing.
  */
 export type TraceEmitter = (event: {
     type: "graph_start" | "graph_end" | "agent_start" | "agent_end";
@@ -27,37 +17,11 @@ export type TraceEmitter = (event: {
 } | {
     type: "status";
     message: string;
-} | {
-    type: "opportunity_draft_ready";
-    opportunityId: string;
-    opportunity: Opportunity;
-    /** Viewer-centric summary derived from interpretation.reasoning. */
-    personalizedSummary?: string;
-    /**
-     * Minimal counterparty data for rendering the inline card without a
-     * second-round-trip user lookup. Populated from the negotiation
-     * candidate's profile; avatar is intentionally omitted (the card
-     * falls back to initials) since UserNegotiationContext doesn't
-     * carry avatars.
-     */
-    counterparty: {
-        userId: string;
-        name?: string;
-    };
 }) => void;
 interface RequestContext {
     originUrl?: string;
     traceEmitter?: TraceEmitter;
-    /**
-     * Signal for cooperative cancellation — propagates the caller's AbortSignal
-     * into long-running graph nodes (e.g. orchestrator negotiation fan-out) so
-     * they can stop emitting events when the chat session closes.
-     *
-     * The orchestrator branch checks this before persisting status flips or
-     * pushing `opportunity_draft_ready` events. In-flight negotiations are not
-     * forcibly cancelled — they finish or time out naturally via their park
-     * window — but their results are suppressed once the signal trips.
-     */
+    /** Signal for cooperative cancellation in long-running graph nodes. */
     abortSignal?: AbortSignal;
 }
 /**

package/dist/shared/schemas/mcp-auth.schema.d.ts

@@ -1,17 +1,89 @@
+import { z } from 'zod';
 /**
- * McpAuthInput — plain DTO extracted from the MCP HTTP request at the transport
- * edge before the protocol auth resolver is called. Keeps the shared auth
- * interface free of platform-specific `Request` coupling.
+ * Transport-neutral auth input extracted at the HTTP boundary.
  */
-export interface McpAuthInput {
-    /** Authorization Bearer token (JWT or opaque session token). */
-    bearerToken?: string;
-    /** API key for agent/API-key authentication. */
-    apiKey?: string;
-    /** Client surface hint for UI branching (telegram vs web). */
-    clientSurface?: 'telegram' | 'web';
-    /** Telegram handle for identity verification (extracted from request headers). */
-    telegramHandle?: string;
-    /** Telegram username for identity verification (extracted from request headers). */
-    telegramUsername?: string;
-}
+export declare const McpAuthInputSchema: z.ZodObject<{
+    bearerToken: z.ZodOptional<z.ZodString>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    clientSurface: z.ZodOptional<z.ZodEnum<["telegram", "web"]>>;
+    telegramHandle: z.ZodOptional<z.ZodString>;
+    telegramUsername: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    apiKey?: string | undefined;
+    clientSurface?: "telegram" | "web" | undefined;
+    bearerToken?: string | undefined;
+    telegramHandle?: string | undefined;
+    telegramUsername?: string | undefined;
+}, {
+    apiKey?: string | undefined;
+    clientSurface?: "telegram" | "web" | undefined;
+    bearerToken?: string | undefined;
+    telegramHandle?: string | undefined;
+    telegramUsername?: string | undefined;
+}>;
+export type McpAuthInput = z.infer<typeof McpAuthInputSchema>;
+/**
+ * Trusted API-key metadata used by the host auth composition.
+ *
+ * Enrollment and delivery flags are explicit opt-ins. Unknown metadata is
+ * ignored so unrelated Better Auth metadata remains forward-compatible.
+ */
+export declare const McpApiKeyMetadataSchema: z.ZodObject<{
+    agentId: z.ZodOptional<z.ZodString>;
+    enrollmentCapable: z.ZodOptional<z.ZodBoolean>;
+    isDeliveryAgent: z.ZodOptional<z.ZodBoolean>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    agentId: z.ZodOptional<z.ZodString>;
+    enrollmentCapable: z.ZodOptional<z.ZodBoolean>;
+    isDeliveryAgent: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    agentId: z.ZodOptional<z.ZodString>;
+    enrollmentCapable: z.ZodOptional<z.ZodBoolean>;
+    isDeliveryAgent: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">>;
+export type McpApiKeyMetadata = z.infer<typeof McpApiKeyMetadataSchema>;
+/**
+ * Protocol-owned result boundary for host authentication.
+ */
+export declare const McpResolvedIdentitySchema: z.ZodEffects<z.ZodObject<{
+    userId: z.ZodString;
+    agentId: z.ZodOptional<z.ZodString>;
+    isSessionAuth: z.ZodOptional<z.ZodBoolean>;
+    enrollmentCapable: z.ZodOptional<z.ZodBoolean>;
+    isDeliveryAgent: z.ZodOptional<z.ZodBoolean>;
+    networkScopeId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    clientSurface: z.ZodOptional<z.ZodEnum<["telegram", "web"]>>;
+}, "strict", z.ZodTypeAny, {
+    userId: string;
+    agentId?: string | undefined;
+    clientSurface?: "telegram" | "web" | undefined;
+    networkScopeId?: string | null | undefined;
+    enrollmentCapable?: boolean | undefined;
+    isDeliveryAgent?: boolean | undefined;
+    isSessionAuth?: boolean | undefined;
+}, {
+    userId: string;
+    agentId?: string | undefined;
+    clientSurface?: "telegram" | "web" | undefined;
+    networkScopeId?: string | null | undefined;
+    enrollmentCapable?: boolean | undefined;
+    isDeliveryAgent?: boolean | undefined;
+    isSessionAuth?: boolean | undefined;
+}>, {
+    userId: string;
+    agentId?: string | undefined;
+    clientSurface?: "telegram" | "web" | undefined;
+    networkScopeId?: string | null | undefined;
+    enrollmentCapable?: boolean | undefined;
+    isDeliveryAgent?: boolean | undefined;
+    isSessionAuth?: boolean | undefined;
+}, {
+    userId: string;
+    agentId?: string | undefined;
+    clientSurface?: "telegram" | "web" | undefined;
+    networkScopeId?: string | null | undefined;
+    enrollmentCapable?: boolean | undefined;
+    isDeliveryAgent?: boolean | undefined;
+    isSessionAuth?: boolean | undefined;
+}>;
+export type McpResolvedIdentity = z.infer<typeof McpResolvedIdentitySchema>;

package/dist/shared/schemas/mcp-auth.schema.js

@@ -1 +1,49 @@
-export {};
+import { z } from 'zod';
+/**
+ * Transport-neutral auth input extracted at the HTTP boundary.
+ */
+export const McpAuthInputSchema = z.object({
+    bearerToken: z.string().min(1).optional(),
+    apiKey: z.string().min(1).optional(),
+    clientSurface: z.enum(['telegram', 'web']).optional(),
+    telegramHandle: z.string().min(1).optional(),
+    telegramUsername: z.string().min(1).optional(),
+}).strict();
+/**
+ * Trusted API-key metadata used by the host auth composition.
+ *
+ * Enrollment and delivery flags are explicit opt-ins. Unknown metadata is
+ * ignored so unrelated Better Auth metadata remains forward-compatible.
+ */
+export const McpApiKeyMetadataSchema = z.object({
+    agentId: z.string().min(1).optional(),
+    enrollmentCapable: z.boolean().optional(),
+    isDeliveryAgent: z.boolean().optional(),
+}).passthrough();
+/**
+ * Protocol-owned result boundary for host authentication.
+ */
+export const McpResolvedIdentitySchema = z.object({
+    userId: z.string().min(1),
+    agentId: z.string().min(1).optional(),
+    isSessionAuth: z.boolean().optional(),
+    enrollmentCapable: z.boolean().optional(),
+    isDeliveryAgent: z.boolean().optional(),
+    networkScopeId: z.string().min(1).nullable().optional(),
+    clientSurface: z.enum(['telegram', 'web']).optional(),
+}).strict().superRefine((identity, ctx) => {
+    if (identity.isSessionAuth === true && identity.agentId) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['agentId'],
+            message: 'Session-authenticated identities cannot carry an agent ID.',
+        });
+    }
+    if (identity.isDeliveryAgent === true && !identity.agentId) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['isDeliveryAgent'],
+            message: 'Delivery-agent designation requires an agent ID.',
+        });
+    }
+});