@nylorun/core 0.0.0-bootstrap → 0.1.1-beta

package/dist/definition/from.js

@@ -0,0 +1,135 @@
+import { HarnessError } from "../errors.js";
+import { assembleAgent } from "./assemble.js";
+import { schemaFromJSON } from "./schema-json.js";
+import { deepFreeze } from "../utils/immutable.js";
+/** Rebuild an agent from manifest JSON + in-process implementations (T28). */
+export function agentFrom(json, implementations) {
+    const manifest = normalizeManifest(json);
+    const entries = [];
+    const dynamics = new Map();
+    for (const capability of manifest.capabilities) {
+        const impl = implementations[capability.id] ?? {};
+        const tools = resolveTools(capability, impl.tools);
+        if (capability.beforeModelCall && !impl.beforeModelCall)
+            throw new HarnessError("agent.build-failed", `Missing beforeModelCall implementation for capability '${capability.id}'`);
+        if (capability.afterModelCall && !impl.afterModelCall)
+            throw new HarnessError("agent.build-failed", `Missing afterModelCall implementation for capability '${capability.id}'`);
+        const handle = impl.middleware ??
+            (async (request, next) => {
+                if (tools.length)
+                    request.configuration.tools.set(capability.id, tools.map((tool) => implementations[capability.id]?.tools?.[tool.name] ?? tool));
+                if (capability.instructions)
+                    request.configuration.instructions.set(capability.id, capability.instructions);
+                return next();
+            });
+        entries.push(Object.freeze({
+            id: capability.id,
+            handle,
+            hasMiddleware: impl.middleware !== undefined || capability.hasMiddleware,
+            tools: capability.tools !== undefined
+                ? tools.map((tool) => {
+                    const live = impl.tools?.[tool.name];
+                    if (!live)
+                        throw new HarnessError("agent.build-failed", `Missing tool implementation '${tool.name}' for capability '${capability.id}'`);
+                    return live;
+                })
+                : undefined,
+            contributions: Object.freeze({
+                ...(capability.instructions
+                    ? { instructions: capability.instructions }
+                    : {}),
+                ...(capability.tools
+                    ? {
+                        tools: capability.tools.map((tool) => Object.freeze({
+                            name: tool.name,
+                            ...(tool.description === undefined
+                                ? {}
+                                : { description: tool.description }),
+                        })),
+                    }
+                    : {}),
+            }),
+            ...(capability.beforeModelCall ? { beforeModelCall: true } : {}),
+            ...(capability.afterModelCall ? { afterModelCall: true } : {}),
+        }));
+        dynamics.set(capability.id, {
+            ...(impl.beforeModelCall
+                ? { beforeModelCall: impl.beforeModelCall }
+                : {}),
+            ...(impl.afterModelCall
+                ? { afterModelCall: impl.afterModelCall }
+                : {}),
+            ...(impl.middleware ? { middleware: impl.middleware } : {}),
+        });
+    }
+    const outputSchema = manifest.outputSchema
+        ? schemaFromJSON(manifest.outputSchema)
+        : undefined;
+    const result = assembleAgent(entries, { id: manifest.id, name: manifest.name, outputSchema }, dynamics);
+    if (!result.ok)
+        throw new HarnessError("agent.build-failed", result.diagnostics.map((item) => item.message).join("; "));
+    return result.agent;
+}
+function resolveTools(capability, tools) {
+    if (!capability.tools?.length)
+        return [];
+    return capability.tools.map((tool) => {
+        const live = tools?.[tool.name];
+        if (!live)
+            throw new HarnessError("agent.build-failed", `Missing tool implementation '${tool.name}' for capability '${capability.id}'`);
+        return live;
+    });
+}
+function normalizeManifest(json) {
+    if (!json || typeof json !== "object" || Array.isArray(json))
+        throw new HarnessError("agent.build-failed", "Agent.from requires a manifest object");
+    const value = json;
+    if (typeof value.id !== "string" || !value.id)
+        throw new HarnessError("agent.build-failed", "Manifest id must be a non-empty string");
+    if (typeof value.name !== "string" || !value.name)
+        throw new HarnessError("agent.build-failed", "Manifest name must be a non-empty string");
+    if (!Array.isArray(value.capabilities))
+        throw new HarnessError("agent.build-failed", "Manifest capabilities must be an array");
+    const schemaVersion = value.schemaVersion === undefined ? 2 : value.schemaVersion;
+    if (schemaVersion !== 2)
+        throw new HarnessError("agent.build-failed", `Unsupported manifest schemaVersion ${schemaVersion}`);
+    // Reject top-level model (Runtime-owned).
+    if ("model" in value && value.model !== undefined)
+        throw new HarnessError("agent.build-failed", "Manifest must not include top-level model; Runtime owns model resolution");
+    return deepFreeze({
+        schemaVersion: 2,
+        id: value.id,
+        name: value.name,
+        ...(value.outputSchema && typeof value.outputSchema === "object"
+            ? { outputSchema: value.outputSchema }
+            : {}),
+        capabilities: value.capabilities.map(normalizeCapability),
+    });
+}
+function normalizeCapability(capability) {
+    return Object.freeze({
+        id: capability.id,
+        kind: capability.kind ?? "capability",
+        hasMiddleware: capability.hasMiddleware ?? false,
+        ...(capability.instructions
+            ? { instructions: Object.freeze([...capability.instructions]) }
+            : {}),
+        ...(capability.tools
+            ? { tools: Object.freeze(capability.tools.map(normalizeTool)) }
+            : {}),
+        ...(capability.beforeModelCall ? { beforeModelCall: true } : {}),
+        ...(capability.afterModelCall ? { afterModelCall: true } : {}),
+    });
+}
+function normalizeTool(tool) {
+    return Object.freeze({
+        name: tool.name,
+        ...(tool.description === undefined
+            ? {}
+            : { description: tool.description }),
+        inputSchema: tool.inputSchema,
+        ...(tool.outputSchema === undefined
+            ? {}
+            : { outputSchema: tool.outputSchema }),
+    });
+}

