Skip to content

The Open Standard for Generative UI

8.4 KB
Raw Blame
import { abortable } from "../shared/abort";
import { THESYS_API_BASE_URL } from "../shared/constants";
import {
  ToolExecutionError,
  type RegisteredTools,
  type ScriptToolCall,
  type ScriptToolResult,
  type ToolExecutionOptions,
  type ToolExecutionRequest,
  type ToolExecutorOptions,
} from "./types";

const MAX_ROUNDS = 8;
const MAX_TOOL_CALLS = 16;
const DEFAULT_TIMEOUT_MS = 60_000;

const isRecord = (value: unknown): value is Record<string, unknown> =>
  value !== null && typeof value === "object" && !Array.isArray(value);

function invalidResponse(): never {
  throw new ToolExecutionError("Invalid script execution response", "invalid_response", 502);
}

/** Register server tools once, then execute direct tools or generated script loops. */
export function createToolExecutor<Context = undefined>(
  options: ToolExecutorOptions<Context>,
): RegisteredTools<Context> {
  const entries = Object.entries(options.tools);
  const tools = Object.fromEntries(entries.map(([name, tool]) => [name, tool.execute]));
  const definitions = entries.map(([name, { description, parameters, output }]) => ({
    name,
    parameters,
    ...(description !== undefined && { description }),
    ...(output !== undefined && { output }),
  }));
  const endpoint = `${(options.apiBaseUrl ?? THESYS_API_BASE_URL).replace(/\/+$/, "")}/v1/app/execute`;
  const fetchFn = options.fetch ?? globalThis.fetch;
  const apiKey = options.apiKey;

  async function execute(
    input: ToolExecutionRequest,
    executionOptions?: ToolExecutionOptions<Context>,
  ): Promise<unknown> {
    if (!input || typeof input.name !== "string" || !input.name) {
      throw new ToolExecutionError("A tool name is required", "invalid_input");
    }
    const args = input.arguments ?? {};
    if (!isRecord(args))
      throw new ToolExecutionError("Tool arguments must be an object", "invalid_input");
    const timeoutMs = executionOptions?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
      throw new ToolExecutionError("timeoutMs must be a positive finite number", "invalid_input");
    }
    executionOptions?.signal?.throwIfAborted();
    const controller = new AbortController();
    const forwardAbort = () => controller.abort(executionOptions?.signal?.reason);
    executionOptions?.signal?.addEventListener("abort", forwardAbort, { once: true });
    const timer = setTimeout(
      () =>
        controller.abort(new ToolExecutionError("Tool execution timed out", "tool_timeout", 504)),
      timeoutMs,
    );
    const signal = controller.signal;

    const dispatch = async (name: string, toolArgs: Record<string, unknown>) => {
      signal.throwIfAborted();
      if (!Object.hasOwn(tools, name) || typeof tools[name] !== "function") {
        throw new ToolExecutionError(`Unknown customer tool: ${name}`, "tool_not_found", 404);
      }
      return abortable(
        Promise.resolve().then(() =>
          tools[name]!(toolArgs, { context: executionOptions?.context as Context, signal }),
        ),
        signal,
      );
    };

    try {
      if (Object.hasOwn(tools, input.name)) return await dispatch(input.name, args);
      if (typeof input.response !== "string" || !input.response.trim()) {
        throw new ToolExecutionError(
          `Unknown tool: ${input.name}. Supply a complete OpenUI response for script execution.`,
          "tool_not_found",
          404,
        );
      }

      if (!apiKey?.trim()) {
        throw new ToolExecutionError(
          "Pass apiKey to createToolExecutor to execute generated scripts",
          "missing_api_key",
        );
      }

      let state: string | undefined;
      let toolResults: ScriptToolResult[] = [];
      const seen = new Set<string>();
      // Allow a final settlement request after the last tool-call round.
      for (let round = 0; round <= MAX_ROUNDS; round++) {
        const response = await abortable(
          executeRound(
            {
              response: input.response,
              name: input.name,
              arguments: args,
              tool_results: toolResults,
              ...(state !== undefined && { state }),
            },
            signal,
          ),
          signal,
        );
        if (!isRecord(response)) invalidResponse();
        if (response["status"] === "done") return response["result"];
        if (response["status"] === "error") {
          const error = response["error"];
          if (
            !isRecord(error) ||
            typeof error["code"] !== "string" ||
            typeof error["message"] !== "string"
          )
            invalidResponse();
          // Never replay tools after a failed snapshot: a prior call may have mutated data.
          throw new ToolExecutionError(error["message"], error["code"]);
        }
        const calls = response["calls"];
        if (
          response["status"] !== "tool_calls" ||
          typeof response["state"] !== "string" ||
          !response["state"] ||
          !Array.isArray(calls) ||
          !calls.length
        )
          invalidResponse();
        if (round === MAX_ROUNDS || seen.size + calls.length > MAX_TOOL_CALLS) {
          throw new ToolExecutionError("Script execution limit exceeded", "script_limit", 502);
        }
        // Validate the complete batch before any customer tool starts.
        for (const call of calls) {
          if (
            !isRecord(call) ||
            (call["type"] !== undefined && call["type"] !== "function_call") ||
            typeof call["call_id"] !== "string" ||
            !call["call_id"] ||
            seen.has(call["call_id"]) ||
            typeof call["name"] !== "string" ||
            !call["name"] ||
            typeof call["arguments"] !== "string"
          )
            invalidResponse();
          seen.add(call["call_id"]);
        }
        state = response["state"];
        toolResults = await Promise.all(
          (calls as ScriptToolCall[]).map(async (call): Promise<ScriptToolResult> => {
            try {
              const toolArgs: unknown = JSON.parse(call.arguments);
              if (!isRecord(toolArgs))
                throw new ToolExecutionError("Tool arguments must be an object", "bad_args");
              const result = await dispatch(call.name, toolArgs);
              signal.throwIfAborted();
              const output = JSON.stringify(result ?? null);
              if (output === undefined)
                throw new ToolExecutionError(
                  "Tool result must be JSON serializable",
                  "bad_tool_result",
                );
              return {
                type: "function_call_output",
                call_id: call.call_id,
                output,
              };
            } catch (error) {
              signal.throwIfAborted();
              return {
                call_id: call.call_id,
                error: {
                  code: error instanceof ToolExecutionError ? error.code : "tool_exec_error",
                  message: error instanceof Error ? error.message : String(error),
                },
              };
            }
          }),
        );
      }
      throw new ToolExecutionError("Script execution limit exceeded", "script_limit", 502);
    } finally {
      clearTimeout(timer);
      executionOptions?.signal?.removeEventListener("abort", forwardAbort);
      controller.abort();
    }
  }

  async function executeRound(body: unknown, signal: AbortSignal): Promise<unknown> {
    signal.throwIfAborted();
    const response = await fetchFn(endpoint, {
      method: "POST",
      headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
      body: JSON.stringify(body),
      signal,
    });
    let result: unknown;
    try {
      result = await response.json();
    } catch {
      signal.throwIfAborted();
      throw new ToolExecutionError(
        `Could not read script execution response (HTTP ${response.status})`,
        "invalid_response",
        response.status,
      );
    }
    signal.throwIfAborted();
    if (!response.ok) {
      const error = isRecord(result) && isRecord(result["error"]) ? result["error"] : undefined;
      throw new ToolExecutionError(
        typeof error?.["message"] === "string"
          ? error["message"]
          : `Script execution failed: HTTP ${response.status}`,
        typeof error?.["code"] === "string" ? error["code"] : "http_error",
        response.status,
      );
    }
    return result;
  }

  return { definitions, execute };
}