macro-agent 0.1.1 → 0.1.3

package/src/activity/deduplication.ts

@@ -1,219 +0,0 @@
-/**
- * Activity Deduplication
- *
- * Prevents alert storms by deduplicating similar activities within a time window.
- * Uses a slot-based pattern inspired by Gastown's notification deduplication.
- *
- * @module activity/deduplication
- * @see s-9rld In-Flight Steering spec
- * @see Gastown internal/daemon/notification.go
- */
-
-import type { AgentId } from "../store/types/index.js";
-import type { Activity, ActivityEventType } from "./types.js";
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/**
- * Key for deduplication slot
- */
-export interface DeduplicationKey {
-  /** Agent being notified */
-  agentId: AgentId;
-  /** Event type */
-  eventType: ActivityEventType | string;
-  /** Optional source agent (for source-specific dedup) */
-  sourceAgentId?: AgentId;
-}
-
-/**
- * Slot entry tracking recent notifications
- */
-interface SlotEntry {
-  /** Key for this slot */
-  key: string;
-  /** Timestamp of last notification */
-  lastNotified: number;
-  /** Count of suppressed notifications */
-  suppressedCount: number;
-}
-
-/**
- * Deduplication configuration
- */
-export interface DeduplicationConfig {
-  /** Time window for deduplication in milliseconds */
-  windowMs: number;
-  /** Maximum slots to track (LRU eviction) */
-  maxSlots: number;
-  /** Whether to track suppression counts */
-  trackSuppressed: boolean;
-}
-
-const DEFAULT_DEDUP_CONFIG: DeduplicationConfig = {
-  windowMs: 5000,
-  maxSlots: 10000,
-  trackSuppressed: true,
-};
-
-// =============================================================================
-// Deduplicator Implementation
-// =============================================================================
-
-/**
- * Activity deduplicator using slot-based pattern.
- *
- * Prevents the same agent from being notified multiple times for similar
- * events within a configurable time window.
- */
-export class ActivityDeduplicator {
-  private slots = new Map<string, SlotEntry>();
-  private config: DeduplicationConfig;
-
-  constructor(config: Partial<DeduplicationConfig> = {}) {
-    this.config = { ...DEFAULT_DEDUP_CONFIG, ...config };
-  }
-
-  /**
-   * Check if a notification should be sent.
-   *
-   * @param agentId - Agent to notify
-   * @param activity - Activity triggering the notification
-   * @returns true if notification should be sent, false if suppressed
-   */
-  shouldNotify(agentId: AgentId, activity: Activity): boolean {
-    const key = this.buildKey({
-      agentId,
-      eventType: activity.type,
-      sourceAgentId: activity.source?.agent_id,
-    });
-
-    const now = Date.now();
-    const existing = this.slots.get(key);
-
-    if (existing) {
-      // Check if within deduplication window
-      if (now - existing.lastNotified < this.config.windowMs) {
-        // Suppress notification
-        if (this.config.trackSuppressed) {
-          existing.suppressedCount++;
-        }
-        return false;
-      }
-    }
-
-    // Update slot
-    this.slots.set(key, {
-      key,
-      lastNotified: now,
-      suppressedCount: 0,
-    });
-
-    // Evict old entries if needed
-    this.evictIfNeeded();
-
-    return true;
-  }
-
-  /**
-   * Mark a notification as sent (update slot timestamp).
-   */
-  markNotified(agentId: AgentId, activity: Activity): void {
-    const key = this.buildKey({
-      agentId,
-      eventType: activity.type,
-      sourceAgentId: activity.source?.agent_id,
-    });
-
-    this.slots.set(key, {
-      key,
-      lastNotified: Date.now(),
-      suppressedCount: 0,
-    });
-
-    this.evictIfNeeded();
-  }
-
-  /**
-   * Get suppression stats for debugging.
-   */
-  getStats(): { totalSlots: number; totalSuppressed: number } {
-    let totalSuppressed = 0;
-    for (const slot of this.slots.values()) {
-      totalSuppressed += slot.suppressedCount;
-    }
-    return {
-      totalSlots: this.slots.size,
-      totalSuppressed,
-    };
-  }
-
-  /**
-   * Clear all slots.
-   */
-  clear(): void {
-    this.slots.clear();
-  }
-
-  /**
-   * Clear expired slots (outside deduplication window).
-   */
-  clearExpired(): number {
-    const now = Date.now();
-    let cleared = 0;
-
-    for (const [key, slot] of this.slots) {
-      if (now - slot.lastNotified >= this.config.windowMs) {
-        this.slots.delete(key);
-        cleared++;
-      }
-    }
-
-    return cleared;
-  }
-
-  /**
-   * Build a slot key from deduplication key components.
-   */
-  private buildKey(keyParts: DeduplicationKey): string {
-    const parts = [keyParts.agentId, keyParts.eventType];
-    if (keyParts.sourceAgentId) {
-      parts.push(keyParts.sourceAgentId);
-    }
-    return parts.join("::");
-  }
-
-  /**
-   * Evict oldest entries if over max slots.
-   */
-  private evictIfNeeded(): void {
-    if (this.slots.size <= this.config.maxSlots) {
-      return;
-    }
-
-    // Find and remove oldest entries
-    const entries = [...this.slots.entries()].sort(
-      (a, b) => a[1].lastNotified - b[1].lastNotified
-    );
-
-    const toRemove = entries.slice(0, this.slots.size - this.config.maxSlots);
-    for (const [key] of toRemove) {
-      this.slots.delete(key);
-    }
-  }
-}
-
-// =============================================================================
-// Factory Function
-// =============================================================================
-
-/**
- * Create an activity deduplicator with the given configuration.
- */
-export function createDeduplicator(
-  config?: Partial<DeduplicationConfig>
-): ActivityDeduplicator {
-  return new ActivityDeduplicator(config);
-}