package/dist/definition/helpers.d.ts

@@ -0,0 +1,21 @@
+import type { ModelAdapter } from "../types/model.js";
+import type { StepMiddleware } from "../types/middleware.js";
+import type { ToolDefinition, ToolInputSchema, ToolOutputSchema, ToolSchemaSource } from "../types/tool.js";
+export declare const tool: <InputSchema extends ToolInputSchema, Info = unknown, OutputSchema extends ToolOutputSchema | undefined = undefined>(value: ToolDefinition<InputSchema, Info, OutputSchema>) => ToolDefinition<InputSchema, Info, OutputSchema>;
+/** @deprecated Prefer Runtime model resolution. Capability-disguised `.use({ model })` is not the taught path. */
+export declare const model: <T extends ModelAdapter>(value: T) => T;
+/** @deprecated Prefer `beforeModelCall` / `afterModelCall`. Kept through 1.0. */
+export declare const middleware: <T extends StepMiddleware>(value: T) => T;
+/** Compose a reusable capability bundle (tools, instructions, optional dynamics). */
+export declare function capability<Info = unknown>(declaration: {
+    readonly id: string;
+    readonly tools?: readonly ToolDefinition<any, Info, any>[];
+    readonly instructions?: string | readonly string[];
+    readonly beforeModelCall?: import("../types/dynamics.js").BeforeModelCallFn<Info>;
+    readonly afterModelCall?: import("../types/dynamics.js").AfterModelCallFn<Info>;
+    /** @deprecated Prefer beforeModelCall / afterModelCall. */
+    readonly middleware?: StepMiddleware<Info>;
+    /** @deprecated Model resolution is Runtime-owned; not projected into the manifest. */
+    readonly model?: import("../types/model.js").ModelDirective;
+}): import("../types/middleware.js").CapabilityDeclaration<Info>;
+export type { ToolSchemaSource };

package/dist/definition/helpers.js

@@ -0,0 +1,29 @@
+import { prepareTool } from "./schema.js";
+export const tool = (value) => prepareTool(value);
+/** @deprecated Prefer Runtime model resolution. Capability-disguised `.use({ model })` is not the taught path. */
+export const model = (value) => value;
+/** @deprecated Prefer `beforeModelCall` / `afterModelCall`. Kept through 1.0. */
+export const middleware = (value) => value;
+/** Compose a reusable capability bundle (tools, instructions, optional dynamics). */
+export function capability(declaration) {
+    const instructions = declaration.instructions === undefined
+        ? undefined
+        : typeof declaration.instructions === "string"
+            ? [declaration.instructions]
+            : declaration.instructions;
+    return {
+        id: declaration.id,
+        ...(declaration.tools === undefined ? {} : { tools: declaration.tools }),
+        ...(instructions === undefined ? {} : { instructions }),
+        ...(declaration.beforeModelCall === undefined
+            ? {}
+            : { beforeModelCall: declaration.beforeModelCall }),
+        ...(declaration.afterModelCall === undefined
+            ? {}
+            : { afterModelCall: declaration.afterModelCall }),
+        ...(declaration.middleware === undefined
+            ? {}
+            : { middleware: declaration.middleware }),
+        ...(declaration.model === undefined ? {} : { model: declaration.model }),
+    };
+}

