@gravity-ui/aikit 2.3.0 → 2.4.0

package/build/esm/utils/toolset/index.d.ts

@@ -0,0 +1,142 @@
+import type { ComponentType } from 'react';
+import type { TChatMessage, TMessageContent, ToolMessageContentData } from "../../types/messages.js";
+import { type MessageRendererRegistry } from "../messageTypeRegistry.js";
+export type ToolSchemaResult<TArgs> = {
+    success: true;
+    data: TArgs;
+} | {
+    success: false;
+    error: {
+        message: string;
+    };
+};
+export type ToolSchema<TArgs> = {
+    validate: (input: unknown) => ToolSchemaResult<TArgs>;
+};
+export type ToolComponentProps<TArgs, TResult> = {
+    args: TArgs;
+    result?: TResult;
+    submitResult: (result: TResult) => void;
+};
+export type ToolExecutionStatus = 'success' | 'error' | 'cancelled';
+/**
+ * Discriminated outcome returned by a tool's `execute` callback.
+ * A tool may also return a bare `TResult`; it is then treated as
+ * `{status: 'success', result}` to keep simple cases boilerplate-free.
+ */
+export type ToolExecutionOutcome<TResult> = {
+    status: 'success';
+    result: TResult;
+} | {
+    status: 'error';
+    result?: TResult;
+    error?: {
+        message: string;
+    };
+} | {
+    status: 'cancelled';
+    result?: TResult;
+};
+export type ToolDefinition<TArgs, TResult, TName extends string = string> = {
+    name: TName;
+    description: string;
+    parameters: Record<string, unknown>;
+    schema: ToolSchema<TArgs>;
+    component: ComponentType<ToolComponentProps<TArgs, TResult>>;
+    /**
+     * Run after the user submits a result inside the tool component.
+     * Return:
+     *  - `TResult` (or a Promise of one) for a successful execution;
+     *  - a `ToolExecutionOutcome<TResult>` to explicitly report `error`
+     *    or `cancelled`. A thrown error is surfaced as `{status: 'error'}`.
+     */
+    execute?: (params: {
+        args: TArgs;
+        result: TResult;
+        toolCallId: string;
+    }) => TResult | ToolExecutionOutcome<TResult> | Promise<TResult | ToolExecutionOutcome<TResult>>;
+};
+export type RuntimeToolDefinition<TName extends string = string> = {
+    name: TName;
+    description: string;
+    parameters: Record<string, unknown>;
+    validate: (input: unknown) => ToolSchemaResult<unknown>;
+    /**
+     * Rendered as `<Renderer ... />` JSX. Hooks placed at the top of this
+     * component work normally because it is a real React component, not a
+     * function called inside another render path.
+     */
+    Renderer: ComponentType<ToolComponentProps<unknown, unknown>>;
+    execute: (params: {
+        args: unknown;
+        result: unknown;
+        toolCallId: string;
+    }) => unknown | ToolExecutionOutcome<unknown> | Promise<unknown | ToolExecutionOutcome<unknown>>;
+};
+export type Toolset = Record<string, RuntimeToolDefinition>;
+export type ToolPartContentData<TArgs = unknown, TResult = unknown> = ToolMessageContentData & {
+    toolCallId: string;
+    args?: TArgs;
+    result?: TResult;
+};
+export type ToolPartContent<TArgs = unknown, TResult = unknown> = TMessageContent<'tool', ToolPartContentData<TArgs, TResult>>;
+export type ToolsetResultEvent = {
+    toolCallId: string;
+    toolName: string;
+    status: ToolExecutionStatus;
+    result: unknown;
+    error?: {
+        message: string;
+    };
+};
+/**
+ * Wrap a typed tool definition into an erased runtime entry that the
+ * toolset renderer can dispatch by `toolName`. The literal `name` is
+ * preserved as a type parameter so `createToolset` can derive its keys.
+ */
+export declare function defineTool<TArgs, TResult, const TName extends string>(definition: ToolDefinition<TArgs, TResult, TName>): RuntimeToolDefinition<TName>;
+/**
+ * Build a `Toolset` from a list of `defineTool(...)` results. Keys are
+ * derived from `definition.name`, so the call site cannot drift between
+ * a literal-object key and the embedded `name`. The return type narrows
+ * its keys to the union of literal tool names, giving name-autocomplete
+ * on lookups. Throws on duplicates.
+ */
+export declare function createToolset<const T extends readonly RuntimeToolDefinition<string>[]>(...tools: T): {
+    [K in T[number]['name']]: RuntimeToolDefinition<T[number]['name']>;
+};
+/**
+ * Map a `Toolset` to the OpenAI `tools[]` shape so chat clients can pass
+ * tool definitions to the model without reimplementing the conversion.
+ */
+export declare function toolsetToOpenAIDefinitions(toolset: Toolset): Array<{
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}>;
+export type CreateToolsetRendererOptions = {
+    onToolResult: (event: ToolsetResultEvent) => void;
+    /**
+     * Existing registry whose entries should be preserved. A shallow copy
+     * is taken; the input reference is never mutated.
+     */
+    registry?: MessageRendererRegistry;
+};
+/**
+ * Build a `MessageRendererRegistry` whose `tool` renderer dispatches
+ * by `toolName` into the provided toolset. Unknown tools and invalid
+ * args fall back to a generic `<ToolMessage status="error" />`. Errors
+ * thrown inside `execute` are surfaced via an `error` outcome.
+ */
+export declare function createToolsetRenderer(toolset: Toolset, options: CreateToolsetRendererOptions): MessageRendererRegistry;
+/**
+ * Merge a tool result into the matching `tool` part of the chat history.
+ * Honors `event.status` so the part reflects success / error / cancelled.
+ * For backward compatibility, a missing `status` is treated as `'success'`.
+ * Returns the original array reference when nothing matched, so React state
+ * setters can skip needless updates.
+ */
+export declare function applyToolResult<TCustom extends TMessageContent = never>(messages: TChatMessage<TCustom>[], event: ToolsetResultEvent): TChatMessage<TCustom>[];

