@cuylabs/agent-core 0.7.0 → 0.8.0

package/dist/{registry-BDLIHOQB.d.ts → registry-DwYqsQkX.d.ts}

@@ -1,4 +1,4 @@
-import { S as SkillDiscoveryResult, a as SkillMetadata, b as SkillContent, c as SkillResource, d as SkillConfig } from './tool-Db1Ue-1U.js';
+import { S as SkillDiscoveryResult, a as SkillMetadata, b as SkillContent, c as SkillResource, d as SkillConfig } from './types-BfNpU8NS.js';
 
 /**
  * Skill Registry — in-memory store for discovered skills

package/dist/{runner-DSKaEz3z.d.ts → runner-e2YRcUoX.d.ts}

@@ -1,10 +1,11 @@
-import * as ai from 'ai';
 import { LanguageModel, ModelMessage, TelemetrySettings, SystemModelMessage } from 'ai';
 import { ProviderOptions } from '@ai-sdk/provider-utils';
-import { T as TokenUsage, M as Message } from './messages-BYWGn8TY.js';
-import { d as SkillConfig, T as Tool } from './tool-Db1Ue-1U.js';
-import { b as ScopeSnapshot } from './types-9jGQUjqW.js';
-import { b as ToolContext } from './tool-HUtkiVBx.js';
+import { A as AgentEvent } from './events-CE72w8W4.js';
+import { d as SkillConfig } from './types-BfNpU8NS.js';
+import { T as TokenUsage } from './messages-BYWGn8TY.js';
+import { S as ScopeSnapshot } from './types-CQL-SvTn.js';
+import { b as ToolContext } from './tool-DLXAR9Ce.js';
+import { T as Tool } from './tool-BHbyUAy3.js';
 import { R as ReasoningLevel } from './types-CQaXbRsS.js';
 
 /**
@@ -173,151 +174,6 @@ interface EnhancedTools extends Array<unknown> {
     __customStreamModels?: string[];
 }
 
-/** Agent status for UI display */
-type AgentStatus = "idle" | "processing" | "thinking" | "reasoning" | "calling-tool" | "waiting-approval" | "error";
-/** Approval request for UI */
-interface ApprovalEvent {
-    id: string;
-    tool: string;
-    args: unknown;
-    description: string;
-    risk: "safe" | "moderate" | "dangerous";
-}
-/** Neutral turn-commit boundaries for runtime/durability integrations */
-type AgentTurnBoundaryKind = "input-commit-start" | "input-commit-finish" | "intervention-commit-start" | "intervention-commit-finish" | "step-commit-start" | "step-commit-finish" | "output-commit-start" | "output-commit-finish";
-/**
- * Events emitted during agent execution
- *
- * These events are designed for UI consumption:
- * - status: Overall agent state for status indicators
- * - approval-request: User confirmation needed
- * - progress: Step counts for progress bars
- */
-type AgentEvent = {
-    type: "status";
-    status: AgentStatus;
-} | {
-    type: "approval-request";
-    request: ApprovalEvent;
-} | {
-    type: "approval-resolved";
-    id: string;
-    action: "allow" | "deny" | "remember";
-} | {
-    type: "step-start";
-    step: number;
-    maxSteps: number;
-} | {
-    type: "step-finish";
-    step: number;
-    usage?: TokenUsage;
-    finishReason?: string;
-} | {
-    type: "turn-boundary";
-    boundary: AgentTurnBoundaryKind;
-    step?: number;
-    messageRole?: Message["role"];
-    pendingToolCallCount?: number;
-} | {
-    type: "message";
-    message: Message;
-} | {
-    type: "text-start";
-} | {
-    type: "text-delta";
-    text: string;
-} | {
-    type: "text-end";
-} | {
-    type: "reasoning-start";
-    id: string;
-} | {
-    type: "reasoning-delta";
-    id: string;
-    text: string;
-} | {
-    type: "reasoning-end";
-    id: string;
-} | {
-    type: "tool-start";
-    toolName: string;
-    toolCallId: string;
-    input: unknown;
-} | {
-    type: "tool-result";
-    toolName: string;
-    toolCallId: string;
-    result: unknown;
-} | {
-    type: "tool-error";
-    toolName: string;
-    toolCallId: string;
-    error: string;
-} | {
-    type: "computer-call";
-    callId: string;
-    action: unknown;
-    pendingSafetyChecks?: unknown[];
-} | {
-    type: "computer-result";
-    callId: string;
-    result: unknown;
-} | {
-    type: "intervention-applied";
-    id: string;
-    message: string;
-} | {
-    type: "doom-loop";
-    toolName: string;
-    repeatCount: number;
-} | {
-    type: "context-overflow";
-    inputTokens: number;
-    limit: number;
-} | {
-    type: "turn-summary";
-    turnId: string;
-    files: Array<{
-        path: string;
-        type: "created" | "modified" | "deleted" | "unchanged";
-        additions: number;
-        deletions: number;
-    }>;
-    additions: number;
-    deletions: number;
-} | {
-    type: "retry";
-    attempt: number;
-    delayMs: number;
-    error: Error;
-} | {
-    type: "error";
-    error: Error;
-} | {
-    type: "complete";
-    usage?: TokenUsage;
-    output?: string;
-};
-/**
- * Step-processing result - what happens after reducing one streamed step
- */
-type StepProcessingResult = "continue" | "stop" | "compact";
-/**
- * @deprecated Use `StepProcessingResult`.
- */
-type ProcessorResult = StepProcessingResult;
-/**
- * Stream input for model inference
- */
-interface StreamInput {
-    sessionID: string;
-    model: ai.LanguageModel;
-    system: string[];
-    messages: ai.ModelMessage[];
-    abort: AbortSignal;
-    tools: Record<string, unknown>;
-}
-
 /**
  * Prompt Pipeline Types
  *
@@ -791,6 +647,57 @@ interface AgentMiddleware {
      */
     getOtelContext?(sessionId: string): unknown;
 }
