@salesforce/sfdx-agent-harness-openai 0.0.1

package/dist/openai-model-provider.js.map

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

package/dist/openai-session-store.d.ts

@@ -0,0 +1,149 @@
+import { type Clock, type LogBus } from '@salesforce/agentic-common';
+import type { AgentInputItem, Session } from '@openai/agents';
+/**
+ * One persisted entry: the `@openai/agents` protocol item plus the two facts
+ * the OpenAI item shape cannot carry.
+ *
+ * The OpenAI Agents SDK stores a completed tool call as a `function_call` +
+ * `function_call_result` item pair sharing `callId`; neither carries a
+ * timestamp, and `function_call_result` has no `isError` field — a thrown tool
+ * error becomes a generic English string in its `output`. The SDK contract,
+ * however, requires `getMessages` to populate `createdAt` on every message
+ * (#464) and to preserve a tool result's `isError` flag (#647). This harness
+ * owns the entire on-disk persistence (the SDK ships only an in-memory
+ * `MemorySession`), so rather than a separate `callId`-keyed sidecar file (the
+ * Claude `ThreadContextStore` pattern, forced on Claude because its transcript is
+ * SDK-owned) the two facts ride on this record envelope: written transactionally
+ * with the item in one file, cleared with it, and keyed to the item by position
+ * (`createdAt`) or by `callId` lookup on the item itself (`isError`).
+ */
+export type SessionRecord = {
+    /** The `@openai/agents` protocol item, stored verbatim. */
+    item: AgentInputItem;
+    /** ISO 8601. Stamped at write time (run loop) or carried from `addContext`. */
+    createdAt: string;
+    /**
+     * Present only on `function_call_result` records the harness knows failed.
+     * Absent on success paths and on non-result items. Carries the SDK's
+     * `ToolResultInfo.isError` across a persistence round-trip so `getMessages`
+     * can restore it on the `tool-result` part (#647).
+     */
+    isError?: boolean;
+};
+/**
+ * Harness-owned disk persistence for OpenAI Agents SDK sessions. One JSON file
+ * per `(agentId, threadId)` under `${storageRootFolder}/openai-sessions/`:
+ *
+ *     ${storageRootFolder}/openai-sessions/
+ *       <agentId>/
+ *         <threadId>.json        ← JSON array of {@link SessionRecord}
+ *
+ * The store is agent-scoped so `getThreadIds(agentId)` maps to a directory
+ * listing and threads survive a harness restart (`createAgent` rehydrates from
+ * the agent directory). Unlike the Claude harness, the OpenAI SDK's
+ * `clearSession()` leaves the session id reusable, so the user-facing `threadId`
+ * *is* the SDK session id — no id-rotation dance and no `threadId`↔`sessionId`
+ * divergence.
+ *
+ * **Whole-file rewrite, not append.** Each mutation reads the current records,
+ * mutates in memory, and writes the whole file via a `.tmp` + `rename` (atomic
+ * on POSIX; per-key serialization handles the Windows concurrent-rename EPERM).
+ * Append-only JSONL (the Claude session store's shape) can't support
+ * `popItem()` (remove-last, used by the run loop's orphan-tool-call cleanup) or
+ * an out-of-band `isError` update, both of which this store needs. Threads are
+ * bounded in practice, so the O(n) rewrite per turn is acceptable — the same
+ * trade the Claude `ThreadContextStore` makes for its per-turn sidecar rewrite.
+ *
+ * **Concurrency.** A per-`(agentId, threadId)` in-flight queue serializes
+ * mutations on the same thread (ported from the Claude `DiskBackedSessionStore`
+ * `serialize()` primitive). Two `AgentManager` instances over the same
+ * `storageRootFolder` is undefined behavior per the SDK ARCHITECTURE —
+ * cross-process locking is out of scope.
+ */
+export declare class OpenAISessionStore {
+    private readonly storageRootFolder;
+    private readonly logBus;
+    private readonly clock;
+    private readonly inflight;
+    constructor(storageRootFolder: string, logBus: LogBus | undefined, clock?: Clock);
+    /**
+     * A per-thread {@link Session} adapter bound to `(agentId, threadId)`,
+     * satisfying the `@openai/agents` `Session` interface so it can be threaded
+     * into `run(agent, input, { session })`. The runner reads history via
+     * `getItems()` and appends new items via `addItems()` itself — the harness
+     * never double-writes the run loop's output.
+     */
+    session(agentId: string, threadId: string): Session;
+    /**
+     * All items for a thread, in stored order (last `limit` when provided),
+     * sanitized for re-submission as model INPUT.
+     *
+     * The runner reads this back and re-sends prior turns as input on every
+     * follow-up model call. The Salesforce gateway echoes output-only fields on
+     * assistant content it returns (notably `logprobs` on an `output_text`
+     * block), and the SDK persists the item verbatim — but the gateway's INPUT
+     * content-param model is strict and rejects those same fields with
+     * `400 Unrecognized field "logprobs" ... not marked as ignorable`. The real
+     * OpenAI API ignores unknown input fields; this gateway does not, so the
+     * harness strips them here. Sanitizing on the READ path (not the write) keeps
+     * stored records verbatim, so `getRecords` / `getMessages` fidelity and the
+     * "item stored verbatim" invariant are untouched — only what is replayed to
+     * the model is cleaned.
+     */
+    getItems(agentId: string, threadId: string, limit?: number): Promise<AgentInputItem[]>;
+    /**
+     * Append run-loop items, stamping `createdAt` at write time. The stamp
+     * seeds strictly after the last stored record's `createdAt` (via
+     * `clock.nextAfter`) and steps per item, so history stays strictly
+     * ascending even under a fixed test clock — the `getMessages` #464
+     * ascending post-condition holds deterministically.
+     */
+    addItems(agentId: string, threadId: string, items: AgentInputItem[]): Promise<void>;
+    /** Remove and return the most recent item, or `undefined` when empty. */
+    popItem(agentId: string, threadId: string): Promise<AgentInputItem | undefined>;
+    /** Truncate a thread's history to empty, leaving the thread reusable. */
+    clear(agentId: string, threadId: string): Promise<void>;
+    /**
+     * Append pre-built records carrying their own `createdAt` + `isError` — the
+     * `addContext` path, which persists consumer-supplied history without a
+     * model turn. `createdAt` is backfilled by the caller (shared
+     * `backfillCreatedAt`); `isError` rides from the `tool-result` part.
+     */
+    appendRecords(agentId: string, threadId: string, records: SessionRecord[]): Promise<void>;
+    /**
+     * Stamp `isError: true` on the `function_call_result` records whose `callId`
+     * is in `toolCallIds` — the out-of-band update the whole-file-rewrite store
+     * exists to support. The run loop persists a consumer tool's result via
+     * `addItems` as a bare `{ item, createdAt }` (the OpenAI `function_call_result`
+     * item has no `isError` field), so when a consumer settles a tool
+     * with `isError: true` the coordinator calls this after the run completes to
+     * carry the flag onto history, satisfying the #647 "isError survives" contract.
+     * A no-op when no matching result record exists (e.g. the id was never
+     * persisted). Late `addItems` from the same turn have already settled under
+     * the per-`(agentId, threadId)` serialize queue, so the target record is
+     * present by the time this runs.
+     */
+    markToolResultError(agentId: string, threadId: string, toolCallIds: Iterable<string>): Promise<void>;
+    /** Full records (item + `createdAt` + `isError`) for the `getMessages` read path. */
+    getRecords(agentId: string, threadId: string): Promise<SessionRecord[]>;
+    /** Delete a thread's file entirely (thread destruction). */
+    delete(agentId: string, threadId: string): Promise<void>;
+    /**
+     * Thread ids for an agent, read from the agent directory. Backs
+     * `getThreadIds` rehydration on restart. Returns `[]` when the agent has no
+     * directory yet (no thread has been persisted).
+     */
+    listThreadIds(agentId: string): Promise<string[]>;
+    private readRecords;
+    private writeRecords;
+    private agentDir;
+    private fileFor;
+    /**
+     * Per-`(agentId, threadId)` in-flight queue. Ported verbatim from the Claude
+     * `DiskBackedSessionStore` — the atomicity primitive that serializes
+     * read-mutate-write cycles on the same thread so a concurrent `run()` turn,
+     * `addContext`, and `clearMessages` never interleave a read against a
+     * half-written file.
+     */
+    private serialize;
+}

