macro-agent 0.2.4 → 0.2.6

package/dist/router/address-resolver.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Address Resolver
+ *
+ * Resolves MAP addresses to concrete agent IDs, with special handling
+ * for hierarchical addresses (parent, children, ancestors, descendants, siblings)
+ * that are relative to the sender.
+ *
+ * @module router/address-resolver
+ * @see specs/s-5qir_map_integration_for_macro_agent.md
+ */
+import type { AgentId } from "../store/types/index.js";
+import type { Address, HierarchicalAddress } from "../map/types.js";
+/**
+ * Agent info required for hierarchy resolution.
+ */
+export interface HierarchyAgentInfo {
+    id: AgentId;
+    parent?: AgentId | null;
+    lineage: AgentId[];
+    state: string;
+}
+/**
+ * Source for agent hierarchy information.
+ */
+export interface HierarchySource {
+    getAgent(id: AgentId): HierarchyAgentInfo | undefined;
+    listAgents(): HierarchyAgentInfo[];
+}
+/**
+ * Result of resolving an address.
+ */
+export interface ResolvedAddress {
+    /** Resolved agent IDs */
+    agentIds: AgentId[];
+    /** Type of resolution performed */
+    type: "direct" | "hierarchical" | "structural" | "broadcast" | "task";
+    /** Original address for reference */
+    originalAddress: Address;
+}
+/**
+ * Resolve parent address to sender's parent agent.
+ *
+ * @param senderId - The agent sending the message
+ * @param hierarchy - Source for hierarchy information
+ * @returns Array containing parent ID, or empty if no parent
+ */
+export declare function resolveParent(senderId: AgentId, hierarchy: HierarchySource): AgentId[];
+/**
+ * Resolve children address to sender's child agents.
+ *
+ * @param senderId - The agent sending the message
+ * @param depth - Maximum depth (1 = direct children only)
+ * @param hierarchy - Source for hierarchy information
+ * @returns Array of child agent IDs
+ */
+export declare function resolveChildren(senderId: AgentId, depth: number | undefined, hierarchy: HierarchySource): AgentId[];
+/**
+ * Resolve ancestors address to sender's ancestor agents.
+ *
+ * @param senderId - The agent sending the message
+ * @param depth - Maximum depth (Infinity = all ancestors)
+ * @param hierarchy - Source for hierarchy information
+ * @returns Array of ancestor agent IDs (closest first)
+ */
+export declare function resolveAncestors(senderId: AgentId, depth: number | undefined, hierarchy: HierarchySource): AgentId[];
+/**
+ * Resolve descendants address to all agents descended from sender.
+ *
+ * @param senderId - The agent sending the message
+ * @param depth - Maximum depth (Infinity = all descendants)
+ * @param hierarchy - Source for hierarchy information
+ * @returns Array of descendant agent IDs
+ */
+export declare function resolveDescendants(senderId: AgentId, depth: number | undefined, hierarchy: HierarchySource): AgentId[];
+/**
+ * Resolve siblings address to agents sharing the same parent as sender.
+ *
+ * @param senderId - The agent sending the message
+ * @param hierarchy - Source for hierarchy information
+ * @returns Array of sibling agent IDs (excludes sender)
+ */
+export declare function resolveSiblings(senderId: AgentId, hierarchy: HierarchySource): AgentId[];
+/**
+ * Resolve a hierarchical address to concrete agent IDs.
+ *
+ * @param address - The hierarchical address to resolve
+ * @param senderId - The agent sending the message
+ * @param hierarchy - Source for hierarchy information
+ * @returns Resolved address with agent IDs
+ */
+export declare function resolveHierarchicalAddress(address: HierarchicalAddress, senderId: AgentId, hierarchy: HierarchySource): ResolvedAddress;
+/**
+ * Check if a hierarchical address will resolve to any agents.
+ * Useful for validation before sending.
+ *
+ * @param address - The hierarchical address to check
+ * @param senderId - The agent sending the message
+ * @param hierarchy - Source for hierarchy information
+ * @returns True if address resolves to at least one agent
+ */
+export declare function hasRecipients(address: HierarchicalAddress, senderId: AgentId, hierarchy: HierarchySource): boolean;
+//# sourceMappingURL=address-resolver.d.ts.map

