@indexnetwork/protocol 22.0.0-rc.499.1 → 64.0.0

package/dist/mcp/mcp.authorization-policy.js

@@ -1,535 +0,0 @@
-import { z } from 'zod';
-import { McpActivityCallerSchema } from '../shared/agent/activity-projection.js';
-/** Canonical MCP permission actions. */
-export const MCP_PERMISSION_ACTIONS = [
-    'manage:identity',
-    'manage:premises',
-    'manage:intents',
-    'manage:networks',
-    'manage:opportunities',
-    'manage:negotiations',
-];
-export const McpPermissionActionSchema = z.enum(MCP_PERMISSION_ACTIONS);
-export const McpToolPermissionRequirementSchema = z.object({
-    action: McpPermissionActionSchema,
-    /**
-     * Capability reach only. Entity ownership, membership, approval, and exact
-     * scope checks remain in the capability handler.
-     */
-    reach: z.enum(['principal', 'network']).default('principal'),
-}).strict();
-const McpToolPermissionMapSchema = z.record(z.string().min(1), McpToolPermissionRequirementSchema);
-/**
- * Runtime-validates a capability-owned tool-to-permission mapping.
- */
-export function defineMcpToolPermissionMap(mapping) {
-    const parsed = McpToolPermissionMapSchema.parse(mapping);
-    return new Map(Object.entries(parsed));
-}
-/**
- * Exact full-standalone Hermes MCP surface. Every admitted tool maps to one
- * canonical action; absence is denial, including human-only, deletion,
- * permission-management, agent-administration, and retired aliases.
- */
-export const HERMES_AGENT_MCP_TOOL_PERMISSIONS = defineMcpToolPermissionMap({
-    read_user_contexts: { action: 'manage:identity', reach: 'principal' },
-    preview_user_context: { action: 'manage:identity', reach: 'principal' },
-    confirm_user_context: { action: 'manage:identity', reach: 'principal' },
-    create_user_context: { action: 'manage:identity', reach: 'principal' },
-    update_user_context: { action: 'manage:identity', reach: 'principal' },
-    get_enrichment_run: { action: 'manage:identity', reach: 'principal' },
-    cancel_enrichment_run: { action: 'manage:identity', reach: 'principal' },
-    read_intents: { action: 'manage:intents', reach: 'network' },
-    search_intents: { action: 'manage:intents', reach: 'network' },
-    create_intent: { action: 'manage:intents', reach: 'network' },
-    update_intent: { action: 'manage:intents', reach: 'network' },
-    read_intent_indexes: { action: 'manage:intents', reach: 'network' },
-    create_intent_index: { action: 'manage:intents', reach: 'network' },
-    list_negotiations: { action: 'manage:negotiations', reach: 'network' },
-    get_negotiation: { action: 'manage:negotiations', reach: 'network' },
-    respond_to_negotiation: { action: 'manage:negotiations', reach: 'network' },
-    read_networks: { action: 'manage:networks', reach: 'network' },
-    read_network_memberships: { action: 'manage:networks', reach: 'network' },
-    create_network: { action: 'manage:networks', reach: 'network' },
-    update_network: { action: 'manage:networks', reach: 'network' },
-    create_network_membership: { action: 'manage:networks', reach: 'network' },
-    list_opportunities: { action: 'manage:opportunities', reach: 'network' },
-    update_opportunity: { action: 'manage:opportunities', reach: 'network' },
-    confirm_opportunity_delivery: { action: 'manage:opportunities', reach: 'network' },
-    read_premises: { action: 'manage:premises', reach: 'principal' },
-    create_premise: { action: 'manage:premises', reach: 'principal' },
-    update_premise: { action: 'manage:premises', reach: 'principal' },
-    retract_premise: { action: 'manage:premises', reach: 'principal' },
-    read_activity_summary: { action: 'manage:identity', reach: 'principal' },
-    read_docs: { action: 'manage:identity', reach: 'principal' },
-});
-export const McpToolAccessRuleSchema = z.object({
-    access: z.enum([
-        'permission',
-        'authenticated',
-        'human_only',
-        'agent_admin',
-        'informational',
-        'delivery_only',
-        'removed',
-    ]),
-    actions: z.array(McpPermissionActionSchema).optional(),
-    reach: z.enum(['principal', 'network']),
-}).strict().superRefine((rule, ctx) => {
-    if (rule.access === 'permission' && (!rule.actions || rule.actions.length === 0)) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ['actions'],
-            message: 'Permission rules require at least one action.',
-        });
-    }
-    if (rule.access !== 'permission' && rule.actions !== undefined) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ['actions'],
-            message: 'Only permission rules may declare actions.',
-        });
-    }
-});
-const McpToolAccessRuleMapSchema = z.record(z.string().min(1), McpToolAccessRuleSchema);
-/** Runtime-validates a complete static MCP tool access matrix. */
-export function defineMcpToolAccessRules(rules) {
-    const parsed = McpToolAccessRuleMapSchema.parse(rules);
-    return new Map(Object.entries(parsed));
-}
-/**
- * Canonical MCP tool authorization matrix.
- *
- * Every tool registered by `createToolRegistry` is classified. Tool handlers
- * retain domain ownership, membership, exact-scope, and approval checks.
- */
-export const CANONICAL_MCP_TOOL_ACCESS_RULES = defineMcpToolAccessRules({
-    // Participant identity/context.
-    read_user_contexts: { access: 'permission', actions: ['manage:identity'], reach: 'principal' },
-    preview_user_context: { access: 'permission', actions: ['manage:identity'], reach: 'principal' },
-    confirm_user_context: { access: 'permission', actions: ['manage:identity'], reach: 'principal' },
-    create_user_context: { access: 'permission', actions: ['manage:identity'], reach: 'principal' },
-    update_user_context: { access: 'permission', actions: ['manage:identity'], reach: 'principal' },
-    get_enrichment_run: { access: 'permission', actions: ['manage:identity'], reach: 'principal' },
-    cancel_enrichment_run: { access: 'permission', actions: ['manage:identity'], reach: 'principal' },
-    // Premises are meta-network; a network-scoped agent retains principal reach.
-    read_premises: { access: 'permission', actions: ['manage:premises'], reach: 'principal' },
-    create_premise: { access: 'permission', actions: ['manage:premises'], reach: 'principal' },
-    update_premise: { access: 'permission', actions: ['manage:premises'], reach: 'principal' },
-    retract_premise: { access: 'permission', actions: ['manage:premises'], reach: 'principal' },
-    // Signals.
-    read_intents: { access: 'authenticated', reach: 'network' },
-    search_intents: { access: 'authenticated', reach: 'network' },
-    create_intent: { access: 'permission', actions: ['manage:intents'], reach: 'network' },
-    update_intent: { access: 'permission', actions: ['manage:intents'], reach: 'network' },
-    delete_intent: { access: 'permission', actions: ['manage:intents'], reach: 'network' },
-    read_intent_indexes: { access: 'authenticated', reach: 'network' },
-    create_intent_index: { access: 'permission', actions: ['manage:intents'], reach: 'network' },
-    delete_intent_index: { access: 'permission', actions: ['manage:intents'], reach: 'network' },
-    // Communities.
-    read_networks: { access: 'authenticated', reach: 'network' },
-    read_network_memberships: { access: 'authenticated', reach: 'network' },
-    create_network: { access: 'permission', actions: ['manage:networks'], reach: 'network' },
-    update_network: { access: 'permission', actions: ['manage:networks'], reach: 'network' },
-    delete_network: { access: 'human_only', reach: 'network' },
-    create_network_membership: { access: 'permission', actions: ['manage:networks'], reach: 'network' },
-    delete_network_membership: { access: 'permission', actions: ['manage:networks'], reach: 'network' },
-    // Opportunities and delivery.
-    list_opportunities: { access: 'authenticated', reach: 'network' },
-    update_opportunity: { access: 'permission', actions: ['manage:opportunities'], reach: 'network' },
-    confirm_opportunity_delivery: { access: 'delivery_only', reach: 'network' },
-    // A2A negotiations.
-    list_negotiations: { access: 'permission', actions: ['manage:negotiations'], reach: 'network' },
-    get_negotiation: { access: 'permission', actions: ['manage:negotiations'], reach: 'network' },
-    respond_to_negotiation: { access: 'permission', actions: ['manage:negotiations'], reach: 'network' },
-    // H2A chat history.
-    list_conversations: { access: 'human_only', reach: 'principal' },
-    get_conversation: { access: 'human_only', reach: 'principal' },
-    // Agent administration.
-    read_own_agent: { access: 'agent_admin', reach: 'principal' },
-    register_agent: { access: 'agent_admin', reach: 'principal' },
-    list_agents: { access: 'agent_admin', reach: 'principal' },
-    update_agent: { access: 'agent_admin', reach: 'principal' },
-    delete_agent: { access: 'agent_admin', reach: 'principal' },
-    grant_agent_permission: { access: 'agent_admin', reach: 'principal' },
-    revoke_agent_permission: { access: 'agent_admin', reach: 'principal' },
-    // Protocol guidance.
-    read_docs: { access: 'informational', reach: 'principal' },
-    // Aggregate activity reporting. Any activity-domain permission admits the
-    // call; the handler then projects each domain by the caller's exact grants
-    // via the centralized activity projection, and a network agent's
-    // network-bound aggregates are narrowed to its bound community at the
-    // query/adapter layer.
-    read_activity_summary: {
-        access: 'permission',
-        actions: [
-            'manage:identity',
-            'manage:premises',
-            'manage:intents',
-            'manage:opportunities',
-            'manage:negotiations',
-        ],
-        reach: 'principal',
-    },
-    // Restricted MCP surface still registered by the shared registry. The contact
-    // and Gmail-import tools, scrape_url, the deprecated profile/profile-run
-    // aliases, and the retired report_agent_activity name are no longer
-    // classified here because they are omitted from the MCP registry composition
-    // entirely (IND-596/597/598/605) — an unregistered tool is rejected as
-    // unknown before any authorization work. read_activity_summary (above) is
-    // the only public activity-reporting name; no legacy alias is retained.
-});
-/** Tools visible on the REST Tool API while web/CLI onboarding is incomplete. MCP does not use this allowlist. */
-export const ONBOARDING_ALLOWED = new Set([
-    'register_agent',
-    'read_docs',
-    'preview_user_context',
-    'get_enrichment_run',
-    'cancel_enrichment_run',
-    'confirm_user_context',
-    'create_user_context',
-    'read_user_contexts',
-    'complete_onboarding',
-    'read_networks',
-    'create_network_membership',
-    'create_intent',
-]);
-/** Agent administration inventory. */
-export const MCP_AGENT_ADMIN_TOOLS = new Set([
-    'read_own_agent',
-    'register_agent',
-    'list_agents',
-    'update_agent',
-    'delete_agent',
-    'grant_agent_permission',
-    'revoke_agent_permission',
-]);
-/** Informational inventory retained as a convenience export. */
-export const MCP_INFORMATIONAL_TOOLS = new Set([
-    'read_docs',
-]);
-const McpPolicyAgentPermissionSchema = z.object({
-    agentId: z.string().min(1),
-    userId: z.string().min(1),
-    scope: z.enum(['global', 'node', 'network']),
-    scopeId: z.string().min(1).nullable(),
-    actions: z.array(z.string()),
-}).strict();
-export const McpPolicyAgentSnapshotSchema = z.object({
-    id: z.string().min(1),
-    ownerId: z.string().min(1),
-    type: z.enum(['personal', 'external', 'system']),
-    status: z.enum(['active', 'inactive']),
-    permissions: z.array(McpPolicyAgentPermissionSchema),
-}).strict();
-export const McpPrincipalProfileSchema = z.enum([
-    'session_human',
-    'enrollment_key',
-    'unregistered_key',
-    'registered_global_agent',
-    'registered_network_agent',
-    'hermes_agent',
-    'delivery_agent',
-    'invalid_agent',
-]);
-export const McpCapabilitySubjectSchema = z.object({
-    profile: McpPrincipalProfileSchema,
-    userId: z.string().min(1),
-    agentId: z.string().min(1).optional(),
-    agentType: z.enum(['personal', 'external', 'system']).optional(),
-    networkScopeId: z.string().min(1).nullable(),
-    permissions: z.array(McpPermissionActionSchema),
-}).strict();
-/**
- * Retired durable grant actions and the canonical capabilities each projects to
- * at the permission-loading boundary. TEMPORARY rolling-data compatibility
- * (IND-607): while a mixed-version fleet is live, old replicas (current `dev`)
- * still WRITE `manage:profile` / `manage:contacts` rows AFTER the pre-deploy
- * `0109` migration runs, and un-migrated rows may also remain. The new runtime
- * must therefore interpret these residual STORED rows so no agent loses access
- * during the rolling window and none is over-authorized:
- *
- *   - `manage:profile`  -> `manage:identity` + `manage:premises`
- *   - `manage:contacts` -> (no capability)
- *
- * This is NOT a public alias: the legacy names are never accepted as INPUT
- * (grant validation and tool schemas are canonical-only) and never surfaced in
- * documentation or `tools/list`. They are tolerated ONLY as pre-existing stored
- * data, and only until the post-drain final sweep sets `retired_remaining = 0`
- * and the compatibility-removal gate is met (see the IND-609 rollout doc).
- */
-const LEGACY_STORED_ACTION_PROJECTION = {
-    'manage:profile': ['manage:identity', 'manage:premises'],
-    'manage:contacts': [],
-};
-/**
- * Central capability-loading interpretation of a stored permission row's raw
- * actions. Canonical actions pass through; retired actions project per
- * {@link LEGACY_STORED_ACTION_PROJECTION}; every unknown action fails closed
- * (ignored). Owner/scope matching is applied by the caller BEFORE this runs, so
- * this function never widens the scope a grant applies to.
- */
-export function projectStoredPermissionActions(actions) {
-    const granted = new Set();
-    for (const action of actions) {
-        const projected = LEGACY_STORED_ACTION_PROJECTION[action];
-        if (projected !== undefined) {
-            for (const capability of projected)
-                granted.add(capability);
-            continue;
-        }
-        const parsed = McpPermissionActionSchema.safeParse(action);
-        if (parsed.success)
-            granted.add(parsed.data);
-        // Unknown actions are ignored — fail closed.
-    }
-    return [...granted];
-}
-function resolveAgentPermissions(identity, agent) {
-    const granted = new Set();
-    for (const permission of agent.permissions) {
-        if (permission.agentId !== identity.agentId || permission.userId !== identity.userId)
-            continue;
-        const scopeApplies = permission.scope === 'global' ||
-            (permission.scope === 'network' &&
-                identity.networkScopeId !== null &&
-                identity.networkScopeId !== undefined &&
-                permission.scopeId === identity.networkScopeId);
-        if (!scopeApplies)
-            continue;
-        // Canonical-only going forward, plus temporary interpretation of residual
-        // legacy stored rows during the mixed-version rolling window.
-        for (const action of projectStoredPermissionActions(permission.actions)) {
-            granted.add(action);
-        }
-    }
-    return [...granted];
-}
-/**
- * Resolves a request-local, runtime-validated principal profile.
- */
-export function resolveMcpCapabilitySubject(input) {
-    const { identity } = input;
-    if (identity.isSessionAuth === true) {
-        return McpCapabilitySubjectSchema.parse({
-            profile: 'session_human',
-            userId: identity.userId,
-            networkScopeId: null,
-            permissions: [],
-        });
-    }
-    if (!identity.agentId) {
-        return McpCapabilitySubjectSchema.parse({
-            profile: identity.enrollmentCapable === true ? 'enrollment_key' : 'unregistered_key',
-            userId: identity.userId,
-            networkScopeId: null,
-            permissions: [],
-        });
-    }
-    const parsedAgent = McpPolicyAgentSnapshotSchema.safeParse(input.agent);
-    if (!parsedAgent.success ||
-        parsedAgent.data.id !== identity.agentId ||
-        parsedAgent.data.ownerId !== identity.userId ||
-        parsedAgent.data.status !== 'active') {
-        return McpCapabilitySubjectSchema.parse({
-            profile: 'invalid_agent',
-            userId: identity.userId,
-            agentId: identity.agentId,
-            networkScopeId: identity.networkScopeId ?? null,
-            permissions: [],
-        });
-    }
-    const agent = parsedAgent.data;
-    const profile = identity.isHermesAgent === true
-        ? 'hermes_agent'
-        : identity.isDeliveryAgent === true
-            ? 'delivery_agent'
-            : identity.networkScopeId
-                ? 'registered_network_agent'
-                : 'registered_global_agent';
-    return McpCapabilitySubjectSchema.parse({
-        profile,
-        userId: identity.userId,
-        agentId: identity.agentId,
-        agentType: agent.type,
-        networkScopeId: identity.networkScopeId ?? null,
-        permissions: resolveAgentPermissions(identity, agent),
-    });
-}
-/**
- * Maps a resolved capability subject to the typed caller context consumed by
- * the centralized activity-summary projection. Session humans own the
- * summarized data and receive the full owner view; every other profile is
- * projected as an agent bounded by its granted permissions and (for network
- * agents) its bound community.
- */
-export function resolveMcpActivityCaller(subject) {
-    const isHuman = subject.profile === 'session_human';
-    return McpActivityCallerSchema.parse({
-        kind: isHuman ? 'human' : 'agent',
-        permissions: isHuman ? [] : subject.permissions,
-        networkScopeId: isHuman ? null : subject.networkScopeId,
-    });
-}
-export const McpCapabilityDecisionReasonSchema = z.enum([
-    'session_human',
-    'enrollment',
-    'authenticated',
-    'agent_self_read',
-    'informational',
-    'permission_granted',
-    'delivery',
-    'enrollment_required',
-    'unregistered_principal',
-    'invalid_agent',
-    'agent_admin_denied',
-    'human_read_own_agent_denied',
-    'human_only',
-    'permission_missing',
-    'delivery_required',
-    'removed',
-    'tool_unclassified',
-]);
-/**
- * Builds a safe denial event from a resolved subject and a denial decision.
- * Only whitelisted, non-sensitive fields are copied across; the caller's
- * granted permissions, credentials, headers, and tool arguments are never
- * included.
- */
-export function buildMcpAuthorizationDenialEvent(input) {
-    const { phase, toolName, subject, decision } = input;
-    return {
-        phase,
-        toolName,
-        profile: subject.profile,
-        reason: decision.reason,
-        ...(decision.reach ? { reach: decision.reach } : {}),
-        ...(decision.requiredPermissions && decision.requiredPermissions.length > 0
-            ? { requiredPermissions: [...decision.requiredPermissions] }
-            : {}),
-        userId: subject.userId,
-        ...(subject.agentId ? { agentId: subject.agentId } : {}),
-        networkScopeId: subject.networkScopeId,
-    };
-}
-/**
- * Reusable MCP capability policy. It stores static rules only; caller-specific
- * subjects and decisions are never retained.
- */
-export class McpCapabilityPolicy {
-    constructor(options = {}) {
-        const parsedRules = McpToolAccessRuleMapSchema.parse(Object.fromEntries(options.toolRules ?? CANONICAL_MCP_TOOL_ACCESS_RULES));
-        this.toolRules = new Map(Object.entries(parsedRules));
-    }
-    /**
-     * Decides whether a resolved caller may use one classified tool.
-     */
-    authorize(subject, toolName) {
-        const rule = this.toolRules.get(toolName);
-        if (!rule)
-            return { allowed: false, reason: 'tool_unclassified' };
-        if (rule.access === 'removed') {
-            return { allowed: false, reason: 'removed', reach: rule.reach };
-        }
-        if (subject.profile === 'invalid_agent') {
-            return { allowed: false, reason: 'invalid_agent', reach: rule.reach };
-        }
-        if (subject.profile === 'unregistered_key') {
-            return { allowed: false, reason: 'unregistered_principal', reach: rule.reach };
-        }
-        if (subject.profile === 'enrollment_key') {
-            return toolName === 'register_agent'
-                ? { allowed: true, reason: 'enrollment', reach: rule.reach }
-                : { allowed: false, reason: 'enrollment_required', reach: rule.reach };
-        }
-        if (subject.profile === 'hermes_agent') {
-            const requirement = HERMES_AGENT_MCP_TOOL_PERMISSIONS.get(toolName);
-            if (!requirement)
-                return { allowed: false, reason: 'tool_unclassified' };
-            return subject.permissions.includes(requirement.action)
-                ? {
-                    allowed: true,
-                    reason: 'permission_granted',
-                    reach: requirement.reach,
-                    requiredPermissions: [requirement.action],
-                }
-                : {
-                    allowed: false,
-                    reason: 'permission_missing',
-                    reach: requirement.reach,
-                    requiredPermissions: [requirement.action],
-                };
-        }
-        if (rule.access === 'delivery_only') {
-            return subject.profile === 'delivery_agent'
-                ? { allowed: true, reason: 'delivery', reach: rule.reach }
-                : { allowed: false, reason: 'delivery_required', reach: rule.reach };
-        }
-        // Agent administration is split by principal kind and must be decided
-        // BEFORE the generic session-human blanket allow below — otherwise a
-        // session human would be admitted to read_own_agent (an agent-only tool)
-        // by the blanket allow before this rule is ever reached (IND-599).
-        if (rule.access === 'agent_admin') {
-            // read_own_agent is the ONLY agent_admin tool available to a registered
-            // active agent, and it returns that agent's own record (no target). Every
-            // other agent_admin tool is an owner/admin action reserved for humans.
-            if (subject.profile === 'registered_global_agent' ||
-                subject.profile === 'registered_network_agent' ||
-                subject.profile === 'delivery_agent') {
-                return toolName === 'read_own_agent'
-                    ? { allowed: true, reason: 'agent_self_read', reach: rule.reach }
-                    : { allowed: false, reason: 'agent_admin_denied', reach: rule.reach };
-            }
-            // Session humans get every agent_admin tool EXCEPT read_own_agent,
-            // which is reserved for agent principals.
-            if (subject.profile === 'session_human') {
-                return toolName === 'read_own_agent'
-                    ? { allowed: false, reason: 'human_read_own_agent_denied', reach: rule.reach }
-                    : { allowed: true, reason: 'session_human', reach: rule.reach };
-            }
-            // Every other profile (enrollment/unregistered/invalid) is handled above
-            // and never reaches here; fail closed for completeness.
-            return { allowed: false, reason: 'agent_admin_denied', reach: rule.reach };
-        }
-        if (subject.profile === 'session_human') {
-            return { allowed: true, reason: 'session_human', reach: rule.reach };
-        }
-        if (rule.access === 'human_only') {
-            return { allowed: false, reason: 'human_only', reach: rule.reach };
-        }
-        if (rule.access === 'informational') {
-            return { allowed: true, reason: 'informational', reach: rule.reach };
-        }
-        if (rule.access === 'authenticated') {
-            return { allowed: true, reason: 'authenticated', reach: rule.reach };
-        }
-        const requiredPermissions = rule.actions ?? [];
-        return requiredPermissions.some((action) => subject.permissions.includes(action))
-            ? {
-                allowed: true,
-                reason: 'permission_granted',
-                reach: rule.reach,
-                requiredPermissions,
-            }
-            : {
-                allowed: false,
-                reason: 'permission_missing',
-                reach: rule.reach,
-                requiredPermissions,
-            };
-    }
-    /**
-     * Filters a static inventory and returns a fresh, uncached caller list.
-     */
-    visibleToolNames(subject, toolNames) {
-        return toolNames.filter((toolName) => this.authorize(subject, toolName).allowed);
-    }
-    /** Returns the static classification for inventory tests and host composition. */
-    ruleFor(toolName) {
-        return this.toolRules.get(toolName);
-    }
-}
-/** Canonical production options explicitly passed by the host composition. */
-export const CANONICAL_MCP_CAPABILITY_POLICY_OPTIONS = {
-    toolRules: CANONICAL_MCP_TOOL_ACCESS_RULES,
-};

