@proposit/proposit-core 1.11.0 → 2.1.0

package/dist/extensions/openai/openai-retrieval.d.ts

@@ -0,0 +1,150 @@
+import type { TLlmRequest } from "../../lib/llm/types.js";
+import { type TOpenAiFetch } from "./types.js";
+/**
+ * The status values the OpenAI Responses API reports for a stored
+ * response. `completed` / `failed` / `incomplete` / `cancelled` are
+ * terminal; `queued` / `in_progress` are transient.
+ */
+export type TResponseStatus = "queued" | "in_progress" | "completed" | "failed" | "incomplete" | "cancelled";
+/**
+ * The structured result of a `retrieveResponse` call. All fields
+ * except `status` and `rawResponseId` are absent for non-terminal
+ * or failed responses.
+ */
+export type TRetrievedResponse = {
+    /** Current status of the stored response. */
+    status: TResponseStatus;
+    /**
+     * Parsed text output, present when `status === "completed"` and
+     * the response carried a `message` output item.
+     */
+    output?: string;
+    /** Token usage reported by OpenAI, when available. */
+    tokenUsage?: import("../../lib/llm/types.js").TLlmTokenUsage;
+    /** The OpenAI response id that was retrieved. */
+    rawResponseId: string;
+    /**
+     * The envelope's `incomplete_details.reason`, present when
+     * `status === "incomplete"` (e.g. `max_output_tokens`,
+     * `content_filter`). Lets a completion-side consumer classify an
+     * incomplete response without re-deriving it. Additive (since
+     * v1.11.0).
+     */
+    incompleteReason?: string;
+    /**
+     * The envelope's `error.message`, present when `status === "failed"`.
+     * Additive (since v1.11.0).
+     */
+    errorMessage?: string;
+};
+/**
+ * Retrieve a stored OpenAI response by id. Surfaces the current
+ * status, output text (when completed), and token usage.
+ *
+ * Throws {@link ResponseNotFoundError} when the response is not found
+ * (HTTP 404), which typically means the ~10-minute retention window
+ * has elapsed. Callers should clear the stored id, settle the
+ * associated stage as failed, and surface a retry prompt.
+ *
+ * @param id - The OpenAI response id to retrieve.
+ * @param options - Provider configuration (apiKey, optional baseUrl and fetch).
+ */
+export declare function retrieveResponse(id: string, options: {
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: TOpenAiFetch;
+    signal?: AbortSignal;
+}): Promise<TRetrievedResponse>;
+/**
+ * Reconnect to a stored, still-generating background response and
+ * **stream it to completion**. This is what actually drives a dropped
+ * background response forward: a passive `retrieveResponse` GET only
+ * reads the current state and leaves a `queued` / `in_progress`
+ * response sitting where it is, whereas reconnecting with `stream=true`
+ * resumes consumption so the response reaches a terminal status.
+ *
+ * Issues `GET /responses/{id}?stream=true&starting_after=<cursor>` and
+ * consumes the SSE stream to its terminal event, returning the same
+ * {@link TRetrievedResponse} shape as {@link retrieveResponse}.
+ *
+ * Throws {@link ResponseNotFoundError} when the response is not found
+ * (HTTP 404 — typically the ~10-minute retention window elapsed).
+ * Honors `signal`: an abort propagates as an `AbortError` from the
+ * underlying stream read.
+ *
+ * @param id - The OpenAI response id to reconnect to.
+ * @param options - `apiKey`, optional `startingAfter` SSE cursor
+ *   (defaults to 0 — replay from the start of the stored stream),
+ *   optional `baseUrl`, `fetch`, and `signal`.
+ */
+export declare function reconnectStream(id: string, options: {
+    apiKey: string;
+    startingAfter?: number;
+    baseUrl?: string;
+    fetch?: TOpenAiFetch;
+    signal?: AbortSignal;
+}): Promise<TRetrievedResponse>;
+/**
+ * Cancel a stored, in-flight OpenAI response. Issues
+ * `POST /responses/{id}/cancel` and returns the resulting
+ * {@link TRetrievedResponse} (typically `status: "cancelled"`).
+ *
+ * Cancel is **idempotent** per the Responses API: cancelling twice, or
+ * cancelling an already-terminal response, simply returns the final
+ * `Response` object rather than erroring — so callers do not need to
+ * guard against double-cancel.
+ *
+ * Throws {@link ResponseNotFoundError} when the response is not found
+ * (HTTP 404 — typically the ~10-minute retention window elapsed).
+ * Honors `signal` (an abort propagates as an `AbortError`).
+ *
+ * Use this to stop an in-flight background response when a stage is
+ * abandoned (resync timeout) or an import is cancelled, so generation
+ * does not keep running (and billing) server-side after the consumer
+ * has given up on it.
+ *
+ * @param id - The OpenAI response id to cancel.
+ * @param options - `apiKey`, optional `baseUrl`, `fetch`, and `signal`.
+ */
+export declare function cancelResponse(id: string, options: {
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: TOpenAiFetch;
+    signal?: AbortSignal;
+}): Promise<TRetrievedResponse>;
+/**
+ * Submit a background OpenAI response and return its `responseId` +
+ * submit-time `status` **without polling or streaming to completion**.
+ *
+ * This is the submit-only half of the existing `backgroundMode`
+ * (`runBackground`): it POSTs `{ background: true, store: true }`, parses
+ * the submit envelope, and returns immediately — the caller drives the
+ * response to completion later via {@link retrieveResponse} (typically
+ * after a durable suspend keyed on the returned `responseId`). It is the
+ * provider capability the pipeline's `launchStage` needs.
+ *
+ * **Terminal-on-submit fast-path:** a small/cached request can come back
+ * already terminal (`completed`/`failed`/`incomplete`/`cancelled`) on the
+ * submit POST. This function still returns `{ responseId, status }` for
+ * that case (no throw, no poll); the caller proceeds to
+ * `retrieveResponse(responseId)`, which sees the terminal state
+ * immediately.
+ *
+ * **No-tools precondition:** background mode does not support function
+ * tools in V1 — a tool-bearing request throws {@link NonRetryableLlmError},
+ * matching `respond`'s background guard.
+ *
+ * @param req - The structured-output request (system/user prompts +
+ *   `outputSchema` + model knobs). Tools are rejected.
+ * @param options - `apiKey`, optional `baseUrl`, `fetch`, and `signal`.
+ */
+export declare function submitBackgroundResponse<T>(req: TLlmRequest<T>, options: {
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: TOpenAiFetch;
+    signal?: AbortSignal;
+}): Promise<{
+    responseId: string;
+    status: TResponseStatus;
+}>;
+//# sourceMappingURL=openai-retrieval.d.ts.map

