@telora/daemon-core 0.2.5

package/dist/resilience.js

@@ -0,0 +1,300 @@
+/**
+ * Resilience utilities for Telora daemon and factory.
+ *
+ * Provides retry with exponential backoff and circuit breaker patterns
+ * to make API calls and other operations robust against transient failures.
+ */
+// ============================================
+// Retry with Exponential Backoff
+// ============================================
+/** Error codes that indicate transient network failures worth retrying. */
+const RETRYABLE_ERROR_CODES = new Set([
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ETIMEDOUT',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'UND_ERR_SOCKET',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'UND_ERR_HEADERS_TIMEOUT',
+    'UND_ERR_BODY_TIMEOUT',
+]);
+/** HTTP status codes that are retryable. */
+const RETRYABLE_HTTP_STATUSES = new Set([429, 502, 503]);
+/** HTTP status codes that should never be retried. */
+const NON_RETRYABLE_HTTP_STATUSES = new Set([400, 401, 403, 404, 422]);
+/**
+ * Custom error class that carries HTTP status information.
+ */
+export class ApiError extends Error {
+    statusCode;
+    isRetryable;
+    constructor(message, statusCode, isRetryable = false) {
+        super(message);
+        this.statusCode = statusCode;
+        this.isRetryable = isRetryable;
+        this.name = 'ApiError';
+    }
+}
+/**
+ * Determine if an error is retryable.
+ */
+export function isRetryableError(error) {
+    if (error instanceof ApiError) {
+        return error.isRetryable;
+    }
+    // Check for network error codes
+    const err = error;
+    const code = err.code || err.cause?.code;
+    if (code && RETRYABLE_ERROR_CODES.has(code)) {
+        return true;
+    }
+    // Check error message for common transient patterns
+    const message = error.message || '';
+    if (message.includes('UND_ERR_SOCKET') ||
+        message.includes('UND_ERR_CONNECT_TIMEOUT') ||
+        message.includes('ConnectTimeoutError') ||
+        message.includes('fetch failed')) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Classify an HTTP response status code for retry decisions.
+ */
+export function classifyHttpStatus(status) {
+    if (RETRYABLE_HTTP_STATUSES.has(status))
+        return 'retryable';
+    if (NON_RETRYABLE_HTTP_STATUSES.has(status))
+        return 'non-retryable';
+    if (status >= 500)
+        return 'retryable'; // Other 5xx errors are generally retryable
+    return 'non-retryable';
+}
+/**
+ * Execute an async function with retry and exponential backoff.
+ *
+ * Only retries on errors classified as retryable. Non-retryable errors
+ * are thrown immediately.
+ */
+export async function withRetry(fn, options = {}) {
+    const { maxAttempts = 3, baseDelayMs = 1000, label = 'operation' } = options;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (!isRetryableError(error) || attempt === maxAttempts) {
+                throw error;
+            }
+            const delayMs = baseDelayMs * Math.pow(2, attempt - 1);
+            console.warn(`[retry] ${label} failed (attempt ${attempt}/${maxAttempts}): ${error.message}. Retrying in ${delayMs}ms...`);
+            await sleep(delayMs);
+        }
+    }
+    // Should not be reached, but satisfy TypeScript
+    throw lastError;
+}
+/** Global registry of all circuit breaker instances for force-close support. */
+const circuitBreakerRegistry = [];
+/**
+ * Get all registered circuit breaker instances.
+ */
+export function getCircuitBreakers() {
+    return circuitBreakerRegistry;
+}
+/**
+ * Force-close all registered circuit breakers. Used by SIGUSR2 handler.
+ */
+export function forceCloseAllCircuitBreakers() {
+    for (const cb of circuitBreakerRegistry) {
+        cb.forceClose();
+    }
+    console.log(`All circuit breakers force-closed via operator override (${circuitBreakerRegistry.length} instance(s))`);
+}
+/**
+ * Circuit breaker to prevent hammering a failing endpoint.
+ *
+ * States:
+ * - closed: Normal operation, requests pass through
+ * - open: Requests fail immediately without hitting the network
+ * - half-open: Probe requests are allowed; N consecutive successes required to close
+ *
+ * Features:
+ * - Graduated recovery: half-open requires N consecutive successes (default 2)
+ * - Exponential cooldown backoff on repeated open cycles
+ * - State transition logging with endpoint label and reason
+ * - Force-close for operator override (SIGUSR2)
+ */
+export class CircuitBreaker {
+    state = 'closed';
+    consecutiveFailures = 0;
+    lastFailureTime = 0;
+    halfOpenSuccesses = 0;
+    consecutiveOpenCycles = 0;
+    /** Tracks whether we already logged the open-state transition to suppress repeat logs. */
+    openStateLogged = false;
+    /** Count of suppressed CircuitOpenError throws since the last state-change log. */
+    suppressedCallCount = 0;
+    failureThreshold;
+    baseCooldownMs;
+    maxCooldownMs;
+    halfOpenSuccessThreshold;
+    label;
+    constructor(options = {}) {
+        this.failureThreshold = options.failureThreshold ?? 5;
+        this.baseCooldownMs = options.cooldownMs ?? 60000;
+        this.maxCooldownMs = options.maxCooldownMs ?? 300000;
+        this.halfOpenSuccessThreshold = options.halfOpenSuccessThreshold ?? 2;
+        this.label = options.label ?? 'circuit';
+        circuitBreakerRegistry.push(this);
+    }
+    /** Current effective cooldown with exponential backoff. */
+    getEffectiveCooldownMs() {
+        const cooldown = this.baseCooldownMs * Math.pow(2, this.consecutiveOpenCycles);
+        return Math.min(cooldown, this.maxCooldownMs);
+    }
+    /** Log a state transition. */
+    logTransition(from, to, reason) {
+        console.log(`[circuit:${this.label}] ${from} -> ${to} (reason: ${reason})`);
+    }
+    /**
+     * Execute a function through the circuit breaker.
+     * Throws CircuitOpenError if the circuit is open and cooldown hasn't elapsed.
+     */
+    async execute(fn) {
+        if (this.state === 'open') {
+            const effectiveCooldown = this.getEffectiveCooldownMs();
+            const elapsed = Date.now() - this.lastFailureTime;
+            if (elapsed < effectiveCooldown) {
+                // Suppress repeated logs: only count, don't log each blocked call
+                this.suppressedCallCount++;
+                throw new CircuitOpenError(`[${this.label}] Circuit is open. ${Math.ceil((effectiveCooldown - elapsed) / 1000)}s until next probe.`);
+            }
+            // Cooldown elapsed, transition to half-open for probe
+            this.transitionToHalfOpen();
+        }
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            this.onFailure();
+            throw error;
+        }
+    }
+    /** Transition from open to half-open, logging suppressed call count. */
+    transitionToHalfOpen() {
+        const prevState = this.state;
+        this.state = 'half-open';
+        this.halfOpenSuccesses = 0;
+        const suppressedNote = this.suppressedCallCount > 0
+            ? `, ${this.suppressedCallCount} calls suppressed while open`
+            : '';
+        this.logTransition(prevState, 'half-open', `cooldown elapsed, allowing probe${suppressedNote}`);
+        this.suppressedCallCount = 0;
+        this.openStateLogged = false;
+    }
+    onSuccess() {
+        if (this.state === 'half-open') {
+            this.halfOpenSuccesses++;
+            if (this.halfOpenSuccesses >= this.halfOpenSuccessThreshold) {
+                this.logTransition('half-open', 'closed', `${this.halfOpenSuccesses} consecutive probe successes`);
+                this.state = 'closed';
+                this.consecutiveFailures = 0;
+                this.halfOpenSuccesses = 0;
+                this.consecutiveOpenCycles = 0; // Reset backoff on full recovery
+                this.openStateLogged = false;
+                this.suppressedCallCount = 0;
+            }
+            return;
+        }
+        // In closed state, just reset failure count
+        this.consecutiveFailures = 0;
+    }
+    onFailure() {
+        this.consecutiveFailures++;
+        this.lastFailureTime = Date.now();
+        if (this.state === 'half-open') {
+            this.consecutiveOpenCycles++;
+            const effectiveCooldown = this.getEffectiveCooldownMs();
+            this.logTransition('half-open', 'open', `probe failed, backoff cycle ${this.consecutiveOpenCycles}, cooldown ${(effectiveCooldown / 1000).toFixed(0)}s`);
+            this.state = 'open';
+            this.halfOpenSuccesses = 0;
+            this.openStateLogged = true;
+            this.suppressedCallCount = 0;
+            return;
+        }
+        if (this.consecutiveFailures >= this.failureThreshold) {
+            this.logTransition('closed', 'open', `${this.consecutiveFailures} consecutive failures`);
+            this.state = 'open';
+            this.openStateLogged = true;
+            this.suppressedCallCount = 0;
+        }
+    }
+    /** Get current circuit state for diagnostics. */
+    getState() {
+        return this.state;
+    }
+    /** Get the number of consecutive open cycles (for diagnostics). */
+    getConsecutiveOpenCycles() {
+        return this.consecutiveOpenCycles;
+    }
+    /** Reset the circuit breaker to closed state. */
+    reset() {
+        this.state = 'closed';
+        this.consecutiveFailures = 0;
+        this.lastFailureTime = 0;
+        this.halfOpenSuccesses = 0;
+        this.consecutiveOpenCycles = 0;
+        this.openStateLogged = false;
+        this.suppressedCallCount = 0;
+    }
+    /**
+     * Force-close the circuit breaker. Used for operator override.
+     * Resets all state including backoff counters.
+     */
+    forceClose() {
+        const prevState = this.state;
+        this.reset();
+        this.logTransition(prevState, 'closed', 'operator force-close');
+    }
+}
+/**
+ * Error thrown when the circuit breaker is open.
+ */
+export class CircuitOpenError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CircuitOpenError';
+    }
+}
+// ============================================
+// Safe Interval
+// ============================================
+/**
+ * Create a setInterval that wraps the callback in try/catch.
+ * Prevents unhandled exceptions from crashing the process.
+ *
+ * @returns The interval handle for clearing with clearInterval()
+ */
+export function safeInterval(callback, intervalMs, label) {
+    return setInterval(async () => {
+        try {
+            await callback();
+        }
+        catch (error) {
+            console.error(`[${label}] Unhandled error in interval callback:`, error.message);
+        }
+    }, intervalMs);
+}
+// ============================================
+// Helpers
+// ============================================
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=resilience.js.map

