@asap-protocol/openai-agents 2.3.1

package/dist/esm/errors.d.ts

@@ -0,0 +1,27 @@
+export { FatalError, RecoverableError, RemoteFatalRPCError, RemoteRecoverableRPCError, } from "@asap-protocol/client";
+/**
+ * Structured `approval_required` payload (`error.data`) from an ASAP provider JSON body.
+ */
+export interface ApprovalRequiredDetail {
+    readonly reason?: string;
+    readonly approval_url?: string;
+}
+/**
+ * Raised when the provider indicates an approval step is required before the capability can run.
+ */
+export declare class ApprovalRequiredError extends Error {
+    readonly name = "ApprovalRequiredError";
+    readonly detail?: ApprovalRequiredDetail;
+    constructor(message?: string, detail?: unknown);
+}
+/**
+ * Raised when the agent JWT is valid but the capability is not granted (HTTP 403 `capability_not_granted`).
+ */
+export declare class CapabilityNotGrantedError extends Error {
+    readonly name = "CapabilityNotGrantedError";
+    readonly requiredCapability: string;
+    private readonly hook?;
+    constructor(requiredCapability: string, requestCapability?: (capability: string) => void | Promise<void>, message?: string);
+    requestCapability(): void | Promise<void>;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/esm/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAE/B;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAmBD;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAkB,IAAI,2BAA2B;IAEjD,QAAQ,CAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC;gBAE7B,OAAO,SAA2C,EAAE,MAAM,CAAC,EAAE,OAAO;CAIjF;AAED;;GAEG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,SAAkB,IAAI,+BAA+B;IAErD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IAEpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAA+C;gBAGnE,kBAAkB,EAAE,MAAM,EAC1B,iBAAiB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAChE,OAAO,CAAC,EAAE,MAAM;IAOlB,iBAAiB,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAG1C"}

package/dist/esm/errors.js

@@ -0,0 +1,44 @@
+export { FatalError, RecoverableError, RemoteFatalRPCError, RemoteRecoverableRPCError, } from "@asap-protocol/client";
+function approvalDetailFromUnknown(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        return undefined;
+    }
+    const rec = data;
+    const reason = rec.reason;
+    const approval_url = rec.approval_url;
+    const detail = {};
+    if (typeof reason === "string") {
+        detail.reason = reason;
+    }
+    if (typeof approval_url === "string") {
+        detail.approval_url = approval_url;
+    }
+    return Object.keys(detail).length > 0 ? detail : undefined;
+}
+/**
+ * Raised when the provider indicates an approval step is required before the capability can run.
+ */
+export class ApprovalRequiredError extends Error {
+    name = "ApprovalRequiredError";
+    detail;
+    constructor(message = "Capability execution requires approval", detail) {
+        super(message);
+        this.detail = approvalDetailFromUnknown(detail);
+    }
+}
+/**
+ * Raised when the agent JWT is valid but the capability is not granted (HTTP 403 `capability_not_granted`).
+ */
+export class CapabilityNotGrantedError extends Error {
+    name = "CapabilityNotGrantedError";
+    requiredCapability;
+    hook;
+    constructor(requiredCapability, requestCapability, message) {
+        super(message ?? `Capability not granted: ${requiredCapability}`);
+        this.requiredCapability = requiredCapability;
+        this.hook = requestCapability;
+    }
+    requestCapability() {
+        return this.hook?.(this.requiredCapability);
+    }
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * OpenAI Agents SDK (`@openai/agents`) integration: ASAP capabilities as `tool()` and related helpers.
+ *
+ * For static `ChatCompletionTool[]` against the Chat Completions HTTP API, use `@asap-protocol/client/adapters/openai` instead.
+ */
+export { asapToolsForOpenAIAgents, asapToolsForOpenAIAgentsSync, type AsapToolsForOpenAIAgentsOptions, } from "./asap-to-openai-tool.js";
+export { asapAsRemoteAgent, draftTaskRequestEnvelopeForRemoteAgent, sameProviderOrigin, type AsapAsRemoteAgentOptions, type AsapRemoteAgentMode, type AsapRemoteRunContext, } from "./asap-as-remote-agent.js";
+export { sendAsapEnvelope, type SendAsapEnvelopeOptions, type SendAsapFetch, } from "./send-asap-envelope.js";
+export { zodFromJsonSchema } from "./schema-bridge.js";
+export { asapStreamToOpenAIAgentsRunStreamChunks, asapStreamToOpenAIAgentsTextStream, type OpenAIAgentsStreamTextDelta, } from "./streaming.js";
+export * from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,wBAAwB,EACxB,4BAA4B,EAC5B,KAAK,+BAA+B,GACrC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,iBAAiB,EACjB,sCAAsC,EACtC,kBAAkB,EAClB,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,aAAa,GACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EACL,uCAAuC,EACvC,kCAAkC,EAClC,KAAK,2BAA2B,GACjC,MAAM,gBAAgB,CAAC;AACxB,cAAc,aAAa,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,11 @@
+/**
+ * OpenAI Agents SDK (`@openai/agents`) integration: ASAP capabilities as `tool()` and related helpers.
+ *
+ * For static `ChatCompletionTool[]` against the Chat Completions HTTP API, use `@asap-protocol/client/adapters/openai` instead.
+ */
+export { asapToolsForOpenAIAgents, asapToolsForOpenAIAgentsSync, } from "./asap-to-openai-tool.js";
+export { asapAsRemoteAgent, draftTaskRequestEnvelopeForRemoteAgent, sameProviderOrigin, } from "./asap-as-remote-agent.js";
+export { sendAsapEnvelope, } from "./send-asap-envelope.js";
+export { zodFromJsonSchema } from "./schema-bridge.js";
+export { asapStreamToOpenAIAgentsRunStreamChunks, asapStreamToOpenAIAgentsTextStream, } from "./streaming.js";
+export * from "./errors.js";

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/schema-bridge.d.ts

@@ -0,0 +1,8 @@
+import { type ZodType } from "zod";
+/**
+ * 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.
+ */
+export declare function zodFromJsonSchema(schema: Record<string, unknown>): ZodType<unknown>;
+//# sourceMappingURL=schema-bridge.d.ts.map

package/dist/esm/schema-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-bridge.d.ts","sourceRoot":"","sources":["../../src/schema-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAK,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAqDtC;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CA4DnF"}

package/dist/esm/schema-bridge.js

@@ -0,0 +1,103 @@
+import { z } from "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 z.null();
+        }
+        if (typeof value === "string") {
+            return z.literal(value);
+        }
+        if (typeof value === "number") {
+            return z.literal(value);
+        }
+        return z.literal(value);
+    });
+    return literals.length === 1
+        ? literals[0]
+        : 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.
+ */
+export function zodFromJsonSchema(schema) {
+    if ("$ref" in schema) {
+        return z.record(z.string(), 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
+            ? z.unknown()
+            : branches.length === 1
+                ? branches[0]
+                : 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 z.object(shape);
+                }
+            }
+            return z.record(z.string(), z.unknown());
+        }
+        case "string":
+            return z.string();
+        case "number":
+        case "integer":
+            return z.number();
+        case "boolean":
+            return z.boolean();
+        case "array": {
+            const items = schema.items;
+            if (typeof items === "object" && items !== null && !Array.isArray(items)) {
+                return z.array(zodFromJsonSchema(items));
+            }
+            return z.array(z.unknown());
+        }
+        default:
+            return z.record(z.string(), z.unknown());
+    }
+}