package/src/activity/index.ts

@@ -1,51 +0,0 @@
-/**
- * Activity Module Exports
- *
- * Activity-based waking system for agents.
- *
- * @module activity
- * @see s-9rld In-Flight Steering spec section 3.4
- */
-
-// Types
-export * from "./types.js";
-
-// Relevance detection
-export {
-  findRelevantAgents,
-  matchesRole,
-  matchesSubscriptionScope,
-  getAncestors,
-  isInSubtree,
-  getAgentsByRole,
-} from "./relevance.js";
-
-export type {
-  RelevanceAgentInfo,
-  RelevanceAgentSource,
-  RelevanceSubscriptionSource,
-  RelevanceOptions,
-} from "./relevance.js";
-
-// Deduplication
-export {
-  ActivityDeduplicator,
-  createDeduplicator,
-} from "./deduplication.js";
-
-export type {
-  DeduplicationKey,
-  DeduplicationConfig,
-} from "./deduplication.js";
-
-// Activity watcher
-export {
-  createActivityWatcher,
-  subscribeAgentToEvents,
-} from "./watcher.js";
-
-export type {
-  ActivityListener,
-  WakeHandler,
-  ActivityWatcher,
-} from "./watcher.js";

package/src/activity/relevance.ts

@@ -1,258 +0,0 @@
-/**
- * Activity Relevance Detection
- *
- * Determines which agents should be notified/woken for a given activity.
- * Uses multiple scopes: lineage, role, subscriptions, and custom rules.
- *
- * @module activity/relevance
- * @see s-9rld In-Flight Steering spec section 3.4
- */
-
-import type { AgentId } from "../store/types/index.js";
-import type {
-  Activity,
-  ActivityEventType,
-  EventSubscription,
-  RelevanceRule,
-} from "./types.js";
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/**
- * Agent info required for relevance detection
- */
-export interface RelevanceAgentInfo {
-  id: AgentId;
-  state: string;
-  role?: string;
-  lineage: AgentId[];
-}
-
-/**
- * Agent source for relevance detection
- */
-export interface RelevanceAgentSource {
-  listAgents(): RelevanceAgentInfo[];
-  getAgent(agentId: AgentId): RelevanceAgentInfo | null;
-}
-
-/**
- * Subscription source for relevance detection
- */
-export interface RelevanceSubscriptionSource {
-  getSubscribers(eventType: ActivityEventType): EventSubscription[];
-}
-
-/**
- * Options for relevance detection
- */
-export interface RelevanceOptions {
-  /** Include lineage-based relevance (ancestors) */
-  includeLineage?: boolean;
-  /** Include role-based relevance */
-  includeRole?: boolean;
-  /** Include subscription-based relevance */
-  includeSubscriptions?: boolean;
-  /** Include direct target relevance */
-  includeTarget?: boolean;
-  /** Custom relevance rules */
-  customRules?: RelevanceRule[];
-}
-
-const DEFAULT_RELEVANCE_OPTIONS: RelevanceOptions = {
-  includeLineage: true,
-  includeRole: true,
-  includeSubscriptions: true,
-  includeTarget: true,
-  customRules: [],
-};
-
-// =============================================================================
-// Relevance Detection
-// =============================================================================
-
-/**
- * Find all agents relevant to an activity.
- *
- * Relevance is determined by:
- * 1. Lineage: Ancestors of the source agent (they may be monitoring subtree)
- * 2. Role: Agents whose role matches the activity target
- * 3. Subscriptions: Agents subscribed to the event type
- * 4. Target: Direct target of the activity
- * 5. Custom rules: User-defined relevance rules
- */
-export function findRelevantAgents(
-  activity: Activity,
-  agentSource: RelevanceAgentSource,
-  subscriptionSource?: RelevanceSubscriptionSource,
-  options: RelevanceOptions = DEFAULT_RELEVANCE_OPTIONS
-): AgentId[] {
-  const relevant = new Set<AgentId>();
-  const opts = { ...DEFAULT_RELEVANCE_OPTIONS, ...options };
-
-  // 1. Lineage: Wake ancestors if event is from their subtree
-  if (opts.includeLineage && activity.source?.agent_id) {
-    const sourceAgent = agentSource.getAgent(activity.source.agent_id);
-    if (sourceAgent) {
-      // Add all ancestors (they have this agent in their subtree)
-      for (const ancestorId of sourceAgent.lineage) {
-        relevant.add(ancestorId);
-      }
-    }
-  }
-
-  // 2. Role-based: Check if event targets a role
-  if (opts.includeRole && activity.target?.type === "role" && activity.target.role) {
-    const agents = agentSource.listAgents();
-    const targetRole = activity.target.role;
-
-    for (const agent of agents) {
-      if (matchesRole(agent.role, targetRole)) {
-        relevant.add(agent.id);
-      }
-    }
-  }
-
-  // 3. Subscriptions: Check event type subscribers
-  if (opts.includeSubscriptions && subscriptionSource) {
-    const eventType = activity.type as ActivityEventType;
-    const subscriptions = subscriptionSource.getSubscribers(eventType);
-
-    for (const sub of subscriptions) {
-      // Check scope filters
-      if (matchesSubscriptionScope(activity, sub, agentSource)) {
-        relevant.add(sub.agentId);
-      }
-    }
-  }
-
-  // 4. Direct target: If activity targets a specific agent
-  if (opts.includeTarget && activity.target?.type === "agent" && activity.target.target) {
-    relevant.add(activity.target.target);
-  }
-
-  // 5. Custom rules
-  if (opts.customRules) {
-    for (const rule of opts.customRules) {
-      const ruleResults = rule(activity);
-      for (const agentId of ruleResults) {
-        relevant.add(agentId);
-      }
-    }
-  }
-
-  // Filter to active agents only
-  const activeRelevant = [...relevant].filter((id) => {
-    const agent = agentSource.getAgent(id);
-    return agent && agent.state === "running";
-  });
-
-  return activeRelevant;
-}
-
-// =============================================================================
-// Helper Functions
-// =============================================================================
-
-/**
- * Check if an agent's role matches a target role.
- * Supports exact match and prefix match (e.g., "worker.resolver" matches "worker").
- */
-export function matchesRole(agentRole: string | undefined, targetRole: string): boolean {
-  if (!agentRole) {
-    return targetRole === "worker";
-  }
-  return agentRole === targetRole || agentRole.startsWith(`${targetRole}.`);
-}
-
-/**
- * Check if an activity matches a subscription's scope filters.
- */
-export function matchesSubscriptionScope(
-  activity: Activity,
-  subscription: EventSubscription,
-  agentSource: RelevanceAgentSource
-): boolean {
-  const scope = subscription.scope;
-  if (!scope) {
-    return true; // No scope filter = matches all
-  }
-
-  // Check subtree filter
-  if (scope.subtree && activity.source?.agent_id) {
-    const sourceAgent = agentSource.getAgent(activity.source.agent_id);
-    if (!sourceAgent) {
-      return false;
-    }
-    // Source must be in the subtree (have subtree agent in lineage or be the subtree agent)
-    if (
-      activity.source.agent_id !== scope.subtree &&
-      !sourceAgent.lineage.includes(scope.subtree)
-    ) {
-      return false;
-    }
-  }
-
-  // Check role filter
-  if (scope.role && activity.source?.role) {
-    if (!matchesRole(activity.source.role, scope.role)) {
-      return false;
-    }
-  }
-
-  // Check target agent filter
-  if (scope.targetAgent) {
-    if (
-      activity.target?.type !== "agent" ||
-      activity.target.target !== scope.targetAgent
-    ) {
-      return false;
-    }
-  }
-
-  return true;
-}
-
-/**
- * Get ancestors of an agent (from lineage).
- */
-export function getAncestors(
-  agentId: AgentId,
-  agentSource: RelevanceAgentSource
-): AgentId[] {
-  const agent = agentSource.getAgent(agentId);
-  if (!agent) {
-    return [];
-  }
-  return [...agent.lineage];
-}
-
-/**
- * Check if an agent is in another agent's subtree.
- */
-export function isInSubtree(
-  agentId: AgentId,
-  subtreeRootId: AgentId,
-  agentSource: RelevanceAgentSource
-): boolean {
-  if (agentId === subtreeRootId) {
-    return true;
-  }
-  const agent = agentSource.getAgent(agentId);
-  return agent ? agent.lineage.includes(subtreeRootId) : false;
-}
-
-/**
- * Get all agents with a specific role.
- */
-export function getAgentsByRole(
-  role: string,
-  agentSource: RelevanceAgentSource
-): AgentId[] {
-  const agents = agentSource.listAgents();
-  return agents
-    .filter((a) => a.state === "running" && matchesRole(a.role, role))
-    .map((a) => a.id);
-}