@calliopelabs/ui 0.13.0 → 0.14.0

package/dist/agent/engine.d.ts

@@ -0,0 +1,41 @@
+/**
+ * An engine runs an AG-UI agent for the controller: it starts runs, executes
+ * the browser's tools and decides on follow-up runs. Two ship: the direct
+ * engine here, over any `@ag-ui/client` agent (an `HttpAgent` on a plain
+ * AG-UI endpoint), and the CopilotKit engine (`@calliopelabs/ui/agent/copilotkit`),
+ * which hands the same work to CopilotKit's core. The controller reads the
+ * agent's events either way, so the conversation looks the same.
+ */
+import type { AbstractAgent } from "@ag-ui/client";
+import type { Context, ResumeEntry } from "@ag-ui/core";
+import { type AgentTool } from "./tool.js";
+/** Runs a tool call for an engine, with validation and human-in-the-loop waiting. */
+export type ToolInvoker = (tool: AgentTool, args: unknown, call: {
+    toolCallId: string;
+    signal: AbortSignal;
+}) => Promise<unknown>;
+export interface EngineRunInput {
+    forwardedProps?: Record<string, unknown>;
+    /** Answers to the previous run's interrupts. */
+    resume?: ResumeEntry[];
+}
+export interface AgentEngine {
+    readonly agent: AbstractAgent;
+    /** Runs until the agent is done: frontend tool calls answered, follow-ups made. */
+    run(input: EngineRunInput): Promise<void>;
+    /** Stops the run in flight and any tool it is waiting on. */
+    stop(): void;
+    /** The tools the agent may call now; the controller calls this whenever they change. */
+    setTools(tools: readonly AgentTool[]): void;
+    /** The context (readables) the next run carries. */
+    setContext(context: readonly Context[]): void;
+    /** Lets go of everything the engine registered. */
+    dispose(): void;
+}
+/**
+ * The engine for a plain AG-UI agent. Each run sends the tools and context;
+ * when the agent calls a browser tool, the engine runs it, adds the result to
+ * the agent's messages and runs again (unless the tool says `followUp: false`).
+ * A run that ends on an interrupt stops there: the person's answer resumes it.
+ */
+export declare function createDirectEngine(agent: AbstractAgent, invoke: ToolInvoker): AgentEngine;

package/dist/agent/engine.js

@@ -0,0 +1,93 @@
+import { toolJsonSchema, toolResultText } from "./tool.js";
+/** Runs past this many follow-ups in one turn are a loop, not a conversation. */
+const MAX_FOLLOW_UPS = 8;
+/**
+ * The engine for a plain AG-UI agent. Each run sends the tools and context;
+ * when the agent calls a browser tool, the engine runs it, adds the result to
+ * the agent's messages and runs again (unless the tool says `followUp: false`).
+ * A run that ends on an interrupt stops there: the person's answer resumes it.
+ */
+export function createDirectEngine(agent, invoke) {
+    let tools = [];
+    let context = [];
+    let aborter = null;
+    const answered = (toolCallId) => agent.messages.some((m) => m.role === "tool" && m.toolCallId === toolCallId);
+    return {
+        agent,
+        async run({ forwardedProps, resume }) {
+            aborter?.abort();
+            const own = new AbortController();
+            aborter = own;
+            let params = { resume };
+            try {
+                for (let turn = 0; turn <= MAX_FOLLOW_UPS; turn++) {
+                    const offered = tools.filter((t) => t.available !== false);
+                    const { newMessages } = await agent.runAgent({
+                        ...params,
+                        tools: offered.map((t) => ({
+                            name: t.name,
+                            description: t.description ?? "",
+                            parameters: toolJsonSchema(t),
+                        })),
+                        context: [...context],
+                        ...(forwardedProps ? { forwardedProps } : {}),
+                    });
+                    if (own.signal.aborted || agent.pendingInterrupts.length > 0)
+                        return;
+                    const calls = newMessages.flatMap((m) => m.role === "assistant" ? (m.toolCalls ?? []) : []);
+                    let again = false;
+                    for (const call of calls) {
+                        const tool = offered.find((t) => t.name === call.function.name);
+                        if (!tool || answered(call.id))
+                            continue;
+                        let content;
+                        let error;
+                        try {
+                            const args = call.function.arguments ? JSON.parse(call.function.arguments) : {};
+                            content = toolResultText(await invoke(tool, args, { toolCallId: call.id, signal: own.signal }));
+                        }
+                        catch (e) {
+                            if (own.signal.aborted)
+                                return;
+                            error = e instanceof Error ? e.message : String(e);
+                            content = `Error: ${error}`;
+                        }
+                        if (own.signal.aborted)
+                            return;
+                        agent.addMessage({
+                            id: `${call.id}:result`,
+                            role: "tool",
+                            toolCallId: call.id,
+                            content,
+                            ...(error ? { error } : {}),
+                        });
+                        if (tool.followUp !== false)
+                            again = true;
+                    }
+                    if (!again)
+                        return;
+                    params = {};
+                }
+            }
+            finally {
+                if (aborter === own)
+                    aborter = null;
+            }
+        },
+        stop() {
+            aborter?.abort();
+            aborter = null;
+            if (agent.isRunning)
+                agent.abortRun();
+        },
+        setTools(next) {
+            tools = next;
+        },
+        setContext(next) {
+            context = next;
+        },
+        dispose() {
+            this.stop();
+        },
+    };
+}