package/dist/esm/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/esm/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/esm/send-asap-envelope.js

@@ -0,0 +1,97 @@
+import { ASAP_SEND_METHOD, ASAP_VERSION_HEADER } from "@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: 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.
+ */
+export 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,
+        [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/esm/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/esm/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/esm/streaming.js

@@ -0,0 +1,41 @@
+/**
+ * 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`).
+ */
+function isRecord(x) {
+    return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+export 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.
+ */
+export async function* asapStreamToOpenAIAgentsRunStreamChunks(source) {
+    for await (const text of asapStreamToOpenAIAgentsTextStream(source)) {
+        yield { type: "text_delta", text };
+    }
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@asap-protocol/openai-agents",
+  "version": "2.3.1",
+  "description": "ASAP Protocol capabilities as OpenAI Agents SDK tools (@openai/agents)",
+  "type": "module",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adriannoes/asap-protocol"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@asap-protocol/client": "^2.3.0",
+    "@openai/agents": "^0.11.0",
+    "zod": "^4.1.8"
+  },
+  "dependencies": {},
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tshy",
+    "test": "vitest run --coverage",
+    "test:no-coverage": "vitest run",
+    "lint": "eslint .",
+    "check:treeshake": "pnpm run build && agadoo ./dist/esm/index.js",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@asap-protocol/client": "workspace:*",
+    "@eslint/js": "9.18.0",
+    "@openai/agents": "^0.11.4",
+    "@types/node": "^20.19.0",
+    "@vitest/coverage-v8": "4.1.5",
+    "agadoo": "3.0.0",
+    "eslint": "9.18.0",
+    "tshy": "^3.3.2",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "8.59.1",
+    "vitest": "^4.1.1",
+    "zod": "^4.4.2"
+  },
+  "tshy": {
+    "project": "./tsconfig.build.json",
+    "exports": {
+      ".": "./src/index.ts"
+    }
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/index.d.ts",
+        "default": "./dist/commonjs/index.js"
+      }
+    }
+  },
+  "main": "./dist/commonjs/index.js",
+  "types": "./dist/commonjs/index.d.ts",
+  "module": "./dist/esm/index.js"
+}