@cuylabs/agent-core 0.7.0 → 0.9.0

package/dist/prompt/index.js

@@ -19,8 +19,9 @@ import {
   getTemplate,
   loadGlobalInstructions,
   summarizeEnvironment
-} from "../chunk-IVUJDISU.js";
-import "../chunk-LRHOS4ZN.js";
+} from "../chunk-GFTW23FV.js";
+import "../chunk-SPILYYDF.js";
+import "../chunk-I6PKJ7XQ.js";
 export {
   DEFAULT_INSTRUCTION_PATTERNS,
   DEFAULT_MAX_DEPTH,

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-CI-XeR16.d.ts

@@ -0,0 +1,91 @@
+import { A as AgentMiddleware, M as ModelCallInput, a as ModelCallContext, B as BlockedModelCall, S as StreamChunk, b as ModelCallOutput, T as ToolCallDecision, P as PromptBuildContext, c as PromptSection } from './types-DTSkxakL.js';
+import { A as AgentEvent } from './events-CE72w8W4.js';
+import { T as TokenUsage } from './messages-BYWGn8TY.js';
+import { T as ToolContext } from './tool-DkhSCV2Y.js';
+import { T as Tool } from './tool-CZWN3KbO.js';
+
+/**
+ * Middleware Runner
+ *
+ * Executes middleware hooks in the correct order with proper
+ * error handling and short-circuit semantics.
+ *
+ * This is the internal engine — consumers never see it.
+ * They interact with middleware through AgentConfig.middleware.
+ */
+
+/**
+ * Middleware runner — holds an ordered list of middleware and
+ * exposes methods to run each hook type with correct semantics.
+ *
+ * Immutable after construction. Fork creates a new runner
+ * (with inherited + additional middleware).
+ */
+declare class MiddlewareRunner {
+    private readonly stack;
+    constructor(middleware?: AgentMiddleware[]);
+    /** Number of registered middleware */
+    get count(): number;
+    /** Whether any middleware is registered */
+    get hasMiddleware(): boolean;
+    /** Get the middleware list (for fork inheritance) */
+    getMiddleware(): readonly AgentMiddleware[];
+    runModelInput(input: ModelCallInput, ctx: ModelCallContext): Promise<ModelCallInput | BlockedModelCall>;
+    runModelChunk(chunk: StreamChunk, ctx: ModelCallContext): Promise<StreamChunk | undefined>;
+    runModelOutput(output: ModelCallOutput, ctx: ModelCallContext): Promise<ModelCallOutput>;
+    /**
+     * Run all `beforeToolCall` hooks in order.
+     *
+     * Returns `{ action: "allow" }` if all middleware allow (or have no hook).
+     * Returns `{ action: "deny", reason }` on first denial — remaining
+     * middleware are skipped.
+     */
+    runBeforeToolCall(tool: string, args: unknown, ctx: ToolContext): Promise<ToolCallDecision>;
+    /**
+     * Run all `afterToolCall` hooks in reverse order.
+     *
+     * Each hook receives the result from the previous hook (or the
+     * original tool result for the first hook). Errors are caught
+     * and logged — the original result passes through.
+     */
+    runAfterToolCall(tool: string, args: unknown, result: Tool.ExecuteResult, ctx: ToolContext): Promise<Tool.ExecuteResult>;
+    /**
+     * Collect prompt sections from all middleware.
+     *
+     * Returns a flat array of sections. Each middleware can return a single
+     * section, an array of sections, or undefined/empty.
+     */
+    collectPromptSections(ctx: PromptBuildContext): PromptSection[];
+    /**
+     * Broadcast an event to all middleware observers.
+     *
+     * Non-blocking — errors are caught and logged. This never
+     * slows down the streaming pipeline.
+     */
+    emitEvent(event: AgentEvent): void;
+    /**
+     * Get the OTel context for a session from the telemetry middleware.
+     * Returns undefined if no telemetry middleware is registered.
+     */
+    getOtelContext(sessionId: string): unknown | undefined;
+    /**
+     * Run all `onChatStart` hooks in order.
+     *
+     * Errors are caught and logged — a broken logger should not
+     * prevent the chat from starting.
+     */
+    runChatStart(sessionId: string, message: string): Promise<void>;
+    /**
+     * Run all `onChatEnd` hooks in order.
+     *
+     * Always called, even when the stream errored. Errors in handlers
+     * are caught and logged.
+     */
+    runChatEnd(sessionId: string, result: {
+        usage?: TokenUsage;
+        error?: Error;
+        output?: string;
+    }): Promise<void>;
+}
+
+export { MiddlewareRunner as M };

package/dist/runtime/index.d.ts

@@ -1,16 +1,20 @@
-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-DmDwi2zI.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-DmDwi2zI.js';
+import { A as AnyInferenceResult } from '../types-BlOKk-Bb.js';
 import { ModelMessage } from 'ai';
-import '@ai-sdk/provider-utils';
-import '../tool-Db1Ue-1U.js';
+import '../tool-CZWN3KbO.js';
 import 'zod';
-import '../tool-HUtkiVBx.js';
+import '../tool-DkhSCV2Y.js';
 import '../types-CHiPh8U2.js';
+import '../runner-CI-XeR16.js';
+import '../types-DTSkxakL.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,15 @@ 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-J4QDGZIA.js";
+import "../chunk-WWYYNWEW.js";
+import "../chunk-WKHDSSXG.js";
+import "../chunk-H3FUYU52.js";
 import "../chunk-VEKUXUVF.js";
-import "../chunk-QGOGIP7T.js";
+import "../chunk-4QFNWPIF.js";
+import "../chunk-N7P4PN3O.js";
+import "../chunk-UDCZ673N.js";
+import "../chunk-I6PKJ7XQ.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-5ARZJWD2.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/{session-manager-B_CWGTsl.d.ts → session-manager-KbYt2WUh.d.ts}

@@ -256,6 +256,14 @@ declare class SessionManager {
         readFiles?: string[];
         modifiedFiles?: string[];
     }): Promise<string>;
