agent-relay 2.2.23 → 2.3.0

package/packages/sdk-ts/src/shadow.ts

@@ -0,0 +1,230 @@
+/**
+ * Shadow agent support for the broker SDK.
+ *
+ * A shadow agent monitors all messages to/from a primary agent.
+ * Implemented SDK-side using the event hook system — no broker
+ * protocol extension required.
+ *
+ * @example
+ * ```ts
+ * import { AgentRelay, ShadowManager } from "agent-relay/broker";
+ *
+ * const relay = new AgentRelay();
+ * const shadows = new ShadowManager();
+ *
+ * // Bind "Reviewer" as shadow of "Worker1"
+ * shadows.bind("Reviewer", "Worker1");
+ *
+ * // Wire into relay events
+ * relay.onMessageReceived = (msg) => {
+ *   const copies = shadows.intercept(msg.from, msg.to, msg);
+ *   for (const copy of copies) {
+ *     // Forward shadow copies to the shadow agent
+ *     relay.human({ name: "system" }).sendMessage({
+ *       to: copy.shadowAgent,
+ *       text: `[Shadow of ${copy.primaryAgent}] ${msg.text}`,
+ *     });
+ *   }
+ * };
+ * ```
+ */
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export type SpeakOnTrigger =
+  | "ALL_MESSAGES"
+  | "EXPLICIT_ASK"
+  | "SESSION_END"
+  | "CODE_WRITTEN"
+  | "REVIEW_REQUEST";
+
+export interface ShadowConfig {
+  primaryAgent: string;
+  speakOn: SpeakOnTrigger[];
+  receiveIncoming: boolean;
+  receiveOutgoing: boolean;
+}
+
+export interface ShadowRelationship extends ShadowConfig {
+  shadowAgent: string;
+}
+
+export interface ShadowCopy {
+  shadowAgent: string;
+  primaryAgent: string;
+  direction: "incoming" | "outgoing";
+}
+
+// ── Manager ──────────────────────────────────────────────────────────────────
+
+export class ShadowManager {
+  /** primaryAgent → list of shadow relationships */
+  private shadowsByPrimary = new Map<string, ShadowRelationship[]>();
+  /** shadowAgent → primaryAgent (reverse lookup) */
+  private primaryByShadow = new Map<string, string>();
+
+  /**
+   * Bind a shadow agent to monitor a primary agent.
+   */
+  bind(
+    shadowAgent: string,
+    primaryAgent: string,
+    options: {
+      speakOn?: SpeakOnTrigger[];
+      receiveIncoming?: boolean;
+      receiveOutgoing?: boolean;
+    } = {},
+  ): void {
+    // Clean up any existing binding for this shadow
+    this.unbind(shadowAgent);
+
+    const relationship: ShadowRelationship = {
+      shadowAgent,
+      primaryAgent,
+      speakOn: options.speakOn ?? ["EXPLICIT_ASK"],
+      receiveIncoming: options.receiveIncoming ?? true,
+      receiveOutgoing: options.receiveOutgoing ?? true,
+    };
+
+    let shadows = this.shadowsByPrimary.get(primaryAgent);
+    if (!shadows) {
+      shadows = [];
+      this.shadowsByPrimary.set(primaryAgent, shadows);
+    }
+    shadows.push(relationship);
+    this.primaryByShadow.set(shadowAgent, primaryAgent);
+  }
+
+  /**
+   * Unbind a shadow from its primary.
+   */
+  unbind(shadowAgent: string): void {
+    const primaryAgent = this.primaryByShadow.get(shadowAgent);
+    if (!primaryAgent) return;
+
+    const shadows = this.shadowsByPrimary.get(primaryAgent);
+    if (shadows) {
+      const updated = shadows.filter((s) => s.shadowAgent !== shadowAgent);
+      if (updated.length === 0) {
+        this.shadowsByPrimary.delete(primaryAgent);
+      } else {
+        this.shadowsByPrimary.set(primaryAgent, updated);
+      }
+    }
+    this.primaryByShadow.delete(shadowAgent);
+  }
+
+  /**
+   * Get all shadows for a primary agent.
+   */
+  getShadowsFor(primaryAgent: string): ShadowRelationship[] {
+    return this.shadowsByPrimary.get(primaryAgent) ?? [];
+  }
+
+  /**
+   * Get the primary agent a shadow is bound to.
+   */
+  getPrimaryFor(shadowAgent: string): string | undefined {
+    return this.primaryByShadow.get(shadowAgent);
+  }
+
+  /**
+   * Check whether a shadow should speak for a given trigger.
+   */
+  shouldSpeak(shadowAgent: string, trigger: SpeakOnTrigger): boolean {
+    const primary = this.primaryByShadow.get(shadowAgent);
+    if (!primary) return true; // not a shadow, always speaks
+
+    const shadows = this.shadowsByPrimary.get(primary);
+    if (!shadows) return true;
+
+    const rel = shadows.find((s) => s.shadowAgent === shadowAgent);
+    if (!rel) return true;
+
+    return (
+      rel.speakOn.includes(trigger) || rel.speakOn.includes("ALL_MESSAGES")
+    );
+  }
+
+  /**
+   * Determine which shadows should receive a copy of a message
+   * between `from` and `to`. Returns a list of shadow copies to deliver.
+   *
+   * Call this from your `onMessageReceived` / `onMessageSent` hooks
+   * to fan out shadow copies.
+   */
+  intercept(from: string, to: string): ShadowCopy[] {
+    const copies: ShadowCopy[] = [];
+
+    // Outgoing shadows of the sender
+    const senderShadows = this.shadowsByPrimary.get(from);
+    if (senderShadows) {
+      for (const s of senderShadows) {
+        if (s.receiveOutgoing && s.shadowAgent !== to) {
+          copies.push({
+            shadowAgent: s.shadowAgent,
+            primaryAgent: from,
+            direction: "outgoing",
+          });
+        }
+      }
+    }
+
+    // Incoming shadows of the recipient
+    if (to && to !== "*") {
+      const recipientShadows = this.shadowsByPrimary.get(to);
+      if (recipientShadows) {
+        for (const s of recipientShadows) {
+          if (s.receiveIncoming && s.shadowAgent !== from) {
+            copies.push({
+              shadowAgent: s.shadowAgent,
+              primaryAgent: to,
+              direction: "incoming",
+            });
+          }
+        }
+      }
+    }
+
+    return copies;
+  }
+
+  /**
+   * Emit a trigger event and return shadow agents that should be notified.
+   *
+   * Use this to implement `speakOn` behavior — when a trigger fires
+   * (e.g. CODE_WRITTEN, REVIEW_REQUEST), call this to find which
+   * shadows should receive a notification.
+   */
+  emitTrigger(
+    primaryAgent: string,
+    trigger: SpeakOnTrigger,
+  ): string[] {
+    const shadows = this.shadowsByPrimary.get(primaryAgent) ?? [];
+    return shadows
+      .filter(
+        (s) =>
+          s.speakOn.includes(trigger) || s.speakOn.includes("ALL_MESSAGES"),
+      )
+      .map((s) => s.shadowAgent);
+  }
+
+  /**
+   * List all current shadow bindings.
+   */
+  listBindings(): ShadowRelationship[] {
+    const all: ShadowRelationship[] = [];
+    for (const shadows of this.shadowsByPrimary.values()) {
+      all.push(...shadows);
+    }
+    return all;
+  }
+
+  /**
+   * Remove all bindings (for shutdown).
+   */
+  clear(): void {
+    this.shadowsByPrimary.clear();
+    this.primaryByShadow.clear();
+  }
+}

