@cuylabs/agent-core 0.8.0 → 0.10.0

package/dist/tool/index.d.ts

@@ -1,16 +1,16 @@
-import { T as Tool } from '../tool-BHbyUAy3.js';
-export { C as CompatibleSchema, I as InferSchemaOutput, d as defineTool } from '../tool-BHbyUAy3.js';
-import { a as ToolReplayPolicy, F as FileOperationMeta, N as NormalizedToolReplayPolicy, d as TurnTrackerContext } from '../tool-DLXAR9Ce.js';
-import { T as ToolHost } from '../types-CHiPh8U2.js';
-import { M as MiddlewareRunner } from '../runner-e2YRcUoX.js';
-import 'zod';
-import '../types-CQL-SvTn.js';
+import { dq as ToolReplayPolicy, F as FileOperationMeta, bN as NormalizedToolReplayPolicy, T as Tool, H as HumanInputController, a as TurnTrackerContext, b as MiddlewareRunner, A as AgentEvent, dn as ToolMetadata, dj as ToolCapabilities } from '../instance-BqV2D5pc.js';
+export { az as CompatibleSchema, bo as InferSchemaOutput, bp as InputCheckResult, dL as getRequiredToolHost, dR as resolveCapability } from '../instance-BqV2D5pc.js';
+import { T as ToolHost } from '../types-C_LCeYNg.js';
+export { D as DirEntry, E as ExecOptions, a as ExecResult, F as FileStat } from '../types-C_LCeYNg.js';
+export { ToolHostProvider, ToolHostProviderSummary, ToolHostRegistry, defaultToolHostRegistry, localHost } from './host/index.js';
 import 'ai';
-import '@ai-sdk/provider-utils';
-import '../events-CE72w8W4.js';
-import '../messages-BYWGn8TY.js';
-import '../types-BfNpU8NS.js';
+import '../types-RSCv7nQ4.js';
+import 'zod';
 import '../types-CQaXbRsS.js';
+import '../types-Bj_J8u_W.js';
+import '@ai-sdk/provider-utils';
+import '../sandbox/index.js';
+import '../llm-error-D93FNNLY.js';
 
 /**
  * Normalize a tool replay policy into explicit, infrastructure-agnostic
@@ -97,6 +97,33 @@ declare class ToolRegistry {
     hasGroup(name: string): boolean;
     /** List all group names. */
     listGroups(): string[];
+    /**
+     * Partition registered tools into eager and deferred sets.
+     *
+     * Eager tools have their full schemas sent to the LLM on turn 1.
+     * Deferred tools are held back — the model discovers them via a
+     * search mechanism when needed, saving context window space.
+     *
+     * @returns `{ eager, deferred }` arrays of tool infos.
+     */
+    partition(): {
+        eager: Tool.AnyInfo[];
+        deferred: Tool.AnyInfo[];
+    };
+    /**
+     * Search deferred tools by keyword with multi-signal weighted scoring.
+     *
+     * Scoring per term:
+     *  - Exact tool ID match: +10
+     *  - Partial tool ID match (substring): +5
+     *  - Keyword word-boundary match: +4
+     *  - Keyword substring match: +2
+     *
+     * @param query - Space-separated search terms
+     * @param maxResults - Maximum results to return (default: 5)
+     * @returns Matching deferred tools sorted by relevance (highest score first)
+     */
+    searchDeferred(query: string, maxResults?: number): Tool.AnyInfo[];
     /**
      * Resolve a `ToolSpec` to an array of tools.
      *
@@ -118,9 +145,62 @@ declare class ToolRegistry {
 /**
  * Default tool registry instance.
  * Shared across the application — register tools here for global access.
+ *
+ * **Single-process only.** In multi-agent or multi-tenant setups where
+ * agents share a process, create a dedicated `new ToolRegistry()` per
+ * agent to avoid cross-contamination of tool registrations.
  */
 declare const defaultRegistry: ToolRegistry;
 
