@cuylabs/agent-core 0.6.0 → 0.8.0

package/dist/types-CHiPh8U2.d.ts

@@ -0,0 +1,100 @@
+/**
+ * ToolHost — execution environment abstraction for agent tools.
+ *
+ * A ToolHost defines *where* tools execute: local machine, Docker container,
+ * SSH remote, etc. Every host provides two surfaces:
+ *
+ * 1. **File system** — read, write, stat, list, check existence
+ * 2. **Process execution** — spawn commands, kill processes
+ *
+ * Tools call `ctx.host.readFile()` / `ctx.host.exec()` instead of importing
+ * `fs` and `child_process` directly. The host implementation handles the rest.
+ *
+ * @example
+ * ```typescript
+ * // Default: runs everything locally
+ * const agent = createAgent({ host: localHost() });
+ *
+ * // Future: run tools inside a Docker container
+ * const agent = createAgent({ host: dockerHost("my-container") });
+ * ```
+ */
+/** Options for spawning a process. */
+interface ExecOptions {
+    /** Working directory for the command. */
+    cwd?: string;
+    /** Environment variables (merged with host defaults). */
+    env?: Record<string, string | undefined>;
+    /** Abort signal for cancellation. */
+    signal?: AbortSignal;
+    /** Timeout in milliseconds. 0 = no timeout. */
+    timeout?: number;
+    /** Callback for stdout data as it arrives. */
+    onStdout?: (data: Buffer) => void;
+    /** Callback for stderr data as it arrives. */
+    onStderr?: (data: Buffer) => void;
+}
+/** Result of a process execution. */
+interface ExecResult {
+    /** Combined stdout output. */
+    stdout: string;
+    /** Combined stderr output. */
+    stderr: string;
+    /** Exit code (null if killed by signal). */
+    exitCode: number | null;
+    /** Whether the process was killed due to timeout. */
+    timedOut: boolean;
+}
+/** Minimal stat result — only the fields tools actually need. */
+interface FileStat {
+    /** File size in bytes. */
+    size: number;
+    /** Last modification time. */
+    mtime: Date;
+    /** Whether this entry is a directory. */
+    isDirectory: boolean;
+    /** Whether this entry is a regular file. */
+    isFile: boolean;
+}
+/** A directory entry returned by `readdir`. */
+interface DirEntry {
+    /** Entry name (not full path). */
+    name: string;
+    /** Whether this entry is a directory. */
+    isDirectory: boolean;
+    /** Whether this entry is a regular file. */
+    isFile: boolean;
+}
+/**
+ * The execution environment for agent tools.
+ *
+ * Abstracts filesystem and process operations so tools work identically
+ * whether running locally, in Docker, over SSH, or in any other environment.
+ */
+interface ToolHost {
+    /** Human-readable host identifier (e.g. "local", "docker:my-container"). */
+    readonly name: string;
+    /** Read a file as a UTF-8 string. Throws if the file doesn't exist. */
+    readFile(path: string): Promise<string>;
+    /** Read raw bytes from a file. Throws if the file doesn't exist. */
+    readBytes(path: string, offset: number, length: number): Promise<Buffer>;
+    /** Write a UTF-8 string to a file. Creates parent directories as needed. */
+    writeFile(path: string, content: string): Promise<void>;
+    /** Check if a path exists. Never throws. */
+    exists(path: string): Promise<boolean>;
+    /** Get file metadata. Throws if the path doesn't exist. */
+    stat(path: string): Promise<FileStat>;
+    /** List directory entries. Throws if the path is not a directory. */
+    readdir(path: string): Promise<DirEntry[]>;
+    /** Create directories recursively. No-op if they already exist. */
+    mkdir(path: string): Promise<void>;
+    /**
+     * Execute a shell command.
+     *
+     * The host decides which shell to use (e.g. local host uses the user's
+     * `$SHELL`, Docker host uses `docker exec`, SSH host uses remote shell).
+     */
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+}
+
+export type { DirEntry as D, ExecOptions as E, FileStat as F, ToolHost as T, ExecResult as a };

