@kuralle-agents/core 0.13.0 → 0.14.0

package/dist/skills/fsSkillStore.js

@@ -0,0 +1,79 @@
+import { parseSkillFrontmatter } from './parseSkillFrontmatter.js';
+const DEFAULT_ROOT = '/skills';
+export function fsSkillStore(fs, orderedRoots = [DEFAULT_ROOT]) {
+    const roots = [...orderedRoots];
+    return {
+        async list() {
+            const skills = await discoverSkills(fs, roots, true);
+            return [...skills.values()]
+                .map((skill) => skill.meta)
+                .sort((a, b) => a.name.localeCompare(b.name));
+        },
+        async loadBody(name) {
+            const skill = (await discoverSkills(fs, roots, false)).get(name);
+            if (!skill) {
+                throw new Error(`[skills] Skill "${name}" not found.`);
+            }
+            return skill.body;
+        },
+        async loadResource(name, path) {
+            const skill = (await discoverSkills(fs, roots, false)).get(name);
+            if (!skill) {
+                throw new Error(`[skills] Skill "${name}" not found.`);
+            }
+            const normalized = path.trim().replace(/^\.?\//, '');
+            if (normalized.includes('..') || normalized.startsWith('/')) {
+                throw new Error(`[skills] Invalid resource path "${path}".`);
+            }
+            const resourcePath = fs.resolvePath(skill.root, `${skill.folder}/${normalized}`);
+            if (!(await fs.exists(resourcePath))) {
+                const err = new Error(`ENOENT: [skills] Resource "${normalized}" not found for skill "${name}".`);
+                throw err;
+            }
+            return fs.readFile(resourcePath);
+        },
+    };
+}
+async function discoverSkills(fs, roots, warnInvalid) {
+    const skills = new Map();
+    for (const root of roots) {
+        let entries;
+        try {
+            entries = await fs.readdir(root);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries.sort()) {
+            const entryPath = fs.resolvePath(root, entry);
+            let stat;
+            try {
+                stat = await fs.stat(entryPath);
+            }
+            catch {
+                continue;
+            }
+            if (stat.type !== 'directory')
+                continue;
+            const skillPath = fs.resolvePath(root, `${entry}/SKILL.md`);
+            if (!(await fs.exists(skillPath)))
+                continue;
+            try {
+                const content = await fs.readFile(skillPath);
+                const parsed = parseSkillFrontmatter(content, { path: skillPath });
+                skills.set(parsed.name, {
+                    root,
+                    folder: entry,
+                    meta: { name: parsed.name, description: parsed.description },
+                    body: parsed.body,
+                });
+            }
+            catch (err) {
+                if (warnInvalid) {
+                    console.warn(`[skills] Skipping ${skillPath}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+    }
+    return skills;
+}

package/dist/skills/index.d.ts

@@ -3,3 +3,7 @@ export { wireAgentSkills } from './wireAgentSkills.js';
 export type { WiredAgentSkills } from './wireAgentSkills.js';
 export { collectRegisteredNames, validateSkillAllowedTools, prepareSkillStore, isSkillStore, type SkillWireAgent, } from './collectSkills.js';
 export { InlineSkillStore } from './inlineSkillStore.js';
+export { CompositeSkillStore } from './compositeSkillStore.js';
+export { fsSkillStore } from './fsSkillStore.js';
+export { defineSkill, type DefineSkillConfig } from './defineSkill.js';
+export { parseSkillFrontmatter, validateSkillName, validateSkillDescription, type ParsedSkill, } from './parseSkillFrontmatter.js';

package/dist/skills/index.js

@@ -2,3 +2,7 @@ export { SkillsCapability } from './SkillsCapability.js';
 export { wireAgentSkills } from './wireAgentSkills.js';
 export { collectRegisteredNames, validateSkillAllowedTools, prepareSkillStore, isSkillStore, } from './collectSkills.js';
 export { InlineSkillStore } from './inlineSkillStore.js';
+export { CompositeSkillStore } from './compositeSkillStore.js';
+export { fsSkillStore } from './fsSkillStore.js';
+export { defineSkill } from './defineSkill.js';
+export { parseSkillFrontmatter, validateSkillName, validateSkillDescription, } from './parseSkillFrontmatter.js';

package/dist/skills/parseSkillFrontmatter.d.ts

@@ -0,0 +1,14 @@
+export interface ParsedSkill {
+    name: string;
+    description: string;
+    body: string;
+    license?: string;
+    compatibility?: string;
+    allowedTools?: string[];
+    metadata?: Record<string, string>;
+}
+export declare function parseSkillFrontmatter(content: string, ctx: {
+    path: string;
+}): ParsedSkill;
+export declare function validateSkillName(name: string, path: string): void;
+export declare function validateSkillDescription(description: string, path: string): void;

package/dist/skills/parseSkillFrontmatter.js

@@ -0,0 +1,183 @@
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)([\s\S]*)$/;
+const NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export function parseSkillFrontmatter(content, ctx) {
+    const stripped = content.replace(/^\uFEFF/, '');
+    const match = stripped.match(FRONTMATTER_RE);
+    if (!match) {
+        throw new Error(`[skills] Skill ${ctx.path} is missing YAML frontmatter. Start SKILL.md with "---", ` +
+            'include "name" and "description", then close the block with "---".');
+    }
+    const raw = parseFlatYaml(match[1] ?? '', ctx.path);
+    const name = requireField(raw, 'name', ctx.path);
+    const description = requireField(raw, 'description', ctx.path);
+    validateSkillName(name, ctx.path);
+    validateSkillDescription(description, ctx.path);
+    const compatibility = optionalString(raw.compatibility);
+    if (compatibility !== undefined && codePointLength(compatibility) > 500) {
+        throw new Error(`[skills] Skill ${ctx.path} field "compatibility" exceeds 500 characters.`);
+    }
+    let body = match[2] ?? '';
+    if (body.startsWith('\n')) {
+        body = body.slice(1);
+    }
+    const result = { name, description, body };
+    const license = optionalString(raw.license);
+    if (license !== undefined)
+        result.license = license;
+    if (compatibility !== undefined)
+        result.compatibility = compatibility;
+    const allowedTools = parseAllowedTools(raw['allowed-tools']);
+    if (allowedTools !== undefined)
+        result.allowedTools = allowedTools;
+    const metadata = parseMetadata(raw.metadata);
+    if (metadata !== undefined)
+        result.metadata = metadata;
+    return result;
+}
+function parseFlatYaml(yaml, path) {
+    const result = {};
+    const lines = yaml.split(/\r?\n/);
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line.trim() === '') {
+            i += 1;
+            continue;
+        }
+        const keyMatch = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (!keyMatch) {
+            throw new Error(`[skills] Skill ${path} has invalid YAML frontmatter near line: ${line}`);
+        }
+        const key = keyMatch[1];
+        const rest = (keyMatch[2] ?? '').trim();
+        if (rest === '') {
+            i += 1;
+            if (i >= lines.length)
+                break;
+            const next = lines[i];
+            if (next.match(/^\s+-\s+/)) {
+                const items = [];
+                while (i < lines.length) {
+                    const listLine = lines[i];
+                    const itemMatch = listLine.match(/^\s+-\s+(.*)$/);
+                    if (!itemMatch)
+                        break;
+                    items.push(parseScalar(itemMatch[1] ?? ''));
+                    i += 1;
+                }
+                result[key] = items;
+                continue;
+            }
+            if (key === 'metadata') {
+                const meta = {};
+                while (i < lines.length) {
+                    const metaLine = lines[i];
+                    const metaMatch = metaLine.match(/^\s{2}([A-Za-z0-9_-]+):\s*(.*)$/);
+                    if (!metaMatch)
+                        break;
+                    meta[metaMatch[1]] = parseScalar((metaMatch[2] ?? '').trim());
+                    i += 1;
+                }
+                result[key] = meta;
+                continue;
+            }
+            result[key] = '';
+            continue;
+        }
+        if (rest.startsWith('[') && rest.endsWith(']')) {
+            const inner = rest.slice(1, -1).trim();
+            result[key] =
+                inner === ''
+                    ? []
+                    : inner.split(',').map((s) => parseScalar(s.trim()));
+            i += 1;
+            continue;
+        }
+        result[key] = parseScalar(rest);
+        i += 1;
+    }
+    return result;
+}
+function parseScalar(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+function requireField(raw, field, path) {
+    const value = raw[field];
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(`[skills] Skill ${path} must define frontmatter ${field} as a non-empty string.`);
+    }
+    return value.trim();
+}
+function optionalString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/** Agent Skills forbids reserved vendor words in a skill name. */
+const RESERVED_NAME_WORDS = ['anthropic', 'claude'];
+/** Frontmatter is injected into the system prompt, so markup in it is a prompt-injection seam. */
+const XML_TAG_PATTERN = /<\/?[a-zA-Z][^>]*>/;
+export function validateSkillName(name, path) {
+    if (name.length > 64) {
+        throw new Error(`[skills] Skill ${path} field "name" must be at most 64 characters.`);
+    }
+    if (XML_TAG_PATTERN.test(name)) {
+        throw new Error(`[skills] Skill ${path} field "name" must not contain XML tags.`);
+    }
+    if (!NAME_PATTERN.test(name)) {
+        throw new Error(`[skills] Skill ${path} field "name" "${name}" must match /^[a-z0-9]+(?:-[a-z0-9]+)*$/.`);
+    }
+    const reserved = RESERVED_NAME_WORDS.find((word) => name.includes(word));
+    if (reserved) {
+        throw new Error(`[skills] Skill ${path} field "name" must not contain the reserved word "${reserved}".`);
+    }
+}
+export function validateSkillDescription(description, path) {
+    if (codePointLength(description) > 1024) {
+        throw new Error(`[skills] Skill ${path} field "description" exceeds 1024 characters.`);
+    }
+    if (XML_TAG_PATTERN.test(description)) {
+        throw new Error(`[skills] Skill ${path} field "description" must not contain XML tags.`);
+    }
+}
+function codePointLength(value) {
+    return [...value].length;
+}
+function parseAllowedTools(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (Array.isArray(value)) {
+        const tools = value.map((v) => String(v).trim()).filter(Boolean);
+        return tools.length > 0 ? tools : undefined;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed)
+            return undefined;
+        const tools = trimmed.includes(',')
+            ? trimmed.split(',').map((s) => s.trim()).filter(Boolean)
+            : trimmed.split(/\s+/).filter(Boolean);
+        return tools.length > 0 ? tools : undefined;
+    }
+    return undefined;
+}
+function parseMetadata(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        return undefined;
+    const meta = {};
+    for (const [k, v] of entries) {
+        meta[k] = String(v);
+    }
+    return meta;
+}

package/dist/skills/wireAgentSkills.d.ts

@@ -1,3 +1,4 @@
+import type { FileSystem } from '../types/filesystem.js';
 import { type AnyTool } from '../types/effectTool.js';
 import type { PromptSection } from '../capabilities/index.js';
 import { type SkillWireAgent } from './collectSkills.js';
@@ -7,4 +8,4 @@ export interface WiredAgentSkills {
     tools: Record<string, AnyTool>;
     promptSections: PromptSection[];
 }
-export declare function wireAgentSkills(agent: SkillWireAgent): Promise<WiredAgentSkills | undefined>;
+export declare function wireAgentSkills(agent: SkillWireAgent, fs?: FileSystem): Promise<WiredAgentSkills | undefined>;

package/dist/skills/wireAgentSkills.js

@@ -1,10 +1,10 @@
 import { defineTool } from '../types/effectTool.js';
 import { collectRegisteredNames, prepareSkillStore, validateSkillAllowedTools, } from './collectSkills.js';
 import { SkillsCapability } from './SkillsCapability.js';
-export async function wireAgentSkills(agent) {
+export async function wireAgentSkills(agent, fs) {
     if (!agent.skills)
         return undefined;
-    const { store, skills } = await prepareSkillStore(agent.skills);
+    const { store, skills } = await prepareSkillStore(agent.skills, fs);
     validateSkillAllowedTools(skills, collectRegisteredNames(agent));
     const metas = await store.list();
     const capability = new SkillsCapability(store, metas);

package/dist/testing/mocks.d.ts

@@ -1,4 +1,4 @@
-import type { HarnessStreamPart, TurnHandle } from '../types/stream.js';
+import type { StreamPart, TurnHandle } from '../types/stream.js';
 import type { TurnResult } from '../types/channel.js';
 import type { Session } from '../types/session.js';
 import type { UserInputContent } from '../runtime/userInput.js';
@@ -13,8 +13,8 @@ export interface CreateMockRuntimeOptions {
     sessions?: Map<string, Session>;
     onRun?: (call: MockRuntimeRunCall) => void;
 }
-export declare function createMockTurnHandle(events: AsyncIterable<HarnessStreamPart>, settled?: TurnResult): TurnHandle;
+export declare function createMockTurnHandle(events: AsyncIterable<StreamPart>, settled?: TurnResult): TurnHandle;
 export declare function createMockSession(partial?: Partial<Session>): Session;
-type MockRuntimeEvents = HarnessStreamPart[] | AsyncIterable<HarnessStreamPart> | (() => never);
+type MockRuntimeEvents = StreamPart[] | AsyncIterable<StreamPart> | (() => never);
 export declare function createMockRuntime(parts: MockRuntimeEvents, options?: CreateMockRuntimeOptions): RuntimeLike;
 export {};

package/dist/testing/mocks.js

@@ -37,12 +37,16 @@ export function createMockSession(partial = {}) {
         handoffHistory: partial.handoffHistory ?? [],
     };
 }
+function isAsyncIterable(value) {
+    return Symbol.asyncIterator in value;
+}
 export function createMockRuntime(parts, options = {}) {
     const sessions = options.sessions ?? new Map();
     const run = (opts) => {
         if (typeof parts === 'function') {
             throw parts();
         }
+        const eventSource = parts;
         options.onRun?.({
             sessionId: opts.sessionId,
             input: opts.input,
@@ -50,13 +54,13 @@ export function createMockRuntime(parts, options = {}) {
             seedMessages: opts.seedMessages,
         });
         async function* events() {
-            if (Symbol.asyncIterator in Object(parts)) {
-                for await (const part of parts) {
+            if (isAsyncIterable(eventSource)) {
+                for await (const part of eventSource) {
                     yield part;
                 }
                 return;
             }
-            for (const part of parts) {
+            for (const part of eventSource) {
                 yield part;
             }
         }

package/dist/tools/controlResults.d.ts

@@ -13,3 +13,17 @@ export declare function toolErrorResult(error: unknown): {
     error: true;
     message: string;
 };
+export interface ToolDeniedResult {
+    __denied: true;
+    toolName: string;
+    deniedBy?: string;
+    message: string;
+}
+/**
+ * What the model sees when a human declines a `needsApproval` tool it asked to run.
+ *
+ * A result rather than an error, so the agent can tell the user the request was declined
+ * instead of the turn dying. `__denied` (not `error: true`) keeps it distinguishable from a
+ * genuine failure — nothing malfunctioned.
+ */
+export declare function toolDeniedResult(toolName: string, deniedBy?: string): ToolDeniedResult;

package/dist/tools/controlResults.js

@@ -16,3 +16,18 @@ export function toolErrorResult(error) {
     const message = error instanceof Error ? error.message : String(error);
     return { error: true, message };
 }
+/**
+ * What the model sees when a human declines a `needsApproval` tool it asked to run.
+ *
+ * A result rather than an error, so the agent can tell the user the request was declined
+ * instead of the turn dying. `__denied` (not `error: true`) keeps it distinguishable from a
+ * genuine failure — nothing malfunctioned.
+ */
+export function toolDeniedResult(toolName, deniedBy) {
+    return {
+        __denied: true,
+        toolName,
+        deniedBy,
+        message: `The "${toolName}" action was not approved${deniedBy ? ` by ${deniedBy}` : ''}. Tell the user it was declined; do not retry it.`,
+    };
+}

package/dist/tools/effect/ToolExecutor.d.ts

@@ -9,6 +9,11 @@ export interface CoreToolExecutorConfig {
     parallelExecution?: boolean;
     agentId?: string;
     onInterim?: (message: string, toolName: string) => void;
+    /**
+     * Called for each chunk an async-iterable tool yields, as it arrives. The aggregate is
+     * still the tool's result; this is progress, not output.
+     */
+    onChunk?: (chunk: unknown, toolName: string, toolCallId: string) => void;
 }
 export interface CoreExecuteArgs {
     name: string;
@@ -26,6 +31,7 @@ export declare class CoreToolExecutor implements EffectToolExecutor {
     private readonly parallelExecution;
     private readonly agentId;
     private readonly onInterim?;
+    private readonly onChunk?;
     private readonly pairing;
     private executionGate;
     private callHistory;

package/dist/tools/effect/ToolExecutor.js

@@ -3,12 +3,44 @@ import { debug } from '../../debug.js';
 import { cancelledPlaceholder, inProgressPlaceholder, PairingTracker, } from './pairing.js';
 import { ToolTimeoutError } from './errors.js';
 import { ToolValidationError, validateAndSanitize, validateOutput } from './schema.js';
+import { isControlFlowSignal } from '../../runtime/controlFlowSignal.js';
+/**
+ * Merges the caller's abort with a timeout so the tool sees one signal. `AbortSignal.any` is
+ * present on Node 20+, Bun, and workerd; the manual path keeps older runtimes working.
+ * Mirrors `composeSignals` in `@kuralle-agents/fs`.
+ */
+function composeSignals(signal, timeoutSignal) {
+    if (!signal)
+        return timeoutSignal;
+    if (!timeoutSignal)
+        return signal;
+    if (typeof AbortSignal.any === 'function') {
+        return AbortSignal.any([signal, timeoutSignal]);
+    }
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    signal.addEventListener('abort', onAbort, { once: true });
+    timeoutSignal.addEventListener('abort', onAbort, { once: true });
+    if (signal.aborted || timeoutSignal.aborted)
+        onAbort();
+    return controller.signal;
+}
+function rejectOnAbort(signal, makeError) {
+    return new Promise((_, reject) => {
+        if (signal.aborted) {
+            reject(makeError());
+            return;
+        }
+        signal.addEventListener('abort', () => reject(makeError()), { once: true });
+    });
+}
 export class CoreToolExecutor {
     tools;
     enforcer;
     parallelExecution;
     agentId;
     onInterim;
+    onChunk;
     pairing = new PairingTracker();
     executionGate = Promise.resolve();
     callHistory = [];
@@ -18,6 +50,7 @@ export class CoreToolExecutor {
         this.parallelExecution = config.parallelExecution ?? false;
         this.agentId = config.agentId ?? 'agent';
         this.onInterim = config.onInterim;
+        this.onChunk = config.onChunk;
     }
     getPairs() {
         return this.pairing.getAllPairs();
@@ -97,19 +130,14 @@ export class CoreToolExecutor {
             }
         }
         let interimTimer;
-        let timeoutTimer;
-        let interimSent = false;
         const onAbort = () => {
             if (interimTimer)
                 clearTimeout(interimTimer);
-            if (timeoutTimer)
-                clearTimeout(timeoutTimer);
         };
         abortSignal?.addEventListener('abort', onAbort, { once: true });
         try {
             if (def.interim && def.interimAfterMs != null && def.interimAfterMs >= 0) {
                 interimTimer = setTimeout(() => {
-                    interimSent = true;
                     this.onInterim?.(def.interim, name);
                     this.pairing.closePair(requestId, 'in_progress', inProgressPlaceholder(requestId, name, def.interim));
                 }, def.interimAfterMs);
@@ -117,40 +145,36 @@ export class CoreToolExecutor {
                     interimTimer.unref();
                 }
             }
+            const timeoutMs = def.timeoutMs;
+            // The tool receives the timeout as an abort, so a cooperative tool stops working when
+            // we stop waiting for it. Racing alone abandoned the promise while the work continued.
+            const timeoutSignal = timeoutMs != null && timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;
+            const effectiveSignal = composeSignals(abortSignal, timeoutSignal);
             const executeCtx = toolCtx
-                ? { ...toolCtx, abortSignal }
-                : abortSignal
-                    ? { abortSignal }
+                ? { ...toolCtx, abortSignal: effectiveSignal }
+                : effectiveSignal
+                    ? { abortSignal: effectiveSignal }
                     : undefined;
             const executePromise = Promise.resolve(def.execute(sanitizedArgs, executeCtx)).then(async (result) => {
                 if (result && typeof result[Symbol.asyncIterator] === 'function') {
                     const chunks = [];
                     for await (const chunk of result) {
                         chunks.push(chunk);
+                        // Surface progress as it arrives. Observational only — the journal records the
+                        // aggregate below, so a replayed step emits nothing and stays deterministic.
+                        this.onChunk?.(chunk, name, requestId);
                     }
                     return chunks.length === 1 ? chunks[0] : chunks;
                 }
                 return result;
             });
+            // The signals above cancel a cooperative tool; these racers stop us waiting on one that
+            // ignores them. Both are needed — neither alone bounds the call.
             const abortPromise = abortSignal && def.interruptible !== false
-                ? new Promise((_, reject) => {
-                    if (abortSignal.aborted) {
-                        reject(new DOMException('Aborted', 'AbortError'));
-                        return;
-                    }
-                    abortSignal.addEventListener('abort', () => reject(new DOMException('Aborted', 'AbortError')), { once: true });
-                })
+                ? rejectOnAbort(abortSignal, () => new DOMException('Aborted', 'AbortError'))
                 : null;
-            const timeoutMs = def.timeoutMs;
-            const timeoutPromise = timeoutMs != null && timeoutMs > 0
-                ? new Promise((_, reject) => {
-                    timeoutTimer = setTimeout(() => {
-                        reject(new ToolTimeoutError(name, timeoutMs));
-                    }, timeoutMs);
-                    if (typeof timeoutTimer === 'object' && 'unref' in timeoutTimer) {
-                        timeoutTimer.unref();
-                    }
-                })
+            const timeoutPromise = timeoutSignal
+                ? rejectOnAbort(timeoutSignal, () => new ToolTimeoutError(name, timeoutMs))
                 : null;
             const racers = [executePromise];
             if (abortPromise)
@@ -160,25 +184,16 @@ export class CoreToolExecutor {
             const rawResult = racers.length > 1 ? await Promise.race(racers) : await executePromise;
             if (interimTimer)
                 clearTimeout(interimTimer);
-            if (timeoutTimer)
-                clearTimeout(timeoutTimer);
             const validated = await validateOutput(def.output, rawResult, name);
             callRecord.result = validated;
             callRecord.durationMs = Date.now() - callRecord.timestamp;
             this.callHistory.push(callRecord);
-            if (!interimSent) {
-                this.pairing.closePair(requestId, 'completed', validated);
-            }
-            else {
-                this.pairing.closePair(requestId, 'completed', validated);
-            }
+            this.pairing.closePair(requestId, 'completed', validated);
             return validated;
         }
         catch (error) {
             if (interimTimer)
                 clearTimeout(interimTimer);
-            if (timeoutTimer)
-                clearTimeout(timeoutTimer);
             if (error instanceof DOMException && error.name === 'AbortError') {
                 const placeholder = cancelledPlaceholder(requestId, name);
                 callRecord.success = false;
@@ -192,6 +207,27 @@ export class CoreToolExecutor {
                 this.pairing.closePair(requestId, 'validation_failed', undefined, error.message);
                 throw error;
             }
+            if (error instanceof ToolTimeoutError || isControlFlowSignal(error)) {
+                // A timeout and a suspend are decisions about the run, not results the tool may
+                // reinterpret. They reach the caller unchanged.
+                throw error;
+            }
+            if (def.onError) {
+                // Recovery runs before the failure is recorded, so a handled error is journaled as
+                // the success it became. A throwing handler falls through to the generic path below.
+                try {
+                    const recovered = await def.onError(error instanceof Error ? error : new Error(String(error)), sanitizedArgs);
+                    const validatedRecovery = await validateOutput(def.output, recovered, name);
+                    callRecord.result = validatedRecovery;
+                    callRecord.durationMs = Date.now() - callRecord.timestamp;
+                    this.callHistory.push(callRecord);
+                    this.pairing.closePair(requestId, 'completed', validatedRecovery);
+                    return validatedRecovery;
+                }
+                catch (recoveryError) {
+                    error = recoveryError;
+                }
+            }
             const err = error instanceof Error ? error : new Error(String(error));
             callRecord.success = false;
             callRecord.error = err;

package/dist/tools/effect/defineTool.d.ts

@@ -22,6 +22,15 @@ export declare function defineTool<S extends z.ZodTypeAny | StandardSchemaV1 | u
     parallelSafe?: boolean;
     idempotencyKey?: (args: InferToolInput<S>) => string;
     execute: (args: InferToolInput<S>, ctx?: ToolContext) => Promise<R> | AsyncIterable<R>;
+    /**
+     * Turns a thrown error into a result the model can act on, instead of a generic failure.
+     * Return a value to recover; rethrow (or omit this) to let the error propagate.
+     *
+     * Runs only for genuine failures — never for a timeout, an abort, an input/output schema
+     * violation, or a control-flow signal, all of which must stay distinguishable from a
+     * result the tool chose to return.
+     */
+    onError?: (error: Error, args: InferToolInput<S>) => Promise<R> | R;
 }): Tool<InferToolInput<S>, R>;
 export declare function toolToAiSdk<TInput = unknown, TOutput = unknown>(def: Tool<TInput, TOutput>): AiTool<TInput, TOutput>;
 export declare function buildToolSet(tools: Record<string, AnyTool>): ToolSet;

package/dist/tools/effect/defineTool.js

@@ -14,6 +14,7 @@ export function defineTool(config) {
         parallelSafe: config.parallelSafe,
         idempotencyKey: config.idempotencyKey,
         execute: config.execute,
+        onError: config.onError,
     };
 }
 export function toolToAiSdk(def) {

package/dist/tools/effect/errors.d.ts

@@ -1,13 +1,10 @@
-/**
- * Thrown by `ctx.tool(...)` when a tool declared `needsApproval: true` is denied
- * by a human (the `__approval` signal resolves with `approved: false`). Catch it
- * inside the calling flow `action` node to route gracefully (e.g. escalate or end).
- */
+/** Thrown when a tool execution exceeds its configured timeout. */
 export declare class ToolTimeoutError extends Error {
     readonly toolName: string;
     readonly timeoutMs: number;
     constructor(toolName: string, timeoutMs: number);
 }
+/** Thrown when a human denies a tool call that requires approval. */
 export declare class ToolApprovalDeniedError extends Error {
     readonly toolName: string;
     readonly by?: string;