macro-agent 0.2.5 → 0.2.6

package/dist/monitor/stall-detector.js

@@ -0,0 +1,152 @@
+/**
+ * StallDetector - Detects stalled agents and cleans up zombies
+ *
+ * A stalled agent is one that:
+ * - Has no recent activity (lastActivityAt is stale)
+ * - Is not actively processing a prompt (isProcessing is false)
+ *
+ * A zombie agent is one that:
+ * - Has state 'stopped' in EventStore
+ * - But still has a session mapping in SessionMapper
+ *
+ * @module monitor/stall-detector
+ * @see s-5yhx Phase B: Monitor Active Behaviors
+ */
+/**
+ * Default configuration values
+ */
+export const DEFAULT_STALL_DETECTOR_CONFIG = {
+    stalledThresholdMs: 10 * 60 * 1000, // 10 minutes
+};
+// =============================================================================
+// StallDetector Class
+// =============================================================================
+/**
+ * Detects stalled agents and cleans up zombie sessions
+ */
+export class StallDetector {
+    eventStore;
+    sessionMapper;
+    config;
+    constructor(eventStore, sessionMapper, config = {}) {
+        this.eventStore = eventStore;
+        this.sessionMapper = sessionMapper;
+        this.config = { ...DEFAULT_STALL_DETECTOR_CONFIG, ...config };
+    }
+    /**
+     * Detect stalled workers under a coordinator
+     *
+     * A worker is considered stalled if:
+     * 1. It's in 'running' state
+     * 2. Its lastActivityAt is older than stalledThresholdMs
+     * 3. Its session is NOT currently processing a prompt
+     *
+     * @param coordinatorId - The coordinator whose workers to check
+     * @returns Array of stalled agents
+     */
+    detectStalled(coordinatorId) {
+        const now = Date.now();
+        const workers = this.eventStore.listAgents({
+            parent: coordinatorId,
+            state: "running",
+        });
+        const stalled = [];
+        for (const worker of workers) {
+            // Use lastActivityAt if available, otherwise fall back to created_at
+            const lastActivity = worker.last_activity_at ?? worker.created_at;
+            const stalledMs = now - lastActivity;
+            // Check if the agent has been inactive long enough
+            if (stalledMs > this.config.stalledThresholdMs) {
+                // Get session status to see if it's actually processing
+                const sessionStatus = this.sessionMapper.getSessionStatus(worker.id);
+                // Only mark as stalled if NOT processing
+                // If processing, the agent is actively working even if lastActivityAt is stale
+                if (!sessionStatus?.isProcessing) {
+                    stalled.push({
+                        agentId: worker.id,
+                        coordinatorId,
+                        lastActivityAt: lastActivity,
+                        stalledDurationMs: stalledMs,
+                        assignedTaskId: worker.task_id,
+                        sessionStatus: sessionStatus ? "idle" : "unknown",
+                    });
+                }
+            }
+        }
+        return stalled;
+    }
+    /**
+     * Detect all stalled agents across all coordinators
+     *
+     * @returns Array of all stalled agents
+     */
+    detectAllStalled() {
+        const allStalled = [];
+        // Find all coordinators (agents with role 'coordinator')
+        const coordinators = this.eventStore.listAgents({ state: "running" });
+        const coordinatorIds = coordinators
+            .filter((a) => a.role === "coordinator")
+            .map((a) => a.id);
+        for (const coordinatorId of coordinatorIds) {
+            const stalled = this.detectStalled(coordinatorId);
+            allStalled.push(...stalled);
+        }
+        return allStalled;
+    }
+    /**
+     * Detect and clean up zombie agents
+     *
+     * A zombie is an agent that:
+     * - Is in 'stopped' state in EventStore
+     * - Still has a session mapping in SessionMapper
+     *
+     * This can happen if an agent terminates but the session cleanup fails.
+     *
+     * @returns Array of cleaned up zombie agents
+     */
+    cleanupZombies() {
+        const zombies = [];
+        // Get all stopped agents
+        const stoppedAgents = this.eventStore.listAgents({ state: "stopped" });
+        for (const agent of stoppedAgents) {
+            // Check if there are any sessions still mapped to this agent
+            const sessions = this.sessionMapper.getSessionsForAgent(agent.id);
+            if (sessions.length > 0) {
+                // Determine stop reason
+                let reason = "unknown";
+                if (agent.stop_reason === "completed") {
+                    reason = "done_called";
+                }
+                else if (agent.stop_reason === "stopped" ||
+                    agent.stop_reason === "cancelled") {
+                    reason = "parent_terminated";
+                }
+                // Record the zombie
+                zombies.push({
+                    agentId: agent.id,
+                    stoppedAt: agent.stopped_at ?? Date.now(),
+                    acpSessionId: sessions[0],
+                    reason,
+                });
+                // Clean up all orphaned session mappings for this agent
+                for (const sessionId of sessions) {
+                    this.sessionMapper.removeMapping(sessionId);
+                }
+            }
+        }
+        return zombies;
+    }
+    /**
+     * Get the current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update the configuration
+     */
+    updateConfig(config) {
+        Object.assign(this.config, config);
+    }
+}
+//# sourceMappingURL=stall-detector.js.map