package/dist/openai-session-store.js

@@ -0,0 +1,328 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { getErrorMessage, RealClock } from '@salesforce/agentic-common';
+const SESSIONS_SUBDIR = 'openai-sessions';
+const FILE_EXT = '.json';
+/**
+ * Harness-owned disk persistence for OpenAI Agents SDK sessions. One JSON file
+ * per `(agentId, threadId)` under `${storageRootFolder}/openai-sessions/`:
+ *
+ *     ${storageRootFolder}/openai-sessions/
+ *       <agentId>/
+ *         <threadId>.json        ← JSON array of {@link SessionRecord}
+ *
+ * The store is agent-scoped so `getThreadIds(agentId)` maps to a directory
+ * listing and threads survive a harness restart (`createAgent` rehydrates from
+ * the agent directory). Unlike the Claude harness, the OpenAI SDK's
+ * `clearSession()` leaves the session id reusable, so the user-facing `threadId`
+ * *is* the SDK session id — no id-rotation dance and no `threadId`↔`sessionId`
+ * divergence.
+ *
+ * **Whole-file rewrite, not append.** Each mutation reads the current records,
+ * mutates in memory, and writes the whole file via a `.tmp` + `rename` (atomic
+ * on POSIX; per-key serialization handles the Windows concurrent-rename EPERM).
+ * Append-only JSONL (the Claude session store's shape) can't support
+ * `popItem()` (remove-last, used by the run loop's orphan-tool-call cleanup) or
+ * an out-of-band `isError` update, both of which this store needs. Threads are
+ * bounded in practice, so the O(n) rewrite per turn is acceptable — the same
+ * trade the Claude `ThreadContextStore` makes for its per-turn sidecar rewrite.
+ *
+ * **Concurrency.** A per-`(agentId, threadId)` in-flight queue serializes
+ * mutations on the same thread (ported from the Claude `DiskBackedSessionStore`
+ * `serialize()` primitive). Two `AgentManager` instances over the same
+ * `storageRootFolder` is undefined behavior per the SDK ARCHITECTURE —
+ * cross-process locking is out of scope.
+ */
+export class OpenAISessionStore {
+    storageRootFolder;
+    logBus;
+    clock;
+    inflight = new Map();
+    constructor(storageRootFolder, logBus, clock = new RealClock()) {
+        this.storageRootFolder = storageRootFolder;
+        this.logBus = logBus;
+        this.clock = clock;
+    }
+    /**
+     * A per-thread {@link Session} adapter bound to `(agentId, threadId)`,
+     * satisfying the `@openai/agents` `Session` interface so it can be threaded
+     * into `run(agent, input, { session })`. The runner reads history via
+     * `getItems()` and appends new items via `addItems()` itself — the harness
+     * never double-writes the run loop's output.
+     */
+    session(agentId, threadId) {
+        return new DiskBackedSession(this, agentId, threadId);
+    }
+    // ── Session-interface primitives (delegated to by DiskBackedSession) ─────
+    /**
+     * All items for a thread, in stored order (last `limit` when provided),
+     * sanitized for re-submission as model INPUT.
+     *
+     * The runner reads this back and re-sends prior turns as input on every
+     * follow-up model call. The Salesforce gateway echoes output-only fields on
+     * assistant content it returns (notably `logprobs` on an `output_text`
+     * block), and the SDK persists the item verbatim — but the gateway's INPUT
+     * content-param model is strict and rejects those same fields with
+     * `400 Unrecognized field "logprobs" ... not marked as ignorable`. The real
+     * OpenAI API ignores unknown input fields; this gateway does not, so the
+     * harness strips them here. Sanitizing on the READ path (not the write) keeps
+     * stored records verbatim, so `getRecords` / `getMessages` fidelity and the
+     * "item stored verbatim" invariant are untouched — only what is replayed to
+     * the model is cleaned.
+     */
+    async getItems(agentId, threadId, limit) {
+        const records = await this.serialize(agentId, threadId, () => this.readRecords(agentId, threadId));
+        const items = records.map((r) => sanitizeForModelInput(r.item));
+        return limit !== undefined && limit >= 0 ? items.slice(Math.max(0, items.length - limit)) : items;
+    }
+    /**
+     * Append run-loop items, stamping `createdAt` at write time. The stamp
+     * seeds strictly after the last stored record's `createdAt` (via
+     * `clock.nextAfter`) and steps per item, so history stays strictly
+     * ascending even under a fixed test clock — the `getMessages` #464
+     * ascending post-condition holds deterministically.
+     */
+    async addItems(agentId, threadId, items) {
+        if (items.length === 0)
+            return;
+        await this.serialize(agentId, threadId, async () => {
+            const records = await this.readRecords(agentId, threadId);
+            let cursor = records.length > 0 ? new Date(records[records.length - 1].createdAt) : undefined;
+            for (const item of items) {
+                cursor = cursor ? this.clock.nextAfter(cursor) : this.clock.now();
+                records.push({ item, createdAt: cursor.toISOString() });
+            }
+            await this.writeRecords(agentId, threadId, records);
+        });
+    }
+    /** Remove and return the most recent item, or `undefined` when empty. */
+    async popItem(agentId, threadId) {
+        return this.serialize(agentId, threadId, async () => {
+            const records = await this.readRecords(agentId, threadId);
+            const last = records.pop();
+            if (last === undefined)
+                return undefined;
+            await this.writeRecords(agentId, threadId, records);
+            return last.item;
+        });
+    }
+    /** Truncate a thread's history to empty, leaving the thread reusable. */
+    async clear(agentId, threadId) {
+        await this.serialize(agentId, threadId, () => this.writeRecords(agentId, threadId, []));
+    }
+    // ── Harness-facing operations (createdAt/isError-aware) ──────────────────
+    /**
+     * Append pre-built records carrying their own `createdAt` + `isError` — the
+     * `addContext` path, which persists consumer-supplied history without a
+     * model turn. `createdAt` is backfilled by the caller (shared
+     * `backfillCreatedAt`); `isError` rides from the `tool-result` part.
+     */
+    async appendRecords(agentId, threadId, records) {
+        if (records.length === 0)
+            return;
+        await this.serialize(agentId, threadId, async () => {
+            const existing = await this.readRecords(agentId, threadId);
+            await this.writeRecords(agentId, threadId, [...existing, ...records]);
+        });
+    }
+    /**
+     * Stamp `isError: true` on the `function_call_result` records whose `callId`
+     * is in `toolCallIds` — the out-of-band update the whole-file-rewrite store
+     * exists to support. The run loop persists a consumer tool's result via
+     * `addItems` as a bare `{ item, createdAt }` (the OpenAI `function_call_result`
+     * item has no `isError` field), so when a consumer settles a tool
+     * with `isError: true` the coordinator calls this after the run completes to
+     * carry the flag onto history, satisfying the #647 "isError survives" contract.
+     * A no-op when no matching result record exists (e.g. the id was never
+     * persisted). Late `addItems` from the same turn have already settled under
+     * the per-`(agentId, threadId)` serialize queue, so the target record is
+     * present by the time this runs.
+     */
+    async markToolResultError(agentId, threadId, toolCallIds) {
+        const ids = new Set(toolCallIds);
+        if (ids.size === 0)
+            return;
+        await this.serialize(agentId, threadId, async () => {
+            const records = await this.readRecords(agentId, threadId);
+            let changed = false;
+            for (const record of records) {
+                const item = record.item;
+                if (item.type === 'function_call_result' && item.callId !== undefined && ids.has(item.callId)) {
+                    if (record.isError !== true) {
+                        record.isError = true;
+                        changed = true;
+                    }
+                }
+            }
+            if (changed)
+                await this.writeRecords(agentId, threadId, records);
+        });
+    }
+    /** Full records (item + `createdAt` + `isError`) for the `getMessages` read path. */
+    async getRecords(agentId, threadId) {
+        return this.serialize(agentId, threadId, () => this.readRecords(agentId, threadId));
+    }
+    /** Delete a thread's file entirely (thread destruction). */
+    async delete(agentId, threadId) {
+        await this.serialize(agentId, threadId, () => rm(this.fileFor(agentId, threadId), { force: true }));
+    }
+    /**
+     * Thread ids for an agent, read from the agent directory. Backs
+     * `getThreadIds` rehydration on restart. Returns `[]` when the agent has no
+     * directory yet (no thread has been persisted).
+     */
+    async listThreadIds(agentId) {
+        const dir = this.agentDir(agentId);
+        let entries;
+        try {
+            entries = await readdir(dir);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+        return entries.filter((n) => n.endsWith(FILE_EXT)).map((n) => n.slice(0, -FILE_EXT.length));
+    }
+    // ── Internals (called only inside `serialize`) ───────────────────────────
+    async readRecords(agentId, threadId) {
+        const file = this.fileFor(agentId, threadId);
+        let raw;
+        try {
+            raw = await readFile(file, 'utf8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch (err) {
+            // A corrupt file is logged and treated as empty rather than failing
+            // every read — matches AgentIdentityStore's soft-skip posture. The
+            // corrupt file stays on disk; the next write overwrites it cleanly.
+            this.logBus?.warn('skipping unparseable OpenAI session file', {
+                file,
+                error: getErrorMessage(err),
+            });
+            return [];
+        }
+    }
+    async writeRecords(agentId, threadId, records) {
+        const file = this.fileFor(agentId, threadId);
+        await mkdir(dirname(file), { recursive: true });
+        const tmp = `${file}.tmp`;
+        await writeFile(tmp, JSON.stringify(records), 'utf8');
+        await rename(tmp, file);
+    }
+    agentDir(agentId) {
+        return join(this.storageRootFolder, SESSIONS_SUBDIR, sanitize(agentId));
+    }
+    fileFor(agentId, threadId) {
+        return join(this.agentDir(agentId), `${sanitize(threadId)}${FILE_EXT}`);
+    }
+    /**
+     * Per-`(agentId, threadId)` in-flight queue. Ported verbatim from the Claude
+     * `DiskBackedSessionStore` — the atomicity primitive that serializes
+     * read-mutate-write cycles on the same thread so a concurrent `run()` turn,
+     * `addContext`, and `clearMessages` never interleave a read against a
+     * half-written file.
+     */
+    serialize(agentId, threadId, fn) {
+        const k = `${sanitize(agentId)} ${sanitize(threadId)}`;
+        const previous = this.inflight.get(k) ?? Promise.resolve();
+        const next = previous.catch(() => undefined).then(fn);
+        this.inflight.set(k, next);
+        next.finally(() => {
+            if (this.inflight.get(k) === next)
+                this.inflight.delete(k);
+        }).catch(() => undefined);
+        return next;
+    }
+}
+/**
+ * Per-thread `Session` adapter. Constructed per `stream()` call, bound to one
+ * `(agentId, threadId)`, delegating every operation to the shared
+ * {@link OpenAISessionStore}. `getSessionId()` returns the `threadId` (they are
+ * the same value on this harness).
+ */
+class DiskBackedSession {
+    store;
+    agentId;
+    threadId;
+    constructor(store, agentId, threadId) {
+        this.store = store;
+        this.agentId = agentId;
+        this.threadId = threadId;
+    }
+    async getSessionId() {
+        return this.threadId;
+    }
+    async getItems(limit) {
+        return this.store.getItems(this.agentId, this.threadId, limit);
+    }
+    async addItems(items) {
+        return this.store.addItems(this.agentId, this.threadId, items);
+    }
+    async popItem() {
+        return this.store.popItem(this.agentId, this.threadId);
+    }
+    async clearSession() {
+        return this.store.clear(this.agentId, this.threadId);
+    }
+}
+/**
+ * Collapse anything outside `[A-Za-z0-9._-]` to `_` so agent ids and thread ids
+ * are safe path segments. Thread ids are UUIDs in practice, but a
+ * consumer-supplied explicit thread id (or agent id) is not guaranteed safe.
+ */
+function sanitize(s) {
+    return s.replace(/[^A-Za-z0-9._-]/g, '_');
+}
+/**
+ * Output-only fields the gateway emits on assistant content but rejects when the
+ * same item is resubmitted as model INPUT. The SDK stashes these under a content
+ * block's `providerData` and spreads `providerData` back onto the wire object on
+ * resend, so `providerData.logprobs` becomes a top-level `logprobs` the gateway's
+ * strict input model rejects (`400 Unrecognized field "logprobs"`). `logprobs` is
+ * the confirmed offender; add siblings here as the wire surfaces them.
+ */
+const OUTPUT_ONLY_CONTENT_FIELDS = ['logprobs'];
+/**
+ * Return a copy of a persisted item safe to resubmit as model input: strip the
+ * gateway's output-only fields ({@link OUTPUT_ONLY_CONTENT_FIELDS}) from each
+ * content block's `providerData` (where the SDK stores echoed provider fields,
+ * confirmed against the live gateway by the `--harness openai` e2e matrix). Deep-clones
+ * only the touched block(s), so the common (clean) item passes through untouched.
+ * Non-object items and items without a content array are returned as-is.
+ */
+function sanitizeForModelInput(item) {
+    const content = item.content;
+    if (!Array.isArray(content))
+        return item;
+    let mutated = false;
+    const cleanedContent = content.map((block) => {
+        if (block === null || typeof block !== 'object')
+            return block;
+        const providerData = block.providerData;
+        if (providerData === null || typeof providerData !== 'object')
+            return block;
+        const present = OUTPUT_ONLY_CONTENT_FIELDS.filter((f) => f in providerData);
+        if (present.length === 0)
+            return block;
+        mutated = true;
+        const cleanedProviderData = { ...providerData };
+        for (const f of present)
+            delete cleanedProviderData[f];
+        return { ...block, providerData: cleanedProviderData };
+    });
+    return mutated ? { ...item, content: cleanedContent } : item;
+}
+//# sourceMappingURL=openai-session-store.js.map

package/dist/openai-session-store.js.map

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

package/dist/openai-tool-mapper.d.ts

@@ -0,0 +1,121 @@
+import { type Tool } from '@openai/agents';
+import { type ToolDefinition } from '@salesforce/sfdx-agent-sdk';
+import { type RedactionContext } from './openai-tool-redaction.js';
+/** The outcome a consumer supplies for a parked tool call via `submitToolResult`. */
+export type ConsumerToolOutcome = {
+    result: unknown;
+    isError?: boolean;
+};
+/**
+ * Per-turn registry for consumer-executed (client-side) tools — those declared
+ * in `AgentConfig.tools` with no `execute`. The harness registers them with the
+ * model so it can call them, but never runs them: the mapped tool's `execute`
+ * PARKS on a promise this registry hands out, and the consumer resolves it
+ * out-of-band via `submitToolResult`. A parked `execute` resolved later lets the
+ * `@openai/agents` run loop continue on the same run — no in-process MCP bridge
+ * needed.
+ *
+ * Keyed by `toolCallId`, read directly off `details.toolCall.callId` at execute
+ * entry (the SDK populates it before invoking the tool), so binding is a direct
+ * map insert — no FIFO-by-name matching.
+ *
+ * Idempotent settle (#589): a second `settle` on the same id, or a settle after
+ * teardown rejected it, is a silent no-op; a `toolCallId` that never parked is
+ * genuine misuse and throws `TOOL_CALL_NOT_FOUND`.
+ */
+export declare class ConsumerToolRegistry {
+    readonly toolNames: ReadonlySet<string>;
+    /** Parked calls awaiting a consumer result, by `toolCallId`. */
+    private readonly pending;
+    /**
+     * Outcomes the consumer submitted BEFORE the tool's `execute` parked, by
+     * `toolCallId`. The harness emits the `tool-call` ChatEvent the moment the SDK
+     * enqueues `tool_called` — which is BEFORE it awaits `execute` — so a consumer
+     * iterating the stream can call `submitToolResult` before the parker
+     * registers. Buffer it here; `park` drains it immediately so the result is
+     * never lost to the race.
+     */
+    private readonly preSubmitted;
+    /** Ids already settled (by consumer or teardown), so a repeat settle is a no-op. */
+    private readonly settled;
+    /**
+     * Consumer-tool call ids the consumer settled with `isError: true`. The run
+     * loop persists the resulting `function_call_result` with no `isError` field
+     * (the OpenAI item shape can't carry it), so the coordinator reads this after
+     * the turn settles and stamps `isError` onto those records out-of-band,
+     * satisfying the #647 "isError survives to history" contract.
+     */
+    private readonly erroredIds;
+    /**
+     * Consumer-tool call ids the coordinator has surfaced as a `tool-call`
+     * ChatEvent this turn. A `settle` for a not-yet-parked id is buffered only
+     * when the id is here (an early-arriving result); an id never seen is genuine
+     * misuse and throws.
+     */
+    private readonly emitted;
+    /** Whether the turn has torn down — a park after teardown resolves immediately as an error. */
+    private tornDown;
+    /** Error to resolve late parks with after teardown. */
+    private teardownError?;
+    /** The bare names of the consumer tools registered this turn (for dual-enforcement checks). */
+    constructor(toolNames: ReadonlySet<string>);
+    /**
+     * Called by a mapped tool's `execute` at invocation. Returns a promise that
+     * settles when the consumer calls `submitToolResult` for `toolCallId`. It
+     * REJECTS only on teardown (so the run loop unblocks rather than hanging on a
+     * promise that will never settle); a normal settle — including an
+     * `isError: true` one — RESOLVES with the outcome, because a consumer-reported
+     * tool failure must reach the model as a recoverable tool output, not throw
+     * out of the run loop (the {@link ToolResultInfo.isError} contract). The
+     * mapper's `execute` turns the outcome into the model-visible value. A park
+     * after teardown rejects immediately.
+     */
+    park(toolCallId: string): Promise<ConsumerToolOutcome>;
+    /**
+     * Record that the coordinator surfaced `toolCallId` as a `tool-call`
+     * ChatEvent — so a `submitToolResult` that races ahead of the parker (the
+     * SDK emits `tool_called` before awaiting `execute`) is buffered rather than
+     * rejected.
+     */
+    markEmitted(toolCallId: string): void;
+    /**
+     * Settle a consumer tool call with the consumer's result. Resolves the parked
+     * `execute` if it has registered; otherwise buffers the outcome for the
+     * imminent `park` (the emit-before-await race) when the id was surfaced this
+     * turn. Idempotent (#589); throws `TOOL_CALL_NOT_FOUND` for an id the
+     * coordinator never surfaced.
+     */
+    settle(toolCallId: string, outcome: ConsumerToolOutcome): void;
+    /**
+     * The consumer-tool call ids settled with `isError: true` this turn — the
+     * records the coordinator stamps `isError` on after the run settles, since
+     * the run loop persists the `function_call_result` without it.
+     */
+    erroredToolCallIds(): readonly string[];
+    /**
+     * Reject every parked call on teardown so the run loop unblocks instead of
+     * hanging on a promise that will never settle. Marks all pending ids settled
+     * so a late consumer `submitToolResult` is a silent no-op (#589).
+     */
+    rejectAll(error: Error): void;
+}
+/**
+ * Map an agent's consumer-tool `ToolDefinition[]` to `@openai/agents` function
+ * tools whose `execute` parks on the shared {@link ConsumerToolRegistry}. Every
+ * tool gets `needsApproval: false` — consumer tools are the consumer's
+ * responsibility via `submitToolResult` and are NEVER approval-gated (the
+ * dual-enforcement contract: the coordinator also short-circuits them by name
+ * before consulting the policy resolver).
+ *
+ * The mapped `execute` reads its own `toolCallId` from `details.toolCall.callId`
+ * (populated by the SDK before invocation) and parks under it; the returned
+ * value becomes the tool's output the model sees.
+ *
+ * When `redaction` is supplied (the agent has an `onToolResult` hook), the
+ * parked result passes through the redactor at this seam — before it becomes the
+ * model-visible output — with full fidelity (`agentId` / `threadId` /
+ * `toolCallId` / `toolName` / `serverName` all known). A redactor throw
+ * propagates out of `execute` (the pump's `catch` synthesizes the terminal
+ * error + finish pair), per the SDK's throws-propagate contract.
+ */
+export declare function mapConsumerTools(defs: ToolDefinition[], registry: ConsumerToolRegistry, redaction?: RedactionContext): Tool[];