agent-relay 1.0.22 → 1.2.0

package/README.md

@@ -190,7 +190,7 @@ prpm install @agent-relay/agent-relay-snippet --location CLAUDE.md
 
 `agent-relay up` starts a web dashboard at http://localhost:3888
 
-![Agent Relay Dashboard](dashboard.png)
+![Agent Relay Dashboard](docs/dashboard.png)
 
 ## Development
 

package/dist/bridge/shadow-cli.d.ts

@@ -0,0 +1,17 @@
+export type ShadowCli = 'claude' | 'codex';
+export type ShadowMode = 'subagent' | 'process';
+export interface ShadowCliSelection {
+    cli: ShadowCli;
+    /** Actual command to execute when spawning a process */
+    command: string;
+    mode: ShadowMode;
+}
+/**
+ * Select the shadow CLI and execution mode based on the primary agent's CLI.
+ * - Claude/OpenCode primaries run shadows as subagents (Task tool)
+ * - Others fall back to spawning a process using an authenticated CLI
+ */
+export declare function selectShadowCli(primaryCli: string, options?: {
+    preferredShadowCli?: string;
+}): Promise<ShadowCliSelection>;
+//# sourceMappingURL=shadow-cli.d.ts.map

package/dist/bridge/shadow-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow-cli.d.ts","sourceRoot":"","sources":["../../src/bridge/shadow-cli.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC3C,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;AAEhD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,SAAS,CAAC;IACf,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;CAClB;AAsCD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;IAAE,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC,OAAO,CAAC,kBAAkB,CAAC,CAkC7B"}

package/dist/bridge/shadow-cli.js