package/build/esm/utils/toolset/index.js

@@ -0,0 +1,176 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ToolMessage } from "../../components/organisms/ToolMessage/index.js";
+import { createMessageRendererRegistry, registerMessageRenderer, } from "../messageTypeRegistry.js";
+import { i18n } from "./i18n/index.js";
+/**
+ * Wrap a typed tool definition into an erased runtime entry that the
+ * toolset renderer can dispatch by `toolName`. The literal `name` is
+ * preserved as a type parameter so `createToolset` can derive its keys.
+ */
+export function defineTool(definition) {
+    return {
+        name: definition.name,
+        description: definition.description,
+        parameters: definition.parameters,
+        validate: definition.schema.validate,
+        Renderer: definition.component,
+        execute: ({ args, result, toolCallId }) => definition.execute
+            ? definition.execute({
+                args: args,
+                result: result,
+                toolCallId,
+            })
+            : result,
+    };
+}
+/**
+ * Build a `Toolset` from a list of `defineTool(...)` results. Keys are
+ * derived from `definition.name`, so the call site cannot drift between
+ * a literal-object key and the embedded `name`. The return type narrows
+ * its keys to the union of literal tool names, giving name-autocomplete
+ * on lookups. Throws on duplicates.
+ */
+export function createToolset(...tools) {
+    const result = {};
+    for (const tool of tools) {
+        if (Object.prototype.hasOwnProperty.call(result, tool.name)) {
+            throw new Error(`createToolset: duplicate tool name "${tool.name}"`);
+        }
+        result[tool.name] = tool;
+    }
+    return result;
+}
+/**
+ * Map a `Toolset` to the OpenAI `tools[]` shape so chat clients can pass
+ * tool definitions to the model without reimplementing the conversion.
+ */
+export function toolsetToOpenAIDefinitions(toolset) {
+    return Object.values(toolset).map((tool) => ({
+        type: 'function',
+        function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.parameters,
+        },
+    }));
+}
+const OUTCOME_KEYS = new Set(['status', 'result', 'error']);
+function isToolExecutionOutcome(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const status = value.status;
+    if (status !== 'success' && status !== 'error' && status !== 'cancelled')
+        return false;
+    // A bare TResult may coincidentally carry a `status` field. Require all
+    // own keys to be in {status, result, error} so e.g. `{status: 'success',
+    // id: '123'}` is treated as a result, not a (result-less) outcome.
+    for (const key of Object.keys(value)) {
+        if (!OUTCOME_KEYS.has(key))
+            return false;
+    }
+    return true;
+}
+function normalizeOutcome(value) {
+    if (isToolExecutionOutcome(value))
+        return value;
+    return { status: 'success', result: value };
+}
+/**
+ * Build a `MessageRendererRegistry` whose `tool` renderer dispatches
+ * by `toolName` into the provided toolset. Unknown tools and invalid
+ * args fall back to a generic `<ToolMessage status="error" />`. Errors
+ * thrown inside `execute` are surfaced via an `error` outcome.
+ */
+export function createToolsetRenderer(toolset, options) {
+    var _a;
+    const { onToolResult } = options;
+    const registry = Object.assign({}, ((_a = options.registry) !== null && _a !== void 0 ? _a : createMessageRendererRegistry()));
+    const toolRenderer = {
+        component: ({ part }) => {
+            const toolPart = part.data;
+            const toolDef = toolset[toolPart.toolName];
+            if (!toolDef) {
+                return (_jsx(ToolMessage, { toolName: toolPart.toolName, status: "error", expandable: true, initialExpanded: true, bodyContent: i18n('fallback-unknown-tool', {
+                        toolName: toolPart.toolName,
+                    }) }));
+            }
+            const validation = toolDef.validate(toolPart.args);
+            if (!validation.success) {
+                return (_jsx(ToolMessage, { toolName: toolPart.toolName, status: "error", expandable: true, initialExpanded: true, bodyContent: validation.error.message }));
+            }
+            const submitResult = (result) => {
+                Promise.resolve()
+                    .then(() => toolDef.execute({
+                    args: validation.data,
+                    result,
+                    toolCallId: toolPart.toolCallId,
+                }))
+                    .then((raw) => normalizeOutcome(raw))
+                    .catch((err) => ({
+                    status: 'error',
+                    error: { message: err instanceof Error ? err.message : String(err) },
+                }))
+                    .then((outcome) => {
+                    onToolResult({
+                        toolCallId: toolPart.toolCallId,
+                        toolName: toolPart.toolName,
+                        status: outcome.status,
+                        result: outcome.result,
+                        error: 'error' in outcome ? outcome.error : undefined,
+                    });
+                });
+            };
+            const { Renderer } = toolDef;
+            return (_jsx(Renderer, { args: validation.data, result: toolPart.result, submitResult: submitResult }));
+        },
+    };
+    registerMessageRenderer(registry, 'tool', toolRenderer);
+    return registry;
+}
+function isToolPartContent(part) {
+    return part.type === 'tool' && typeof part.data === 'object' && part.data !== null;
+}
+function toContentParts(content) {
+    if (typeof content === 'string') {
+        return content ? [{ type: 'text', data: { text: content } }] : [];
+    }
+    return Array.isArray(content) ? content : [content];
+}
+/**
+ * Merge a tool result into the matching `tool` part of the chat history.
+ * Honors `event.status` so the part reflects success / error / cancelled.
+ * For backward compatibility, a missing `status` is treated as `'success'`.
+ * Returns the original array reference when nothing matched, so React state
+ * setters can skip needless updates.
+ */
+export function applyToolResult(messages, event) {
+    var _a;
+    let changed = false;
+    const status = (_a = event.status) !== null && _a !== void 0 ? _a : 'success';
+    const isError = status === 'error';
+    const next = messages.map((msg) => {
+        if (msg.role !== 'assistant')
+            return msg;
+        const parts = toContentParts(msg.content);
+        const hasMatch = parts.some((part) => isToolPartContent(part) && part.data.toolCallId === event.toolCallId);
+        if (!hasMatch)
+            return msg;
+        changed = true;
+        const updatedParts = parts.map((part) => {
+            var _a;
+            if (!isToolPartContent(part) || part.data.toolCallId !== event.toolCallId) {
+                return part;
+            }
+            const nextData = Object.assign(Object.assign({}, part.data), { status, result: event.result });
+            if (isError && ((_a = event.error) === null || _a === void 0 ? void 0 : _a.message)) {
+                nextData.bodyContent = event.error.message;
+                nextData.expandable = true;
+                nextData.initialExpanded = true;
+            }
+            return Object.assign(Object.assign({}, part), { data: nextData });
+        });
+        return Object.assign(Object.assign({}, msg), { content: updatedParts });
+    });
+    return changed ? next : messages;
+}
+//# sourceMappingURL=index.js.map