package/dist/definition/implementations.d.ts

@@ -0,0 +1,16 @@
+import type { AfterModelCallFn, BeforeModelCallFn } from "../types/dynamics.js";
+import type { ToolDefinition } from "../types/tool.js";
+import type { StepMiddleware } from "../types/middleware.js";
+/** In-process implementations table keyed by capability id (never serialized). */
+export interface Implementations<Info = unknown> {
+    readonly [capabilityId: string]: {
+        readonly tools?: {
+            readonly [toolName: string]: ToolDefinition<any, Info, any>;
+        };
+        readonly beforeModelCall?: BeforeModelCallFn<Info>;
+        readonly afterModelCall?: AfterModelCallFn<Info>;
+        /** @deprecated Local engine only through 1.0. */
+        readonly middleware?: StepMiddleware<Info>;
+    };
+}
+export declare function emptyImplementations(): Implementations;

package/dist/definition/implementations.js

@@ -0,0 +1,3 @@
+export function emptyImplementations() {
+    return Object.freeze({});
+}

package/dist/definition/manifest.d.ts

@@ -0,0 +1,9 @@
+import type { BoundMiddleware } from "./bound.js";
+import type { AgentManifest } from "../types/manifest.js";
+import type { ToolSchemaSource } from "../types/tool.js";
+export declare function createManifest(input: {
+    id: string;
+    name: string;
+    outputSchema?: ToolSchemaSource;
+    middleware: readonly BoundMiddleware[];
+}): AgentManifest;

package/dist/definition/manifest.js

@@ -0,0 +1,57 @@
+import { bindOutputContract } from "./output-contract.js";
+import { normalizedSchemasFor } from "./schema.js";
+import { deepFreeze } from "../utils/immutable.js";
+export function createManifest(input) {
+    const capabilities = input.middleware.map((item) => projectCapability(item));
+    return deepFreeze({
+        schemaVersion: 2,
+        id: input.id,
+        name: input.name,
+        ...(input.outputSchema === undefined
+            ? {}
+            : {
+                outputSchema: bindOutputContract(input.outputSchema).schema
+                    .jsonSchema,
+            }),
+        capabilities,
+    });
+}
+function projectCapability(item) {
+    const contributions = item.contributions;
+    return {
+        id: item.id,
+        kind: capabilityKind(item),
+        hasMiddleware: item.hasMiddleware,
+        ...(contributions?.instructions === undefined
+            ? {}
+            : { instructions: contributions.instructions }),
+        ...(item.tools === undefined
+            ? {}
+            : { tools: item.tools.map((tool) => projectTool(tool)) }),
+        ...(item.beforeModelCall ? { beforeModelCall: true } : {}),
+        ...(item.afterModelCall ? { afterModelCall: true } : {}),
+        // Deliberately omit capability.model from new manifests (Runtime-owned).
+    };
+}
+function capabilityKind(item) {
+    if (item.id === "agent")
+        return "agent";
+    if (item.contributions !== undefined ||
+        item.beforeModelCall ||
+        item.afterModelCall)
+        return "capability";
+    return "middleware";
+}
+function projectTool(tool) {
+    const schemas = normalizedSchemasFor(tool);
+    return {
+        name: tool.name,
+        ...(tool.description === undefined
+            ? {}
+            : { description: tool.description }),
+        inputSchema: schemas.inputSchema.jsonSchema,
+        ...(schemas.outputSchema === undefined
+            ? {}
+            : { outputSchema: schemas.outputSchema.jsonSchema }),
+    };
+}

package/dist/definition/output-contract.d.ts

@@ -0,0 +1,6 @@
+import type { ToolSchema, ToolSchemaSource } from "../types/tool.js";
+/** Runtime-only validator paired with the portable JSON Schema projected to models. */
+export interface TurnOutputContract {
+    readonly schema: ToolSchema<unknown>;
+}
+export declare function bindOutputContract(source: ToolSchemaSource): TurnOutputContract;

package/dist/definition/output-contract.js

