@runcore-sh/runcore 0.1.2

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

@@ -0,0 +1,168 @@
+/**
+ * Agent Runtime Environment — Type definitions.
+ *
+ * Defines the core abstractions for agent lifecycle management,
+ * resource allocation, inter-agent messaging, and driver interface.
+ */
+/** Finite states an agent instance can occupy. */
+export type AgentState = "initializing" | "running" | "paused" | "resuming" | "terminating" | "terminated" | "failed" | "completed";
+/** All valid state transitions. */
+export declare const VALID_TRANSITIONS: Record<AgentState, AgentState[]>;
+/** Terminal states — no further transitions possible. */
+export declare const TERMINAL_STATES: ReadonlySet<AgentState>;
+/** A runtime-managed agent instance. Links to an AgentTask by taskId. */
+export interface AgentInstance {
+    id: string;
+    taskId: string;
+    state: AgentState;
+    pid?: number;
+    config: AgentInstanceConfig;
+    resources: ResourceAllocation;
+    metadata: AgentMetadata;
+    /** Saved context for pause → resume cycles. */
+    checkpointData?: string;
+    /** Last runtime error (if state is "failed"). */
+    error?: AgentError;
+    retryCount: number;
+    createdAt: string;
+    updatedAt: string;
+    pausedAt?: string;
+    terminatedAt?: string;
+}
+/** Per-instance configuration (merged from defaults + request overrides). */
+export interface AgentInstanceConfig {
+    timeoutMs: number;
+    maxRetries: number;
+    backoffMs: number;
+    backoffMultiplier: number;
+    maxBackoffMs: number;
+    env: Record<string, string>;
+    isolation: "shared" | "sandboxed";
+    priority: number;
+}
+/** Resource limits assigned to a single agent. */
+export interface ResourceAllocation {
+    memoryLimitMB: number;
+    cpuWeight: number;
+}
+/** Descriptive metadata attached to an agent instance. */
+export interface AgentMetadata {
+    label: string;
+    origin: "user" | "ai" | "system";
+    parentId?: string;
+    tags: string[];
+}
+/** Structured error stored on failed agents. */
+export interface AgentError {
+    code: string;
+    message: string;
+    timestamp: string;
+    recoverable: boolean;
+    context?: Record<string, unknown>;
+}
+/** A message routed between agents via the event bus. */
+export interface AgentMessage {
+    id: string;
+    from: string;
+    to: string;
+    type: string;
+    payload: unknown;
+    timestamp: string;
+    /** For request/response patterns — correlate reply to original. */
+    correlationId?: string;
+    /** TTL in ms — message expires after this duration. */
+    ttlMs?: number;
+}
+/** Emitted on every state transition. */
+export interface LifecycleEvent {
+    agentId: string;
+    previousState: AgentState;
+    newState: AgentState;
+    timestamp: string;
+    reason?: string;
+}
+/** All event types the runtime bus emits. */
+export interface RuntimeEvents {
+    "agent:lifecycle": LifecycleEvent;
+    "agent:message": AgentMessage;
+    "agent:error": {
+        agentId: string;
+        error: AgentError;
+    };
+    "agent:spawned": {
+        agentId: string;
+        pid?: number;
+    };
+    "agent:completed": {
+        agentId: string;
+        exitCode?: number;
+    };
+    "agent:failed": {
+        agentId: string;
+        error: AgentError;
+    };
+    "runtime:resource-warning": {
+        usage: ResourceSnapshot;
+    };
+    "runtime:shutdown": {
+        reason: string;
+    };
+}
+/** Point-in-time snapshot of resource usage. */
+export interface ResourceSnapshot {
+    activeAgents: number;
+    maxAgents: number;
+    totalMemoryMB: number;
+    maxMemoryMB: number;
+    queuedRequests: number;
+}
+/**
+ * Strategy for how to run an agent process.
+ * Implementations handle the platform-specific spawning, pausing, resuming,
+ * and terminating. The runtime delegates to the driver for all process ops.
+ */
+export interface AgentDriver {
+    readonly name: string;
+    /** Spawn the agent. Returns PID if applicable. */
+    spawn(instance: AgentInstance): Promise<number | undefined>;
+    /**
+     * Pause a running agent. Returns a checkpoint string that can
+     * be passed to resume(). Not all drivers support pause — return
+     * undefined if unsupported.
+     */
+    pause(instance: AgentInstance): Promise<string | undefined>;
+    /** Resume a paused agent using checkpoint data. Returns new PID. */
+    resume(instance: AgentInstance, checkpoint?: string): Promise<number | undefined>;
+    /** Terminate the agent. Should be idempotent. */
+    terminate(instance: AgentInstance): Promise<void>;
+    /** Check if the agent's process is still alive. */
+    isAlive(instance: AgentInstance): boolean;
+}
+/** Top-level runtime configuration. */
+export interface RuntimeConfig {
+    maxConcurrentAgents: number;
+    defaultTimeoutMs: number;
+    defaultMaxRetries: number;
+    defaultBackoffMs: number;
+    defaultBackoffMultiplier: number;
+    defaultMaxBackoffMs: number;
+    maxTotalMemoryMB: number;
+    defaultMemoryLimitMB: number;
+    defaultCpuWeight: number;
+    monitorIntervalMs: number;
+    /** Directory for runtime persistence files. */
+    persistDir: string;
+}
+/** Request to spawn a new agent via the runtime. */
+export interface SpawnRequest {
+    taskId: string;
+    label: string;
+    prompt: string;
+    cwd?: string;
+    origin: "user" | "ai" | "system";
+    parentId?: string;
+    tags?: string[];
+    config?: Partial<AgentInstanceConfig>;
+    resources?: Partial<ResourceAllocation>;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/agents/runtime/types.js

@@ -0,0 +1,24 @@
+/**
+ * Agent Runtime Environment — Type definitions.
+ *
+ * Defines the core abstractions for agent lifecycle management,
+ * resource allocation, inter-agent messaging, and driver interface.
+ */
+/** All valid state transitions. */
+export const VALID_TRANSITIONS = {
+    initializing: ["running", "failed"],
+    running: ["paused", "terminating", "completed", "failed"],
+    paused: ["resuming", "terminating"],
+    resuming: ["running", "failed"],
+    terminating: ["terminated"],
+    terminated: [],
+    failed: [],
+    completed: [],
+};
+/** Terminal states — no further transitions possible. */
+export const TERMINAL_STATES = new Set([
+    "terminated",
+    "failed",
+    "completed",
+]);
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/agents/runtime/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAiBH,mCAAmC;AACnC,MAAM,CAAC,MAAM,iBAAiB,GAAqC;IACjE,YAAY,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC;IACnC,OAAO,EAAE,CAAC,QAAQ,EAAE,aAAa,EAAE,WAAW,EAAE,QAAQ,CAAC;IACzD,MAAM,EAAE,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC;IAC/B,WAAW,EAAE,CAAC,YAAY,CAAC;IAC3B,UAAU,EAAE,EAAE;IACd,MAAM,EAAE,EAAE;IACV,SAAS,EAAE,EAAE;CACd,CAAC;AAEF,yDAAyD;AACzD,MAAM,CAAC,MAAM,eAAe,GAA4B,IAAI,GAAG,CAAC;IAC9D,YAAY;IACZ,QAAQ;IACR,WAAW;CACZ,CAAC,CAAC"}

package/dist/agents/runtime.d.ts

@@ -0,0 +1,240 @@
+/**
+ * Agent Runtime Environment — Unified facade.
+ *
+ * Provides four core components on top of the existing runtime/ layer:
+ *
+ * 1. **AgentPool** — Pool-level lifecycle management (spawn, monitor, cleanup, drain).
+ * 2. **ResourceManager** — Per-agent CPU/memory allocation with utilization tracking.
+ * 3. **ErrorRecovery** — Retry policies with exponential backoff + circuit breakers.
+ * 4. **AgentIsolation** — Process boundary enforcement, env sanitization, timeouts.
+ *
+ * Usage:
+ *   const pool = await AgentPool.create();
+ *   const instance = await pool.spawn({ taskId, label, prompt, origin });
+ *   pool.getMonitoringSnapshot();
+ *   await pool.shutdown("done");
+ */
+import type { AgentInstance, AgentState, AgentError, SpawnRequest, ResourceAllocation, ResourceSnapshot, AgentInstanceConfig } from "./runtime/types.js";
+import { RuntimeManager } from "./runtime/manager.js";
+import { AgentInstanceManager, type HealthSummary, type InstanceHealth } from "./instance-manager.js";
+/** Circuit breaker states. */
+export type CircuitState = "closed" | "open" | "half-open";
+/** Configuration for a circuit breaker. */
+export interface CircuitBreakerConfig {
+    /** Failures within the window to trip the circuit. Default: 5. */
+    failureThreshold: number;
+    /** Rolling window for failure counting (ms). Default: 60s. */
+    windowMs: number;
+    /** How long the circuit stays open before probing (ms). Default: 30s. */
+    resetTimeoutMs: number;
+    /** Max probe attempts in half-open state before re-opening. Default: 2. */
+    halfOpenMaxProbes: number;
+}
+/** Per-operation circuit breaker state. */
+interface CircuitBreakerState {
+    state: CircuitState;
+    failures: number[];
+    lastFailure?: number;
+    openedAt?: number;
+    probeCount: number;
+    totalTrips: number;
+    config: CircuitBreakerConfig;
+}
+/** Retry policy for a spawn or operation. */
+export interface RetryPolicy {
+    maxRetries: number;
+    backoffMs: number;
+    backoffMultiplier: number;
+    maxBackoffMs: number;
+    /** Only retry on these error codes. Empty = retry all recoverable. */
+    retryableErrors?: string[];
+}
+/** Snapshot of error recovery state for monitoring. */
+export interface ErrorRecoverySnapshot {
+    circuits: Record<string, {
+        state: CircuitState;
+        failureCount: number;
+        totalTrips: number;
+        lastFailure?: string;
+        openedAt?: string;
+    }>;
+    retryPolicy: RetryPolicy;
+}
+export declare class ErrorRecovery {
+    private circuits;
+    private retryPolicy;
+    constructor(retryPolicy?: Partial<RetryPolicy>);
+    /** Get or create a circuit breaker for a named operation. */
+    getCircuit(name: string, config?: Partial<CircuitBreakerConfig>): CircuitBreakerState;
+    /**
+     * Check if an operation is allowed through its circuit breaker.
+     * Returns true if the call should proceed, false if the circuit is open.
+     */
+    allowRequest(circuitName: string): boolean;
+    /** Record a successful operation — resets the circuit to closed. */
+    recordSuccess(circuitName: string): void;
+    /** Record a failure — may trip the circuit to open. */
+    recordFailure(circuitName: string, error?: AgentError): void;
+    /** Calculate retry delay for a given attempt number. Returns null if exhausted. */
+    getRetryDelay(attempt: number, error?: AgentError): number | null;
+    /** Get a monitoring snapshot of all circuit breakers. */
+    snapshot(): ErrorRecoverySnapshot;
+    /** Reset a specific circuit breaker to closed. */
+    resetCircuit(name: string): void;
+    /** Clear all circuit breakers. */
+    clear(): void;
+}
+/** Isolation level for an agent. */
+export type IsolationLevel = "shared" | "sandboxed" | "strict";
+/** Isolation constraints applied to a spawn request. */
+export interface IsolationConstraints {
+    level: IsolationLevel;
+    /** Allowed env var prefixes. */
+    envAllowList: string[];
+    /** Maximum wall-clock time (ms). */
+    timeoutMs: number;
+    /** Working directory override (sandboxed agents get a unique dir). */
+    cwd?: string;
+    /** Whether the agent can spawn child agents. */
+    canSpawnChildren: boolean;
+}
+export declare class AgentIsolation {
+    private readonly sandboxRoot;
+    constructor(sandboxRoot?: string);
+    /** Resolve isolation constraints for a spawn request. */
+    resolveConstraints(request: SpawnRequest): IsolationConstraints;
+    /** Resolve strict isolation for untrusted or system-critical agents. */
+    resolveStrictConstraints(request: SpawnRequest): IsolationConstraints;
+    /**
+     * Sanitize environment variables based on isolation constraints.
+     * Returns a clean env object with only allowed variables.
+     */
+    sanitizeEnv(env: Record<string, string | undefined>, constraints: IsolationConstraints): Record<string, string>;
+    /**
+     * Apply isolation constraints to a spawn request's config.
+     * Returns the modified config partial to merge into the request.
+     */
+    applyToConfig(request: SpawnRequest, constraints: IsolationConstraints): Partial<AgentInstanceConfig>;
+}
+/** Per-agent resource usage record. */
+export interface AgentResourceUsage {
+    agentId: string;
+    label: string;
+    allocated: ResourceAllocation;
+    startedAt: string;
+    elapsedMs: number;
+    state: AgentState;
+}
+/** Detailed resource utilization snapshot. */
+export interface ResourceUtilization {
+    snapshot: ResourceSnapshot;
+    perAgent: AgentResourceUsage[];
+    utilization: {
+        agentPercent: number;
+        memoryPercent: number;
+    };
+    pressure: "low" | "moderate" | "high" | "critical";
+}
+export declare class ResourceManager {
+    private readonly runtime;
+    constructor(runtime: RuntimeManager);
+    /** Get detailed per-agent resource utilization. */
+    getUtilization(): ResourceUtilization;
+    /** Check if there's capacity to spawn with the given resources. */
+    canSpawn(resources?: Partial<ResourceAllocation>): boolean;
+    /** Get the number of queued spawn requests. */
+    get queueLength(): number;
+}
+/** Configuration for the agent pool. */
+export interface AgentPoolConfig {
+    /** Maximum concurrent agents. Overrides runtime default. */
+    maxConcurrent?: number;
+    /** Circuit breaker config for spawn operations. */
+    spawnCircuit?: Partial<CircuitBreakerConfig>;
+    /** Default retry policy for agent operations. */
+    retryPolicy?: Partial<RetryPolicy>;
+    /** Sandbox root for isolated agents. */
+    sandboxRoot?: string;
+    /** Whether to drain the queue on shutdown (vs. reject). Default: true. */
+    drainOnShutdown?: boolean;
+    /** Max time to wait for drain on shutdown (ms). Default: 30s. */
+    drainTimeoutMs?: number;
+}
+/** Full monitoring snapshot of the agent pool. */
+export interface PoolMonitoringSnapshot {
+    timestamp: string;
+    pool: {
+        active: number;
+        queued: number;
+        maxConcurrent: number;
+        totalSpawned: number;
+        totalCompleted: number;
+        totalFailed: number;
+    };
+    resources: ResourceUtilization;
+    errorRecovery: ErrorRecoverySnapshot;
+    health: HealthSummary | null;
+}
+export declare class AgentPool {
+    readonly errorRecovery: ErrorRecovery;
+    readonly isolation: AgentIsolation;
+    readonly resourceManager: ResourceManager;
+    private readonly runtime;
+    private readonly instanceManager;
+    private readonly config;
+    private totalSpawned;
+    private totalCompleted;
+    private totalFailed;
+    private shuttingDown;
+    private constructor();
+    /**
+     * Create and initialize a fully wired AgentPool.
+     * Uses the existing runtime singleton or creates one.
+     */
+    static create(config?: AgentPoolConfig): Promise<AgentPool>;
+    /**
+     * Create from existing runtime and instance manager.
+     * Use when the runtime is already initialized (e.g., from server.ts).
+     */
+    static fromExisting(runtime: RuntimeManager, instanceManager: AgentInstanceManager, config?: AgentPoolConfig): AgentPool;
+    /**
+     * Spawn an agent through the pool.
+     * Applies circuit breaker check, isolation constraints, and delegates
+     * to the instance manager for load-balanced spawning.
+     */
+    spawn(request: SpawnRequest): Promise<AgentInstance>;
+    /**
+     * Spawn with strict isolation for untrusted or system-critical agents.
+     */
+    spawnIsolated(request: SpawnRequest): Promise<AgentInstance>;
+    pause(instanceId: string, reason?: string): Promise<AgentInstance>;
+    resume(instanceId: string): Promise<AgentInstance>;
+    terminate(instanceId: string, reason?: string): Promise<AgentInstance>;
+    restart(instanceId: string, reason?: string): Promise<AgentInstance>;
+    getInstance(id: string): AgentInstance | undefined;
+    listActive(): AgentInstance[];
+    listAll(): AgentInstance[];
+    getHealthSummary(): HealthSummary;
+    assessHealth(instanceId: string): InstanceHealth;
+    /** Get a full monitoring snapshot of the pool. */
+    getMonitoringSnapshot(): PoolMonitoringSnapshot;
+    /**
+     * Graceful shutdown:
+     * 1. Stop accepting new spawns
+     * 2. Optionally drain the queue (wait for queued items to complete)
+     * 3. Terminate all active agents
+     * 4. Clean up resources
+     */
+    shutdown(reason?: string): Promise<void>;
+    /** Wait for the queue to drain, with a timeout. */
+    private drainQueue;
+    private attachEventTracking;
+    /** Access the underlying RuntimeManager. */
+    get runtimeManager(): RuntimeManager;
+    /** Access the underlying AgentInstanceManager. */
+    get agentInstanceManager(): AgentInstanceManager;
+    /** Whether the pool is in shutdown mode. */
+    get isShuttingDown(): boolean;
+}
+export {};
+//# sourceMappingURL=runtime.d.ts.map

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

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