@@ -0,0 +1,75 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { commandExists } from '../utils/command-resolver.js';
+const execFileAsync = promisify(execFile);
+/** Normalize CLI name to a supported identifier */
+function normalizeCli(cli) {
+    if (!cli)
+        return null;
+    const base = cli.trim().split(' ')[0]; // Strip any args
+    const [command] = base.split(':'); // Handle variants like claude:opus
+    const lower = command.toLowerCase();
+    if (lower.startsWith('claude'))
+        return 'claude';
+    if (lower === 'codex' || lower === 'opencode')
+        return 'codex';
+    return null;
+}
+async function isCommandAuthenticated(command) {
+    if (!commandExists(command))
+        return false;
+    try {
+        await execFileAsync(command, ['--version'], { timeout: 4000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function detectAuthenticatedCommand(cli) {
+    const candidates = cli === 'claude' ? ['claude'] : ['codex', 'opencode'];
+    for (const candidate of candidates) {
+        if (await isCommandAuthenticated(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Select the shadow CLI and execution mode based on the primary agent's CLI.
+ * - Claude/OpenCode primaries run shadows as subagents (Task tool)
+ * - Others fall back to spawning a process using an authenticated CLI
+ */
+export async function selectShadowCli(primaryCli, options) {
+    const primary = normalizeCli(primaryCli);
+    const preferred = normalizeCli(options?.preferredShadowCli);
+    // Native subagent support for Claude/OpenCode primaries
+    if (primary) {
+        return {
+            cli: primary,
+            command: primary === 'claude' ? 'claude' : 'codex',
+            mode: 'subagent',
+        };
+    }
+    // Process-mode fallback for non-supporting primaries
+    const fallbackOrder = [];
+    if (preferred)
+        fallbackOrder.push(preferred);
+    fallbackOrder.push('claude', 'codex');
+    const seen = new Set();
+    for (const candidate of fallbackOrder) {
+        if (seen.has(candidate))
+            continue;
+        seen.add(candidate);
+        const authenticatedCommand = await detectAuthenticatedCommand(candidate);
+        if (authenticatedCommand) {
+            return {
+                cli: candidate,
+                command: authenticatedCommand,
+                mode: 'process',
+            };
+        }
+    }
+    throw new Error('No shadow-capable CLI authenticated. Install Claude or OpenCode (codex) and try again.');
+}
+//# sourceMappingURL=shadow-cli.js.map

package/dist/bridge/shadow-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow-cli.js","sourceRoot":"","sources":["../../src/bridge/shadow-cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAE7D,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAY1C,mDAAmD;AACnD,SAAS,YAAY,CAAC,GAAuB;IAC3C,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,iBAAiB;IACxD,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,mCAAmC;IACtE,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAEpC,IAAI,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAChD,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,UAAU;QAAE,OAAO,OAAO,CAAC;IAE9D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,KAAK,UAAU,sBAAsB,CAAC,OAAe;IACnD,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAE1C,IAAI,CAAC;QACH,MAAM,aAAa,CAAC,OAAO,EAAE,CAAC,WAAW,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/D,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,KAAK,UAAU,0BAA0B,CAAC,GAAc;IACtD,MAAM,UAAU,GAAG,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAEzE,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,MAAM,sBAAsB,CAAC,SAAS,CAAC,EAAE,CAAC;YAC5C,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,UAAkB,EAClB,OAAyC;IAEzC,MAAM,OAAO,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;IACzC,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;IAE5D,wDAAwD;IACxD,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO;YACL,GAAG,EAAE,OAAO;YACZ,OAAO,EAAE,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO;YAClD,IAAI,EAAE,UAAU;SACjB,CAAC;IACJ,CAAC;IAED,qDAAqD;IACrD,MAAM,aAAa,GAAgB,EAAE,CAAC;IACtC,IAAI,SAAS;QAAE,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC7C,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAEtC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAa,CAAC;IAClC,KAAK,MAAM,SAAS,IAAI,aAAa,EAAE,CAAC;QACtC,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,SAAS;QAClC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAEpB,MAAM,oBAAoB,GAAG,MAAM,0BAA0B,CAAC,SAAS,CAAC,CAAC;QACzE,IAAI,oBAAoB,EAAE,CAAC;YACzB,OAAO;gBACL,GAAG,EAAE,SAAS;gBACd,OAAO,EAAE,oBAAoB;gBAC7B,IAAI,EAAE,SAAS;aAChB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,wFAAwF,CAAC,CAAC;AAC5G,CAAC"}

package/dist/bridge/shadow-config.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Shadow Agent Configuration
+ * Handles loading and parsing shadow agent configuration from .agent-relay.json.
+ *
+ * Configuration can be placed in:
+ * - Project root: ./.agent-relay.json
+ * - Agent-relay dir: ./.agent-relay/config.json
+ *
+ * Shadow configuration structure:
+ * {
+ *   "shadows": {
+ *     "pairs": {
+ *       "Lead": { "shadow": "Auditor", "shadowRole": "reviewer" }
+ *     },
+ *     "roles": {
+ *       "reviewer": { "prompt": "Review code...", "speakOn": ["CODE_WRITTEN"] }
+ *     }
+ *   }
+ * }
+ */
+import type { SpeakOnTrigger } from '../protocol/types.js';
+/** Shadow role definition */
+export interface ShadowRoleConfig {
+    /** System prompt for this shadow role */
+    prompt?: string;
+    /** Triggers for when the shadow should speak */
+    speakOn: SpeakOnTrigger[];
+}
+/** Shadow pair definition */
+export interface ShadowPairConfig {
+    /** Name of the shadow agent */
+    shadow: string;
+    /** Role name (references roles config) or preset (reviewer, auditor, active) */
+    shadowRole?: string;
+    /** Override speakOn triggers (takes precedence over role) */
+    speakOn?: SpeakOnTrigger[];
+    /** CLI to use for shadow (defaults to same as primary) */
+    cli?: string;
+}
+/** Shadow configuration section */
+export interface ShadowConfig {
+    /** Primary -> Shadow mappings */
+    pairs: Record<string, ShadowPairConfig>;
+    /** Role definitions */
+    roles?: Record<string, ShadowRoleConfig>;
+}
+/** Full agent-relay configuration file structure */
+export interface AgentRelayConfig {
+    /** Shadow agent configuration */
+    shadows?: ShadowConfig;
+}
+/** Resolved shadow config for a primary agent */
+export interface ResolvedShadowConfig {
+    /** Shadow agent name */
+    shadowName: string;
+    /** Role name (for logging/display) */
+    roleName?: string;
+    /** Resolved speakOn triggers */
+    speakOn: SpeakOnTrigger[];
+    /** System prompt for the shadow */
+    prompt?: string;
+    /** CLI to use for shadow */
+    cli?: string;
+}
+/**
+ * Load agent-relay configuration from project root
+ * Returns null if no config found
+ */
+export declare function loadAgentRelayConfig(projectRoot: string): AgentRelayConfig | null;
+/**
+ * Get shadow configuration for a primary agent
+ * Returns null if no shadow configured for this agent
+ */
+export declare function getShadowForAgent(projectRoot: string, primaryAgentName: string): ResolvedShadowConfig | null;
+/**
+ * Get all configured shadow pairs
+ */
+export declare function getAllShadowPairs(projectRoot: string): Map<string, ResolvedShadowConfig>;
+/**
+ * Check if shadow config exists
+ */
+export declare function hasShadowConfig(projectRoot: string): boolean;
+/**
+ * Get the config file path that would be used
+ */
+export declare function getConfigPath(projectRoot: string): string | null;
+//# sourceMappingURL=shadow-config.d.ts.map

package/dist/bridge/shadow-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow-config.d.ts","sourceRoot":"","sources":["../../src/bridge/shadow-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,6BAA6B;AAC7B,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,6BAA6B;AAC7B,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACxC,uBAAuB;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC1C;AAED,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,OAAO,CAAC,EAAE,YAAY,CAAC;CAExB;AAED,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAmBD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAkBjF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,MAAM,GACvB,oBAAoB,GAAG,IAAI,CAwC7B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAgBxF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAG5D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQhE"}

package/dist/bridge/shadow-config.js

@@ -0,0 +1,134 @@
+/**
+ * Shadow Agent Configuration
+ * Handles loading and parsing shadow agent configuration from .agent-relay.json.
+ *
+ * Configuration can be placed in:
+ * - Project root: ./.agent-relay.json
+ * - Agent-relay dir: ./.agent-relay/config.json
+ *
+ * Shadow configuration structure:
+ * {
+ *   "shadows": {
+ *     "pairs": {
+ *       "Lead": { "shadow": "Auditor", "shadowRole": "reviewer" }
+ *     },
+ *     "roles": {
+ *       "reviewer": { "prompt": "Review code...", "speakOn": ["CODE_WRITTEN"] }
+ *     }
+ *   }
+ * }
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** Role presets matching CLI behavior */
+const ROLE_PRESETS = {
+    reviewer: ['CODE_WRITTEN', 'REVIEW_REQUEST', 'EXPLICIT_ASK'],
+    auditor: ['SESSION_END', 'EXPLICIT_ASK'],
+    active: ['ALL_MESSAGES'],
+};
+/**
+ * Possible locations for .agent-relay.json (in order of precedence)
+ */
+function getConfigPaths(projectRoot) {
+    return [
+        path.join(projectRoot, '.agent-relay', 'config.json'),
+        path.join(projectRoot, '.agent-relay.json'),
+    ];
+}
+/**
+ * Load agent-relay configuration from project root
+ * Returns null if no config found
+ */
+export function loadAgentRelayConfig(projectRoot) {
+    const configPaths = getConfigPaths(projectRoot);
+    for (const configPath of configPaths) {
+        if (fs.existsSync(configPath)) {
+            try {
+                const content = fs.readFileSync(configPath, 'utf-8');
+                const config = JSON.parse(content);
+                console.log(`[shadow-config] Loaded config from ${configPath}`);
+                return config;
+            }
+            catch (err) {
+                console.error(`[shadow-config] Failed to parse ${configPath}:`, err);
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Get shadow configuration for a primary agent
+ * Returns null if no shadow configured for this agent
+ */
+export function getShadowForAgent(projectRoot, primaryAgentName) {
+    const config = loadAgentRelayConfig(projectRoot);
+    if (!config?.shadows?.pairs) {
+        return null;
+    }
+    const pairConfig = config.shadows.pairs[primaryAgentName];
+    if (!pairConfig) {
+        return null;
+    }
+    // Resolve speakOn triggers
+    let speakOn = ['EXPLICIT_ASK']; // Default
+    let prompt;
+    const roleName = pairConfig.shadowRole;
+    // First, try to resolve from role preset
+    if (roleName && ROLE_PRESETS[roleName.toLowerCase()]) {
+        speakOn = ROLE_PRESETS[roleName.toLowerCase()];
+    }
+    // Then, try custom role from config
+    if (roleName && config.shadows.roles?.[roleName]) {
+        const roleConfig = config.shadows.roles[roleName];
+        speakOn = roleConfig.speakOn;
+        prompt = roleConfig.prompt;
+    }
+    // Finally, override with explicit speakOn if provided
+    if (pairConfig.speakOn && pairConfig.speakOn.length > 0) {
+        speakOn = pairConfig.speakOn;
+    }
+    return {
+        shadowName: pairConfig.shadow,
+        roleName,
+        speakOn,
+        prompt,
+        cli: pairConfig.cli,
+    };
+}
+/**
+ * Get all configured shadow pairs
+ */
+export function getAllShadowPairs(projectRoot) {
+    const config = loadAgentRelayConfig(projectRoot);
+    const result = new Map();
+    if (!config?.shadows?.pairs) {
+        return result;
+    }
+    for (const primaryName of Object.keys(config.shadows.pairs)) {
+        const resolved = getShadowForAgent(projectRoot, primaryName);
+        if (resolved) {
+            result.set(primaryName, resolved);
+        }
+    }
+    return result;
+}
+/**
+ * Check if shadow config exists
+ */
+export function hasShadowConfig(projectRoot) {
+    const config = loadAgentRelayConfig(projectRoot);
+    return !!(config?.shadows?.pairs && Object.keys(config.shadows.pairs).length > 0);
+}
+/**
+ * Get the config file path that would be used
+ */
+export function getConfigPath(projectRoot) {
+    const configPaths = getConfigPaths(projectRoot);
+    for (const configPath of configPaths) {
+        if (fs.existsSync(configPath)) {
+            return configPath;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=shadow-config.js.map

package/dist/bridge/shadow-config.js.map

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

package/dist/bridge/spawner.d.ts

@@ -3,7 +3,19 @@
  * Handles spawning and releasing worker agents via node-pty.
  * Workers run headlessly with output capture for logs.
  */
-import type { SpawnRequest, SpawnResult, WorkerInfo } from './types.js';
+import { type SummaryEvent, type SessionEndEvent } from '../wrapper/pty-wrapper.js';
+import { AgentPolicyService, type CloudPolicyFetcher } from '../policy/agent-policy.js';
+import type { SpawnRequest, SpawnResult, WorkerInfo, SpawnWithShadowRequest, SpawnWithShadowResult } from './types.js';
+/**
+ * Cloud persistence handler interface.
+ * Implement this to persist agent session data to cloud storage.
+ */
+export interface CloudPersistenceHandler {
+    onSummary: (agentName: string, event: SummaryEvent) => Promise<void>;
+    onSessionEnd: (agentName: string, event: SessionEndEvent) => Promise<void>;
+    /** Optional cleanup method for tests and graceful shutdown */
+    destroy?: () => void;
+}
 /** Worker metadata stored in workers.json */
 interface WorkerMeta {
     name: string;
@@ -15,6 +27,13 @@ interface WorkerMeta {
     pid?: number;
     logFile?: string;
 }
+/** Callback for agent death notifications */
+export type OnAgentDeathCallback = (info: {
+    name: string;
+    exitCode: number | null;
+    agentId?: string;
+    resumeInstructions?: string;
+}) => void;
 export declare class AgentSpawner {
     private activeWorkers;
     private agentsPath;
@@ -23,16 +42,64 @@ export declare class AgentSpawner {
     private logsDir;
     private workersPath;
     private dashboardPort?;
+    private onAgentDeath?;
+    private cloudPersistence?;
+    private policyService?;
+    private policyEnforcementEnabled;
     constructor(projectRoot: string, _tmuxSession?: string, dashboardPort?: number);
+    /**
+     * Set cloud policy fetcher for workspace-level policies
+     */
+    setCloudPolicyFetcher(fetcher: CloudPolicyFetcher): void;
+    /**
+     * Get the policy service (for external access to policy checks)
+     */
+    getPolicyService(): AgentPolicyService | undefined;
     /**
      * Set the dashboard port (for nested spawn API calls).
      * Called after the dashboard server starts and we know the actual port.
      */
     setDashboardPort(port: number): void;
+    /**
+     * Set callback for agent death notifications.
+     * Called when an agent exits unexpectedly (non-zero exit code).
+     */
+    setOnAgentDeath(callback: OnAgentDeathCallback): void;
+    /**
+     * Set cloud persistence handler for forwarding PtyWrapper events.
+     * When set, 'summary' and 'session-end' events from spawned agents
+     * are forwarded to the handler for cloud persistence (PostgreSQL/Redis).
+     *
+     * Note: Enable via RELAY_CLOUD_ENABLED=true environment variable.
+     */
+    setCloudPersistence(handler: CloudPersistenceHandler): void;
+    /**
+     * Bind cloud persistence event handlers to a PtyWrapper.
+     * Returns the listener references for cleanup.
+     */
+    private bindCloudPersistenceEvents;
+    /**
+     * Unbind all tracked listeners from a PtyWrapper.
+     */
+    private unbindListeners;
     /**
      * Spawn a new worker agent using node-pty
      */
     spawn(request: SpawnRequest): Promise<SpawnResult>;
+    /** Role presets for shadow agents */
+    private static readonly ROLE_PRESETS;
+    /**
+     * Spawn a primary agent with its shadow agent
+     *
+     * Example usage:
+     * ```ts
+     * const result = await spawner.spawnWithShadow({
+     *   primary: { name: 'Lead', command: 'claude', task: 'Implement feature X' },
+     *   shadow: { name: 'Auditor', role: 'reviewer', speakOn: ['CODE_WRITTEN'] }
+     * });
+     * ```
+     */
+    spawnWithShadow(request: SpawnWithShadowRequest): Promise<SpawnWithShadowResult>;
     /**
      * Release (terminate) a worker
      */

package/dist/bridge/spawner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spawner.d.ts","sourceRoot":"","sources":["../../src/bridge/spawner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExE,6CAA6C;AAC7C,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAOD,qBAAa,YAAY;IACvB,OAAO,CAAC,aAAa,CAAwC;IAC7D,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAC,CAAS;IAC5B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,aAAa,CAAC,CAAS;gBAEnB,WAAW,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM;IAa9E;;;OAGG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIpC;;OAEG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAqIxD;;OAEG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiC7C;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAOjC;;OAEG;IACH,gBAAgB,IAAI,UAAU,EAAE;IAWhC;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIhC;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAa/C;;OAEG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAM9D;;OAEG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAM/C;;OAEG;YACW,wBAAwB;IAkBtC,OAAO,CAAC,iBAAiB;IAmBzB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAkB3B;;OAEG;IACH,UAAU,IAAI,MAAM;IAIpB;;OAEG;IACH,cAAc,IAAI,MAAM;CAGzB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,EAAE,CAcrE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAG5D"}
+{"version":3,"file":"spawner.d.ts","sourceRoot":"","sources":["../../src/bridge/spawner.ts"],"names":[],"mappings":"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"}