@vibesdotdev/tools 0.0.0-stage → 1.0.0-rc.4

package/dist/execution/core.js

@@ -0,0 +1,157 @@
+/**
+ * invokeToolCore — single source of truth for invoking a universal tool.
+ *
+ * This owns the cross-cutting concerns shared by every tool invocation path:
+ * hook-bus emission, descriptor-driven input validation, timeout handling,
+ * beforeExecute rejections, and recovery-hint enrichment.
+ */
+import { CapabilityError } from '@vibesdotdev/kernel';
+import { assertToolAllowedByExecutionBindings } from "../agents/execution-bindings.js";
+import { authorizeToolCall } from "./approval.js";
+import { ToolDescriptorSchema } from "../schemas/runtime/descriptors.js";
+import { ToolInputValidationError, validateToolInputForRuntime } from "./input-validation.js";
+export { ToolInputValidationError, validateToolInput, validateToolInputForRuntime } from "./input-validation.js";
+/** Metadata key used by beforeExecute subscribers to deny a call. */
+export const BEFORE_EXECUTE_REJECT_KEY = 'beforeExecute:reject';
+export async function invokeToolCore(runtime, toolId, input, ctx, options) {
+    assertToolAllowedByExecutionBindings(ctx, toolId);
+    const bus = runtime.hooks('tools/tool');
+    const metadata = new Map();
+    const callId = ctx.callId;
+    const contextBuildResult = await bus.emit('contextBuild', { toolId, callId, input, runtime, metadata });
+    if (contextBuildResult?.failures && contextBuildResult.failures.length > 0) {
+        const first = contextBuildResult.failures[0].error;
+        throw first instanceof Error ? first : new Error(String(first));
+    }
+    const startTime = Date.now();
+    const abort = new AbortController();
+    if (ctx.signal?.aborted) {
+        abort.abort(ctx.signal.reason);
+    }
+    else {
+        ctx.signal?.addEventListener('abort', () => abort.abort(ctx.signal?.reason), { once: true });
+    }
+    const callCtx = { ...ctx, signal: abort.signal };
+    try {
+        let effectiveInput = input;
+        if (!options.skipInputValidation) {
+            const validation = validateToolInputForRuntime(runtime, toolId, input);
+            if (!validation.ok) {
+                await bus.emit('inputValidationFailed', {
+                    toolId,
+                    callId,
+                    input,
+                    issues: validation.issues,
+                    runtime,
+                    metadata
+                });
+                throw new ToolInputValidationError(toolId, validation.issues);
+            }
+            // SAFETY: validateToolInputForRuntime parses and verifies input conforms to tool input schema
+            effectiveInput = validation.value;
+        }
+        const beforeExecuteEvent = {
+            toolId, callId, input: effectiveInput, runtime, metadata
+        };
+        const admission = { open: true };
+        // Inline admission hooks need the runner's trusted identity and progress sink.
+        // Keep credentials and host context out of JSON/spread event projections.
+        Object.defineProperty(beforeExecuteEvent, 'ctx', { value: callCtx });
+        Object.defineProperty(beforeExecuteEvent, 'complete', { value: (result) => {
+                if (!admission.open || admission.completion)
+                    throw new CapabilityError('Tool admission cannot complete this invocation more than once or after admission ends.', 'CONFLICT', { reason: 'tool-preflight-completion-conflict' });
+                const descriptor = runtime.hasKind('tools/tool') ? runtime.assets('tools/tool').descriptor(toolId) : undefined;
+                const output = ToolDescriptorSchema.pick({ schemas: true }).parse(descriptor).schemas.output;
+                admission.completion = { result: output.parse(result) };
+            } });
+        const beforeExecuteResult = await bus.emit('beforeExecute', beforeExecuteEvent);
+        admission.open = false;
+        if (beforeExecuteResult?.failures && beforeExecuteResult.failures.length > 0) {
+            const first = beforeExecuteResult.failures[0].error;
+            throw first instanceof Error ? first : new Error(String(first));
+        }
+        const rejection = metadata.get(BEFORE_EXECUTE_REJECT_KEY);
+        if (rejection !== undefined) {
+            const error = rejection instanceof Error ? rejection : new Error(String(rejection));
+            throw error;
+        }
+        if (callCtx.signal?.aborted) {
+            const reason = callCtx.signal.reason;
+            if (reason instanceof Error)
+                throw reason;
+            throw new CapabilityError('The caller cancelled this tool call before it ran.', 'CANCELLED', {
+                reason: 'tool-call-cancelled'
+            });
+        }
+        let result;
+        if (admission.completion) {
+            result = admission.completion.result;
+        }
+        else {
+            const approval = await authorizeToolCall(runtime, toolId, effectiveInput, callCtx, options.approval);
+            await options.onApproval?.(approval);
+            result = options.timeoutMs && options.timeoutMs > 0
+                ? await withInvocationTimeout(runtime, options.runner(effectiveInput, callCtx), options.timeoutMs, `Tool '${toolId}' execution timed out after ${options.timeoutMs}ms`, abort)
+                : await options.runner(effectiveInput, callCtx);
+        }
+        const durationMs = Date.now() - startTime;
+        const afterExecuteEvent = {
+            toolId,
+            callId,
+            input: effectiveInput,
+            result,
+            durationMs,
+            runtime,
+            metadata
+        };
+        await bus.emit('afterExecute', afterExecuteEvent);
+        // SAFETY: afterExecute subscribers may mutate or redact result in afterExecuteEvent.
+        return afterExecuteEvent.result;
+    }
+    catch (error) {
+        const durationMs = Date.now() - startTime;
+        const typedError = error instanceof Error ? error : new Error(String(error), { cause: error });
+        const recoveryHints = {};
+        await bus.emit('error', {
+            toolId,
+            callId,
+            input,
+            error: typedError,
+            durationMs,
+            runtime,
+            metadata,
+            recoveryHints
+        });
+        if (error instanceof Error) {
+            enrichInvocationError(error, recoveryHints);
+        }
+        throw error;
+    }
+}
+function enrichInvocationError(error, recoveryHints) {
+    // SAFETY: Attaching optional ToolInvocationErrorMetadata fields to the error object.
+    const enriched = error;
+    if (recoveryHints.hint !== undefined && enriched.recoveryHint === undefined) {
+        enriched.recoveryHint = recoveryHints.hint;
+    }
+    if (recoveryHints.retryable !== undefined && enriched.retryable === undefined) {
+        enriched.retryable = recoveryHints.retryable;
+    }
+    return enriched;
+}
+function withInvocationTimeout(runtime, promise, ms, message, abort) {
+    return new Promise((resolve, reject) => {
+        const disarm = runtime.lifecycle.timeout(() => {
+            abort.abort(message);
+            reject(new Error(message));
+        }, ms);
+        promise.then((value) => {
+            disarm();
+            resolve(value);
+        }, (err) => {
+            disarm();
+            reject(err);
+        });
+    });
+}
+//# sourceMappingURL=core.js.map