package/dist/monitor/stall-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stall-detector.js","sourceRoot":"","sources":["../../src/monitor/stall-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA6DH;;GAEG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAwB;IAChE,kBAAkB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,aAAa;CAClD,CAAC;AAEF,gFAAgF;AAChF,sBAAsB;AACtB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,OAAO,aAAa;IACP,UAAU,CAAa;IACvB,aAAa,CAAgB;IAC7B,MAAM,CAAsB;IAE7C,YACE,UAAsB,EACtB,aAA4B,EAC5B,SAAuC,EAAE;QAEzC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,6BAA6B,EAAE,GAAG,MAAM,EAAE,CAAC;IAChE,CAAC;IAED;;;;;;;;;;OAUG;IACH,aAAa,CAAC,aAAsB;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;YACzC,MAAM,EAAE,aAAa;YACrB,KAAK,EAAE,SAAS;SACjB,CAAC,CAAC;QAEH,MAAM,OAAO,GAAmB,EAAE,CAAC;QAEnC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,qEAAqE;YACrE,MAAM,YAAY,GAAG,MAAM,CAAC,gBAAgB,IAAI,MAAM,CAAC,UAAU,CAAC;YAClE,MAAM,SAAS,GAAG,GAAG,GAAG,YAAY,CAAC;YAErC,mDAAmD;YACnD,IAAI,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC;gBAC/C,wDAAwD;gBACxD,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBAErE,yCAAyC;gBACzC,+EAA+E;gBAC/E,IAAI,CAAC,aAAa,EAAE,YAAY,EAAE,CAAC;oBACjC,OAAO,CAAC,IAAI,CAAC;wBACX,OAAO,EAAE,MAAM,CAAC,EAAE;wBAClB,aAAa;wBACb,cAAc,EAAE,YAAY;wBAC5B,iBAAiB,EAAE,SAAS;wBAC5B,cAAc,EAAE,MAAM,CAAC,OAAO;wBAC9B,aAAa,EAAE,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;qBAClD,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACH,gBAAgB;QACd,MAAM,UAAU,GAAmB,EAAE,CAAC;QAEtC,yDAAyD;QACzD,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QACtE,MAAM,cAAc,GAAG,YAAY;aAChC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,aAAa,CAAC;aACvC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAEpB,KAAK,MAAM,aAAa,IAAI,cAAc,EAAE,CAAC;YAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC;YAClD,UAAU,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;QAC9B,CAAC;QAED,OAAO,UAAU,CAAC;IACpB,CAAC;IAED;;;;;;;;;;OAUG;IACH,cAAc;QACZ,MAAM,OAAO,GAAkB,EAAE,CAAC;QAElC,yBAAyB;QACzB,MAAM,aAAa,GAAG,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QAEvE,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;YAClC,6DAA6D;YAC7D,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAElE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxB,wBAAwB;gBACxB,IAAI,MAAM,GAA0B,SAAS,CAAC;gBAC9C,IAAI,KAAK,CAAC,WAAW,KAAK,WAAW,EAAE,CAAC;oBACtC,MAAM,GAAG,aAAa,CAAC;gBACzB,CAAC;qBAAM,IACL,KAAK,CAAC,WAAW,KAAK,SAAS;oBAC/B,KAAK,CAAC,WAAW,KAAK,WAAW,EACjC,CAAC;oBACD,MAAM,GAAG,mBAAmB,CAAC;gBAC/B,CAAC;gBAED,oBAAoB;gBACpB,OAAO,CAAC,IAAI,CAAC;oBACX,OAAO,EAAE,KAAK,CAAC,EAAE;oBACjB,SAAS,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,EAAE;oBACzC,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC;oBACzB,MAAM;iBACP,CAAC,CAAC;gBAEH,wDAAwD;gBACxD,KAAK,MAAM,SAAS,IAAI,QAAQ,EAAE,CAAC;oBACjC,IAAI,CAAC,aAAa,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;gBAC9C,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,MAAoC;QAC/C,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;CACF"}

