macro-agent 0.1.2 → 0.1.4

package/src/router/address-resolver.ts

@@ -1,303 +0,0 @@
-/**
- * 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,
-  ParentAddress,
-  ChildrenAddress,
-  AncestorsAddress,
-  DescendantsAddress,
-  SiblingsAddress,
-} from "../map/types.js";
-import {
-  isAgentAddress,
-  isAgentsAddress,
-  isScopeAddress,
-  isRoleAddress,
-  isTaskAddress,
-  isBroadcastAddress,
-  isParentAddress,
-  isChildrenAddress,
-  isAncestorsAddress,
-  isDescendantsAddress,
-  isSiblingsAddress,
-  isHierarchicalAddress,
-} from "../map/types.js";
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/**
- * 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;
-}
-
-// =============================================================================
-// 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: AgentId,
-  hierarchy: HierarchySource
-): AgentId[] {
-  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: AgentId,
-  depth: number = 1,
-  hierarchy: HierarchySource
-): AgentId[] {
-  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: AgentId,
-  depth: number = Infinity,
-  hierarchy: HierarchySource
-): AgentId[] {
-  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: AgentId,
-  depth: number = Infinity,
-  hierarchy: HierarchySource
-): AgentId[] {
-  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: AgentId,
-  hierarchy: HierarchySource
-): AgentId[] {
-  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: HierarchicalAddress,
-  senderId: AgentId,
-  hierarchy: HierarchySource
-): ResolvedAddress {
-  let agentIds: AgentId[] = [];
-
-  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: HierarchicalAddress,
-  senderId: AgentId,
-  hierarchy: HierarchySource
-): boolean {
-  const resolved = resolveHierarchicalAddress(address, senderId, hierarchy);
-  return resolved.agentIds.length > 0;
-}

package/src/router/broadcast.ts

@@ -1,117 +0,0 @@
-/**
- * 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";
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/**
- * 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[];
-}
-
-// =============================================================================
-// 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: string | undefined,
-  scope: BroadcastScope
-): boolean {
-  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: Record<BroadcastScope, string> = {
-    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: BroadcastAgentSource,
-  scope?: BroadcastScope
-): AgentId[] {
-  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: BroadcastAgentSource,
-  target: { scope?: BroadcastScope }
-): AgentId[] {
-  return getBroadcastRecipients(agentSource, target.scope);
-}

package/src/router/channels.ts

@@ -1,283 +0,0 @@
-/**
- * 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";
-
-// =============================================================================
-// Channel Types
-// =============================================================================
-
-/**
- * All supported channel types
- */
-export type ChannelType =
-  | "agent" // Direct to specific agent
-  | "task" // To task's assigned agent
-  | "lineage" // Parent/child chain
-  | "subtree" // All descendants
-  | "topic" // Topic-based pub/sub
-  | "broadcast" // Fan-out to all subscribers
-  | "role"; // Dynamic resolution by role
-
-// =============================================================================
-// Channel Specifications
-// =============================================================================
-
-/**
- * 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;
-
-// =============================================================================
-// Message Priority
-// =============================================================================
-
-// MessagePriority is imported from types.ts to avoid duplication
-import type { MessagePriority } from "./types.js";
-export type { MessagePriority } from "./types.js";
-
-/**
- * Priority level numeric values for ordering
- */
-export const PRIORITY_VALUES: Record<MessagePriority, number> = {
-  low: 0,
-  normal: 1,
-  high: 2,
-  urgent: 3,
-};
-
-/**
- * Compare two priorities (higher priority = larger value)
- */
-export function comparePriority(
-  a: MessagePriority,
-  b: MessagePriority
-): number {
-  return PRIORITY_VALUES[a] - PRIORITY_VALUES[b];
-}
-
-// =============================================================================
-// Delivery Modes
-// =============================================================================
-
-/**
- * Message delivery mode
- */
-export type DeliveryMode =
-  | "queue" // Add to recipient's queue (default)
-  | "interrupt"; // Attempt immediate delivery (future: mid-turn)
-
-// =============================================================================
-// Group Resolution
-// =============================================================================
-
-/**
- * Group resolution strategy
- */
-export type GroupResolution =
-  | "send-time" // Snapshot of current agents when message sent (default)
-  | "receive-time"; // Resolve on each delivery attempt
-
-// =============================================================================
-// Channel Helpers
-// =============================================================================
-
-/**
- * Create an agent channel
- */
-export function agentChannel(id: AgentId): AgentChannel {
-  return { type: "agent", id };
-}
-
-/**
- * Create a task channel
- */
-export function taskChannel(id: TaskId): TaskChannel {
-  return { type: "task", id };
-}
-
-/**
- * Create a topic channel
- */
-export function topicChannel(topic: string): TopicChannel {
-  return { type: "topic", topic };
-}
-
-/**
- * Create a broadcast channel
- */
-export function broadcastChannel(
-  scope?: BroadcastChannel["scope"]
-): BroadcastChannel {
-  return { type: "broadcast", scope };
-}
-
-/**
- * Create a role channel
- */
-export function roleChannel(
-  role: string,
-  coordinatorId?: AgentId
-): RoleChannel {
-  return { type: "role", role, coordinatorId };
-}
-
-/**
- * Create a lineage channel
- */
-export function lineageChannel(agentId: AgentId): LineageChannel {
-  return { type: "lineage", agentId };
-}
-
-/**
- * Create a subtree channel
- */
-export function subtreeChannel(agentId: AgentId): SubtreeChannel {
-  return { type: "subtree", agentId };
-}
-
-/**
- * Parse @role syntax to role channel
- * Examples: @workers, @integrator, @monitor
- */
-export function parseRoleSyntax(
-  syntax: string,
-  coordinatorId?: AgentId
-): RoleChannel | null {
-  if (!syntax.startsWith("@")) {
-    return null;
-  }
-  const role = syntax.slice(1);
-  if (!role) {
-    return null;
-  }
-  return roleChannel(role, coordinatorId);
-}
-
-// =============================================================================
-// Channel Type Guards
-// =============================================================================
-
-/**
- * Check if channel is an agent channel
- */
-export function isAgentChannel(channel: Channel): channel is AgentChannel {
-  return channel.type === "agent";
-}
-
-/**
- * Check if channel is a task channel
- */
-export function isTaskChannel(channel: Channel): channel is TaskChannel {
-  return channel.type === "task";
-}
-
-/**
- * Check if channel is a topic channel
- */
-export function isTopicChannel(channel: Channel): channel is TopicChannel {
-  return channel.type === "topic";
-}
-
-/**
- * Check if channel is a broadcast channel
- */
-export function isBroadcastChannel(
-  channel: Channel
-): channel is BroadcastChannel {
-  return channel.type === "broadcast";
-}
-
-/**
- * Check if channel is a role channel
- */
-export function isRoleChannel(channel: Channel): channel is RoleChannel {
-  return channel.type === "role";
-}
-
-/**
- * Check if channel targets multiple recipients
- */
-export function isMulticastChannel(channel: Channel): boolean {
-  return (
-    channel.type === "broadcast" ||
-    channel.type === "role" ||
-    channel.type === "topic" ||
-    channel.type === "subtree"
-  );
-}