@multi-agent-protocol/sdk 0.0.2

package/dist/index-C7XPWnxS.d.ts

@@ -0,0 +1,3052 @@
+/**
+ * Multi-Agent Protocol (MAP) Type Definitions - v2
+ *
+ * Core type definitions matching the MAP JSON Schema.
+ * These types are the foundation for the TypeScript SDK.
+ *
+ * v2 Changes:
+ * - Fixed ERROR_CODES collision (FEDERATION_AUTH_FAILED)
+ * - Added Agent.ownerId for ownership tracking
+ * - Reorganized method constants by capability domain
+ * - Added EventInput type and createEvent() helper
+ * - Added disconnect policy and lifecycle events
+ * - Expanded subscription filters
+ * - Standardized response shapes (always return entities)
+ * - Added hierarchy expansion to agents/get
+ * - Added CAPABILITY_REQUIREMENTS mapping
+ * - Clarified message event data (no payloads)
+ */
+/** Unique identifier for any participant (agent, client, system, gateway) */
+type ParticipantId = string;
+/** Unique identifier for an agent */
+type AgentId = string;
+/** Unique identifier for a scope */
+type ScopeId = string;
+/** Unique identifier for a session */
+type SessionId = string;
+/** Unique identifier for a message */
+type MessageId = string;
+/** Unique identifier for a subscription */
+type SubscriptionId = string;
+/** Identifier for correlating related messages */
+type CorrelationId = string;
+/** JSON-RPC request ID */
+type RequestId = string | number;
+/** MAP protocol version */
+type ProtocolVersion = 1;
+/** Unix timestamp in milliseconds */
+type Timestamp = number;
+/** Vendor extension metadata */
+type Meta = Record<string, unknown>;
+/** Type of participant in the protocol */
+type ParticipantType = 'agent' | 'client' | 'system' | 'gateway';
+/** Transport binding type */
+type TransportType = 'websocket' | 'stdio' | 'inprocess' | 'http-sse';
+/**
+ * Streaming capabilities for backpressure and flow control.
+ * Servers advertise these to indicate what features they support.
+ */
+interface StreamingCapabilities {
+    /** Server can receive and process ack notifications */
+    supportsAck?: boolean;
+    /** Server will pause sending when client falls behind */
+    supportsFlowControl?: boolean;
+    /** Server supports pause/resume subscription state */
+    supportsPause?: boolean;
+}
+/** Capabilities of a participant, grouped by category */
+interface ParticipantCapabilities {
+    observation?: {
+        /** Can subscribe to event streams */
+        canObserve?: boolean;
+        /** Can query agents and structure */
+        canQuery?: boolean;
+    };
+    messaging?: {
+        /** Can send messages */
+        canSend?: boolean;
+        /** Can receive messages addressed to it */
+        canReceive?: boolean;
+        /** Can send to scopes/roles */
+        canBroadcast?: boolean;
+    };
+    lifecycle?: {
+        /** Can create child agents */
+        canSpawn?: boolean;
+        /** Can register agents (not as children) */
+        canRegister?: boolean;
+        /** Can remove agents */
+        canUnregister?: boolean;
+        /** Can inject context/control agents */
+        canSteer?: boolean;
+        /** Can request agent termination */
+        canStop?: boolean;
+    };
+    scopes?: {
+        /** Can create new scopes */
+        canCreateScopes?: boolean;
+        /** Can modify and delete scopes */
+        canManageScopes?: boolean;
+    };
+    federation?: {
+        /** Can connect to and route to federated systems */
+        canFederate?: boolean;
+    };
+    /** Streaming/backpressure capabilities */
+    streaming?: StreamingCapabilities;
+    _meta?: Meta;
+}
+/** A participant in the MAP protocol */
+interface Participant {
+    id: ParticipantId;
+    type: ParticipantType;
+    name?: string;
+    capabilities?: ParticipantCapabilities;
+    transport?: TransportType;
+    sessionId?: SessionId;
+    metadata?: Record<string, unknown>;
+    _meta?: Meta;
+}
+/**
+ * State of an agent.
+ * Standard states are enumerated; custom states use 'x-' prefix.
+ */
+type AgentState = 'registered' | 'active' | 'busy' | 'idle' | 'suspended' | 'stopping' | 'stopped' | 'failed' | 'orphaned' | `x-${string}`;
+/** Type of relationship between agents */
+type AgentRelationshipType = 'peer' | 'supervisor' | 'supervised' | 'collaborator';
+/** A relationship between agents */
+interface AgentRelationship {
+    type: AgentRelationshipType;
+    agentId: AgentId;
+    metadata?: Record<string, unknown>;
+    _meta?: Meta;
+}
+/** Lifecycle metadata for an agent */
+interface AgentLifecycle {
+    createdAt?: Timestamp;
+    startedAt?: Timestamp;
+    stoppedAt?: Timestamp;
+    lastActiveAt?: Timestamp;
+    orphanedAt?: Timestamp;
+    exitCode?: number;
+    exitReason?: string;
+    _meta?: Meta;
+}
+/** Who can see this agent */
+type AgentVisibility = 'public' | 'parent-only' | 'scope' | 'system';
+/** An agent in the multi-agent system */
+interface Agent {
+    id: AgentId;
+    /**
+     * The participant that owns/controls this agent's connection.
+     * Used for message routing and cleanup on disconnect.
+     *
+     * - Non-null: Agent is owned by the specified participant
+     * - null: Agent is orphaned (owner disconnected with 'orphan' policy)
+     */
+    ownerId: ParticipantId | null;
+    name?: string;
+    description?: string;
+    /** Parent agent ID (for spawned agents) */
+    parent?: AgentId;
+    /** Child agent IDs (populated when queried with include.children) */
+    children?: AgentId[];
+    relationships?: AgentRelationship[];
+    state: AgentState;
+    role?: string;
+    scopes?: ScopeId[];
+    /**
+     * Simple visibility setting (legacy).
+     * @deprecated Use permissionOverrides.canSee.agents for more granular control
+     */
+    visibility?: AgentVisibility;
+    /**
+     * Per-agent permission overrides.
+     * Merged on top of role-based defaults from system configuration.
+     * Only include fields that differ from the role default.
+     *
+     * @example
+     * ```typescript
+     * // Agent that accepts messages from clients (unlike role default)
+     * permissionOverrides: {
+     *   acceptsFrom: { clients: 'all' }
+     * }
+     * ```
+     */
+    permissionOverrides?: Partial<AgentPermissions>;
+    lifecycle?: AgentLifecycle;
+    capabilities?: ParticipantCapabilities;
+    metadata?: Record<string, unknown>;
+    _meta?: Meta;
+}
+/**
+ * Check if an agent is orphaned (owner disconnected).
+ * Orphaned agents have `ownerId === null`.
+ */
+declare function isOrphanedAgent(agent: Agent): boolean;
+/**
+ * Rule for which agents this agent can see.
+ * - 'all': Can see any agent in the system
+ * - 'hierarchy': Can see parent, children, ancestors, descendants
+ * - 'scoped': Can see agents in the same scopes
+ * - 'direct': Can only see explicitly included agents
+ * - { include: [...] }: Explicit allowlist of agent IDs
+ */
+type AgentVisibilityRule = 'all' | 'hierarchy' | 'scoped' | 'direct' | {
+    include: AgentId[];
+};
+/**
+ * Rule for which scopes this agent can see.
+ * - 'all': Can see any scope
+ * - 'member': Can only see scopes they're a member of
+ * - { include: [...] }: Explicit allowlist of scope IDs
+ */
+type ScopeVisibilityRule = 'all' | 'member' | {
+    include: ScopeId[];
+};
+/**
+ * Rule for how much agent hierarchy structure this agent can see.
+ * - 'full': Can see the full agent hierarchy tree
+ * - 'local': Can see immediate parent and children only
+ * - 'none': Cannot see hierarchy relationships
+ */
+type StructureVisibilityRule = 'full' | 'local' | 'none';
+/**
+ * Rule for which agents this agent can send messages to.
+ * - 'all': Can message any agent
+ * - 'hierarchy': Can message parent, children, ancestors, descendants
+ * - 'scoped': Can message agents in the same scopes
+ * - { include: [...] }: Explicit allowlist of agent IDs
+ */
+type AgentMessagingRule = 'all' | 'hierarchy' | 'scoped' | {
+    include: AgentId[];
+};
+/**
+ * Rule for which scopes this agent can send messages to.
+ * - 'all': Can send to any scope
+ * - 'member': Can only send to scopes they're a member of
+ * - { include: [...] }: Explicit allowlist of scope IDs
+ */
+type ScopeMessagingRule = 'all' | 'member' | {
+    include: ScopeId[];
+};
+/**
+ * Rule for which agents this agent accepts messages from.
+ * - 'all': Accepts from any agent
+ * - 'hierarchy': Accepts from parent, children, ancestors, descendants
+ * - 'scoped': Accepts from agents in the same scopes
+ * - { include: [...] }: Explicit allowlist of agent IDs
+ */
+type AgentAcceptanceRule = 'all' | 'hierarchy' | 'scoped' | {
+    include: AgentId[];
+};
+/**
+ * Rule for which clients this agent accepts messages from.
+ * - 'all': Accepts from any client
+ * - 'none': Does not accept from any client
+ * - { include: [...] }: Explicit allowlist of participant IDs
+ */
+type ClientAcceptanceRule = 'all' | 'none' | {
+    include: ParticipantId[];
+};
+/**
+ * Rule for which federated systems this agent accepts messages from.
+ * - 'all': Accepts from any federated system
+ * - 'none': Does not accept from any federated system
+ * - { include: [...] }: Explicit allowlist of system IDs
+ */
+type SystemAcceptanceRule = 'all' | 'none' | {
+    include: string[];
+};
+/**
+ * Permission configuration for an agent.
+ * Defines what the agent can see, who it can message, and who it accepts messages from.
+ *
+ * Used in two ways:
+ * 1. As role-based defaults in system configuration
+ * 2. As per-agent overrides via Agent.permissionOverrides
+ *
+ * @example
+ * ```typescript
+ * const workerPermissions: AgentPermissions = {
+ *   canSee: {
+ *     agents: 'hierarchy',
+ *     scopes: 'member',
+ *     structure: 'local',
+ *   },
+ *   canMessage: {
+ *     agents: 'hierarchy',
+ *     scopes: 'member',
+ *   },
+ *   acceptsFrom: {
+ *     agents: 'hierarchy',
+ *     clients: 'none',
+ *     systems: 'none',
+ *   },
+ * };
+ * ```
+ */
+interface AgentPermissions {
+    /** Rules for what this agent can see */
+    canSee?: {
+        /** Which agents this agent can see */
+        agents?: AgentVisibilityRule;
+        /** Which scopes this agent can see */
+        scopes?: ScopeVisibilityRule;
+        /** How much hierarchy structure this agent can see */
+        structure?: StructureVisibilityRule;
+    };
+    /** Rules for who this agent can send messages to */
+    canMessage?: {
+        /** Which agents this agent can message */
+        agents?: AgentMessagingRule;
+        /** Which scopes this agent can send to */
+        scopes?: ScopeMessagingRule;
+    };
+    /** Rules for who this agent accepts messages from */
+    acceptsFrom?: {
+        /** Which agents this agent accepts messages from */
+        agents?: AgentAcceptanceRule;
+        /** Which clients this agent accepts messages from */
+        clients?: ClientAcceptanceRule;
+        /** Which federated systems this agent accepts messages from */
+        systems?: SystemAcceptanceRule;
+    };
+}
+/**
+ * System-level configuration for agent permissions.
+ * Defines default permissions and role-based permission templates.
+ *
+ * Resolution order:
+ * 1. Start with defaultPermissions
+ * 2. If agent has a role, deep merge rolePermissions[role]
+ * 3. Deep merge agent.permissionOverrides
+ *
+ * @example
+ * ```typescript
+ * const config: AgentPermissionConfig = {
+ *   defaultPermissions: {
+ *     canSee: { agents: 'hierarchy', scopes: 'member', structure: 'local' },
+ *     canMessage: { agents: 'hierarchy', scopes: 'member' },
+ *     acceptsFrom: { agents: 'hierarchy', clients: 'none', systems: 'none' },
+ *   },
+ *   rolePermissions: {
+ *     coordinator: {
+ *       canSee: { agents: 'all', scopes: 'all', structure: 'full' },
+ *       canMessage: { agents: 'all', scopes: 'all' },
+ *       acceptsFrom: { agents: 'all', clients: 'all', systems: 'none' },
+ *     },
+ *   },
+ * };
+ * ```
+ */
+interface AgentPermissionConfig {
+    /** Default permissions for agents without a role or role-specific config */
+    defaultPermissions: AgentPermissions;
+    /** Role-based permission templates */
+    rolePermissions: Record<string, AgentPermissions>;
+}
+/** Address a single agent directly */
+interface DirectAddress {
+    agent: AgentId;
+}
+/** Address multiple agents */
+interface MultiAddress {
+    agents: AgentId[];
+}
+/** Address all agents in a scope */
+interface ScopeAddress {
+    scope: ScopeId;
+}
+/** Address agents by role, optionally within a scope */
+interface RoleAddress {
+    role: string;
+    within?: ScopeId;
+}
+/** Address relative to sender in hierarchy */
+interface HierarchicalAddress {
+    parent?: true;
+    children?: true;
+    ancestors?: true;
+    descendants?: true;
+    siblings?: true;
+    depth?: number;
+}
+/** Address all agents in the system */
+interface BroadcastAddress {
+    broadcast: true;
+}
+/** Address the system/router itself */
+interface SystemAddress {
+    system: true;
+}
+/** Address any participant by ID or category */
+interface ParticipantAddress {
+    participant?: ParticipantId;
+    participants?: 'all' | 'agents' | 'clients';
+}
+/** Address an agent in a federated system */
+interface FederatedAddress {
+    system: string;
+    agent: AgentId;
+}
+/** Flexible addressing for any topology */
+type Address = string | DirectAddress | MultiAddress | ScopeAddress | RoleAddress | HierarchicalAddress | BroadcastAddress | SystemAddress | ParticipantAddress | FederatedAddress;
+/** Message priority */
+type MessagePriority = 'urgent' | 'high' | 'normal' | 'low';
+/** Message delivery guarantees */
+type DeliverySemantics = 'fire-and-forget' | 'acknowledged' | 'guaranteed';
+/** Relationship context for the message */
+type MessageRelationship = 'parent-to-child' | 'child-to-parent' | 'peer' | 'broadcast';
+/** Metadata for a message */
+interface MessageMeta {
+    timestamp?: Timestamp;
+    relationship?: MessageRelationship;
+    expectsResponse?: boolean;
+    correlationId?: CorrelationId;
+    isResult?: boolean;
+    priority?: MessagePriority;
+    delivery?: DeliverySemantics;
+    ttlMs?: number;
+    _meta?: Meta;
+}
+/** A message in the multi-agent system */
+interface Message<T = unknown> {
+    id: MessageId;
+    from: ParticipantId;
+    to: Address;
+    timestamp: Timestamp;
+    payload?: T;
+    meta?: MessageMeta;
+    _meta?: Meta;
+}
+/** Policy for joining a scope */
+type JoinPolicy = 'open' | 'invite' | 'role' | 'system';
+/** Who can see the scope exists and its members */
+type ScopeVisibility = 'public' | 'members' | 'system';
+/** Who can see messages sent to this scope */
+type MessageVisibility = 'public' | 'members' | 'system';
+/** Who can send messages to this scope */
+type SendPolicy = 'members' | 'any';
+/** A scope for grouping agents */
+interface Scope {
+    id: ScopeId;
+    name?: string;
+    description?: string;
+    parent?: ScopeId;
+    joinPolicy?: JoinPolicy;
+    autoJoinRoles?: string[];
+    visibility?: ScopeVisibility;
+    messageVisibility?: MessageVisibility;
+    sendPolicy?: SendPolicy;
+    persistent?: boolean;
+    autoDelete?: boolean;
+    metadata?: Record<string, unknown>;
+    _meta?: Meta;
+}
+/**
+ * Event type constants.
+ * Use these instead of string literals for type safety and autocomplete.
+ */
+declare const EVENT_TYPES: {
+    readonly AGENT_REGISTERED: "agent_registered";
+    readonly AGENT_UNREGISTERED: "agent_unregistered";
+    readonly AGENT_STATE_CHANGED: "agent_state_changed";
+    readonly AGENT_ORPHANED: "agent_orphaned";
+    readonly PARTICIPANT_CONNECTED: "participant_connected";
+    readonly PARTICIPANT_DISCONNECTED: "participant_disconnected";
+    readonly MESSAGE_SENT: "message_sent";
+    readonly MESSAGE_DELIVERED: "message_delivered";
+    readonly MESSAGE_FAILED: "message_failed";
+    readonly SCOPE_CREATED: "scope_created";
+    readonly SCOPE_DELETED: "scope_deleted";
+    readonly SCOPE_MEMBER_JOINED: "scope_member_joined";
+    readonly SCOPE_MEMBER_LEFT: "scope_member_left";
+    readonly PERMISSIONS_CLIENT_UPDATED: "permissions_client_updated";
+    readonly PERMISSIONS_AGENT_UPDATED: "permissions_agent_updated";
+    readonly SYSTEM_ERROR: "system_error";
+    readonly FEDERATION_CONNECTED: "federation_connected";
+    readonly FEDERATION_DISCONNECTED: "federation_disconnected";
+};
+/** Type of system event (derived from EVENT_TYPES) */
+type EventType = (typeof EVENT_TYPES)[keyof typeof EVENT_TYPES];
+/**
+ * Input for creating events.
+ * id and timestamp are optional - server generates them.
+ */
+interface EventInput {
+    type: EventType;
+    timestamp?: Timestamp;
+    source?: ParticipantId;
+    data?: Record<string, unknown>;
+    causedBy?: string[];
+    _meta?: Meta;
+}
+/**
+ * Wire event as sent to clients.
+ * id and timestamp are always present.
+ */
+interface Event {
+    id: string;
+    type: EventType;
+    timestamp: Timestamp;
+    source?: ParticipantId;
+    data?: Record<string, unknown>;
+    causedBy?: string[];
+    _meta?: Meta;
+}
+/** Helper to create events with auto-generated id and timestamp */
+declare function createEvent(input: EventInput): Event;
+/**
+ * Filter for event subscriptions.
+ *
+ * ## Combination Logic
+ *
+ * All specified fields are combined with **AND** logic:
+ * - An event must match ALL specified criteria to be delivered
+ * - Within array fields, values are combined with **OR** logic
+ * - Empty arrays (`[]`) are treated as "no filter" (matches any)
+ * - Undefined/omitted fields are treated as "no filter" (matches any)
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * // Match agent_registered OR agent_unregistered events from agent-1 OR agent-2
+ * {
+ *   eventTypes: ['agent_registered', 'agent_unregistered'],
+ *   fromAgents: ['agent-1', 'agent-2']
+ * }
+ *
+ * // Match any event from agents with role 'worker' OR 'supervisor'
+ * { fromRoles: ['worker', 'supervisor'] }
+ *
+ * // Match scope events in scope-1 with metadata containing priority='high'
+ * {
+ *   scopes: ['scope-1'],
+ *   metadataMatch: { priority: 'high' }
+ * }
+ * ```
+ *
+ * ## Field Semantics
+ *
+ * | Field | Within-field | Cross-field | Description |
+ * |-------|--------------|-------------|-------------|
+ * | `eventTypes` | OR | AND | Event type is one of the listed types |
+ * | `agents` | OR | AND | Event relates to one of the listed agents (legacy) |
+ * | `fromAgents` | OR | AND | Event source is one of the listed agents |
+ * | `fromRoles` | OR | AND | Event source agent has one of the listed roles |
+ * | `roles` | OR | AND | Event relates to agents with one of the listed roles |
+ * | `scopes` | OR | AND | Event relates to one of the listed scopes |
+ * | `priorities` | OR | AND | Message priority is one of the listed levels |
+ * | `correlationIds` | OR | AND | Event has one of the listed correlation IDs |
+ * | `metadataMatch` | AND | AND | Event metadata contains ALL specified key-value pairs |
+ */
+interface SubscriptionFilter {
+    /**
+     * Filter by agents the event relates to.
+     * @deprecated Use `fromAgents` for clearer semantics
+     */
+    agents?: AgentId[];
+    /**
+     * Filter by roles the event relates to.
+     * Matches events where the related agent has one of these roles.
+     */
+    roles?: string[];
+    /**
+     * Filter by scopes the event relates to.
+     * Matches events with scopeId in event.data matching one of these.
+     */
+    scopes?: ScopeId[];
+    /**
+     * Filter by event type.
+     * Use EVENT_TYPES constants: `eventTypes: [EVENT_TYPES.AGENT_REGISTERED]`
+     */
+    eventTypes?: EventType[];
+    /**
+     * Filter by message priority (for message events).
+     */
+    priorities?: MessagePriority[];
+    /**
+     * Filter by correlation ID.
+     * Matches events with correlationId in event.data matching one of these.
+     */
+    correlationIds?: CorrelationId[];
+    /**
+     * Filter by source agent ID.
+     * Matches events where event.source is one of these agent IDs.
+     */
+    fromAgents?: AgentId[];
+    /**
+     * Filter by source agent role.
+     * Matches events where the source agent has one of these roles.
+     */
+    fromRoles?: string[];
+    /**
+     * Filter by metadata key-value pairs.
+     * All specified pairs must match (AND logic within this field).
+     * Checks event.data.metadata for matching values.
+     */
+    metadataMatch?: Record<string, unknown>;
+    _meta?: Meta;
+}
+/** Options for subscriptions */
+interface SubscriptionOptions$1 {
+    /** Include full payloads in message events (default: false) */
+    includeMessagePayloads?: boolean;
+    /** Exclude events from own actions (default: false) */
+    excludeOwnEvents?: boolean;
+}
+/**
+ * State of a subscription's event delivery.
+ * - 'active': Events are being delivered normally
+ * - 'paused': Events are buffered but not delivered to the iterator
+ * - 'closed': Subscription is terminated
+ */
+type SubscriptionState = 'active' | 'paused' | 'closed';
+/**
+ * Information about events dropped due to buffer overflow.
+ * Passed to overflow handlers when events cannot be buffered.
+ */
+interface OverflowInfo {
+    /** Number of events dropped in this overflow batch */
+    eventsDropped: number;
+    /** Event ID of oldest dropped event (if available) */
+    oldestDroppedId?: string;
+    /** Event ID of newest dropped event (if available) */
+    newestDroppedId?: string;
+    /** Timestamp when overflow occurred */
+    timestamp: Timestamp;
+    /** Total events dropped since subscription started */
+    totalDropped: number;
+}
+/** Handler called when subscription buffer overflows */
+type OverflowHandler = (info: OverflowInfo) => void;
+/**
+ * Parameters for acknowledging received events.
+ * Sent as a notification to inform the server of client progress.
+ * Enables optional server-side flow control.
+ */
+interface SubscriptionAckParams {
+    /** Subscription being acknowledged */
+    subscriptionId: SubscriptionId;
+    /** Acknowledge all events up to and including this sequence number */
+    upToSequence: number;
+    _meta?: Meta;
+}
+/** Notification for subscription acknowledgment */
+interface SubscriptionAckNotification extends MAPNotificationBase<SubscriptionAckParams> {
+    method: 'map/subscribe.ack';
+    params: SubscriptionAckParams;
+}
+/** Data for message_sent events (no payload for privacy) */
+interface MessageSentEventData {
+    messageId: MessageId;
+    from: ParticipantId;
+    to: Address;
+    timestamp: Timestamp;
+    correlationId?: CorrelationId;
+    priority?: MessagePriority;
+}
+/** Data for message_delivered events (no payload for privacy) */
+interface MessageDeliveredEventData {
+    messageId: MessageId;
+    from: ParticipantId;
+    deliveredTo: ParticipantId[];
+    timestamp: Timestamp;
+    correlationId?: CorrelationId;
+}
+/** Data for message_failed events */
+interface MessageFailedEventData {
+    messageId: MessageId;
+    from: ParticipantId;
+    to: Address;
+    reason: string;
+    code?: number;
+}
+/** Category of error for handling decisions */
+type ErrorCategory = 'protocol' | 'auth' | 'routing' | 'agent' | 'resource' | 'federation' | 'internal';
+/** Structured error data */
+interface MAPErrorData {
+    category?: ErrorCategory;
+    retryable?: boolean;
+    retryAfterMs?: number;
+    details?: Record<string, unknown>;
+    _meta?: Meta;
+}
+/** JSON-RPC 2.0 error object */
+interface MAPError {
+    code: number;
+    message: string;
+    data?: MAPErrorData;
+}
+/** JSON-RPC version constant */
+declare const JSONRPC_VERSION: "2.0";
+/** Base JSON-RPC request */
+interface MAPRequestBase<TParams = unknown> {
+    jsonrpc: '2.0';
+    id: RequestId;
+    method: string;
+    params?: TParams;
+}
+/** Base JSON-RPC response (success) */
+interface MAPResponseSuccess<T = unknown> {
+    jsonrpc: '2.0';
+    id: RequestId;
+    result: T;
+}
+/** Base JSON-RPC response (error) */
+interface MAPResponseError {
+    jsonrpc: '2.0';
+    id: RequestId;
+    error: MAPError;
+}
+/** JSON-RPC response (success or error) */
+type MAPResponse<T = unknown> = MAPResponseSuccess<T> | MAPResponseError;
+/** Base JSON-RPC notification */
+interface MAPNotificationBase<TParams = unknown> {
+    jsonrpc: '2.0';
+    method: string;
+    params?: TParams;
+}
+interface SessionInfo {
+    id: SessionId;
+    createdAt: Timestamp;
+    lastActiveAt?: Timestamp;
+    closedAt?: Timestamp;
+}
+type AuthMethod = 'bearer' | 'api-key' | 'mtls' | 'none';
+interface AuthParams {
+    method: AuthMethod;
+    token?: string;
+}
+interface FederationAuth {
+    method: 'bearer' | 'api-key' | 'mtls';
+    credentials?: string;
+}
+/** Policy for handling unexpected disconnection */
+interface DisconnectPolicy {
+    /** What happens to agents on disconnect */
+    agentBehavior: 'unregister' | 'orphan' | 'grace-period';
+    /** Grace period before unregistering (ms) */
+    gracePeriodMs?: number;
+    /** Emit events to subscribers */
+    notifySubscribers?: boolean;
+}
+interface ConnectRequestParams {
+    protocolVersion: ProtocolVersion;
+    participantType: ParticipantType;
+    participantId?: ParticipantId;
+    name?: string;
+    capabilities?: ParticipantCapabilities;
+    sessionId?: SessionId;
+    /** Reclaim orphaned agents from previous connection */
+    reclaimAgents?: AgentId[];
+    /** Policy for unexpected disconnect */
+    disconnectPolicy?: DisconnectPolicy;
+    auth?: AuthParams;
+    _meta?: Meta;
+}
+interface ConnectRequest extends MAPRequestBase<ConnectRequestParams> {
+    method: 'map/connect';
+    params: ConnectRequestParams;
+}
+interface ConnectResponseResult {
+    protocolVersion: ProtocolVersion;
+    sessionId: SessionId;
+    participantId: ParticipantId;
+    capabilities: ParticipantCapabilities;
+    systemInfo?: {
+        name?: string;
+        version?: string;
+    };
+    /** Is this a reconnection? */
+    reconnected?: boolean;
+    /** Reclaimed agents */
+    reclaimedAgents?: Agent[];
+    /** Currently owned agents */
+    ownedAgents?: AgentId[];
+    _meta?: Meta;
+}
+interface DisconnectRequestParams {
+    reason?: string;
+    _meta?: Meta;
+}
+interface DisconnectRequest extends MAPRequestBase<DisconnectRequestParams> {
+    method: 'map/disconnect';
+    params?: DisconnectRequestParams;
+}
+interface DisconnectResponseResult {
+    session: SessionInfo;
+    _meta?: Meta;
+}
+interface SessionListRequestParams {
+    _meta?: Meta;
+}
+interface SessionListRequest extends MAPRequestBase<SessionListRequestParams> {
+    method: 'map/session/list';
+    params?: SessionListRequestParams;
+}
+interface SessionListResponseResult {
+    sessions: SessionInfo[];
+    _meta?: Meta;
+}
+interface SessionLoadRequestParams {
+    sessionId: SessionId;
+    _meta?: Meta;
+}
+interface SessionLoadRequest extends MAPRequestBase<SessionLoadRequestParams> {
+    method: 'map/session/load';
+    params: SessionLoadRequestParams;
+}
+interface SessionLoadResponseResult {
+    sessionId: SessionId;
+    restored: boolean;
+    _meta?: Meta;
+}
+interface SessionCloseRequestParams {
+    sessionId?: SessionId;
+    _meta?: Meta;
+}
+interface SessionCloseRequest extends MAPRequestBase<SessionCloseRequestParams> {
+    method: 'map/session/close';
+    params?: SessionCloseRequestParams;
+}
+interface SessionCloseResponseResult {
+    session: SessionInfo;
+    _meta?: Meta;
+}
+interface AgentsListFilter {
+    states?: AgentState[];
+    roles?: string[];
+    scopes?: ScopeId[];
+    parent?: AgentId;
+    hasChildren?: boolean;
+    ownerId?: ParticipantId;
+}
+interface AgentsListRequestParams {
+    filter?: AgentsListFilter;
+    limit?: number;
+    cursor?: string;
+    _meta?: Meta;
+}
+interface AgentsListRequest extends MAPRequestBase<AgentsListRequestParams> {
+    method: 'map/agents/list';
+    params?: AgentsListRequestParams;
+}
+interface AgentsListResponseResult {
+    agents: Agent[];
+    nextCursor?: string;
+    _meta?: Meta;
+}
+/** Options for expanding related agents */
+interface AgentIncludeOptions {
+    parent?: boolean;
+    children?: boolean;
+    siblings?: boolean;
+    ancestors?: boolean;
+    descendants?: boolean;
+    maxDepth?: number;
+}
+interface AgentsGetRequestParams {
+    agentId: AgentId;
+    include?: AgentIncludeOptions;
+    _meta?: Meta;
+}
+interface AgentsGetRequest extends MAPRequestBase<AgentsGetRequestParams> {
+    method: 'map/agents/get';
+    params: AgentsGetRequestParams;
+}
+interface AgentsGetResponseResult {
+    agent: Agent;
+    parent?: Agent;
+    children?: Agent[];
+    siblings?: Agent[];
+    ancestors?: Agent[];
+    descendants?: Agent[];
+    _meta?: Meta;
+}
+interface AgentsRegisterRequestParams {
+    agentId?: AgentId;
+    name?: string;
+    description?: string;
+    role?: string;
+    parent?: AgentId;
+    scopes?: ScopeId[];
+    visibility?: AgentVisibility;
+    capabilities?: ParticipantCapabilities;
+    metadata?: Record<string, unknown>;
+    /** Permission overrides merged on top of role-based defaults */
+    permissionOverrides?: Partial<AgentPermissions>;
+    _meta?: Meta;
+}
+interface AgentsRegisterRequest extends MAPRequestBase<AgentsRegisterRequestParams> {
+    method: 'map/agents/register';
+    params?: AgentsRegisterRequestParams;
+}
+interface AgentsRegisterResponseResult {
+    agent: Agent;
+    _meta?: Meta;
+}
+interface AgentsUnregisterRequestParams {
+    agentId: AgentId;
+    reason?: string;
+    _meta?: Meta;
+}
+interface AgentsUnregisterRequest extends MAPRequestBase<AgentsUnregisterRequestParams> {
+    method: 'map/agents/unregister';
+    params: AgentsUnregisterRequestParams;
+}
+interface AgentsUnregisterResponseResult {
+    agent: Agent;
+    _meta?: Meta;
+}
+interface AgentsUpdateRequestParams {
+    agentId: AgentId;
+    state?: AgentState;
+    metadata?: Record<string, unknown>;
+    /**
+     * Permission overrides to apply to the agent.
+     * Merged on top of role-based defaults.
+     */
+    permissionOverrides?: Partial<AgentPermissions>;
+    _meta?: Meta;
+}
+interface AgentsUpdateRequest extends MAPRequestBase<AgentsUpdateRequestParams> {
+    method: 'map/agents/update';
+    params: AgentsUpdateRequestParams;
+}
+interface AgentsUpdateResponseResult {
+    agent: Agent;
+    _meta?: Meta;
+}
+interface AgentsSpawnRequestParams {
+    agentId?: AgentId;
+    name?: string;
+    description?: string;
+    role?: string;
+    parent?: AgentId;
+    scopes?: ScopeId[];
+    visibility?: AgentVisibility;
+    capabilities?: ParticipantCapabilities;
+    initialMessage?: Message;
+    metadata?: Record<string, unknown>;
+    _meta?: Meta;
+}
+interface AgentsSpawnRequest extends MAPRequestBase<AgentsSpawnRequestParams> {
+    method: 'map/agents/spawn';
+    params?: AgentsSpawnRequestParams;
+}
+interface AgentsSpawnResponseResult {
+    agent: Agent;
+    messageId?: MessageId;
+    _meta?: Meta;
+}
+interface AgentsStopRequestParams {
+    agentId: AgentId;
+    reason?: string;
+    force?: boolean;
+    _meta?: Meta;
+}
+interface AgentsStopRequest extends MAPRequestBase<AgentsStopRequestParams> {
+    method: 'map/agents/stop';
+    params: AgentsStopRequestParams;
+}
+interface AgentsStopResponseResult {
+    agent: Agent;
+    _meta?: Meta;
+}
+interface AgentsSuspendRequestParams {
+    agentId: AgentId;
+    reason?: string;
+    _meta?: Meta;
+}
+interface AgentsSuspendRequest extends MAPRequestBase<AgentsSuspendRequestParams> {
+    method: 'map/agents/suspend';
+    params: AgentsSuspendRequestParams;
+}
+interface AgentsSuspendResponseResult {
+    agent: Agent;
+    _meta?: Meta;
+}
+interface AgentsResumeRequestParams {
+    agentId: AgentId;
+    _meta?: Meta;
+}
+interface AgentsResumeRequest extends MAPRequestBase<AgentsResumeRequestParams> {
+    method: 'map/agents/resume';
+    params: AgentsResumeRequestParams;
+}
+interface AgentsResumeResponseResult {
+    agent: Agent;
+    _meta?: Meta;
+}
+interface SendRequestParams {
+    to: Address;
+    payload?: unknown;
+    meta?: MessageMeta;
+    _meta?: Meta;
+}
+interface SendRequest extends MAPRequestBase<SendRequestParams> {
+    method: 'map/send';
+    params: SendRequestParams;
+}
+interface SendResponseResult {
+    messageId: MessageId;
+    delivered?: ParticipantId[];
+    _meta?: Meta;
+}
+interface SubscribeRequestParams {
+    filter?: SubscriptionFilter;
+    options?: SubscriptionOptions$1;
+    replayFrom?: Timestamp | string;
+    _meta?: Meta;
+}
+interface SubscribeRequest extends MAPRequestBase<SubscribeRequestParams> {
+    method: 'map/subscribe';
+    params?: SubscribeRequestParams;
+}
+interface SubscribeResponseResult {
+    subscriptionId: SubscriptionId;
+    _meta?: Meta;
+}
+interface UnsubscribeRequestParams {
+    subscriptionId: SubscriptionId;
+    _meta?: Meta;
+}
+interface UnsubscribeRequest extends MAPRequestBase<UnsubscribeRequestParams> {
+    method: 'map/unsubscribe';
+    params: UnsubscribeRequestParams;
+}
+interface UnsubscribeResponseResult {
+    subscription: {
+        id: SubscriptionId;
+        closedAt: Timestamp;
+    };
+    _meta?: Meta;
+}
+/**
+ * A replayed event with its envelope metadata.
+ */
+interface ReplayedEvent {
+    /** Globally unique event ID (ULID format) */
+    eventId: string;
+    /** Server timestamp when event was originally processed */
+    timestamp: Timestamp;
+    /** Event IDs that causally precede this event */
+    causedBy?: string[];
+    /** The event payload */
+    event: Event;
+}
+/**
+ * Parameters for replaying historical events.
+ *
+ * Uses keyset pagination with `afterEventId` - pass the last eventId
+ * from the previous response to get the next page of results.
+ *
+ * @example
+ * ```typescript
+ * // Replay from a specific point
+ * const page1 = await client.replay({ limit: 100 });
+ * const page2 = await client.replay({
+ *   afterEventId: page1.events.at(-1)?.eventId,
+ *   limit: 100
+ * });
+ * ```
+ */
+interface ReplayRequestParams {
+    /**
+     * Start after this eventId (exclusive).
+     * Used for keyset pagination - pass the last eventId from previous response.
+     */
+    afterEventId?: string;
+    /**
+     * Alternative: start from this timestamp (inclusive).
+     * If both afterEventId and fromTimestamp are provided, afterEventId takes precedence.
+     */
+    fromTimestamp?: Timestamp;
+    /**
+     * End at this timestamp (inclusive).
+     * If not provided, replays up to the most recent event.
+     */
+    toTimestamp?: Timestamp;
+    /**
+     * Filter events (same as subscription filter).
+     */
+    filter?: SubscriptionFilter;
+    /**
+     * Maximum number of events to return.
+     * Default: 100, Maximum: 1000
+     */
+    limit?: number;
+    _meta?: Meta;
+}
+interface ReplayRequest extends MAPRequestBase<ReplayRequestParams> {
+    method: 'map/replay';
+    params?: ReplayRequestParams;
+}
+interface ReplayResponseResult {
+    /** Replayed events in chronological order */
+    events: ReplayedEvent[];
+    /** Whether more events exist after the last returned event */
+    hasMore: boolean;
+    /**
+     * Total count of matching events (if known).
+     * May be omitted for performance reasons on large result sets.
+     */
+    totalCount?: number;
+    _meta?: Meta;
+}
+interface AuthRefreshRequestParams {
+    refreshToken: string;
+    _meta?: Meta;
+}
+interface AuthRefreshRequest extends MAPRequestBase<AuthRefreshRequestParams> {
+    method: 'map/auth/refresh';
+    params: AuthRefreshRequestParams;
+}
+interface AuthRefreshResponseResult {
+    accessToken: string;
+    expiresAt: Timestamp;
+    refreshToken?: string;
+    _meta?: Meta;
+}
+interface ScopesListRequestParams {
+    parent?: ScopeId;
+    _meta?: Meta;
+}
+interface ScopesListRequest extends MAPRequestBase<ScopesListRequestParams> {
+    method: 'map/scopes/list';
+    params?: ScopesListRequestParams;
+}
+interface ScopesListResponseResult {
+    scopes: Scope[];
+    _meta?: Meta;
+}
+interface ScopesGetRequestParams {
+    scopeId: ScopeId;
+    _meta?: Meta;
+}
+interface ScopesGetRequest extends MAPRequestBase<ScopesGetRequestParams> {
+    method: 'map/scopes/get';
+    params: ScopesGetRequestParams;
+}
+interface ScopesGetResponseResult {
+    scope: Scope;
+    _meta?: Meta;
+}
+interface ScopesCreateRequestParams {
+    scopeId?: ScopeId;
+    name?: string;
+    description?: string;
+    parent?: ScopeId;
+    joinPolicy?: JoinPolicy;
+    autoJoinRoles?: string[];
+    visibility?: ScopeVisibility;
+    messageVisibility?: MessageVisibility;
+    sendPolicy?: SendPolicy;
+    persistent?: boolean;
+    autoDelete?: boolean;
+    metadata?: Record<string, unknown>;
+    _meta?: Meta;
+}
+interface ScopesCreateRequest extends MAPRequestBase<ScopesCreateRequestParams> {
+    method: 'map/scopes/create';
+    params?: ScopesCreateRequestParams;
+}
+interface ScopesCreateResponseResult {
+    scope: Scope;
+    _meta?: Meta;
+}
+interface ScopesDeleteRequestParams {
+    scopeId: ScopeId;
+    _meta?: Meta;
+}
+interface ScopesDeleteRequest extends MAPRequestBase<ScopesDeleteRequestParams> {
+    method: 'map/scopes/delete';
+    params: ScopesDeleteRequestParams;
+}
+interface ScopesDeleteResponseResult {
+    scope: Scope;
+    _meta?: Meta;
+}
+interface ScopesJoinRequestParams {
+    scopeId: ScopeId;
+    agentId: AgentId;
+    _meta?: Meta;
+}
+interface ScopesJoinRequest extends MAPRequestBase<ScopesJoinRequestParams> {
+    method: 'map/scopes/join';
+    params: ScopesJoinRequestParams;
+}
+interface ScopesJoinResponseResult {
+    scope: Scope;
+    agent: Agent;
+    _meta?: Meta;
+}
+interface ScopesLeaveRequestParams {
+    scopeId: ScopeId;
+    agentId: AgentId;
+    _meta?: Meta;
+}
+interface ScopesLeaveRequest extends MAPRequestBase<ScopesLeaveRequestParams> {
+    method: 'map/scopes/leave';
+    params: ScopesLeaveRequestParams;
+}
+interface ScopesLeaveResponseResult {
+    scope: Scope;
+    agent: Agent;
+    _meta?: Meta;
+}
+interface ScopesMembersRequestParams {
+    scopeId: ScopeId;
+    limit?: number;
+    cursor?: string;
+    _meta?: Meta;
+}
+interface ScopesMembersRequest extends MAPRequestBase<ScopesMembersRequestParams> {
+    method: 'map/scopes/members';
+    params: ScopesMembersRequestParams;
+}
+interface ScopesMembersResponseResult {
+    members: AgentId[];
+    nextCursor?: string;
+    _meta?: Meta;
+}
+interface StructureGraphRequestParams {
+    rootAgentId?: AgentId;
+    depth?: number;
+    includeRelationships?: boolean;
+    _meta?: Meta;
+}
+interface StructureGraphRequest extends MAPRequestBase<StructureGraphRequestParams> {
+    method: 'map/structure/graph';
+    params?: StructureGraphRequestParams;
+}
+interface GraphEdge {
+    from: AgentId;
+    to: AgentId;
+    type: 'parent-child' | 'peer' | 'supervisor' | 'collaborator';
+}
+interface StructureGraphResponseResult {
+    nodes: Agent[];
+    edges: GraphEdge[];
+    _meta?: Meta;
+}
+type InjectDelivery = 'interrupt' | 'queue' | 'best-effort';
+type InjectDeliveryResult = 'interrupt' | 'queue' | 'message';
+interface InjectRequestParams {
+    agentId: AgentId;
+    content: unknown;
+    delivery?: InjectDelivery;
+    _meta?: Meta;
+}
+interface InjectRequest extends MAPRequestBase<InjectRequestParams> {
+    method: 'map/inject';
+    params: InjectRequestParams;
+}
+interface InjectResponseResult {
+    injected: boolean;
+    delivery?: InjectDeliveryResult;
+    _meta?: Meta;
+}
+/**
+ * Parameters for updating client permissions.
+ * Only system/admin participants can update client permissions.
+ */
+interface PermissionsUpdateRequestParams {
+    /** Client to update permissions for */
+    clientId: ParticipantId;
+    /** Partial permissions to merge with existing */
+    permissions: Partial<ParticipantCapabilities>;
+    _meta?: Meta;
+}
+interface PermissionsUpdateRequest extends MAPRequestBase<PermissionsUpdateRequestParams> {
+    method: 'map/permissions/update';
+    params: PermissionsUpdateRequestParams;
+}
+interface PermissionsUpdateResponseResult {
+    /** Whether update was applied */
+    success: boolean;
+    /** Effective permissions after update */
+    effectivePermissions: ParticipantCapabilities;
+    _meta?: Meta;
+}
+/**
+ * Event data for permissions_client_updated events.
+ * Emitted when a client's permissions are changed.
+ */
+interface PermissionsClientUpdatedEventData {
+    /** Client whose permissions changed */
+    clientId: ParticipantId;
+    /** The permission changes that were applied */
+    changes: Partial<ParticipantCapabilities>;
+    /** Effective permissions after the update */
+    effectivePermissions: ParticipantCapabilities;
+    /** Participant who made the change */
+    updatedBy: ParticipantId;
+}
+/**
+ * Event data for permissions_agent_updated events.
+ * Emitted when an agent's permission overrides are changed.
+ */
+interface PermissionsAgentUpdatedEventData {
+    /** Agent whose permissions changed */
+    agentId: AgentId;
+    /** The permission changes that were applied */
+    changes: Partial<AgentPermissions>;
+    /** Effective permissions after the update */
+    effectivePermissions: AgentPermissions;
+    /** Participant who made the change */
+    updatedBy: ParticipantId;
+}
+/**
+ * Metadata for federation routing and tracking.
+ * Included in every message routed between federated systems.
+ */
+interface FederationMetadata {
+    /** System that originated this message */
+    sourceSystem: string;
+    /** Intended final destination system */
+    targetSystem: string;
+    /** Number of systems this message has traversed */
+    hopCount: number;
+    /** Maximum hops before rejection (prevents infinite loops) */
+    maxHops?: number;
+    /** Systems this message has traversed (for debugging/loop detection) */
+    path?: string[];
+    /** Timestamp when message was first sent (ms since epoch) */
+    originTimestamp: Timestamp;
+    /** Correlation ID for cross-system tracing */
+    correlationId?: string;
+    /**
+     * Signature for integrity verification.
+     * @todo Define signing algorithm and key management
+     */
+    signature?: string;
+}
+/**
+ * Envelope for messages routed between federated systems.
+ * Wraps the payload with routing metadata for tracking and loop prevention.
+ *
+ * @typeParam T - The payload type (typically Message)
+ *
+ * @example
+ * ```typescript
+ * const envelope: FederationEnvelope<Message> = {
+ *   payload: message,
+ *   federation: {
+ *     sourceSystem: 'alpha',
+ *     targetSystem: 'beta',
+ *     hopCount: 0,
+ *     originTimestamp: Date.now(),
+ *   },
+ * };
+ * ```
+ */
+interface FederationEnvelope<T = unknown> {
+    /** The payload being routed */
+    payload: T;
+    /** Federation routing metadata */
+    federation: FederationMetadata;
+}
+/**
+ * Configuration for federation routing behavior.
+ * Used by gateways to control message routing policies.
+ */
+interface FederationRoutingConfig {
+    /** This system's identifier */
+    systemId: string;
+    /** Maximum hops to accept (default: 10) */
+    maxHops?: number;
+    /** Whether to track full path for debugging (default: false) */
+    trackPath?: boolean;
+    /** Systems we're willing to route to (undefined = all) */
+    allowedTargets?: string[];
+    /** Systems we accept routes from (undefined = all) */
+    allowedSources?: string[];
+}
+/**
+ * Configuration for buffering messages during federation outages.
+ * Messages are stored locally until the peer reconnects.
+ */
+interface FederationBufferConfig {
+    /** Enable buffering of messages during disconnection (default: true) */
+    enabled?: boolean;
+    /** Maximum number of messages to buffer per peer (default: 1000) */
+    maxMessages?: number;
+    /** Maximum buffer size in bytes per peer (default: 10MB) */
+    maxBytes?: number;
+    /** Time to retain buffered messages in ms (default: 1 hour) */
+    retentionMs?: number;
+    /** Strategy when buffer is full */
+    overflowStrategy?: 'drop-oldest' | 'drop-newest' | 'reject';
+}
+/**
+ * Configuration for replaying events from event store on reconnection.
+ * Supplements buffer with persisted events.
+ */
+interface FederationReplayConfig {
+    /** Enable replay from event store on reconnection (default: true) */
+    enabled?: boolean;
+    /** Maximum time window for replay in ms (default: 1 hour) */
+    maxReplayWindowMs?: number;
+    /** Maximum number of events to replay (default: 10000) */
+    maxReplayEvents?: number;
+    /** Filter for events to replay (optional) */
+    filter?: SubscriptionFilter;
+}
+/**
+ * Type of gateway reconnection event.
+ */
+type GatewayReconnectionEventType = 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'reconnect_failed' | 'buffer_overflow' | 'replay_started' | 'replay_completed';
+/**
+ * Event emitted during gateway reconnection lifecycle.
+ */
+interface GatewayReconnectionEvent {
+    /** Type of reconnection event */
+    type: GatewayReconnectionEventType;
+    /** Target system ID */
+    systemId: string;
+    /** Timestamp of the event */
+    timestamp: Timestamp;
+    /** Current reconnection attempt (for reconnecting events) */
+    attempt?: number;
+    /** Error message (for disconnected/reconnect_failed) */
+    error?: string;
+    /** Number of buffered messages (for buffer_overflow) */
+    bufferedCount?: number;
+    /** Number of events being replayed (for replay_started/completed) */
+    replayCount?: number;
+    /** Duration of outage in ms (for connected after reconnect) */
+    outageDurationMs?: number;
+}
+/** Handler for gateway reconnection events */
+type GatewayReconnectionEventHandler = (event: GatewayReconnectionEvent) => void;
+/**
+ * Options for gateway connection with reconnection support.
+ * Extends base connection options with federation-specific settings.
+ */
+interface GatewayReconnectionOptions {
+    /** Enable automatic reconnection (default: true) */
+    autoReconnect?: boolean;
+    /** Initial delay before first reconnection attempt in ms (default: 1000) */
+    initialDelayMs?: number;
+    /** Maximum delay between reconnection attempts in ms (default: 30000) */
+    maxDelayMs?: number;
+    /** Backoff multiplier for exponential backoff (default: 2) */
+    backoffMultiplier?: number;
+    /** Maximum number of reconnection attempts (default: Infinity) */
+    maxRetries?: number;
+    /** Add random jitter to delays (default: true) */
+    jitter?: boolean;
+    /** Buffer configuration for outages */
+    buffer?: FederationBufferConfig;
+    /** Replay configuration for event store recovery */
+    replay?: FederationReplayConfig;
+    /** Handler for reconnection lifecycle events */
+    onReconnectionEvent?: GatewayReconnectionEventHandler;
+}
+interface FederationConnectRequestParams {
+    systemId: string;
+    endpoint: string;
+    auth?: FederationAuth;
+    _meta?: Meta;
+}
+interface FederationConnectRequest extends MAPRequestBase<FederationConnectRequestParams> {
+    method: 'map/federation/connect';
+    params: FederationConnectRequestParams;
+}
+interface FederationConnectResponseResult {
+    connected: boolean;
+    systemInfo?: {
+        name?: string;
+        version?: string;
+        capabilities?: ParticipantCapabilities;
+    };
+    _meta?: Meta;
+}
+interface FederationRouteRequestParams {
+    /** Target system ID (for immediate next hop) */
+    systemId: string;
+    /**
+     * Wrapped message with federation metadata.
+     * Use this for new implementations.
+     */
+    envelope?: FederationEnvelope<Message>;
+    /**
+     * Raw message (legacy format).
+     * @deprecated Use envelope instead for proper routing metadata
+     */
+    message?: Message;
+    _meta?: Meta;
+}
+interface FederationRouteRequest extends MAPRequestBase<FederationRouteRequestParams> {
+    method: 'map/federation/route';
+    params: FederationRouteRequestParams;
+}
+interface FederationRouteResponseResult {
+    routed: boolean;
+    messageId?: MessageId;
+    _meta?: Meta;
+}
+/**
+ * Parameters for event notifications delivered to subscribers.
+ *
+ * The envelope contains both delivery metadata (subscriptionId, sequence)
+ * and optional fields for deduplication and causal ordering.
+ */
+interface EventNotificationParams {
+    /** The subscription this event is being delivered to */
+    subscriptionId: SubscriptionId;
+    /** Monotonically increasing sequence number within this subscription */
+    sequenceNumber: number;
+    /**
+     * Globally unique event identifier (ULID format).
+     *
+     * Used for:
+     * - Deduplication (same event delivered multiple times)
+     * - Replay references (afterEventId in replay requests)
+     * - Causal tracking (referenced in causedBy arrays)
+     *
+     * Format: 26-character ULID, e.g., "01HQJY3KCNP5VXWZ8M4R6T2G9B"
+     *
+     * @remarks
+     * If not provided by the server, deduplication is skipped.
+     * New routers should always provide this field.
+     */
+    eventId?: string;
+    /**
+     * Server timestamp when the event was processed (milliseconds since epoch).
+     *
+     * This is the envelope-level timestamp, which may differ from event.timestamp
+     * if the event was queued or replayed.
+     */
+    timestamp?: Timestamp;
+    /**
+     * Event IDs of events that causally precede this event.
+     *
+     * Used for enforcing causal ordering - this event should not be
+     * processed until all events in causedBy have been processed.
+     *
+     * @example
+     * A message_delivered event would have causedBy: [messagesentEventId]
+     */
+    causedBy?: string[];
+    /** The event payload */
+    event: Event;
+    _meta?: Meta;
+}
+interface EventNotification extends MAPNotificationBase<EventNotificationParams> {
+    method: 'map/event';
+    params: EventNotificationParams;
+}
+interface MessageNotificationParams {
+    message: Message;
+    _meta?: Meta;
+}
+interface MessageNotification extends MAPNotificationBase<MessageNotificationParams> {
+    method: 'map/message';
+    params: MessageNotificationParams;
+}
+/** All MAP request types */
+type MAPRequest = ConnectRequest | DisconnectRequest | SessionListRequest | SessionLoadRequest | SessionCloseRequest | AgentsListRequest | AgentsGetRequest | SendRequest | SubscribeRequest | UnsubscribeRequest | ReplayRequest | AuthRefreshRequest | AgentsRegisterRequest | AgentsSpawnRequest | AgentsUnregisterRequest | AgentsUpdateRequest | AgentsStopRequest | AgentsSuspendRequest | AgentsResumeRequest | StructureGraphRequest | ScopesListRequest | ScopesGetRequest | ScopesCreateRequest | ScopesDeleteRequest | ScopesJoinRequest | ScopesLeaveRequest | ScopesMembersRequest | PermissionsUpdateRequest | InjectRequest | FederationConnectRequest | FederationRouteRequest;
+/** All MAP notification types */
+type MAPNotification = EventNotification | MessageNotification | SubscriptionAckNotification;
+/** Core methods - All implementations must support */
+declare const CORE_METHODS: {
+    readonly CONNECT: "map/connect";
+    readonly DISCONNECT: "map/disconnect";
+    readonly SEND: "map/send";
+    readonly SUBSCRIBE: "map/subscribe";
+    readonly UNSUBSCRIBE: "map/unsubscribe";
+    readonly REPLAY: "map/replay";
+};
+/** Observation methods - Query/read operations */
+declare const OBSERVATION_METHODS: {
+    readonly AGENTS_LIST: "map/agents/list";
+    readonly AGENTS_GET: "map/agents/get";
+    readonly SCOPES_LIST: "map/scopes/list";
+    readonly SCOPES_GET: "map/scopes/get";
+    readonly SCOPES_MEMBERS: "map/scopes/members";
+    readonly STRUCTURE_GRAPH: "map/structure/graph";
+};
+/** Lifecycle methods - Agent creation/destruction */
+declare const LIFECYCLE_METHODS: {
+    readonly AGENTS_REGISTER: "map/agents/register";
+    readonly AGENTS_UNREGISTER: "map/agents/unregister";
+    readonly AGENTS_SPAWN: "map/agents/spawn";
+};
+/** State methods - Agent state management */
+declare const STATE_METHODS: {
+    readonly AGENTS_UPDATE: "map/agents/update";
+    readonly AGENTS_SUSPEND: "map/agents/suspend";
+    readonly AGENTS_RESUME: "map/agents/resume";
+    readonly AGENTS_STOP: "map/agents/stop";
+};
+/** Steering methods - External control */
+declare const STEERING_METHODS: {
+    readonly INJECT: "map/inject";
+};
+/** Scope methods - Scope management */
+declare const SCOPE_METHODS: {
+    readonly SCOPES_CREATE: "map/scopes/create";
+    readonly SCOPES_DELETE: "map/scopes/delete";
+    readonly SCOPES_JOIN: "map/scopes/join";
+    readonly SCOPES_LEAVE: "map/scopes/leave";
+};
+/** Session methods */
+declare const SESSION_METHODS: {
+    readonly SESSION_LIST: "map/session/list";
+    readonly SESSION_LOAD: "map/session/load";
+    readonly SESSION_CLOSE: "map/session/close";
+};
+/** Auth methods */
+declare const AUTH_METHODS: {
+    readonly AUTH_REFRESH: "map/auth/refresh";
+};
+/** Permission methods */
+declare const PERMISSION_METHODS: {
+    readonly PERMISSIONS_UPDATE: "map/permissions/update";
+};
+/** Federation methods */
+declare const FEDERATION_METHODS: {
+    readonly FEDERATION_CONNECT: "map/federation/connect";
+    readonly FEDERATION_ROUTE: "map/federation/route";
+};
+/** Notification methods */
+declare const NOTIFICATION_METHODS: {
+    readonly EVENT: "map/event";
+    readonly MESSAGE: "map/message";
+    /** Client acknowledges received events (for backpressure) */
+    readonly SUBSCRIBE_ACK: "map/subscribe.ack";
+};
+/** All MAP methods */
+declare const MAP_METHODS: {
+    readonly FEDERATION_CONNECT: "map/federation/connect";
+    readonly FEDERATION_ROUTE: "map/federation/route";
+    readonly PERMISSIONS_UPDATE: "map/permissions/update";
+    readonly AUTH_REFRESH: "map/auth/refresh";
+    readonly SESSION_LIST: "map/session/list";
+    readonly SESSION_LOAD: "map/session/load";
+    readonly SESSION_CLOSE: "map/session/close";
+    readonly SCOPES_CREATE: "map/scopes/create";
+    readonly SCOPES_DELETE: "map/scopes/delete";
+    readonly SCOPES_JOIN: "map/scopes/join";
+    readonly SCOPES_LEAVE: "map/scopes/leave";
+    readonly INJECT: "map/inject";
+    readonly AGENTS_UPDATE: "map/agents/update";
+    readonly AGENTS_SUSPEND: "map/agents/suspend";
+    readonly AGENTS_RESUME: "map/agents/resume";
+    readonly AGENTS_STOP: "map/agents/stop";
+    readonly AGENTS_REGISTER: "map/agents/register";
+    readonly AGENTS_UNREGISTER: "map/agents/unregister";
+    readonly AGENTS_SPAWN: "map/agents/spawn";
+    readonly AGENTS_LIST: "map/agents/list";
+    readonly AGENTS_GET: "map/agents/get";
+    readonly SCOPES_LIST: "map/scopes/list";
+    readonly SCOPES_GET: "map/scopes/get";
+    readonly SCOPES_MEMBERS: "map/scopes/members";
+    readonly STRUCTURE_GRAPH: "map/structure/graph";
+    readonly CONNECT: "map/connect";
+    readonly DISCONNECT: "map/disconnect";
+    readonly SEND: "map/send";
+    readonly SUBSCRIBE: "map/subscribe";
+    readonly UNSUBSCRIBE: "map/unsubscribe";
+    readonly REPLAY: "map/replay";
+};
+declare const STRUCTURE_METHODS: {
+    readonly STRUCTURE_GRAPH: "map/structure/graph";
+    readonly SCOPES_CREATE: "map/scopes/create";
+    readonly SCOPES_DELETE: "map/scopes/delete";
+    readonly SCOPES_JOIN: "map/scopes/join";
+    readonly SCOPES_LEAVE: "map/scopes/leave";
+    readonly AGENTS_UPDATE: "map/agents/update";
+    readonly AGENTS_SUSPEND: "map/agents/suspend";
+    readonly AGENTS_RESUME: "map/agents/resume";
+    readonly AGENTS_STOP: "map/agents/stop";
+    readonly AGENTS_REGISTER: "map/agents/register";
+    readonly AGENTS_UNREGISTER: "map/agents/unregister";
+    readonly AGENTS_SPAWN: "map/agents/spawn";
+};
+declare const EXTENSION_METHODS: {
+    readonly FEDERATION_CONNECT: "map/federation/connect";
+    readonly FEDERATION_ROUTE: "map/federation/route";
+    readonly INJECT: "map/inject";
+};
+/** JSON-RPC standard error codes */
+declare const PROTOCOL_ERROR_CODES: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+};
+/** Authentication error codes */
+declare const AUTH_ERROR_CODES: {
+    readonly AUTH_REQUIRED: 1000;
+    readonly AUTH_FAILED: 1001;
+    readonly TOKEN_EXPIRED: 1002;
+    readonly PERMISSION_DENIED: 1003;
+};
+/** Routing error codes */
+declare const ROUTING_ERROR_CODES: {
+    readonly ADDRESS_NOT_FOUND: 2000;
+    readonly AGENT_NOT_FOUND: 2001;
+    readonly SCOPE_NOT_FOUND: 2002;
+    readonly DELIVERY_FAILED: 2003;
+    readonly ADDRESS_AMBIGUOUS: 2004;
+};
+/** Agent error codes */
+declare const AGENT_ERROR_CODES: {
+    readonly AGENT_EXISTS: 3000;
+    readonly STATE_INVALID: 3001;
+    readonly NOT_RESPONDING: 3002;
+    readonly TERMINATED: 3003;
+    readonly SPAWN_FAILED: 3004;
+};
+/** Resource error codes */
+declare const RESOURCE_ERROR_CODES: {
+    readonly EXHAUSTED: 4000;
+    readonly RATE_LIMITED: 4001;
+    readonly QUOTA_EXCEEDED: 4002;
+};
+/** Federation error codes - prefixed to avoid collision with AUTH_FAILED */
+declare const FEDERATION_ERROR_CODES: {
+    readonly FEDERATION_UNAVAILABLE: 5000;
+    readonly FEDERATION_SYSTEM_NOT_FOUND: 5001;
+    readonly FEDERATION_AUTH_FAILED: 5002;
+    readonly FEDERATION_ROUTE_REJECTED: 5003;
+    /** Message has already visited this system (loop detected) */
+    readonly FEDERATION_LOOP_DETECTED: 5010;
+    /** Message exceeded maximum hop count */
+    readonly FEDERATION_MAX_HOPS_EXCEEDED: 5011;
+};
+/** All error codes */
+declare const ERROR_CODES: {
+    readonly FEDERATION_UNAVAILABLE: 5000;
+    readonly FEDERATION_SYSTEM_NOT_FOUND: 5001;
+    readonly FEDERATION_AUTH_FAILED: 5002;
+    readonly FEDERATION_ROUTE_REJECTED: 5003;
+    /** Message has already visited this system (loop detected) */
+    readonly FEDERATION_LOOP_DETECTED: 5010;
+    /** Message exceeded maximum hop count */
+    readonly FEDERATION_MAX_HOPS_EXCEEDED: 5011;
+    readonly EXHAUSTED: 4000;
+    readonly RATE_LIMITED: 4001;
+    readonly QUOTA_EXCEEDED: 4002;
+    readonly AGENT_EXISTS: 3000;
+    readonly STATE_INVALID: 3001;
+    readonly NOT_RESPONDING: 3002;
+    readonly TERMINATED: 3003;
+    readonly SPAWN_FAILED: 3004;
+    readonly ADDRESS_NOT_FOUND: 2000;
+    readonly AGENT_NOT_FOUND: 2001;
+    readonly SCOPE_NOT_FOUND: 2002;
+    readonly DELIVERY_FAILED: 2003;
+    readonly ADDRESS_AMBIGUOUS: 2004;
+    readonly AUTH_REQUIRED: 1000;
+    readonly AUTH_FAILED: 1001;
+    readonly TOKEN_EXPIRED: 1002;
+    readonly PERMISSION_DENIED: 1003;
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+};
+/** Protocol version */
+declare const PROTOCOL_VERSION: ProtocolVersion;
+/**
+ * Maps methods to required capabilities.
+ * Empty array means no special capability required.
+ */
+declare const CAPABILITY_REQUIREMENTS: Record<string, string[]>;
+/** Check if a response is a success response */
+declare function isSuccessResponse<T>(response: MAPResponse<T>): response is MAPResponseSuccess<T>;
+/** Check if an address is a direct address */
+declare function isDirectAddress(address: Address): address is DirectAddress;
+/** Check if an address is a federated address */
+declare function isFederatedAddress(address: Address): address is FederatedAddress;
+/** Check if an address is a scope address */
+declare function isScopeAddress(address: Address): address is ScopeAddress;
+/** Check if an address is a broadcast address */
+declare function isBroadcastAddress(address: Address): address is BroadcastAddress;
+/** Check if an address is a hierarchical address */
+declare function isHierarchicalAddress(address: Address): address is HierarchicalAddress;
+
+/**
+ * Stream utilities for MAP protocol transport
+ *
+ * Provides helpers for converting byte streams to/from MAP message streams.
+ */
+
+/** Any MAP message type */
+type AnyMessage = MAPRequest | MAPResponse | MAPNotification | Record<string, unknown>;
+/**
+ * Bidirectional message stream interface.
+ * This is the transport abstraction that connection classes use.
+ */
+interface Stream {
+    writable: WritableStream<AnyMessage>;
+    readable: ReadableStream<AnyMessage>;
+}
+/**
+ * Converts raw byte streams to newline-delimited JSON message streams.
+ *
+ * This is the primary transport adapter - works with any byte stream
+ * (stdio, TCP socket, etc.)
+ *
+ * @param readable - Input byte stream
+ * @param writable - Output byte stream
+ * @returns Stream interface for MAP messages
+ */
+declare function ndJsonStream(readable: ReadableStream<Uint8Array>, writable: WritableStream<Uint8Array>): Stream;
+/**
+ * Wraps a WebSocket in a Stream interface.
+ *
+ * @param ws - WebSocket instance (must be open or will wait for open)
+ * @returns Stream interface for MAP messages
+ */
+declare function websocketStream(ws: WebSocket): Stream;
+/**
+ * Creates a pair of connected in-memory streams for testing.
+ *
+ * Messages written to one stream's writable appear on the other's readable.
+ *
+ * @returns Tuple of [clientStream, serverStream]
+ */
+declare function createStreamPair(): [Stream, Stream];
+
+/**
+ * Subscription class for MAP event streams
+ *
+ * Provides both AsyncIterable and event emitter patterns for consuming events.
+ * Includes automatic deduplication based on eventId when provided by the server.
+ */
+
+/**
+ * Event handler callback type
+ */
+type EventHandler = (event: Event) => void;
+/**
+ * Subscription options
+ */
+interface SubscriptionOptions {
+    /** Filter for events */
+    filter?: SubscriptionFilter;
+    /** Buffer size for events before backpressure */
+    bufferSize?: number;
+    /**
+     * Maximum number of eventIds to track for deduplication.
+     * Older eventIds are evicted when this limit is reached.
+     * Default: 10000
+     */
+    maxSeenEventIds?: number;
+}
+/**
+ * Subscription to MAP events.
+ *
+ * Supports both async iteration and event handler patterns:
+ *
+ * ```typescript
+ * // Async iteration
+ * for await (const event of subscription) {
+ *   console.log(event);
+ * }
+ *
+ * // Event handler
+ * subscription.on('event', (event) => console.log(event));
+ * ```
+ *
+ * ## Deduplication
+ *
+ * When the server provides `eventId` in the notification params,
+ * the subscription automatically deduplicates events. This handles
+ * scenarios like:
+ * - Network retries delivering the same event twice
+ * - Reconnection replay overlapping with already-received events
+ *
+ * If `eventId` is not provided, deduplication is skipped.
+ *
+ * ## Pause/Resume
+ *
+ * You can pause event delivery from the async iterator while still
+ * buffering events:
+ *
+ * ```typescript
+ * subscription.pause();
+ * // Events are buffered but not yielded
+ * subscription.resume();
+ * // Buffered events are now yielded
+ * ```
+ *
+ * ## Overflow Handling
+ *
+ * When the buffer is full, events are dropped and overflow handlers
+ * are notified:
+ *
+ * ```typescript
+ * subscription.on('overflow', (info) => {
+ *   console.log(`Dropped ${info.eventsDropped} events`);
+ * });
+ * ```
+ */
+declare class Subscription implements AsyncIterable<Event> {
+    #private;
+    readonly id: SubscriptionId;
+    readonly filter?: SubscriptionFilter;
+    constructor(id: SubscriptionId, unsubscribe: () => Promise<void>, options?: SubscriptionOptions, sendAck?: (params: SubscriptionAckParams) => void);
+    /**
+     * Current subscription state
+     */
+    get state(): SubscriptionState;
+    /**
+     * Whether the subscription is closed
+     */
+    get isClosed(): boolean;
+    /**
+     * Whether the subscription is paused
+     */
+    get isPaused(): boolean;
+    /**
+     * Last received sequence number (for ordering verification)
+     */
+    get lastSequenceNumber(): number;
+    /**
+     * Last received eventId (for replay positioning)
+     */
+    get lastEventId(): string | undefined;
+    /**
+     * Last received server timestamp
+     */
+    get lastTimestamp(): number | undefined;
+    /**
+     * Number of events currently buffered
+     */
+    get bufferedCount(): number;
+    /**
+     * Number of eventIds being tracked for deduplication
+     */
+    get trackedEventIdCount(): number;
+    /**
+     * Total number of events dropped due to buffer overflow
+     */
+    get totalDropped(): number;
+    /**
+     * Whether the server supports acknowledgments
+     */
+    get supportsAck(): boolean;
+    /**
+     * Pause event delivery from the async iterator.
+     * Events are still buffered but not yielded until resume() is called.
+     * Event handlers (on('event', ...)) still receive events while paused.
+     */
+    pause(): void;
+    /**
+     * Resume event delivery from the async iterator.
+     * Any events buffered during pause will be yielded.
+     */
+    resume(): void;
+    /**
+     * Acknowledge events up to a sequence number.
+     * No-op if server doesn't support acks.
+     *
+     * @param upToSequence - Acknowledge all events up to and including this sequence.
+     *                       If omitted, acknowledges up to lastSequenceNumber.
+     */
+    ack(upToSequence?: number): void;
+    /**
+     * Register an event or overflow handler
+     */
+    on(type: 'event', handler: EventHandler): this;
+    on(type: 'overflow', handler: OverflowHandler): this;
+    /**
+     * Remove an event or overflow handler
+     */
+    off(type: 'event', handler: EventHandler): this;
+    off(type: 'overflow', handler: OverflowHandler): this;
+    /**
+     * Register a one-time event handler
+     */
+    once(type: 'event', handler: EventHandler): this;
+    /**
+     * Unsubscribe and close the subscription
+     */
+    unsubscribe(): Promise<void>;
+    /**
+     * Set whether server supports acknowledgments.
+     * Called by connection after capability negotiation.
+     * @internal
+     */
+    _setServerSupportsAck(supports: boolean): void;
+    /**
+     * Push an event to the subscription (called by connection)
+     * @internal
+     */
+    _pushEvent(params: EventNotificationParams): void;
+    /**
+     * Mark the subscription as closed (called by connection)
+     * @internal
+     */
+    _close(): void;
+    /**
+     * Async iterator implementation
+     */
+    [Symbol.asyncIterator](): AsyncIterator<Event>;
+}
+/**
+ * Create a subscription instance
+ * @internal
+ */
+declare function createSubscription(id: SubscriptionId, unsubscribe: () => Promise<void>, options?: SubscriptionOptions, sendAck?: (params: SubscriptionAckParams) => void): Subscription;
+
+/**
+ * Base connection class for MAP protocol
+ *
+ * Handles JSON-RPC message correlation, request/response matching,
+ * and connection lifecycle management.
+ */
+
+/**
+ * Handler for incoming requests
+ */
+type RequestHandler = (method: string, params: unknown) => Promise<unknown>;
+/**
+ * Handler for incoming notifications
+ */
+type NotificationHandler = (method: string, params: unknown) => Promise<void>;
+/**
+ * Connection state for tracking lifecycle
+ */
+type ConnectionState = 'initial' | 'connecting' | 'connected' | 'reconnecting' | 'closed';
+/**
+ * Handler for connection state changes
+ */
+type StateChangeHandler = (newState: ConnectionState, oldState: ConnectionState) => void;
+/**
+ * Options for base connection
+ */
+interface BaseConnectionOptions {
+    /** Default timeout for requests in milliseconds */
+    defaultTimeout?: number;
+}
+/**
+ * Base connection class providing JSON-RPC message handling.
+ *
+ * This class is used internally by the role-specific connection classes
+ * (ClientConnection, AgentConnection, etc.)
+ */
+declare class BaseConnection {
+    #private;
+    constructor(stream: Stream, options?: BaseConnectionOptions);
+    /**
+     * AbortSignal that triggers when the connection closes.
+     * Useful for cancelling operations tied to this connection.
+     */
+    get signal(): AbortSignal;
+    /**
+     * Promise that resolves when the connection is closed.
+     */
+    get closed(): Promise<void>;
+    /**
+     * Whether the connection is closed
+     */
+    get isClosed(): boolean;
+    /**
+     * Set the handler for incoming requests
+     */
+    setRequestHandler(handler: RequestHandler): void;
+    /**
+     * Set the handler for incoming notifications
+     */
+    setNotificationHandler(handler: NotificationHandler): void;
+    /**
+     * Current connection state
+     */
+    get state(): ConnectionState;
+    /**
+     * Register a handler for state changes.
+     *
+     * @param handler - Function called when state changes
+     * @returns Unsubscribe function to remove the handler
+     */
+    onStateChange(handler: StateChangeHandler): () => void;
+    /**
+     * Transition to a new state and notify handlers.
+     * @internal
+     */
+    _transitionTo(newState: ConnectionState): void;
+    /**
+     * Reconnect with a new stream.
+     *
+     * This method is used by role-specific connections to replace the
+     * underlying transport after a disconnect.
+     *
+     * @param newStream - The new stream to use
+     * @throws If the connection is permanently closed
+     */
+    reconnect(newStream: Stream): Promise<void>;
+    /**
+     * Send a request and wait for response
+     */
+    sendRequest<TParams, TResult>(method: string, params?: TParams, options?: {
+        timeout?: number;
+    }): Promise<TResult>;
+    /**
+     * Send a notification (no response expected)
+     */
+    sendNotification<TParams>(method: string, params?: TParams): Promise<void>;
+    /**
+     * Send a response to a request
+     */
+    sendResponse<TResult>(id: RequestId, result: TResult): Promise<void>;
+    /**
+     * Send an error response to a request
+     */
+    sendErrorResponse(id: RequestId, error: MAPError): Promise<void>;
+    /**
+     * Close the connection
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * Client connection for MAP protocol
+ *
+ * Used by clients to connect to a MAP system, query agents,
+ * subscribe to events, and send messages.
+ */
+
+/**
+ * Options for automatic reconnection
+ */
+interface ReconnectionOptions {
+    /** Enable automatic reconnection (default: false) */
+    enabled: boolean;
+    /** Maximum number of retry attempts (default: 10) */
+    maxRetries?: number;
+    /** Initial delay in milliseconds (default: 1000) */
+    baseDelayMs?: number;
+    /** Maximum delay in milliseconds (default: 30000) */
+    maxDelayMs?: number;
+    /** Add jitter to delays (default: true) */
+    jitter?: boolean;
+    /** Restore subscriptions after reconnect (default: true) */
+    restoreSubscriptions?: boolean;
+    /** Replay missed events on restore (default: true) */
+    replayOnRestore?: boolean;
+    /** Maximum events to replay per subscription (default: 1000) */
+    maxReplayEventsPerSubscription?: number;
+}
+/**
+ * Reconnection event types
+ */
+type ReconnectionEventType = 'disconnected' | 'reconnecting' | 'reconnected' | 'reconnectFailed' | 'subscriptionRestored' | 'subscriptionRestoreFailed';
+/**
+ * Handler for reconnection events
+ */
+type ReconnectionEventHandler = (event: {
+    type: ReconnectionEventType;
+    attempt?: number;
+    delay?: number;
+    error?: Error;
+    subscriptionId?: SubscriptionId;
+    newSubscriptionId?: SubscriptionId;
+}) => void;
+/**
+ * Options for client connection
+ */
+interface ClientConnectionOptions extends BaseConnectionOptions {
+    /** Client name for identification */
+    name?: string;
+    /** Client capabilities */
+    capabilities?: ParticipantCapabilities;
+    /** Factory to create new stream for reconnection */
+    createStream?: () => Promise<Stream>;
+    /** Reconnection options */
+    reconnection?: ReconnectionOptions;
+}
+/**
+ * Client connection to a MAP system.
+ *
+ * Provides methods for:
+ * - Querying agents and structure
+ * - Subscribing to events
+ * - Sending messages to agents
+ * - (With permissions) Steering agents
+ */
+declare class ClientConnection {
+    #private;
+    constructor(stream: Stream, options?: ClientConnectionOptions);
+    /**
+     * Connect to the MAP system
+     */
+    connect(options?: {
+        sessionId?: SessionId;
+        auth?: {
+            method: 'bearer' | 'api-key' | 'mtls' | 'none';
+            token?: string;
+        };
+    }): Promise<ConnectResponseResult>;
+    /**
+     * Disconnect from the MAP system
+     */
+    disconnect(reason?: string): Promise<void>;
+    /**
+     * Whether the client is connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Current session ID
+     */
+    get sessionId(): SessionId | null;
+    /**
+     * Server capabilities
+     */
+    get serverCapabilities(): ParticipantCapabilities | null;
+    /**
+     * AbortSignal that triggers when the connection closes
+     */
+    get signal(): AbortSignal;
+    /**
+     * Promise that resolves when the connection closes
+     */
+    get closed(): Promise<void>;
+    /**
+     * List available sessions
+     */
+    listSessions(): Promise<SessionListResponseResult>;
+    /**
+     * Load an existing session
+     */
+    loadSession(sessionId: SessionId): Promise<SessionLoadResponseResult>;
+    /**
+     * Close the current session
+     */
+    closeSession(sessionId?: SessionId): Promise<SessionCloseResponseResult>;
+    /**
+     * List agents with optional filters
+     */
+    listAgents(options?: AgentsListRequestParams): Promise<AgentsListResponseResult>;
+    /**
+     * Get a single agent by ID
+     */
+    getAgent(agentId: AgentId, options?: {
+        include?: {
+            children?: boolean;
+            descendants?: boolean;
+        };
+    }): Promise<AgentsGetResponseResult>;
+    /**
+     * Get the agent structure/hierarchy graph
+     */
+    getStructureGraph(options?: StructureGraphRequestParams): Promise<StructureGraphResponseResult>;
+    /**
+     * List scopes
+     */
+    listScopes(options?: ScopesListRequestParams): Promise<ScopesListResponseResult>;
+    /**
+     * Get a single scope by ID
+     */
+    getScope(scopeId: ScopeId): Promise<Scope>;
+    /**
+     * List members of a scope
+     */
+    getScopeMembers(scopeId: ScopeId, options?: Omit<ScopesMembersRequestParams, 'scopeId'>): Promise<ScopesMembersResponseResult>;
+    /**
+     * Send a message to an address
+     */
+    send(to: Address, payload?: unknown, meta?: MessageMeta): Promise<SendResponseResult>;
+    /**
+     * Send a message to a specific agent
+     */
+    sendToAgent(agentId: AgentId, payload?: unknown, meta?: MessageMeta): Promise<SendResponseResult>;
+    /**
+     * Send a message to all agents in a scope
+     */
+    sendToScope(scopeId: ScopeId, payload?: unknown, meta?: MessageMeta): Promise<SendResponseResult>;
+    /**
+     * Send a message to agents with a specific role
+     */
+    sendToRole(role: string, payload?: unknown, meta?: MessageMeta, withinScope?: ScopeId): Promise<SendResponseResult>;
+    /**
+     * Broadcast a message to all agents
+     */
+    broadcast(payload?: unknown, meta?: MessageMeta): Promise<SendResponseResult>;
+    /**
+     * Send a request and wait for a correlated response
+     *
+     * This is a higher-level pattern for request/response messaging.
+     * A correlationId is automatically generated.
+     */
+    request<T = unknown>(to: Address, payload?: unknown, options?: {
+        timeout?: number;
+        meta?: MessageMeta;
+    }): Promise<Message<T>>;
+    /**
+     * Subscribe to events
+     */
+    subscribe(filter?: SubscriptionFilter): Promise<Subscription>;
+    /**
+     * Unsubscribe from events
+     */
+    unsubscribe(subscriptionId: SubscriptionId): Promise<void>;
+    /**
+     * Replay historical events.
+     *
+     * Uses keyset pagination - pass the last eventId from the previous
+     * response to get the next page.
+     *
+     * @example
+     * ```typescript
+     * // Replay all events from the last hour
+     * const result = await client.replay({
+     *   fromTimestamp: Date.now() - 3600000,
+     *   filter: { eventTypes: ['agent.registered'] },
+     *   limit: 100
+     * });
+     *
+     * // Paginate through results
+     * let afterEventId: string | undefined;
+     * do {
+     *   const page = await client.replay({ afterEventId, limit: 100 });
+     *   for (const item of page.events) {
+     *     console.log(item.eventId, item.event);
+     *   }
+     *   afterEventId = page.events.at(-1)?.eventId;
+     * } while (page.hasMore);
+     * ```
+     */
+    replay(params?: ReplayRequestParams): Promise<ReplayResponseResult>;
+    /**
+     * Replay all events matching filter, handling pagination automatically.
+     *
+     * Returns an async generator for streaming through all results.
+     *
+     * @example
+     * ```typescript
+     * for await (const item of client.replayAll({
+     *   filter: { eventTypes: ['agent.registered'] }
+     * })) {
+     *   console.log(item.eventId, item.event);
+     * }
+     * ```
+     */
+    replayAll(params?: Omit<ReplayRequestParams, 'afterEventId'>): AsyncGenerator<ReplayedEvent>;
+    /**
+     * Inject context into a running agent
+     */
+    inject(agentId: AgentId, content: unknown, delivery?: 'interrupt' | 'queue' | 'best-effort'): Promise<InjectResponseResult>;
+    /**
+     * Request an agent to stop
+     */
+    stopAgent(agentId: AgentId, options?: {
+        reason?: string;
+        force?: boolean;
+    }): Promise<{
+        stopping: boolean;
+        agent?: Agent;
+    }>;
+    /**
+     * Suspend an agent
+     */
+    suspendAgent(agentId: AgentId, reason?: string): Promise<{
+        suspended: boolean;
+        agent?: Agent;
+    }>;
+    /**
+     * Resume a suspended agent
+     */
+    resumeAgent(agentId: AgentId): Promise<{
+        resumed: boolean;
+        agent?: Agent;
+    }>;
+    /**
+     * Current connection state
+     */
+    get state(): ConnectionState;
+    /**
+     * Whether the connection is currently reconnecting
+     */
+    get isReconnecting(): boolean;
+    /**
+     * Register a handler for reconnection events.
+     *
+     * @param handler - Function called when reconnection events occur
+     * @returns Unsubscribe function to remove the handler
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = client.onReconnection((event) => {
+     *   switch (event.type) {
+     *     case 'disconnected':
+     *       console.log('Connection lost');
+     *       break;
+     *     case 'reconnecting':
+     *       console.log(`Reconnecting, attempt ${event.attempt}`);
+     *       break;
+     *     case 'reconnected':
+     *       console.log('Reconnected successfully');
+     *       break;
+     *     case 'reconnectFailed':
+     *       console.log('Failed to reconnect:', event.error);
+     *       break;
+     *   }
+     * });
+     * ```
+     */
+    onReconnection(handler: ReconnectionEventHandler): () => void;
+    /**
+     * Register a handler for connection state changes.
+     *
+     * @param handler - Function called when state changes
+     * @returns Unsubscribe function to remove the handler
+     */
+    onStateChange(handler: (newState: ConnectionState, oldState: ConnectionState) => void): () => void;
+}
+
+/**
+ * Agent connection for MAP protocol
+ *
+ * Used by agents to connect to a MAP system, receive messages,
+ * update state, spawn children, and communicate with peers.
+ */
+
+/**
+ * Handler for incoming messages addressed to this agent
+ */
+type MessageHandler = (message: Message) => void | Promise<void>;
+/**
+ * Options for automatic reconnection
+ */
+interface AgentReconnectionOptions {
+    /** Enable automatic reconnection (default: false) */
+    enabled: boolean;
+    /** Maximum number of retry attempts (default: 10) */
+    maxRetries?: number;
+    /** Initial delay in milliseconds (default: 1000) */
+    baseDelayMs?: number;
+    /** Maximum delay in milliseconds (default: 30000) */
+    maxDelayMs?: number;
+    /** Add jitter to delays (default: true) */
+    jitter?: boolean;
+    /** Restore scope memberships after reconnect (default: true) */
+    restoreScopeMemberships?: boolean;
+}
+/**
+ * Agent reconnection event types
+ */
+type AgentReconnectionEventType = 'disconnected' | 'reconnecting' | 'reconnected' | 'reconnectFailed';
+/**
+ * Handler for reconnection events
+ */
+type AgentReconnectionEventHandler = (event: {
+    type: AgentReconnectionEventType;
+    attempt?: number;
+    delay?: number;
+    error?: Error;
+}) => void;
+/**
+ * Options for agent connection
+ */
+interface AgentConnectionOptions extends BaseConnectionOptions {
+    /** Agent name */
+    name?: string;
+    /** Agent role */
+    role?: string;
+    /** Agent capabilities */
+    capabilities?: ParticipantCapabilities;
+    /** Agent visibility */
+    visibility?: AgentVisibility;
+    /** Parent agent ID (if this is a child agent) */
+    parent?: AgentId;
+    /** Initial scopes to join */
+    scopes?: ScopeId[];
+    /** Factory to create new stream for reconnection */
+    createStream?: () => Promise<Stream>;
+    /** Reconnection options */
+    reconnection?: AgentReconnectionOptions;
+}
+/**
+ * Agent connection to a MAP system.
+ *
+ * Provides methods for:
+ * - Registering self with the system
+ * - Receiving and handling messages
+ * - Sending messages to other agents
+ * - Spawning child agents
+ * - Updating own state
+ * - Managing scope memberships
+ */
+declare class AgentConnection {
+    #private;
+    constructor(stream: Stream, options?: AgentConnectionOptions);
+    /**
+     * Connect and register with the MAP system
+     */
+    connect(options?: {
+        agentId?: AgentId;
+        auth?: {
+            method: 'bearer' | 'api-key' | 'mtls' | 'none';
+            token?: string;
+        };
+    }): Promise<{
+        connection: ConnectResponseResult;
+        agent: Agent;
+    }>;
+    /**
+     * Disconnect from the MAP system
+     */
+    disconnect(reason?: string): Promise<void>;
+    /**
+     * Whether the agent is connected
+     */
+    get isConnected(): boolean;
+    /**
+     * This agent's ID
+     */
+    get agentId(): AgentId | null;
+    /**
+     * Current session ID
+     */
+    get sessionId(): SessionId | null;
+    /**
+     * Server capabilities
+     */
+    get serverCapabilities(): ParticipantCapabilities | null;
+    /**
+     * Current agent state
+     */
+    get state(): AgentState;
+    /**
+     * AbortSignal that triggers when the connection closes
+     */
+    get signal(): AbortSignal;
+    /**
+     * Promise that resolves when the connection closes
+     */
+    get closed(): Promise<void>;
+    /**
+     * Register a handler for incoming messages
+     */
+    onMessage(handler: MessageHandler): this;
+    /**
+     * Remove a message handler
+     */
+    offMessage(handler: MessageHandler): this;
+    /**
+     * Update this agent's state
+     */
+    updateState(state: AgentState): Promise<Agent>;
+    /**
+     * Update this agent's metadata
+     */
+    updateMetadata(metadata: Record<string, unknown>): Promise<Agent>;
+    /**
+     * Mark this agent as busy
+     */
+    busy(): Promise<Agent>;
+    /**
+     * Mark this agent as idle
+     */
+    idle(): Promise<Agent>;
+    /**
+     * Mark this agent as done/stopped
+     */
+    done(result?: {
+        exitCode?: number;
+        exitReason?: string;
+    }): Promise<void>;
+    /**
+     * Spawn a child agent
+     */
+    spawn(options: {
+        agentId?: AgentId;
+        name?: string;
+        role?: string;
+        visibility?: AgentVisibility;
+        capabilities?: ParticipantCapabilities;
+        scopes?: ScopeId[];
+        initialMessage?: Message;
+        metadata?: Record<string, unknown>;
+    }): Promise<AgentsSpawnResponseResult>;
+    /**
+     * Send a message to an address
+     */
+    send(to: Address, payload?: unknown, meta?: MessageMeta): Promise<SendResponseResult>;
+    /**
+     * Send a message to the parent agent
+     */
+    sendToParent(payload?: unknown, meta?: MessageMeta): Promise<SendResponseResult>;
+    /**
+     * Send a message to child agents
+     */
+    sendToChildren(payload?: unknown, meta?: MessageMeta): Promise<SendResponseResult>;
+    /**
+     * Send a message to a specific agent
+     */
+    sendToAgent(agentId: AgentId, payload?: unknown, meta?: MessageMeta): Promise<SendResponseResult>;
+    /**
+     * Send a message to all agents in a scope
+     */
+    sendToScope(scopeId: ScopeId, payload?: unknown, meta?: MessageMeta): Promise<SendResponseResult>;
+    /**
+     * Send a message to sibling agents
+     */
+    sendToSiblings(payload?: unknown, meta?: MessageMeta): Promise<SendResponseResult>;
+    /**
+     * Reply to a message (uses correlationId from original)
+     */
+    reply(originalMessage: Message, payload?: unknown, meta?: MessageMeta): Promise<SendResponseResult>;
+    /**
+     * Create a new scope
+     */
+    createScope(options: ScopesCreateRequestParams): Promise<Scope>;
+    /**
+     * Join a scope
+     */
+    joinScope(scopeId: ScopeId): Promise<ScopesJoinResponseResult>;
+    /**
+     * Leave a scope
+     */
+    leaveScope(scopeId: ScopeId): Promise<ScopesLeaveResponseResult>;
+    /**
+     * Subscribe to events
+     */
+    subscribe(filter?: SubscriptionFilter): Promise<Subscription>;
+    /**
+     * Unsubscribe from events
+     */
+    unsubscribe(subscriptionId: SubscriptionId): Promise<void>;
+    /**
+     * Current connection state
+     */
+    get connectionState(): ConnectionState;
+    /**
+     * Whether the connection is currently reconnecting
+     */
+    get isReconnecting(): boolean;
+    /**
+     * Register a handler for reconnection events.
+     *
+     * @param handler - Function called when reconnection events occur
+     * @returns Unsubscribe function to remove the handler
+     */
+    onReconnection(handler: AgentReconnectionEventHandler): () => void;
+    /**
+     * Register a handler for connection state changes.
+     *
+     * @param handler - Function called when state changes
+     * @returns Unsubscribe function to remove the handler
+     */
+    onStateChange(handler: (newState: ConnectionState, oldState: ConnectionState) => void): () => void;
+}
+
+/**
+ * Permission utilities for MAP SDK
+ *
+ * Provides building blocks for implementing the 4-layer permission model:
+ * - Layer 1: System configuration (what's exposed at all)
+ * - Layer 2: Client permissions (what can this client do)
+ * - Layer 3: Scope permissions (what's allowed in this scope)
+ * - Layer 4: Agent permissions (what can this agent do)
+ *
+ * These utilities are opt-in building blocks for router implementations.
+ * They provide the logic for permission checks but don't enforce them.
+ */
+
+/**
+ * System-level exposure configuration.
+ * Controls what entities are visible to participants at all.
+ */
+interface SystemExposure {
+    agents?: {
+        /** Whether agents are public by default (default: true) */
+        publicByDefault?: boolean;
+        /** Glob patterns for agents that are always public */
+        publicAgents?: string[];
+        /** Glob patterns for agents that are always hidden (takes precedence) */
+        hiddenAgents?: string[];
+    };
+    events?: {
+        /** Event types that are exposed (whitelist, if provided) */
+        exposedTypes?: EventType[];
+        /** Event types that are always hidden (blacklist) */
+        hiddenTypes?: EventType[];
+    };
+    scopes?: {
+        /** Whether scopes are public by default (default: true) */
+        publicByDefault?: boolean;
+        /** Glob patterns for scopes that are always public */
+        publicScopes?: string[];
+        /** Glob patterns for scopes that are always hidden (takes precedence) */
+        hiddenScopes?: string[];
+    };
+}
+/**
+ * Full system configuration for permissions
+ */
+interface PermissionSystemConfig {
+    /** What entities are exposed to participants */
+    exposure?: SystemExposure;
+    /** Resource limits */
+    limits?: {
+        maxConnections?: number;
+        maxConnectionsPerClient?: number;
+        maxSubscriptionsPerConnection?: number;
+        maxAgentsPerClient?: number;
+    };
+}
+/**
+ * Represents a connected participant for permission checks
+ */
+interface PermissionParticipant {
+    /** Participant ID */
+    id: string;
+    /** Participant type */
+    type: ParticipantType;
+    /** Granted capabilities */
+    capabilities: ParticipantCapabilities;
+}
+/**
+ * Context for permission checks
+ */
+interface PermissionContext {
+    /** System-wide configuration */
+    system: PermissionSystemConfig;
+    /** The participant performing the action */
+    participant: PermissionParticipant;
+    /** Agent IDs owned by this participant */
+    ownedAgentIds?: AgentId[];
+    /** Scope membership: scopeId -> agent IDs that are members */
+    scopeMembership?: Map<ScopeId, AgentId[]>;
+}
+/**
+ * Action being performed for permission checking
+ */
+interface PermissionAction {
+    /** Action category */
+    type: 'query' | 'message' | 'lifecycle' | 'scope' | 'subscribe';
+    /** Wire method name (e.g., 'map/agents/list') */
+    method: string;
+    /** Target of the action */
+    target?: {
+        agentId?: AgentId;
+        scopeId?: ScopeId;
+        eventTypes?: EventType[];
+    };
+}
+/**
+ * Result of a permission check
+ */
+interface PermissionResult {
+    /** Whether the action is allowed */
+    allowed: boolean;
+    /** Reason for denial (if denied) */
+    reason?: string;
+    /** Which layer denied the action (if denied) */
+    layer?: 1 | 2 | 3 | 4;
+}
+/**
+ * Check if an agent is exposed by system configuration.
+ *
+ * Hidden patterns take precedence over public patterns.
+ * If no configuration, agents are exposed by default.
+ *
+ * @param exposure - System exposure configuration
+ * @param agentId - Agent ID to check
+ * @returns true if the agent is exposed
+ */
+declare function isAgentExposed(exposure: SystemExposure | undefined, agentId: AgentId): boolean;
+/**
+ * Check if an event type is exposed by system configuration.
+ *
+ * Hidden types take precedence. If a whitelist is provided,
+ * only those types are exposed.
+ *
+ * @param exposure - System exposure configuration
+ * @param eventType - Event type to check
+ * @returns true if the event type is exposed
+ */
+declare function isEventTypeExposed(exposure: SystemExposure | undefined, eventType: EventType): boolean;
+/**
+ * Check if a scope is exposed by system configuration.
+ *
+ * Hidden patterns take precedence over public patterns.
+ *
+ * @param exposure - System exposure configuration
+ * @param scopeId - Scope ID to check
+ * @returns true if the scope is exposed
+ */
+declare function isScopeExposed(exposure: SystemExposure | undefined, scopeId: ScopeId): boolean;
+/**
+ * Check if a participant has a specific capability.
+ *
+ * @param capabilities - Participant's capabilities
+ * @param path - Capability path like 'observation.canQuery'
+ * @returns true if the capability is granted
+ *
+ * @example
+ * ```typescript
+ * if (hasCapability(participant.capabilities, 'lifecycle.canSpawn')) {
+ *   // Can spawn agents
+ * }
+ * ```
+ */
+declare function hasCapability(capabilities: ParticipantCapabilities, path: string): boolean;
+/**
+ * Check if a participant can perform a method based on capabilities.
+ *
+ * @param method - Wire method name (e.g., 'map/agents/list')
+ * @param capabilities - Participant's capabilities
+ * @returns true if all required capabilities are present
+ */
+declare function canPerformMethod(method: string, capabilities: ParticipantCapabilities): boolean;
+
+/**
+ * Check if a participant can see a scope.
+ *
+ * @param scope - The scope to check
+ * @param participant - The participant
+ * @param memberAgentIds - Agent IDs owned by participant that are scope members
+ * @returns true if the participant can see the scope
+ */
+declare function canSeeScope(scope: Scope, participant: PermissionParticipant, memberAgentIds?: AgentId[]): boolean;
+/**
+ * Check if a participant can send messages to a scope.
+ *
+ * @param scope - The scope to check
+ * @param participant - The participant
+ * @param memberAgentIds - Agent IDs owned by participant that are scope members
+ * @returns true if the participant can send to the scope
+ */
+declare function canSendToScope(scope: Scope, participant: PermissionParticipant, memberAgentIds?: AgentId[]): boolean;
+/**
+ * Check if a participant can join a scope.
+ *
+ * @param scope - The scope to check
+ * @param participantType - Type of the participant
+ * @param agentRole - Role of the agent trying to join (for role-based policies)
+ * @returns true if the participant can join the scope
+ */
+declare function canJoinScope(scope: Scope, participantType: ParticipantType, agentRole?: string): boolean;
+/**
+ * Check if a participant can see an agent.
+ *
+ * @param agent - The agent to check
+ * @param participant - The participant
+ * @param ownedAgentIds - Agent IDs owned by this participant
+ * @returns true if the participant can see the agent
+ */
+declare function canSeeAgent(agent: Agent, participant: PermissionParticipant, ownedAgentIds?: AgentId[]): boolean;
+/**
+ * Check if a participant can send messages to an agent.
+ *
+ * @param agent - Target agent
+ * @param participant - The participant
+ * @param ownedAgentIds - Agent IDs owned by this participant
+ * @returns true if the participant can message the agent
+ */
+declare function canMessageAgent(agent: Agent, participant: PermissionParticipant, ownedAgentIds?: AgentId[]): boolean;
+/**
+ * Check if a participant can control an agent (stop, suspend, etc.).
+ *
+ * @param agent - Target agent
+ * @param participant - The participant
+ * @param ownedAgentIds - Agent IDs owned by this participant
+ * @returns true if the participant can control the agent
+ */
+declare function canControlAgent(agent: Agent, participant: PermissionParticipant, ownedAgentIds?: AgentId[]): boolean;
+/**
+ * Check if an action is permitted across all 4 layers.
+ *
+ * This is the main entry point for comprehensive permission checking.
+ * It evaluates each layer in order and returns the first denial or success.
+ *
+ * @param context - Permission context with system config and participant info
+ * @param action - The action to check
+ * @returns Permission result with allowed status, reason, and layer
+ *
+ * @example
+ * ```typescript
+ * const result = canPerformAction(
+ *   {
+ *     system: { exposure: { agents: { hiddenAgents: ['internal-*'] } } },
+ *     participant: { id: 'client-1', type: 'client', capabilities },
+ *     ownedAgentIds: ['agent-1'],
+ *   },
+ *   {
+ *     type: 'query',
+ *     method: 'map/agents/get',
+ *     target: { agentId: 'internal-worker' },
+ *   }
+ * );
+ *
+ * if (!result.allowed) {
+ *   console.log(`Denied at layer ${result.layer}: ${result.reason}`);
+ * }
+ * ```
+ */
+declare function canPerformAction(context: PermissionContext, action: PermissionAction): PermissionResult;
+/**
+ * Filter agents to only those visible to the participant.
+ *
+ * Applies both Layer 1 (system exposure) and Layer 4 (agent visibility).
+ *
+ * @param agents - Agents to filter
+ * @param context - Permission context
+ * @returns Filtered list of visible agents
+ */
+declare function filterVisibleAgents(agents: Agent[], context: PermissionContext): Agent[];
+/**
+ * Filter scopes to only those visible to the participant.
+ *
+ * Applies both Layer 1 (system exposure) and Layer 3 (scope visibility).
+ *
+ * @param scopes - Scopes to filter
+ * @param context - Permission context
+ * @returns Filtered list of visible scopes
+ */
+declare function filterVisibleScopes(scopes: Scope[], context: PermissionContext): Scope[];
+/**
+ * Filter events to only those visible to the participant.
+ *
+ * Applies Layer 1 (system exposure) for event types.
+ *
+ * @param events - Events to filter
+ * @param context - Permission context
+ * @returns Filtered list of visible events
+ */
+declare function filterVisibleEvents(events: Event[], context: PermissionContext): Event[];
+/**
+ * Deep merge two permission objects.
+ * Second object's fields override first at the leaf level.
+ *
+ * @param base - Base permissions
+ * @param override - Override permissions (partial)
+ * @returns Merged permissions
+ */
+declare function deepMergePermissions(base: AgentPermissions, override: Partial<AgentPermissions>): AgentPermissions;
+/**
+ * Map legacy AgentVisibility to AgentVisibilityRule.
+ *
+ * @param visibility - Legacy visibility value
+ * @returns Equivalent visibility rule
+ */
+declare function mapVisibilityToRule(visibility: AgentVisibility): AgentVisibilityRule;
+/**
+ * Default agent permission configuration.
+ * Used when no configuration is provided.
+ */
+declare const DEFAULT_AGENT_PERMISSION_CONFIG: AgentPermissionConfig;
+/**
+ * Resolve effective permissions for an agent.
+ *
+ * Resolution order:
+ * 1. Start with system default permissions
+ * 2. If agent has a role, deep merge role permissions
+ * 3. Deep merge agent's permissionOverrides
+ * 4. (Backwards compat) Map legacy visibility field if no override
+ *
+ * @param agent - The agent to resolve permissions for
+ * @param config - System permission configuration
+ * @returns Resolved effective permissions
+ *
+ * @example
+ * ```typescript
+ * const config: AgentPermissionConfig = {
+ *   defaultPermissions: { canSee: { agents: 'all' } },
+ *   rolePermissions: {
+ *     worker: { canSee: { agents: 'hierarchy' } },
+ *   },
+ * };
+ *
+ * const agent = { id: 'a1', role: 'worker', ownerId: 'c1', state: 'active' };
+ * const perms = resolveAgentPermissions(agent, config);
+ * // perms.canSee.agents === 'hierarchy'
+ * ```
+ */
+declare function resolveAgentPermissions(agent: Agent, config?: AgentPermissionConfig): AgentPermissions;
+/**
+ * Context for checking if an agent accepts messages from a sender.
+ */
+interface AcceptanceContext {
+    /** Type of the sender */
+    senderType: ParticipantType;
+    /** Participant ID of the sender */
+    senderId: ParticipantId;
+    /** If sender is an agent, its agent ID */
+    senderAgentId?: AgentId;
+    /** If sender is from a federated system, its system ID */
+    senderSystemId?: string;
+    /** Whether sender is the parent of target */
+    isParent?: boolean;
+    /** Whether sender is a child of target */
+    isChild?: boolean;
+    /** Whether sender is an ancestor of target */
+    isAncestor?: boolean;
+    /** Whether sender is a descendant of target */
+    isDescendant?: boolean;
+    /** Scope IDs that both sender and target are members of */
+    sharedScopes?: ScopeId[];
+}
+/**
+ * Check if an agent accepts messages from the given sender.
+ *
+ * Uses the agent's resolved permissions to determine if the sender
+ * is allowed based on sender type and acceptance rules.
+ *
+ * @param targetAgent - The agent that would receive the message
+ * @param context - Information about the sender
+ * @param config - System permission configuration
+ * @returns true if the agent accepts messages from this sender
+ *
+ * @example
+ * ```typescript
+ * const accepts = canAgentAcceptMessage(
+ *   targetAgent,
+ *   {
+ *     senderType: 'agent',
+ *     senderId: 'client-1',
+ *     senderAgentId: 'agent-2',
+ *     isParent: true,
+ *   },
+ *   config
+ * );
+ * ```
+ */
+declare function canAgentAcceptMessage(targetAgent: Agent, context: AcceptanceContext, config?: AgentPermissionConfig): boolean;
+/**
+ * Check if an agent can see another agent based on permissions.
+ *
+ * @param viewerAgent - The agent trying to see
+ * @param targetAgentId - ID of the agent being viewed
+ * @param context - Hierarchy and scope context
+ * @param config - System permission configuration
+ * @returns true if viewer can see target
+ */
+declare function canAgentSeeAgent(viewerAgent: Agent, targetAgentId: AgentId, context: {
+    isParent?: boolean;
+    isChild?: boolean;
+    isAncestor?: boolean;
+    isDescendant?: boolean;
+    sharedScopes?: ScopeId[];
+}, config?: AgentPermissionConfig): boolean;
+/**
+ * Check if an agent can message another agent based on permissions.
+ *
+ * @param senderAgent - The agent sending the message
+ * @param targetAgentId - ID of the target agent
+ * @param context - Hierarchy and scope context
+ * @param config - System permission configuration
+ * @returns true if sender can message target
+ */
+declare function canAgentMessageAgent(senderAgent: Agent, targetAgentId: AgentId, context: {
+    isParent?: boolean;
+    isChild?: boolean;
+    isAncestor?: boolean;
+    isDescendant?: boolean;
+    sharedScopes?: ScopeId[];
+}, config?: AgentPermissionConfig): boolean;
+
+export { type AgentMessagingRule as $, type AgentId as A, type BaseConnectionOptions as B, type ConnectResponseResult as C, type DisconnectResponseResult as D, type ErrorCategory as E, type FederationBufferConfig as F, type ScopesJoinResponseResult as G, type ScopesLeaveResponseResult as H, type ScopesListResponseResult as I, type MessageId as J, type SendResponseResult as K, type SubscriptionId as L, type MAPError as M, type SubscribeResponseResult as N, AGENT_ERROR_CODES as O, type ParticipantCapabilities as P, AUTH_ERROR_CODES as Q, type RequestId as R, type Stream as S, AUTH_METHODS as T, type UnsubscribeResponseResult as U, type AcceptanceContext as V, type AgentAcceptanceRule as W, AgentConnection as X, type AgentConnectionOptions as Y, type AgentIncludeOptions as Z, type AgentLifecycle as _, type MAPErrorData as a, type FederationAuth as a$, type AgentPermissionConfig as a0, type AgentPermissions as a1, type AgentReconnectionEventHandler as a2, type AgentReconnectionEventType as a3, type AgentReconnectionOptions as a4, type AgentRelationship as a5, type AgentRelationshipType as a6, type AgentState as a7, type AgentVisibility as a8, type AgentVisibilityRule as a9, type AuthRefreshRequestParams as aA, type AuthRefreshResponseResult as aB, BaseConnection as aC, type BroadcastAddress as aD, CAPABILITY_REQUIREMENTS as aE, CORE_METHODS as aF, type ClientAcceptanceRule as aG, ClientConnection as aH, type ClientConnectionOptions as aI, type ConnectRequest as aJ, type ConnectRequestParams as aK, type CorrelationId as aL, DEFAULT_AGENT_PERMISSION_CONFIG as aM, type DeliverySemantics as aN, type DirectAddress as aO, type DisconnectPolicy as aP, type DisconnectRequest as aQ, type DisconnectRequestParams as aR, ERROR_CODES as aS, EVENT_TYPES as aT, EXTENSION_METHODS as aU, type EventInput as aV, type EventNotification as aW, type EventNotificationParams as aX, FEDERATION_ERROR_CODES as aY, FEDERATION_METHODS as aZ, type FederatedAddress as a_, type AgentsGetRequest as aa, type AgentsGetRequestParams as ab, type AgentsListFilter as ac, type AgentsListRequest as ad, type AgentsListRequestParams as ae, type AgentsRegisterRequest as af, type AgentsRegisterRequestParams as ag, type AgentsResumeRequest as ah, type AgentsResumeRequestParams as ai, type AgentsResumeResponseResult as aj, type AgentsSpawnRequest as ak, type AgentsSpawnRequestParams as al, type AgentsStopRequest as am, type AgentsStopRequestParams as an, type AgentsStopResponseResult as ao, type AgentsSuspendRequest as ap, type AgentsSuspendRequestParams as aq, type AgentsSuspendResponseResult as ar, type AgentsUnregisterRequest as as, type AgentsUnregisterRequestParams as at, type AgentsUpdateRequest as au, type AgentsUpdateRequestParams as av, type AnyMessage as aw, type AuthMethod as ax, type AuthParams as ay, type AuthRefreshRequest as az, type FederationEnvelope as b, type ReconnectionEventType as b$, type FederationConnectRequest as b0, type FederationConnectRequestParams as b1, type FederationMetadata as b2, type FederationReplayConfig as b3, type FederationRouteRequest as b4, type FederationRouteRequestParams as b5, type GatewayReconnectionEvent as b6, type GatewayReconnectionEventHandler as b7, type GatewayReconnectionEventType as b8, type GatewayReconnectionOptions as b9, type MessageSentEventData as bA, type MessageVisibility as bB, type Meta as bC, type MultiAddress as bD, NOTIFICATION_METHODS as bE, type NotificationHandler as bF, OBSERVATION_METHODS as bG, type OverflowHandler as bH, type OverflowInfo as bI, PERMISSION_METHODS as bJ, PROTOCOL_ERROR_CODES as bK, PROTOCOL_VERSION as bL, type Participant as bM, type ParticipantAddress as bN, type PermissionAction as bO, type PermissionContext as bP, type PermissionParticipant as bQ, type PermissionResult as bR, type PermissionSystemConfig as bS, type PermissionsAgentUpdatedEventData as bT, type PermissionsClientUpdatedEventData as bU, type PermissionsUpdateRequest as bV, type PermissionsUpdateRequestParams as bW, type PermissionsUpdateResponseResult as bX, RESOURCE_ERROR_CODES as bY, ROUTING_ERROR_CODES as bZ, type ReconnectionEventHandler as b_, type GraphEdge as ba, type HierarchicalAddress as bb, type InjectDelivery as bc, type InjectDeliveryResult as bd, type InjectRequest as be, type InjectRequestParams as bf, type InjectResponseResult as bg, JSONRPC_VERSION as bh, type JoinPolicy as bi, LIFECYCLE_METHODS as bj, type MAPNotification as bk, type MAPNotificationBase as bl, type MAPRequest as bm, type MAPRequestBase as bn, type MAPResponse as bo, type MAPResponseError as bp, type MAPResponseSuccess as bq, MAP_METHODS as br, type MessageDeliveredEventData as bs, type MessageFailedEventData as bt, type MessageHandler as bu, type MessageMeta as bv, type MessageNotification as bw, type MessageNotificationParams as bx, type MessagePriority as by, type MessageRelationship as bz, type Message as c, type UnsubscribeRequestParams as c$, type ReconnectionOptions as c0, type ReplayRequest as c1, type ReplayRequestParams as c2, type ReplayResponseResult as c3, type ReplayedEvent as c4, type RequestHandler as c5, type RoleAddress as c6, SCOPE_METHODS as c7, SESSION_METHODS as c8, STATE_METHODS as c9, type SessionCloseRequest as cA, type SessionCloseRequestParams as cB, type SessionCloseResponseResult as cC, type SessionListRequest as cD, type SessionListRequestParams as cE, type SessionListResponseResult as cF, type SessionLoadRequest as cG, type SessionLoadRequestParams as cH, type SessionLoadResponseResult as cI, type StateChangeHandler as cJ, type StreamingCapabilities as cK, type StructureGraphRequest as cL, type StructureGraphRequestParams as cM, type StructureGraphResponseResult as cN, type StructureVisibilityRule as cO, type SubscribeRequest as cP, type SubscribeRequestParams as cQ, Subscription as cR, type SubscriptionAckNotification as cS, type SubscriptionAckParams as cT, type SubscriptionOptions$1 as cU, type SubscriptionState as cV, type SystemAcceptanceRule as cW, type SystemAddress as cX, type Timestamp as cY, type TransportType as cZ, type UnsubscribeRequest as c_, STEERING_METHODS as ca, STRUCTURE_METHODS as cb, type ScopeAddress as cc, type ScopeMessagingRule as cd, type ScopeVisibility as ce, type ScopeVisibilityRule as cf, type ScopesCreateRequest as cg, type ScopesCreateRequestParams as ch, type ScopesDeleteRequest as ci, type ScopesDeleteRequestParams as cj, type ScopesDeleteResponseResult as ck, type ScopesGetRequest as cl, type ScopesGetRequestParams as cm, type ScopesGetResponseResult as cn, type ScopesJoinRequest as co, type ScopesJoinRequestParams as cp, type ScopesLeaveRequest as cq, type ScopesLeaveRequestParams as cr, type ScopesListRequest as cs, type ScopesListRequestParams as ct, type ScopesMembersRequest as cu, type ScopesMembersRequestParams as cv, type ScopesMembersResponseResult as cw, type SendPolicy as cx, type SendRequest as cy, type SendRequestParams as cz, type FederationRoutingConfig as d, canAgentAcceptMessage as d0, canAgentMessageAgent as d1, canAgentSeeAgent as d2, canControlAgent as d3, canJoinScope as d4, canMessageAgent as d5, canPerformAction as d6, canPerformMethod as d7, canSeeAgent as d8, canSeeScope as d9, canSendToScope as da, createEvent as db, createStreamPair as dc, createSubscription as dd, deepMergePermissions as de, filterVisibleAgents as df, filterVisibleEvents as dg, filterVisibleScopes as dh, hasCapability as di, isAgentExposed as dj, isBroadcastAddress as dk, isDirectAddress as dl, isEventTypeExposed as dm, isFederatedAddress as dn, isHierarchicalAddress as dp, isOrphanedAgent as dq, isScopeAddress as dr, isScopeExposed as ds, isSuccessResponse as dt, mapVisibilityToRule as du, ndJsonStream as dv, resolveAgentPermissions as dw, websocketStream as dx, type SystemExposure as dy, type EventType as e, type SessionId as f, type FederationConnectResponseResult as g, type FederationRouteResponseResult as h, type ConnectionState as i, type ParticipantId as j, type ParticipantType as k, type ScopeId as l, type Agent as m, type Scope as n, type Address as o, type SubscriptionFilter as p, type Event as q, type AgentsGetResponseResult as r, type AgentsListResponseResult as s, type AgentsRegisterResponseResult as t, type AgentsSpawnResponseResult as u, type AgentsUnregisterResponseResult as v, type AgentsUpdateResponseResult as w, type ProtocolVersion as x, type SessionInfo as y, type ScopesCreateResponseResult as z };