package/dist/router/address-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-resolver.d.ts","sourceRoot":"","sources":["../../src/router/address-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EACV,OAAO,EACP,mBAAmB,EAMpB,MAAM,iBAAiB,CAAC;AAoBzB;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,kBAAkB,GAAG,SAAS,CAAC;IACtD,UAAU,IAAI,kBAAkB,EAAE,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,yBAAyB;IACzB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,mCAAmC;IACnC,IAAI,EAAE,QAAQ,GAAG,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,MAAM,CAAC;IACtE,qCAAqC;IACrC,eAAe,EAAE,OAAO,CAAC;CAC1B;AAMD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,OAAO,EACjB,SAAS,EAAE,eAAe,GACzB,OAAO,EAAE,CAaX;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,MAAM,YAAI,EACjB,SAAS,EAAE,eAAe,GACzB,OAAO,EAAE,CA2BX;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,MAAM,YAAW,EACxB,SAAS,EAAE,eAAe,GACzB,OAAO,EAAE,CAmBX;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,MAAM,YAAW,EACxB,SAAS,EAAE,eAAe,GACzB,OAAO,EAAE,CA0BX;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,OAAO,EACjB,SAAS,EAAE,eAAe,GACzB,OAAO,EAAE,CAoBX;AAMD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,OAAO,EACjB,SAAS,EAAE,eAAe,GACzB,eAAe,CAuBjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,OAAO,EACjB,SAAS,EAAE,eAAe,GACzB,OAAO,CAGT"}

package/dist/router/address-resolver.js