+/**
+ * A user-facing command a plugin can register.
+ *
+ * How commands surface depends on the host:
+ *   - CLI/TUI → slash commands (e.g. `/deploy`)
+ *   - HTTP     → could be API routes
+ *   - Chatbot  → chat commands
+ *
+ * Hosts that don't support commands can silently ignore them.
+ */
+interface PluginCommand {
+    /** Command name (without leading slash) */
+    name: string;
+    /** Optional aliases */
+    alias?: string[];
+    /** One-line description shown in help */
+    summary: string;
+    /** Execute the command. Return the text to display, or null for silent. */
+    execute: (args: string) => Promise<string | null>;
+}
+/**
+ * The context object passed to a plugin's default export.
+ *
+ * Through the context, plugins contribute tools, middleware, and
+ * (optionally) host-specific commands.
+ *
+ * @example
+ * ```ts
+ * import { Tool, z, type PluginContext } from "@cuylabs/agent-code";
+ *
+ * export default function (ctx: PluginContext) {
+ *   ctx.addTool(Tool.define("ping", {
+ *     description: "Pong!",
+ *     parameters: z.object({}),
+ *     execute: async () => ({ title: "pong", output: "pong", metadata: {} }),
+ *   }));
+ * }
+ * ```
+ */
+interface PluginContext {
+    /** Working directory of the agent (project root) */
+    cwd: string;
+    /** Register a tool the LLM can call */
+    addTool(tool: Tool.AnyInfo): void;
+    /** Register middleware (model hooks, tool guards, prompt sections) */
+    addMiddleware(mw: AgentMiddleware): void;
+    /** Register a user-facing command (host-dependent) */
+    addCommand(cmd: PluginCommand): void;
+}
+/** The function shape a plugin file must default-export. */
+type PluginInit = (ctx: PluginContext) => void | Promise<void>;
 
 /**
  * Middleware Runner
@@ -876,4 +783,4 @@ declare class MiddlewareRunner {
     }): Promise<void>;
 }
 
-export { type AgentEvent as A, type BlockedModelCall as B, type EnhancedTools as E, type InstructionFile as I, MiddlewareRunner as M, type PromptConfig as P, type StreamChunk as S, type ToolCallDecision as T, type PromptBuildContext as a, type PromptSection as b, type ModelFamily as c, type StreamProvider as d, type ModelCallInput as e, type StepProcessingResult as f, type AgentTurnBoundaryKind as g, type AgentMiddleware as h, type AgentModelHooks as i, type AgentStatus as j, type ApprovalEvent as k, type EnvironmentInfo as l, type ModelCallContext as m, type ModelCallOutput as n, type ProcessorResult as o, type StreamInput as p, type StreamProviderConfig as q, type StreamProviderFactory as r, type StreamProviderInput as s, type StreamProviderResult as t };
+export { type AgentMiddleware as A, type BlockedModelCall as B, type EnhancedTools as E, type InstructionFile as I, MiddlewareRunner as M, type PromptConfig as P, type StreamChunk as S, type ToolCallDecision as T, type PromptBuildContext as a, type PromptSection as b, type ModelFamily as c, type StreamProvider as d, type ModelCallInput as e, type AgentModelHooks as f, type EnvironmentInfo as g, type ModelCallContext as h, type ModelCallOutput as i, type PluginCommand as j, type PluginContext as k, type PluginInit as l, type StreamProviderConfig as m, type StreamProviderFactory as n, type StreamProviderInput as o, type StreamProviderResult as p };

package/dist/runtime/index.d.ts

@@ -1,16 +1,19 @@
-import { A as AgentEvent } from '../runner-DSKaEz3z.js';
+import { A as AgentEvent } from '../events-CE72w8W4.js';
 import { T as TokenUsage, M as Message } from '../messages-BYWGn8TY.js';
-import { b as ScopeSnapshot } from '../types-9jGQUjqW.js';
-import { S as StepProcessingOptions, z as StepProcessingOutput, l as AgentTurnStepCommitSnapshot, r as CreateAgentTurnStepCommitBatchOptions, d as AgentTurnCommitBatch, P as PrepareModelStepOptions, u as PreparedAgentModelStep, R as RunModelStepOptions, x as RunToolBatchOptions, y as RunToolBatchResult, C as CommitOutputOptions, p as CommitStepOptions, j as AgentTurnState, n as AgentTurnStepCommitToolResult, m as AgentTurnStepCommitToolCall } from '../types-CqDZTh4d.js';
-export { A as AgentTurnActiveToolCall, a as AgentTurnBoundaryMetadata, b as AgentTurnBoundarySnapshot, c as AgentTurnCommitApplier, e as AgentTurnCommitOptions, f as AgentTurnEngine, g as AgentTurnEngineOptions, h as AgentTurnPhase, i as AgentTurnResolvedToolCall, k as AgentTurnStateAdvanceOptions, o as AgentTurnStepRuntimeConfig, q as CreateAgentTurnStateOptions, v as ProcessorOptions, w as ProcessorOutput, B as advanceAgentTurnState, E as createAgentTurnEngine, F as createAgentTurnState, G as failAgentTurnState } from '../types-CqDZTh4d.js';
-import { A as AnyInferenceResult } from '../types-FRpzzg_9.js';
+import { S as ScopeSnapshot } from '../types-CQL-SvTn.js';
+import { S as StepProcessingOptions, z as StepProcessingOutput, l as AgentTurnStepCommitSnapshot, r as CreateAgentTurnStepCommitBatchOptions, d as AgentTurnCommitBatch, P as PrepareModelStepOptions, u as PreparedAgentModelStep, R as RunModelStepOptions, x as RunToolBatchOptions, y as RunToolBatchResult, C as CommitOutputOptions, p as CommitStepOptions, j as AgentTurnState, n as AgentTurnStepCommitToolResult, m as AgentTurnStepCommitToolCall } from '../types-QKHHQLLq.js';
+export { A as AgentTurnActiveToolCall, a as AgentTurnBoundaryMetadata, b as AgentTurnBoundarySnapshot, c as AgentTurnCommitApplier, e as AgentTurnCommitOptions, f as AgentTurnEngine, g as AgentTurnEngineOptions, h as AgentTurnPhase, i as AgentTurnResolvedToolCall, k as AgentTurnStateAdvanceOptions, o as AgentTurnStepRuntimeConfig, q as CreateAgentTurnStateOptions, v as ProcessorOptions, w as ProcessorOutput, B as advanceAgentTurnState, E as createAgentTurnEngine, F as createAgentTurnState, G as failAgentTurnState } from '../types-QKHHQLLq.js';
+import { A as AnyInferenceResult } from '../types-KKDrdU9Y.js';
 import { ModelMessage } from 'ai';
-import '@ai-sdk/provider-utils';
-import '../tool-Db1Ue-1U.js';
+import '../tool-BHbyUAy3.js';
 import 'zod';
-import '../tool-HUtkiVBx.js';
+import '../tool-DLXAR9Ce.js';
 import '../types-CHiPh8U2.js';
+import '../runner-e2YRcUoX.js';
+import '@ai-sdk/provider-utils';
+import '../types-BfNpU8NS.js';
 import '../types-CQaXbRsS.js';
+import '../llm-error-D93FNNLY.js';
 
 /**
  * Doom loop error thrown when repeated tool calls are detected.

package/dist/runtime/index.js

@@ -30,14 +30,16 @@ import {
   runToolBatch,
   snapshotAgentWorkflowMessage,
   snapshotAgentWorkflowMessages
-} from "../chunk-3HNO5SVI.js";
-import "../chunk-BNSHUWCV.js";
-import "../chunk-5K7AQVOU.js";
-import "../chunk-ZPMACVZK.js";
-import "../chunk-IEFIQENH.js";
-import "../chunk-N7P4PN3O.js";
+} from "../chunk-4BDA7DQY.js";
+import "../chunk-WWYYNWEW.js";
+import "../chunk-N6HWIEEA.js";
+import "../chunk-7VKQ4WPB.js";
 import "../chunk-VEKUXUVF.js";
-import "../chunk-QGOGIP7T.js";
+import "../chunk-SQU2AJHO.js";
+import "../chunk-N7P4PN3O.js";
+import "../chunk-RZITT45F.js";
+import "../chunk-RFEKJKTO.js";
+import "../chunk-DWYX7ASF.js";
 export {
   AgentTurnEngine,
   ContextOverflowError,

package/dist/safety/index.d.ts

@@ -0,0 +1,38 @@
+import { R as RiskLevel, a as ApprovalConfig, c as ApprovalRule } from '../types-CWm-7rvB.js';
+export { A as ApprovalAction, b as ApprovalRequest } from '../types-CWm-7rvB.js';
+
+/**
+ * Get the risk level for a tool.
+ */
+declare function getToolRisk(tool: string, customRisks?: Record<string, RiskLevel>): RiskLevel;
+
+/**
+ * Thrown when a user or rule denies an operation.
+ */
+declare class ApprovalDeniedError extends Error {
+    readonly tool: string;
+    readonly args: unknown;
+    constructor(tool: string, args: unknown, message?: string);
+}
+/**
+ * Thrown when an approval request times out.
+ */
+declare class ApprovalTimeoutError extends Error {
+    readonly tool: string;
+    readonly timeoutMs: number;
+    constructor(tool: string, timeoutMs: number);
+}
+
+/**
+ * Creates an approval handler for managing tool execution permissions.
+ */
+declare function createApprovalHandler(config?: ApprovalConfig): {
+    request: (sessionId: string, tool: string, args: unknown, customRisks?: Record<string, RiskLevel>) => Promise<void>;
+    cancelAll: (reason?: string) => void;
+    addRule: (rule: ApprovalRule) => void;
+    getRules: () => readonly ApprovalRule[];
+    clearSessionRules: () => void;
+};
+type ApprovalHandler = ReturnType<typeof createApprovalHandler>;
+
+export { ApprovalConfig, ApprovalDeniedError, type ApprovalHandler, ApprovalRule, ApprovalTimeoutError, RiskLevel, createApprovalHandler, getToolRisk };