package/dist/peer/capability-manager.d.ts

@@ -0,0 +1,56 @@
+/**
+ * CapabilityManager - Manages peer capabilities for distributed hierarchy operations
+ *
+ * Provides explicit, scoped permission system for controlling what peers can do.
+ * Inspired by AWS IAM, OAuth 2.0, and Erlang/OTP supervision patterns.
+ *
+ * Design principles:
+ * - No implicit trust - all permissions must be explicitly granted
+ * - Scoped grants - different capabilities for different patterns
+ * - Bilateral agreement - both sides must consent to relationships
+ */
+import type { CapabilityGrant, CapabilityType, PeerCapabilities, GrantCapabilityOptions } from "./types.js";
+/**
+ * CapabilityManager interface
+ */
+export interface CapabilityManager {
+    /**
+     * Grant capabilities to a peer.
+     * If the peer already has capabilities, new grants are merged with existing ones.
+     * @param peerId - Peer to grant capabilities to
+     * @param grants - Capabilities to grant
+     * @param options - Optional expiration and issuer info
+     * @returns The full capability set for the peer
+     */
+    grant(peerId: string, grants: CapabilityGrant[], options?: GrantCapabilityOptions): PeerCapabilities;
+    /**
+     * Revoke capabilities from a peer.
+     * @param peerId - Peer to revoke capabilities from
+     * @param grantTypes - Specific types to revoke, or all if omitted
+     */
+    revoke(peerId: string, grantTypes?: CapabilityType[]): void;
+    /**
+     * Check if peer has required capability.
+     * Checks both type and specific permissions within the grant.
+     * @param peerId - Peer to check
+     * @param required - Required capability (type and permissions)
+     * @returns true if peer has the required capability
+     */
+    hasCapability(peerId: string, required: CapabilityGrant): boolean;
+    /**
+     * Get all capabilities for a peer.
+     * Returns null if peer has no capabilities or capabilities have expired.
+     * @param peerId - Peer to get capabilities for
+     */
+    getCapabilities(peerId: string): PeerCapabilities | null;
+    /**
+     * List all peers with any capabilities.
+     * Excludes expired capabilities.
+     */
+    listAuthorizedPeers(): PeerCapabilities[];
+}
+/**
+ * Create a CapabilityManager instance
+ */
+export declare function createCapabilityManager(): CapabilityManager;
+//# sourceMappingURL=capability-manager.d.ts.map

package/dist/peer/capability-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-manager.d.ts","sourceRoot":"","sources":["../../src/peer/capability-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EAIvB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;OAOG;IACH,KAAK,CACH,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,eAAe,EAAE,EACzB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,gBAAgB,CAAC;IAEpB;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;IAE5D;;;;;;OAMG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC;IAElE;;;;OAIG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAEzD;;;OAGG;IACH,mBAAmB,IAAI,gBAAgB,EAAE,CAAC;CAC3C;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,iBAAiB,CAuN3D"}

package/dist/peer/capability-manager.js