package/dist/types-CQL-SvTn.d.ts

@@ -0,0 +1,29 @@
+type ScopeKind = "task" | "turn" | "model" | "tool" | "commit" | "sub-agent" | "activity";
+type ScopeAttributeValue = string | number | boolean | null;
+type ScopeAttributes = Record<string, ScopeAttributeValue | undefined>;
+interface Scope {
+    id: string;
+    rootId: string;
+    kind: ScopeKind;
+    name: string;
+    parentId?: string;
+    depth: number;
+    startedAt: string;
+    sessionId?: string;
+    taskId?: string;
+    step?: number;
+    attributes: ScopeAttributes;
+}
+type ScopeSnapshot = Scope;
+interface ScopeOptions {
+    id?: string;
+    kind: ScopeKind;
+    name: string;
+    parent?: ScopeSnapshot | null;
+    sessionId?: string;
+    taskId?: string;
+    step?: number;
+    attributes?: ScopeAttributes;
+}
+
+export type { ScopeSnapshot as S, Scope as a, ScopeAttributeValue as b, ScopeAttributes as c, ScopeKind as d, ScopeOptions as e };

package/dist/types-CWm-7rvB.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Risk level for operations.
+ */
+type RiskLevel = "safe" | "moderate" | "dangerous";
+/**
+ * User response to an approval request.
+ */
+type ApprovalAction = "allow" | "deny" | "remember";
+/**
+ * Approval request sent to the UI/handler.
+ */
+interface ApprovalRequest {
+    /** Unique request ID */
+    id: string;
+    /** Session ID */
+    sessionId: string;
+    /** Tool name */
+    tool: string;
+    /** Tool arguments */
+    args: unknown;
+    /** Human-readable description */
+    description: string;
+    /** Risk level */
+    risk: RiskLevel;
+    /** Patterns that would be remembered if "remember" is chosen */
+    patterns: string[];
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Rule for auto-approving/denying operations.
+ */
+interface ApprovalRule {
+    /** Pattern to match (glob-style) */
+    pattern: string;
+    /** Tool to match (`*` for all) */
+    tool: string;
+    /** Action to take */
+    action: "allow" | "deny";
+}
+/**
+ * Configuration for the approval handler.
+ */
+interface ApprovalConfig {
+    /** Default action when no rule matches (default: "ask") */
+    defaultAction?: "allow" | "deny" | "ask";
+    /** Pre-configured rules */
+    rules?: ApprovalRule[];
+    /** Handler for approval requests */
+    onRequest?: (request: ApprovalRequest) => Promise<ApprovalAction>;
+    /** Timeout for approval requests in ms (default: 5 minutes) */
+    timeout?: number;
+}
+
+export type { ApprovalAction as A, RiskLevel as R, ApprovalConfig as a, ApprovalRequest as b, ApprovalRule as c };

package/dist/types-KKDrdU9Y.d.ts

@@ -0,0 +1,325 @@
+import { StreamTextResult, ToolSet, Output, LanguageModel, ModelMessage, TelemetrySettings } from 'ai';
+import { T as Tool } from './tool-BHbyUAy3.js';
+import { T as ToolHost } from './types-CHiPh8U2.js';
+import { S as StreamChunk, d as StreamProvider, M as MiddlewareRunner, e as ModelCallInput } from './runner-e2YRcUoX.js';
+import { R as ReasoningLevel } from './types-CQaXbRsS.js';
+import { d as TurnTrackerContext } from './tool-DLXAR9Ce.js';
+import { L as LLMError } from './llm-error-D93FNNLY.js';
+
+/**
+ * Intervention Controller for @cuylabs/agent-core
+ *
+ * Manages mid-turn message injection into running agent turns.
+ * Uses Vercel AI SDK v6's `prepareStep` hook for zero-overhead
+ * integration at step boundaries (between LLM calls in a multi-step turn).
+ *
+ * Instead of polling a queue after each tool execution, this leverages
+ * the SDK's native step lifecycle. The
+ * `prepareStep` callback fires before every LLM call, giving us a
+ * natural injection point with no custom loop machinery.
+ *
+ * Two injection modes:
+ * - **Immediate**: `intervene(msg)` — injected at the next step boundary
+ * - **Deferred**: `queueNext(msg)` — held until the turn completes
+ */
+/** A queued intervention message waiting to be applied */
+interface PendingIntervention {
+    /** Unique identifier for tracking */
+    readonly id: string;
+    /** The user message to inject */
+    readonly message: string;
+    /** When the intervention was created */
+    readonly createdAt: Date;
+}
+/**
+ * Callback fired when an intervention is applied to a step.
+ *
+ * The agent uses this to push `intervention-applied` events into
+ * the streaming event queue so they reach the consumer in the
+ * correct order relative to other events.
+ */
+type OnInterventionApplied = (intervention: PendingIntervention) => void;
+/**
+ * Manages mid-turn message injection for agents.
+ *
+ * This is the core primitive that connects user redirection intent
+ * to the AI SDK's multi-step loop. The flow:
+ *
+ * 1. Consumer calls `agent.intervene("focus on auth.ts")` from any async context
+ * 2. The message is queued as a `PendingIntervention`
+ * 3. At the next step boundary, `prepareStep` drains the queue
+ * 4. The message is appended to the LLM's input messages
+ * 5. The LLM responds to the redirect naturally
+ *
+ * Thread safety: All operations are synchronous and run on the
+ * same event loop. No locks needed — Node.js guarantees ordering.
+ *
+ * @example
+ * ```typescript
+ * const ctrl = new InterventionController();
+ *
+ * // Queue an intervention (from a UI handler, WebSocket, etc.)
+ * const id = ctrl.intervene("stop refactoring, fix the failing test first");
+ *
+ * // Later, in prepareStep:
+ * const pending = ctrl.drainImmediate();
+ * // → [{ id, message: "stop refactoring...", createdAt }]
+ * ```
+ */
+declare class InterventionController {
+    /** Immediate interventions — applied at the next step boundary */
+    private immediate;
+    /** Deferred messages — held until the turn completes */
+    private deferred;
+    /**
+     * Callback fired when an intervention is wired into a step.
+     * Set by the Agent before starting a chat turn, cleared after.
+     */
+    onApplied?: OnInterventionApplied;
+    /**
+     * Inject a message at the next LLM step boundary.
+     *
+     * The message is appended as a user message to the conversation
+     * before the next LLM call in the current multi-step turn. The
+     * LLM will see it and can adjust its behavior accordingly.
+     *
+     * Safe to call from any async context while `chat()` is running.
+     * If called when no turn is active, the message will be picked up
+     * by the first step of the next `chat()` call.
+     *
+     * @param message - The user message to inject
+     * @returns Intervention ID for tracking
+     */
+    intervene(message: string): string;
+    /**
+     * Drain and return all pending immediate interventions.
+     * The internal queue is cleared atomically.
+     *
+     * @internal Called by the LLM stream's `prepareStep` hook
+     */
+    drainImmediate(): PendingIntervention[];
+    /** Whether there are pending immediate interventions */
+    get hasPending(): boolean;
+    /** Number of pending immediate interventions */
+    get pendingCount(): number;
+    /**
+     * Queue a message for after the current turn completes.
+     *
+     * Unlike `intervene()`, this does **not** inject mid-turn. The
+     * message is held and available via `drainDeferred()` after
+     * `chat()` finishes. The consumer decides whether to send it
+     * as a new turn.
+     *
+     * @param message - The message to queue
+     * @returns Intervention ID for tracking
+     */
+    queueNext(message: string): string;
+    /**
+     * Drain and return all deferred messages.
+     * The internal queue is cleared atomically.
+     */
+    drainDeferred(): PendingIntervention[];
+    /** Whether there are deferred messages */
+    get hasDeferred(): boolean;
+    /** Number of deferred messages */
+    get deferredCount(): number;
+    /** Clear all queues (immediate + deferred) */
+    clear(): void;
+    /** Reset the controller for a new turn (clears onApplied, keeps queues) */
+    resetCallbacks(): void;
+}
+
+/**
+ * Retry logic with exponential backoff for @cuylabs/agent-core
+ *
+ * Provides configurable retry behavior with header-aware delays,
+ * exponential backoff, and abort signal support.
+ */
+
+/**
+ * Retry configuration
+ */
+interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Initial delay in ms (default: 2000) */
+    initialDelayMs?: number;
+    /** Backoff multiplier (default: 2) */
+    backoffFactor?: number;
+    /** Maximum delay without headers in ms (default: 30000) */
+    maxDelayMs?: number;
+    /** Whether to jitter delays (default: true) */
+    jitter?: boolean;
+    /** Callback when retrying */
+    onRetry?: (attempt: number, delayMs: number, error: LLMError) => void;
+}
+/**
+ * Default retry configuration
+ */
+declare const DEFAULT_RETRY_CONFIG: Required<Omit<RetryConfig, "onRetry">>;
+/**
+ * Tracks retry state across attempts
+ */
+interface RetryState {
+    /** Current attempt number (1-indexed) */
+    attempt: number;
+    /** Total errors encountered */
+    errors: LLMError[];
+    /** Whether more retries are available */
+    canRetry: boolean;
+    /** Delay until next retry (if applicable) */
+    nextDelayMs?: number;
+}
+/**
+ * Creates initial retry state
+ */
+declare function createRetryState(): RetryState;
+/**
+ * Calculate delay for a retry attempt
+ */
+declare function calculateDelay(attempt: number, error: LLMError | undefined, config: Required<Omit<RetryConfig, "onRetry">>): number;
+/**
+ * Sleep for a duration, respecting abort signal
+ */
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Execute a function with retry logic
+ */
+declare function withRetry<T>(fn: (attempt: number) => Promise<T>, config?: RetryConfig, signal?: AbortSignal): Promise<T>;
+/**
+ * Options for retry handler
+ */
+interface RetryHandlerOptions extends RetryConfig {
+    /** Abort signal */
+    signal?: AbortSignal;
+}
+/**
+ * Creates a retry handler that wraps stream creation
+ */
+declare function createRetryHandler(options?: RetryHandlerOptions): <T>(createStream: (attempt: number) => Promise<T>) => Promise<T>;
+/**
+ * Checks if more retries should be attempted
+ */
+declare function shouldRetry(error: unknown, attempt: number, maxAttempts?: number): boolean;
+
+/** Stream result type - uses default Output for text streaming. */
+type InferenceStreamResult = StreamTextResult<ToolSet, Output.Output<string, string, never>>;
+/**
+ * @deprecated Use `InferenceStreamResult`.
+ */
+type LLMStreamResult = InferenceStreamResult;
+
+/**
+ * Custom stream result type - compatible shape from external providers.
+ */
+type InferenceCustomResult = {
+    fullStream: AsyncIterable<StreamChunk>;
+    text: Promise<string>;
+    usage: Promise<{
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    }>;
+    finishReason: Promise<string>;
+};
+/** Union type for stream results - either AI SDK or custom. */
+type AnyInferenceResult = InferenceStreamResult | InferenceCustomResult;
+/**
+ * @deprecated Use `InferenceCustomResult`.
+ */
+type CustomStreamResult = InferenceCustomResult;
+/**
+ * @deprecated Use `AnyInferenceResult`.
+ */
+type AnyStreamResult = AnyInferenceResult;
+/** Default max output tokens. */
+declare const DEFAULT_MAX_OUTPUT_TOKENS = 32000;
+/**
+ * @deprecated Use `DEFAULT_MAX_OUTPUT_TOKENS`.
+ */
+declare const OUTPUT_TOKEN_MAX = 32000;
+/**
+ * @deprecated Use StreamProvider from types instead.
+ */
+type CustomStreamProvider = StreamProvider;
+/** Control whether AI SDK tool definitions auto-execute or only expose calls. */
+type ToolExecutionMode = "auto" | "plan";
+/**
+ * Input for model inference stream creation.
+ */
+interface InferenceStreamInput {
+    /** Session ID */
+    sessionID: string;
+    /** Step number within the current turn */
+    step?: number;
+    /** Model to use */
+    model: LanguageModel;
+    /** System prompt parts */
+    system: string[];
+    /** Messages to send */
+    messages: ModelMessage[];
+    /** Abort signal */
+    abort: AbortSignal;
+    /** Tools to use */
+    tools: Record<string, Tool.Info>;
+    /** Whether tools should auto-execute or only be surfaced as tool calls. */
+    toolExecutionMode?: ToolExecutionMode;
+    /** Working directory */
+    cwd: string;
+    /** Execution environment for tools */
+    host?: ToolHost;
+    /** Temperature */
+    temperature?: number;
+    /** Top-p */
+    topP?: number;
+    /** Max output tokens */
+    maxOutputTokens?: number;
+    /** Max steps (tool iterations) */
+    maxSteps?: number;
+    /** Reasoning level for extended-thinking models */
+    reasoningLevel?: ReasoningLevel;
+    /** Retry configuration */
+    retry?: RetryConfig;
+    /** Callback for step completion */
+    onStepFinish?: (step: InferenceStepInfo) => void | Promise<void>;
+    /** Custom stream provider */
+    customStreamProvider?: StreamProvider;
+    /** Turn tracker for automatic file baseline capture */
+    turnTracker?: TurnTrackerContext;
+    /** Pre-built MCP tools */
+    mcpTools?: ToolSet;
+    /** Intervention controller for mid-turn message injection */
+    intervention?: InterventionController;
+    /** Middleware runner for lifecycle hooks */
+    middleware?: MiddlewareRunner;
+    /** AI SDK telemetry settings */
+    telemetry?: TelemetrySettings;
+    /** Internal snapshot of the resolved model request after middleware input hooks. */
+    activeModelCall?: ModelCallInput;
+}
+/**
+ * Step information surfaced to callers.
+ */
+interface InferenceStepInfo {
+    toolResults?: Array<{
+        toolName: string;
+        toolCallId: string;
+        output: unknown;
+    }>;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+    finishReason?: string;
+}
+/**
+ * @deprecated Use `InferenceStreamInput`.
+ */
+type LLMStreamInput = InferenceStreamInput;
+/**
+ * @deprecated Use `InferenceStepInfo`.
+ */
+type StepInfo = InferenceStepInfo;
+
+export { type AnyInferenceResult as A, type CustomStreamProvider as C, DEFAULT_MAX_OUTPUT_TOKENS as D, type InferenceStreamInput as I, type LLMStreamInput as L, OUTPUT_TOKEN_MAX as O, type PendingIntervention as P, type RetryConfig as R, type StepInfo as S, type ToolExecutionMode as T, type AnyStreamResult as a, type CustomStreamResult as b, type InferenceCustomResult as c, type InferenceStepInfo as d, type InferenceStreamResult as e, type LLMStreamResult as f, InterventionController as g, DEFAULT_RETRY_CONFIG as h, type OnInterventionApplied as i, type RetryHandlerOptions as j, type RetryState as k, calculateDelay as l, createRetryHandler as m, createRetryState as n, sleep as o, shouldRetry as s, withRetry as w };