@@ -0,0 +1,198 @@
+/**
+ * Address Resolver
+ *
+ * Resolves MAP addresses to concrete agent IDs, with special handling
+ * for hierarchical addresses (parent, children, ancestors, descendants, siblings)
+ * that are relative to the sender.
+ *
+ * @module router/address-resolver
+ * @see specs/s-5qir_map_integration_for_macro_agent.md
+ */
+import { isParentAddress, isChildrenAddress, isAncestorsAddress, isDescendantsAddress, isSiblingsAddress, } from "../map/types.js";
+// =============================================================================
+// Hierarchical Resolution Functions
+// =============================================================================
+/**
+ * Resolve parent address to sender's parent agent.
+ *
+ * @param senderId - The agent sending the message
+ * @param hierarchy - Source for hierarchy information
+ * @returns Array containing parent ID, or empty if no parent
+ */
+export function resolveParent(senderId, hierarchy) {
+    const sender = hierarchy.getAgent(senderId);
+    if (!sender?.parent) {
+        return [];
+    }
+    // Verify parent exists and is running
+    const parent = hierarchy.getAgent(sender.parent);
+    if (!parent || parent.state !== "running") {
+        return [];
+    }
+    return [sender.parent];
+}
+/**
+ * Resolve children address to sender's child agents.
+ *
+ * @param senderId - The agent sending the message
+ * @param depth - Maximum depth (1 = direct children only)
+ * @param hierarchy - Source for hierarchy information
+ * @returns Array of child agent IDs
+ */
+export function resolveChildren(senderId, depth = 1, hierarchy) {
+    const agents = hierarchy.listAgents();
+    return agents
+        .filter((agent) => {
+        // Only include running agents
+        if (agent.state !== "running") {
+            return false;
+        }
+        // For depth 1, only direct children (parent === senderId)
+        if (depth === 1) {
+            return agent.parent === senderId;
+        }
+        // For depth > 1, check lineage position
+        // EventStore lineage is ordered root-to-parent (oldest to newest)
+        // The depth from sender to agent is (lineage.length - lineageIndex)
+        const lineageIndex = agent.lineage.indexOf(senderId);
+        if (lineageIndex === -1) {
+            return false;
+        }
+        const agentDepth = agent.lineage.length - lineageIndex;
+        return agentDepth <= depth;
+    })
+        .map((agent) => agent.id);
+}
+/**
+ * Resolve ancestors address to sender's ancestor agents.
+ *
+ * @param senderId - The agent sending the message
+ * @param depth - Maximum depth (Infinity = all ancestors)
+ * @param hierarchy - Source for hierarchy information
+ * @returns Array of ancestor agent IDs (closest first)
+ */
+export function resolveAncestors(senderId, depth = Infinity, hierarchy) {
+    const sender = hierarchy.getAgent(senderId);
+    if (!sender || sender.lineage.length === 0) {
+        return [];
+    }
+    // EventStore lineage is ordered from root to parent (oldest to newest)
+    // For depth=1, we want just the direct parent (last element)
+    // For depth=2, we want parent and grandparent (last 2 elements)
+    // We reverse to get closest ancestors first
+    const reversedLineage = [...sender.lineage].reverse();
+    const ancestorsToCheck = depth === Infinity ? reversedLineage : reversedLineage.slice(0, depth);
+    // Filter to only running ancestors
+    return ancestorsToCheck.filter((ancestorId) => {
+        const ancestor = hierarchy.getAgent(ancestorId);
+        return ancestor && ancestor.state === "running";
+    });
+}
+/**
+ * Resolve descendants address to all agents descended from sender.
+ *
+ * @param senderId - The agent sending the message
+ * @param depth - Maximum depth (Infinity = all descendants)
+ * @param hierarchy - Source for hierarchy information
+ * @returns Array of descendant agent IDs
+ */
+export function resolveDescendants(senderId, depth = Infinity, hierarchy) {
+    const agents = hierarchy.listAgents();
+    return agents
+        .filter((agent) => {
+        // Only include running agents
+        if (agent.state !== "running") {
+            return false;
+        }
+        // Check if senderId is in this agent's lineage
+        const lineageIndex = agent.lineage.indexOf(senderId);
+        if (lineageIndex === -1) {
+            return false;
+        }
+        // EventStore lineage is ordered root-to-parent (oldest to newest)
+        // The depth from sender to agent is (lineage.length - lineageIndex)
+        // Example: lineage [root, parent], sender=root, lineageIndex=0
+        //   depth = 2 - 0 = 2 (grandchild of root)
+        // Example: lineage [root], sender=root, lineageIndex=0
+        //   depth = 1 - 0 = 1 (direct child of root)
+        const agentDepth = agent.lineage.length - lineageIndex;
+        return depth === Infinity || agentDepth <= depth;
+    })
+        .map((agent) => agent.id);
+}
+/**
+ * Resolve siblings address to agents sharing the same parent as sender.
+ *
+ * @param senderId - The agent sending the message
+ * @param hierarchy - Source for hierarchy information
+ * @returns Array of sibling agent IDs (excludes sender)
+ */
+export function resolveSiblings(senderId, hierarchy) {
+    const sender = hierarchy.getAgent(senderId);
+    if (!sender?.parent) {
+        // Root agents have no siblings (no parent)
+        return [];
+    }
+    const agents = hierarchy.listAgents();
+    return agents
+        .filter((agent) => {
+        // Only include running agents
+        if (agent.state !== "running") {
+            return false;
+        }
+        // Same parent, but not the sender
+        return agent.parent === sender.parent && agent.id !== senderId;
+    })
+        .map((agent) => agent.id);
+}
+// =============================================================================
+// Main Resolution Function
+// =============================================================================
+/**
+ * Resolve a hierarchical address to concrete agent IDs.
+ *
+ * @param address - The hierarchical address to resolve
+ * @param senderId - The agent sending the message
+ * @param hierarchy - Source for hierarchy information
+ * @returns Resolved address with agent IDs
+ */
+export function resolveHierarchicalAddress(address, senderId, hierarchy) {
+    let agentIds = [];
+    if (isParentAddress(address)) {
+        agentIds = resolveParent(senderId, hierarchy);
+    }
+    else if (isChildrenAddress(address)) {
+        const depth = address.depth ?? 1;
+        agentIds = resolveChildren(senderId, depth, hierarchy);
+    }
+    else if (isAncestorsAddress(address)) {
+        const depth = address.depth ?? Infinity;
+        agentIds = resolveAncestors(senderId, depth, hierarchy);
+    }
+    else if (isDescendantsAddress(address)) {
+        const depth = address.depth ?? Infinity;
+        agentIds = resolveDescendants(senderId, depth, hierarchy);
+    }
+    else if (isSiblingsAddress(address)) {
+        agentIds = resolveSiblings(senderId, hierarchy);
+    }
+    return {
+        agentIds,
+        type: "hierarchical",
+        originalAddress: address,
+    };
+}
+/**
+ * Check if a hierarchical address will resolve to any agents.
+ * Useful for validation before sending.
+ *
+ * @param address - The hierarchical address to check
+ * @param senderId - The agent sending the message
+ * @param hierarchy - Source for hierarchy information
+ * @returns True if address resolves to at least one agent
+ */
+export function hasRecipients(address, senderId, hierarchy) {
+    const resolved = resolveHierarchicalAddress(address, senderId, hierarchy);
+    return resolved.agentIds.length > 0;
+}
+//# sourceMappingURL=address-resolver.js.map

