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

package/dist/runtime/foreground/composition/tool.registry.js

@@ -14,17 +14,9 @@ import { createQuestionerTools } from '../../../capabilities/questions.facade.js
 import { protocolLogger } from '../../../shared/observability/protocol.logger.js';
 import { requestContext } from '../../../shared/observability/request-context.js';
 const logger = protocolLogger('ToolRegistry');
-/**
- * Creates a tool registry containing all tool handlers indexed by name.
- * Handlers are raw async functions (not LangChain tool() wrappers) that
- * accept { context, query } and return a JSON string.
- *
- * @param deps - Shared tool dependencies (graphs, database, embedder, etc.)
- * @param context - Resolved user context for this request.
- * @returns Map of tool name to raw tool definition.
- */
-export function createToolRegistry(deps) {
+export function createToolRegistry(deps, options = {}) {
     const registry = new Map();
+    const isMcpSurface = options.surface === 'mcp';
     // defineTool that captures raw handlers into the registry
     function defineTool(opts) {
         const entry = {
@@ -65,9 +57,17 @@ export function createToolRegistry(deps) {
     createIntentTools(dt, deps);
     createNetworkTools(dt, deps);
     createOpportunityTools(dt, deps);
-    createUtilityTools(dt, deps);
-    createIntegrationTools(dt, deps);
-    createContactTools(dt, deps);
+    // Utility tools always register read_docs + read_activity_summary; on the
+    // MCP surface scrape_url is omitted and read_docs guidance is sanitized
+    // (IND-597). The retired report_agent_activity name retains no alias on
+    // either surface (IND-605).
+    createUtilityTools(dt, deps, { surface: isMcpSurface ? 'mcp' : 'rest' });
+    // Contact/Gmail import tools are omitted from the MCP surface (IND-596). Their
+    // implementations remain available to the REST Tool API and chat agent.
+    if (!isMcpSurface) {
+        createIntegrationTools(dt, deps);
+        createContactTools(dt, deps);
+    }
     createAgentTools(dt, deps);
     createNegotiationTools(dt, deps);
     createPremiseTools(dt, deps);
@@ -75,32 +75,35 @@ export function createToolRegistry(deps) {
     if (deps.chatSession) {
         createChatTools(dt, deps);
     }
-    // Deprecated tool-name aliases (IND-371). The canonical implementations are now
-    // registered under their *_user_context / *_enrichment_run names; we expose the
-    // legacy *_user_profile / *_profile_run names as thin aliases that delegate to the
-    // exact same handler + schema, so existing MCP clients keep working while they
-    // migrate. The old names are removed in IND-373.
-    const DEPRECATED_TOOL_ALIASES = [
-        ["read_user_profiles", "read_user_contexts"],
-        ["create_user_profile", "create_user_context"],
-        ["update_user_profile", "update_user_context"],
-        ["confirm_user_profile", "confirm_user_context"],
-        ["preview_user_profile", "preview_user_context"],
-        ["get_profile_run", "get_enrichment_run"],
-        ["cancel_profile_run", "cancel_enrichment_run"],
-    ];
-    for (const [oldName, canonicalName] of DEPRECATED_TOOL_ALIASES) {
-        const canonical = registry.get(canonicalName);
-        if (!canonical) {
-            logger.warn('Cannot register deprecated alias: canonical tool not found', { alias: oldName, canonicalName });
-            continue;
+    // Deprecated tool-name aliases (IND-371). The canonical implementations are
+    // registered under their *_user_context / *_enrichment_run names; the legacy
+    // *_user_profile / *_profile_run names are retained as thin aliases that
+    // delegate to the exact same handler + schema so existing direct HTTP Tool
+    // API clients keep working. These aliases are NOT exposed on the MCP surface
+    // (IND-598) — MCP callers must use the canonical names.
+    if (!isMcpSurface) {
+        const DEPRECATED_TOOL_ALIASES = [
+            ["read_user_profiles", "read_user_contexts"],
+            ["create_user_profile", "create_user_context"],
+            ["update_user_profile", "update_user_context"],
+            ["confirm_user_profile", "confirm_user_context"],
+            ["preview_user_profile", "preview_user_context"],
+            ["get_profile_run", "get_enrichment_run"],
+            ["cancel_profile_run", "cancel_enrichment_run"],
+        ];
+        for (const [oldName, canonicalName] of DEPRECATED_TOOL_ALIASES) {
+            const canonical = registry.get(canonicalName);
+            if (!canonical) {
+                logger.warn('Cannot register deprecated alias: canonical tool not found', { alias: oldName, canonicalName });
+                continue;
+            }
+            registry.set(oldName, {
+                ...canonical,
+                name: oldName,
+                description: `[DEPRECATED — use \`${canonicalName}\` instead; this alias is retained for backward compatibility and will be removed.] ${canonical.description}`,
+            });
         }
-        registry.set(oldName, {
-            ...canonical,
-            name: oldName,
-            description: `[DEPRECATED — use \`${canonicalName}\` instead; this alias is retained for backward compatibility and will be removed.] ${canonical.description}`,
-        });
     }
-    logger.verbose('Tool registry created', { toolCount: registry.size });
+    logger.verbose('Tool registry created', { toolCount: registry.size, surface: options.surface ?? 'rest' });
     return registry;
 }

package/dist/shared/agent/activity-projection.d.ts

@@ -0,0 +1,271 @@
+import { z } from "zod";
+import type { AgentActivitySummary } from "../interfaces/database.interface.js";
+/**
+ * Centralized activity-summary permission projection (IND-605).
+ *
+ * `read_activity_summary` is the only public name for grounded, aggregate-only
+ * agent activity reporting. The handler passes a typed resolved caller context
+ * into this one projection:
+ *
+ * - Human owners (REST/chat surfaces and session-authenticated MCP callers)
+ *   receive every domain.
+ * - Registered agents receive only the domains their permissions authorize.
+ *   Signal IDs/titles (`opportunitiesBySignal`) require `manage:intents`.
+ * - Question counts are meta-network: they are never narrowed by a network
+ *   binding, but each count inherits the permission of the domain the
+ *   question AFFECTS. A caller sees a domain's question counts only when it
+ *   holds that domain's permission; conversational (`chat`-mode) and
+ *   unrecognized modes are human-owner-only. There is deliberately no
+ *   any-of all-question count shortcut.
+ * - Network agents additionally narrow network-bound aggregates to their bound
+ *   community — exposed here as `activitySummaryNetworkId` so the narrowing
+ *   happens in the query/adapter layer, never as transport-local JSON
+ *   filtering.
+ *
+ * The projection can only drop fields. It never fabricates data and it never
+ * exposes counterparty identities, chats, turns, transcripts, or private
+ * content; the strict response schema below is the explicit output contract.
+ */
+/** Canonical public tool name for aggregate activity reporting. */
+export declare const READ_ACTIVITY_SUMMARY_TOOL_NAME = "read_activity_summary";
+/** Activity summary domains, in stable projection order. */
+export declare const ActivitySummaryDomainSchema: z.ZodEnum<["signals", "opportunities", "questions", "negotiations"]>;
+export type ActivitySummaryDomain = z.infer<typeof ActivitySummaryDomainSchema>;
+/**
+ * Domains a question can affect. `'chat'` covers conversational questions
+ * (and, fail-closed, any mode added to the protocol enum later): they have no
+ * agent-permission domain and are visible to human owners only.
+ */
+export declare const ActivityQuestionDomainSchema: z.ZodEnum<["identity", "premises", "intents", "opportunities", "negotiations", "chat"]>;
+export type ActivityQuestionDomain = z.infer<typeof ActivityQuestionDomainSchema>;
+/**
+ * Maps every current `QuestionMode` to the domain the question affects.
+ * Modes missing from this table fail closed to the human-only `'chat'`
+ * bucket so a future protocol mode can never leak to an agent caller.
+ */
+export declare const QUESTION_MODE_TO_DOMAIN: Readonly<Record<string, ActivityQuestionDomain>>;
+/**
+ * Explicit per-domain question counts. Each key is present only when the
+ * caller is authorized for that domain and the count is non-zero.
+ */
+export declare const ActivityQuestionCountsSchema: z.ZodObject<{
+    identity: z.ZodOptional<z.ZodNumber>;
+    premises: z.ZodOptional<z.ZodNumber>;
+    intents: z.ZodOptional<z.ZodNumber>;
+    opportunities: z.ZodOptional<z.ZodNumber>;
+    negotiations: z.ZodOptional<z.ZodNumber>;
+    /** Human-owner-only conversational (or unrecognized) question counts. */
+    chat: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    chat?: number | undefined;
+    identity?: number | undefined;
+    intents?: number | undefined;
+    premises?: number | undefined;
+    opportunities?: number | undefined;
+    negotiations?: number | undefined;
+}, {
+    chat?: number | undefined;
+    identity?: number | undefined;
+    intents?: number | undefined;
+    premises?: number | undefined;
+    opportunities?: number | undefined;
+    negotiations?: number | undefined;
+}>;
+export type ActivityQuestionCounts = z.infer<typeof ActivityQuestionCountsSchema>;
+/**
+ * Typed resolved MCP caller context consumed by the projection. Derived from
+ * the MCP capability subject at the transport boundary (see
+ * `resolveMcpActivityCaller` in mcp.authorization-policy.ts); absent on
+ * REST/chat surfaces, which are owner-trusted.
+ */
+export declare const McpActivityCallerSchema: z.ZodObject<{
+    /** `'human'` callers own the summarized data and see every domain. */
+    kind: z.ZodEnum<["human", "agent"]>;
+    /** Canonical `manage:*` permission actions granted to the caller. */
+    permissions: z.ZodArray<z.ZodString, "many">;
+    /** A network agent's bound community; always null for humans. */
+    networkScopeId: z.ZodNullable<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    kind: "human" | "agent";
+    permissions: string[];
+    networkScopeId: string | null;
+}, {
+    kind: "human" | "agent";
+    permissions: string[];
+    networkScopeId: string | null;
+}>;
+export type McpActivityCaller = z.infer<typeof McpActivityCallerSchema>;
+/**
+ * Canonical affected-domain permission an agent must hold to read or answer a
+ * question of the given mode. Returns `null` for human-owner-only questions
+ * (`chat`, and any unrecognized mode, which fail closed to the human-only
+ * bucket) — no agent permission can release those.
+ *
+ * This is the single shared mode → affected-domain → permission mapping, reusing
+ * `QUESTION_MODE_TO_DOMAIN` and `QUESTION_DOMAIN_PERMISSIONS` so question
+ * read/answer inheritance is identical to the `read_activity_summary`
+ * projection. It keys on `mode` only: the canonical question model does not vary
+ * a question's owning domain by `purpose` (purpose refines generation and
+ * provenance, not the affected domain), so purpose is intentionally not a
+ * discriminant here rather than being guessed at.
+ */
+export declare function questionModeRequiredPermission(mode: string): string | null;
+/**
+ * Whether an MCP caller may read or answer a question of the given mode. Human
+ * (owner) callers see every mode; agents are confined to modes backed by one of
+ * their exact affected-domain permissions. A network agent's binding is applied
+ * separately by the caller (network/intent clamp); this is purely the
+ * affected-domain permission gate.
+ */
+export declare function callerMayAccessQuestionMode(caller: McpActivityCaller, mode: string): boolean;
+/**
+ * Explicit response contract for `read_activity_summary`. Every domain field
+ * is optional because agent callers receive only their authorized domains.
+ * Strict: no counterparty or unspecified field can pass validation.
+ */
+export declare const ActivitySummaryResponseSchema: z.ZodObject<{
+    /** The reporting window actually used, in hours. */
+    sinceHours: z.ZodNumber;
+    /** signals domain — liveSignalsWatched and per-signal opportunity counts. */
+    liveSignalsWatched: z.ZodOptional<z.ZodNumber>;
+    /** opportunities domain. */
+    opportunitiesSurfaced: z.ZodOptional<z.ZodNumber>;
+    /** signals domain — signal IDs/titles, authorized by manage:intents only. */
+    opportunitiesBySignal: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        intentId: z.ZodString;
+        title: z.ZodString;
+        count: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        title: string;
+        intentId: string;
+        count: number;
+    }, {
+        title: string;
+        intentId: string;
+        count: number;
+    }>, "many">>;
+    /** questions domain (meta-network) — counts grouped by affected domain. */
+    pendingQuestionsByDomain: z.ZodOptional<z.ZodObject<{
+        identity: z.ZodOptional<z.ZodNumber>;
+        premises: z.ZodOptional<z.ZodNumber>;
+        intents: z.ZodOptional<z.ZodNumber>;
+        opportunities: z.ZodOptional<z.ZodNumber>;
+        negotiations: z.ZodOptional<z.ZodNumber>;
+        /** Human-owner-only conversational (or unrecognized) question counts. */
+        chat: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        chat?: number | undefined;
+        identity?: number | undefined;
+        intents?: number | undefined;
+        premises?: number | undefined;
+        opportunities?: number | undefined;
+        negotiations?: number | undefined;
+    }, {
+        chat?: number | undefined;
+        identity?: number | undefined;
+        intents?: number | undefined;
+        premises?: number | undefined;
+        opportunities?: number | undefined;
+        negotiations?: number | undefined;
+    }>>;
+    answeredQuestionsByDomain: z.ZodOptional<z.ZodObject<{
+        identity: z.ZodOptional<z.ZodNumber>;
+        premises: z.ZodOptional<z.ZodNumber>;
+        intents: z.ZodOptional<z.ZodNumber>;
+        opportunities: z.ZodOptional<z.ZodNumber>;
+        negotiations: z.ZodOptional<z.ZodNumber>;
+        /** Human-owner-only conversational (or unrecognized) question counts. */
+        chat: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        chat?: number | undefined;
+        identity?: number | undefined;
+        intents?: number | undefined;
+        premises?: number | undefined;
+        opportunities?: number | undefined;
+        negotiations?: number | undefined;
+    }, {
+        chat?: number | undefined;
+        identity?: number | undefined;
+        intents?: number | undefined;
+        premises?: number | undefined;
+        opportunities?: number | undefined;
+        negotiations?: number | undefined;
+    }>>;
+    /** negotiations domain. */
+    negotiationsStarted: z.ZodOptional<z.ZodNumber>;
+    negotiationsCompleted: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    sinceHours: number;
+    liveSignalsWatched?: number | undefined;
+    opportunitiesSurfaced?: number | undefined;
+    opportunitiesBySignal?: {
+        title: string;
+        intentId: string;
+        count: number;
+    }[] | undefined;
+    pendingQuestionsByDomain?: {
+        chat?: number | undefined;
+        identity?: number | undefined;
+        intents?: number | undefined;
+        premises?: number | undefined;
+        opportunities?: number | undefined;
+        negotiations?: number | undefined;
+    } | undefined;
+    answeredQuestionsByDomain?: {
+        chat?: number | undefined;
+        identity?: number | undefined;
+        intents?: number | undefined;
+        premises?: number | undefined;
+        opportunities?: number | undefined;
+        negotiations?: number | undefined;
+    } | undefined;
+    negotiationsStarted?: number | undefined;
+    negotiationsCompleted?: number | undefined;
+}, {
+    sinceHours: number;
+    liveSignalsWatched?: number | undefined;
+    opportunitiesSurfaced?: number | undefined;
+    opportunitiesBySignal?: {
+        title: string;
+        intentId: string;
+        count: number;
+    }[] | undefined;
+    pendingQuestionsByDomain?: {
+        chat?: number | undefined;
+        identity?: number | undefined;
+        intents?: number | undefined;
+        premises?: number | undefined;
+        opportunities?: number | undefined;
+        negotiations?: number | undefined;
+    } | undefined;
+    answeredQuestionsByDomain?: {
+        chat?: number | undefined;
+        identity?: number | undefined;
+        intents?: number | undefined;
+        premises?: number | undefined;
+        opportunities?: number | undefined;
+        negotiations?: number | undefined;
+    } | undefined;
+    negotiationsStarted?: number | undefined;
+    negotiationsCompleted?: number | undefined;
+}>;
+export type ProjectedActivitySummary = z.infer<typeof ActivitySummaryResponseSchema>;
+/**
+ * Resolves the summary domains a caller may see. Human owners receive every
+ * domain; agents receive only domains backed by one of their permissions.
+ * The `questions` domain only flags that at least one affected-domain count
+ * may be visible — each count is still filtered per affected domain in
+ * `projectActivitySummary`.
+ */
+export declare function resolveActivitySummaryDomains(caller: McpActivityCaller): ActivitySummaryDomain[];
+/**
+ * Returns the bound community a network agent's network-bound aggregates must
+ * be narrowed to in the query/adapter layer. Undefined for human callers and
+ * global agents, whose aggregates span the owner's networks.
+ */
+export declare function activitySummaryNetworkId(caller: McpActivityCaller): string | undefined;
+/**
+ * Projects a full owner-scoped summary down to the caller's authorized
+ * domains. Pure field selection — no data is transformed or fabricated.
+ */
+export declare function projectActivitySummary(caller: McpActivityCaller, summary: AgentActivitySummary): ProjectedActivitySummary;

package/dist/shared/agent/activity-projection.js

@@ -0,0 +1,248 @@
+import { z } from "zod";
+/**
+ * Centralized activity-summary permission projection (IND-605).
+ *
+ * `read_activity_summary` is the only public name for grounded, aggregate-only
+ * agent activity reporting. The handler passes a typed resolved caller context
+ * into this one projection:
+ *
+ * - Human owners (REST/chat surfaces and session-authenticated MCP callers)
+ *   receive every domain.
+ * - Registered agents receive only the domains their permissions authorize.
+ *   Signal IDs/titles (`opportunitiesBySignal`) require `manage:intents`.
+ * - Question counts are meta-network: they are never narrowed by a network
+ *   binding, but each count inherits the permission of the domain the
+ *   question AFFECTS. A caller sees a domain's question counts only when it
+ *   holds that domain's permission; conversational (`chat`-mode) and
+ *   unrecognized modes are human-owner-only. There is deliberately no
+ *   any-of all-question count shortcut.
+ * - Network agents additionally narrow network-bound aggregates to their bound
+ *   community — exposed here as `activitySummaryNetworkId` so the narrowing
+ *   happens in the query/adapter layer, never as transport-local JSON
+ *   filtering.
+ *
+ * The projection can only drop fields. It never fabricates data and it never
+ * exposes counterparty identities, chats, turns, transcripts, or private
+ * content; the strict response schema below is the explicit output contract.
+ */
+/** Canonical public tool name for aggregate activity reporting. */
+export const READ_ACTIVITY_SUMMARY_TOOL_NAME = "read_activity_summary";
+/** Activity summary domains, in stable projection order. */
+export const ActivitySummaryDomainSchema = z.enum([
+    "signals",
+    "opportunities",
+    "questions",
+    "negotiations",
+]);
+/**
+ * Domains a question can affect. `'chat'` covers conversational questions
+ * (and, fail-closed, any mode added to the protocol enum later): they have no
+ * agent-permission domain and are visible to human owners only.
+ */
+export const ActivityQuestionDomainSchema = z.enum([
+    "identity",
+    "premises",
+    "intents",
+    "opportunities",
+    "negotiations",
+    "chat",
+]);
+/**
+ * Maps every current `QuestionMode` to the domain the question affects.
+ * Modes missing from this table fail closed to the human-only `'chat'`
+ * bucket so a future protocol mode can never leak to an agent caller.
+ */
+export const QUESTION_MODE_TO_DOMAIN = {
+    // Enrichment answers run the PremiseGraph lifecycle (createPremiseFromAnswer →
+    // PremiseEvents.onCreated), so enrichment questions affect the premises domain.
+    enrichment: "premises",
+    intent: "intents",
+    discovery: "opportunities",
+    pool_discovery: "opportunities",
+    negotiation: "negotiations",
+    negotiation_inflight: "negotiations",
+    chat: "chat",
+};
+/**
+ * Explicit per-domain question counts. Each key is present only when the
+ * caller is authorized for that domain and the count is non-zero.
+ */
+export const ActivityQuestionCountsSchema = z.object({
+    identity: z.number().int().optional(),
+    premises: z.number().int().optional(),
+    intents: z.number().int().optional(),
+    opportunities: z.number().int().optional(),
+    negotiations: z.number().int().optional(),
+    /** Human-owner-only conversational (or unrecognized) question counts. */
+    chat: z.number().int().optional(),
+}).strict();
+/**
+ * Typed resolved MCP caller context consumed by the projection. Derived from
+ * the MCP capability subject at the transport boundary (see
+ * `resolveMcpActivityCaller` in mcp.authorization-policy.ts); absent on
+ * REST/chat surfaces, which are owner-trusted.
+ */
+export const McpActivityCallerSchema = z.object({
+    /** `'human'` callers own the summarized data and see every domain. */
+    kind: z.enum(["human", "agent"]),
+    /** Canonical `manage:*` permission actions granted to the caller. */
+    permissions: z.array(z.string()),
+    /** A network agent's bound community; always null for humans. */
+    networkScopeId: z.string().min(1).nullable(),
+}).strict();
+/** Summary domain → authorizing permission action for agent callers. */
+const DOMAIN_PERMISSIONS = {
+    signals: "manage:intents",
+    opportunities: "manage:opportunities",
+    negotiations: "manage:negotiations",
+};
+/**
+ * Affected question domain → authorizing permission action. `'chat'` is
+ * deliberately absent: conversational counts are human-owner-only and no
+ * agent permission releases them.
+ */
+const QUESTION_DOMAIN_PERMISSIONS = {
+    identity: "manage:identity",
+    premises: "manage:premises",
+    intents: "manage:intents",
+    opportunities: "manage:opportunities",
+    negotiations: "manage:negotiations",
+};
+/**
+ * Canonical affected-domain permission an agent must hold to read or answer a
+ * question of the given mode. Returns `null` for human-owner-only questions
+ * (`chat`, and any unrecognized mode, which fail closed to the human-only
+ * bucket) — no agent permission can release those.
+ *
+ * This is the single shared mode → affected-domain → permission mapping, reusing
+ * `QUESTION_MODE_TO_DOMAIN` and `QUESTION_DOMAIN_PERMISSIONS` so question
+ * read/answer inheritance is identical to the `read_activity_summary`
+ * projection. It keys on `mode` only: the canonical question model does not vary
+ * a question's owning domain by `purpose` (purpose refines generation and
+ * provenance, not the affected domain), so purpose is intentionally not a
+ * discriminant here rather than being guessed at.
+ */
+export function questionModeRequiredPermission(mode) {
+    const domain = QUESTION_MODE_TO_DOMAIN[mode] ?? "chat";
+    return QUESTION_DOMAIN_PERMISSIONS[domain] ?? null;
+}
+/**
+ * Whether an MCP caller may read or answer a question of the given mode. Human
+ * (owner) callers see every mode; agents are confined to modes backed by one of
+ * their exact affected-domain permissions. A network agent's binding is applied
+ * separately by the caller (network/intent clamp); this is purely the
+ * affected-domain permission gate.
+ */
+export function callerMayAccessQuestionMode(caller, mode) {
+    if (caller.kind === "human")
+        return true;
+    const required = questionModeRequiredPermission(mode);
+    return required !== null && caller.permissions.includes(required);
+}
+/**
+ * Explicit response contract for `read_activity_summary`. Every domain field
+ * is optional because agent callers receive only their authorized domains.
+ * Strict: no counterparty or unspecified field can pass validation.
+ */
+export const ActivitySummaryResponseSchema = z.object({
+    /** The reporting window actually used, in hours. */
+    sinceHours: z.number().int(),
+    /** signals domain — liveSignalsWatched and per-signal opportunity counts. */
+    liveSignalsWatched: z.number().int().optional(),
+    /** opportunities domain. */
+    opportunitiesSurfaced: z.number().int().optional(),
+    /** signals domain — signal IDs/titles, authorized by manage:intents only. */
+    opportunitiesBySignal: z.array(z.object({
+        intentId: z.string(),
+        title: z.string(),
+        count: z.number().int(),
+    }).strict()).optional(),
+    /** questions domain (meta-network) — counts grouped by affected domain. */
+    pendingQuestionsByDomain: ActivityQuestionCountsSchema.optional(),
+    answeredQuestionsByDomain: ActivityQuestionCountsSchema.optional(),
+    /** negotiations domain. */
+    negotiationsStarted: z.number().int().optional(),
+    negotiationsCompleted: z.number().int().optional(),
+}).strict();
+/**
+ * Resolves the summary domains a caller may see. Human owners receive every
+ * domain; agents receive only domains backed by one of their permissions.
+ * The `questions` domain only flags that at least one affected-domain count
+ * may be visible — each count is still filtered per affected domain in
+ * `projectActivitySummary`.
+ */
+export function resolveActivitySummaryDomains(caller) {
+    if (caller.kind === "human") {
+        return ["signals", "opportunities", "questions", "negotiations"];
+    }
+    const granted = new Set(caller.permissions);
+    const domains = [];
+    if (granted.has(DOMAIN_PERMISSIONS.signals))
+        domains.push("signals");
+    if (granted.has(DOMAIN_PERMISSIONS.opportunities))
+        domains.push("opportunities");
+    if (Object.values(QUESTION_DOMAIN_PERMISSIONS).some((action) => granted.has(action))) {
+        domains.push("questions");
+    }
+    if (granted.has(DOMAIN_PERMISSIONS.negotiations))
+        domains.push("negotiations");
+    return domains;
+}
+/**
+ * Returns the bound community a network agent's network-bound aggregates must
+ * be narrowed to in the query/adapter layer. Undefined for human callers and
+ * global agents, whose aggregates span the owner's networks.
+ */
+export function activitySummaryNetworkId(caller) {
+    if (caller.kind !== "agent")
+        return undefined;
+    return caller.networkScopeId ?? undefined;
+}
+/**
+ * Aggregates raw per-mode question counts into per-affected-domain counts,
+ * releasing only the domains the caller is authorized for. Meta-network:
+ * domain permissions are the only boundary — never a network filter.
+ */
+function projectQuestionCounts(caller, byMode) {
+    const granted = new Set(caller.permissions);
+    const counts = {};
+    for (const [mode, count] of Object.entries(byMode)) {
+        // Unrecognized modes fail closed to the human-only bucket.
+        const domain = QUESTION_MODE_TO_DOMAIN[mode] ?? "chat";
+        if (caller.kind === "agent") {
+            const permission = QUESTION_DOMAIN_PERMISSIONS[domain];
+            if (!permission || !granted.has(permission))
+                continue;
+        }
+        counts[domain] = (counts[domain] ?? 0) + count;
+    }
+    return Object.keys(counts).length > 0 ? counts : undefined;
+}
+/**
+ * Projects a full owner-scoped summary down to the caller's authorized
+ * domains. Pure field selection — no data is transformed or fabricated.
+ */
+export function projectActivitySummary(caller, summary) {
+    const domains = new Set(resolveActivitySummaryDomains(caller));
+    const projected = { sinceHours: summary.sinceHours };
+    if (domains.has("signals")) {
+        projected.liveSignalsWatched = summary.liveSignalsWatched;
+        projected.opportunitiesBySignal = summary.opportunitiesBySignal;
+    }
+    if (domains.has("opportunities")) {
+        projected.opportunitiesSurfaced = summary.opportunitiesSurfaced;
+    }
+    if (domains.has("questions")) {
+        const pending = projectQuestionCounts(caller, summary.pendingQuestionsByMode);
+        if (pending)
+            projected.pendingQuestionsByDomain = pending;
+        const answered = projectQuestionCounts(caller, summary.answeredQuestionsByMode);
+        if (answered)
+            projected.answeredQuestionsByDomain = answered;
+    }
+    if (domains.has("negotiations")) {
+        projected.negotiationsStarted = summary.negotiationsStarted;
+        projected.negotiationsCompleted = summary.negotiationsCompleted;
+    }
+    return projected;
+}

package/dist/shared/agent/canonical-guidance.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Canonical guidance for Index Network protocol operations.
+ *
+ * This is the single normative source for:
+ * - Entity model and identity/context definitions
+ * - Premise, signal, community, network, and opportunity concepts
+ * - Negotiation semantics (owner approval vs A2A acceptance)
+ * - H2A and A2A collaboration (H2H is never exposed)
+ * - Retired vocabulary (no contact/Gmail/scrape/profile/ghost-user guidance)
+ *
+ * Wired into:
+ * - MCP_INSTRUCTIONS (packages/protocol/src/mcp/mcp.server.ts)
+ * - read_docs tool (packages/protocol/src/shared/agent/utility.tools.ts)
+ *
+ * IND-602, IND-603
+ */
+export declare const CANONICAL_GUIDANCE_TOPICS: readonly ["identity-context", "premises", "signals", "communities-networks", "opportunities", "negotiations", "workflows"];
+export type CanonicalGuidanceTopic = (typeof CANONICAL_GUIDANCE_TOPICS)[number];
+/**
+ * Summary of canonical entity model and protocol semantics.
+ * Used in MCP_INSTRUCTIONS and as read_docs summary across all surfaces.
+ * Never mentions retired contact/Gmail/scrape/profile/ghost-user guidance.
+ * Optimized to ~1900 chars to leave room for MCP_INSTRUCTIONS context budget.
+ */
+export declare const CANONICAL_GUIDANCE_SUMMARY = "# Index Network Protocol\n\nIndex Network is a private, intent-driven discovery protocol. Users express signals (intents), agents find matches within shared networks, and decisions proceed through clear gates.\n\n## Core Concepts\n\n**Identity & Context** \u2014 User profile (name, bio, skills, interests, location) and current scope (networks, intents, stage).\n\n**Premises** \u2014 Foundational facts: background, experience, stage, timeline, constraints.\n\n**Signals** \u2014 What users seek (intents, opportunities). Drive semantic matching.\n\n**Communities & Networks** \u2014 Private groups where members share signals and discover connections via shared membership.\n\n**Opportunities** \u2014 Discovered matches between users. Lifecycle: draft \u2192 pending \u2192 accepted/rejected/expired.\n\n**Negotiations** \u2014 Agents coordinate, users approve. **A2A acceptance is not owner approval.** These are separate gates.\n\n**Workflows** \u2014 H2A (users express signals \u2192 agents discover) and A2A (agents coordinate) over MCP. Further escalation via native surfaces (human-to-human threads do not cross MCP).\n\n## Canonical Topics\n\nRefer to these for detailed entity facts and lifecycle:\n\n- **identity-context** \u2014 Profile structure, context scoping\n- **premises** \u2014 Background, stage, constraints\n- **signals** \u2014 Intent inference, classification\n- **communities-networks** \u2014 Membership, auto-assign\n- **opportunities** \u2014 Discovery, roles, reasoning\n- **negotiations** \u2014 Owner approval vs A2A, acceptance gates\n- **workflows** \u2014 H2A and A2A tool sequences";
+/**
+ * Detailed canonical topic content for read_docs.
+ * Indexed by topic name; each contains current entity, capability, and lifecycle facts.
+ */
+export declare const CANONICAL_GUIDANCE_TOPICS_CONTENT: Record<CanonicalGuidanceTopic, string>;