package/dist/resilience.js.map

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

package/dist/resource-governor.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Resource Governor -- global concurrency limiter for Claude Code processes.
+ *
+ * Enforces both per-engine and global limits on the number of concurrent
+ * Claude Code processes. Uses a semaphore pattern with FIFO queuing:
+ *
+ * - Each engine has its own max (e.g. strategy.maxSessions = 4)
+ * - A global max caps the total across all engines (e.g. maxGlobalSessions = 8)
+ * - If one engine is idle, the other can use slots up to the global max
+ * - When at capacity, acquireSlot() queues and resolves FIFO when slots free up
+ */
+/** Configuration for the resource governor. */
+export interface ResourceGovernorConfig {
+    /** Maximum total Claude Code processes across all engines. */
+    maxGlobalSessions: number;
+    /** Per-engine limits. Key = engine name, value = max concurrent sessions. */
+    engineLimits: Record<string, number>;
+}
+/** Utilization snapshot returned by getUtilization(). */
+export interface ResourceUtilization {
+    /** Total slots currently in use across all engines. */
+    total: number;
+    /** Slots in use per engine. */
+    perEngine: Record<string, number>;
+    /** Global maximum. */
+    max: number;
+    /** Number of queued requests waiting for slots. */
+    queueDepth: number;
+    /** Queued requests per engine. */
+    queueDepthPerEngine: Record<string, number>;
+}
+export declare class ResourceGovernor {
+    private readonly maxGlobal;
+    private readonly engineLimits;
+    /** Current slot count per engine. */
+    private readonly activePerEngine;
+    /** FIFO queue of pending acquire requests. */
+    private readonly queue;
+    /** Whether the governor has been shut down (rejects new acquires). */
+    private shuttingDown;
+    constructor(config: ResourceGovernorConfig);
+    /**
+     * Acquire a slot for the given engine. Blocks (returns a Promise) until
+     * a slot is available within both the engine limit and global limit.
+     *
+     * Rejects if the governor is shutting down.
+     */
+    acquireSlot(engine: string): Promise<void>;
+    /**
+     * Try to acquire a slot without blocking. Returns true if successful,
+     * false if at capacity.
+     */
+    tryAcquireSlot(engine: string): boolean;
+    /**
+     * Release a slot for the given engine. Processes the next queued
+     * request if one is waiting.
+     */
+    releaseSlot(engine: string): void;
+    /** Return a snapshot of current utilization. */
+    getUtilization(): ResourceUtilization;
+    /**
+     * Shut down the governor. Rejects all pending requests and prevents
+     * new acquisitions.
+     */
+    shutdown(): void;
+    /**
+     * Reset the governor (for testing). Clears all state and re-enables
+     * slot acquisition.
+     */
+    reset(): void;
+    /** Check if a slot can be acquired for the given engine right now. */
+    private canAcquire;
+    /** Increment the active slot count for an engine. */
+    private incrementSlot;
+    /** Get the total active slots across all engines. */
+    private getGlobalActive;
+    /**
+     * Process the FIFO queue, granting slots to waiting requests
+     * that can now be satisfied.
+     */
+    private processQueue;
+}
+//# sourceMappingURL=resource-governor.d.ts.map