package/dist/execution/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../src/execution/core.ts"],"names":[],"mappings":"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"}

package/dist/execution/direct-context.d.ts

@@ -0,0 +1,13 @@
+import { type VibesRuntime } from '@vibesdotdev/kernel';
+import type { ToolCallContext } from '@vibesdotdev/kernel/schemas/tool-call';
+/**
+ * Build trusted metadata for a direct tool invocation.
+ *
+ * Authenticated identity and validated provider credentials are projected from
+ * the runtime when available. Local identity-free tools remain usable without
+ * login. Caller-supplied identity and credential keys are always stripped, so
+ * tool input or ad hoc metadata cannot impersonate an actor or inject auth;
+ * tools that require either reject its absence themselves.
+ */
+export declare function buildDirectToolCallContext(runtime: VibesRuntime, base: ToolCallContext): Promise<ToolCallContext>;
+//# sourceMappingURL=direct-context.d.ts.map

package/dist/execution/direct-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"direct-context.d.ts","sourceRoot":"","sources":["../../src/execution/direct-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAoB,MAAM,uCAAuC,CAAC;AAoH/F;;;;;;;;GAQG;AACH,wBAAsB,0BAA0B,CAC/C,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,eAAe,GACnB,OAAO,CAAC,eAAe,CAAC,CAiD1B"}

package/dist/execution/direct-context.js