package/dist/safety/index.js

@@ -0,0 +1,12 @@
+import {
+  ApprovalDeniedError,
+  ApprovalTimeoutError,
+  createApprovalHandler,
+  getToolRisk
+} from "../chunk-BFM2YHNM.js";
+export {
+  ApprovalDeniedError,
+  ApprovalTimeoutError,
+  createApprovalHandler,
+  getToolRisk
+};

package/dist/scope/index.d.ts

@@ -1,5 +1,5 @@
-import { S as ScopeOptions, a as Scope, b as ScopeSnapshot } from '../types-9jGQUjqW.js';
-export { c as ScopeAttributeValue, d as ScopeAttributes, e as ScopeKind } from '../types-9jGQUjqW.js';
+import { e as ScopeOptions, a as Scope, S as ScopeSnapshot } from '../types-CQL-SvTn.js';
+export { b as ScopeAttributeValue, c as ScopeAttributes, d as ScopeKind } from '../types-CQL-SvTn.js';
 
 declare function currentScope(): Scope | undefined;
 declare function snapshotScope(scope?: Scope | undefined): ScopeSnapshot | undefined;

package/dist/signal/index.d.ts

@@ -0,0 +1,28 @@
+import { A as AgentSignal, T as TypedHandler, U as Unsubscribe, W as WildcardHandler } from '../types-YuWV4ag7.js';
+export { E as EventOf } from '../types-YuWV4ag7.js';
+import { A as AgentEvent } from '../events-CE72w8W4.js';
+import 'ai';
+import '../messages-BYWGn8TY.js';
+
+/**
+ * LocalSignal — in-process event dispatch.
+ *
+ * Dispatches events synchronously via direct function calls.
+ * Zero dependencies, zero serialization, zero network.
+ *
+ * Handler errors are caught silently — a broken listener must never
+ * interrupt the agent's streaming pipeline.
+ */
+
+declare class LocalSignal implements AgentSignal {
+    /** type → Set<handler> for typed subscriptions */
+    private readonly typed;
+    /** handlers that receive every event */
+    private readonly wildcard;
+    on<T extends AgentEvent["type"]>(type: T, handler: TypedHandler<T>): Unsubscribe;
+    onAny(handler: WildcardHandler): Unsubscribe;
+    emit(event: AgentEvent): void;
+    clear(): void;
+}
+
+export { AgentSignal, LocalSignal, TypedHandler, Unsubscribe, WildcardHandler };

