@runcore-sh/runcore 0.1.2

package/dist/agents/runtime/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Agent Runtime Environment — Public API.
+ *
+ * Re-exports the core runtime components and provides a convenience
+ * factory for creating a fully configured RuntimeManager.
+ */
+export type { AgentState, AgentInstance, AgentInstanceConfig, ResourceAllocation, AgentMetadata, AgentError, AgentMessage, LifecycleEvent, RuntimeEvents, ResourceSnapshot, AgentDriver, RuntimeConfig, SpawnRequest, } from "./types.js";
+export { VALID_TRANSITIONS, TERMINAL_STATES } from "./types.js";
+export { RuntimeError, ErrorCodes } from "./errors.js";
+export type { ErrorCode } from "./errors.js";
+export { loadRuntimeConfig, resolveInstanceConfig, resolveResources } from "./config.js";
+export { isValidTransition, assertTransition, isTerminal, transition, shouldRetry, prepareRetry, reachableStates, isActive, } from "./lifecycle.js";
+export { ResourcePool } from "./resources.js";
+export { RuntimeBus } from "./bus.js";
+export { AgentRegistry } from "./registry.js";
+export { ClaudeCliDriver } from "./driver.js";
+export { RuntimeManager } from "./manager.js";
+import { RuntimeManager } from "./manager.js";
+import type { RuntimeConfig } from "./types.js";
+/**
+ * Create and initialize a RuntimeManager with the default Claude CLI driver.
+ * Returns the same instance on subsequent calls (singleton).
+ */
+export declare function createRuntime(configOverrides?: Partial<RuntimeConfig>): Promise<RuntimeManager>;
+/** Get the current runtime manager (or null if not initialized). */
+export declare function getRuntime(): RuntimeManager | null;
+/** Shut down and clear the singleton runtime. */
+export declare function shutdownRuntime(reason?: string): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agents/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACV,UAAU,EACV,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,UAAU,EACV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGhE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACvD,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGzF,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,eAAe,EACf,QAAQ,GACT,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGtC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAM9C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAKhD;;;GAGG;AACH,wBAAsB,aAAa,CACjC,eAAe,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GACvC,OAAO,CAAC,cAAc,CAAC,CAQzB;AAED,oEAAoE;AACpE,wBAAgB,UAAU,IAAI,cAAc,GAAG,IAAI,CAElD;AAED,iDAAiD;AACjD,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKpE"}

package/dist/agents/runtime/index.js