@@ -0,0 +1,143 @@
+import { CapabilityError } from '@vibesdotdev/kernel';
+import { DiagnosticCheckLineageSchema } from '@vibesdotdev/diagnostics/schemas';
+import { selectUntrustedTraceMetadata } from "../agents/trusted-context.js";
+const FORWARDABLE_AUTH_COOKIES = new Set([
+    'vibes.jwt',
+    'better-auth.session_token',
+    '__Secure-better-auth.session_token',
+    '__Host-better-auth.session_token'
+]);
+function readHeader(headers, name) {
+    if (!headers)
+        return undefined;
+    const entry = Object.entries(headers).find(([key]) => key.toLowerCase() === name);
+    const value = entry?.[1]?.trim();
+    return value && !/[\r\n]/.test(value) ? value : undefined;
+}
+function isNonEmptyString(val) {
+    if (Object.prototype.toString.call(val) !== '[object String]')
+        return false;
+    // SAFETY: Object.prototype.toString check verifies val is a string before accessing string methods.
+    return val.trim().length > 0;
+}
+function selectForwardableAuthHeaders(headers) {
+    const authorization = readHeader(headers, 'authorization');
+    const jwt = authorization?.match(/^Bearer\s+(\S+)$/i)?.[1];
+    const rawCookie = readHeader(headers, 'cookie');
+    const cookies = [];
+    if (rawCookie) {
+        for (const part of rawCookie.split(';')) {
+            const separator = part.indexOf('=');
+            if (separator <= 0)
+                continue;
+            const name = part.slice(0, separator).trim();
+            const value = part.slice(separator + 1).trim();
+            if (FORWARDABLE_AUTH_COOKIES.has(name) && value.length > 0 && !/[;\r\n]/.test(value)) {
+                cookies.push(`${name}=${value}`);
+            }
+        }
+    }
+    const result = {};
+    if (cookies.length > 0) {
+        result.cookie = cookies.join('; ');
+    }
+    if (jwt) {
+        result.jwt = jwt;
+    }
+    return result;
+}
+async function readOptionalStringContext(runtime, contextId) {
+    if (!runtime.hasContext(contextId))
+        return undefined;
+    try {
+        const value = await runtime.context(contextId);
+        return isNonEmptyString(value) ? value : undefined;
+    }
+    catch (error) {
+        if (error instanceof Error && CapabilityError.isAbsenceOf(error, 'context', contextId))
+            return undefined;
+        throw error;
+    }
+}
+async function readValidatedAuth(runtime, userId) {
+    if (!runtime.hasKind('auth/provider'))
+        return {};
+    try {
+        // SAFETY: Runtime query for auth/provider resolves the declared auth provider implementation or null.
+        const provider = (await runtime.query('auth/provider').resolve());
+        if (!provider?.validateCredentials || !provider.getAuthContext)
+            return {};
+        const validation = await provider.validateCredentials();
+        if (validation.valid !== true)
+            return {};
+        const auth = await provider.getAuthContext();
+        if (auth.isAuthenticated !== true)
+            return {};
+        const authUserId = isNonEmptyString(auth.userId) ? auth.userId.trim() : undefined;
+        if (authUserId && authUserId !== userId)
+            return {};
+        return selectForwardableAuthHeaders(auth.headers);
+    }
+    catch (error) {
+        if (error instanceof Error && CapabilityError.isAbsenceOf(error, 'service', 'auth/provider')) {
+            return {};
+        }
+        throw error;
+    }
+}
+/**
+ * Build trusted metadata for a direct tool invocation.
+ *
+ * Authenticated identity and validated provider credentials are projected from
+ * the runtime when available. Local identity-free tools remain usable without
+ * login. Caller-supplied identity and credential keys are always stripped, so
+ * tool input or ad hoc metadata cannot impersonate an actor or inject auth;
+ * tools that require either reject its absence themselves.
+ */
+export async function buildDirectToolCallContext(runtime, base) {
+    const safeMetadata = {
+        ...selectUntrustedTraceMetadata(base.metadata),
+        invocationSurface: 'consumer'
+    };
+    if (base.metadata?.diagnosticLineage !== undefined)
+        safeMetadata.diagnosticLineage = DiagnosticCheckLineageSchema.parse(base.metadata.diagnosticLineage);
+    if (!runtime.hasContext('auth/identity')) {
+        return { ...base, metadata: safeMetadata };
+    }
+    let identity;
+    try {
+        identity = await runtime.context('auth/identity');
+    }
+    catch (error) {
+        if (error instanceof Error && CapabilityError.isAbsenceOf(error, 'context', 'auth/identity')) {
+            return { ...base, metadata: safeMetadata };
+        }
+        throw error;
+    }
+    const userId = identity?.userId;
+    if (identity?.isAuthenticated !== true ||
+        !isNonEmptyString(userId)) {
+        return { ...base, metadata: safeMetadata };
+    }
+    const actorUserId = userId.trim();
+    const orgId = (await readOptionalStringContext(runtime, 'orgId')) ??
+        (await readOptionalStringContext(runtime, 'organizationId'));
+    const auth = await readValidatedAuth(runtime, actorUserId);
+    const metadata = {
+        ...safeMetadata,
+        actorUserId,
+        userId: actorUserId,
+        ...auth,
+        orgId: orgId ?? undefined,
+        organizationId: orgId ?? undefined
+    };
+    const actor = runtime.scope.actor;
+    const sameOrganization = orgId === undefined || actor?.orgId === orgId;
+    if (actor?.userId === actorUserId && sameOrganization && actor.projectId !== undefined)
+        metadata.projectId = actor.projectId;
+    return {
+        ...base,
+        metadata
+    };
+}
+//# sourceMappingURL=direct-context.js.map