package/dist/router/address-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-resolver.js","sourceRoot":"","sources":["../../src/router/address-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAYH,OAAO,EAOL,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,GAElB,MAAM,iBAAiB,CAAC;AAoCzB,gFAAgF;AAChF,oCAAoC;AACpC,gFAAgF;AAEhF;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAiB,EACjB,SAA0B;IAE1B,MAAM,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC5C,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QACpB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,sCAAsC;IACtC,MAAM,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACjD,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAiB,EACjB,QAAgB,CAAC,EACjB,SAA0B;IAE1B,MAAM,MAAM,GAAG,SAAS,CAAC,UAAU,EAAE,CAAC;IAEtC,OAAO,MAAM;SACV,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QAChB,8BAA8B;QAC9B,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;QAED,0DAA0D;QAC1D,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC;QACnC,CAAC;QAED,wCAAwC;QACxC,kEAAkE;QAClE,oEAAoE;QACpE,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACrD,IAAI,YAAY,KAAK,CAAC,CAAC,EAAE,CAAC;YACxB,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,YAAY,CAAC;QACvD,OAAO,UAAU,IAAI,KAAK,CAAC;IAC7B,CAAC,CAAC;SACD,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAAiB,EACjB,QAAgB,QAAQ,EACxB,SAA0B;IAE1B,MAAM,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC5C,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3C,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,uEAAuE;IACvE,6DAA6D;IAC7D,gEAAgE;IAChE,4CAA4C;IAC5C,MAAM,eAAe,GAAG,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC;IACtD,MAAM,gBAAgB,GACpB,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAEzE,mCAAmC;IACnC,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE;QAC5C,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QAChD,OAAO,QAAQ,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,CAAC;IAClD,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAiB,EACjB,QAAgB,QAAQ,EACxB,SAA0B;IAE1B,MAAM,MAAM,GAAG,SAAS,CAAC,UAAU,EAAE,CAAC;IAEtC,OAAO,MAAM;SACV,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QAChB,8BAA8B;QAC9B,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;QAED,+CAA+C;QAC/C,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACrD,IAAI,YAAY,KAAK,CAAC,CAAC,EAAE,CAAC;YACxB,OAAO,KAAK,CAAC;QACf,CAAC;QAED,kEAAkE;QAClE,oEAAoE;QACpE,+DAA+D;QAC/D,2CAA2C;QAC3C,uDAAuD;QACvD,6CAA6C;QAC7C,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,YAAY,CAAC;QACvD,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,IAAI,KAAK,CAAC;IACnD,CAAC,CAAC;SACD,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAiB,EACjB,SAA0B;IAE1B,MAAM,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC5C,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QACpB,2CAA2C;QAC3C,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,CAAC,UAAU,EAAE,CAAC;IAEtC,OAAO,MAAM;SACV,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QAChB,8BAA8B;QAC9B,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;QAED,kCAAkC;QAClC,OAAO,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,IAAI,KAAK,CAAC,EAAE,KAAK,QAAQ,CAAC;IACjE,CAAC,CAAC;SACD,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,gFAAgF;AAChF,2BAA2B;AAC3B,gFAAgF;AAEhF;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAA4B,EAC5B,QAAiB,EACjB,SAA0B;IAE1B,IAAI,QAAQ,GAAc,EAAE,CAAC;IAE7B,IAAI,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,QAAQ,GAAG,aAAa,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAChD,CAAC;SAAM,IAAI,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;QACjC,QAAQ,GAAG,eAAe,CAAC,QAAQ,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;IACzD,CAAC;SAAM,IAAI,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,QAAQ,CAAC;QACxC,QAAQ,GAAG,gBAAgB,CAAC,QAAQ,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;IAC1D,CAAC;SAAM,IAAI,oBAAoB,CAAC,OAAO,CAAC,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,QAAQ,CAAC;QACxC,QAAQ,GAAG,kBAAkB,CAAC,QAAQ,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;IAC5D,CAAC;SAAM,IAAI,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,QAAQ,GAAG,eAAe,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAClD,CAAC;IAED,OAAO;QACL,QAAQ;QACR,IAAI,EAAE,cAAc;QACpB,eAAe,EAAE,OAAO;KACzB,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAC3B,OAA4B,EAC5B,QAAiB,EACjB,SAA0B;IAE1B,MAAM,QAAQ,GAAG,0BAA0B,CAAC,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC1E,OAAO,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;AACtC,CAAC"}