package/dist/signal/index.js

@@ -0,0 +1,6 @@
+import {
+  LocalSignal
+} from "../chunk-KUVSERLJ.js";
+export {
+  LocalSignal
+};

package/dist/skill/index.d.ts

@@ -1,11 +1,12 @@
-import { h as SkillScope, i as SkillSource, a as SkillMetadata, g as SkillResourceType, c as SkillResource, b as SkillContent, d as SkillConfig, S as SkillDiscoveryResult, T as Tool } from '../tool-Db1Ue-1U.js';
-export { R as RemoteSkillEntry, e as RemoteSkillIndex, f as SkillDiscoveryError, j as SkillSourceType } from '../tool-Db1Ue-1U.js';
-import { S as SkillRegistry } from '../registry-BDLIHOQB.js';
-export { c as createSkillRegistry, e as emptySkillRegistry } from '../registry-BDLIHOQB.js';
+import { h as SkillScope, i as SkillSource, a as SkillMetadata, g as SkillResourceType, c as SkillResource, b as SkillContent, d as SkillConfig, S as SkillDiscoveryResult } from '../types-BfNpU8NS.js';
+export { R as RemoteSkillEntry, e as RemoteSkillIndex, f as SkillDiscoveryError, j as SkillSourceType } from '../types-BfNpU8NS.js';
+import { S as SkillRegistry } from '../registry-DwYqsQkX.js';
+export { c as createSkillRegistry, e as emptySkillRegistry } from '../registry-DwYqsQkX.js';
+import { T as Tool } from '../tool-BHbyUAy3.js';
 import 'zod';