package/dist/execution/direct-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"direct-context.js","sourceRoot":"","sources":["../../src/execution/direct-context.ts"],"names":[],"mappings":"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"}

package/dist/execution/execute-tool.d.ts

@@ -0,0 +1,60 @@
+/**
+ * High-level tool execution helper.
+ *
+ * Wraps invokeTool with the common caller-side concerns:
+ *   - generating a stable toolCallId
+ *   - dispatching system tools directly through the runtime
+ *   - resolving custom tools (id prefixed with `custom:`) by fetching their
+ *     code via a caller-provided resolver and invoking the `execute-code`
+ *     system tool
+ *   - normalizing results and errors into the canonical ToolOutput shape
+ *
+ * This helper lives in tools so every app/surface executes tools
+ * through the same canonical path instead of forking the dispatch logic.
+ */
+import { type VibesRuntime } from '@vibesdotdev/kernel';
+import { type JsonValue } from '../schemas/runtime/json.ts';
+import type { ToolOutput } from '../schemas/types.ts';
+export type CustomToolResolver = (customToolId: string) => Promise<{
+    code: string;
+    timeoutMs?: number;
+} | null | undefined>;
+export interface ExecuteToolOptions {
+    /** Tool id. Custom tools are identified by `custom:<uuid>`. */
+    id: string;
+    /** Parsed tool input. */
+    input: Record<string, JsonValue>;
+    /** Runtime to use. Required. */
+    runtime: VibesRuntime;
+    /** Optional workspace path passed to the tool context. */
+    workspacePath?: string;
+    /**
+     * Resolver for custom tool code. Required when executing custom tools.
+     * Returning null/undefined causes an EXECUTION_ERROR.
+     */
+    customToolResolver?: CustomToolResolver;
+    /**
+     * Stamp a verified direct-consumer invocation into the trusted tool context.
+     * Agent callers must leave this unset; model-authored session ids then fail
+     * closed in code-session tools.
+     */
+    invocationSurface?: 'consumer';
+}
+export interface MappedExecuteToolError {
+    code: string;
+    message: string;
+    recoveryHint?: string;
+    retryable?: boolean;
+}
+export interface ExecuteToolError {
+    code: string;
+    message: string;
+    recoveryHint?: string;
+    retryable?: boolean;
+}
+export interface ExecuteToolOutput extends ToolOutput {
+    error?: ExecuteToolError;
+    failure?: unknown;
+}
+export declare function executeTool({ id, input, runtime, workspacePath, customToolResolver, invocationSurface }: ExecuteToolOptions): Promise<ExecuteToolOutput>;
+//# sourceMappingURL=execute-tool.d.ts.map

