@agent-relay/bridge 0.1.0

package/dist/spawner.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Agent Spawner
+ * Handles spawning and releasing worker agents via relay-pty.
+ * Workers run headlessly with output capture for logs.
+ */
+import type { SummaryEvent, SessionEndEvent } from '@agent-relay/wrapper';
+import { AgentPolicyService, type CloudPolicyFetcher } from '@agent-relay/policy';
+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;
+    cli: string;
+    task: string;
+    /** Optional team name this agent belongs to */
+    team?: string;
+    /** Optional user ID for per-user credential scoping */
+    userId?: string;
+    spawnedAt: number;
+    pid?: number;
+    logFile?: string;
+}
+/** Callback for agent death notifications */
+export type OnAgentDeathCallback = (info: {
+    name: string;
+    exitCode: number | null;
+    agentId?: string;
+    resumeInstructions?: string;
+    /** Traceable error ID for support lookup */
+    errorId?: string;
+}) => void;
+/** Options for AgentSpawner constructor */
+export interface AgentSpawnerOptions {
+    projectRoot: string;
+    tmuxSession?: string;
+    dashboardPort?: number;
+    /**
+     * Callback to mark an agent as spawning (before HELLO completes).
+     * Messages sent to this agent will be queued for delivery after registration.
+     */
+    onMarkSpawning?: (agentName: string) => void;
+    /**
+     * Callback to clear the spawning flag for an agent.
+     * Called when spawn fails or is cancelled.
+     */
+    onClearSpawning?: (agentName: string) => void;
+}
+export declare class AgentSpawner {
+    private static readonly ONLINE_THRESHOLD_MS;
+    private activeWorkers;
+    private agentsPath;
+    private registryPath;
+    private projectRoot;
+    private socketPath?;
+    private logsDir;
+    private workersPath;
+    private dashboardPort?;
+    private onAgentDeath?;
+    private cloudPersistence?;
+    private policyService?;
+    private policyEnforcementEnabled;
+    private onMarkSpawning?;
+    private onClearSpawning?;
+    constructor(projectRoot: string, _tmuxSession?: string, dashboardPort?: number);
+    constructor(options: AgentSpawnerOptions);
+    /**
+     * 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;
+    private fetchGhTokenFromCloud;
+    private resolveGhTokenFromHostsFile;
+    private resolveGhTokenFromGhCli;
+    /**
+     * Resolve GitHub token using multiple fallback sources.
+     *
+     * Fallback order (same as git-credential-relay for consistency):
+     * 1. Environment - GH_TOKEN or GITHUB_TOKEN (fastest, set by entrypoint)
+     * 2. hosts.yml - gh CLI config file (~/.config/gh/hosts.yml)
+     * 3. gh CLI - execute `gh auth token` command
+     * 4. Cloud API - workspace-scoped token from Nango (requires network)
+     *
+     * Environment is checked first because:
+     * - It's the fastest (no I/O or network)
+     * - The entrypoint pre-fetches and caches GH_TOKEN at startup
+     * - This avoids delays when cloud API is slow/unreachable
+     */
+    private resolveGhToken;
+    /**
+     * 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 RelayPtyOrchestrator 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 RelayPtyOrchestrator.
+     * Returns the listener references for cleanup.
+     */
+    private bindCloudPersistenceEvents;
+    /**
+     * Unbind all tracked listeners from a RelayPtyOrchestrator.
+     */
+    private unbindListeners;
+    /**
+     * Spawn a new worker agent using relay-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
+     */
+    release(name: string): Promise<boolean>;
+    /**
+     * Release all workers
+     */
+    releaseAll(): Promise<void>;
+    /**
+     * Get all active workers (returns WorkerInfo without pty reference)
+     */
+    getActiveWorkers(): WorkerInfo[];
+    /**
+     * Check if a worker exists
+     */
+    hasWorker(name: string): boolean;
+    /**
+     * Get worker info
+     */
+    getWorker(name: string): WorkerInfo | undefined;
+    /**
+     * Get output logs from a worker
+     */
+    getWorkerOutput(name: string, limit?: number): string[] | null;
+    /**
+     * Get raw output from a worker
+     */
+    getWorkerRawOutput(name: string): string | null;
+    /**
+     * Send input to a worker's PTY (for interactive terminal support)
+     * @param name - Worker name
+     * @param data - Input data to send (keystrokes, text, etc.)
+     * @returns true if input was sent, false if worker not found
+     */
+    sendWorkerInput(name: string, data: string): boolean;
+    /**
+     * Wait for an agent to appear in the connected list and registry (connected-agents.json + agents.json).
+     */
+    private waitForAgentRegistration;
+    private isAgentRegistered;
+    private isAgentConnected;
+    private isAgentRecentlySeen;
+    /**
+     * Save workers metadata to disk for CLI access
+     */
+    private saveWorkersMetadata;
+    /**
+     * Get path to logs directory
+     */
+    getLogsDir(): string;
+    /**
+     * Get path to workers metadata file
+     */
+    getWorkersPath(): string;
+}
+/**
+ * Read workers metadata from disk (for CLI use)
+ */
+export declare function readWorkersMetadata(projectRoot: string): WorkerMeta[];
+/**
+ * Get the worker logs directory path
+ */
+export declare function getWorkerLogsDir(projectRoot: string): string;
+export {};
+//# sourceMappingURL=spawner.d.ts.map

package/dist/spawner.d.ts.map

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