-import '../tool-HUtkiVBx.js';
+import '../tool-DLXAR9Ce.js';
 import '../types-CHiPh8U2.js';
-import '../types-9jGQUjqW.js';
+import '../types-CQL-SvTn.js';
 
 declare const SKILL_FILENAME = "SKILL.md";
 declare const DEFAULT_SKILL_MAX_SIZE = 102400;

package/dist/sub-agent/index.d.ts

@@ -1,18 +1,23 @@
-export { c as AgentProfile, D as DEFAULT_MAX_CONCURRENT, d as DEFAULT_MAX_SPAWN_DEPTH, e as DEFAULT_SESSION_TITLE_PREFIX, S as SubAgentCompletedResult, g as SubAgentHandle, h as SubAgentStatus, i as SubAgentToolConfig, j as SubAgentTracker, k as SubAgentUsage, m as createSubAgentTools } from '../index-C33hlD6H.js';
+export { b as AgentProfile, D as DEFAULT_MAX_CONCURRENT, c as DEFAULT_MAX_SPAWN_DEPTH, d as DEFAULT_SESSION_TITLE_PREFIX, S as SubAgentCompletedResult, e as SubAgentHandle, f as SubAgentStatus, g as SubAgentToolConfig, h as SubAgentTracker, i as SubAgentUsage, k as createSubAgentTools } from '../index-CWSchSql.js';
 import 'ai';
