agent-relay 2.3.13 → 2.4.0

package/packages/sdk/src/shadow.ts

@@ -0,0 +1,228 @@
+/**
+ * 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}`,
+ *     });
+ *   }
+ * };
+ * ```
+ */
+
+import type { SpeakOnTrigger } from '@agent-relay/config';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+// Re-export from config to maintain backwards compatibility
+export type { SpeakOnTrigger };
+
+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/src/spawn-from-env.ts

@@ -0,0 +1,245 @@
+/**
+ * Canonical spawn-from-env module.
+ *
+ * Single source of truth for environment-driven agent spawning with
+ * SDK-owned bypass policy. Cloud callers set env vars and invoke
+ * `spawnFromEnv()` — no custom bypass logic, no spawn scripts.
+ *
+ * @example
+ * ```ts
+ * import { spawnFromEnv } from "@agent-relay/sdk";
+ * await spawnFromEnv(); // reads AGENT_NAME, AGENT_CLI, etc. from process.env
+ * ```
+ */
+
+import { AgentRelay } from "./relay.js";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface SpawnEnvInput {
+  AGENT_NAME: string;
+  AGENT_CLI: string;
+  RELAY_API_KEY: string;
+  AGENT_TASK?: string;
+  /** JSON array preferred, space-delimited fallback */
+  AGENT_ARGS?: string;
+  AGENT_CWD?: string;
+  /** Comma-separated channel list, defaults to "general" */
+  AGENT_CHANNELS?: string;
+  RELAY_BASE_URL?: string;
+  BROKER_BINARY_PATH?: string;
+  /** Model override (e.g. "opus", "sonnet") */
+  AGENT_MODEL?: string;
+  /** "1" disables SDK default bypass flags */
+  AGENT_DISABLE_DEFAULT_BYPASS?: string;
+}
+
+export interface SpawnPolicyResult {
+  name: string;
+  cli: string;
+  args: string[];
+  channels: string[];
+  task?: string;
+  cwd?: string;
+  model?: string;
+  bypassApplied: boolean;
+}
+
+export interface SpawnFromEnvOptions {
+  /** Override env source (defaults to process.env) */
+  env?: Record<string, string | undefined>;
+  /** Override binary path */
+  binaryPath?: string;
+  /** Override broker name */
+  brokerName?: string;
+}
+
+export interface SpawnFromEnvResult {
+  exitReason: string;
+  exitCode?: number;
+}
+
+// ── Bypass Policy (SDK-owned, single source of truth) ──────────────────────
+
+/** SDK-owned bypass flag mapping. Cloud must NOT duplicate these. */
+const BYPASS_FLAGS: Record<string, string> = {
+  claude: "--dangerously-skip-permissions",
+  codex: "--full-auto",
+};
+
+/**
+ * Resolve the bypass flag for a CLI.
+ * Handles `claude:model` variants (e.g. `claude:opus`).
+ */
+function getBypassFlag(cli: string): string | undefined {
+  const baseCli = cli.includes(":") ? cli.split(":")[0] : cli;
+  return BYPASS_FLAGS[baseCli];
+}
+
+// ── Env Parsing ────────────────────────────────────────────────────────────
+
+/**
+ * Parse and validate spawn environment variables.
+ * Throws with a clear message on missing required keys.
+ */
+export function parseSpawnEnv(
+  env: Record<string, string | undefined> = process.env,
+): SpawnEnvInput {
+  const AGENT_NAME = env.AGENT_NAME;
+  const AGENT_CLI = env.AGENT_CLI;
+  const RELAY_API_KEY = env.RELAY_API_KEY;
+
+  const missing: string[] = [];
+  if (!AGENT_NAME) missing.push("AGENT_NAME");
+  if (!AGENT_CLI) missing.push("AGENT_CLI");
+  if (!RELAY_API_KEY) missing.push("RELAY_API_KEY");
+
+  if (missing.length > 0) {
+    throw new Error(
+      `[spawn-from-env] Missing required environment variables: ${missing.join(", ")}`,
+    );
+  }
+
+  return {
+    AGENT_NAME: AGENT_NAME!,
+    AGENT_CLI: AGENT_CLI!,
+    RELAY_API_KEY: RELAY_API_KEY!,
+    AGENT_TASK: env.AGENT_TASK || undefined,
+    AGENT_ARGS: env.AGENT_ARGS || undefined,
+    AGENT_CWD: env.AGENT_CWD || undefined,
+    AGENT_CHANNELS: env.AGENT_CHANNELS || undefined,
+    RELAY_BASE_URL: env.RELAY_BASE_URL || undefined,
+    BROKER_BINARY_PATH: env.BROKER_BINARY_PATH || undefined,
+    AGENT_MODEL: env.AGENT_MODEL || undefined,
+    AGENT_DISABLE_DEFAULT_BYPASS: env.AGENT_DISABLE_DEFAULT_BYPASS || undefined,
+  };
+}
+
+// ── Policy Resolution ──────────────────────────────────────────────────────
+
+/**
+ * Parse extra args from env. Supports JSON array or space-delimited string.
+ */
+function parseArgs(raw: string | undefined): string[] {
+  if (!raw) return [];
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (Array.isArray(parsed)) return parsed.map(String);
+    } catch {
+      // Fall through to space-delimited
+    }
+  }
+  return trimmed.split(/\s+/).filter(Boolean);
+}
+
+/**
+ * Resolve the full spawn policy from parsed env input.
+ * Applies bypass flags unless disabled or already present.
+ */
+export function resolveSpawnPolicy(input: SpawnEnvInput): SpawnPolicyResult {
+  const extraArgs = parseArgs(input.AGENT_ARGS);
+  const channels = input.AGENT_CHANNELS
+    ? input.AGENT_CHANNELS.split(",")
+        .map((c) => c.trim())
+        .filter(Boolean)
+    : ["general"];
+
+  const disableBypass = input.AGENT_DISABLE_DEFAULT_BYPASS === "1";
+  const bypassFlag = getBypassFlag(input.AGENT_CLI);
+
+  let bypassApplied = false;
+  const args = [...extraArgs];
+
+  if (bypassFlag && !disableBypass && !args.includes(bypassFlag)) {
+    args.push(bypassFlag);
+    bypassApplied = true;
+  }
+
+  return {
+    name: input.AGENT_NAME,
+    cli: input.AGENT_CLI,
+    args,
+    channels,
+    task: input.AGENT_TASK,
+    cwd: input.AGENT_CWD,
+    model: input.AGENT_MODEL,
+    bypassApplied,
+  };
+}
+
+// ── Main Entry Point ───────────────────────────────────────────────────────
+
+/**
+ * Spawn an agent from environment variables.
+ *
+ * Reads AGENT_NAME, AGENT_CLI, RELAY_API_KEY (required) plus optional
+ * AGENT_TASK, AGENT_ARGS, AGENT_CWD, AGENT_CHANNELS, AGENT_MODEL from
+ * the environment.
+ *
+ * Applies canonical bypass flags (claude -> --dangerously-skip-permissions,
+ * codex -> --full-auto) unless AGENT_DISABLE_DEFAULT_BYPASS=1.
+ *
+ * Creates a broker, spawns the agent via PTY, and waits for exit.
+ * Returns the exit reason and exit code.
+ */
+export async function spawnFromEnv(
+  options: SpawnFromEnvOptions = {},
+): Promise<SpawnFromEnvResult> {
+  const env =
+    options.env ?? (process.env as Record<string, string | undefined>);
+  const parsed = parseSpawnEnv(env);
+  const policy = resolveSpawnPolicy(parsed);
+
+  console.log(
+    `[spawn-from-env] Spawning agent: name=${policy.name} cli=${policy.cli} ` +
+      `channels=${policy.channels.join(",")} bypass=${policy.bypassApplied}`,
+  );
+  if (policy.task) {
+    console.log(
+      `[spawn-from-env] Task: ${policy.task.slice(0, 200)}${policy.task.length > 200 ? "..." : ""}`,
+    );
+  }
+
+  const relay = new AgentRelay({
+    binaryPath: options.binaryPath ?? parsed.BROKER_BINARY_PATH,
+    brokerName: options.brokerName ?? `broker-${policy.name}`,
+    channels: policy.channels,
+    cwd: policy.cwd ?? process.cwd(),
+    env: env as NodeJS.ProcessEnv,
+  });
+
+  relay.onAgentSpawned = (agent) => {
+    console.log(`[spawn-from-env] Agent spawned: ${agent.name}`);
+  };
+  relay.onAgentReady = (agent) => {
+    console.log(`[spawn-from-env] Agent ready: ${agent.name}`);
+  };
+  relay.onAgentExited = (agent) => {
+    console.log(
+      `[spawn-from-env] Agent exited: ${agent.name} ` +
+        `code=${agent.exitCode ?? "none"} signal=${agent.exitSignal ?? "none"}`,
+    );
+  };
+
+  try {
+    const agent = await relay.spawnPty({
+      name: policy.name,
+      cli: policy.cli,
+      args: policy.args,
+      channels: policy.channels,
+      task: policy.task,
+    });
+
+    const exitReason = await agent.waitForExit();
+    console.log(`[spawn-from-env] Exit reason: ${exitReason}`);
+
+    return { exitReason, exitCode: agent.exitCode };
+  } catch (err) {
+    console.error(`[spawn-from-env] Error:`, err);
+    throw err;
+  } finally {
+    await relay.shutdown();
+  }
+}