package/dist/router/broadcast.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Broadcast Channel Resolution
+ *
+ * Handles fan-out delivery for broadcast channels with scope filtering.
+ *
+ * @module router/broadcast
+ * @see s-9rld In-Flight Steering spec section 3.2
+ */
+import type { AgentId } from "../store/types/index.js";
+import type { BroadcastScope } from "./types.js";
+/**
+ * Agent info required for broadcast resolution
+ */
+export interface BroadcastAgentInfo {
+    id: AgentId;
+    state: string;
+    role?: string;
+}
+/**
+ * Agent source for broadcast resolution
+ */
+export interface BroadcastAgentSource {
+    listAgents(): BroadcastAgentInfo[];
+}
+/**
+ * Check if a role matches a broadcast scope.
+ *
+ * Scope mappings:
+ * - 'all': matches all agents
+ * - 'coordinators': matches 'coordinator' role and any 'coordinator.*' subroles
+ * - 'workers': matches 'worker' role and any 'worker.*' subroles
+ * - 'monitors': matches 'monitor' role and any 'monitor.*' subroles
+ */
+export declare function matchesBroadcastScope(role: string | undefined, scope: BroadcastScope): boolean;
+/**
+ * Get all agents that should receive a broadcast message.
+ *
+ * @param agentSource - Source for listing agents
+ * @param scope - Optional scope filter (default: 'all')
+ * @returns Array of agent IDs to deliver message to
+ */
+export declare function getBroadcastRecipients(agentSource: BroadcastAgentSource, scope?: BroadcastScope): AgentId[];
+/**
+ * Resolve a broadcast target to recipient agent IDs.
+ *
+ * @param agentSource - Source for listing agents
+ * @param target - Broadcast target with optional scope
+ * @returns Array of agent IDs for fan-out delivery
+ */
+export declare function resolveBroadcastTarget(agentSource: BroadcastAgentSource, target: {
+    scope?: BroadcastScope;
+}): AgentId[];
+//# sourceMappingURL=broadcast.d.ts.map

package/dist/router/broadcast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broadcast.d.ts","sourceRoot":"","sources":["../../src/router/broadcast.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAMjD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,IAAI,kBAAkB,EAAE,CAAC;CACpC;AAMD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,KAAK,EAAE,cAAc,GACpB,OAAO,CAsBT;AAMD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,oBAAoB,EACjC,KAAK,CAAC,EAAE,cAAc,GACrB,OAAO,EAAE,CAgBX;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,oBAAoB,EACjC,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,cAAc,CAAA;CAAE,GACjC,OAAO,EAAE,CAEX"}

package/dist/router/broadcast.js