package/dist/execution/execute-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-tool.d.ts","sourceRoot":"","sources":["../../src/execution/execute-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACN,KAAK,YAAY,EAGjB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAOtD,MAAM,MAAM,kBAAkB,GAAG,CAChC,YAAY,EAAE,MAAM,KAChB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAEtE,MAAM,WAAW,kBAAkB;IAClC,+DAA+D;IAC/D,EAAE,EAAE,MAAM,CAAC;IACX,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACjC,gCAAgC;IAChC,OAAO,EAAE,YAAY,CAAC;IACtB,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,UAAU,CAAC;CAC/B;AAuCD,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AA0CD,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACpD,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,WAAW,CAAC,EACjC,EAAE,EACF,KAAK,EACL,OAAO,EACP,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAyEjD"}

package/dist/execution/execute-tool.js

@@ -0,0 +1,162 @@
+/**
+ * High-level tool execution helper.
+ *
+ * Wraps invokeTool with the common caller-side concerns:
+ *   - generating a stable toolCallId
+ *   - dispatching system tools directly through the runtime
+ *   - resolving custom tools (id prefixed with `custom:`) by fetching their
+ *     code via a caller-provided resolver and invoking the `execute-code`
+ *     system tool
+ *   - normalizing results and errors into the canonical ToolOutput shape
+ *
+ * This helper lives in tools so every app/surface executes tools
+ * through the same canonical path instead of forking the dispatch logic.
+ */
+import { CaughtFailureSchema, valueFreeFailure } from '@vibesdotdev/kernel';
+import { getLogger } from '@vibesdotdev/logging';
+import * as z from 'zod/v4';
+import { JsonValueSchema } from "../schemas/runtime/json.js";
+import { ToolErrorCode } from "../errors/codes.js";
+import { CapabilityTierExceededError } from "./tier-enforcement.errors.js";
+import { ToolInputValidationError } from "./input-validation.js";
+import { invokeTool } from "./invoke.js";
+import { callerFromRuntimeScope } from "./caller-invocation.js";
+function toJsonRecord(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        throw Object.assign(new Error('Tool result is an array; ToolOutput.output requires an object'), {
+            name: 'ToolOutputShapeError'
+        });
+    }
+    if (value instanceof Object) {
+        const parsed = JsonValueSchema.safeParse(value);
+        if (parsed.success &&
+            parsed.data !== null &&
+            parsed.data instanceof Object &&
+            !Array.isArray(parsed.data)) {
+            // SAFETY: parsed.data is a verified non-array JSON object per instanceof and !Array.isArray checks
+            return parsed.data;
+        }
+        throw Object.assign(new Error('Tool result is not a JSON object'), {
+            name: 'ToolOutputShapeError'
+        });
+    }
+    const scalar = JsonValueSchema.safeParse(value);
+    if (scalar.success) {
+        return { value: scalar.data };
+    }
+    throw Object.assign(new Error('Tool result is not JSON-serializable'), {
+        name: 'ToolOutputShapeError'
+    });
+}
+const ErrorMetaSchema = z.object({
+    recoveryHint: z.string().optional(),
+    retryable: z.boolean().optional()
+});
+function mapExecuteToolError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const metaParsed = ErrorMetaSchema.safeParse(error);
+    const recoveryHint = metaParsed.success ? metaParsed.data.recoveryHint : undefined;
+    const retryable = metaParsed.success ? metaParsed.data.retryable : undefined;
+    if (error instanceof ToolInputValidationError) {
+        return {
+            code: ToolErrorCode.VALIDATION_FAILED,
+            message,
+            recoveryHint: recoveryHint ?? 'Fix the listed input issues and retry.',
+            retryable: false
+        };
+    }
+    if (error instanceof CapabilityTierExceededError) {
+        return { code: ToolErrorCode.CAPABILITY_CEILING_DENIED, message, recoveryHint, retryable: false };
+    }
+    if (error instanceof Error && error.name === 'ToolOutputShapeError') {
+        return { code: ToolErrorCode.EXECUTION_FAILED, message, recoveryHint, retryable: false };
+    }
+    if (/not allowed/i.test(message)) {
+        return { code: ToolErrorCode.PERMISSION_DENIED, message, recoveryHint, retryable: false };
+    }
+    if (/requires approval/i.test(message)) {
+        return { code: ToolErrorCode.PERMISSION_DENIED, message, recoveryHint, retryable: false };
+    }
+    if (/timed out/i.test(message)) {
+        return { code: ToolErrorCode.TIMEOUT, message, recoveryHint, retryable: retryable ?? true };
+    }
+    if (/not found/i.test(message)) {
+        return { code: ToolErrorCode.NOT_FOUND, message, recoveryHint, retryable: false };
+    }
+    return { code: ToolErrorCode.EXECUTION_FAILED, message, recoveryHint, retryable };
+}
+export async function executeTool({ id, input, runtime, workspacePath, customToolResolver, invocationSurface }) {
+    const toolCallId = `exec-${crypto.randomUUID()}`;
+    const rt = runtime;
+    const logger = getLogger('tools:execute', rt);
+    const toolLogger = logger.child(id);
+    try {
+        let rawResult;
+        const context = {
+            callId: toolCallId,
+            logger: toolLogger
+        };
+        if (workspacePath) {
+            context.workspacePath = workspacePath;
+        }
+        if (invocationSurface) {
+            const metadata = {};
+            metadata.invocationSurface = invocationSurface;
+            context.metadata = metadata;
+        }
+        // The call runs as the caller this runtime's scope names, so caller
+        // admission sees it like any other surface's call.
+        const caller = await callerFromRuntimeScope(rt);
+        if (caller)
+            context.caller = caller;
+        if (id.startsWith('custom:')) {
+            const customToolId = id.slice(7);
+            const customTool = customToolResolver ? await customToolResolver(customToolId) : null;
+            if (!customTool) {
+                throw new Error(`Custom tool '${customToolId}' not found`);
+            }
+            rawResult = await invokeTool({
+                runtime: rt,
+                toolId: 'execute-code',
+                input: {
+                    code: customTool.code,
+                    input,
+                    timeoutMs: customTool.timeoutMs ?? 5000
+                },
+                ctx: context
+            });
+        }
+        else {
+            rawResult = await invokeTool({ runtime: rt, toolId: id, input, ctx: context });
+        }
+        return {
+            toolCallId,
+            status: 'success',
+            output: toJsonRecord(rawResult)
+        };
+    }
+    catch (error) {
+        logger.error('Tool execution failed', { error });
+        const mapped = mapExecuteToolError(error);
+        const errorPayload = {
+            code: mapped.code,
+            message: mapped.message
+        };
+        if (mapped.recoveryHint) {
+            errorPayload.recoveryHint = mapped.recoveryHint;
+        }
+        if (mapped.retryable !== undefined) {
+            errorPayload.retryable = mapped.retryable;
+        }
+        return {
+            toolCallId,
+            status: 'error',
+            error: errorPayload,
+            failure: valueFreeFailure(CaughtFailureSchema.parse(error))
+        };
+    }
+}
+//# sourceMappingURL=execute-tool.js.map