+import '../types-BnpEOYV-.js';
 import '../types-CQaXbRsS.js';
-import '../tool-Db1Ue-1U.js';
+import '../tool-BHbyUAy3.js';
 import 'zod';
-import '../tool-HUtkiVBx.js';
+import '../tool-DLXAR9Ce.js';
 import '../types-CHiPh8U2.js';
-import '../types-9jGQUjqW.js';
-import '../runner-DSKaEz3z.js';
+import '../types-CQL-SvTn.js';
+import '../runner-e2YRcUoX.js';
 import '@ai-sdk/provider-utils';
+import '../events-CE72w8W4.js';
 import '../messages-BYWGn8TY.js';
+import '../types-BfNpU8NS.js';
 import '../session-manager-B_CWGTsl.js';
 import '../types-VQgymC1N.js';
+import '../types-YuWV4ag7.js';
 import '../tracker-DClqYqTj.js';
-import '../builder-BRvqCcIk.js';
-import '../registry-BDLIHOQB.js';
-import '../types-FRpzzg_9.js';
-import '../types-CqDZTh4d.js';
+import '../builder-UpOWQMW3.js';
+import '../registry-DwYqsQkX.js';
+import '../types-KKDrdU9Y.js';
+import '../llm-error-D93FNNLY.js';
+import '../types-QKHHQLLq.js';

package/dist/tool/index.d.ts

@@ -1,13 +1,15 @@
-import { T as Tool } from '../tool-Db1Ue-1U.js';
-export { C as CompatibleSchema, I as InferSchemaOutput, k as defineTool } from '../tool-Db1Ue-1U.js';
-import { a as ToolReplayPolicy, F as FileOperationMeta, N as NormalizedToolReplayPolicy, d as TurnTrackerContext } from '../tool-HUtkiVBx.js';
+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-DSKaEz3z.js';
+import { M as MiddlewareRunner } from '../runner-e2YRcUoX.js';
 import 'zod';