package/build/esm/utils/toolset/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"../../../../src","sources":["utils/toolset/index.tsx"],"names":[],"mappings":";AAEA,OAAO,EAAC,WAAW,EAAC,wDAA+C;AAOnE,OAAO,EAGH,6BAA6B,EAC7B,uBAAuB,GAC1B,kCAA+B;AAEhC,OAAO,EAAC,IAAI,EAAC,wBAAe;AA6F5B;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACtB,UAAiD;IAEjD,OAAO;QACH,IAAI,EAAE,UAAU,CAAC,IAAI;QACrB,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,UAAU,EAAE,UAAU,CAAC,UAAU;QACjC,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,QAAyD;QACrF,QAAQ,EAAE,UAAU,CAAC,SAAgE;QACrF,OAAO,EAAE,CAAC,EAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAC,EAAE,EAAE,CACpC,UAAU,CAAC,OAAO;YACd,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC;gBACf,IAAI,EAAE,IAAa;gBACnB,MAAM,EAAE,MAAiB;gBACzB,UAAU;aACb,CAAC;YACJ,CAAC,CAAC,MAAM;KACnB,CAAC;AACN,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CACzB,GAAG,KAAQ;IAEX,MAAM,MAAM,GAA0C,EAAE,CAAC;IACzD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1D,MAAM,IAAI,KAAK,CAAC,uCAAuC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7B,CAAC;IACD,OAAO,MAA8E,CAAC;AAC1F,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CAAC,OAAgB;IAIvD,OAAO,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACzC,IAAI,EAAE,UAAmB;QACzB,QAAQ,EAAE;YACN,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,UAAU,EAAE,IAAI,CAAC,UAAU;SAC9B;KACJ,CAAC,CAAC,CAAC;AACR,CAAC;AAWD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;AAE5D,SAAS,sBAAsB,CAAU,KAAc;IACnD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,MAAM,GAAI,KAA4B,CAAC,MAAM,CAAC;IACpD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,OAAO,IAAI,MAAM,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC;IACvF,wEAAwE;IACxE,yEAAyE;IACzE,mEAAmE;IACnE,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACnC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;IAC7C,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED,SAAS,gBAAgB,CAAU,KAAc;IAC7C,IAAI,sBAAsB,CAAU,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACzD,OAAO,EAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAgB,EAAC,CAAC;AACzD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACjC,OAAgB,EAChB,OAAqC;;IAErC,MAAM,EAAC,YAAY,EAAC,GAAG,OAAO,CAAC;IAC/B,MAAM,QAAQ,qBACP,CAAC,MAAA,OAAO,CAAC,QAAQ,mCAAI,6BAA6B,EAAE,CAAC,CAC3D,CAAC;IAEF,MAAM,YAAY,GAAqC;QACnD,SAAS,EAAE,CAAC,EAAC,IAAI,EAAC,EAAE,EAAE;YAClB,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC;YAC3B,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAE3C,IAAI,CAAC,OAAO,EAAE,CAAC;gBACX,OAAO,CACH,KAAC,WAAW,IACR,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAC3B,MAAM,EAAC,OAAO,EACd,UAAU,QACV,eAAe,QACf,WAAW,EAAE,IAAI,CAAC,uBAAuB,EAAE;wBACvC,QAAQ,EAAE,QAAQ,CAAC,QAAQ;qBAC9B,CAAC,GACJ,CACL,CAAC;YACN,CAAC;YAED,MAAM,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACnD,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;gBACtB,OAAO,CACH,KAAC,WAAW,IACR,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAC3B,MAAM,EAAC,OAAO,EACd,UAAU,QACV,eAAe,QACf,WAAW,EAAE,UAAU,CAAC,KAAK,CAAC,OAAO,GACvC,CACL,CAAC;YACN,CAAC;YAED,MAAM,YAAY,GAAG,CAAC,MAAe,EAAE,EAAE;gBACrC,OAAO,CAAC,OAAO,EAAE;qBACZ,IAAI,CAAC,GAAG,EAAE,CACP,OAAO,CAAC,OAAO,CAAC;oBACZ,IAAI,EAAE,UAAU,CAAC,IAAI;oBACrB,MAAM;oBACN,UAAU,EAAE,QAAQ,CAAC,UAAU;iBAClC,CAAC,CACL;qBACA,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;qBACpC,KAAK,CACF,CAAC,GAAG,EAAiC,EAAE,CAAC,CAAC;oBACrC,MAAM,EAAE,OAAO;oBACf,KAAK,EAAE,EAAC,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAC;iBACrE,CAAC,CACL;qBACA,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;oBACd,YAAY,CAAC;wBACT,UAAU,EAAE,QAAQ,CAAC,UAAU;wBAC/B,QAAQ,EAAE,QAAQ,CAAC,QAAQ;wBAC3B,MAAM,EAAE,OAAO,CAAC,MAAM;wBACtB,MAAM,EAAE,OAAO,CAAC,MAAM;wBACtB,KAAK,EAAE,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;qBACxD,CAAC,CAAC;gBACP,CAAC,CAAC,CAAC;YACX,CAAC,CAAC;YAEF,MAAM,EAAC,QAAQ,EAAC,GAAG,OAAO,CAAC;YAC3B,OAAO,CACH,KAAC,QAAQ,IACL,IAAI,EAAE,UAAU,CAAC,IAAI,EACrB,MAAM,EAAE,QAAQ,CAAC,MAAM,EACvB,YAAY,EAAE,YAAY,GAC5B,CACL,CAAC;QACN,CAAC;KACJ,CAAC;IAEF,uBAAuB,CAAkB,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;IAEzE,OAAO,QAAQ,CAAC;AACpB,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAqB;IAC5C,OAAO,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC;AACvF,CAAC;AAED,SAAS,cAAc,CACnB,OAA8C;IAE9C,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,EAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAC,IAAI,EAAE,OAAO,EAAC,EAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAClE,CAAC;IACD,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAE,OAA6B,CAAC,CAAC,CAAC,CAAC,OAA0B,CAAC,CAAC;AAClG,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC3B,QAAiC,EACjC,KAAyB;;IAEzB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,MAAM,GAAwB,MAAA,KAAK,CAAC,MAAM,mCAAI,SAAS,CAAC;IAC9D,MAAM,OAAO,GAAG,MAAM,KAAK,OAAO,CAAC;IAEnC,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAyB,EAAE;QACrD,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW;YAAE,OAAO,GAAG,CAAC;QAEzC,MAAM,KAAK,GAAG,cAAc,CAAU,GAAG,CAAC,OAAO,CAAC,CAAC;QACnD,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CACvB,CAAC,IAAI,EAAE,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,KAAK,KAAK,CAAC,UAAU,CACjF,CAAC;QACF,IAAI,CAAC,QAAQ;YAAE,OAAO,GAAG,CAAC;QAE1B,OAAO,GAAG,IAAI,CAAC;QACf,MAAM,YAAY,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;;YACpC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,KAAK,KAAK,CAAC,UAAU,EAAE,CAAC;gBACxE,OAAO,IAAI,CAAC;YAChB,CAAC;YACD,MAAM,QAAQ,mCACP,IAAI,CAAC,IAAI,KACZ,MAAM,EACN,MAAM,EAAE,KAAK,CAAC,MAAM,GACvB,CAAC;YACF,IAAI,OAAO,KAAI,MAAA,KAAK,CAAC,KAAK,0CAAE,OAAO,CAAA,EAAE,CAAC;gBAClC,QAAQ,CAAC,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC;gBAC3C,QAAQ,CAAC,UAAU,GAAG,IAAI,CAAC;gBAC3B,QAAQ,CAAC,eAAe,GAAG,IAAI,CAAC;YACpC,CAAC;YACD,uCACO,IAAI,KACP,IAAI,EAAE,QAAQ,IAChB;QACN,CAAC,CAAC,CAAC;QAEH,uCACO,GAAG,KACN,OAAO,EAAE,YAAqD,IAChE;IACN,CAAC,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;AACrC,CAAC","sourcesContent":["import type {ComponentType} from 'react';\n\nimport {ToolMessage} from '../../components/organisms/ToolMessage';\nimport type {\n    TAssistantMessage,\n    TChatMessage,\n    TMessageContent,\n    ToolMessageContentData,\n} from '../../types/messages';\nimport {\n    type MessageRenderer,\n    type MessageRendererRegistry,\n    createMessageRendererRegistry,\n    registerMessageRenderer,\n} from '../messageTypeRegistry';\n\nimport {i18n} from './i18n';\n\nexport type ToolSchemaResult<TArgs> =\n    | {success: true; data: TArgs}\n    | {success: false; error: {message: string}};\n\nexport type ToolSchema<TArgs> = {\n    validate: (input: unknown) => ToolSchemaResult<TArgs>;\n};\n\nexport type ToolComponentProps<TArgs, TResult> = {\n    args: TArgs;\n    result?: TResult;\n    submitResult: (result: TResult) => void;\n};\n\nexport type ToolExecutionStatus = 'success' | 'error' | 'cancelled';\n\n/**\n * Discriminated outcome returned by a tool's `execute` callback.\n * A tool may also return a bare `TResult`; it is then treated as\n * `{status: 'success', result}` to keep simple cases boilerplate-free.\n */\nexport type ToolExecutionOutcome<TResult> =\n    | {status: 'success'; result: TResult}\n    | {status: 'error'; result?: TResult; error?: {message: string}}\n    | {status: 'cancelled'; result?: TResult};\n\nexport type ToolDefinition<TArgs, TResult, TName extends string = string> = {\n    name: TName;\n    description: string;\n    parameters: Record<string, unknown>;\n    schema: ToolSchema<TArgs>;\n    component: ComponentType<ToolComponentProps<TArgs, TResult>>;\n    /**\n     * Run after the user submits a result inside the tool component.\n     * Return:\n     *  - `TResult` (or a Promise of one) for a successful execution;\n     *  - a `ToolExecutionOutcome<TResult>` to explicitly report `error`\n     *    or `cancelled`. A thrown error is surfaced as `{status: 'error'}`.\n     */\n    execute?: (params: {\n        args: TArgs;\n        result: TResult;\n        toolCallId: string;\n    }) =>\n        | TResult\n        | ToolExecutionOutcome<TResult>\n        | Promise<TResult | ToolExecutionOutcome<TResult>>;\n};\n\nexport type RuntimeToolDefinition<TName extends string = string> = {\n    name: TName;\n    description: string;\n    parameters: Record<string, unknown>;\n    validate: (input: unknown) => ToolSchemaResult<unknown>;\n    /**\n     * Rendered as `<Renderer ... />` JSX. Hooks placed at the top of this\n     * component work normally because it is a real React component, not a\n     * function called inside another render path.\n     */\n    Renderer: ComponentType<ToolComponentProps<unknown, unknown>>;\n    execute: (params: {\n        args: unknown;\n        result: unknown;\n        toolCallId: string;\n    }) =>\n        | unknown\n        | ToolExecutionOutcome<unknown>\n        | Promise<unknown | ToolExecutionOutcome<unknown>>;\n};\n\nexport type Toolset = Record<string, RuntimeToolDefinition>;\n\nexport type ToolPartContentData<TArgs = unknown, TResult = unknown> = ToolMessageContentData & {\n    toolCallId: string;\n    args?: TArgs;\n    result?: TResult;\n};\n\nexport type ToolPartContent<TArgs = unknown, TResult = unknown> = TMessageContent<\n    'tool',\n    ToolPartContentData<TArgs, TResult>\n>;\n\nexport type ToolsetResultEvent = {\n    toolCallId: string;\n    toolName: string;\n    status: ToolExecutionStatus;\n    result: unknown;\n    error?: {message: string};\n};\n\n/**\n * Wrap a typed tool definition into an erased runtime entry that the\n * toolset renderer can dispatch by `toolName`. The literal `name` is\n * preserved as a type parameter so `createToolset` can derive its keys.\n */\nexport function defineTool<TArgs, TResult, const TName extends string>(\n    definition: ToolDefinition<TArgs, TResult, TName>,\n): RuntimeToolDefinition<TName> {\n    return {\n        name: definition.name,\n        description: definition.description,\n        parameters: definition.parameters,\n        validate: definition.schema.validate as (input: unknown) => ToolSchemaResult<unknown>,\n        Renderer: definition.component as ComponentType<ToolComponentProps<unknown, unknown>>,\n        execute: ({args, result, toolCallId}) =>\n            definition.execute\n                ? definition.execute({\n                      args: args as TArgs,\n                      result: result as TResult,\n                      toolCallId,\n                  })\n                : result,\n    };\n}\n\n/**\n * Build a `Toolset` from a list of `defineTool(...)` results. Keys are\n * derived from `definition.name`, so the call site cannot drift between\n * a literal-object key and the embedded `name`. The return type narrows\n * its keys to the union of literal tool names, giving name-autocomplete\n * on lookups. Throws on duplicates.\n */\nexport function createToolset<const T extends readonly RuntimeToolDefinition<string>[]>(\n    ...tools: T\n): {[K in T[number]['name']]: RuntimeToolDefinition<T[number]['name']>} {\n    const result: Record<string, RuntimeToolDefinition> = {};\n    for (const tool of tools) {\n        if (Object.prototype.hasOwnProperty.call(result, tool.name)) {\n            throw new Error(`createToolset: duplicate tool name \"${tool.name}\"`);\n        }\n        result[tool.name] = tool;\n    }\n    return result as {[K in T[number]['name']]: RuntimeToolDefinition<T[number]['name']>};\n}\n\n/**\n * Map a `Toolset` to the OpenAI `tools[]` shape so chat clients can pass\n * tool definitions to the model without reimplementing the conversion.\n */\nexport function toolsetToOpenAIDefinitions(toolset: Toolset): Array<{\n    type: 'function';\n    function: {name: string; description: string; parameters: Record<string, unknown>};\n}> {\n    return Object.values(toolset).map((tool) => ({\n        type: 'function' as const,\n        function: {\n            name: tool.name,\n            description: tool.description,\n            parameters: tool.parameters,\n        },\n    }));\n}\n\nexport type CreateToolsetRendererOptions = {\n    onToolResult: (event: ToolsetResultEvent) => void;\n    /**\n     * Existing registry whose entries should be preserved. A shallow copy\n     * is taken; the input reference is never mutated.\n     */\n    registry?: MessageRendererRegistry;\n};\n\nconst OUTCOME_KEYS = new Set(['status', 'result', 'error']);\n\nfunction isToolExecutionOutcome<TResult>(value: unknown): value is ToolExecutionOutcome<TResult> {\n    if (!value || typeof value !== 'object') return false;\n    const status = (value as {status?: unknown}).status;\n    if (status !== 'success' && status !== 'error' && status !== 'cancelled') return false;\n    // A bare TResult may coincidentally carry a `status` field. Require all\n    // own keys to be in {status, result, error} so e.g. `{status: 'success',\n    // id: '123'}` is treated as a result, not a (result-less) outcome.\n    for (const key of Object.keys(value)) {\n        if (!OUTCOME_KEYS.has(key)) return false;\n    }\n    return true;\n}\n\nfunction normalizeOutcome<TResult>(value: unknown): ToolExecutionOutcome<TResult> {\n    if (isToolExecutionOutcome<TResult>(value)) return value;\n    return {status: 'success', result: value as TResult};\n}\n\n/**\n * Build a `MessageRendererRegistry` whose `tool` renderer dispatches\n * by `toolName` into the provided toolset. Unknown tools and invalid\n * args fall back to a generic `<ToolMessage status=\"error\" />`. Errors\n * thrown inside `execute` are surfaced via an `error` outcome.\n */\nexport function createToolsetRenderer(\n    toolset: Toolset,\n    options: CreateToolsetRendererOptions,\n): MessageRendererRegistry {\n    const {onToolResult} = options;\n    const registry: MessageRendererRegistry = {\n        ...(options.registry ?? createMessageRendererRegistry()),\n    };\n\n    const toolRenderer: MessageRenderer<ToolPartContent> = {\n        component: ({part}) => {\n            const toolPart = part.data;\n            const toolDef = toolset[toolPart.toolName];\n\n            if (!toolDef) {\n                return (\n                    <ToolMessage\n                        toolName={toolPart.toolName}\n                        status=\"error\"\n                        expandable\n                        initialExpanded\n                        bodyContent={i18n('fallback-unknown-tool', {\n                            toolName: toolPart.toolName,\n                        })}\n                    />\n                );\n            }\n\n            const validation = toolDef.validate(toolPart.args);\n            if (!validation.success) {\n                return (\n                    <ToolMessage\n                        toolName={toolPart.toolName}\n                        status=\"error\"\n                        expandable\n                        initialExpanded\n                        bodyContent={validation.error.message}\n                    />\n                );\n            }\n\n            const submitResult = (result: unknown) => {\n                Promise.resolve()\n                    .then(() =>\n                        toolDef.execute({\n                            args: validation.data,\n                            result,\n                            toolCallId: toolPart.toolCallId,\n                        }),\n                    )\n                    .then((raw) => normalizeOutcome(raw))\n                    .catch(\n                        (err): ToolExecutionOutcome<unknown> => ({\n                            status: 'error',\n                            error: {message: err instanceof Error ? err.message : String(err)},\n                        }),\n                    )\n                    .then((outcome) => {\n                        onToolResult({\n                            toolCallId: toolPart.toolCallId,\n                            toolName: toolPart.toolName,\n                            status: outcome.status,\n                            result: outcome.result,\n                            error: 'error' in outcome ? outcome.error : undefined,\n                        });\n                    });\n            };\n\n            const {Renderer} = toolDef;\n            return (\n                <Renderer\n                    args={validation.data}\n                    result={toolPart.result}\n                    submitResult={submitResult}\n                />\n            );\n        },\n    };\n\n    registerMessageRenderer<ToolPartContent>(registry, 'tool', toolRenderer);\n\n    return registry;\n}\n\nfunction isToolPartContent(part: TMessageContent): part is ToolPartContent {\n    return part.type === 'tool' && typeof part.data === 'object' && part.data !== null;\n}\n\nfunction toContentParts<TCustom extends TMessageContent>(\n    content: TAssistantMessage<TCustom>['content'],\n): TMessageContent[] {\n    if (typeof content === 'string') {\n        return content ? [{type: 'text', data: {text: content}}] : [];\n    }\n    return Array.isArray(content) ? (content as TMessageContent[]) : [content as TMessageContent];\n}\n\n/**\n * Merge a tool result into the matching `tool` part of the chat history.\n * Honors `event.status` so the part reflects success / error / cancelled.\n * For backward compatibility, a missing `status` is treated as `'success'`.\n * Returns the original array reference when nothing matched, so React state\n * setters can skip needless updates.\n */\nexport function applyToolResult<TCustom extends TMessageContent = never>(\n    messages: TChatMessage<TCustom>[],\n    event: ToolsetResultEvent,\n): TChatMessage<TCustom>[] {\n    let changed = false;\n    const status: ToolExecutionStatus = event.status ?? 'success';\n    const isError = status === 'error';\n\n    const next = messages.map((msg): TChatMessage<TCustom> => {\n        if (msg.role !== 'assistant') return msg;\n\n        const parts = toContentParts<TCustom>(msg.content);\n        const hasMatch = parts.some(\n            (part) => isToolPartContent(part) && part.data.toolCallId === event.toolCallId,\n        );\n        if (!hasMatch) return msg;\n\n        changed = true;\n        const updatedParts = parts.map((part) => {\n            if (!isToolPartContent(part) || part.data.toolCallId !== event.toolCallId) {\n                return part;\n            }\n            const nextData: ToolPartContentData = {\n                ...part.data,\n                status,\n                result: event.result,\n            };\n            if (isError && event.error?.message) {\n                nextData.bodyContent = event.error.message;\n                nextData.expandable = true;\n                nextData.initialExpanded = true;\n            }\n            return {\n                ...part,\n                data: nextData,\n            };\n        });\n\n        return {\n            ...msg,\n            content: updatedParts as TAssistantMessage<TCustom>['content'],\n        };\n    });\n\n    return changed ? next : messages;\n}\n"]}