package/dist/mcp/mcp.server.d.ts

@@ -1,90 +0,0 @@
-/**
- * MCP Server Factory — creates an McpServer instance with all protocol tools
- * registered from the existing tool registry. Each tool invocation resolves
- * auth from the HTTP request, builds a ResolvedToolContext, and delegates
- * to the raw tool handler.
- */
-import { McpServer, fromJsonSchema } from '@modelcontextprotocol/server';
-import type { JsonSchemaType } from '@modelcontextprotocol/server';
-import type { McpAuthResolver } from '../shared/interfaces/auth.interface.js';
-import type { ToolDeps, ResolvedToolContext, RawToolDefinition } from '../shared/agent/tool.helpers.js';
-import type { ToolRegistryDeps } from '../shared/agent/tool.registry.js';
-import type { McpAuthorizationObserver, McpCapabilityPolicyOptions } from './mcp.authorization-policy.js';
-/**
- * Static registration metadata for one MCP tool — schema conversion artifacts
- * that depend only on registry-shaping feature flags, not on per-request
- * database scope.
- */
-type McpToolRegistrationMetadata = Pick<RawToolDefinition, 'name' | 'description' | 'schema'> & {
-    jsonSchema: JsonSchemaType;
-    inputSchema: ReturnType<typeof fromJsonSchema>;
-};
-/**
- * Builds a cache key from registry-shaping dependency booleans.
- * When a feature flag changes the tool set, the cache key changes so
- * the cached metadata set is automatically invalidated.
- */
-export declare function getMcpToolMetadataCacheKey(deps: Pick<ToolDeps, 'chatSession' | 'agentDatabase' | 'agentDispatcher' | 'questionerEnqueue'>): string;
-/**
- * Clears the metadata cache. Used in tests to ensure fresh state between cases.
- */
-export declare function clearMcpToolMetadataCacheForTests(): void;
-/**
- * Returns cached (or builds and caches) static MCP tool registration metadata.
- * The first call per cache key runs the full registry creation + schema
- * conversion; subsequent calls return the cached metadata array for the same
- * registry-shaping dependency profile.
- *
- * Does NOT store tool handlers — those remain request-scoped because they
- * capture per-request userDb/systemDb.
- */
-export declare function getCachedMcpToolMetadata(deps: ToolRegistryDeps): readonly McpToolRegistrationMetadata[];
-/**
- * Runtime/auth failures are converted into structured MCP `isError` tool
- * results for the caller. Reporting them as application exceptions produces
- * Sentry noise for expected client failures and policy-enforced timeouts.
- */
-export declare function shouldReportMcpToolError(err: unknown): boolean;
-/**
- * Strips internal `_`-prefixed keys from `data` and promotes `isError`
- * from the inner `success: false` signal to the MCP envelope level.
- * Fail-open: if JSON parsing throws, returns the original text with isError: false.
- */
-export declare function sanitizeMcpResult(text: string): {
-    text: string;
-    isError: boolean;
-};
-/**
- * Factory for creating per-request scoped database instances.
- * Injected from the controller/handler layer to keep the protocol layer
- * free of direct adapter imports.
- */
-export interface ScopedDepsFactory {
-    /** Creates scoped userDb and systemDb for the given user and allowed network IDs. */
-    create(userId: string, allowedNetworkIds: string[]): Pick<ToolDeps, 'userDb' | 'systemDb'>;
-}
-/**
- * Promotes a network-scoped agent's bound network into the resolved tool
- * context as the implicit chat scope. Every tool derives its focused network
- * from the `scopeType`/`scopeId` envelope; without this step scoped API-key
- * calls would still resolve an unscoped/global view.
- *
- * No-op when there is no scope, or when an explicit scope is already set
- * (a user-driven network-scoped chat must keep precedence over the agent
- * binding — which would be a strict subset anyway, since the API key cannot
- * reach beyond its bound network).
- */
-export declare const applyNetworkScopeToContext: (context: ResolvedToolContext, networkScopeId: string | null | undefined) => void;
-export { ONBOARDING_ALLOWED } from './mcp.authorization-policy.js';
-/**
- * Builds the onboarding gate message for REST Tool API callers. Condensed
- * from the chat onboarding flow into a 6-step tool-error guide. MCP does
- * not use this gate.
- */
-export declare function buildMcpOnboardingMessage(ctx: ResolvedToolContext): string;
-export declare const MCP_INSTRUCTIONS: string;
-/**
- * Extracts a Bearer token from an HTTP Authorization header.
- */
-export declare function extractBearerToken(req: Request): string | undefined;
-export declare function createMcpServer(deps: ToolRegistryDeps, authResolver: McpAuthResolver, scopedDepsFactory: ScopedDepsFactory, policyOptions?: McpCapabilityPolicyOptions, authorizationObserver?: McpAuthorizationObserver): McpServer;