-import '../types-9jGQUjqW.js';
+import '../types-CQL-SvTn.js';
 import 'ai';
 import '@ai-sdk/provider-utils';
+import '../events-CE72w8W4.js';
 import '../messages-BYWGn8TY.js';
+import '../types-BfNpU8NS.js';
 import '../types-CQaXbRsS.js';
 
 /**

package/dist/tool/index.js

@@ -15,9 +15,9 @@ import {
 } from "../chunk-P6YF7USR.js";
 import {
   executeAgentToolCall
-} from "../chunk-IEFIQENH.js";
-import "../chunk-N7P4PN3O.js";
+} from "../chunk-7VKQ4WPB.js";
 import "../chunk-VEKUXUVF.js";
+import "../chunk-N7P4PN3O.js";
 export {
   MAX_BYTES,
   MAX_LINES,

package/dist/tool-BHbyUAy3.d.ts

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+import { T as ToolMetadata, a as ToolReplayPolicy, b as ToolContext, F as FileOperationMeta, c as ToolResult } from './tool-DLXAR9Ce.js';
+
+/**
+ * Tool definition namespace for @cuylabs/agent-core
+ *
+ * Provides consistent tool creation via Tool.define.
+ */
+
+/**
+ * A schema type compatible with both Zod 3 and Zod 4.
+ *
+ * Uses structural typing so that schemas from either Zod version satisfy
+ * the constraint. This avoids the problem where Zod 3's `ZodType` class
+ * and Zod 4's `ZodType` class have incompatible internal shapes, causing
+ * type errors when a library compiled against one version is consumed with
+ * the other.
+ *
+ * Both Zod 3 and Zod 4 (classic API) schemas have `parse()` and `_output`.
+ */
+interface CompatibleSchema<T = any> {
+    /** Parse and validate input data. Present in both Zod 3 and Zod 4. */
+    parse(data: unknown): T;
+    /**
+     * Type-level output marker used by both Zod versions:
+     * - Zod 3: `readonly _output!: T` (definite assignment assertion)
+     * - Zod 4 classic: `get _output(): T` (getter)
+     */
+    readonly _output: T;
+}
+/**
+ * Infer the output type from a compatible schema.
+ * Equivalent to `z.infer<T>` but works with both Zod 3 and Zod 4 schemas.
+ */
+type InferSchemaOutput<T extends CompatibleSchema> = T["_output"];
+/**
+ * Tool namespace - tool definition utilities
+ */
+declare namespace Tool {
+    /**
+     * Tool info interface - the shape of a defined tool
+     */
+    interface Info<TParams extends CompatibleSchema = any, TMeta extends ToolMetadata = ToolMetadata> {
+        /** Unique tool identifier */
+        id: string;
+        /** Recovery semantics for resume-capable runtimes. */
+        replayPolicy?: ToolReplayPolicy;
+        /** Initialize the tool (can be async for dynamic descriptions) */
+        init: (ctx?: InitContext) => Promise<InitResult<TParams, TMeta>> | InitResult<TParams, TMeta>;
+    }
+    /**
+     * Any tool info - for use in arrays and collections where generic types vary
+     */
+    type AnyInfo = Info<any, any>;
+    /**
+     * Context passed during tool initialization
+     */
+    interface InitContext {
+        /** Working directory */
+        cwd?: string;
+        /** Agent name (if known) */
+        agent?: string;
+    }
+    /**
+     * Result of tool initialization
+     */
+    interface InitResult<TParams extends CompatibleSchema = any, TMeta extends ToolMetadata = ToolMetadata> {
+        /** Tool description for the LLM */
+        description: string;
+        /** Zod schema for parameters */
+        parameters: TParams;
+        /** Execute the tool */
+        execute: (params: InferSchemaOutput<TParams>, ctx: ToolContext) => Promise<ExecuteResult<TMeta>>;
+        /** Optional custom validation error formatter */
+        formatValidationError?: (error: z.ZodError) => string;
+        /**
+         * File operation metadata for automatic turn tracking.
+         * When set, the agent will automatically capture file baselines
+         * before tool execution for undo/diff capabilities.
+         *
+         * @example
+         * ```typescript
+         * // For a write tool
+         * fileOps: {
+         *   pathArgs: ['path'],
+         *   operationType: 'write'
+         * }
+         * ```
+         */
+        fileOps?: FileOperationMeta;
+        /** Optional replay metadata for resume-capable runtimes. */
+        replayPolicy?: ToolReplayPolicy;
+    }
+    /**
+     * Result of tool execution
+     */
+    interface ExecuteResult<TMeta extends ToolMetadata = ToolMetadata> {
+        /** Short title for display */
+        title: string;
+        /** Main output text */
+        output: string;
+        /** Metadata */
+        metadata: TMeta;
+    }
+    interface DefineOptions {
+        /** Static replay metadata exposed to higher-level runtimes. */
+        replayPolicy?: ToolReplayPolicy;
+    }
+    /**
+     * Define a tool with standard patterns
+     *
+     * @example
+     * ```typescript
+     * const myTool = Tool.define("my_tool", {
+     *   description: "Does something useful",
+     *   parameters: z.object({
+     *     input: z.string().describe("The input to process"),
+     *   }),
+     *   execute: async (params, ctx) => ({
+     *     title: "Processed",
+     *     output: `Result: ${params.input}`,
+     *     metadata: {},
+     *   }),
+     * });
+     * ```
+     */
+    function define<TParams extends CompatibleSchema, TMeta extends ToolMetadata = ToolMetadata>(id: string, init: Info<TParams, TMeta>["init"] | Awaited<ReturnType<Info<TParams, TMeta>["init"]>>, options?: DefineOptions): Info<TParams, TMeta>;
+    /**
+     * Simple define for static tools (no async init)
+     */
+    function defineSimple<TParams extends CompatibleSchema, TMeta extends ToolMetadata = ToolMetadata>(id: string, config: {
+        description: string;
+        parameters: TParams;
+        execute: (params: InferSchemaOutput<TParams>, ctx: ToolContext) => Promise<ExecuteResult<TMeta>>;
+        replayPolicy?: ToolReplayPolicy;
+    }): Info<TParams, TMeta>;
+}
+/**
+ * Legacy helper - wraps to Tool.Info format
+ *
+ * @deprecated Use Tool.define instead
+ */
+declare function defineTool<TParams extends CompatibleSchema>(definition: {
+    id: string;
+    description: string;
+    parameters: TParams;
+    execute: (params: InferSchemaOutput<TParams>, ctx: ToolContext) => Promise<ToolResult>;
+}): Tool.Info<TParams>;
+
+export { type CompatibleSchema as C, type InferSchemaOutput as I, Tool as T, defineTool as d };

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

@@ -1,5 +1,5 @@
 import { T as ToolHost } from './types-CHiPh8U2.js';
-import { b as ScopeSnapshot } from './types-9jGQUjqW.js';
+import { S as ScopeSnapshot } from './types-CQL-SvTn.js';
 
 /**
  * Tool-related types for @cuylabs/agent-core

package/dist/tracking/index.d.ts

@@ -1,8 +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-HUtkiVBx.js';
+import { F as FileOperationMeta } from '../tool-DLXAR9Ce.js';
 import '../types-CHiPh8U2.js';
-import '../types-9jGQUjqW.js';
+import '../types-CQL-SvTn.js';
 
 /**
  * Checkpoint system contracts for @cuylabs/agent-core.