package/dist/extensions/openai/openai-retrieval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-retrieval.d.ts","sourceRoot":"","sources":["../../../src/extensions/openai/openai-retrieval.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAqBzD,OAAO,EAEH,KAAK,YAAY,EAGpB,MAAM,YAAY,CAAA;AAInB;;;;GAIG;AACH,MAAM,MAAM,eAAe,GACrB,QAAQ,GACR,aAAa,GACb,WAAW,GACX,QAAQ,GACR,YAAY,GACZ,WAAW,CAAA;AAEjB;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC7B,6CAA6C;IAC7C,MAAM,EAAE,eAAe,CAAA;IACvB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sDAAsD;IACtD,UAAU,CAAC,EAAE,OAAO,wBAAwB,EAAE,cAAc,CAAA;IAC5D,iDAAiD;IACjD,aAAa,EAAE,MAAM,CAAA;IACrB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CAClC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;IACL,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,YAAY,CAAA;IACpB,MAAM,CAAC,EAAE,WAAW,CAAA;CACvB,GACF,OAAO,CAAC,kBAAkB,CAAC,CAU7B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,eAAe,CACjC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;IACL,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,YAAY,CAAA;IACpB,MAAM,CAAC,EAAE,WAAW,CAAA;CACvB,GACF,OAAO,CAAC,kBAAkB,CAAC,CAmC7B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,cAAc,CAChC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;IACL,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,YAAY,CAAA;IACpB,MAAM,CAAC,EAAE,WAAW,CAAA;CACvB,GACF,OAAO,CAAC,kBAAkB,CAAC,CAoC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,wBAAwB,CAAC,CAAC,EAC5C,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EACnB,OAAO,EAAE;IACL,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,YAAY,CAAA;IACpB,MAAM,CAAC,EAAE,WAAW,CAAA;CACvB,GACF,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,CAAC,CA+D1D"}