@@ -0,0 +1,75 @@
+/**
+ * Broadcast Channel Resolution
+ *
+ * Handles fan-out delivery for broadcast channels with scope filtering.
+ *
+ * @module router/broadcast
+ * @see s-9rld In-Flight Steering spec section 3.2
+ */
+// =============================================================================
+// Scope Matching
+// =============================================================================
+/**
+ * Check if a role matches a broadcast scope.
+ *
+ * Scope mappings:
+ * - 'all': matches all agents
+ * - 'coordinators': matches 'coordinator' role and any 'coordinator.*' subroles
+ * - 'workers': matches 'worker' role and any 'worker.*' subroles
+ * - 'monitors': matches 'monitor' role and any 'monitor.*' subroles
+ */
+export function matchesBroadcastScope(role, scope) {
+    if (scope === "all") {
+        return true;
+    }
+    if (!role) {
+        // Agents without a role default to worker behavior
+        return scope === "workers";
+    }
+    // Map scope to role prefix
+    const scopeToRolePrefix = {
+        all: "", // Already handled above
+        coordinators: "coordinator",
+        workers: "worker",
+        monitors: "monitor",
+    };
+    const rolePrefix = scopeToRolePrefix[scope];
+    // Match exact role or subrole (e.g., "worker" or "worker.resolver")
+    return role === rolePrefix || role.startsWith(`${rolePrefix}.`);
+}
+// =============================================================================
+// Broadcast Resolution
+// =============================================================================
+/**
+ * Get all agents that should receive a broadcast message.
+ *
+ * @param agentSource - Source for listing agents
+ * @param scope - Optional scope filter (default: 'all')
+ * @returns Array of agent IDs to deliver message to
+ */
+export function getBroadcastRecipients(agentSource, scope) {
+    const effectiveScope = scope ?? "all";
+    const agents = agentSource.listAgents();
+    // Filter to running agents that match the scope
+    return agents
+        .filter((agent) => {
+        // Only include running agents
+        if (agent.state !== "running") {
+            return false;
+        }
+        // Check scope match
+        return matchesBroadcastScope(agent.role, effectiveScope);
+    })
+        .map((agent) => agent.id);
+}
+/**
+ * Resolve a broadcast target to recipient agent IDs.
+ *
+ * @param agentSource - Source for listing agents
+ * @param target - Broadcast target with optional scope
+ * @returns Array of agent IDs for fan-out delivery
+ */
+export function resolveBroadcastTarget(agentSource, target) {
+    return getBroadcastRecipients(agentSource, target.scope);
+}
+//# sourceMappingURL=broadcast.js.map

package/dist/router/broadcast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"broadcast.js","sourceRoot":"","sources":["../../src/router/broadcast.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAyBH,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAwB,EACxB,KAAqB;IAErB,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,mDAAmD;QACnD,OAAO,KAAK,KAAK,SAAS,CAAC;IAC7B,CAAC;IAED,2BAA2B;IAC3B,MAAM,iBAAiB,GAAmC;QACxD,GAAG,EAAE,EAAE,EAAE,wBAAwB;QACjC,YAAY,EAAE,aAAa;QAC3B,OAAO,EAAE,QAAQ;QACjB,QAAQ,EAAE,SAAS;KACpB,CAAC;IAEF,MAAM,UAAU,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAE5C,oEAAoE;IACpE,OAAO,IAAI,KAAK,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,UAAU,GAAG,CAAC,CAAC;AAClE,CAAC;AAED,gFAAgF;AAChF,uBAAuB;AACvB,gFAAgF;AAEhF;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,WAAiC,EACjC,KAAsB;IAEtB,MAAM,cAAc,GAAG,KAAK,IAAI,KAAK,CAAC;IACtC,MAAM,MAAM,GAAG,WAAW,CAAC,UAAU,EAAE,CAAC;IAExC,gDAAgD;IAChD,OAAO,MAAM;SACV,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QAChB,8BAA8B;QAC9B,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;QAED,oBAAoB;QACpB,OAAO,qBAAqB,CAAC,KAAK,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IAC3D,CAAC,CAAC;SACD,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,WAAiC,EACjC,MAAkC;IAElC,OAAO,sBAAsB,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;AAC3D,CAAC"}