@@ -0,0 +1,54 @@
+/**
+ * Agent Runtime Environment — Public API.
+ *
+ * Re-exports the core runtime components and provides a convenience
+ * factory for creating a fully configured RuntimeManager.
+ */
+export { VALID_TRANSITIONS, TERMINAL_STATES } from "./types.js";
+// Errors
+export { RuntimeError, ErrorCodes } from "./errors.js";
+// Configuration
+export { loadRuntimeConfig, resolveInstanceConfig, resolveResources } from "./config.js";
+// Lifecycle state machine
+export { isValidTransition, assertTransition, isTerminal, transition, shouldRetry, prepareRetry, reachableStates, isActive, } from "./lifecycle.js";
+// Resources
+export { ResourcePool } from "./resources.js";
+// Event bus
+export { RuntimeBus } from "./bus.js";
+// Registry
+export { AgentRegistry } from "./registry.js";
+// Driver
+export { ClaudeCliDriver } from "./driver.js";
+// Manager
+export { RuntimeManager } from "./manager.js";
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+import { RuntimeManager } from "./manager.js";
+import { ClaudeCliDriver } from "./driver.js";
+/** Module-level singleton. */
+let _manager = null;
+/**
+ * Create and initialize a RuntimeManager with the default Claude CLI driver.
+ * Returns the same instance on subsequent calls (singleton).
+ */
+export async function createRuntime(configOverrides) {
+    if (_manager)
+        return _manager;
+    const driver = new ClaudeCliDriver();
+    _manager = new RuntimeManager(driver, configOverrides);
+    await _manager.init();
+    return _manager;
+}
+/** Get the current runtime manager (or null if not initialized). */
+export function getRuntime() {
+    return _manager;
+}
+/** Shut down and clear the singleton runtime. */
+export async function shutdownRuntime(reason) {
+    if (_manager) {
+        await _manager.shutdown(reason);
+        _manager = null;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/agents/runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agents/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAmBH,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEhE,SAAS;AACT,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGvD,gBAAgB;AAChB,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEzF,0BAA0B;AAC1B,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,eAAe,EACf,QAAQ,GACT,MAAM,gBAAgB,CAAC;AAExB,YAAY;AACZ,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,YAAY;AACZ,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC,WAAW;AACX,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,SAAS;AACT,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,UAAU;AACV,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,8BAA8B;AAC9B,IAAI,QAAQ,GAA0B,IAAI,CAAC;AAE3C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,eAAwC;IAExC,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAE9B,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,QAAQ,GAAG,IAAI,cAAc,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACvD,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAEtB,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,UAAU;IACxB,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,iDAAiD;AACjD,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAe;IACnD,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAChC,QAAQ,GAAG,IAAI,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/agents/runtime/lifecycle.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Agent Runtime Environment — Lifecycle state machine.
+ *
+ * Enforces valid state transitions with guards and hooks.
+ * Every transition is validated, timestamped, and emits a LifecycleEvent.
+ */
+import type { AgentInstance, AgentState, AgentError, LifecycleEvent } from "./types.js";
+/** Check if a transition from → to is valid per the state machine. */
+export declare function isValidTransition(from: AgentState, to: AgentState): boolean;
+/** Assert a transition is valid; throw RuntimeError if not. */
+export declare function assertTransition(from: AgentState, to: AgentState): void;
+/** Check if an agent is in a terminal state. */
+export declare function isTerminal(state: AgentState): boolean;
+export type LifecycleHook = (event: LifecycleEvent) => void | Promise<void>;
+/**
+ * Apply a state transition to an agent instance.
+ *
+ * - Validates the transition
+ * - Updates state + timestamps
+ * - Returns the LifecycleEvent for emission
+ *
+ * Mutates the instance in place (consistent with existing Core patterns).
+ */
+export declare function transition(instance: AgentInstance, newState: AgentState, reason?: string, error?: AgentError): LifecycleEvent;
+/**
+ * Determine if an agent should be retried after failure.
+ * Returns the delay in ms before retry, or null if no retry should occur.
+ *
+ * Uses exponential backoff with jitter to prevent thundering-herd when
+ * multiple agents fail simultaneously.
+ */
+export declare function shouldRetry(instance: AgentInstance): number | null;
+/**
+ * Prepare an instance for retry: increment counter, clear error, reset to initializing.
+ * Returns the LifecycleEvent for the transition back to initializing.
+ *
+ * The caller should transition through failed first, then call this to reset.
+ * This does a direct state override since failed → initializing isn't in the
+ * standard FSM — retries are a runtime-level concern.
+ */
+export declare function prepareRetry(instance: AgentInstance): LifecycleEvent;
+/** Returns all states reachable from the given state. */
+export declare function reachableStates(from: AgentState): AgentState[];
+/** Check if an agent is currently active (not terminal). */
+export declare function isActive(state: AgentState): boolean;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/agents/runtime/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../src/agents/runtime/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAQxF,sEAAsE;AACtE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,GAAG,OAAO,CAE3E;AAED,+DAA+D;AAC/D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,GAAG,IAAI,CASvE;AAED,gDAAgD;AAChD,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAErD;AAMD,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE5E;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,UAAU,EACpB,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,UAAU,GACjB,cAAc,CA2BhB;AAMD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAYlE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,cAAc,CAiBpE;AAMD,yDAAyD;AACzD,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,EAAE,CAE9D;AAED,4DAA4D;AAC5D,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAEnD"}

package/dist/agents/runtime/lifecycle.js

@@ -0,0 +1,116 @@
+/**
+ * Agent Runtime Environment — Lifecycle state machine.
+ *
+ * Enforces valid state transitions with guards and hooks.
+ * Every transition is validated, timestamped, and emits a LifecycleEvent.
+ */
+import { VALID_TRANSITIONS, TERMINAL_STATES } from "./types.js";
+import { RuntimeError, ErrorCodes } from "./errors.js";
+// ---------------------------------------------------------------------------
+// Transition validation
+// ---------------------------------------------------------------------------
+/** Check if a transition from → to is valid per the state machine. */
+export function isValidTransition(from, to) {
+    return VALID_TRANSITIONS[from]?.includes(to) ?? false;
+}
+/** Assert a transition is valid; throw RuntimeError if not. */
+export function assertTransition(from, to) {
+    if (!isValidTransition(from, to)) {
+        throw new RuntimeError(ErrorCodes.INVALID_TRANSITION, `Invalid state transition: ${from} → ${to}`, false, { from, to, validTargets: VALID_TRANSITIONS[from] });
+    }
+}
+/** Check if an agent is in a terminal state. */
+export function isTerminal(state) {
+    return TERMINAL_STATES.has(state);
+}
+/**
+ * Apply a state transition to an agent instance.
+ *
+ * - Validates the transition
+ * - Updates state + timestamps
+ * - Returns the LifecycleEvent for emission
+ *
+ * Mutates the instance in place (consistent with existing Core patterns).
+ */
+export function transition(instance, newState, reason, error) {
+    assertTransition(instance.state, newState);
+    const event = {
+        agentId: instance.id,
+        previousState: instance.state,
+        newState,
+        timestamp: new Date().toISOString(),
+        reason,
+    };
+    instance.state = newState;
+    instance.updatedAt = event.timestamp;
+    // Set state-specific timestamps
+    if (newState === "paused") {
+        instance.pausedAt = event.timestamp;
+    }
+    else if (isTerminal(newState)) {
+        instance.terminatedAt = event.timestamp;
+    }
+    // Attach error if transitioning to failed
+    if (newState === "failed" && error) {
+        instance.error = error;
+    }
+    return event;
+}
+// ---------------------------------------------------------------------------
+// Retry logic
+// ---------------------------------------------------------------------------
+/**
+ * Determine if an agent should be retried after failure.
+ * Returns the delay in ms before retry, or null if no retry should occur.
+ *
+ * Uses exponential backoff with jitter to prevent thundering-herd when
+ * multiple agents fail simultaneously.
+ */
+export function shouldRetry(instance) {
+    const { maxRetries, backoffMs, backoffMultiplier, maxBackoffMs } = instance.config;
+    if (instance.retryCount >= maxRetries)
+        return null;
+    if (instance.error && !instance.error.recoverable)
+        return null;
+    const baseDelay = backoffMs * Math.pow(backoffMultiplier, instance.retryCount);
+    // Add ±25% jitter to prevent synchronized retries
+    const jitter = baseDelay * 0.25 * (2 * Math.random() - 1);
+    const delay = Math.min(Math.max(0, baseDelay + jitter), maxBackoffMs);
+    return Math.round(delay);
+}
+/**
+ * Prepare an instance for retry: increment counter, clear error, reset to initializing.
+ * Returns the LifecycleEvent for the transition back to initializing.
+ *
+ * The caller should transition through failed first, then call this to reset.
+ * This does a direct state override since failed → initializing isn't in the
+ * standard FSM — retries are a runtime-level concern.
+ */
+export function prepareRetry(instance) {
+    const event = {
+        agentId: instance.id,
+        previousState: instance.state,
+        newState: "initializing",
+        timestamp: new Date().toISOString(),
+        reason: `Retry attempt ${instance.retryCount + 1}/${instance.config.maxRetries}`,
+    };
+    instance.retryCount += 1;
+    instance.state = "initializing";
+    instance.error = undefined;
+    instance.pid = undefined;
+    instance.updatedAt = event.timestamp;
+    instance.terminatedAt = undefined;
+    return event;
+}
+// ---------------------------------------------------------------------------
+// Convenience queries
+// ---------------------------------------------------------------------------
+/** Returns all states reachable from the given state. */
+export function reachableStates(from) {
+    return VALID_TRANSITIONS[from] ?? [];
+}
+/** Check if an agent is currently active (not terminal). */
+export function isActive(state) {
+    return !isTerminal(state);
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/agents/runtime/lifecycle.js.map

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

package/dist/agents/runtime/manager.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Agent Runtime Environment — RuntimeManager.
+ *
+ * The central orchestrator that ties together lifecycle management,
+ * resource allocation, the event bus, registry persistence, and the
+ * agent driver. Provides the high-level API for spawning, pausing,
+ * resuming, and terminating agent instances.
+ *
+ * Usage:
+ *   const manager = new RuntimeManager(driver, configOverrides);
+ *   await manager.init();
+ *   const instance = await manager.spawn({ taskId, label, prompt, origin });
+ *   await manager.pause(instance.id);
+ *   await manager.resume(instance.id);
+ *   await manager.terminate(instance.id);
+ *   await manager.shutdown();
+ */
+import type { AgentInstance, AgentDriver, AgentError, RuntimeConfig, SpawnRequest, ResourceSnapshot, LifecycleEvent, AgentMessage } from "./types.js";
+import { ResourcePool } from "./resources.js";
+import { RuntimeBus } from "./bus.js";
+import { AgentRegistry } from "./registry.js";
+export declare class RuntimeManager {
+    readonly config: RuntimeConfig;
+    readonly bus: RuntimeBus;
+    readonly resources: ResourcePool;
+    readonly registry: AgentRegistry;
+    private readonly driver;
+    private monitorTimer;
+    private shutdownRequested;
+    /** Prevents concurrent handleExit calls for the same instance. */
+    private handleExitGuard;
+    /** Tracks instances with a pending retry timeout (prevents duplicate scheduling). */
+    private retryPending;
+    /** Rolling window of retry timestamps across all instances. */
+    private globalRetryTimestamps;
+    /**
+     * Max retries across all instances within the budget window.
+     * Scaled to 3× maxConcurrentAgents to avoid budget exhaustion when a full
+     * batch fails (each agent gets maxRetries=2, so 5 agents = 10 retries
+     * which previously exhausted the entire budget in one batch).
+     */
+    private globalRetryBudget;
+    /** Rolling window for the global retry budget (ms). */
+    private static GLOBAL_RETRY_WINDOW_MS;
+    constructor(driver: AgentDriver, configOverrides?: Partial<RuntimeConfig>);
+    /** Initialize the runtime: load registry, recover agents, start monitor. */
+    init(): Promise<void>;
+    /** Graceful shutdown: terminate active agents, stop monitor, clean up. */
+    shutdown(reason?: string): Promise<void>;
+    /** Spawn a new agent instance. */
+    spawn(request: SpawnRequest): Promise<AgentInstance>;
+    /** Pause a running agent. */
+    pause(instanceId: string, reason?: string): Promise<AgentInstance>;
+    /** Resume a paused agent. */
+    resume(instanceId: string): Promise<AgentInstance>;
+    /** Terminate an agent (from any active state). */
+    terminate(instanceId: string, reason?: string): Promise<AgentInstance>;
+    /** Get an agent instance by ID. */
+    getInstance(id: string): AgentInstance | undefined;
+    /** Get an instance by its linked task ID. */
+    getByTaskId(taskId: string): AgentInstance | undefined;
+    /** List all instances, optionally filtered. */
+    listInstances(filter?: {
+        states?: string[];
+    }): AgentInstance[];
+    /** List all active (non-terminal) instances. */
+    listActive(): AgentInstance[];
+    /** Get a snapshot of current resource usage. */
+    getResourceSnapshot(): ResourceSnapshot;
+    /** Get instance counts by state. */
+    getStateCounts(): Record<string, number>;
+    /** Remove a terminated instance from the registry and disk. */
+    removeInstance(id: string): Promise<boolean>;
+    /** Remove multiple terminated instances in parallel. */
+    removeInstances(ids: string[]): Promise<number>;
+    /**
+     * Remove multiple instances from in-memory registry only (no file I/O).
+     * Returns the count removed and their persist file paths for caller-managed
+     * batch deletion.
+     */
+    removeInstancesInMemory(ids: string[]): {
+        removed: number;
+        filePaths: string[];
+    };
+    /** Send a message between agents. */
+    sendMessage(from: string, to: string, type: string, payload: unknown): AgentMessage;
+    /** Send a request and await a correlated response. */
+    requestResponse(from: string, to: string, type: string, payload: unknown, timeoutMs?: number): Promise<AgentMessage>;
+    /** Subscribe an agent to receive messages. */
+    subscribeAgent(agentId: string, handler: (msg: AgentMessage) => void): void;
+    /** Subscribe to lifecycle events. */
+    onLifecycle(handler: (event: LifecycleEvent) => void): void;
+    /** Subscribe to agent error events. */
+    onError(handler: (data: {
+        agentId: string;
+        error: AgentError;
+    }) => void): void;
+    /** Subscribe to resource warning events. */
+    onResourceWarning(handler: (data: {
+        usage: ResourceSnapshot;
+    }) => void): void;
+    private handleExit;
+    private handleExitInner;
+    /**
+     * Emit terminal failure event and finalize task store + memory.
+     * Called when all retries are exhausted or a non-recoverable error occurs
+     * within the retry path. This ensures external listeners (spawn.ts batch
+     * tracking) are notified and the task store reflects the final state.
+     *
+     * Without this, tasks that fail during retries would leave the task store
+     * in a stale "running" state and batch continuation would never trigger.
+     */
+    private finalizeTerminalFailure;
+    private maybeRetry;
+    private recoverAgents;
+    private startMonitor;
+    private stopMonitor;
+    private monitorCycle;
+    private requireInstance;
+    private assertState;
+    /**
+     * Detect deterministic failures that won't succeed on retry.
+     * Checks output for patterns like TypeScript errors, missing modules, etc.
+     * A broader pattern set prevents wasting retry budget on non-recoverable errors.
+     */
+    private isDeterministicFailure;
+    private toAgentError;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/agents/runtime/manager.d.ts.map

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