@asap-protocol/openai-agents 2.3.1

package/dist/commonjs/schema-bridge.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zodFromJsonSchema = zodFromJsonSchema;
+const zod_1 = require("zod");
+function enumLiteralKind(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return typeof value;
+    }
+    return "unsupported";
+}
+function zodFromJsonSchemaEnum(enumValues) {
+    if (enumValues.length === 0) {
+        throw new Error("JSON Schema enum must contain at least one value");
+    }
+    const kinds = new Set();
+    for (const value of enumValues) {
+        kinds.add(enumLiteralKind(value));
+    }
+    if (kinds.has("unsupported")) {
+        throw new Error("JSON Schema enum supports only string, number, boolean, and null literals");
+    }
+    const nonNullKinds = [...kinds].filter((kind) => kind !== "null");
+    if (nonNullKinds.length > 1) {
+        throw new Error(`JSON Schema enum with mixed primitive types is unsupported (found: ${[...kinds].join(", ")})`);
+    }
+    const literals = enumValues.map((value) => {
+        if (value === null) {
+            return zod_1.z.null();
+        }
+        if (typeof value === "string") {
+            return zod_1.z.literal(value);
+        }
+        if (typeof value === "number") {
+            return zod_1.z.literal(value);
+        }
+        return zod_1.z.literal(value);
+    });
+    return literals.length === 1
+        ? literals[0]
+        : zod_1.z.union(literals);
+}
+/**
+ * Minimal JSON Schema → Zod bridge for adapter tool schemas (subset only).
+ *
+ * Lossy for `$ref` / complex `oneOf`; mirrors `@asap-protocol/mastra` / legacy Chat Completions adapter patterns.
+ */
+function zodFromJsonSchema(schema) {
+    if ("$ref" in schema) {
+        return zod_1.z.record(zod_1.z.string(), zod_1.z.unknown());
+    }
+    if ("oneOf" in schema && Array.isArray(schema.oneOf)) {
+        const branches = schema.oneOf
+            .filter((s) => typeof s === "object" && s !== null && !Array.isArray(s))
+            .map((s) => zodFromJsonSchema(s));
+        return branches.length === 0
+            ? zod_1.z.unknown()
+            : branches.length === 1
+                ? branches[0]
+                : zod_1.z.union(branches);
+    }
+    if ("enum" in schema && Array.isArray(schema.enum) && schema.enum.length > 0) {
+        return zodFromJsonSchemaEnum(schema.enum);
+    }
+    switch (schema.type) {
+        case "object": {
+            const maybeProps = schema.properties;
+            if (maybeProps !== undefined &&
+                typeof maybeProps === "object" &&
+                maybeProps !== null &&
+                !Array.isArray(maybeProps)) {
+                const propsRecord = maybeProps;
+                const required = new Set(Array.isArray(schema.required) ? schema.required.filter((k) => typeof k === "string") : []);
+                const shape = {};
+                for (const [key, val] of Object.entries(propsRecord)) {
+                    if (typeof val === "object" && val !== null && !Array.isArray(val)) {
+                        const child = zodFromJsonSchema(val);
+                        shape[key] = required.has(key) ? child : child.optional();
+                    }
+                }
+                if (Object.keys(shape).length > 0) {
+                    return zod_1.z.object(shape);
+                }
+            }
+            return zod_1.z.record(zod_1.z.string(), zod_1.z.unknown());
+        }
+        case "string":
+            return zod_1.z.string();
+        case "number":
+        case "integer":
+            return zod_1.z.number();
+        case "boolean":
+            return zod_1.z.boolean();
+        case "array": {
+            const items = schema.items;
+            if (typeof items === "object" && items !== null && !Array.isArray(items)) {
+                return zod_1.z.array(zodFromJsonSchema(items));
+            }
+            return zod_1.z.array(zod_1.z.unknown());
+        }
+        default:
+            return zod_1.z.record(zod_1.z.string(), zod_1.z.unknown());
+    }
+}

package/dist/commonjs/send-asap-envelope.d.ts