@@ -0,0 +1,12 @@
+import { HarnessError, isHarnessError } from "../errors.js";
+import { normalizeSchema } from "./schema.js";
+export function bindOutputContract(source) {
+    try {
+        return Object.freeze({ schema: normalizeSchema(source, "output") });
+    }
+    catch (cause) {
+        if (isHarnessError(cause))
+            throw new HarnessError("output.invalid-schema", cause.message, { cause });
+        throw new HarnessError("output.invalid-schema", String(cause), { cause });
+    }
+}

package/dist/definition/schema-json.d.ts

@@ -0,0 +1,3 @@
+import type { JsonObject } from "../types/shared.js";
+/** Unsupported JSON Schema constructs fail closed during definition loading. */
+export declare function schemaFromJSON(jsonSchema: JsonObject): import("../define.js").ToolSchema<unknown>;

package/dist/definition/schema-json.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { defineSchema } from "./schema.js";
+/** Unsupported JSON Schema constructs fail closed during definition loading. */
+export function schemaFromJSON(jsonSchema) {
+    const schema = z.fromJSONSchema(jsonSchema);
+    return defineSchema({
+        jsonSchema,
+        validate(value) {
+            const result = schema.safeParse(value);
+            return result.success
+                ? { ok: true, value: result.data }
+                : {
+                    ok: false,
+                    issues: result.error.issues.map((issue) => ({
+                        path: issue.path.filter((v) => typeof v === "string" || typeof v === "number"),
+                        code: issue.code,
+                        message: issue.message,
+                    })),
+                };
+        },
+    });
+}

package/dist/definition/schema.d.ts

@@ -0,0 +1,16 @@
+import type { ToolDefinition, ToolSchema, ToolSchemaSource } from "../types/tool.js";
+export type { SchemaValidation } from "../types/tool.js";
+interface NormalizedToolSchemas {
+    readonly inputSchema: ToolSchema<unknown>;
+    readonly outputSchema?: ToolSchema<unknown>;
+}
+/** Creates a portable, explicitly validated schema source from raw JSON Schema. */
+export declare function defineSchema<T>(value: ToolSchema<T>): ToolSchema<T>;
+/** Eagerly prepares a definition authored through Harness's tool() helper. */
+export declare function prepareTool<T extends ToolDefinition>(definition: T): T;
+/** Resolves `input`/`output`/`run` aliases onto the legacy field names. */
+export declare function normalizeToolDefinition(definition: ToolDefinition): ToolDefinition;
+/** Returns cached normalized contracts, preparing raw definitions on first bind. */
+export declare function normalizedSchemasFor(definition: ToolDefinition): NormalizedToolSchemas;
+/** Converts an accepted tool schema source into Harness's immutable runtime representation. */
+export declare function normalizeSchema<T>(source: ToolSchemaSource<T>, role: "input" | "output"): ToolSchema<T>;

package/dist/definition/schema.js