+/**
+ * Tool Search — lets the model discover deferred tools at runtime.
+ *
+ * When an agent has many tools, sending all schemas on turn 1 wastes
+ * context window. Tools marked `deferred: true` are held back. The
+ * model calls `tool_search` to find them by keyword, and the matching
+ * schemas are added to subsequent turns.
+ *
+ * The search tool itself is always eager (never deferred).
+ */
+
+/**
+ * Options for creating a tool_search tool.
+ */
+interface ToolSearchOptions {
+    /** Registry to search. Falls back to the default registry if not provided. */
+    registry: ToolRegistry;
+    /** Maximum results per search (default: 5). */
+    maxResults?: number;
+    /**
+     * Callback invoked with the matched tools after each search.
+     *
+     * The agent setup should use this to add the discovered tools
+     * to the active tool set for subsequent model calls.
+     */
+    onMatch: (tools: Tool.AnyInfo[]) => void;
+}
+/**
+ * Create a `tool_search` tool that the model can call to discover
+ * deferred tools by keyword.
+ *
+ * @example
+ * ```typescript
+ * import { createToolSearchTool, ToolRegistry } from "@cuylabs/agent-core";
+ *
+ * const registry = new ToolRegistry();
+ * // ... register tools including deferred ones ...
+ *
+ * const activeTools = new Map<string, Tool.AnyInfo>();
+ * const search = createToolSearchTool({
+ *   registry,
+ *   onMatch: (tools) => {
+ *     for (const t of tools) activeTools.set(t.id, t);
+ *   },
+ * });
+ * ```
+ */
+declare function createToolSearchTool(options: ToolSearchOptions): Tool.Info;
+
 /**
  * Output truncation utilities for @cuylabs/agent-core
  */
@@ -128,10 +208,6 @@ declare const defaultRegistry: ToolRegistry;
 declare const MAX_LINES = 2000;
 /** Maximum bytes before truncation */
 declare const MAX_BYTES = 100000;