package/dist/router/channels.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Enhanced Channel Types
+ *
+ * Extended channel types for agent communication including
+ * broadcast and role-based addressing.
+ *
+ * @module router/channels
+ * @see s-9rld In-Flight Steering spec section 3.2
+ */
+import type { AgentId, TaskId } from "../store/types/index.js";
+/**
+ * All supported channel types
+ */
+export type ChannelType = "agent" | "task" | "lineage" | "subtree" | "topic" | "broadcast" | "role";
+/**
+ * Direct agent channel
+ */
+export interface AgentChannel {
+    type: "agent";
+    id: AgentId;
+}
+/**
+ * Task channel - routes to task's assigned agent
+ */
+export interface TaskChannel {
+    type: "task";
+    id: TaskId;
+}
+/**
+ * Lineage channel - messages from ancestors
+ */
+export interface LineageChannel {
+    type: "lineage";
+    agentId: AgentId;
+}
+/**
+ * Subtree channel - events from descendants
+ */
+export interface SubtreeChannel {
+    type: "subtree";
+    agentId: AgentId;
+}
+/**
+ * Topic channel - topic-based pub/sub
+ */
+export interface TopicChannel {
+    type: "topic";
+    topic: string;
+}
+/**
+ * Broadcast channel - fan-out to all subscribers
+ */
+export interface BroadcastChannel {
+    type: "broadcast";
+    /** Optional scope for targeted broadcasts */
+    scope?: "all" | "coordinators" | "workers" | "monitors";
+}
+/**
+ * Role channel - dynamic resolution by agent role
+ * Uses @role syntax (e.g., @workers, @integrator)
+ */
+export interface RoleChannel {
+    type: "role";
+    /** Role name to target (e.g., "worker", "integrator", "monitor") */
+    role: string;
+    /** Optional scope to specific coordinator's agents */
+    coordinatorId?: AgentId;
+}
+/**
+ * Union of all channel specifications
+ */
+export type Channel = AgentChannel | TaskChannel | LineageChannel | SubtreeChannel | TopicChannel | BroadcastChannel | RoleChannel;
+import type { MessagePriority } from "./types.js";
+export type { MessagePriority } from "./types.js";
+/**
+ * Priority level numeric values for ordering
+ */
+export declare const PRIORITY_VALUES: Record<MessagePriority, number>;
+/**
+ * Compare two priorities (higher priority = larger value)
+ */
+export declare function comparePriority(a: MessagePriority, b: MessagePriority): number;
+/**
+ * Message delivery mode
+ */
+export type DeliveryMode = "queue" | "interrupt";
+/**
+ * Group resolution strategy
+ */
+export type GroupResolution = "send-time" | "receive-time";
+/**
+ * Create an agent channel
+ */
+export declare function agentChannel(id: AgentId): AgentChannel;
+/**
+ * Create a task channel
+ */
+export declare function taskChannel(id: TaskId): TaskChannel;
+/**
+ * Create a topic channel
+ */
+export declare function topicChannel(topic: string): TopicChannel;
+/**
+ * Create a broadcast channel
+ */
+export declare function broadcastChannel(scope?: BroadcastChannel["scope"]): BroadcastChannel;
+/**
+ * Create a role channel
+ */
+export declare function roleChannel(role: string, coordinatorId?: AgentId): RoleChannel;
+/**
+ * Create a lineage channel
+ */
+export declare function lineageChannel(agentId: AgentId): LineageChannel;
+/**
+ * Create a subtree channel
+ */
+export declare function subtreeChannel(agentId: AgentId): SubtreeChannel;
+/**
+ * Parse @role syntax to role channel
+ * Examples: @workers, @integrator, @monitor
+ */
+export declare function parseRoleSyntax(syntax: string, coordinatorId?: AgentId): RoleChannel | null;
+/**
+ * Check if channel is an agent channel
+ */
+export declare function isAgentChannel(channel: Channel): channel is AgentChannel;
+/**
+ * Check if channel is a task channel
+ */
+export declare function isTaskChannel(channel: Channel): channel is TaskChannel;
+/**
+ * Check if channel is a topic channel
+ */
+export declare function isTopicChannel(channel: Channel): channel is TopicChannel;
+/**
+ * Check if channel is a broadcast channel
+ */
+export declare function isBroadcastChannel(channel: Channel): channel is BroadcastChannel;
+/**
+ * Check if channel is a role channel
+ */
+export declare function isRoleChannel(channel: Channel): channel is RoleChannel;
+/**
+ * Check if channel targets multiple recipients
+ */
+export declare function isMulticastChannel(channel: Channel): boolean;
+//# sourceMappingURL=channels.d.ts.map

package/dist/router/channels.d.ts.map

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