@cuylabs/agent-core 0.5.0 → 0.7.0

package/dist/{tool-DYp6-cC3.d.ts → tool-HUtkiVBx.d.ts}

@@ -1,101 +1,5 @@
-/**
- * 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>;
-}
+import { T as ToolHost } from './types-CHiPh8U2.js';
+import { b as ScopeSnapshot } from './types-9jGQUjqW.js';
 
 /**
  * Tool-related types for @cuylabs/agent-core
@@ -128,6 +32,8 @@ interface ToolContext {
     messageID: string;
     /** Agent name */
     agent: string;
+    /** Active execution scope snapshot for this tool call. */
+    scope?: ScopeSnapshot;
     /**
      * Execution environment for file and process operations.
      *
@@ -236,4 +142,4 @@ interface ToolMetadata {
     [key: string]: unknown;
 }
 
-export type { DirEntry as D, ExecOptions as E, FileOperationMeta as F, NormalizedToolReplayPolicy as N, ToolMetadata as T, ToolReplayPolicy as a, ToolContext as b, ToolResult as c, ToolHost as d, TurnTrackerContext as e, ExecResult as f, FileStat as g, ToolReplayMode as h, ToolSideEffectLevel as i };
+export type { FileOperationMeta as F, NormalizedToolReplayPolicy as N, ToolMetadata as T, ToolReplayPolicy as a, ToolContext as b, ToolResult as c, TurnTrackerContext as d, ToolReplayMode as e, ToolSideEffectLevel as f };

package/dist/tracking/index.d.ts

@@ -1,6 +1,8 @@
 import { T as TurnChangeTracker } from '../tracker-DClqYqTj.js';
 export { F as FileBaseline, a as TurnFileChange, b as TurnSummary, c as TurnTrackerConfig, U as UndoResult, d as createTurnTracker } from '../tracker-DClqYqTj.js';
-import { F as FileOperationMeta } from '../tool-DYp6-cC3.js';
+import { F as FileOperationMeta } from '../tool-HUtkiVBx.js';
+import '../types-CHiPh8U2.js';
+import '../types-9jGQUjqW.js';
 
 /**
  * Checkpoint system contracts for @cuylabs/agent-core.

package/dist/types-9jGQUjqW.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 { ScopeOptions as S, Scope as a, ScopeSnapshot as b, ScopeAttributeValue as c, ScopeAttributes as d, ScopeKind as e };

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-CqDZTh4d.d.ts

@@ -0,0 +1,335 @@
+import { LanguageModel, TelemetrySettings, ModelMessage, ToolSet } from 'ai';
+import { T as Tool } from './tool-Db1Ue-1U.js';
+import { T as ToolHost } from './types-CHiPh8U2.js';
+import { f as StepProcessingResult, A as AgentEvent, g as AgentTurnBoundaryKind, d as StreamProvider, M as MiddlewareRunner } from './runner-DSKaEz3z.js';
+import { g as InterventionController, T as ToolExecutionMode, I as InferenceStreamInput } from './types-FRpzzg_9.js';
+import { R as ReasoningLevel } from './types-CQaXbRsS.js';
+import { N as NormalizedToolReplayPolicy, d as TurnTrackerContext } from './tool-HUtkiVBx.js';
+import { T as TokenUsage, M as Message } from './messages-BYWGn8TY.js';
+
+/**
+ * Doom-loop handling contracts for repeated tool invocations.
+ */
+/**
+ * Response from a doom-loop handler.
+ */
+type DoomLoopAction = "allow" | "deny" | "remember";
+/**
+ * Doom-loop detection request.
+ */
+interface DoomLoopRequest {
+    /** The tool being called repeatedly */
+    tool: string;
+    /** How many times it has been called with the same input */
+    repeatCount: number;
+    /** The repeated input */
+    input: unknown;
+    /** Session ID */
+    sessionId: string;
+}
+/**
+ * Handler for doom-loop situations.
+ */
+type DoomLoopHandler = (request: DoomLoopRequest) => Promise<DoomLoopAction>;
+
+/**
+ * Options for processing a streamed model result.
+ */
+interface StepProcessingOptions {
+    /** Session ID (optional - for tracking purposes) */
+    sessionID?: string;
+    /** Abort signal */
+    abort: AbortSignal;
+    /** Event callback */
+    onEvent: (event: AgentEvent) => void | Promise<void>;
+    /** Doom loop threshold (default: 3) */
+    doomLoopThreshold?: number;
+    /** Enforce doom loop (throw error vs warn) when no handler is provided */
+    enforceDoomLoop?: boolean;
+    /**
+     * Handler for doom loop detection.
+     * Allows user choice: allow, deny, or remember.
+     */
+    onDoomLoop?: DoomLoopHandler;
+    /** Tools that are "remembered" (allowed without asking) */
+    rememberedDoomLoopTools?: Set<string>;
+    /** Token limit for context overflow detection */
+    contextTokenLimit?: number;
+    /** Callback for context overflow */
+    onContextOverflow?: (tokens: number, limit: number) => void | Promise<void>;
+    /** Current step number */
+    currentStep?: number;
+    /** Max steps */
+    maxSteps?: number;
+}
+/**
+ * Result of stream processing.
+ */
+interface StepProcessingOutput {
+    /** Processing result */
+    result: StepProcessingResult;
+    /** Accumulated text */
+    text: string;
+    /** Tool results */
+    toolResults: Array<{
+        toolName: string;
+        toolCallId: string;
+        result: unknown;
+    }>;
+    /** Final usage */
+    usage?: TokenUsage;
+    /** Finish reason reported by the most recent completed step */
+    finishReason?: string;
+    /** Error if any */
+    error?: Error;
+}
+/**
+ * @deprecated Use `StepProcessingOptions`.
+ */
+type ProcessorOptions = StepProcessingOptions;
+/**
+ * @deprecated Use `StepProcessingOutput`.
+ */
+type ProcessorOutput = StepProcessingOutput;
+
+interface AgentTurnEngineOptions {
+    sessionId: string;
+    startedAt: string;
+    getToolReplayPolicy?: (toolName: string) => NormalizedToolReplayPolicy | undefined;
+}
+interface AgentTurnBoundaryMetadata {
+    step?: number;
+    messageRole?: Message["role"];
+    pendingToolCallCount?: number;
+}
+interface AgentTurnStepCommitToolCall {
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    replayPolicy?: NormalizedToolReplayPolicy;
+}
+interface AgentTurnStepCommitToolResult {
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+    replayPolicy?: NormalizedToolReplayPolicy;
+}
+interface AgentTurnStepCommitSnapshot {
+    toolCalls: AgentTurnStepCommitToolCall[];
+    toolResults: AgentTurnStepCommitToolResult[];
+}
+interface CreateAgentTurnStepCommitBatchOptions {
+    assistantMessageId?: string;
+    toolMessageIds?: Record<string, string>;
+    createdAt?: Date;
+}
+interface AgentTurnCommitBatch {
+    startBoundary: AgentEvent & {
+        type: "turn-boundary";
+    };
+    finishBoundary: AgentEvent & {
+        type: "turn-boundary";
+    };
+    messages: Message[];
+}
+interface AgentTurnOutputCommitOptions {
+    text: string;
+    usage?: TokenUsage;
+    createdAt?: Date;
+    id?: string;
+}
+type AgentTurnBoundaryEvent = AgentEvent & {
+    type: "turn-boundary";
+};
+
+type AgentTurnPhase = "initializing" | "committing-input" | "running-model" | "running-tools" | "committing-step" | "committing-output" | "completed" | "failed";
+interface AgentTurnBoundarySnapshot {
+    kind: AgentTurnBoundaryKind;
+    createdAt: string;
+    step?: number;
+    messageRole?: "system" | "user" | "assistant" | "tool";
+    pendingToolCallCount?: number;
+}
+interface AgentTurnActiveToolCall {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    startedAt: string;
+    replayPolicy?: NormalizedToolReplayPolicy;
+}
+interface AgentTurnResolvedToolCall {
+    toolCallId: string;
+    toolName: string;
+    outcome: "result" | "error";
+    value: unknown;
+    resolvedAt: string;
+    replayPolicy?: NormalizedToolReplayPolicy;
+}
+/**
+ * Neutral state model for a single in-flight agent turn.
+ *
+ * This is intentionally infrastructure-agnostic. Runtime adapters can persist
+ * or inspect it without coupling `agent-core` to Dapr, queues, or workflow
+ * engines. The current shape is suitable for durable tracking and forms the
+ * basis for future workflow-level resume support.
+ */
+interface AgentTurnState {
+    sessionId: string;
+    phase: AgentTurnPhase;
+    step: number;
+    maxSteps?: number;
+    response: string;
+    usage: TokenUsage;
+    eventCount: number;
+    activeToolCalls: AgentTurnActiveToolCall[];
+    resolvedToolCalls: AgentTurnResolvedToolCall[];
+    lastFinishReason?: string;
+    lastBoundary?: AgentTurnBoundarySnapshot;
+    lastEvent?: AgentEvent;
+    error?: string;
+    startedAt: string;
+    updatedAt: string;
+}
+interface CreateAgentTurnStateOptions {
+    sessionId: string;
+    startedAt: string;
+}
+interface AgentTurnStateAdvanceOptions {
+    toolReplayPolicy?: NormalizedToolReplayPolicy;
+}
+/**
+ * Create the initial neutral state for a single agent turn.
+ */
+declare function createAgentTurnState(options: CreateAgentTurnStateOptions): AgentTurnState;
+/**
+ * Advance neutral turn state from a streamed `AgentEvent`.
+ *
+ * This reducer deliberately models coarse but deterministic boundaries:
+ * step start, tool activity, step finish, completion, and failure. Runtime
+ * adapters can persist the resulting state now, and future resume-capable
+ * engines can build on the same state transitions.
+ */
+declare function advanceAgentTurnState(state: AgentTurnState, event: AgentEvent, updatedAt: string, options?: AgentTurnStateAdvanceOptions): AgentTurnState;
+/**
+ * Mark the turn as failed when execution aborts without a terminal `error`
+ * event. This covers exceptions thrown by the stream itself or runtime
+ * wrappers around the loop.
+ */
+declare function failAgentTurnState(state: AgentTurnState, error: Error, updatedAt: string): AgentTurnState;
+
+/**
+ * Neutral internal turn engine for one in-flight agent turn.
+ */
+declare class AgentTurnEngine {
+    private turnState;
+    private readonly pendingToolCalls;
+    private readonly pendingToolResults;
+    private readonly getToolReplayPolicy?;
+    constructor(options: AgentTurnEngineOptions);
+    getState(): AgentTurnState;
+    hasPendingToolCalls(): boolean;
+    createStepCommitSnapshot(): AgentTurnStepCommitSnapshot | undefined;
+    recordEvent(event: AgentEvent, updatedAt: string): AgentTurnState;
+    createBoundaryEvent(boundary: AgentTurnBoundaryKind, metadata?: AgentTurnBoundaryMetadata): AgentTurnBoundaryEvent;
+    createInputCommit(options: {
+        content: string;
+        system?: string;
+        createdAt?: Date;
+        id?: string;
+    }): AgentTurnCommitBatch;
+    createInterventionCommit(options: {
+        id: string;
+        content: string;
+        createdAt?: Date;
+    }): AgentTurnCommitBatch;
+    consumeStepCommit(step: number): AgentTurnCommitBatch | undefined;
+    createOutputCommit(options: AgentTurnOutputCommitOptions): AgentTurnCommitBatch | undefined;
+}
+declare function createAgentTurnEngine(options: AgentTurnEngineOptions): AgentTurnEngine;
+
+interface AgentTurnCommitOptions {
+    emitMessages?: boolean;
+}
+type AgentTurnCommitApplier = (batch: AgentTurnCommitBatch, options?: AgentTurnCommitOptions) => AsyncGenerator<AgentEvent>;
+interface AgentTurnStepRuntimeConfig {
+    model: LanguageModel;
+    cwd: string;
+    temperature?: number;
+    topP?: number;
+    maxOutputTokens?: number;
+    maxSteps: number;
+    doomLoopThreshold?: number;
+    enforceDoomLoop?: boolean;
+    onDoomLoop?: DoomLoopHandler;
+    contextWindow?: number;
+    streamProvider?: StreamProvider;
+    telemetry?: TelemetrySettings;
+}
+interface PrepareModelStepOptions {
+    sessionId: string;
+    step: number;
+    systemPrompts: string[];
+    messages: Message[];
+    toModelMessages: (messages: Message[]) => ModelMessage[];
+    abort: AbortSignal;
+    tools: Record<string, Tool.Info>;
+    mcpTools?: ToolSet;
+    config: AgentTurnStepRuntimeConfig;
+    host?: ToolHost;
+    turnTracker?: TurnTrackerContext;
+    intervention?: InterventionController;
+    middleware?: MiddlewareRunner;
+    reasoningLevel?: ReasoningLevel;
+    toolExecutionMode?: ToolExecutionMode;
+}
+interface PreparedAgentModelStep {
+    step: number;
+    messages: Message[];
+    modelMessages: ModelMessage[];
+    inferenceInput: InferenceStreamInput;
+    stepProcessing: {
+        maxSteps: number;
+        doomLoopThreshold?: number;
+        enforceDoomLoop?: boolean;
+        onDoomLoop?: DoomLoopHandler;
+        contextTokenLimit?: number;
+    };
+}
+interface RunModelStepOptions {
+    preparedStep: PreparedAgentModelStep;
+    turnEngine: AgentTurnEngine;
+    applyCommitBatch: AgentTurnCommitApplier;
+    rememberedDoomLoopTools?: Set<string>;
+}
+interface CommitStepOptions {
+    step: number;
+    finishReason?: string;
+    turnEngine: AgentTurnEngine;
+    applyCommitBatch: AgentTurnCommitApplier;
+}
+interface CommitOutputOptions {
+    text: string;
+    usage?: StepProcessingOutput["usage"];
+    turnEngine: AgentTurnEngine;
+    applyCommitBatch: AgentTurnCommitApplier;
+}
+interface RunToolBatchOptions {
+    sessionId: string;
+    snapshot: AgentTurnStepCommitSnapshot;
+    tools: Record<string, Tool.Info>;
+    cwd: string;
+    abort: AbortSignal;
+    host?: ToolHost;
+    turnTracker?: TurnTrackerContext;
+    middleware?: MiddlewareRunner;
+    turnState?: AgentTurnState;
+}
+interface RunToolBatchResult {
+    snapshot: AgentTurnStepCommitSnapshot;
+    turnState?: AgentTurnState;
+    events: Array<Extract<AgentEvent, {
+        type: "tool-result" | "tool-error";
+    }>>;
+}
+
+export { type AgentTurnActiveToolCall as A, advanceAgentTurnState as B, type CommitOutputOptions as C, type DoomLoopAction as D, createAgentTurnEngine as E, createAgentTurnState as F, failAgentTurnState as G, type PrepareModelStepOptions as P, type RunModelStepOptions as R, type StepProcessingOptions as S, type AgentTurnBoundaryMetadata as a, type AgentTurnBoundarySnapshot as b, type AgentTurnCommitApplier as c, type AgentTurnCommitBatch as d, type AgentTurnCommitOptions as e, AgentTurnEngine as f, type AgentTurnEngineOptions as g, type AgentTurnPhase as h, type AgentTurnResolvedToolCall as i, type AgentTurnState as j, type AgentTurnStateAdvanceOptions as k, type AgentTurnStepCommitSnapshot as l, type AgentTurnStepCommitToolCall as m, type AgentTurnStepCommitToolResult as n, type AgentTurnStepRuntimeConfig as o, type CommitStepOptions as p, type CreateAgentTurnStateOptions as q, type CreateAgentTurnStepCommitBatchOptions as r, type DoomLoopHandler as s, type DoomLoopRequest as t, type PreparedAgentModelStep as u, type ProcessorOptions as v, type ProcessorOutput as w, type RunToolBatchOptions as x, type RunToolBatchResult as y, type StepProcessingOutput as z };