-/** Directory for storing truncated outputs */
-declare const TRUNCATE_DIR: string;
-/** Glob pattern for truncation directory */
-declare const TRUNCATE_GLOB: string;
 interface TruncateResult {
     /** The (possibly truncated) content */
     content: string;
@@ -141,40 +217,68 @@ interface TruncateResult {
     outputPath?: string;
 }
 /**
- * Truncate output if it exceeds limits
+ * Truncate output if it exceeds limits.
+ *
+ * When truncation occurs the full output is written to a temp file
+ * **synchronously** so the path is valid immediately.
  */
 declare function truncateOutput(output: string, options?: {
     maxLines?: number;
     maxBytes?: number;
 }): TruncateResult;
-/**
- * Format file size for display
- */
-declare function formatSize(bytes: number): string;
 
 interface ExecuteAgentToolCallOptions {
     toolName: string;
     tool: Tool.Info;
+    toolCallId?: string;
     params: unknown;
     cwd: string;
     abort: AbortSignal;
     sessionID: string;
+    turnID?: string;
     messageID: string;
     agent?: string;
     host?: ToolHost;
+    humanInputController?: HumanInputController;
     turnTracker?: TurnTrackerContext;
     middleware?: MiddlewareRunner;
+    onEvent?: (event: AgentEvent) => void | Promise<void>;
+    /**
+     * Pre-initialized tool result. When provided the executor skips
+     * `tool.init()` and uses this directly, avoiding double-init when
+     * the caller (e.g. `buildToolSet`) has already initialized the tool.
+     */
+    initialized?: Awaited<ReturnType<Tool.Info["init"]>>;
 }
 interface ExecuteAgentToolCallResult {
     output: string;
+    /** Short title for display (populated when middleware preserves it). */
+    title?: string;
+    /** Tool metadata (populated when middleware preserves it). */
+    metadata?: ToolMetadata;
+    /**
+     * Capabilities declared by the tool after initialization.
+     * Exposed so callers (e.g. tool-batch dispatch) can use them
+     * for parallelism and approval decisions without re-initializing.
+     */
+    capabilities?: ToolCapabilities;
 }
 /**
  * Execute one initialized framework tool with the same semantics used by the
  * standard AI SDK path.
  *
+ * Execution pipeline (in order):
+ *  1. Init — resolve tool description, schema, capabilities
+ *  2. Schema validation — parse params against Zod schema (handled by Tool.define wrapper)
+ *  3. Input validation — tool-specific `validate()` check (fail-fast, no side effects)
+ *  4. Middleware pre-hook — `beforeToolCall` (approval, gating, arg rewriting)
+ *  5. Baseline capture — turn tracker snapshots files before writes
+ *  6. Execute — run the tool (with potentially rewritten args from step 4)
+ *  7. Middleware post-hook — `afterToolCall` (transform output, add supplements)
+ *
  * This keeps middleware, baseline capture, and output normalization in one
  * place so resumable runtimes do not need a second tool execution stack.
  */
 declare function executeAgentToolCall(options: ExecuteAgentToolCallOptions): Promise<ExecuteAgentToolCallResult>;
 
-export { type ExecuteAgentToolCallOptions, type ExecuteAgentToolCallResult, MAX_BYTES, MAX_LINES, TRUNCATE_DIR, TRUNCATE_GLOB, Tool, ToolRegistry, type ToolSpec, type TruncateResult, defaultRegistry, executeAgentToolCall, formatSize, normalizeToolReplayPolicy, truncateOutput };
+export { type ExecuteAgentToolCallOptions, type ExecuteAgentToolCallResult, MAX_BYTES, MAX_LINES, Tool, ToolCapabilities, ToolHost, ToolRegistry, type ToolSearchOptions, type ToolSpec, type TruncateResult, createToolSearchTool, defaultRegistry, executeAgentToolCall, normalizeToolReplayPolicy, truncateOutput };

package/dist/tool/index.js

@@ -1,34 +1,41 @@
 import {
   ToolRegistry,
+  createToolSearchTool,
   defaultRegistry
-} from "../chunk-SDSBEQXG.js";
+} from "../chunk-KYLPMBHD.js";
+import {
+  ToolHostRegistry,
+  defaultToolHostRegistry,
+  localHost
+} from "../chunk-X4VN4GIJ.js";
 import {
   MAX_BYTES,
   MAX_LINES,
-  TRUNCATE_DIR,
-  TRUNCATE_GLOB,
   Tool,
-  defineTool,
-  formatSize,
   normalizeToolReplayPolicy,
   truncateOutput
-} from "../chunk-P6YF7USR.js";
+} from "../chunk-Q742PSH3.js";
 import {
   executeAgentToolCall
-} from "../chunk-7VKQ4WPB.js";
-import "../chunk-VEKUXUVF.js";
-import "../chunk-N7P4PN3O.js";
+} from "../chunk-5NVVNXPQ.js";
+import "../chunk-V4RFNEET.js";
+import {
+  getRequiredToolHost,
+  resolveCapability
+} from "../chunk-FII65CN7.js";
 export {
   MAX_BYTES,
   MAX_LINES,
-  TRUNCATE_DIR,
-  TRUNCATE_GLOB,
   Tool,
+  ToolHostRegistry,
   ToolRegistry,
+  createToolSearchTool,
   defaultRegistry,
-  defineTool,
+  defaultToolHostRegistry,
   executeAgentToolCall,
-  formatSize,
+  getRequiredToolHost,
+  localHost,
   normalizeToolReplayPolicy,
+  resolveCapability,
   truncateOutput
 };

package/dist/{types-VQgymC1N.d.ts → types-Bj_J8u_W.d.ts}

@@ -21,35 +21,67 @@ interface StdioTransportConfig {
     cwd?: string;
 }
 /**
- * HTTP transport configuration for remote MCP servers.
+ * HTTP/SSE transport configuration for remote MCP servers.
+ *
+ * Supports all options from the AI SDK's `MCPTransportConfig` so that
+ * agents can leverage OAuth, custom fetch, and redirect control.
  */
