@salesforce/sfdx-agent-harness-openai 0.0.1

package/dist/openai-approval-coordinator.js

@@ -0,0 +1,422 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { MaxTurnsExceededError, } from '@openai/agents';
+import { isAbortError } from '@salesforce/agentic-common';
+import { AgentSDKError, AgentSDKErrorType, } from '@salesforce/sfdx-agent-sdk';
+import { GenSink } from '@salesforce/sfdx-agent-sdk/harness';
+import { OpenAIEventAdapter } from './openai-event-adapter.js';
+import { teeTextStream } from './text-stream.js';
+/** Default per-`toolCallId` approval timeout — mirrors both sibling harnesses (10 min). */
+const DEFAULT_TOOL_APPROVAL_TIMEOUT_MS = 600_000;
+/**
+ * Owns one chat turn's lifecycle for a single `(agentId, threadId)`: the
+ * `@openai/agents` run(s), the per-turn `OpenAIEventAdapter`, the
+ * `GenSink<ChatEvent>` the consumer iterates, the approval settle ledgers, and a
+ * single teardown path.
+ *
+ * **Suspend / resume.** `@openai/agents` surfaces tool approvals as a batch of
+ * `result.interruptions` (`RunToolApprovalItem[]`) on the COMPLETED streamed run
+ * — not as a mid-stream event — and resumes via a FRESH `run(agent, state)`. So
+ * the pump is a loop: drain a run onto the sink, and if it completed with
+ * interruptions, settle each (policy `allow` ⇒ silent `state.approve`; `deny` ⇒
+ * silent `state.reject` with a denial message the model sees natively via a real
+ * `function_call_result`, no synthesized tool-result; `require-approval` ⇒ emit
+ * `tool-approval-request`, arm a timer, and park until the consumer settles),
+ * then re-`run(agent, state)` and drain the fresh result onto the SAME sink.
+ * Passing `session` on every resume is safe: the runner tracks
+ * `_currentTurnPersistedItemCount` on the state and persists only new items, so
+ * it stays the sole history writer with no double-write.
+ *
+ * **Idempotent settle (#589).** `approve` / `decline` are `void`-typed. A second
+ * settle on the same `toolCallId`, or a settle after the coordinator auto-resolved
+ * it (timeout / abort / dispose / pump-error), is a silent no-op — the consumer's
+ * intended outcome (id is settled) is already true. A `toolCallId` the coordinator
+ * never emitted an approval for is genuine misuse and throws
+ * `AgentSDKError(TOOL_CALL_NOT_FOUND)`.
+ *
+ * One coordinator serves one turn. `stream()` disposes any prior coordinator on
+ * the same `(agentId, threadId)` before constructing a fresh one, so a
+ * re-`stream()` mid-turn can't leave a stale pump running.
+ */
+export class OpenAIApprovalCoordinator {
+    sink = new GenSink();
+    adapter;
+    /**
+     * Cancels the in-flight `run()`. Distinct from any consumer-supplied
+     * `abortSignal` so teardown can cancel the turn (dispose / destroyThread)
+     * even when the consumer passed no signal of its own.
+     */
+    abortController = new AbortController();
+    /** Removes the consumer's external-abort listener (if one was wired). */
+    detachExternalAbort;
+    /** True once the turn has reached a terminal state by any path. */
+    settled = false;
+    runner;
+    agent;
+    input;
+    session;
+    onSettled;
+    policy;
+    externalSignal;
+    toolApprovalTimeoutMs;
+    maxTurns;
+    consumerTools;
+    onConsumerToolErrors;
+    /** Approvals emitted this turn (surfaced a `tool-approval-request`), by `toolCallId`. */
+    emittedApprovals = new Set();
+    /** Approvals awaiting a consumer settle, by `toolCallId`. */
+    pendingApprovals = new Map();
+    /** Ids the consumer settled (approve / decline), so a repeat settle is a no-op. */
+    consumerSettled = new Set();
+    /** Ids the coordinator auto-settled (teardown), so a late consumer settle is a no-op. */
+    settledByCoordinator = new Set();
+    constructor(options) {
+        this.runner = options.runner;
+        this.agent = options.agent;
+        this.input = options.input;
+        this.session = options.session;
+        this.onSettled = options.onSettled;
+        this.policy = options.policy;
+        this.externalSignal = options.externalSignal;
+        this.toolApprovalTimeoutMs = options.toolApprovalTimeoutMs ?? DEFAULT_TOOL_APPROVAL_TIMEOUT_MS;
+        this.maxTurns = options.maxTurns;
+        this.consumerTools = options.consumerTools;
+        this.onConsumerToolErrors = options.onConsumerToolErrors;
+        this.adapter = new OpenAIEventAdapter(options.mcpCatalog);
+    }
+    /**
+     * Start pumping the run loop onto the sink (background task) and return the
+     * consumer's `ChatStreamResult`. Callers MUST have already thrown on an
+     * already-aborted signal (`stream()` does this synchronously at entry, per
+     * the pre-existing contract), so `start()` only wires the live-abort path.
+     */
+    start() {
+        if (this.externalSignal !== undefined) {
+            const onAbort = () => this.teardown(new AbortError(), 'abort');
+            this.externalSignal.addEventListener('abort', onAbort, { once: true });
+            this.detachExternalAbort = () => this.externalSignal?.removeEventListener('abort', onAbort);
+        }
+        void this.pump();
+        return teeTextStream(this.sink.generator());
+    }
+    /**
+     * Cancel the turn and release its resources. Used by `destroyThread`,
+     * `destroyAgent`, and `shutdown`. Idempotent (the `settled` guard in
+     * `teardown` collapses a second call to a no-op), and safe to call after the
+     * turn completed naturally.
+     */
+    dispose() {
+        this.teardown(new AgentSDKError('Harness disposed.', AgentSDKErrorType.DISPOSED), 'DISPOSED');
+    }
+    /**
+     * Approve a pending tool call. Buffers the decision and wakes the parked pump
+     * so it drives `state.approve(item)` + resume. Idempotent (#589): a repeat or
+     * post-teardown settle is a silent no-op; an id with no emitted approval is
+     * misuse and throws `TOOL_CALL_NOT_FOUND`.
+     */
+    approve(toolCallId) {
+        this.settleApproval('approve', toolCallId);
+    }
+    /**
+     * Decline a pending tool call. Buffers the decision and wakes the parked pump
+     * so it drives `state.reject(item, { message })` + resume — the run loop feeds
+     * a real `function_call_result` carrying the denial text back to the model, so
+     * the decline is model-visible with no synthesized result. Same idempotency
+     * contract as {@link approve}.
+     */
+    decline(toolCallId) {
+        this.settleApproval('decline', toolCallId);
+    }
+    /**
+     * Feed a consumer-executed tool's result back into the turn. Resolves the
+     * parked `execute` in the {@link ConsumerToolRegistry} keyed by `toolCallId`;
+     * the SDK run loop — blocked inside the pump's `await result.completed` on
+     * that parked promise — then continues the SAME run (emits `tool_output`, the
+     * model's follow-up, and a natural terminal `finish`) onto the same sink. No
+     * fresh `run()` and no synthetic `finish('tool-calls')`: unlike the approval
+     * path, the run never left. Idempotent (#589) and typed-throws
+     * (`TOOL_CALL_NOT_FOUND`) are owned by the registry.
+     */
+    submitToolResult(toolCallId, outcome) {
+        if (this.consumerTools === undefined) {
+            throw new AgentSDKError(`No parked consumer tool call for id "${toolCallId}".`, AgentSDKErrorType.TOOL_CALL_NOT_FOUND);
+        }
+        this.consumerTools.settle(toolCallId, outcome);
+    }
+    settleApproval(decision, toolCallId) {
+        // Lost-race no-op: already settled by the consumer or auto-settled by a
+        // teardown. The consumer's intended outcome (id is settled) already holds.
+        if (this.consumerSettled.has(toolCallId) || this.settledByCoordinator.has(toolCallId))
+            return;
+        const pending = this.pendingApprovals.get(toolCallId);
+        if (pending === undefined) {
+            // Never emitted an approval for this id — genuine misuse.
+            throw new AgentSDKError(`No pending tool-approval for tool call "${toolCallId}".`, AgentSDKErrorType.TOOL_CALL_NOT_FOUND);
+        }
+        this.consumerSettled.add(toolCallId);
+        clearTimeout(pending.timer);
+        this.pendingApprovals.delete(toolCallId);
+        pending.resolve(decision);
+    }
+    /**
+     * The turn's pump: run to a terminal state across one-or-more runs, draining
+     * each onto the SAME sink, settling any interruptions between runs. The SDK
+     * throws a mid-stream model error out of the iterator rather than emitting an
+     * event, so the `catch` synthesizes `error` + `finish('error')`.
+     */
+    async pump() {
+        try {
+            let result = (await this.runner.run(this.agent, this.input, this.runOptions()));
+            await this.drainRun(result);
+            // Resume loop: while the completed run carries interruptions, settle
+            // each and re-run onto the same sink until a run finishes clean.
+            while (!this.settled && result.interruptions.length > 0) {
+                await this.settleInterruptions(result);
+                if (this.settled)
+                    return;
+                result = (await this.runner.run(this.agent, result.state, this.runOptions()));
+                await this.drainRun(result);
+            }
+            if (this.settled)
+                return;
+            // Flush any `step-finish` the adapter deferred for a tool-calling
+            // step whose outputs drained without a following `response_started`
+            // (the last step of the turn), so every step closes before the
+            // terminal `finish`.
+            for (const chatEvent of this.adapter.drainDeferredStepFinish())
+                this.sink.push(chatEvent);
+            // The run loop emits no dedicated terminal event and does not throw on
+            // clean completion, so synthesize the single terminal `finish`.
+            this.settled = true;
+            this.sink.push({ type: 'finish', finishReason: 'stop', ...usageField(this.adapter.lastUsage()) });
+            this.sink.end();
+            this.cleanup();
+        }
+        catch (error) {
+            if (this.settled)
+                return;
+            for (const startEvent of this.adapter.ensureStarted()) {
+                this.sink.push(startEvent);
+            }
+            // Exceeding the step limit is a normal terminal condition, not a
+            // failure: `run(..., { maxTurns })` throws `MaxTurnsExceededError`
+            // out of the streamed iterator (like every mid-stream signal), but
+            // the harness surfaces it as a terminal `finish('max-steps')` with
+            // NO preceding `error` event — matching the Mastra / Claude harnesses
+            // and the SDK's `FinishReason` contract. Any other throw is a real
+            // mid-stream failure and keeps the `error` + `finish('error')` pair.
+            if (error instanceof MaxTurnsExceededError) {
+                for (const chatEvent of this.adapter.drainDeferredStepFinish())
+                    this.sink.push(chatEvent);
+                this.releaseParkedApprovals();
+                this.settled = true;
+                this.sink.push({ type: 'finish', finishReason: 'max-steps', ...usageField(this.adapter.lastUsage()) });
+                this.sink.end();
+                this.cleanup();
+                return;
+            }
+            const aborted = isAbortError(error) || this.abortController.signal.aborted;
+            this.releaseParkedApprovals();
+            this.settled = true;
+            this.sink.push({
+                type: 'error',
+                error: error instanceof Error ? error : new Error(String(error)),
+                code: aborted ? 'abort' : 'stream-error',
+            });
+            this.sink.push({ type: 'finish', finishReason: 'error' });
+            this.sink.end();
+            this.cleanup();
+        }
+    }
+    /**
+     * The `run()` options shared by the initial run and every resume, so the two
+     * can't drift.
+     *
+     * `reasoningItemIdPolicy: 'omit'` is load-bearing against the Salesforce
+     * gateway. The gateway is a stateless `/responses` pass-through
+     * (`store: false`), so it does not persist reasoning items by id. The SDK's
+     * default re-sends prior reasoning items BY ID REFERENCE (`rs_...`) on every
+     * follow-up model call — the initial run's second step (after a tool result)
+     * and every resume run — which the gateway rejects with
+     * `400 Item with id 'rs_...' not found. Items are not persisted when 'store'
+     * is set to false.` `'omit'` strips the id so the reasoning content is sent
+     * inline rather than referenced, which the stateless gateway accepts. (Server
+     * -side conversation state via `previousResponseId` is likewise unavailable
+     * here; the disk-backed `session` is our source of truth for prior turns.)
+     */
+    runOptions() {
+        return {
+            stream: true,
+            session: this.session,
+            signal: this.abortController.signal,
+            reasoningItemIdPolicy: 'omit',
+            // Forward the turn's step limit (`StreamOptions.maxSteps`) as
+            // `maxTurns`. Omitting the key entirely when unset preserves the
+            // SDK's own default rather than forcing `null` (unbounded).
+            ...(this.maxTurns !== undefined ? { maxTurns: this.maxTurns } : {}),
+        };
+    }
+    /**
+     * Drain one streamed run result: map every event onto the sink, then await
+     * the run's terminal completion so the SDK finishes writing session state
+     * (the runner owns the history write) before the caller decides
+     * the turn's next step. Does NOT emit any terminal `finish` — that is the
+     * pump's decision, since a run that ends with `interruptions` is resumed
+     * rather than finished.
+     */
+    async drainRun(result) {
+        for await (const event of result) {
+            for (const chatEvent of this.adapter.map(event)) {
+                // Record consumer-tool call ids the moment they're surfaced so a
+                // `submitToolResult` that races ahead of the parked `execute` (the
+                // SDK emits `tool_called` before awaiting `execute`) is buffered,
+                // not rejected.
+                if (chatEvent.type === 'tool-call' && this.consumerTools?.toolNames.has(chatEvent.toolName) === true) {
+                    this.consumerTools.markEmitted(chatEvent.toolCallId);
+                }
+                this.sink.push(chatEvent);
+            }
+        }
+        await result.completed;
+    }
+    /**
+     * Settle every interruption on a completed run against the policy, mutating
+     * `result.state` in place so the caller can resume from it. `allow` / `deny`
+     * are resolved silently here; `require-approval` emits a
+     * `tool-approval-request`, arms a timer, and awaits the consumer's settle.
+     * Returns once all interruptions on this run have been approved or rejected
+     * (or the turn was torn down while a settle was parked).
+     */
+    async settleInterruptions(result) {
+        for (const item of result.interruptions) {
+            if (this.settled)
+                return;
+            const toolCallId = item.rawItem?.callId;
+            const toolName = item.toolName ?? item.name ?? item.rawItem?.name;
+            // An interruption with no callId/name can't be routed or settled —
+            // approve it so the run makes progress rather than deadlocking.
+            if (toolCallId === undefined || toolName === undefined) {
+                result.state.approve(item);
+                continue;
+            }
+            const decision = this.policy?.({ toolName }) ?? 'require-approval';
+            if (decision === 'allow') {
+                result.state.approve(item);
+                continue;
+            }
+            if (decision === 'deny') {
+                result.state.reject(item, { message: 'Tool call was not approved by policy.' });
+                continue;
+            }
+            const settled = await this.awaitApproval(toolCallId, toolName, item);
+            if (settled === undefined)
+                return; // torn down while parked
+            if (settled === 'approve')
+                result.state.approve(item);
+            else
+                result.state.reject(item, { message: 'User declined the tool call.' });
+        }
+    }
+    /**
+     * Emit a `tool-approval-request`, arm the per-`toolCallId` timeout, and return
+     * a promise that resolves when the consumer settles (or `undefined` if the
+     * turn is torn down while parked, in which case the pump exits).
+     */
+    awaitApproval(toolCallId, toolName, item) {
+        this.sink.push({
+            type: 'tool-approval-request',
+            toolCall: { toolCallId, toolName, args: parseArgs(item) },
+        });
+        this.emittedApprovals.add(toolCallId);
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.teardown(new Error(`Tool approval timed out after ${this.toolApprovalTimeoutMs}ms for "${toolCallId}".`), 'tool-approval-timeout');
+            }, this.toolApprovalTimeoutMs);
+            this.pendingApprovals.set(toolCallId, { resolve, timer });
+        });
+    }
+    /**
+     * Single terminal path for abort / dispose / timeout. Releases every parked
+     * approval so nothing hangs, aborts the in-flight run, emits the terminal
+     * `error` + `finish('error')` pair (a `start` first if the turn produced no
+     * events), and settles. `code` distinguishes the reason to the consumer
+     * (`'abort'` / `'DISPOSED'` / `'tool-approval-timeout'`). The `settled` guard
+     * makes it single-shot and a no-op after natural completion.
+     */
+    teardown(error, code) {
+        if (this.settled)
+            return;
+        this.releaseParkedApprovals();
+        this.settled = true;
+        this.abortController.abort();
+        for (const startEvent of this.adapter.ensureStarted()) {
+            this.sink.push(startEvent);
+        }
+        this.sink.push({ type: 'error', error, code });
+        this.sink.push({ type: 'finish', finishReason: 'error' });
+        this.sink.end();
+        this.cleanup();
+    }
+    /**
+     * Release every parked approval AND every parked consumer-tool call: cancel
+     * each approval timer, record the id as coordinator-settled (so a late
+     * consumer settle is a no-op, #589), resolve the parked approval waiter with
+     * `undefined` so the pump exits its `awaitApproval`, and reject every parked
+     * consumer `execute` so the SDK run loop unblocks rather than hanging on a
+     * promise that will never settle. Shared by the error path and
+     * {@link teardown}. Does not set `settled` — callers own that ordering
+     * relative to the terminal emit.
+     */
+    releaseParkedApprovals() {
+        for (const [toolCallId, pending] of this.pendingApprovals) {
+            clearTimeout(pending.timer);
+            this.settledByCoordinator.add(toolCallId);
+            pending.resolve(undefined);
+        }
+        for (const toolCallId of this.emittedApprovals)
+            this.settledByCoordinator.add(toolCallId);
+        this.pendingApprovals.clear();
+        this.consumerTools?.rejectAll(new Error('Turn ended before the consumer tool result arrived.'));
+    }
+    /** Detach the external-abort listener and notify the harness exactly once. */
+    cleanup() {
+        this.detachExternalAbort?.();
+        this.detachExternalAbort = undefined;
+        // Stamp `isError` onto the persisted results of any consumer tool the
+        // consumer settled with `isError: true` — the run loop wrote them without
+        // it (the OpenAI item shape has no `isError` field). Fires on every
+        // terminal path (a tool can be settled with an error before an abort), and
+        // the harness's async stamp settles under the store's per-thread queue
+        // after the run's own writes.
+        const errored = this.consumerTools?.erroredToolCallIds() ?? [];
+        if (errored.length > 0)
+            this.onConsumerToolErrors?.(errored);
+        this.onSettled();
+    }
+}
+/** An `AbortError`-shaped `Error` so `isAbortError` and consumers classify it. */
+class AbortError extends Error {
+    constructor() {
+        super('The operation was aborted.');
+        this.name = 'AbortError';
+    }
+}
+/** Parse the interruption's raw `arguments` JSON into an args object (best-effort). */
+function parseArgs(item) {
+    const raw = item.arguments;
+    if (typeof raw !== 'string')
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed === 'object' && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function usageField(usage) {
+    return usage !== undefined ? { usage } : {};
+}
+//# sourceMappingURL=openai-approval-coordinator.js.map

package/dist/openai-approval-coordinator.js.map

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

package/dist/openai-built-in-policies.d.ts

@@ -0,0 +1,29 @@
+import type { ToolPolicyRule } from '@salesforce/sfdx-agent-sdk';
+/**
+ * OpenAI harness-specific built-in tool-approval rules — the `tiers.harness`
+ * slice passed to `resolveToolApprovalPolicy`. Per the SDK's R4 layering
+ * invariant, harness-specific built-ins live here, not in the SDK's
+ * harness-agnostic `BUILT_IN_TOOL_POLICIES`.
+ *
+ * **Empty today.** Unlike Claude (`Bash` / `Edit` / … registered by the CLI
+ * subprocess) and Mastra (`updateWorkingMemory` / `skill*` registered by the
+ * runtime), the OpenAI harness registers no runtime built-in tools of its own:
+ * a turn's tools are the consumer-declared (`AgentConfig.tools`) and — once MCP
+ * support lands — MCP tools, both of which the resolver already covers via
+ * `builtin` / `mcp` matchers on the consumer tier. So there is nothing
+ * harness-specific to pre-gate here today.
+ *
+ * The array is present (not omitted) so the harness always passes a
+ * `{ harness }` tier to `resolveToolApprovalPolicy` — a stable call shape — and
+ * so a future built-in has an obvious home. The `@openai/agents` hosted tools
+ * (`shell` / `apply_patch` / `computer`) each carry their OWN `needsApproval`
+ * flag in the SDK and are not wired into this harness yet; when they are, decide
+ * per-tool whether the gate belongs on the SDK flag or as a rule here.
+ *
+ * Frozen: adding an entry is a soft contract change consumers will have noticed;
+ * removing or modifying one is a breaking change. The drift test in
+ * `test/openai-built-in-policies.test.ts` pins the shape (currently: empty, all
+ * `builtin` matchers, all `source: 'built-in'` — vacuously true while empty, and
+ * the guard the first real entry must satisfy).
+ */
+export declare const OPENAI_BUILT_IN_TOOL_POLICIES: ReadonlyArray<ToolPolicyRule>;

package/dist/openai-built-in-policies.js

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * OpenAI harness-specific built-in tool-approval rules — the `tiers.harness`
+ * slice passed to `resolveToolApprovalPolicy`. Per the SDK's R4 layering
+ * invariant, harness-specific built-ins live here, not in the SDK's
+ * harness-agnostic `BUILT_IN_TOOL_POLICIES`.
+ *
+ * **Empty today.** Unlike Claude (`Bash` / `Edit` / … registered by the CLI
+ * subprocess) and Mastra (`updateWorkingMemory` / `skill*` registered by the
+ * runtime), the OpenAI harness registers no runtime built-in tools of its own:
+ * a turn's tools are the consumer-declared (`AgentConfig.tools`) and — once MCP
+ * support lands — MCP tools, both of which the resolver already covers via
+ * `builtin` / `mcp` matchers on the consumer tier. So there is nothing
+ * harness-specific to pre-gate here today.
+ *
+ * The array is present (not omitted) so the harness always passes a
+ * `{ harness }` tier to `resolveToolApprovalPolicy` — a stable call shape — and
+ * so a future built-in has an obvious home. The `@openai/agents` hosted tools
+ * (`shell` / `apply_patch` / `computer`) each carry their OWN `needsApproval`
+ * flag in the SDK and are not wired into this harness yet; when they are, decide
+ * per-tool whether the gate belongs on the SDK flag or as a rule here.
+ *
+ * Frozen: adding an entry is a soft contract change consumers will have noticed;
+ * removing or modifying one is a breaking change. The drift test in
+ * `test/openai-built-in-policies.test.ts` pins the shape (currently: empty, all
+ * `builtin` matchers, all `source: 'built-in'` — vacuously true while empty, and
+ * the guard the first real entry must satisfy).
+ */
+export const OPENAI_BUILT_IN_TOOL_POLICIES = Object.freeze([]);
+//# sourceMappingURL=openai-built-in-policies.js.map

package/dist/openai-built-in-policies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-built-in-policies.js","sourceRoot":"","sources":["../src/openai-built-in-policies.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAkC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC"}

package/dist/openai-event-adapter.d.ts

@@ -0,0 +1,119 @@
+import type { RunStreamEvent } from '@openai/agents';
+import type { ChatEvent, FinishReason, UsageMetadata } from '@salesforce/sfdx-agent-sdk';
+import type { McpCatalogEntry } from './openai-mcp-state.js';
+/**
+ * Per-stream stateful mapper from `@openai/agents` `RunStreamEvent`s to the
+ * SDK's `ChatEvent` variants. A new instance is constructed per `stream()` call
+ * because it tracks `stepIndex` and the last-seen per-step usage.
+ *
+ * **Text + tool events.** The run loop emits three event families:
+ * `raw_model_stream_event` (the underlying model stream, carrying
+ * `output_text_delta` / `response_started` / `response_done`),
+ * `run_item_stream_event` (tool calls / outputs), and
+ * `agent_updated_stream_event` (handoffs — not used). This adapter maps the
+ * text and step-boundary events plus the `tool_called` / `tool_output` run-item
+ * events to `tool-call` / `tool-result` ChatEvents. The terminal `finish` is
+ * synthesized by the harness pump when the run stream completes, since the run
+ * loop does not emit a dedicated "run finished" event and mid-stream errors are
+ * thrown, not emitted.
+ *
+ * The adapter never emits an event whose `type` is not a member of the
+ * `ChatEvent` union. Unrecognized events are skipped.
+ */
+export declare class OpenAIEventAdapter {
+    private readonly mcpCatalog?;
+    private stepIndex;
+    private started;
+    private lastStepUsage;
+    /**
+     * A `step-finish` buffered because its step produced tool calls. The
+     * `@openai/agents` run loop emits `response_done` for a tool-calling step
+     * BEFORE the `tool_called` / `tool_output` run-items for that step, so
+     * emitting `step-finish` inline would place the `tool-result` AFTER its
+     * step's `step-finish` — outside the step. We hold the `step-finish` until
+     * the step's tool outputs drain (or a new step starts / the run ends), so a
+     * `tool-result` always lands inside the `step-start`/`step-finish` bracket
+     * that produced it. Mirrors the Claude adapter's deferred-`step-finish`
+     * ordering (`pendingToolUseIds`).
+     */
+    private deferredStepFinish;
+    /** Outstanding `tool_output`s for the deferred step; `step-finish` flushes at 0. */
+    private pendingToolOutputs;
+    /**
+     * Optional MCP tool catalog (bare tool name → `{ serverName, annotations }`),
+     * used to enrich `tool-call` / `tool-result` events for MCP-sourced tools
+     * with `serverName` / `bareToolName` / `annotations`. Read live so a mid-turn
+     * discovery settle enriches later events. `undefined` (or a miss) leaves the
+     * fields unset — the contract for consumer / built-in tools.
+     */
+    constructor(mcpCatalog?: ReadonlyMap<string, McpCatalogEntry> | undefined);
+    /**
+     * Map one `RunStreamEvent` to zero or more `ChatEvent`s. Emits a synthetic
+     * `start` before the first mapped event.
+     */
+    map(event: RunStreamEvent): ChatEvent[];
+    /**
+     * Map a `run_item_stream_event` to a `tool-call` / `tool-result` ChatEvent.
+     * The run loop fires `tool_called` with a `RunToolCallItem` (the model's
+     * request) and `tool_output` with a `RunToolCallOutputItem` (the result).
+     *
+     * **MCP enrichment.** When the tool's (bare) name is in the {@link mcpCatalog},
+     * the event carries `serverName` / `bareToolName` / `annotations` so a consumer
+     * can build a `{ type: 'mcp', serverName, toolName }` policy matcher without
+     * string-splitting the display name. Consumer / built-in tools miss the
+     * catalog and surface with `serverName === undefined`, per the SDK contract.
+     * `isError` is not carried on the live `tool-result` event — the OpenAI
+     * `tool_output` item has no `isError` field; a consumer-reported failure is
+     * stamped onto the persisted record instead (see the session store). This
+     * maps the raw call/result the loop emits so a tool turn is observable and
+     * round-trips through history.
+     */
+    private mapRunItem;
+    /**
+     * Look up the (bare) tool name in the MCP catalog and return the enrichment
+     * fields for a `tool-call` / `tool-result` event, or an empty object when the
+     * tool is not MCP-sourced. `bareToolName` equals the display `toolName` here
+     * because `@openai/agents` registers MCP tools under their bare name.
+     */
+    private enrich;
+    /**
+     * The last per-step usage observed, used to populate the terminal `finish`
+     * event the pump synthesizes when the run stream completes cleanly.
+     */
+    lastUsage(): UsageMetadata | undefined;
+    /**
+     * Emit a synthetic `start` if the stream produced no events at all (e.g. a
+     * turn that failed before the first delta). Called by the pump on the error
+     * path so a consumer always sees a `start` before the terminal pair.
+     */
+    ensureStarted(): ChatEvent[];
+    private mapRaw;
+    /**
+     * Emit a held `step-finish` (if any) and reset the deferral state. Called
+     * when the step's tool outputs have drained, when a new step starts, and by
+     * the pump before the terminal `finish` so a deferred step-finish can never
+     * be dropped.
+     */
+    flushDeferredStepFinish(out: ChatEvent[]): void;
+    /** Emit any held `step-finish` as a standalone event list (pump terminal path). */
+    drainDeferredStepFinish(): ChatEvent[];
+}
+/**
+ * Maps the OpenAI Agents SDK's `response_done` usage shape (camelCase
+ * `inputTokens` / `outputTokens` / `totalTokens`, plus optional
+ * `inputTokensDetails` / `outputTokensDetails`) onto the SDK's
+ * {@link UsageMetadata}. Returns `undefined` when no usage was reported at all,
+ * so consumers see an honest "usage not reported" signal rather than a fake
+ * all-zero object (the missing-usage-faithfulness contract, W-22692131).
+ */
+export declare function mapUsage(usage: OpenAIStreamUsage | undefined): UsageMetadata | undefined;
+/** The usage shape carried on a `response_done` stream event. */
+export type OpenAIStreamUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    inputTokensDetails?: Record<string, number> | Array<Record<string, number>>;
+    outputTokensDetails?: Record<string, number> | Array<Record<string, number>>;
+};
+/** Re-export so the harness pump can reference the union without re-importing. */
+export type { FinishReason };