package/dist/agent/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@calliopelabs/ui/agent`: one embedded agent for every Calliope AI product,
+ * over the AG-UI protocol, drawn with the chat kit. Opt-in: it needs
+ * `@ag-ui/client`, which the package's main entry never loads. For a
+ * CopilotKit runtime, see `@calliopelabs/ui/agent/copilotkit`.
+ */
+export { AgentController, agentId, type AgentContextEntry, type AgentControllerOptions, type AgentSnapshot, type AgentSuggestion, type AgentThread, type SendOptions, } from "./controller.js";
+export { createDirectEngine, type AgentEngine, type EngineRunInput, type ToolInvoker, } from "./engine.js";
+export { defineTool, isStandardSchema, toolJsonSchema, toolResultText, toolStandardSchema, validateToolArgs, type AgentTool, type AgentToolContext, type AgentToolRenderProps, type JsonSchema, type StandardSchemaV1, } from "./tool.js";
+export { CalliopeAgentProvider, useAgentController, useAgentReadable, useAgentSuggestions, useAgentTool, useCalliopeAgent, type CalliopeAgentApi, type CalliopeAgentOptions, type CalliopeAgentProviderProps, } from "./AgentProvider.js";
+export { createMockAgent, textEvents, toolCallEvents, type MockAgentOptions, type MockTurn, } from "./mock.js";
+export { AgentChat, NewConversationButton, type AgentChatProps } from "./AgentChat.js";
+export { AgentLauncher, type AgentLauncherProps } from "./AgentLauncher.js";
+export { CalliopeAgent, type CalliopeAgentMode, type CalliopeAgentProps } from "./CalliopeAgent.js";
+export { shortcutLabel, useMediaQuery, useOpenState, useShortcut } from "./surface.js";

package/dist/agent/index.js

@@ -0,0 +1,15 @@
+/**
+ * `@calliopelabs/ui/agent`: one embedded agent for every Calliope AI product,
+ * over the AG-UI protocol, drawn with the chat kit. Opt-in: it needs
+ * `@ag-ui/client`, which the package's main entry never loads. For a
+ * CopilotKit runtime, see `@calliopelabs/ui/agent/copilotkit`.
+ */
+export { AgentController, agentId, } from "./controller.js";
+export { createDirectEngine, } from "./engine.js";
+export { defineTool, isStandardSchema, toolJsonSchema, toolResultText, toolStandardSchema, validateToolArgs, } from "./tool.js";
+export { CalliopeAgentProvider, useAgentController, useAgentReadable, useAgentSuggestions, useAgentTool, useCalliopeAgent, } from "./AgentProvider.js";
+export { createMockAgent, textEvents, toolCallEvents, } from "./mock.js";
+export { AgentChat, NewConversationButton } from "./AgentChat.js";
+export { AgentLauncher } from "./AgentLauncher.js";
+export { CalliopeAgent } from "./CalliopeAgent.js";
+export { shortcutLabel, useMediaQuery, useOpenState, useShortcut } from "./surface.js";

package/dist/agent/mock.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A mock AG-UI agent for Storybook and tests: a real `@ag-ui/client`
+ * `HttpAgent` whose fetch is answered from a script instead of the network,
+ * as a server-sent event stream. The client's own parser, verifier and
+ * message bookkeeping run exactly as they do against a live endpoint.
+ */
+import { HttpAgent } from "@ag-ui/client";
+import { type Message, type RunAgentInput } from "@ag-ui/core";
+import type { AgUiEvent } from "../chat/model.js";
+/** What the mock answers one run with: the events, without the run's start and finish. */
+export type MockTurn = readonly AgUiEvent[] | ((input: RunAgentInput, turn: number) => readonly AgUiEvent[]);
+export interface MockAgentOptions {
+    /**
+     * One entry per run, in order; the last repeats. A function sees the run's
+     * input (messages, tools, context, resume) and the run's index.
+     */
+    turns: readonly MockTurn[];
+    /** Pause between events, in ms; 0 for tests. Defaults to 30. */
+    delay?: number;
+    threadId?: string;
+    initialMessages?: Message[];
+    initialState?: unknown;
+    /** Every request's input, for a test to read. */
+    onRequest?: (input: RunAgentInput) => void;
+}
+/** An agent that answers from `turns`, streaming each event as SSE. */
+export declare function createMockAgent({ turns, delay, threadId, initialMessages, initialState, onRequest, }: MockAgentOptions): HttpAgent;
+/** An assistant's streamed reply, in `chunks`, as the events that make it. */
+export declare function textEvents(messageId: string, ...chunks: string[]): AgUiEvent[];
+/** A tool call with its arguments, optionally with a result (a backend tool). */
+export declare function toolCallEvents(toolCallId: string, name: string, args: unknown, options?: {
+    parentMessageId?: string;
+    result?: unknown;
+}): AgUiEvent[];

package/dist/agent/mock.js

@@ -0,0 +1,112 @@
+/**
+ * A mock AG-UI agent for Storybook and tests: a real `@ag-ui/client`
+ * `HttpAgent` whose fetch is answered from a script instead of the network,
+ * as a server-sent event stream. The client's own parser, verifier and
+ * message bookkeeping run exactly as they do against a live endpoint.
+ */
+import { HttpAgent } from "@ag-ui/client";
+import { EventType } from "@ag-ui/core";
+const encoder = new TextEncoder();
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted)
+        return reject(new DOMException("Aborted", "AbortError"));
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+        clearTimeout(timer);
+        reject(new DOMException("Aborted", "AbortError"));
+    }, { once: true });
+});
+/** Wraps a turn's events in its run's start and, unless they end it, its finish. */
+function framed(input, events) {
+    const ends = events.some((e) => e.type === EventType.RUN_FINISHED || e.type === EventType.RUN_ERROR);
+    return [
+        { type: EventType.RUN_STARTED, threadId: input.threadId, runId: input.runId },
+        ...events,
+        ...(ends
+            ? []
+            : [
+                {
+                    type: EventType.RUN_FINISHED,
+                    threadId: input.threadId,
+                    runId: input.runId,
+                },
+            ]),
+    ];
+}
+/** An agent that answers from `turns`, streaming each event as SSE. */
+export function createMockAgent({ turns, delay = 30, threadId, initialMessages, initialState, onRequest, }) {
+    let turn = 0;
+    const fetch = async (_url, init) => {
+        const input = JSON.parse(String(init.body));
+        onRequest?.(input);
+        const index = turn++;
+        const script = turns[Math.min(index, turns.length - 1)] ?? [];
+        const events = framed(input, typeof script === "function" ? script(input, index) : script);
+        const signal = init.signal;
+        const body = new ReadableStream({
+            async start(controller) {
+                try {
+                    for (const event of events) {
+                        if (delay > 0)
+                            await sleep(delay, signal);
+                        else
+                            await Promise.resolve();
+                        if (signal?.aborted)
+                            throw new DOMException("Aborted", "AbortError");
+                        controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
+                    }
+                    controller.close();
+                }
+                catch (error) {
+                    controller.error(error);
+                }
+            },
+        });
+        return new Response(body, {
+            status: 200,
+            headers: { "content-type": "text/event-stream" },
+        });
+    };
+    return new HttpAgent({
+        url: "https://agent.invalid/agui",
+        fetch,
+        ...(threadId ? { threadId } : {}),
+        ...(initialMessages ? { initialMessages } : {}),
+        ...(initialState !== undefined ? { initialState: initialState } : {}),
+    });
+}
+/** An assistant's streamed reply, in `chunks`, as the events that make it. */
+export function textEvents(messageId, ...chunks) {
+    return [
+        { type: EventType.TEXT_MESSAGE_START, messageId, role: "assistant" },
+        ...chunks.map((delta) => ({
+            type: EventType.TEXT_MESSAGE_CONTENT,
+            messageId,
+            delta,
+        })),
+        { type: EventType.TEXT_MESSAGE_END, messageId },
+    ];
+}
+/** A tool call with its arguments, optionally with a result (a backend tool). */
+export function toolCallEvents(toolCallId, name, args, options = {}) {
+    return [
+        {
+            type: EventType.TOOL_CALL_START,
+            toolCallId,
+            toolCallName: name,
+            ...(options.parentMessageId ? { parentMessageId: options.parentMessageId } : {}),
+        },
+        { type: EventType.TOOL_CALL_ARGS, toolCallId, delta: JSON.stringify(args) },
+        { type: EventType.TOOL_CALL_END, toolCallId },
+        ...(options.result === undefined
+            ? []
+            : [
+                {
+                    type: EventType.TOOL_CALL_RESULT,
+                    messageId: `${toolCallId}:result`,
+                    toolCallId,
+                    content: typeof options.result === "string" ? options.result : JSON.stringify(options.result),
+                },
+            ]),
+    ];
+}

package/dist/agent/surface.d.ts

@@ -0,0 +1,30 @@
+/**
+ * An open state that is controlled (`open`), remembered per person in this
+ * browser (`persistKey`), or held here. The server renders `defaultOpen`; the
+ * client applies the saved state after hydration, without a mismatch, and a
+ * change in one tab reaches the others.
+ */
+export declare function useOpenState({ open, defaultOpen, onOpenChange, persistKey, }: {
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    persistKey?: string;
+}): readonly [boolean, (open: boolean) => void];
+/** A shortcut as given: "mod+/" (Cmd on a Mac, Ctrl elsewhere) or a single key ("]"). */
+export interface ParsedShortcut {
+    mod: boolean;
+    key: string;
+}
+export declare function parseShortcut(shortcut: string): ParsedShortcut;
+/** The shortcut as people read it on this machine ("⌘/", "Ctrl+/"). */
+export declare function shortcutLabel(shortcut: string): string;
+/** The shortcut in `aria-keyshortcuts` form. */
+export declare function shortcutAria(shortcut: string): string;
+/**
+ * Calls `onPress` on the shortcut, anywhere in the page. A modified shortcut
+ * works while typing (the assistant opens from the middle of a form); a bare
+ * key does not, and neither works while a modal dialog holds the keyboard.
+ */
+export declare function useShortcut(shortcut: string | false | undefined, onPress: () => void): void;
+/** Whether a media query matches; the server and the first render say `serverValue`. */
+export declare function useMediaQuery(query: string, serverValue?: boolean): boolean;

package/dist/agent/surface.js

@@ -0,0 +1,90 @@
+"use client";
+import * as React from "react";
+import { readLocal, subscribeLocal, writeLocal } from "../lib/local-store.js";
+/**
+ * An open state that is controlled (`open`), remembered per person in this
+ * browser (`persistKey`), or held here. The server renders `defaultOpen`; the
+ * client applies the saved state after hydration, without a mismatch, and a
+ * change in one tab reaches the others.
+ */
+export function useOpenState({ open, defaultOpen = false, onOpenChange, persistKey, }) {
+    const [own, setOwn] = React.useState(defaultOpen);
+    const saved = React.useSyncExternalStore(subscribeLocal, () => (persistKey ? readLocal(persistKey) : null), () => null);
+    const current = open ?? (persistKey && saved !== null ? saved === "1" : persistKey ? defaultOpen : own);
+    const set = React.useCallback((next) => {
+        if (open === undefined) {
+            if (persistKey)
+                writeLocal(persistKey, next ? "1" : "0");
+            else
+                setOwn(next);
+        }
+        onOpenChange?.(next);
+    }, [open, persistKey, onOpenChange]);
+    return [current, set];
+}
+export function parseShortcut(shortcut) {
+    const mod = shortcut.toLowerCase().startsWith("mod+");
+    return { mod, key: mod ? shortcut.slice(4) : shortcut };
+}
+const isMac = () => typeof navigator !== "undefined" && /mac|iphone|ipad/i.test(navigator.platform || "");
+/** The shortcut as people read it on this machine ("⌘/", "Ctrl+/"). */
+export function shortcutLabel(shortcut) {
+    const { mod, key } = parseShortcut(shortcut);
+    if (!mod)
+        return key;
+    return isMac() ? `⌘${key}` : `Ctrl+${key}`;
+}
+/** The shortcut in `aria-keyshortcuts` form. */
+export function shortcutAria(shortcut) {
+    const { mod, key } = parseShortcut(shortcut);
+    return mod ? `Meta+${key} Control+${key}` : key;
+}
+function typing(target) {
+    if (!(target instanceof HTMLElement))
+        return false;
+    return target.isContentEditable || ["INPUT", "TEXTAREA", "SELECT"].includes(target.tagName);
+}
+/**
+ * Calls `onPress` on the shortcut, anywhere in the page. A modified shortcut
+ * works while typing (the assistant opens from the middle of a form); a bare
+ * key does not, and neither works while a modal dialog holds the keyboard.
+ */
+export function useShortcut(shortcut, onPress) {
+    const latest = React.useRef(onPress);
+    React.useEffect(() => {
+        latest.current = onPress;
+    });
+    React.useEffect(() => {
+        if (!shortcut)
+            return;
+        const { mod, key } = parseShortcut(shortcut);
+        const onKey = (event) => {
+            if (event.defaultPrevented || event.isComposing || event.altKey)
+                return;
+            if (event.key !== key)
+                return;
+            const modified = event.metaKey || event.ctrlKey;
+            if (mod !== modified)
+                return;
+            if (!mod && typing(event.target))
+                return;
+            const target = event.target instanceof HTMLElement ? event.target : null;
+            if (target?.closest("[aria-modal='true'], [role='alertdialog']"))
+                return;
+            event.preventDefault();
+            latest.current();
+        };
+        window.addEventListener("keydown", onKey);
+        return () => window.removeEventListener("keydown", onKey);
+    }, [shortcut]);
+}
+/** Whether a media query matches; the server and the first render say `serverValue`. */
+export function useMediaQuery(query, serverValue = true) {
+    return React.useSyncExternalStore((onChange) => {
+        if (typeof window.matchMedia !== "function")
+            return () => { };
+        const list = window.matchMedia(query);
+        list.addEventListener("change", onChange);
+        return () => list.removeEventListener("change", onChange);
+    }, () => typeof window.matchMedia === "function" ? window.matchMedia(query).matches : serverValue, () => serverValue);
+}

package/dist/agent/tool.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Frontend tools: what the agent may call in the browser, typed once. The
+ * parameters are a Standard Schema (zod 3.25+ and 4, valibot, arktype), which
+ * types the handler's arguments and validates them, or a plain JSON Schema
+ * with the argument type given as a type parameter. Pure: no React, no
+ * network, so a Server Component can import a tool's definition.
+ */
+import type * as React from "react";
+import type { ChatToolCall } from "../chat/model.js";
+/** The Standard Schema v1 interface (standardschema.dev), inlined so no schema library is a dependency. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        } | undefined;
+        /** Standard JSON Schema v1, when the library implements it. */
+        readonly jsonSchema?: {
+            readonly input: (options: {
+                target: string;
+            }) => JsonSchema;
+        };
+    };
+}
+type StandardResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: readonly {
+        readonly message: string;
+    }[];
+};
+/** A JSON Schema object, as AG-UI's `Tool.parameters` carries it. */
+export type JsonSchema = Record<string, unknown>;
+/** What a tool's handler is told besides its arguments. */
+export interface AgentToolContext {
+    /** Aborts when the person stops the run or the agent unmounts. */
+    signal: AbortSignal;
+    toolCallId: string;
+}
+/** What a tool's renderer draws from. */
+export interface AgentToolRenderProps<Args = unknown> {
+    call: ChatToolCall;
+    /** The arguments so far: undefined while they stream and do not parse yet. */
+    args: Partial<Args> | undefined;
+    /**
+     * Set while the call waits on the person (a tool with no handler): answers
+     * it, and the answer goes back to the agent as the tool's result.
+     */
+    respond?: (result: unknown) => void;
+}
+export interface AgentTool<Args = unknown> {
+    /** The name the agent calls it by. */
+    name: string;
+    /** What it does, for the agent. */
+    description?: string;
+    parameters?: StandardSchemaV1<unknown, Args> | JsonSchema;
+    /**
+     * Runs the call and returns its result (sent to the agent as JSON text). A
+     * tool with no handler and a `render` is a human-in-the-loop tool: the run
+     * waits until the rendered component calls `respond`.
+     */
+    handler?: (args: Args, context: AgentToolContext) => unknown;
+    /** Draws the call in the conversation instead of the default tool card. */
+    render?: (props: AgentToolRenderProps<Args>) => React.ReactNode;
+    /** Whether the agent runs again after the result. Defaults to true. */
+    followUp?: boolean;
+    /** False hides the tool from the agent without unregistering it. */
+    available?: boolean;
+}
+/** Types a tool's handler and renderer from its parameters; returns the tool as given. */
+export declare function defineTool<Args = Record<string, unknown>>(tool: AgentTool<Args>): AgentTool<Args>;
+export declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
+/**
+ * A tool's parameters as JSON Schema for the agent: Standard JSON Schema when
+ * the library implements it, zod 4's `toJSONSchema()`, or the JSON Schema
+ * given. Throws for a schema it cannot convert (zod 3 without Standard JSON
+ * Schema), naming the tool.
+ */
+export declare function toolJsonSchema(tool: Pick<AgentTool, "name" | "parameters">): JsonSchema;
+/**
+ * The arguments as the handler receives them: validated (and transformed)
+ * through a Standard Schema, or as parsed for a JSON Schema. Rejects with
+ * the schema's issues.
+ */
+export declare function validateToolArgs<Args>(tool: AgentTool<Args>, args: unknown): Promise<Args>;
+/**
+ * A tool's parameters as a Standard Schema, for an engine that only takes
+ * one (CopilotKit): a JSON Schema becomes a schema that passes values through
+ * and reports itself as Standard JSON Schema.
+ */
+export declare function toolStandardSchema(tool: AgentTool): StandardSchemaV1;
+/** A tool result as the text AG-UI's tool message carries. */
+export declare function toolResultText(result: unknown): string;
+export {};

package/dist/agent/tool.js

@@ -0,0 +1,81 @@
+/** Types a tool's handler and renderer from its parameters; returns the tool as given. */
+export function defineTool(tool) {
+    return tool;
+}
+export function isStandardSchema(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "~standard" in value &&
+        typeof value["~standard"]?.validate === "function");
+}
+const EMPTY_OBJECT = { type: "object", properties: {} };
+/**
+ * A tool's parameters as JSON Schema for the agent: Standard JSON Schema when
+ * the library implements it, zod 4's `toJSONSchema()`, or the JSON Schema
+ * given. Throws for a schema it cannot convert (zod 3 without Standard JSON
+ * Schema), naming the tool.
+ */
+export function toolJsonSchema(tool) {
+    const { parameters } = tool;
+    if (parameters === undefined)
+        return EMPTY_OBJECT;
+    if (!isStandardSchema(parameters))
+        return parameters;
+    const standard = parameters["~standard"];
+    if (typeof standard.jsonSchema?.input === "function") {
+        return clean(standard.jsonSchema.input({ target: "draft-07" }));
+    }
+    const withMethod = parameters;
+    if (typeof withMethod.toJSONSchema === "function")
+        return clean(withMethod.toJSONSchema());
+    throw new Error(`Tool ${tool.name}: its ${standard.vendor} schema has no JSON Schema form. Use a library with Standard JSON Schema (zod 4, valibot 1, arktype 2) or pass a JSON Schema.`);
+}
+function clean(schema) {
+    const { $schema: _, ...rest } = schema;
+    return rest;
+}
+/**
+ * The arguments as the handler receives them: validated (and transformed)
+ * through a Standard Schema, or as parsed for a JSON Schema. Rejects with
+ * the schema's issues.
+ */
+export async function validateToolArgs(tool, args) {
+    if (!isStandardSchema(tool.parameters))
+        return args;
+    const result = await tool.parameters["~standard"].validate(args);
+    if (result.issues) {
+        throw new Error(`Invalid arguments for ${tool.name}: ${result.issues.map((i) => i.message).join("; ")}`);
+    }
+    return result.value;
+}
+/**
+ * A tool's parameters as a Standard Schema, for an engine that only takes
+ * one (CopilotKit): a JSON Schema becomes a schema that passes values through
+ * and reports itself as Standard JSON Schema.
+ */
+export function toolStandardSchema(tool) {
+    if (isStandardSchema(tool.parameters))
+        return tool.parameters;
+    const schema = toolJsonSchema(tool);
+    return {
+        "~standard": {
+            version: 1,
+            vendor: "calliope-json-schema",
+            validate: (value) => ({ value }),
+            jsonSchema: { input: () => schema },
+        },
+    };
+}
+/** A tool result as the text AG-UI's tool message carries. */
+export function toolResultText(result) {
+    if (result === undefined)
+        return "";
+    if (typeof result === "string")
+        return result;
+    try {
+        return JSON.stringify(result);
+    }
+    catch {
+        return String(result);
+    }
+}