package/dist/extensions/openai/openai-retrieval.js

@@ -0,0 +1,248 @@
+// Public retrieval API for stored OpenAI Responses: retrieve a stored
+// response by id, reconnect-and-stream a dropped background response to
+// completion, cancel an in-flight response, and submit a background
+// response without polling. These are the resync surfaces a consumer
+// drives after a durable suspend.
+//
+// Layering: this module sits alongside `provider.ts` (neither imports
+// the other) and above `openai-http.ts` / `openai-parsing.ts`, from
+// which it consumes the transport and parsing helpers.
+import { callOnce, getResponseById, parseJsonOrThrowTransient, resolveFetch, } from "./openai-http.js";
+import { extractAssistantText, extractUsage, isAbortError, readSseEnvelope, } from "./openai-parsing.js";
+import { deriveSchemaName } from "./openai-tools.js";
+import { typeboxToOpenAiSchema } from "./structured-output.js";
+import { classifyHttpError, NonRetryableLlmError, ResponseNotFoundError, TransientLlmError, } from "./errors.js";
+import { DEFAULT_BASE_URL, } from "./types.js";
+/**
+ * Retrieve a stored OpenAI response by id. Surfaces the current
+ * status, output text (when completed), and token usage.
+ *
+ * Throws {@link ResponseNotFoundError} when the response is not found
+ * (HTTP 404), which typically means the ~10-minute retention window
+ * has elapsed. Callers should clear the stored id, settle the
+ * associated stage as failed, and surface a retry prompt.
+ *
+ * @param id - The OpenAI response id to retrieve.
+ * @param options - Provider configuration (apiKey, optional baseUrl and fetch).
+ */
+export async function retrieveResponse(id, options) {
+    const fetchImpl = resolveFetch(options.fetch, "retrieveResponse");
+    const envelope = await getResponseById({
+        url: options.baseUrl ?? DEFAULT_BASE_URL,
+        id,
+        apiKey: options.apiKey,
+        fetchImpl,
+        signal: options.signal,
+    });
+    return envelopeToRetrievedResponse(envelope, id);
+}
+/**
+ * Reconnect to a stored, still-generating background response and
+ * **stream it to completion**. This is what actually drives a dropped
+ * background response forward: a passive `retrieveResponse` GET only
+ * reads the current state and leaves a `queued` / `in_progress`
+ * response sitting where it is, whereas reconnecting with `stream=true`
+ * resumes consumption so the response reaches a terminal status.
+ *
+ * Issues `GET /responses/{id}?stream=true&starting_after=<cursor>` and
+ * consumes the SSE stream to its terminal event, returning the same
+ * {@link TRetrievedResponse} shape as {@link retrieveResponse}.
+ *
+ * Throws {@link ResponseNotFoundError} when the response is not found
+ * (HTTP 404 — typically the ~10-minute retention window elapsed).
+ * Honors `signal`: an abort propagates as an `AbortError` from the
+ * underlying stream read.
+ *
+ * @param id - The OpenAI response id to reconnect to.
+ * @param options - `apiKey`, optional `startingAfter` SSE cursor
+ *   (defaults to 0 — replay from the start of the stored stream),
+ *   optional `baseUrl`, `fetch`, and `signal`.
+ */
+export async function reconnectStream(id, options) {
+    const fetchImpl = resolveFetch(options.fetch, "reconnectStream");
+    const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+    const startingAfter = options.startingAfter ?? 0;
+    const url = `${baseUrl}/${id}?stream=true&starting_after=${startingAfter.toString()}`;
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${options.apiKey}` },
+            signal: options.signal,
+        });
+    }
+    catch (err) {
+        if (isAbortError(err))
+            throw err;
+        throw new TransientLlmError({
+            message: `Network error reconnecting to OpenAI background response: ${err instanceof Error ? err.message : String(err)}`,
+        });
+    }
+    if (response.status === 404) {
+        throw new ResponseNotFoundError({ responseId: id });
+    }
+    if (!response.ok) {
+        const errorBody = await response.text().catch(() => "");
+        throw classifyHttpError(response.status, `OpenAI reconnect ${response.status.toString()}: ${errorBody || response.statusText}`);
+    }
+    const envelope = await readSseEnvelope(response);
+    return envelopeToRetrievedResponse(envelope, id);
+}
+/**
+ * Cancel a stored, in-flight OpenAI response. Issues
+ * `POST /responses/{id}/cancel` and returns the resulting
+ * {@link TRetrievedResponse} (typically `status: "cancelled"`).
+ *
+ * Cancel is **idempotent** per the Responses API: cancelling twice, or
+ * cancelling an already-terminal response, simply returns the final
+ * `Response` object rather than erroring — so callers do not need to
+ * guard against double-cancel.
+ *
+ * Throws {@link ResponseNotFoundError} when the response is not found
+ * (HTTP 404 — typically the ~10-minute retention window elapsed).
+ * Honors `signal` (an abort propagates as an `AbortError`).
+ *
+ * Use this to stop an in-flight background response when a stage is
+ * abandoned (resync timeout) or an import is cancelled, so generation
+ * does not keep running (and billing) server-side after the consumer
+ * has given up on it.
+ *
+ * @param id - The OpenAI response id to cancel.
+ * @param options - `apiKey`, optional `baseUrl`, `fetch`, and `signal`.
+ */
+export async function cancelResponse(id, options) {
+    const fetchImpl = resolveFetch(options.fetch, "cancelResponse");
+    const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+    let response;
+    try {
+        response = await fetchImpl(`${baseUrl}/${id}/cancel`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${options.apiKey}` },
+            signal: options.signal,
+        });
+    }
+    catch (err) {
+        if (isAbortError(err))
+            throw err;
+        throw new TransientLlmError({
+            message: `Network error cancelling OpenAI background response: ${err instanceof Error ? err.message : String(err)}`,
+        });
+    }
+    if (response.status === 404) {
+        throw new ResponseNotFoundError({ responseId: id });
+    }
+    if (!response.ok) {
+        const errorBody = await response.text().catch(() => "");
+        throw classifyHttpError(response.status, `OpenAI cancel ${response.status.toString()}: ${errorBody || response.statusText}`);
+    }
+    const envelope = await parseJsonOrThrowTransient(response, "OpenAI cancel body was not valid JSON");
+    return envelopeToRetrievedResponse(envelope, id);
+}
+/**
+ * Submit a background OpenAI response and return its `responseId` +
+ * submit-time `status` **without polling or streaming to completion**.
+ *
+ * This is the submit-only half of the existing `backgroundMode`
+ * (`runBackground`): it POSTs `{ background: true, store: true }`, parses
+ * the submit envelope, and returns immediately — the caller drives the
+ * response to completion later via {@link retrieveResponse} (typically
+ * after a durable suspend keyed on the returned `responseId`). It is the
+ * provider capability the pipeline's `launchStage` needs.
+ *
+ * **Terminal-on-submit fast-path:** a small/cached request can come back
+ * already terminal (`completed`/`failed`/`incomplete`/`cancelled`) on the
+ * submit POST. This function still returns `{ responseId, status }` for
+ * that case (no throw, no poll); the caller proceeds to
+ * `retrieveResponse(responseId)`, which sees the terminal state
+ * immediately.
+ *
+ * **No-tools precondition:** background mode does not support function
+ * tools in V1 — a tool-bearing request throws {@link NonRetryableLlmError},
+ * matching `respond`'s background guard.
+ *
+ * @param req - The structured-output request (system/user prompts +
+ *   `outputSchema` + model knobs). Tools are rejected.
+ * @param options - `apiKey`, optional `baseUrl`, `fetch`, and `signal`.
+ */
+export async function submitBackgroundResponse(req, options) {
+    if (req.tools && req.tools.length > 0) {
+        throw new NonRetryableLlmError({
+            message: "OpenAI background mode does not support function tools in V1. Disable backgroundMode / backgroundStreamMode for tool-using requests, or run the tools synchronously.",
+        });
+    }
+    const fetchImpl = resolveFetch(options.fetch, "submitBackgroundResponse");
+    const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+    const schemaName = deriveSchemaName(req.outputSchema);
+    const convertedSchema = typeboxToOpenAiSchema(req.outputSchema);
+    const body = {
+        model: req.model,
+        input: [
+            { role: "system", content: req.systemPrompt },
+            { role: "user", content: req.userMessage },
+        ],
+        text: {
+            format: {
+                type: "json_schema",
+                name: schemaName,
+                strict: true,
+                schema: convertedSchema,
+            },
+        },
+        background: true,
+        store: true,
+    };
+    if (req.maxOutputTokens !== undefined) {
+        body.max_output_tokens = req.maxOutputTokens;
+    }
+    if (req.reasoningEffort) {
+        body.reasoning = { effort: req.reasoningEffort };
+    }
+    const submit = await callOnce({
+        url: baseUrl,
+        apiKey: options.apiKey,
+        body,
+        fetchImpl,
+        signal: req.signal ?? options.signal,
+    });
+    const submitEnvelope = await parseJsonOrThrowTransient(submit, "OpenAI background submit body was not valid JSON");
+    const id = submitEnvelope.id;
+    if (!id) {
+        throw new TransientLlmError({
+            message: "OpenAI background submit returned no response id.",
+        });
+    }
+    // Return at submit — including the terminal-on-submit fast-path. Unlike
+    // `runBackground`, a `cancelled` submit envelope is NOT thrown here: the
+    // submit-only contract returns every terminal status, and the caller's
+    // completion step classifies it (a cancelled response settles as a skip).
+    return {
+        responseId: id,
+        status: (submitEnvelope.status ?? "queued"),
+    };
+}
+function envelopeToRetrievedResponse(envelope, id) {
+    const output = extractAssistantText(envelope.output);
+    const usage = extractUsage(envelope);
+    const result = {
+        status: (envelope.status ?? "in_progress"),
+        rawResponseId: envelope.id ?? id,
+    };
+    if (output !== undefined) {
+        result.output = output;
+    }
+    if (usage.input > 0 || usage.output > 0) {
+        result.tokenUsage = usage;
+    }
+    // Surface the incomplete reason / error message so a completion-side
+    // consumer (e.g. `completeStage`) can classify the outcome.
+    const incompleteReason = envelope.incomplete_details?.reason;
+    if (incompleteReason !== undefined) {
+        result.incompleteReason = incompleteReason;
+    }
+    const errorMessage = envelope.error?.message;
+    if (errorMessage !== undefined) {
+        result.errorMessage = errorMessage;
+    }
+    return result;
+}
+//# sourceMappingURL=openai-retrieval.js.map