@@ -0,0 +1,281 @@
+import { z } from "zod";
+import { HarnessError } from "../errors.js";
+import { copyJsonObject } from "../utils/immutable.js";
+const preparedSchemas = new WeakMap();
+/** Creates a portable, explicitly validated schema source from raw JSON Schema. */
+export function defineSchema(value) {
+    if (!value ||
+        typeof value !== "object" ||
+        typeof value.validate !== "function")
+        throw new HarnessError("tool.invalid-schema", "Tool schema must provide validate()");
+    return Object.freeze({
+        jsonSchema: copyJsonObject(value.jsonSchema, "tool schema jsonSchema"),
+        validate: value.validate.bind(value),
+    });
+}
+/** Eagerly prepares a definition authored through Harness's tool() helper. */
+export function prepareTool(definition) {
+    const normalized = normalizeToolDefinition(definition);
+    normalizedSchemasFor(normalized);
+    return normalized;
+}
+/** Resolves `input`/`output`/`run` aliases onto the legacy field names. */
+export function normalizeToolDefinition(definition) {
+    const alreadyCanonical = definition.inputSchema !== undefined &&
+        typeof definition.execute === "function" &&
+        definition.input === undefined &&
+        definition.output === undefined &&
+        definition.run === undefined;
+    if (alreadyCanonical)
+        return definition;
+    const inputSchema = definition.inputSchema ?? definition.input;
+    const outputSchema = definition.outputSchema ?? definition.output;
+    const execute = definition.execute ?? definition.run;
+    if (!inputSchema)
+        throw new HarnessError("tool.invalid-schema", `Tool '${definition.name}' must provide input or inputSchema`);
+    if (typeof execute !== "function")
+        throw new HarnessError("tool.invalid", `Tool '${definition.name}' must provide run() or execute()`);
+    return {
+        name: definition.name,
+        ...(definition.description === undefined
+            ? {}
+            : { description: definition.description }),
+        inputSchema,
+        ...(outputSchema === undefined ? {} : { outputSchema }),
+        execute,
+        ...(definition.approval === undefined
+            ? {}
+            : { approval: definition.approval }),
+        ...(definition.effects === undefined
+            ? {}
+            : { effects: definition.effects }),
+    };
+}
+/** Returns cached normalized contracts, preparing raw definitions on first bind. */
+export function normalizedSchemasFor(definition) {
+    const cached = preparedSchemas.get(definition);
+    if (cached)
+        return cached;
+    const prepared = normalizeToolDefinition(definition);
+    const cachedPrepared = prepared !== definition ? preparedSchemas.get(prepared) : undefined;
+    if (cachedPrepared) {
+        preparedSchemas.set(definition, cachedPrepared);
+        return cachedPrepared;
+    }
+    if (!prepared.inputSchema)
+        throw new HarnessError("tool.invalid-schema", `Tool '${prepared.name}' is missing inputSchema`);
+    const normalized = Object.freeze({
+        inputSchema: normalizeSchema(prepared.inputSchema, "input"),
+        ...(prepared.outputSchema === undefined
+            ? {}
+            : { outputSchema: normalizeSchema(prepared.outputSchema, "output") }),
+    });
+    preparedSchemas.set(prepared, normalized);
+    if (definition !== prepared)
+        preparedSchemas.set(definition, normalized);
+    return normalized;
+}
+/** Converts an accepted tool schema source into Harness's immutable runtime representation. */
+export function normalizeSchema(source, role) {
+    const normalized = isZodSchema(source)
+        ? normalizeZodSchema(source, role)
+        : isStandardSchema(source)
+            ? normalizeStandardSchema(source, role)
+            : isToolSchema(source)
+                ? normalizeExplicitSchema(source)
+                : undefined;
+    if (!normalized)
+        throw new HarnessError("tool.invalid-schema", "Tool schema must be a Zod schema, synchronous Standard Schema with JSON Schema conversion, or defineSchema() contract");
+    if (role === "input" && normalized.jsonSchema.type !== "object")
+        throw new HarnessError("tool.invalid-schema", "Tool inputSchema JSON Schema root type must be object");
+    return normalized;
+}
+function normalizeZodSchema(source, role) {
+    if (hasDeclaredAsyncWork(source))
+        throw new HarnessError("tool.invalid-schema", "Tool schema must validate synchronously");
+    let jsonSchema;
+    try {
+        jsonSchema = copyJsonObject(z.toJSONSchema(source, { target: "draft-07" }), `tool.${role}Schema.jsonSchema`);
+    }
+    catch (error) {
+        throw new HarnessError("tool.invalid-schema", `Tool ${role}Schema must convert to JSON Schema: ${message(error)}`, { cause: error });
+    }
+    return Object.freeze({
+        jsonSchema,
+        validate(value) {
+            try {
+                const result = source.safeParse(value);
+                if (result.success)
+                    return { ok: true, value: result.data };
+                return {
+                    ok: false,
+                    issues: Object.freeze(result.error.issues.map((entry) => issue(entry.path.filter(isPathSegment), entry.code, entry.message))),
+                };
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    issues: [issue([], "schema_error", synchronousIssue(error))],
+                };
+            }
+        },
+    });
+}
+function normalizeStandardSchema(source, role) {
+    let jsonSchema;
+    try {
+        jsonSchema = copyJsonObject(role === "input"
+            ? source["~standard"].jsonSchema.input()
+            : source["~standard"].jsonSchema.output(), `tool.${role}Schema.jsonSchema`);
+    }
+    catch (error) {
+        throw new HarnessError("tool.invalid-schema", `Tool ${role}Schema must convert to JSON Schema: ${message(error)}`, { cause: error });
+    }
+    return Object.freeze({
+        jsonSchema,
+        validate(value) {
+            try {
+                const result = source["~standard"].validate(value);
+                if (isPromiseLike(result))
+                    return {
+                        ok: false,
+                        issues: [
+                            issue([], "async_validation", "Schema validation must be synchronous"),
+                        ],
+                    };
+                if (result &&
+                    typeof result === "object" &&
+                    "issues" in result &&
+                    result.issues)
+                    return {
+                        ok: false,
+                        issues: Object.freeze(result.issues.map(standardIssue)),
+                    };
+                if (result && typeof result === "object" && "value" in result)
+                    return { ok: true, value: result.value };
+                return {
+                    ok: false,
+                    issues: [
+                        issue([], "schema_error", "Standard Schema returned an invalid result"),
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    issues: [issue([], "schema_error", synchronousIssue(error))],
+                };
+            }
+        },
+    });
+}
+function normalizeExplicitSchema(source) {
+    return Object.freeze({
+        jsonSchema: copyJsonObject(source.jsonSchema, "tool schema jsonSchema"),
+        validate(value) {
+            try {
+                const result = source.validate(value);
+                if (isPromiseLike(result))
+                    return {
+                        ok: false,
+                        issues: [
+                            issue([], "async_validation", "Schema validation must be synchronous"),
+                        ],
+                    };
+                if (!result ||
+                    typeof result !== "object" ||
+                    typeof result.ok !== "boolean")
+                    return {
+                        ok: false,
+                        issues: [
+                            issue([], "schema_error", "Tool schema returned an invalid result"),
+                        ],
+                    };
+                if (result.ok)
+                    return { ok: true, value: result.value };
+                return {
+                    ok: false,
+                    issues: Object.freeze(result.issues.map(normalizeIssue)),
+                };
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    issues: [issue([], "schema_error", synchronousIssue(error))],
+                };
+            }
+        },
+    });
+}
+function isZodSchema(value) {
+    return value instanceof z.ZodType;
+}
+function isStandardSchema(value) {
+    if (!value || typeof value !== "object" || !("~standard" in value))
+        return false;
+    const standard = value["~standard"];
+    if (!standard || typeof standard !== "object")
+        return false;
+    const record = standard;
+    if (typeof record.validate !== "function" ||
+        !record.jsonSchema ||
+        typeof record.jsonSchema !== "object")
+        return false;
+    const jsonSchema = record.jsonSchema;
+    return (typeof jsonSchema.input === "function" &&
+        typeof jsonSchema.output === "function");
+}
+function isToolSchema(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        "jsonSchema" in value &&
+        "validate" in value &&
+        typeof value.validate === "function");
+}
+/** Zod exposes declared checks in its stable v4 definition graph; reject async checks before a run. */
+function hasDeclaredAsyncWork(schema) {
+    return visitDefinition(schema._zod?.def, new Set());
+}
+function visitDefinition(value, seen) {
+    if (typeof value === "function")
+        return value.constructor.name === "AsyncFunction";
+    if (!value || typeof value !== "object")
+        return false;
+    if (seen.has(value))
+        return false;
+    seen.add(value);
+    const nestedDefinition = value._zod?.def;
+    if (nestedDefinition !== undefined && nestedDefinition !== value)
+        return visitDefinition(nestedDefinition, seen);
+    for (const item of Object.values(value)) {
+        if (visitDefinition(item, seen))
+            return true;
+    }
+    return false;
+}
+function standardIssue(value) {
+    return issue(value.path?.filter(isPathSegment) ?? [], value.code ?? "invalid", value.message ?? "Invalid value");
+}
+function normalizeIssue(value) {
+    return issue(value.path?.filter(isPathSegment) ?? [], value.code ?? "invalid", value.message ?? "Invalid value");
+}
+function issue(path, code, text) {
+    return Object.freeze({ path: Object.freeze([...path]), code, message: text });
+}
+function isPathSegment(value) {
+    return typeof value === "string" || typeof value === "number";
+}
+function isPromiseLike(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        typeof value.then === "function");
+}
+function synchronousIssue(error) {
+    const reason = message(error);
+    return reason.includes("Promise during synchronous parse")
+        ? "Schema validation must be synchronous"
+        : reason;
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/definition/tool-error.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Thrown from a tool `run` / `execute` to produce a failed tool result.
+ * Prefer this over returning `{ kind: "failed" }` in new code.
+ */
+export declare class ToolError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function isToolError(error: unknown): error is ToolError;

package/dist/definition/tool-error.js

@@ -0,0 +1,20 @@
+const errorBrand = Symbol.for("@nylorun/core/ToolError");
+/**
+ * Thrown from a tool `run` / `execute` to produce a failed tool result.
+ * Prefer this over returning `{ kind: "failed" }` in new code.
+ */
+export class ToolError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ToolError";
+        Object.defineProperty(this, errorBrand, { value: true });
+        this.code = code;
+    }
+}
+export function isToolError(error) {
+    return (error instanceof ToolError ||
+        (typeof error === "object" &&
+            error !== null &&
+            error[errorBrand] === true));
+}