@@ -0,0 +1,16 @@
+export type SendAsapFetch = typeof fetch;
+export interface SendAsapEnvelopeOptions {
+    readonly fetch?: SendAsapFetch;
+    readonly signal?: AbortSignal;
+    /** When set, sends `Authorization: Bearer <token>`. */
+    readonly agentJwt?: string;
+    /** Sent as `ASAP-Version` (default `2.2`). */
+    readonly asapVersion?: string;
+}
+/**
+ * POST a JSON-RPC `asap.send` request to the provider's `/asap` endpoint.
+ *
+ * @throws When HTTP status is not ok or the JSON-RPC response contains an error.
+ */
+export declare function sendAsapEnvelope(provider: URL, envelope: Record<string, unknown>, options?: SendAsapEnvelopeOptions): Promise<unknown>;
+//# sourceMappingURL=send-asap-envelope.d.ts.map

package/dist/commonjs/send-asap-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"send-asap-envelope.d.ts","sourceRoot":"","sources":["../../src/send-asap-envelope.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,aAAa,GAAG,OAAO,KAAK,CAAC;AAEzC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAiED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,GAAG,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,OAAO,CAAC,CAqClB"}

package/dist/commonjs/send-asap-envelope.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendAsapEnvelope = sendAsapEnvelope;
+const client_1 = require("@asap-protocol/client");
+const DEFAULT_ASAP_VERSION = "2.2";
+/** Base URL with trailing slash for safe relative resolution of `asap/...` paths. */
+function providerBaseHref(provider) {
+    const href = provider.href;
+    return provider.pathname.endsWith("/") ? href : `${href}/`;
+}
+function asapSendHref(provider) {
+    return new URL("asap", providerBaseHref(provider)).href;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function jsonRpcErrorToError(error) {
+    if (!isRecord(error)) {
+        return new Error(String(error));
+    }
+    const message = typeof error.message === "string" ? error.message : JSON.stringify(error);
+    const err = new Error(message);
+    err.name = "JsonRpcError";
+    if (typeof error.code === "number") {
+        err.code = error.code;
+    }
+    return err;
+}
+function parseJsonRpcResult(payload) {
+    if (!isRecord(payload)) {
+        return payload;
+    }
+    if (payload.jsonrpc !== "2.0") {
+        return payload;
+    }
+    if (payload.error !== undefined && payload.error !== null) {
+        throw jsonRpcErrorToError(payload.error);
+    }
+    return payload.result;
+}
+function normalizeEnvelopeForSend(envelope) {
+    return {
+        ...envelope,
+        id: typeof envelope.id === "string" ? envelope.id : crypto.randomUUID(),
+        timestamp: typeof envelope.timestamp === "string" ? envelope.timestamp : new Date().toISOString(),
+    };
+}
+function buildJsonRpcSendBody(envelope) {
+    const requestId = crypto.randomUUID();
+    const idempotencyKey = crypto.randomUUID();
+    const jsonRpcRequest = {
+        jsonrpc: "2.0",
+        method: client_1.ASAP_SEND_METHOD,
+        params: {
+            envelope,
+            idempotency_key: idempotencyKey,
+        },
+        id: requestId,
+    };
+    return { body: JSON.stringify(jsonRpcRequest), idempotencyKey };
+}
+/**
+ * POST a JSON-RPC `asap.send` request to the provider's `/asap` endpoint.
+ *
+ * @throws When HTTP status is not ok or the JSON-RPC response contains an error.
+ */
+async function sendAsapEnvelope(provider, envelope, options) {
+    const fetchFn = options?.fetch ?? globalThis.fetch.bind(globalThis);
+    const asapVersion = options?.asapVersion ?? DEFAULT_ASAP_VERSION;
+    const wireEnvelope = normalizeEnvelopeForSend(envelope);
+    const { body, idempotencyKey } = buildJsonRpcSendBody(wireEnvelope);
+    const headers = {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "X-Idempotency-Key": idempotencyKey,
+        [client_1.ASAP_VERSION_HEADER]: asapVersion,
+    };
+    if (options?.agentJwt !== undefined && options.agentJwt.length > 0) {
+        headers.Authorization = `Bearer ${options.agentJwt}`;
+    }
+    const response = await fetchFn(asapSendHref(provider), {
+        method: "POST",
+        headers,
+        body,
+        signal: options?.signal,
+    });
+    const text = await response.text();
+    let parsed;
+    try {
+        parsed = text.length === 0 ? {} : JSON.parse(text);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`asap.send: invalid JSON (${msg})`);
+    }
+    if (!response.ok) {
+        throw new Error(`asap.send failed: HTTP ${String(response.status)} ${text.slice(0, 200)}`);
+    }
+    return parseJsonRpcResult(parsed);
+}