package/dist/extensions/openai/openai-retrieval.js.map

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

package/dist/extensions/openai/openai-tools.d.ts

@@ -0,0 +1,9 @@
+import type { TSchema } from "typebox";
+import type { TToolSpec } from "../../lib/llm/types.js";
+import type { TOpenAiTool } from "./types.js";
+export declare function translateTools(tools: readonly TToolSpec[]): TOpenAiTool[];
+export declare function findFunctionHandler(tools: readonly TToolSpec[] | undefined, name: string): Extract<TToolSpec, {
+    kind: "function";
+}> | undefined;
+export declare function deriveSchemaName(schema: TSchema): string;
+//# sourceMappingURL=openai-tools.d.ts.map

package/dist/extensions/openai/openai-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-tools.d.ts","sourceRoot":"","sources":["../../../src/extensions/openai/openai-tools.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAEvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAI7C,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,WAAW,EAAE,CAiCzE;AAED,wBAAgB,mBAAmB,CAC/B,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,EACvC,IAAI,EAAE,MAAM,GACb,OAAO,CAAC,SAAS,EAAE;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,GAAG,SAAS,CAQtD;AAID,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAOxD"}

package/dist/extensions/openai/openai-tools.js

@@ -0,0 +1,93 @@
+// Translation of the framework's `TToolSpec` discriminated union into
+// the OpenAI Responses-API tool wire format, plus the structured-output
+// schema-name derivation (a stable, OpenAI-name-safe identifier for each
+// response schema). These are pure helpers with no captured state.
+import { typeboxToOpenAiSchema } from "./structured-output.js";
+// -- tool translation --
+export function translateTools(tools) {
+    return tools.map((tool) => {
+        switch (tool.kind) {
+            case "web_search":
+                return { type: "web_search" };
+            case "file_search":
+                return {
+                    type: "file_search",
+                    vector_store_ids: [tool.vectorStoreId],
+                };
+            case "mcp": {
+                const out = {
+                    type: "mcp",
+                    server_url: tool.serverUrl,
+                };
+                if (tool.toolName) {
+                    return {
+                        ...out,
+                        allowed_tools: [tool.toolName],
+                    };
+                }
+                return out;
+            }
+            case "function":
+                return {
+                    type: "function",
+                    name: tool.name,
+                    description: tool.description,
+                    parameters: typeboxToOpenAiSchema(tool.parameters),
+                    strict: true,
+                };
+        }
+    });
+}
+export function findFunctionHandler(tools, name) {
+    if (!tools)
+        return undefined;
+    for (const tool of tools) {
+        if (tool.kind === "function" && tool.name === name) {
+            return tool;
+        }
+    }
+    return undefined;
+}
+// -- schema name derivation --
+export function deriveSchemaName(schema) {
+    const id = schema.$id;
+    if (typeof id === "string" && id.length > 0) {
+        return sanitizeName(id);
+    }
+    const serialized = canonicalJson(schema);
+    return `schema_${shortHash(serialized)}`;
+}
+function sanitizeName(raw) {
+    // OpenAI requires schema names match `^[a-zA-Z0-9_-]{1,64}$`.
+    const cleaned = raw.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64);
+    return cleaned.length > 0 ? cleaned : "schema";
+}
+function canonicalJson(value) {
+    return JSON.stringify(value, (_key, v) => {
+        if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+            const obj = v;
+            const sorted = {};
+            for (const key of Object.keys(obj).sort()) {
+                sorted[key] = obj[key];
+            }
+            return sorted;
+        }
+        return v;
+    });
+}
+function shortHash(input) {
+    // Stable 12-hex-char hash. We avoid pulling `crypto.subtle` because
+    // it's async and would force `deriveSchemaName` to be async too;
+    // FNV-1a is sufficient for naming uniqueness within a process.
+    let h1 = 0xcbf29ce4;
+    let h2 = 0x84222325;
+    for (let i = 0; i < input.length; i += 1) {
+        const c = input.charCodeAt(i);
+        h1 = Math.imul(h1 ^ c, 0x01000193) >>> 0;
+        h2 = Math.imul(h2 ^ c, 0x01000193) >>> 0;
+    }
+    const hex1 = h1.toString(16).padStart(8, "0");
+    const hex2 = h2.toString(16).padStart(8, "0");
+    return (hex1 + hex2).slice(0, 12);
+}
+//# sourceMappingURL=openai-tools.js.map

package/dist/extensions/openai/openai-tools.js.map

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