+    replaceWithCompaction(options: {
+        summary: string;
+        messages: Message[];
+        tokensBefore: number;
+        tokensAfter: number;
+        readFiles?: string[];
+        modifiedFiles?: string[];
+    }): Promise<string>;
     branch(fromEntryId: string, summary?: string): Promise<string>;
     switchToLeaf(leafId: string): void;
     updateMetadata(updates: {

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-DXFBQMXP.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-CZWN3KbO.js';
 import 'zod';
-import '../tool-HUtkiVBx.js';
+import '../tool-DkhSCV2Y.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/skill/index.js

@@ -2,8 +2,8 @@ import {
   createSkillResourceTool,
   createSkillTool,
   createSkillTools
-} from "../chunk-YUUJK53A.js";
-import "../chunk-P6YF7USR.js";
+} from "../chunk-RKEW5WXI.js";
+import "../chunk-MHKK374K.js";
 import {
   DEFAULT_EXTERNAL_DIRS,
   DEFAULT_MAX_SCAN_DEPTH,
@@ -18,7 +18,7 @@ import {
   loadSkillContent,
   loadSkillMetadata,
   parseFrontmatter
-} from "../chunk-LRHOS4ZN.js";
+} from "../chunk-SPILYYDF.js";
 export {
   DEFAULT_EXTERNAL_DIRS,
   DEFAULT_MAX_SCAN_DEPTH,

package/dist/storage/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FileEntry, g as SessionEntry, M as MessageEntry, c as MetadataEntry, e as SerializedMessage, i as SessionInfo, j as SessionStorage, h as SessionHeader, S as SessionManager } from '../session-manager-B_CWGTsl.js';
-export { B as BranchEntry, C as CompactionEntry, a as ConfigChangeEntry, b as CreateSessionOptions, E as EntryBase, d as STORAGE_VERSION, f as SessionContext } from '../session-manager-B_CWGTsl.js';
+import { F as FileEntry, g as SessionEntry, M as MessageEntry, c as MetadataEntry, e as SerializedMessage, i as SessionInfo, j as SessionStorage, h as SessionHeader, S as SessionManager } from '../session-manager-KbYt2WUh.js';
+export { B as BranchEntry, C as CompactionEntry, a as ConfigChangeEntry, b as CreateSessionOptions, E as EntryBase, d as STORAGE_VERSION, f as SessionContext } from '../session-manager-KbYt2WUh.js';
 import { M as Message } from '../messages-BYWGn8TY.js';
 
 /**

package/dist/storage/index.js

@@ -22,7 +22,7 @@ import {
   serializeMessage,
   toJSONL,
   toJSONLBatch
-} from "../chunk-BDBZ3SLK.js";
+} from "../chunk-UHCJEM2E.js";
 export {
   FileStorage,
   MemoryStorage,

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

@@ -1,18 +1,24 @@
-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 AgentDiscoveryOptions, c as AgentDiscoveryResult, d as AgentProfile, e as AgentSource, D as DEFAULT_MAX_CONCURRENT, f as DEFAULT_MAX_SPAWN_DEPTH, g as DEFAULT_SESSION_TITLE_PREFIX, h as DiscoveredProfile, M as MarkdownAgentFrontmatter, i as MarkdownAgentProfile, j as ParsedMarkdownAgent, k as ParsedToolSpec, l as ProfileResolvers, S as SubAgentCompletedResult, m as SubAgentHandle, n as SubAgentStatus, o as SubAgentToolConfig, p as SubAgentTracker, q as SubAgentUsage, T as ToolModifier, t as createSubAgentTools, u as discoverAgentProfiles, v as getProjectAgentsDir, w as getUserAgentsDir, x as isMarkdownProfile, y as parseAgentFrontmatter, z as parseMarkdownAgent, B as parseToolSpec, E as toAgentProfile } from '../index-DQuTZ8xL.js';
 import 'ai';
+import '../types-BlZwmnuW.js';
 import '../types-CQaXbRsS.js';
-import '../tool-Db1Ue-1U.js';
+import '../tool-CZWN3KbO.js';
 import 'zod';
-import '../tool-HUtkiVBx.js';
+import '../tool-DkhSCV2Y.js';
 import '../types-CHiPh8U2.js';
-import '../types-9jGQUjqW.js';
-import '../runner-DSKaEz3z.js';
+import '../types-CQL-SvTn.js';
+import '../types-DTSkxakL.js';
 import '@ai-sdk/provider-utils';
+import '../events-CE72w8W4.js';
 import '../messages-BYWGn8TY.js';
-import '../session-manager-B_CWGTsl.js';
+import '../types-BfNpU8NS.js';
+import '../session-manager-KbYt2WUh.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-BgZ_j4Vs.js';
+import '../registry-DwYqsQkX.js';
+import '../runner-CI-XeR16.js';
+import '../types-BlOKk-Bb.js';
+import '../llm-error-D93FNNLY.js';
+import '../types-DmDwi2zI.js';

package/dist/sub-agent/index.js

@@ -3,13 +3,30 @@ import {
   DEFAULT_MAX_SPAWN_DEPTH,
   DEFAULT_SESSION_TITLE_PREFIX,
   SubAgentTracker,
-  createSubAgentTools
-} from "../chunk-7MUFEN4K.js";
-import "../chunk-P6YF7USR.js";
+  createSubAgentTools,
+  discoverAgentProfiles,
+  getProjectAgentsDir,
+  getUserAgentsDir,
+  isMarkdownProfile,
+  parseAgentFrontmatter,
+  parseMarkdownAgent,
+  parseToolSpec,
+  toAgentProfile
+} from "../chunk-JLXG2SH7.js";
+import "../chunk-EKR6PKXU.js";
+import "../chunk-MHKK374K.js";
 export {
   DEFAULT_MAX_CONCURRENT,
   DEFAULT_MAX_SPAWN_DEPTH,
   DEFAULT_SESSION_TITLE_PREFIX,
   SubAgentTracker,
-  createSubAgentTools
+  createSubAgentTools,
+  discoverAgentProfiles,
+  getProjectAgentsDir,
+  getUserAgentsDir,
+  isMarkdownProfile,
+  parseAgentFrontmatter,
+  parseMarkdownAgent,
+  parseToolSpec,
+  toAgentProfile
 };

package/dist/tool/index.d.ts

@@ -1,13 +1,16 @@
-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-CZWN3KbO.js';
+export { C as CompatibleSchema, I as InferSchemaOutput, d as defineTool } from '../tool-CZWN3KbO.js';
+import { b as ToolReplayPolicy, F as FileOperationMeta, N as NormalizedToolReplayPolicy, d as TurnTrackerContext, a as ToolMetadata } from '../tool-DkhSCV2Y.js';
 import { T as ToolHost } from '../types-CHiPh8U2.js';
-import { M as MiddlewareRunner } from '../runner-DSKaEz3z.js';
+import { M as MiddlewareRunner } from '../runner-CI-XeR16.js';
 import 'zod';
-import '../types-9jGQUjqW.js';
+import '../types-CQL-SvTn.js';
+import '../types-DTSkxakL.js';
 import 'ai';
 import '@ai-sdk/provider-utils';
+import '../events-CE72w8W4.js';
 import '../messages-BYWGn8TY.js';
+import '../types-BfNpU8NS.js';
 import '../types-CQaXbRsS.js';
 
 /**
@@ -139,7 +142,10 @@ 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;
@@ -162,9 +168,19 @@ interface ExecuteAgentToolCallOptions {
     host?: ToolHost;
     turnTracker?: TurnTrackerContext;
     middleware?: MiddlewareRunner;
+    /**
+     * 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;
 }
 /**
  * Execute one initialized framework tool with the same semantics used by the

package/dist/tool/index.js

@@ -12,12 +12,12 @@ import {
   formatSize,
   normalizeToolReplayPolicy,
   truncateOutput
-} from "../chunk-P6YF7USR.js";
+} from "../chunk-MHKK374K.js";
 import {
   executeAgentToolCall
-} from "../chunk-IEFIQENH.js";
-import "../chunk-N7P4PN3O.js";
+} from "../chunk-H3FUYU52.js";
 import "../chunk-VEKUXUVF.js";
+import "../chunk-N7P4PN3O.js";
 export {
   MAX_BYTES,
   MAX_LINES,

package/dist/tool-CZWN3KbO.d.ts

@@ -0,0 +1,141 @@
+import { z } from 'zod';
+import { a as ToolMetadata, b as ToolReplayPolicy, T as ToolContext, F as FileOperationMeta, c as ToolResult } from './tool-DkhSCV2Y.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>;
+}
+/**
+ * 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-DkhSCV2Y.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
@@ -142,4 +142,4 @@ interface ToolMetadata {
     [key: string]: unknown;
 }
 
-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 };
+export type { FileOperationMeta as F, NormalizedToolReplayPolicy as N, ToolContext as T, ToolMetadata as a, ToolReplayPolicy as b, ToolResult as c, TurnTrackerContext as d, ToolReplayMode as e, ToolSideEffectLevel as f };

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-DkhSCV2Y.js';
 import '../types-CHiPh8U2.js';
-import '../types-9jGQUjqW.js';
+import '../types-CQL-SvTn.js';
 
 /**
  * Checkpoint system contracts for @cuylabs/agent-core.