macro-agent 0.2.4 → 0.2.6

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Alex Ngai
+Copyright (c) 2025-2026 Alex Ngai
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -25,7 +25,7 @@ macro-agent handles **orchestration** (agent lifecycle, team topology, workspace
   - [Why V3 was needed](#why-v3-was-needed)
   - [Workspace interfaces](#workspace-interfaces)
   - [Conflict recovery mechanics](#conflict-recovery-mechanics)
-  - [Implementation status](#implementation-status)
+  - [Project status](#project-status)
 - [Advanced integrations](#advanced-integrations)
 - [Dependencies](#dependencies)
 - [Testing](#testing)
@@ -39,7 +39,7 @@ macro-agent handles **orchestration** (agent lifecycle, team topology, workspace
 npm install macro-agent
 ```
 
-Peer dependency: [git-cascade](https://github.com/alexngai/git-cascade) `>=0.0.3` for the workspace layer.
+The workspace layer is powered by [git-cascade](https://github.com/alexngai/git-cascade), installed automatically as a dependency.
 
 ---
 
@@ -276,7 +276,7 @@ roles:
 
 ### Six team shapes
 
-The workspace layer is designed to express 6 common multi-agent patterns. See [docs/git-cascade-integration-gaps.md](docs/git-cascade-integration-gaps.md) §5 for traces.
+The workspace layer is designed to express 6 common multi-agent patterns. See [docs/design/git-cascade-integration-gaps.md](docs/design/git-cascade-integration-gaps.md) §5 for traces.
 
 **1. Solo stack** — one agent, chain of forked streams:
 ```yaml
@@ -363,6 +363,9 @@ npx multiagent-cli run <teamName> [--task "..."] [--cwd <path>] [--base-path <pa
 # Interactive chat with a head manager (no team)
 npx multiagent-cli chat [--cwd <path>]
 
+# Start the long-running server (REST/ACP as configured)
+npx multiagent-cli start [--port <port>] [--host <host>] [--cwd <path>]
+
 # System status (agent count, active sessions)
 npx multiagent-cli status
 
@@ -511,10 +514,10 @@ Three subsystems:
 - **opentasks** — task management (separate daemon, IPC client)
 
 For full design rationale and interface contracts:
-- [docs/workspace-interfaces.md](docs/workspace-interfaces.md) — V3 TypeScript contracts
-- [docs/git-cascade-integration-gaps.md](docs/git-cascade-integration-gaps.md) — design narrative + 6 workflow traces
-- [docs/conflict-recovery.md](docs/conflict-recovery.md) — recovery strategy design
-- [docs/workspace-redesign-plan.md](docs/workspace-redesign-plan.md) — implementation plan + status
+- [docs/design/workspace-interfaces.md](docs/design/workspace-interfaces.md) — V3 TypeScript contracts
+- [docs/design/git-cascade-integration-gaps.md](docs/design/git-cascade-integration-gaps.md) — design narrative + 6 workflow traces
+- [docs/design/conflict-recovery.md](docs/design/conflict-recovery.md) — recovery strategy design
+- [docs/design/workspace-redesign-plan.md](docs/design/workspace-redesign-plan.md) — implementation plan + status
 
 The four subsections below summarize those docs so this README is useful standalone.
 
@@ -764,57 +767,28 @@ type ConflictResolution =
 
 Recursion: if a resolver agent's resolution itself produces a new conflict, `recoveryDepth` increments. When it exceeds `max_recovery_depth`, the strategy falls back to `escalate`.
 
-### Implementation status
-
-The V3 redesign shipped as 10 phases plus 6 follow-up fixes. All are in `main`.
-
-**Completed:**
-
-| # | Phase | What shipped |
-|---|---|---|
-| 0 | GitCascadeAdapter expansion | 40+ git-cascade primitives surfaced (streams, forks, merges, cascade, changes, events) |
-| 1 | WorkspaceManager V3 surface | Stream-first methods alongside legacy role-shaped ones |
-| 2 | YAML Zod schema | `macro_agent.workspace` validated at team load |
-| 3 | TopologyPolicy + YamlDrivenTopology | Declarative topology compiler |
-| 4 | AgentManagerV2 delegates to TopologyPolicy | V3 dispatch path with legacy capability fallback |
-| 5 | LandingStrategy integration | 4 built-in strategies registered |
-| 6 | MergeQueue marked `@deprecated` | Duplicate kept for legacy callers; scheduled for removal |
-| 7 | ConflictRecoveryStrategy | 5 built-in strategies (including real-git `auto-resolve` + `spawn-resolver`) |
-| 8 | Role-name fallback removed | `switch(role)` deleted; capability-based path retained |
-| 9 | Legacy methods retained (not hard-removed) | Reframed: they serve programmatic callers |
-| 10 | `macro-agent run <team>` CLI | Single-command team launch |
-
-**Follow-up fixes (post-plan):**
-
-| # | Fix | Verified by |
-|---|---|---|
-| a | git-cascade 0.0.3 event wiring + cascade namespace | Adapter forwards `x-cascade/*` events into `WorkspaceEvent` stream |
-| b | `macro-agent run` CLI e2e (subprocess spawn, SIGINT exit) | 2 e2e tests |
-| c | self-driving team migrated to V3 YAML | 4 e2e tests; caught duplicate-stream bug in TeamRuntime |
-| d | `spawn-resolver` real-spawn e2e | 4 unit + 2 e2e tests |
-| e | Shared worktree ref-counting (Gap 3) | Fixed 2 latent bugs: sharer dealloc leaked refs; owner dealloc tore down path while sharers alive. 6 unit tests cover lifecycle |
-| f | Cascade worktree provider (Gap 1) | Replaced null-returning stub with real provider: reuses live worktrees, allocates ephemeral `system:cascade-<id>` worktrees, cleans up in `finally`. Per-root-stream lock prevents parallel cascades racing. 4 e2e tests |
-| g | `on_parent_advanced: sync_with_parent` auto-sync (Gap 2) | Full implementation: event subscription, 2-second coalescing debounce, role-scoped dispatch. 3 e2e tests |
+### Project status
 
-**Test counts after all fixes:**
+macro-agent is pre-1.0, but the core is stable and in active use. The V3
+stream-first workspace layer (topology, landing, conflict recovery), teams,
+triggers, the ACP and REST servers, federation, and the OpenHive/MAP bridge are
+all implemented and covered by unit and end-to-end tests — the e2e suite drives
+real Claude Code subprocesses behind the `RUN_FULL_AGENT_TESTS` flag.
 
-- 998 unit tests (59 files)
-- 183 e2e tests (25 files) — all previously skipped `RUN_FULL_AGENT_TESTS` tests pass with real Claude Code
-- Zero regressions, clean typecheck
+**Known limitations:**
 
-**Known open items / follow-ups:**
-
-| Item | Severity | Notes |
-|---|---|---|
-| Hard removal of legacy capability dispatch | Low | Retained as programmatic API; not a gap, a supported path |
-| `on_team_complete: merge_to_main` implementation | Low | Currently leaves stream active. Requires landing strategy on team stream; deferred |
-| Cross-team conflict policy | Low | When conflicts span teams, owner team's policy applies; federation-specific edge cases |
-| Recovery observability dashboard | Low | `conflict:*` events fire; no built-in UI yet |
+- `on_team_complete: merge_to_main` currently leaves the team stream active
+  (merge it manually); `keep` and `abandon` work as documented.
+- Cross-team conflicts apply the owning team's recovery policy; some
+  federation-specific edge cases are unspecified.
+- There is no built-in dashboard for conflict/recovery observability — the
+  `conflict:*` workspace events fire, but you wire your own consumer.
 
-**Coverage gaps intentionally accepted:**
+The legacy capability-based dispatch path is intentionally retained as the
+programmatic API for library consumers that don't load team YAML — it's a
+supported path, not a deprecated one.
 
-- Cascade with >3 levels under `stop_on_conflict` — tested at 3 levels only
-- Shared worktree edge case: sharer outlives owner for >1 hour (no TTL) — accepted; `reconcileV3` cleans stale entries on boot
+See the [CHANGELOG](CHANGELOG.md) for release history.
 
 ---
 
@@ -822,7 +796,7 @@ The V3 redesign shipped as 10 phases plus 6 follow-up fixes. All are in `main`.
 
 ### ACP Protocol Server
 
-Bridges the [Agent Client Protocol](https://github.com/anthropics/acp) to macro-agent so external clients can connect:
+Bridges the [Agent Client Protocol](https://github.com/agentclientprotocol/agent-client-protocol) to macro-agent so external clients can connect:
 
 ```typescript
 const system = await bootV2({ acp: { enabled: true, port: 8080 } });
@@ -858,7 +832,7 @@ const system = await bootV2({
 Serve as compute backend for [cognitive-core](https://github.com/alexngai/cognitive-core) / OpenHive:
 
 ```typescript
-import { MacroAgentBackend } from 'macro-agent/cognitive';
+import { MacroAgentBackend } from 'macro-agent';
 const backend = new MacroAgentBackend(system.agentManager, {
   tasksAdapter: system.tasksAdapter,
   inboxAdapter: system.inboxAdapter,
@@ -877,7 +851,7 @@ The swarm is pure compute — atlas, trajectory extraction, and team coordinatio
 | [opentasks](https://github.com/alexngai/opentasks) | Task graph, dependencies, claiming |
 | [acp-factory](https://github.com/alexngai/acp-factory) | Agent process management |
 | [openteams](https://github.com/alexngai/openteams) | Team template resolution |
-| [git-cascade](https://github.com/alexngai/git-cascade) | Git worktrees, stream/fork/merge, Change-Id tracking, cascade rebase (≥0.0.3) |
+| [git-cascade](https://github.com/alexngai/git-cascade) | Git worktrees, stream/fork/merge, Change-Id tracking, cascade rebase |
 | express | REST API server |
 | ws | ACP WebSocket transport |
 

package/dist/acp/websocket-server.d.ts

@@ -25,6 +25,12 @@ export interface WebSocketACPServerConfig {
     host?: string;
     path?: string;
     initConfig?: MacroAgentInitConfig;
+    /**
+     * Bearer token required to open a connection. Falls back to the
+     * `MACRO_SERVER_TOKEN` env var. When unset, the server refuses to bind to a
+     * non-loopback host (see auth/server-auth).
+     */
+    token?: string;
 }
 export declare function createWebSocketACPServer(system: MacroAgentSystemV2, config?: WebSocketACPServerConfig): WebSocketACPServer;
 //# sourceMappingURL=websocket-server.d.ts.map

package/dist/acp/websocket-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"websocket-server.d.ts","sourceRoot":"","sources":["../../src/acp/websocket-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAUH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAMvD,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,gDAAgD;IAChD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB,6CAA6C;IAC7C,kBAAkB,IAAI,MAAM,CAAC;IAE7B,yCAAyC;IACzC,MAAM,IAAI,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,oBAAoB,CAAC;CACnC;AAoDD,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,kBAAkB,EAC1B,MAAM,CAAC,EAAE,wBAAwB,GAChC,kBAAkB,CAgHpB"}
+{"version":3,"file":"websocket-server.d.ts","sourceRoot":"","sources":["../../src/acp/websocket-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAeH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAMvD,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,gDAAgD;IAChD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB,6CAA6C;IAC7C,kBAAkB,IAAI,MAAM,CAAC;IAE7B,yCAAyC;IACzC,MAAM,IAAI,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAClC;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAoDD,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,kBAAkB,EAC1B,MAAM,CAAC,EAAE,wBAAwB,GAChC,kBAAkB,CA2HpB"}

package/dist/acp/websocket-server.js

@@ -10,6 +10,7 @@
  */
 import { WebSocketServer, WebSocket } from "ws";
 import * as http from "node:http";
+import { assertBindAllowed, isRequestAuthorized, resolveServerToken, } from "../auth/server-auth.js";
 import { AgentSideConnection, } from "@agentclientprotocol/sdk";
 import { createMacroAgent } from "./macro-agent.js";
 // ─────────────────────────────────────────────────────────────────
@@ -65,6 +66,7 @@ export function createWebSocketACPServer(system, config) {
     const host = config?.host ?? "127.0.0.1";
     const wsPath = config?.path ?? "/acp";
     const initConfig = config?.initConfig;
+    const token = resolveServerToken(config?.token);
     let httpServer = null;
     let wss = null;
     const connections = new Set();
@@ -88,6 +90,16 @@ export function createWebSocketACPServer(system, config) {
             wss = new WebSocketServer({
                 server: httpServer,
                 path: wsPath,
+                // Authenticate at the WebSocket handshake. No-op when no token is
+                // configured (the bind guard keeps such servers loopback-only).
+                verifyClient: (info, done) => {
+                    if (isRequestAuthorized(token, info.req)) {
+                        done(true);
+                    }
+                    else {
+                        done(false, 401, "Unauthorized");
+                    }
+                },
             });
             wss.on("connection", (ws) => {
                 webSockets.add(ws);
@@ -106,6 +118,7 @@ export function createWebSocketACPServer(system, config) {
                     connections.delete(conn);
                 });
             });
+            assertBindAllowed("acp", host, token);
             await new Promise((resolve, reject) => {
                 httpServer.on("error", reject);
                 httpServer.listen(port, host, () => {

package/dist/acp/websocket-server.js.map

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

package/dist/acp/websocket-stream.d.ts

@@ -0,0 +1,30 @@
+/**
+ * WebSocket Stream Adapter for ACP
+ *
+ * Adapts a WebSocket connection to the ACP SDK's Stream interface.
+ * Unlike ndJsonStream (used for stdio), this doesn't need newline delimiters
+ * since WebSocket already frames messages.
+ */
+import type { WebSocket } from "ws";
+export type { Stream } from "@agentclientprotocol/sdk";
+import type { Stream } from "@agentclientprotocol/sdk";
+/**
+ * Create an ACP Stream from a WebSocket connection.
+ *
+ * This adapts a WebSocket to the bidirectional Stream interface expected
+ * by AgentSideConnection. Each WebSocket message is a complete JSON-RPC
+ * message (no newline delimiters needed).
+ *
+ * @param ws - The WebSocket connection to adapt
+ * @returns A Stream for bidirectional ACP communication
+ */
+export declare function webSocketStream(ws: WebSocket): Stream;
+/**
+ * Check if a WebSocket is in a state that can receive messages
+ */
+export declare function isWebSocketOpen(ws: WebSocket): boolean;
+/**
+ * Check if a WebSocket is connecting
+ */
+export declare function isWebSocketConnecting(ws: WebSocket): boolean;
+//# sourceMappingURL=websocket-stream.d.ts.map

package/dist/acp/websocket-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-stream.d.ts","sourceRoot":"","sources":["../../src/acp/websocket-stream.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAGpC,YAAY,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAGvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAMvD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CA+FrD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAEtD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAE5D"}

package/dist/acp/websocket-stream.js

@@ -0,0 +1,118 @@
+/**
+ * WebSocket Stream Adapter for ACP
+ *
+ * Adapts a WebSocket connection to the ACP SDK's Stream interface.
+ * Unlike ndJsonStream (used for stdio), this doesn't need newline delimiters
+ * since WebSocket already frames messages.
+ */
+/**
+ * Create an ACP Stream from a WebSocket connection.
+ *
+ * This adapts a WebSocket to the bidirectional Stream interface expected
+ * by AgentSideConnection. Each WebSocket message is a complete JSON-RPC
+ * message (no newline delimiters needed).
+ *
+ * @param ws - The WebSocket connection to adapt
+ * @returns A Stream for bidirectional ACP communication
+ */
+export function webSocketStream(ws) {
+    // Track if the stream has been closed to prevent double-close
+    let isClosed = false;
+    const readable = new ReadableStream({
+        start(controller) {
+            // Handle incoming messages
+            ws.on("message", (data) => {
+                if (isClosed)
+                    return;
+                try {
+                    const text = data instanceof Buffer
+                        ? data.toString("utf-8")
+                        : Buffer.from(data).toString("utf-8");
+                    const message = JSON.parse(text);
+                    controller.enqueue(message);
+                }
+                catch (err) {
+                    console.error("[websocket-stream] Failed to parse message:", err);
+                    // Don't close the stream on parse errors - just log and continue
+                }
+            });
+            // Handle connection close
+            ws.on("close", () => {
+                if (!isClosed) {
+                    isClosed = true;
+                    controller.close();
+                }
+            });
+            // Handle errors
+            ws.on("error", (err) => {
+                if (!isClosed) {
+                    isClosed = true;
+                    controller.error(err);
+                }
+            });
+        },
+        cancel() {
+            // Called when the readable stream is cancelled
+            if (!isClosed) {
+                isClosed = true;
+                ws.close(1000, "Stream cancelled");
+            }
+        },
+    });
+    const writable = new WritableStream({
+        write(message) {
+            return new Promise((resolve, reject) => {
+                if (ws.readyState !== ws.OPEN) {
+                    // Silently drop messages if connection is not open
+                    // This can happen during shutdown
+                    resolve();
+                    return;
+                }
+                try {
+                    const data = JSON.stringify(message);
+                    ws.send(data, (err) => {
+                        if (err) {
+                            reject(err);
+                        }
+                        else {
+                            resolve();
+                        }
+                    });
+                }
+                catch (err) {
+                    reject(err);
+                }
+            });
+        },
+        close() {
+            // Close the WebSocket when the writable stream is closed
+            if (ws.readyState === ws.OPEN) {
+                ws.close(1000, "Stream closed");
+            }
+            return Promise.resolve();
+        },
+        abort(reason) {
+            // Abort the connection
+            if (ws.readyState === ws.OPEN) {
+                ws.close(1011, String(reason));
+            }
+            return Promise.resolve();
+        },
+    });
+    // Cast to Stream - the SDK's Stream type uses AnyMessage which is compatible
+    // with our Record<string, unknown> type
+    return { readable, writable };
+}
+/**
+ * Check if a WebSocket is in a state that can receive messages
+ */
+export function isWebSocketOpen(ws) {
+    return ws.readyState === ws.OPEN;
+}
+/**
+ * Check if a WebSocket is connecting
+ */
+export function isWebSocketConnecting(ws) {
+    return ws.readyState === ws.CONNECTING;
+}
+//# sourceMappingURL=websocket-stream.js.map

package/dist/acp/websocket-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-stream.js","sourceRoot":"","sources":["../../src/acp/websocket-stream.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,EAAa;IAC3C,8DAA8D;IAC9D,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAa;QAC9C,KAAK,CAAC,UAAU;YACd,2BAA2B;YAC3B,EAAE,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,IAAqC,EAAE,EAAE;gBACzD,IAAI,QAAQ;oBAAE,OAAO;gBAErB,IAAI,CAAC;oBACH,MAAM,IAAI,GACR,IAAI,YAAY,MAAM;wBACpB,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;wBACxB,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAmB,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;oBAEzD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAe,CAAC;oBAC/C,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;gBAC9B,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO,CAAC,KAAK,CAAC,6CAA6C,EAAE,GAAG,CAAC,CAAC;oBAClE,iEAAiE;gBACnE,CAAC;YACH,CAAC,CAAC,CAAC;YAEH,0BAA0B;YAC1B,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;gBAClB,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACd,QAAQ,GAAG,IAAI,CAAC;oBAChB,UAAU,CAAC,KAAK,EAAE,CAAC;gBACrB,CAAC;YACH,CAAC,CAAC,CAAC;YAEH,gBAAgB;YAChB,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;gBACrB,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACd,QAAQ,GAAG,IAAI,CAAC;oBAChB,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;gBACxB,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC;QAED,MAAM;YACJ,+CAA+C;YAC/C,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,QAAQ,GAAG,IAAI,CAAC;gBAChB,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;YACrC,CAAC;QACH,CAAC;KACF,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAa;QAC9C,KAAK,CAAC,OAAO;YACX,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC3C,IAAI,EAAE,CAAC,UAAU,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC;oBAC9B,mDAAmD;oBACnD,kCAAkC;oBAClC,OAAO,EAAE,CAAC;oBACV,OAAO;gBACT,CAAC;gBAED,IAAI,CAAC;oBACH,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;oBACrC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE;wBACpB,IAAI,GAAG,EAAE,CAAC;4BACR,MAAM,CAAC,GAAG,CAAC,CAAC;wBACd,CAAC;6BAAM,CAAC;4BACN,OAAO,EAAE,CAAC;wBACZ,CAAC;oBACH,CAAC,CAAC,CAAC;gBACL,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,CAAC,GAAG,CAAC,CAAC;gBACd,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC;QAED,KAAK;YACH,yDAAyD;YACzD,IAAI,EAAE,CAAC,UAAU,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC;gBAC9B,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;YAClC,CAAC;YACD,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QAED,KAAK,CAAC,MAAM;YACV,uBAAuB;YACvB,IAAI,EAAE,CAAC,UAAU,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC;gBAC9B,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;YACjC,CAAC;YACD,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;KACF,CAAC,CAAC;IAEH,6EAA6E;IAC7E,wCAAwC;IACxC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAuB,CAAC;AACrD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,EAAa;IAC3C,OAAO,EAAE,CAAC,UAAU,KAAK,EAAE,CAAC,IAAI,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,EAAa;IACjD,OAAO,EAAE,CAAC,UAAU,KAAK,EAAE,CAAC,UAAU,CAAC;AACzC,CAAC"}

package/dist/activity/deduplication.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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";
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * Activity deduplicator using slot-based pattern.
+ *
+ * Prevents the same agent from being notified multiple times for similar
+ * events within a configurable time window.
+ */
+export declare class ActivityDeduplicator {
+    private slots;
+    private config;
+    constructor(config?: Partial<DeduplicationConfig>);
+    /**
+     * 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;
+    /**
+     * Mark a notification as sent (update slot timestamp).
+     */
+    markNotified(agentId: AgentId, activity: Activity): void;
+    /**
+     * Get suppression stats for debugging.
+     */
+    getStats(): {
+        totalSlots: number;
+        totalSuppressed: number;
+    };
+    /**
+     * Clear all slots.
+     */
+    clear(): void;
+    /**
+     * Clear expired slots (outside deduplication window).
+     */
+    clearExpired(): number;
+    /**
+     * Build a slot key from deduplication key components.
+     */
+    private buildKey;
+    /**
+     * Evict oldest entries if over max slots.
+     */
+    private evictIfNeeded;
+}
+/**
+ * Create an activity deduplicator with the given configuration.
+ */
+export declare function createDeduplicator(config?: Partial<DeduplicationConfig>): ActivityDeduplicator;
+//# sourceMappingURL=deduplication.d.ts.map

package/dist/activity/deduplication.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deduplication.d.ts","sourceRoot":"","sources":["../../src/activity/deduplication.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAM9D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2BAA2B;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,iBAAiB;IACjB,SAAS,EAAE,iBAAiB,GAAG,MAAM,CAAC;IACtC,wDAAwD;IACxD,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAcD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,eAAe,EAAE,OAAO,CAAC;CAC1B;AAYD;;;;;GAKG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,MAAM,CAAsB;gBAExB,MAAM,GAAE,OAAO,CAAC,mBAAmB,CAAM;IAIrD;;;;;;OAMG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO;IAkC3D;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAgBxD;;OAEG;IACH,QAAQ,IAAI;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE;IAW3D;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,YAAY,IAAI,MAAM;IActB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAQhB;;OAEG;IACH,OAAO,CAAC,aAAa;CAetB;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GACpC,oBAAoB,CAEtB"}

package/dist/activity/deduplication.js

@@ -0,0 +1,149 @@
+/**
+ * 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
+ */
+const DEFAULT_DEDUP_CONFIG = {
+    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 {
+    slots = new Map();
+    config;
+    constructor(config = {}) {
+        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, activity) {
+        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, activity) {
+        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() {
+        let totalSuppressed = 0;
+        for (const slot of this.slots.values()) {
+            totalSuppressed += slot.suppressedCount;
+        }
+        return {
+            totalSlots: this.slots.size,
+            totalSuppressed,
+        };
+    }
+    /**
+     * Clear all slots.
+     */
+    clear() {
+        this.slots.clear();
+    }
+    /**
+     * Clear expired slots (outside deduplication window).
+     */
+    clearExpired() {
+        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.
+     */
+    buildKey(keyParts) {
+        const parts = [keyParts.agentId, keyParts.eventType];
+        if (keyParts.sourceAgentId) {
+            parts.push(keyParts.sourceAgentId);
+        }
+        return parts.join("::");
+    }
+    /**
+     * Evict oldest entries if over max slots.
+     */
+    evictIfNeeded() {
+        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) {
+    return new ActivityDeduplicator(config);
+}
+//# sourceMappingURL=deduplication.js.map

package/dist/activity/deduplication.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deduplication.js","sourceRoot":"","sources":["../../src/activity/deduplication.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA6CH,MAAM,oBAAoB,GAAwB;IAChD,QAAQ,EAAE,IAAI;IACd,QAAQ,EAAE,KAAK;IACf,eAAe,EAAE,IAAI;CACtB,CAAC;AAEF,gFAAgF;AAChF,8BAA8B;AAC9B,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,OAAO,oBAAoB;IACvB,KAAK,GAAG,IAAI,GAAG,EAAqB,CAAC;IACrC,MAAM,CAAsB;IAEpC,YAAY,SAAuC,EAAE;QACnD,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,oBAAoB,EAAE,GAAG,MAAM,EAAE,CAAC;IACvD,CAAC;IAED;;;;;;OAMG;IACH,YAAY,CAAC,OAAgB,EAAE,QAAkB;QAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC;YACxB,OAAO;YACP,SAAS,EAAE,QAAQ,CAAC,IAAI;YACxB,aAAa,EAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ;SACzC,CAAC,CAAC;QAEH,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAErC,IAAI,QAAQ,EAAE,CAAC;YACb,uCAAuC;YACvC,IAAI,GAAG,GAAG,QAAQ,CAAC,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACvD,wBAAwB;gBACxB,IAAI,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;oBAChC,QAAQ,CAAC,eAAe,EAAE,CAAC;gBAC7B,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,cAAc;QACd,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YAClB,GAAG;YACH,YAAY,EAAE,GAAG;YACjB,eAAe,EAAE,CAAC;SACnB,CAAC,CAAC;QAEH,8BAA8B;QAC9B,IAAI,CAAC,aAAa,EAAE,CAAC;QAErB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,OAAgB,EAAE,QAAkB;QAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC;YACxB,OAAO;YACP,SAAS,EAAE,QAAQ,CAAC,IAAI;YACxB,aAAa,EAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ;SACzC,CAAC,CAAC;QAEH,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YAClB,GAAG;YACH,YAAY,EAAE,IAAI,CAAC,GAAG,EAAE;YACxB,eAAe,EAAE,CAAC;SACnB,CAAC,CAAC;QAEH,IAAI,CAAC,aAAa,EAAE,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,IAAI,eAAe,GAAG,CAAC,CAAC;QACxB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YACvC,eAAe,IAAI,IAAI,CAAC,eAAe,CAAC;QAC1C,CAAC;QACD,OAAO;YACL,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;YAC3B,eAAe;SAChB,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,YAAY;QACV,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,OAAO,GAAG,CAAC,CAAC;QAEhB,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACrC,IAAI,GAAG,GAAG,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACpD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACvB,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACK,QAAQ,CAAC,QAA0B;QACzC,MAAM,KAAK,GAAG,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;QACrD,IAAI,QAAQ,CAAC,aAAa,EAAE,CAAC;YAC3B,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;QACrC,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;OAEG;IACK,aAAa;QACnB,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YAC5C,OAAO;QACT,CAAC;QAED,iCAAiC;QACjC,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAC5C,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAChD,CAAC;QAEF,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC1E,KAAK,MAAM,CAAC,GAAG,CAAC,IAAI,QAAQ,EAAE,CAAC;YAC7B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;CACF;AAED,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAqC;IAErC,OAAO,IAAI,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC1C,CAAC"}