package/dist/{resolver-DOfZ-xuk.d.ts → types-QA4WhEfz.d.ts}

@@ -1,5 +1,3 @@
-import { LanguageModel } from 'ai';
-
 /**
  * Model Capability Types for @cuylabs/agent-core
  *
@@ -137,118 +135,4 @@ interface ResolverOptions {
  */
 declare const DEFAULT_RESOLVER_OPTIONS: Required<ResolverOptions>;
 
-interface NetworkStatus {
-    online: boolean;
-    lastSuccess?: number;
-    lastError?: string;
-    failureCount: number;
-}
-
-/**
- * Model Capability Resolver for @cuylabs/agent-core
- *
- * Main orchestrator that combines multiple capability sources:
- * 1. User overrides (highest priority)
- * 2. Local cache (fast, persisted)
- * 3. Pattern matching (always available)
- * 4. Remote API (optional, network-dependent)
- *
- * Designed for the Vercel AI SDK v6 ecosystem.
- */
-
-/**
- * Extract model ID from LanguageModel
- */
-declare function extractModelId(model: LanguageModel): string;
-/**
- * Extract provider from LanguageModel
- */
-declare function extractProvider(model: LanguageModel): string | undefined;
-/**
- * Resolution result with source information
- */
-interface ResolutionResult {
-    /** The resolved model entry */
-    entry: ModelEntry;
-    /** Which source provided the primary result */
-    source: SourcePriority;
-    /** Whether this is a confident match */
-    confident: boolean;
-    /** Resolution timing in ms */
-    resolveTimeMs: number;
-}
-/**
- * Model Capability Resolver
- *
- * Provides a unified API for querying model capabilities with
- * automatic fallback through multiple sources.
- */
-declare class ModelCapabilityResolver {
-    private options;
-    private cache;
-    private sources;
-    private initialized;
-    private initPromise;
-    constructor(options?: Partial<ResolverOptions>);
-    /**
-     * Initialize the resolver (load cache, optionally fetch remote)
-     */
-    initialize(): Promise<void>;
-    /**
-     * Resolve capabilities for a model
-     */
-    resolve(model: LanguageModel): Promise<ResolutionResult>;
-    /**
-     * Quick check if a model supports reasoning
-     * Uses cache/patterns only for speed
-     */
-    supportsReasoning(model: LanguageModel): Promise<boolean>;
-    /**
-     * Get capabilities for a model
-     */
-    getCapabilities(model: LanguageModel): Promise<ModelCapabilities>;
-    /**
-     * Get provider compatibility settings
-     */
-    getCompatibility(model: LanguageModel): Promise<ProviderCompatibility | undefined>;
-    /**
-     * Force refresh from remote API
-     */
-    refreshRemote(): Promise<void>;
-    /**
-     * Get current network status
-     */
-    getNetworkStatus(): NetworkStatus;
-    /**
-     * Get resolver statistics
-     */
-    getStats(): {
-        cacheSize: number;
-        cacheLoaded: boolean;
-        remoteFetchEnabled: boolean;
-        networkOnline: boolean;
-    };
-    /**
-     * Clear all cached data
-     */
-    clearCache(): Promise<void>;
-    /**
-     * List all available models
-     * Fetches from remote if cache is empty and remote is enabled
-     */
-    listModels(): Promise<ModelEntry[]>;
-    /**
-     * List all available models grouped by provider
-     */
-    listModelsByProvider(): Promise<Record<string, ModelEntry[]>>;
-}
-/**
- * Get the default resolver instance
- */
-declare function getDefaultResolver(): ModelCapabilityResolver;
-/**
- * Configure the default resolver with custom options
- */
-declare function configureResolver(options: Partial<ResolverOptions>): void;
-
-export { type CapabilitySource as C, DEFAULT_RESOLVER_OPTIONS as D, type InputModality as I, type ModelEntry as M, type NetworkStatus as N, type OutputModality as O, type ProviderCompatibility as P, type ResolverOptions as R, SourcePriority as S, extractProvider as a, type SourceResult as b, type ModelCapabilities as c, ModelCapabilityResolver as d, extractModelId as e, type ResolutionResult as f, configureResolver as g, getDefaultResolver as h };
+export { type CapabilitySource as C, DEFAULT_RESOLVER_OPTIONS as D, type InputModality as I, type ModelCapabilities as M, type OutputModality as O, type ProviderCompatibility as P, type ResolverOptions as R, SourcePriority as S, type ModelEntry as a, type SourceResult as b };