-interface HttpTransportConfig {
-    transport: "http";
+interface RemoteTransportConfig {
+    transport: "http" | "sse";
     /** Server URL */
     url: string;
     /** HTTP headers (e.g. Authorization) */
     headers?: Record<string, string>;
+    /**
+     * OAuth client provider for authenticated MCP servers.
+     * Pass an `OAuthClientProvider` from `@ai-sdk/mcp` when the server
+     * requires OAuth authentication.
+     */
+    authProvider?: any;
+    /**
+     * How HTTP redirects are handled.
+     * - `'follow'` — follow automatically
+     * - `'error'` — reject redirects
+     * @default 'error'
+     */
+    redirect?: "follow" | "error";
+    /**
+     * Custom fetch implementation (useful for runtimes with
+     * request-scoped fetch or test doubles).
+     */
+    fetch?: any;
 }
 /**
- * SSE transport configuration for remote MCP servers.
+ * @deprecated Use `RemoteTransportConfig` with `transport: "http"`.
+ */
+type HttpTransportConfig = RemoteTransportConfig & {
+    transport: "http";
+};
+/**
+ * @deprecated Use `RemoteTransportConfig` with `transport: "sse"`.
  */
-interface SseTransportConfig {
+type SseTransportConfig = RemoteTransportConfig & {
     transport: "sse";
-    /** Server URL */
-    url: string;
-    /** HTTP headers (e.g. Authorization) */
-    headers?: Record<string, string>;
-}
+};
 /**
  * MCP server configuration.
  */
-type MCPServerConfig = (StdioTransportConfig | HttpTransportConfig | SseTransportConfig) & {
+type MCPServerConfig = (StdioTransportConfig | RemoteTransportConfig) & {
     /** Whether this server is enabled (default: true) */
     enabled?: boolean;
     /** Connection timeout in ms (default: 30000) */
     timeout?: number;
     /** Human-readable name for the server */
     name?: string;
+    /**
+     * Client capabilities to advertise during MCP initialization.
+     * Enables features like elicitation when the server supports them.
+     */
+    capabilities?: Record<string, unknown>;
+    /**
+     * Callback for uncaught transport errors.
+     */
+    onUncaughtError?: (error: unknown) => void;
 };
 /**
  * MCP manager configuration - map of server name to config.
@@ -71,29 +103,6 @@ type MCPServerStatus = {
 } | {
     status: "disabled";
 };
-/**
- * MCP resource descriptor.
- */
-interface MCPResource {
-    uri: string;
-    name: string;
-    description?: string;
-    mimeType?: string;
-    server: string;
-}
-/**
- * MCP prompt descriptor.
- */
-interface MCPPrompt {
-    name: string;
-    description?: string;
-    arguments?: Array<{
-        name: string;
-        description?: string;
-        required?: boolean;
-    }>;
-    server: string;
-}
 /**
  * MCP manager - handles connections to multiple MCP servers.
  */
@@ -114,35 +123,6 @@ interface MCPManager {
      * Get status of all servers.
      */
     getAllStatus(): Map<string, MCPServerStatus>;
-    /**
-     * List available resources from all connected servers.
-     */
-    listResources(): Promise<MCPResource[]>;
-    /**
-     * Read a resource by URI.
-     */
-    readResource(uri: string): Promise<{
-        contents: Array<{
-            uri: string;
-            text?: string;
-            blob?: string;
-            mimeType?: string;
-        }>;
-    }>;
-    /**
-     * List available prompts from all connected servers.
-     */
-    listPrompts(): Promise<MCPPrompt[]>;
-    /**
-     * Get a prompt with optional arguments.
-     */
-    getPrompt(serverName: string, promptName: string, args?: Record<string, unknown>): Promise<{
-        description?: string;
-        messages: Array<{
-            role: string;
-            content: unknown;
-        }>;
-    }>;
     /**
      * Close all connections.
      */
@@ -153,4 +133,4 @@ interface MCPManager {
     isConnected(): boolean;
 }
 
-export type { HttpTransportConfig as H, MCPConfig as M, SseTransportConfig as S, MCPManager as a, MCPPrompt as b, MCPResource as c, MCPServerConfig as d, MCPServerStatus as e, StdioTransportConfig as f };
+export type { HttpTransportConfig as H, MCPConfig as M, RemoteTransportConfig as R, SseTransportConfig as S, MCPManager as a, MCPServerConfig as b, MCPServerStatus as c, StdioTransportConfig as d };

package/dist/{types-CHiPh8U2.d.ts → types-C_LCeYNg.d.ts}

@@ -1,8 +1,8 @@
 /**
  * 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:
+ * A ToolHost defines *where* tools execute: local machine, container,
+ * remote workspace, etc. Every host provides two surfaces:
  *
  * 1. **File system** — read, write, stat, list, check existence
  * 2. **Process execution** — spawn commands, kill processes
@@ -15,8 +15,8 @@
  * // Default: runs everything locally
  * const agent = createAgent({ host: localHost() });
  *
- * // Future: run tools inside a Docker container
- * const agent = createAgent({ host: dockerHost("my-container") });
+ * // Swap in a custom host package when needed
+ * const agent = createAgent({ host: workspaceHost() });
  * ```
  */
 /** Options for spawning a process. */
@@ -69,10 +69,10 @@ interface DirEntry {
  * 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.
+ * whether running locally, in a container, over SSH, or in any other environment.
  */
 interface ToolHost {
-    /** Human-readable host identifier (e.g. "local", "docker:my-container"). */
+    /** Human-readable host identifier (e.g. "local", "container:workspace"). */
     readonly name: string;
     /** Read a file as a UTF-8 string. Throws if the file doesn't exist. */
     readFile(path: string): Promise<string>;
@@ -92,7 +92,7 @@ interface ToolHost {
      * 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).
+     * `$SHELL`, a container host uses its runtime entrypoint, an SSH host uses a remote shell).
      */
     exec(command: string, options?: ExecOptions): Promise<ExecResult>;
 }

package/dist/types-RSCv7nQ4.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Logger type definitions for @cuylabs/agent-core.
+ *
+ * The logger is intentionally minimal — four levels, optional structured
+ * metadata, and a child-logger factory for namespace scoping.
+ *
+ * By default agents use a silent (no-op) logger. Consumers opt into
+ * output by supplying a concrete logger via `createAgent({ logger })`.
+ */
+/** Structured metadata bag attached to log entries. */
+type LogMeta = Record<string, unknown>;
+/** Log severity levels, lowest to highest. */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Core logger contract.
+ *
+ * Every internal module that needs to log accepts a `Logger` instance.
+ * The interface is intentionally compatible with `RuntimeLogger` from
+ * `@cuylabs/agent-runtime` so the same object can serve both roles.
+ */
+interface Logger {
+    debug(message: string, meta?: LogMeta): void;
+    info(message: string, meta?: LogMeta): void;
+    warn(message: string, meta?: LogMeta): void;
+    error(message: string, meta?: LogMeta): void;
+    /**
+     * Create a child logger that prepends a namespace prefix.
+     *
+     * ```ts
+     * const child = logger.child("mcp");
+     * child.warn("timeout"); // → "[mcp] timeout"
+     * ```
+     *
+     * Implementations that don't support children can return `this`.
+     */
+    child(namespace: string): Logger;
+}
+/**
+ * Options accepted by the built-in console logger factory.
+ */
+interface ConsoleLoggerOptions {
+    /** Minimum level to emit. Messages below this are discarded. Default: `"warn"`. */
+    level?: LogLevel;
+    /** Prefix prepended to every line. Default: `"agent-core"`. */
+    prefix?: string;
+}
+/**
+ * Options for the file-backed logger factory.
+ */
+interface FileLoggerOptions {
+    /** Absolute path to the log file. Created (with parents) if it doesn't exist. */
+    filePath: string;
+    /** Minimum level to emit. Default: `"debug"`. */
+    level?: LogLevel;
+    /** Prefix prepended to every line. Default: `"agent-core"`. */
+    prefix?: string;
+}
+
+export type { ConsoleLoggerOptions as C, FileLoggerOptions as F, Logger as L, LogLevel as a, LogMeta as b };