package/dist/resource-governor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-governor.d.ts","sourceRoot":"","sources":["../src/resource-governor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC,8DAA8D;IAC9D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,sBAAsB;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7C;AAaD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IAEnD,qCAAqC;IACrC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6B;IAE7D,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAE9C,sEAAsE;IACtE,OAAO,CAAC,YAAY,CAAS;gBAEjB,MAAM,EAAE,sBAAsB;IAe1C;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB1C;;;OAGG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAOvC;;;OAGG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAUjC,gDAAgD;IAChD,cAAc,IAAI,mBAAmB;IA+BrC;;;OAGG;IACH,QAAQ,IAAI,IAAI;IAShB;;;OAGG;IACH,KAAK,IAAI,IAAI;IAab,sEAAsE;IACtE,OAAO,CAAC,UAAU;IAelB,qDAAqD;IACrD,OAAO,CAAC,aAAa;IAKrB,qDAAqD;IACrD,OAAO,CAAC,eAAe;IAQvB;;;OAGG;IACH,OAAO,CAAC,YAAY;CAcrB"}

package/dist/resource-governor.js

@@ -0,0 +1,184 @@
+/**
+ * Resource Governor -- global concurrency limiter for Claude Code processes.
+ *
+ * Enforces both per-engine and global limits on the number of concurrent
+ * Claude Code processes. Uses a semaphore pattern with FIFO queuing:
+ *
+ * - Each engine has its own max (e.g. strategy.maxSessions = 4)
+ * - A global max caps the total across all engines (e.g. maxGlobalSessions = 8)
+ * - If one engine is idle, the other can use slots up to the global max
+ * - When at capacity, acquireSlot() queues and resolves FIFO when slots free up
+ */
+// ---------------------------------------------------------------------------
+// ResourceGovernor
+// ---------------------------------------------------------------------------
+export class ResourceGovernor {
+    maxGlobal;
+    engineLimits;
+    /** Current slot count per engine. */
+    activePerEngine = new Map();
+    /** FIFO queue of pending acquire requests. */
+    queue = [];
+    /** Whether the governor has been shut down (rejects new acquires). */
+    shuttingDown = false;
+    constructor(config) {
+        if (config.maxGlobalSessions < 1) {
+            throw new Error('maxGlobalSessions must be >= 1');
+        }
+        this.maxGlobal = config.maxGlobalSessions;
+        this.engineLimits = new Map(Object.entries(config.engineLimits));
+        // Validate per-engine limits
+        for (const [engine, limit] of this.engineLimits) {
+            if (limit < 1) {
+                throw new Error(`Engine limit for '${engine}' must be >= 1, got ${limit}`);
+            }
+        }
+    }
+    /**
+     * Acquire a slot for the given engine. Blocks (returns a Promise) until
+     * a slot is available within both the engine limit and global limit.
+     *
+     * Rejects if the governor is shutting down.
+     */
+    acquireSlot(engine) {
+        if (this.shuttingDown) {
+            return Promise.reject(new Error('ResourceGovernor is shutting down'));
+        }
+        // Try immediate acquisition
+        if (this.canAcquire(engine)) {
+            this.incrementSlot(engine);
+            return Promise.resolve();
+        }
+        // Queue the request
+        return new Promise((resolve, reject) => {
+            this.queue.push({ engine, resolve, reject });
+        });
+    }
+    /**
+     * Try to acquire a slot without blocking. Returns true if successful,
+     * false if at capacity.
+     */
+    tryAcquireSlot(engine) {
+        if (this.shuttingDown)
+            return false;
+        if (!this.canAcquire(engine))
+            return false;
+        this.incrementSlot(engine);
+        return true;
+    }
+    /**
+     * Release a slot for the given engine. Processes the next queued
+     * request if one is waiting.
+     */
+    releaseSlot(engine) {
+        const current = this.activePerEngine.get(engine) ?? 0;
+        if (current <= 0) {
+            console.warn(`ResourceGovernor: releaseSlot('${engine}') called with no active slots`);
+            return;
+        }
+        this.activePerEngine.set(engine, current - 1);
+        this.processQueue();
+    }
+    /** Return a snapshot of current utilization. */
+    getUtilization() {
+        let total = 0;
+        const perEngine = {};
+        for (const [engine, count] of this.activePerEngine) {
+            perEngine[engine] = count;
+            total += count;
+        }
+        // Include engines that have limits but no active slots
+        for (const engine of this.engineLimits.keys()) {
+            if (!(engine in perEngine)) {
+                perEngine[engine] = 0;
+            }
+        }
+        // Queue depth per engine
+        const queueDepthPerEngine = {};
+        for (const req of this.queue) {
+            queueDepthPerEngine[req.engine] = (queueDepthPerEngine[req.engine] ?? 0) + 1;
+        }
+        return {
+            total,
+            perEngine,
+            max: this.maxGlobal,
+            queueDepth: this.queue.length,
+            queueDepthPerEngine,
+        };
+    }
+    /**
+     * Shut down the governor. Rejects all pending requests and prevents
+     * new acquisitions.
+     */
+    shutdown() {
+        this.shuttingDown = true;
+        // Reject all queued requests
+        while (this.queue.length > 0) {
+            const req = this.queue.shift();
+            req.reject(new Error('ResourceGovernor is shutting down'));
+        }
+    }
+    /**
+     * Reset the governor (for testing). Clears all state and re-enables
+     * slot acquisition.
+     */
+    reset() {
+        this.shuttingDown = false;
+        this.activePerEngine.clear();
+        while (this.queue.length > 0) {
+            const req = this.queue.shift();
+            req.reject(new Error('ResourceGovernor reset'));
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Private
+    // -------------------------------------------------------------------------
+    /** Check if a slot can be acquired for the given engine right now. */
+    canAcquire(engine) {
+        // Check global limit
+        const globalCurrent = this.getGlobalActive();
+        if (globalCurrent >= this.maxGlobal)
+            return false;
+        // Check per-engine limit (if configured)
+        const engineLimit = this.engineLimits.get(engine);
+        if (engineLimit !== undefined) {
+            const engineCurrent = this.activePerEngine.get(engine) ?? 0;
+            if (engineCurrent >= engineLimit)
+                return false;
+        }
+        return true;
+    }
+    /** Increment the active slot count for an engine. */
+    incrementSlot(engine) {
+        const current = this.activePerEngine.get(engine) ?? 0;
+        this.activePerEngine.set(engine, current + 1);
+    }
+    /** Get the total active slots across all engines. */
+    getGlobalActive() {
+        let total = 0;
+        for (const count of this.activePerEngine.values()) {
+            total += count;
+        }
+        return total;
+    }
+    /**
+     * Process the FIFO queue, granting slots to waiting requests
+     * that can now be satisfied.
+     */
+    processQueue() {
+        let i = 0;
+        while (i < this.queue.length) {
+            const req = this.queue[i];
+            if (this.canAcquire(req.engine)) {
+                this.queue.splice(i, 1);
+                this.incrementSlot(req.engine);
+                req.resolve();
+                // Don't increment i -- array shifted
+            }
+            else {
+                i++;
+            }
+        }
+    }
+}
+//# sourceMappingURL=resource-governor.js.map

package/dist/resource-governor.js.map

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

package/dist/spawn.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared Claude Code process spawning utilities.
+ *
+ * Provides common building blocks for spawning Claude Code CLI processes:
+ * - CLI argument construction for stream-json mode
+ * - Environment variable stripping (remove inherited Claude Code session vars)
+ * - Log file creation with restrictive permissions
+ *
+ * Both the Telora daemon and factory engines use these primitives,
+ * appending their own engine-specific options on top.
+ */
+import { type WriteStream } from 'node:fs';
+/**
+ * Options for building stream-json CLI arguments.
+ *
+ * Only the common, cross-engine flags are included here. Engine-specific
+ * flags (e.g. --teammate-mode, --setting-sources) should be appended by
+ * the caller after calling `buildStreamJsonArgs`.
+ */
+export interface StreamJsonArgsOptions {
+    /** Path to an MCP config file. Resolved to an absolute path. Null/undefined means no MCP config. */
+    mcpConfigPath?: string | null;
+}
+/**
+ * Options controlling which env var patterns are stripped.
+ */
+export interface StripEnvOptions {
+    /**
+     * Env var keys to preserve even if they match a strip pattern.
+     * For example, the daemon preserves `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`.
+     */
+    preserve?: string[];
+}
+/**
+ * Build the common Claude Code CLI arguments for stream-json I/O.
+ *
+ * Returns the base set of flags shared across all engines:
+ * - `--dangerously-skip-permissions`
+ * - `--input-format stream-json`
+ * - `--output-format stream-json`
+ * - `--verbose`
+ * - `--mcp-config <absolute-path>` (when mcpConfigPath is provided)
+ *
+ * Callers append engine-specific flags (e.g. `--teammate-mode`, `--setting-sources`).
+ */
+export declare function buildStreamJsonArgs(options?: StreamJsonArgsOptions): string[];
+/**
+ * Strip inherited Claude Code session variables from an environment object.
+ *
+ * When a Claude Code process is spawned from within another Claude Code session,
+ * inherited env vars (CLAUDECODE, CLAUDE_CODE_*, CLAUDECODE_*) cause the child
+ * to detect a parent session and hang indefinitely. This function removes those
+ * markers while allowing specific keys to be preserved.
+ *
+ * Patterns stripped:
+ * - `CLAUDECODE` (exact match)
+ * - `CLAUDE_CODE_*` (prefix match)
+ * - `CLAUDECODE_*` (prefix match -- used by some versions)
+ *
+ * @param env - The environment object to clean (not mutated; a copy is returned).
+ * @param options - Optional settings (e.g. keys to preserve).
+ * @returns A new environment object with matching keys removed.
+ */
+export declare function stripClaudeCodeEnvVars(env: Record<string, string | undefined>, options?: StripEnvOptions): Record<string, string | undefined>;
+/**
+ * Create a writable log stream with restrictive permissions (owner-only read/write).
+ *
+ * Used for stdout/stderr/jsonl log files for spawned agent processes.
+ * The file is created with mode 0o600 (rw-------).
+ */
+export declare function createLogStream(path: string): WriteStream;
+//# sourceMappingURL=spawn.d.ts.map

package/dist/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../src/spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAK9D;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,oGAAoG;IACpG,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,qBAA0B,GAAG,MAAM,EAAE,CAcjF;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,OAAO,GAAE,eAAoB,GAC5B,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAiBpC;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAEzD"}