package/packages/sdk-ts/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"],
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/packages/spawner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/spawner",
-  "version": "2.2.23",
+  "version": "2.3.0",
   "description": "Agent spawning types and utilities for Agent Relay",
   "type": "module",
   "main": "dist/index.js",

package/packages/state/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/state",
-  "version": "2.2.23",
+  "version": "2.3.0",
   "description": "Agent state persistence for non-hook CLIs (Codex, Gemini, etc.)",
   "type": "module",
   "main": "dist/index.js",

package/packages/storage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/storage",
-  "version": "2.2.23",
+  "version": "2.3.0",
   "description": "Storage adapters and interfaces for Relay message/session persistence",
   "type": "module",
   "main": "dist/index.js",
@@ -56,7 +56,7 @@
     }
   },
   "dependencies": {
-    "@agent-relay/protocol": "2.2.23"
+    "@agent-relay/protocol": "2.3.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/telemetry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/telemetry",
-  "version": "2.2.23",
+  "version": "2.3.0",
   "description": "Anonymous telemetry for Agent Relay usage analytics",
   "type": "module",
   "main": "dist/index.js",

package/packages/trajectory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/trajectory",
-  "version": "2.2.23",
+  "version": "2.3.0",
   "description": "Trajectory integration utilities (trail/PDERO) for Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "2.2.23"
+    "@agent-relay/config": "2.3.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/user-directory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/user-directory",
-  "version": "2.2.23",
+  "version": "2.3.0",
   "description": "User directory service for agent-relay (per-user credential storage)",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/resiliency": "2.2.23"
+    "@agent-relay/resiliency": "2.3.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/utils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/utils",
-  "version": "2.2.23",
+  "version": "2.3.0",
   "description": "Shared utilities for agent-relay: logging, name generation, command resolution, update checking",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -112,8 +112,8 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@agent-relay/config": "2.2.23",
-    "@agent-relay/protocol": "2.2.23",
+    "@agent-relay/config": "2.3.0",
+    "@agent-relay/protocol": "2.3.0",
     "compare-versions": "^6.1.1"
   },
   "publishConfig": {

package/packages/wrapper/dist/client.js

@@ -568,7 +568,7 @@ export class RelayClient {
                 shadowTriggers: options.shadowTriggers,
                 shadowSpeakOn: options.shadowSpeakOn,
             };
-            const result = await this.requestResponse('SPAWN', payload, 30000 // 30 second timeout for spawn
+            const result = await this.requestResponse('SPAWN', payload, 60000 // 60 second timeout for spawn
             );
             return toSpawnResult(result);
         }

package/packages/wrapper/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/wrapper",
-  "version": "2.2.23",
+  "version": "2.3.0",
   "description": "CLI agent wrappers for Agent Relay - tmux, pty integration",
   "type": "module",
   "main": "dist/index.js",
@@ -30,11 +30,11 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@agent-relay/api-types": "2.2.23",
-    "@agent-relay/protocol": "2.2.23",
-    "@agent-relay/config": "2.2.23",
-    "@agent-relay/continuity": "2.2.23",
-    "@agent-relay/resiliency": "2.2.23",
+    "@agent-relay/api-types": "2.3.0",
+    "@agent-relay/protocol": "2.3.0",
+    "@agent-relay/config": "2.3.0",
+    "@agent-relay/continuity": "2.3.0",
+    "@agent-relay/resiliency": "2.3.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {

package/packages/wrapper/src/client.test.ts

@@ -290,7 +290,7 @@ describe('RelayClient', () => {
           model: 'opus',
           cwd: '/test/path',
         }),
-        30000
+        60000
       );
       expect(result.success).toBe(true);
     });

package/packages/wrapper/src/client.ts

@@ -750,7 +750,7 @@ export class RelayClient {
       const result = await this.requestResponse<SpawnResultPayload>(
         'SPAWN',
         payload as unknown as Record<string, unknown>,
-        30000 // 30 second timeout for spawn
+        60000 // 60 second timeout for spawn
       );
 
       return toSpawnResult(result);