package/dist/commonjs/streaming.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Bridge ASAP TaskStream-style payloads into UTF-8 text chunks suitable for OpenAI Agents streaming UX.
+ *
+ * Pair with `@asap-protocol/client` streaming helpers (`createAsapStreamClient`, `streamTaskStreamEnvelopes`).
+ */
+/** Streaming text delta aligned with incremental assistant output (surface-only shape). */
+export interface OpenAIAgentsStreamTextDelta {
+    readonly type: "text_delta";
+    readonly text: string;
+}
+export declare function asapStreamToOpenAIAgentsTextStream(source: AsyncIterable<unknown>): AsyncIterable<string>;
+/**
+ * Same mapping as {@link asapStreamToOpenAIAgentsTextStream}, wrapped as `{ type: "text_delta" }` chunks.
+ */
+export declare function asapStreamToOpenAIAgentsRunStreamChunks(source: AsyncIterable<unknown>): AsyncIterable<OpenAIAgentsStreamTextDelta>;
+//# sourceMappingURL=streaming.d.ts.map

package/dist/commonjs/streaming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../../src/streaming.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,2FAA2F;AAC3F,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wBAAuB,kCAAkC,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,CAuB/G;AAED;;GAEG;AACH,wBAAuB,uCAAuC,CAC5D,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,GAC7B,aAAa,CAAC,2BAA2B,CAAC,CAI5C"}