@@ -0,0 +1,186 @@
+/**
+ * CapabilityManager - Manages peer capabilities for distributed hierarchy operations
+ *
+ * Provides explicit, scoped permission system for controlling what peers can do.
+ * Inspired by AWS IAM, OAuth 2.0, and Erlang/OTP supervision patterns.
+ *
+ * Design principles:
+ * - No implicit trust - all permissions must be explicitly granted
+ * - Scoped grants - different capabilities for different patterns
+ * - Bilateral agreement - both sides must consent to relationships
+ */
+/**
+ * Create a CapabilityManager instance
+ */
+export function createCapabilityManager() {
+    // In-memory capability storage
+    const capabilities = new Map();
+    /**
+     * Check if capabilities have expired
+     */
+    function isExpired(caps) {
+        if (caps.expiresAt === undefined) {
+            return false;
+        }
+        return Date.now() > caps.expiresAt;
+    }
+    /**
+     * Grant capabilities to a peer
+     */
+    function grant(peerId, grants, options) {
+        const now = Date.now();
+        const existing = capabilities.get(peerId);
+        // Merge with existing grants if present and not expired
+        let mergedGrants;
+        if (existing && !isExpired(existing)) {
+            // Create a map of existing grants by type
+            const grantMap = new Map();
+            for (const g of existing.grants) {
+                grantMap.set(g.type, g);
+            }
+            // Override with new grants
+            for (const g of grants) {
+                grantMap.set(g.type, g);
+            }
+            mergedGrants = Array.from(grantMap.values());
+        }
+        else {
+            mergedGrants = [...grants];
+        }
+        const peerCaps = {
+            peerId,
+            grants: mergedGrants,
+            issuedAt: now,
+            expiresAt: options?.expiresIn ? now + options.expiresIn : undefined,
+            issuedBy: options?.issuedBy,
+        };
+        capabilities.set(peerId, peerCaps);
+        return peerCaps;
+    }
+    /**
+     * Revoke capabilities from a peer
+     */
+    function revoke(peerId, grantTypes) {
+        if (!grantTypes || grantTypes.length === 0) {
+            // Revoke all capabilities
+            capabilities.delete(peerId);
+            return;
+        }
+        const existing = capabilities.get(peerId);
+        if (!existing) {
+            return;
+        }
+        // Filter out revoked grant types
+        const typesToRevoke = new Set(grantTypes);
+        const remainingGrants = existing.grants.filter((g) => !typesToRevoke.has(g.type));
+        if (remainingGrants.length === 0) {
+            capabilities.delete(peerId);
+        }
+        else {
+            capabilities.set(peerId, {
+                ...existing,
+                grants: remainingGrants,
+            });
+        }
+    }
+    /**
+     * Check if peer has required capability
+     */
+    function hasCapability(peerId, required) {
+        const peerCaps = capabilities.get(peerId);
+        if (!peerCaps || isExpired(peerCaps)) {
+            return false;
+        }
+        // Find a grant of the same type
+        const grant = peerCaps.grants.find((g) => g.type === required.type);
+        if (!grant) {
+            return false;
+        }
+        // Check type-specific permissions
+        switch (required.type) {
+            case "task-delegation":
+                return checkTaskDelegation(grant, required);
+            case "federated-hierarchy":
+                return checkFederatedHierarchy(grant, required);
+            case "encapsulation":
+                return checkEncapsulation(grant, required);
+            default:
+                return false;
+        }
+    }
+    /**
+     * Check task delegation capability
+     */
+    function checkTaskDelegation(grant, required) {
+        // Task delegation is granted if type matches
+        // maxConcurrentTasks is a limit, not a requirement to check
+        return true;
+    }
+    /**
+     * Check federated hierarchy capability
+     */
+    function checkFederatedHierarchy(grant, required) {
+        // Check each required permission
+        if (required.canQueryAgents && !grant.canQueryAgents) {
+            return false;
+        }
+        if (required.canMount && !grant.canMount) {
+            return false;
+        }
+        if (required.canSubscribeStatus && !grant.canSubscribeStatus) {
+            return false;
+        }
+        // Check agent ID restrictions if present
+        if (grant.allowedAgentIds && required.allowedAgentIds) {
+            const allowedSet = new Set(grant.allowedAgentIds);
+            for (const agentId of required.allowedAgentIds) {
+                if (!allowedSet.has(agentId)) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    /**
+     * Check encapsulation capability
+     */
+    function checkEncapsulation(grant, required) {
+        if (required.canActAsChild && !grant.canActAsChild) {
+            return false;
+        }
+        if (required.canActAsParent && !grant.canActAsParent) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Get capabilities for a peer
+     */
+    function getCapabilities(peerId) {
+        const peerCaps = capabilities.get(peerId);
+        if (!peerCaps || isExpired(peerCaps)) {
+            return null;
+        }
+        return peerCaps;
+    }
+    /**
+     * List all authorized peers
+     */
+    function listAuthorizedPeers() {
+        const result = [];
+        for (const peerCaps of capabilities.values()) {
+            if (!isExpired(peerCaps)) {
+                result.push(peerCaps);
+            }
+        }
+        return result;
+    }
+    return {
+        grant,
+        revoke,
+        hasCapability,
+        getCapabilities,
+        listAuthorizedPeers,
+    };
+}
+//# sourceMappingURL=capability-manager.js.map

package/dist/peer/capability-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-manager.js","sourceRoot":"","sources":["../../src/peer/capability-manager.ts"],"names":[],"mappings":"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"}

package/dist/peer/encapsulation-manager.d.ts

@@ -0,0 +1,190 @@
+/**
+ * EncapsulationManager - Transparent encapsulation pattern for distributed macro-agents
+ *
+ * A remote macro-agent (B) registers with a parent macro-agent (A) and appears
+ * as a single child agent within A's hierarchy. B's entire internal hierarchy
+ * is hidden behind a facade - A only sees a "proxy agent" representing B.
+ *
+ * Features:
+ * - Child-initiated registration with facade configuration
+ * - Status aggregation (consolidated status, not per-internal-agent)
+ * - Configurable error detail levels (opaque/summary/full)
+ * - Task routing through proxy agents
+ */
+import type { PeerAddress, FacadeConfig } from "./types.js";
+import type { PatternHandler, HierarchyResponse } from "./hierarchy-protocol.js";
+import type { CapabilityManager } from "./capability-manager.js";
+/**
+ * Encapsulated agent status
+ */
+export type EncapsulatedStatus = "idle" | "running" | "completed" | "failed";
+/**
+ * Encapsulated child state (from parent's perspective)
+ */
+export interface EncapsulatedChild {
+    /** Proxy agent ID in parent's namespace */
+    proxyAgentId: string;
+    /** Remote peer ID */
+    peerId: string;
+    /** Facade configuration */
+    facadeConfig: FacadeConfig;
+    /** Current status */
+    status: EncapsulatedStatus;
+    /** When registered */
+    registeredAt: number;
+}
+/**
+ * Parent registration (from child's perspective)
+ */
+export interface ParentRegistration {
+    /** Parent peer ID */
+    parentPeerId: string;
+    /** Our proxy agent ID in parent's namespace */
+    proxyAgentId: string;
+    /** Our facade configuration */
+    facadeConfig: FacadeConfig;
+    /** When registered */
+    registeredAt: number;
+}
+/**
+ * Task sent to encapsulated agent
+ */
+export interface EncapsulatedTask {
+    /** Task ID for tracking */
+    taskId: string;
+    /** Proxy agent ID */
+    proxyAgentId: string;
+    /** Task description */
+    task: string;
+    /** Additional context */
+    context?: Record<string, unknown>;
+}
+/**
+ * Task result from encapsulated agent
+ */
+export interface EncapsulatedResult {
+    /** Proxy agent ID */
+    proxyAgentId: string;
+    /** Task ID */
+    taskId: string;
+    /** Result status */
+    status: "completed" | "failed";
+    /** Result if completed */
+    result?: unknown;
+    /** Error if failed */
+    error?: {
+        code: number;
+        message: string;
+        details?: unknown;
+    };
+}
+/**
+ * Status update from encapsulated agent
+ */
+export interface EncapsulatedStatusPayload {
+    /** Proxy agent ID */
+    proxyAgentId: string;
+    /** Current status */
+    status: EncapsulatedStatus;
+    /** Optional message */
+    message?: string;
+}
+/**
+ * Callbacks for encapsulation events
+ */
+export interface EncapsulationCallbacks {
+    /** Called when a child wants to register (as parent) */
+    onRegistrationRequested?: (peerId: string, config: FacadeConfig) => Promise<{
+        accepted: boolean;
+        reason?: string;
+    }>;
+    /** Called when a task is received (as child) */
+    onTaskReceived?: (task: EncapsulatedTask) => Promise<void>;
+    /** Called when status update is received (as parent) */
+    onStatusUpdate?: (payload: EncapsulatedStatusPayload) => void;
+    /** Called when result is received (as parent) */
+    onResultReceived?: (result: EncapsulatedResult) => void;
+    /** Called when a child is created to add to store (as parent) */
+    onChildCreated?: (child: EncapsulatedChild) => void;
+    /** Called when a child is removed (as parent) */
+    onChildRemoved?: (proxyAgentId: string) => void;
+}
+export interface EncapsulationManagerConfig {
+    /** Capability manager for permission checks */
+    capabilityManager?: CapabilityManager;
+    /** Callbacks for encapsulation events */
+    callbacks?: EncapsulationCallbacks;
+    /** Maximum encapsulated children (optional) */
+    maxChildren?: number;
+}
+export interface EncapsulationManager {
+    /**
+     * Get the pattern handler for routing
+     */
+    getHandler(): PatternHandler;
+    /**
+     * Accept a registration from a child (called internally by handler)
+     */
+    acceptRegistration(peerId: string, config: FacadeConfig): Promise<string>;
+    /**
+     * Remove an encapsulated child
+     */
+    removeChild(proxyAgentId: string): void;
+    /**
+     * Send a task to an encapsulated agent
+     */
+    sendTask(proxyAgentId: string, task: string, context?: Record<string, unknown>): Promise<{
+        accepted: boolean;
+        taskId: string;
+    }>;
+    /**
+     * Get an encapsulated child by proxy agent ID
+     */
+    getChild(proxyAgentId: string): EncapsulatedChild | undefined;
+    /**
+     * List all encapsulated children
+     */
+    listChildren(): EncapsulatedChild[];
+    /**
+     * Register with a parent as an encapsulated child
+     */
+    registerWithParent(parentPeerId: string, config: FacadeConfig): Promise<{
+        proxyAgentId: string;
+        accepted: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Unregister from a parent
+     */
+    unregisterFromParent(parentPeerId: string): Promise<{
+        unregistered: boolean;
+    }>;
+    /**
+     * Report status to parent
+     */
+    reportStatus(status: EncapsulatedStatus, message?: string): void;
+    /**
+     * Report task result to parent
+     */
+    reportResult(taskId: string, result: Omit<EncapsulatedResult, "proxyAgentId" | "taskId">): void;
+    /**
+     * Get our parent registration (if registered)
+     */
+    getParentRegistration(): ParentRegistration | undefined;
+    /**
+     * Set the send functions (injected by PeerManager)
+     */
+    setSendFunctions(fns: {
+        sendRequest: (to: PeerAddress, method: string, params: unknown) => Promise<HierarchyResponse>;
+        sendMessage: (to: PeerAddress, type: string, payload: unknown) => Promise<void>;
+    }): void;
+}
+/**
+ * Create an EncapsulationManager
+ */
+export declare function createEncapsulationManager(config?: EncapsulationManagerConfig): EncapsulationManager;
+/**
+ * Generate a proxy agent ID
+ */
+export declare function generateProxyAgentId(): string;
+//# sourceMappingURL=encapsulation-manager.d.ts.map

package/dist/peer/encapsulation-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encapsulation-manager.d.ts","sourceRoot":"","sources":["../../src/peer/encapsulation-manager.ts"],"names":[],"mappings":"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"}