package/dist/execution/execute-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-tool.js","sourceRoot":"","sources":["../../src/execution/execute-tool.ts"],"names":[],"mappings":"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"}

package/dist/execution/host-bridge-coercion.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Undo host-bridge stringification of nested records, numbers, and booleans.
+ *
+ * Hosts that project `z.record` / open objects as JSON Schema maps often
+ * deliver nested objects as JSON strings and numbers/booleans as decimal or
+ * `"true"`/`"false"` strings. Descriptor schemas stay JSON-Schema-safe
+ * (no `.preprocess` / `.transform`); this walk is the receive-side gate.
+ */
+import type { HostBridgeJsonSchema, HostBridgeValue } from './schemas/host-bridge.ts';
+export declare function coerceHostBridgeInput<T = HostBridgeValue>(jsonSchema: HostBridgeJsonSchema | null | undefined, input: HostBridgeValue): T;
+//# sourceMappingURL=host-bridge-coercion.d.ts.map

package/dist/execution/host-bridge-coercion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-bridge-coercion.d.ts","sourceRoot":"","sources":["../../src/execution/host-bridge-coercion.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAMtF,wBAAgB,qBAAqB,CAAC,CAAC,GAAG,eAAe,EACxD,UAAU,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,EACnD,KAAK,EAAE,eAAe,GACpB,CAAC,CAIH"}