package/dist/commonjs/streaming.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Bridge ASAP TaskStream-style payloads into UTF-8 text chunks suitable for OpenAI Agents streaming UX.
+ *
+ * Pair with `@asap-protocol/client` streaming helpers (`createAsapStreamClient`, `streamTaskStreamEnvelopes`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asapStreamToOpenAIAgentsTextStream = asapStreamToOpenAIAgentsTextStream;
+exports.asapStreamToOpenAIAgentsRunStreamChunks = asapStreamToOpenAIAgentsRunStreamChunks;
+function isRecord(x) {
+    return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+async function* asapStreamToOpenAIAgentsTextStream(source) {
+    const it = source[Symbol.asyncIterator]();
+    try {
+        while (true) {
+            const { value: event, done } = await it.next();
+            if (done) {
+                return;
+            }
+            if (!isRecord(event) || event.type !== "task_stream") {
+                continue;
+            }
+            const payload = event.payload;
+            if (!isRecord(payload)) {
+                continue;
+            }
+            const chunk = payload.chunk;
+            if (typeof chunk === "string") {
+                yield chunk;
+            }
+        }
+    }
+    finally {
+        await it.return?.();
+    }
+}
+/**
+ * Same mapping as {@link asapStreamToOpenAIAgentsTextStream}, wrapped as `{ type: "text_delta" }` chunks.
+ */
+async function* asapStreamToOpenAIAgentsRunStreamChunks(source) {
+    for await (const text of asapStreamToOpenAIAgentsTextStream(source)) {
+        yield { type: "text_delta", text };
+    }
+}

package/dist/esm/asap-as-remote-agent.d.ts

@@ -0,0 +1,44 @@
+import { Agent, type AgentInputItem } from "@openai/agents";
+import type { AsapExecuteClient } from "@asap-protocol/client/adapters/shared";
+import { type AsapToolsForOpenAIAgentsOptions } from "./asap-to-openai-tool.js";
+export type AsapRemoteAgentMode = "delegated" | "autonomous";
+/** Mutable bag carried through {@link RunContext} when using {@link asapAsRemoteAgent}. */
+export interface AsapRemoteRunContext {
+    /** Latest draft ASAP envelope captured when this agent starts (including after an SDK handoff). */
+    lastAsapHandoffEnvelope?: Record<string, unknown>;
+}
+export interface AsapAsRemoteAgentOptions {
+    readonly mode?: AsapRemoteAgentMode;
+    readonly name?: string;
+    readonly instructions?: string | undefined;
+    readonly handoffDescription?: string;
+    readonly model?: string;
+    readonly toolsOptions?: AsapToolsForOpenAIAgentsOptions;
+    /**
+     * Agent JWT scoped to `providerUrl` when it differs from `client.provider`.
+     * Required for cross-provider handoffs when `client.agentJwt` is set.
+     */
+    readonly remoteAgentJwt?: string;
+}
+/**
+ * Returns whether two provider URLs refer to the same ASAP host path (origin + pathname).
+ */
+export declare function sameProviderOrigin(a: URL, b: URL): boolean;
+/**
+ * Draft `task.request`-style envelope metadata used when delegating from OpenAI Agents handoffs to ASAP.
+ *
+ * The gateway still performs authorization and routing; this object mirrors how adapters attach agent mode.
+ */
+export declare function draftTaskRequestEnvelopeForRemoteAgent(params: {
+    readonly mode: AsapRemoteAgentMode;
+    readonly providerUrl: URL;
+    readonly turnInput?: string | AgentInputItem[];
+}): Record<string, unknown>;
+/**
+ * Returns an OpenAI Agents {@link Agent} backed by ASAP capability tools on `providerUrl`.
+ *
+ * Subscribes to `agent_start` so {@link AsapRemoteRunContext.lastAsapHandoffEnvelope} captures draft envelope metadata
+ * and POSTs a real `task.request` via JSON-RPC `asap.send` whenever this agent begins a turn—including after an SDK handoff.
+ */
+export declare function asapAsRemoteAgent(client: AsapExecuteClient, providerUrl: string | URL, options?: AsapAsRemoteAgentOptions): Promise<Agent<AsapRemoteRunContext>>;
+//# sourceMappingURL=asap-as-remote-agent.d.ts.map

package/dist/esm/asap-as-remote-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asap-as-remote-agent.d.ts","sourceRoot":"","sources":["../../src/asap-as-remote-agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE/E,OAAO,EACL,KAAK,+BAA+B,EAErC,MAAM,0BAA0B,CAAC;AAGlC,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,YAAY,CAAC;AAE7D,2FAA2F;AAC3F,MAAM,WAAW,oBAAoB;IACnC,mGAAmG;IACnG,uBAAuB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,mBAAmB,CAAC;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,+BAA+B,CAAC;IACxD;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAgBD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,OAAO,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,sCAAsC,CAAC,MAAM,EAAE;IAC7D,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE,CAAC;CAChD,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmB1B;AAgDD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,iBAAiB,EACzB,WAAW,EAAE,MAAM,GAAG,GAAG,EACzB,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAgCtC"}

package/dist/esm/asap-as-remote-agent.js

@@ -0,0 +1,114 @@
+import { Agent } from "@openai/agents";
+import { asapToolsForOpenAIAgents, } from "./asap-to-openai-tool.js";
+import { sendAsapEnvelope } from "./send-asap-envelope.js";
+function serializeTurnInput(turnInput) {
+    if (turnInput === undefined) {
+        return "";
+    }
+    if (typeof turnInput === "string") {
+        return turnInput;
+    }
+    try {
+        return JSON.stringify(turnInput);
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Returns whether two provider URLs refer to the same ASAP host path (origin + pathname).
+ */
+export function sameProviderOrigin(a, b) {
+    return a.origin === b.origin && a.pathname === b.pathname;
+}
+/**
+ * Draft `task.request`-style envelope metadata used when delegating from OpenAI Agents handoffs to ASAP.
+ *
+ * The gateway still performs authorization and routing; this object mirrors how adapters attach agent mode.
+ */
+export function draftTaskRequestEnvelopeForRemoteAgent(params) {
+    const delegatedInput = serializeTurnInput(params.turnInput);
+    return {
+        asap_version: "2.2",
+        sender: "urn:asap:agent:openai-agents-adapter",
+        recipient: params.providerUrl.href,
+        payload_type: "task.request",
+        payload: {
+            conversation_id: "openai-agents-handoff",
+            skill_id: "asap-remote-handoff",
+            input: {
+                query: delegatedInput,
+                asap_agent_mode: params.mode,
+            },
+        },
+        extensions: {
+            asap_agent_mode: params.mode,
+        },
+    };
+}
+function defaultInstructions(mode, capabilities) {
+    const list = capabilities.length > 0 ? capabilities.join(", ") : "(none configured)";
+    return [
+        "You are an ASAP-backed specialist agent invoked via OpenAI Agents SDK handoffs.",
+        `Operate in ${mode} mode with respect to host policy.`,
+        `Use the ASAP capability tools wired for this agent (deterministic keys). Capability URNs: ${list}.`,
+        "Pass structured JSON arguments that satisfy each capability schema.",
+    ].join(" ");
+}
+function resolveProvider(providerUrl) {
+    return typeof providerUrl === "string" ? new URL(providerUrl) : providerUrl;
+}
+function resolveHandoffJwt(client, providerUrl, options) {
+    if (options?.remoteAgentJwt !== undefined) {
+        return options.remoteAgentJwt;
+    }
+    if (client.agentJwt !== undefined && !sameProviderOrigin(client.provider, providerUrl)) {
+        throw new Error(`client.agentJwt is scoped to ${client.provider.href}; pass remoteAgentJwt when providerUrl (${providerUrl.href}) differs`);
+    }
+    return client.agentJwt;
+}
+function buildMergedClient(client, resolvedProvider, handoffJwt) {
+    const merged = {
+        ...client,
+        provider: resolvedProvider,
+    };
+    if (handoffJwt !== undefined) {
+        return { ...merged, agentJwt: handoffJwt };
+    }
+    const { agentJwt: _omit, ...withoutJwt } = merged;
+    return withoutJwt;
+}
+/**
+ * Returns an OpenAI Agents {@link Agent} backed by ASAP capability tools on `providerUrl`.
+ *
+ * Subscribes to `agent_start` so {@link AsapRemoteRunContext.lastAsapHandoffEnvelope} captures draft envelope metadata
+ * and POSTs a real `task.request` via JSON-RPC `asap.send` whenever this agent begins a turn—including after an SDK handoff.
+ */
+export async function asapAsRemoteAgent(client, providerUrl, options) {
+    const mode = options?.mode ?? "delegated";
+    const resolvedProvider = resolveProvider(providerUrl);
+    const handoffJwt = resolveHandoffJwt(client, resolvedProvider, options);
+    const mergedClient = buildMergedClient(client, resolvedProvider, handoffJwt);
+    const tools = await asapToolsForOpenAIAgents(mergedClient, options?.toolsOptions);
+    const agent = new Agent({
+        name: options?.name ?? `asap-remote-${resolvedProvider.hostname}`,
+        instructions: options?.instructions ?? defaultInstructions(mode, mergedClient.capabilities),
+        handoffDescription: options?.handoffDescription ??
+            `Delegates to ASAP capabilities at ${resolvedProvider.href} (${mode} mode).`,
+        model: options?.model ?? "gpt-4o-mini",
+        tools: [...tools],
+    });
+    agent.on("agent_start", (runContext, _self, turnInput) => {
+        const draft = draftTaskRequestEnvelopeForRemoteAgent({
+            mode,
+            providerUrl: resolvedProvider,
+            turnInput,
+        });
+        runContext.context.lastAsapHandoffEnvelope = draft;
+        void sendAsapEnvelope(resolvedProvider, draft, {
+            fetch: mergedClient.fetch,
+            agentJwt: mergedClient.agentJwt,
+        });
+    });
+    return agent;
+}

package/dist/esm/asap-to-openai-tool.d.ts

@@ -0,0 +1,34 @@
+import { tool } from "@openai/agents";
+import { type AsapExecuteClient } from "@asap-protocol/client/adapters/shared";
+export interface AsapToolsForOpenAIAgentsOptions {
+    /**
+     * Invoked when the provider returns `403` with `error.code === "capability_not_granted"`.
+     */
+    readonly requestCapability?: (requiredCapability: string) => void | Promise<void>;
+    readonly inputSchemas?: Readonly<Record<string, unknown>>;
+    readonly outputSchemas?: Readonly<Record<string, unknown>>;
+    /**
+     * Called when {@link describeCapability} fails for a capability. The error is rethrown unless
+     * {@link allowPermissiveDescribeFallback} is `true`.
+     */
+    readonly onDescribeError?: (capabilityId: string, error: unknown) => void;
+    /**
+     * When `true`, failed describe calls fall back to generic tool metadata instead of failing
+     * tool construction. Defaults to `false`.
+     */
+    readonly allowPermissiveDescribeFallback?: boolean;
+    /** Passed to {@link describeCapability} and {@link executeCapability} fetch calls. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Build OpenAI Agents SDK {@link tool} instances for each ASAP capability on the client.
+ *
+ * Uses top-level {@link executeCapability} from `@asap-protocol/client` on each execution path.
+ */
+export declare function asapToolsForOpenAIAgents(client: AsapExecuteClient, options?: AsapToolsForOpenAIAgentsOptions): Promise<readonly ReturnType<typeof tool>[]>;
+/**
+ * Synchronous variant when {@link AsapToolsForOpenAIAgentsOptions.inputSchemas} / `outputSchemas`
+ * are already materialized (skips describe round-trips).
+ */
+export declare function asapToolsForOpenAIAgentsSync(client: AsapExecuteClient, options?: AsapToolsForOpenAIAgentsOptions): readonly ReturnType<typeof tool>[];
+//# sourceMappingURL=asap-to-openai-tool.d.ts.map

package/dist/esm/asap-to-openai-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asap-to-openai-tool.d.ts","sourceRoot":"","sources":["../../src/asap-to-openai-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtC,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,uCAAuC,CAAC;AAiC/C,MAAM,WAAW,+BAA+B;IAC9C;;OAEG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,kBAAkB,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClF,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3D;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC1E;;;OAGG;IACH,QAAQ,CAAC,+BAA+B,CAAC,EAAE,OAAO,CAAC;IACnD,sFAAsF;IACtF,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAuID;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,+BAA+B,GACxC,OAAO,CAAC,SAAS,UAAU,CAAC,OAAO,IAAI,CAAC,EAAE,CAAC,CA4C7C;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,+BAA+B,GACxC,SAAS,UAAU,CAAC,OAAO,IAAI,CAAC,EAAE,CAepC"}

package/dist/esm/asap-to-openai-tool.js

@@ -0,0 +1,168 @@
+import { tool } from "@openai/agents";
+import { describeCapability, executeCapability } from "@asap-protocol/client";
+import { capabilityToolKey, jsonSchemaForCapabilityInput, } from "@asap-protocol/client/adapters/shared";
+import { z } from "zod";
+import { ApprovalRequiredError, CapabilityNotGrantedError } from "./errors.js";
+import { zodFromJsonSchema } from "./schema-bridge.js";
+function buildToolParameters(inputJson) {
+    const props = inputJson.properties;
+    const hasProps = inputJson.type === "object" &&
+        typeof props === "object" &&
+        props !== null &&
+        !Array.isArray(props) &&
+        Object.keys(props).length > 0;
+    if (hasProps) {
+        const zSch = zodFromJsonSchema(inputJson);
+        if (zSch instanceof z.ZodObject) {
+            return { mode: "zod", schema: zSch.strict() };
+        }
+    }
+    return { mode: "json", schema: inputJson };
+}
+const DESCRIBE_CONCURRENCY = 5;
+async function mapInBatches(items, batchSize, fn) {
+    const results = [];
+    for (let i = 0; i < items.length; i += batchSize) {
+        const batch = items.slice(i, i + batchSize);
+        const batchResults = await Promise.all(batch.map(fn));
+        results.push(...batchResults);
+    }
+    return results;
+}
+function isRecord(x) {
+    return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+function wrapFetchWithCapabilityErrors(base, options) {
+    const impl = base ?? globalThis.fetch;
+    return async (input, init) => {
+        const res = await impl(input, init);
+        if (res.status !== 403) {
+            return res;
+        }
+        const text = await res.clone().text();
+        let parsed;
+        try {
+            parsed = text.length === 0 ? {} : JSON.parse(text);
+        }
+        catch {
+            return new Response(text, { status: res.status, statusText: res.statusText, headers: res.headers });
+        }
+        if (!isRecord(parsed)) {
+            return new Response(text, { status: res.status, statusText: res.statusText, headers: res.headers });
+        }
+        if (parsed.error === "constraint_violated") {
+            return new Response(text, { status: res.status, statusText: res.statusText, headers: res.headers });
+        }
+        const errObj = parsed.error;
+        if (!isRecord(errObj)) {
+            return new Response(text, { status: res.status, statusText: res.statusText, headers: res.headers });
+        }
+        const code = errObj.code;
+        if (code === "capability_not_granted") {
+            const data = isRecord(errObj.data) ? errObj.data : undefined;
+            const required = typeof data?.required_capability === "string" ? data.required_capability : "";
+            const msg = typeof errObj.message === "string" ? errObj.message : undefined;
+            throw new CapabilityNotGrantedError(required, options?.requestCapability, msg);
+        }
+        if (code === "approval_required") {
+            const msg = typeof errObj.message === "string" ? errObj.message : "Capability execution requires approval";
+            throw new ApprovalRequiredError(msg, errObj.data);
+        }
+        return new Response(text, { status: res.status, statusText: res.statusText, headers: res.headers });
+    };
+}
+function buildTools(client, fetchFn, describedByCapability, options) {
+    const tools = [];
+    const seenToolNames = new Map();
+    for (const capabilityId of client.capabilities) {
+        const id = capabilityToolKey(capabilityId);
+        const existingCapabilityId = seenToolNames.get(id);
+        if (existingCapabilityId !== undefined && existingCapabilityId !== capabilityId) {
+            throw new Error(`OpenAI Agents tool name collision: "${id}" maps to both "${existingCapabilityId}" and "${capabilityId}". ` +
+                "Use distinct capability identifiers or provide inputSchemas to skip describe.");
+        }
+        seenToolNames.set(id, capabilityId);
+        const described = describedByCapability.get(capabilityId);
+        const inputJson = jsonSchemaForCapabilityInput(options?.inputSchemas?.[capabilityId] ?? described?.input_schema);
+        const built = buildToolParameters(inputJson);
+        const exec = async (input) => {
+            const ctx = isRecord(input) ? input : {};
+            return executeCapability(client.provider, capabilityId, ctx, {
+                agentJwt: client.agentJwt,
+                fetch: fetchFn,
+                signal: options?.signal,
+            });
+        };
+        if (built.mode === "zod") {
+            tools.push(tool({
+                name: id,
+                description: described?.description ?? `ASAP capability: ${capabilityId}`,
+                parameters: built.schema,
+                strict: true,
+                errorFunction: null,
+                execute: exec,
+            }));
+        }
+        else {
+            tools.push(tool({
+                name: id,
+                description: described?.description ?? `ASAP capability: ${capabilityId}`,
+                parameters: built.schema,
+                strict: false,
+                errorFunction: null,
+                execute: exec,
+            }));
+        }
+    }
+    return tools;
+}
+/**
+ * Build OpenAI Agents SDK {@link tool} instances for each ASAP capability on the client.
+ *
+ * Uses top-level {@link executeCapability} from `@asap-protocol/client` on each execution path.
+ */
+export async function asapToolsForOpenAIAgents(client, options) {
+    const fetchFn = wrapFetchWithCapabilityErrors(client.fetch, options);
+    const describedByCapability = new Map();
+    const toDescribe = client.capabilities.filter((capabilityId) => options?.inputSchemas?.[capabilityId] === undefined);
+    for (const capabilityId of client.capabilities) {
+        if (options?.inputSchemas?.[capabilityId] !== undefined) {
+            describedByCapability.set(capabilityId, undefined);
+        }
+    }
+    await mapInBatches(toDescribe, DESCRIBE_CONCURRENCY, async (capabilityId) => {
+        try {
+            const described = await describeCapability(client.provider, capabilityId, {
+                fetch: fetchFn,
+                agentJwt: client.agentJwt,
+                signal: options?.signal,
+            });
+            describedByCapability.set(capabilityId, {
+                description: described.description,
+                input_schema: described.input_schema,
+                output_schema: described.output_schema,
+            });
+        }
+        catch (error) {
+            options?.onDescribeError?.(capabilityId, error);
+            if (options?.allowPermissiveDescribeFallback === true) {
+                describedByCapability.set(capabilityId, undefined);
+                return;
+            }
+            throw error;
+        }
+    });
+    return buildTools(client, fetchFn, describedByCapability, options);
+}
+/**
+ * Synchronous variant when {@link AsapToolsForOpenAIAgentsOptions.inputSchemas} / `outputSchemas`
+ * are already materialized (skips describe round-trips).
+ */
+export function asapToolsForOpenAIAgentsSync(client, options) {
+    const fetchFn = wrapFetchWithCapabilityErrors(client.fetch, options);
+    const describedByCapability = new Map();
+    for (const capabilityId of client.capabilities) {
+        describedByCapability.set(capabilityId, undefined);
+    }
+    return buildTools(client, fetchFn, describedByCapability, options);
+}