@salesforce/sfdx-agent-harness-openai 0.0.1

package/dist/openai-event-adapter.js

@@ -0,0 +1,322 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * 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 class OpenAIEventAdapter {
+    mcpCatalog;
+    stepIndex = 0;
+    started = false;
+    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`).
+     */
+    deferredStepFinish;
+    /** Outstanding `tool_output`s for the deferred step; `step-finish` flushes at 0. */
+    pendingToolOutputs = 0;
+    /**
+     * 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) {
+        this.mcpCatalog = mcpCatalog;
+    }
+    /**
+     * Map one `RunStreamEvent` to zero or more `ChatEvent`s. Emits a synthetic
+     * `start` before the first mapped event.
+     */
+    map(event) {
+        const out = [];
+        if (!this.started) {
+            this.started = true;
+            out.push({ type: 'start' });
+        }
+        if (event.type === 'raw_model_stream_event') {
+            this.mapRaw(event.data, out);
+        }
+        else if (event.type === 'run_item_stream_event') {
+            this.mapRunItem(event, out);
+        }
+        // `agent_updated_stream_event` (handoffs) is not used by this harness.
+        return out;
+    }
+    /**
+     * 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.
+     */
+    mapRunItem(event, out) {
+        if (event.name === 'tool_called') {
+            const item = event.item;
+            const raw = item.rawItem ?? {};
+            const toolName = item.toolName ?? raw.name;
+            const toolCallId = item.callId ?? raw.callId;
+            if (toolName === undefined || toolCallId === undefined)
+                return;
+            out.push({
+                type: 'tool-call',
+                toolCallId,
+                toolName,
+                args: parseArgs(raw.arguments),
+                ...this.enrich(toolName),
+            });
+        }
+        else if (event.name === 'tool_output') {
+            const item = event.item;
+            const raw = item.rawItem ?? {};
+            const toolCallId = item.callId ?? raw.callId;
+            const toolName = raw.name;
+            if (toolName === undefined || toolCallId === undefined)
+                return;
+            out.push({
+                type: 'tool-result',
+                toolCallId,
+                toolName,
+                result: normalizeOutput(item.output ?? raw.output),
+                ...this.enrich(toolName),
+            });
+            // The tool-result is now emitted INSIDE its step. Once every tool
+            // output of the deferred step has drained, flush the held
+            // `step-finish` so it closes the step after its results.
+            if (this.pendingToolOutputs > 0) {
+                this.pendingToolOutputs -= 1;
+                if (this.pendingToolOutputs === 0)
+                    this.flushDeferredStepFinish(out);
+            }
+        }
+        // Other run-item names (message_output_created, reasoning_item_created,
+        // handoff_*, tool_search_*, tool_approval_requested) are not mapped —
+        // skipped.
+    }
+    /**
+     * 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.
+     */
+    enrich(toolName) {
+        const entry = this.mcpCatalog?.get(toolName);
+        if (entry === undefined)
+            return {};
+        return {
+            serverName: entry.serverName,
+            bareToolName: toolName,
+            ...(entry.annotations !== undefined ? { annotations: entry.annotations } : {}),
+        };
+    }
+    /**
+     * The last per-step usage observed, used to populate the terminal `finish`
+     * event the pump synthesizes when the run stream completes cleanly.
+     */
+    lastUsage() {
+        return this.lastStepUsage;
+    }
+    /**
+     * 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() {
+        if (this.started)
+            return [];
+        this.started = true;
+        return [{ type: 'start' }];
+    }
+    mapRaw(data, out) {
+        // The raw model stream is the OpenAI Agents SDK's protocol `StreamEvent`
+        // union: `output_text_delta` | `response_started` | `response_done` |
+        // generic item events. We map the three text/step shapes.
+        switch (data.type) {
+            case 'output_text_delta': {
+                out.push({ type: 'text-delta', text: data.delta });
+                break;
+            }
+            case 'response_started': {
+                // Defensive: if a prior step's tool outputs never fully drained
+                // (a tool call with no matching `tool_output`), flush its held
+                // `step-finish` before opening the next step so steps never nest.
+                this.flushDeferredStepFinish(out);
+                out.push({ type: 'step-start', stepIndex: this.stepIndex });
+                break;
+            }
+            case 'response_done': {
+                const usage = mapUsage(data.response?.usage);
+                this.lastStepUsage = usage;
+                const stepFinish = {
+                    type: 'step-finish',
+                    stepIndex: this.stepIndex,
+                    // A completed model response is reported as a natural stop; the
+                    // step-level `finishReason` does not distinguish a tool-call step.
+                    finishReason: 'stop',
+                    ...(usage !== undefined ? { usage } : {}),
+                };
+                this.stepIndex += 1;
+                // A tool-calling step emits its `tool_called` / `tool_output`
+                // run-items AFTER this `response_done`. Hold the `step-finish`
+                // until those outputs drain so the `tool-result` lands inside the
+                // step; a step with no tool calls closes inline as before.
+                const toolCallCount = countFunctionCalls(data.response?.output);
+                if (toolCallCount > 0) {
+                    this.deferredStepFinish = stepFinish;
+                    this.pendingToolOutputs = toolCallCount;
+                }
+                else {
+                    out.push(stepFinish);
+                }
+                break;
+            }
+            // Generic item events (reasoning, tool-search, etc.) are not mapped
+            // to a ChatEvent — skipped.
+        }
+    }
+    /**
+     * 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) {
+        if (this.deferredStepFinish === undefined)
+            return;
+        out.push(this.deferredStepFinish);
+        this.deferredStepFinish = undefined;
+        this.pendingToolOutputs = 0;
+    }
+    /** Emit any held `step-finish` as a standalone event list (pump terminal path). */
+    drainDeferredStepFinish() {
+        const out = [];
+        this.flushDeferredStepFinish(out);
+        return out;
+    }
+}
+/**
+ * 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 function mapUsage(usage) {
+    if (usage === undefined)
+        return undefined;
+    const inputTokens = usage.inputTokens;
+    const outputTokens = usage.outputTokens;
+    const totalTokens = usage.totalTokens;
+    const cachedInputTokens = pickDetail(usage.inputTokensDetails, 'cached_tokens');
+    const reasoningTokens = pickDetail(usage.outputTokensDetails, 'reasoning_tokens');
+    const mapped = {};
+    if (inputTokens)
+        mapped.inputTokens = inputTokens;
+    if (outputTokens)
+        mapped.outputTokens = outputTokens;
+    if (totalTokens)
+        mapped.totalTokens = totalTokens;
+    if (cachedInputTokens)
+        mapped.cachedInputTokens = cachedInputTokens;
+    if (reasoningTokens)
+        mapped.reasoningTokens = reasoningTokens;
+    // If every field is falsy the stream reported no usage — collapse to
+    // undefined so a downstream `getContextUsage` doesn't clobber a prior
+    // reading with a populated-but-empty object.
+    return Object.keys(mapped).length > 0 ? mapped : undefined;
+}
+/**
+ * Reads a numeric detail (e.g. `cached_tokens`, `reasoning_tokens`) from the
+ * details shape, which may be a single record or an array of records (the SDK
+ * types it as a union). Sums across array entries.
+ */
+function pickDetail(details, key) {
+    if (details === undefined)
+        return undefined;
+    const records = Array.isArray(details) ? details : [details];
+    let sum = 0;
+    let seen = false;
+    for (const record of records) {
+        const value = record[key];
+        if (typeof value === 'number') {
+            sum += value;
+            seen = true;
+        }
+    }
+    return seen ? sum : undefined;
+}
+/**
+ * Count the `function_call` items on a `response_done` output. A tool-calling
+ * step carries one `function_call` per tool the model requested; the run loop
+ * then emits a matching `tool_output` run-item per call after the response
+ * completes. The count tells the adapter how many `tool_output`s to wait for
+ * before flushing the step's deferred `step-finish`.
+ */
+function countFunctionCalls(output) {
+    if (!Array.isArray(output))
+        return 0;
+    return output.filter((item) => typeof item === 'object' && item !== null && item.type === 'function_call').length;
+}
+/** Parse a `function_call` item's JSON `arguments` string into an args object. */
+function parseArgs(raw) {
+    if (typeof raw !== 'string')
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed === 'object' && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Normalize a tool result's `output` (a bare string, a `{ type:'text'; text }`
+ * object, or another structured shape) to the value carried on the SDK
+ * `tool-result` ChatEvent's `result`. Mirrors the message mapper's read-path
+ * normalization so a result surfaces identically on the stream and in history.
+ */
+function normalizeOutput(output) {
+    if (typeof output === 'string')
+        return output;
+    if (typeof output === 'object' && output !== null && output.type === 'text') {
+        return output.text ?? '';
+    }
+    return output;
+}
+//# sourceMappingURL=openai-event-adapter.js.map

package/dist/openai-event-adapter.js.map

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

package/dist/openai-mcp-config-mapper.d.ts

@@ -0,0 +1,58 @@
+import type { JSONWebToken } from '@salesforce/agentic-common';
+import { type MCPConfiguration, type MCPServerConfig } from '@salesforce/sfdx-agent-sdk';
+import { MCPServerStdio, MCPServerStreamableHttp, type MCPServer } from '@openai/agents';
+/**
+ * The `@openai/agents` MCP server constructor options. The SDK exports the
+ * server classes from its top-level entry but not their option interfaces, so
+ * we derive each from its constructor rather than reaching through a `dist/`
+ * deep import (which the SDK-import invariant forbids).
+ */
+type MCPServerStdioOptions = ConstructorParameters<typeof MCPServerStdio>[0];
+type MCPServerStreamableHttpOptions = ConstructorParameters<typeof MCPServerStreamableHttp>[0];
+/**
+ * Returns `true` if `config` contains at least one server that is not explicitly
+ * disabled. A server is enabled when its `enabled` property is `true` or absent.
+ * Mirrors the sibling harnesses' `hasEnabledServers` guard so a config of all
+ * disabled servers allocates no `@openai/agents` MCP client.
+ */
+export declare function hasEnabledServers(config: MCPConfiguration | undefined): config is MCPConfiguration;
+/** A discriminated, ready-to-construct options bag for one `@openai/agents` MCP server. */
+export type OpenAIMcpServerOptions = {
+    readonly kind: 'stdio';
+    readonly options: MCPServerStdioOptions;
+} | {
+    readonly kind: 'remote';
+    readonly options: MCPServerStreamableHttpOptions;
+};
+/**
+ * Map one SDK {@link McpServerConfig} to the plain `@openai/agents` constructor
+ * options bag — WITHOUT constructing the client. Splitting the pure mapping from
+ * the instance construction serves two callers:
+ *
+ * 1. {@link mapToOpenAIMcpServers} constructs the live clients from it.
+ * 2. The conformance seam (`readReconnectionOptions`) reads the forwarded
+ *    `reconnectionOptions` off `.options` deterministically — no reliance on the
+ *    constructed `MCPServer` surfacing the field, mirroring how the Mastra seam
+ *    reads its mapped server-definition object rather than the client.
+ *
+ * Every server carries `cacheToolsList: true` and `name: <configKey>` — the
+ * #541 keystone: the tool-list cache lives on the instance and is keyed by
+ * `server.name`, so a rebuilt `Agent` reusing the same connected instance skips
+ * `tools/list`.
+ *
+ * Remote servers get an auth-injecting `fetch` (via {@link resolveMcpServerHeaders})
+ * when `orgJwt` is supplied, so a rotating Salesforce JWT lands per request; the
+ * config's own `headers` ride through `requestInit`. Stdio env vars are frozen
+ * at spawn (the stdio transport has no per-request hook — see
+ * `MCPStdioServerConfig.env`).
+ */
+export declare function toOpenAIMcpServerOptions(name: string, config: MCPServerConfig, orgJwt?: JSONWebToken, innerFetch?: typeof fetch): OpenAIMcpServerOptions;
+/**
+ * Converts an {@link MCPConfiguration} into live `@openai/agents` {@link MCPServer}
+ * instances keyed by config server name. Servers with `enabled === false` are
+ * omitted so no client is constructed for them. Construction does no I/O
+ * (`@openai/agents` connects lazily); the harness owns the `connect()` /
+ * `close()` lifecycle.
+ */
+export declare function mapToOpenAIMcpServers(config: MCPConfiguration, orgJwt?: JSONWebToken, innerFetch?: typeof fetch): Map<string, MCPServer>;
+export {};

package/dist/openai-mcp-config-mapper.js

@@ -0,0 +1,133 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { resolveMcpServerHeaders } from '@salesforce/sfdx-agent-sdk';
+import { MCPServerStdio, MCPServerStreamableHttp } from '@openai/agents';
+/**
+ * MCP SDK's built-in `StreamableHTTPReconnectionOptions` defaults. This is a
+ * byte-identical copy of the Mastra harness's `DEFAULT_RECONNECTION_OPTIONS`
+ * (`mcp-config-mapper.ts`) and the Claude harness's copy
+ * (`mcp-client-factory.ts`) — cross-harness imports are lint-blocked
+ * (`harnessIsolationPack`), so the constant is duplicated on purpose and the
+ * shared `@salesforce/harness-conformance` `RECONNECTION_DEFAULTS` table is the
+ * drift-guard that keeps the three in lockstep.
+ *
+ * The field-wise merge below (`{ ...DEFAULT_RECONNECTION_OPTIONS, ...input }`)
+ * is required because the underlying transport replaces the entire defaults
+ * object when `reconnectionOptions` is set — a partial override would otherwise
+ * zero out the unspecified fields.
+ */
+const DEFAULT_RECONNECTION_OPTIONS = {
+    maxRetries: 2,
+    initialReconnectionDelay: 1000,
+    maxReconnectionDelay: 30000,
+    reconnectionDelayGrowFactor: 1.5,
+};
+/**
+ * Returns `true` if `config` contains at least one server that is not explicitly
+ * disabled. A server is enabled when its `enabled` property is `true` or absent.
+ * Mirrors the sibling harnesses' `hasEnabledServers` guard so a config of all
+ * disabled servers allocates no `@openai/agents` MCP client.
+ */
+export function hasEnabledServers(config) {
+    if (!config)
+        return false;
+    return Object.values(config).some((s) => s.enabled !== false);
+}
+/**
+ * Map one SDK {@link McpServerConfig} to the plain `@openai/agents` constructor
+ * options bag — WITHOUT constructing the client. Splitting the pure mapping from
+ * the instance construction serves two callers:
+ *
+ * 1. {@link mapToOpenAIMcpServers} constructs the live clients from it.
+ * 2. The conformance seam (`readReconnectionOptions`) reads the forwarded
+ *    `reconnectionOptions` off `.options` deterministically — no reliance on the
+ *    constructed `MCPServer` surfacing the field, mirroring how the Mastra seam
+ *    reads its mapped server-definition object rather than the client.
+ *
+ * Every server carries `cacheToolsList: true` and `name: <configKey>` — the
+ * #541 keystone: the tool-list cache lives on the instance and is keyed by
+ * `server.name`, so a rebuilt `Agent` reusing the same connected instance skips
+ * `tools/list`.
+ *
+ * Remote servers get an auth-injecting `fetch` (via {@link resolveMcpServerHeaders})
+ * when `orgJwt` is supplied, so a rotating Salesforce JWT lands per request; the
+ * config's own `headers` ride through `requestInit`. Stdio env vars are frozen
+ * at spawn (the stdio transport has no per-request hook — see
+ * `MCPStdioServerConfig.env`).
+ */
+export function toOpenAIMcpServerOptions(name, config, orgJwt, innerFetch = fetch) {
+    if (config.type === 'stdio') {
+        return {
+            kind: 'stdio',
+            options: {
+                name,
+                command: config.command,
+                cacheToolsList: true,
+                ...(config.args !== undefined ? { args: config.args } : {}),
+                ...(config.env !== undefined ? { env: config.env } : {}),
+                ...(config.timeout !== undefined ? { timeout: config.timeout } : {}),
+            },
+        };
+    }
+    if (config.type === 'remote') {
+        const url = String(config.url);
+        return {
+            kind: 'remote',
+            options: {
+                name,
+                url,
+                cacheToolsList: true,
+                ...(config.timeout !== undefined ? { timeout: config.timeout } : {}),
+                ...(config.reconnectionOptions !== undefined
+                    ? { reconnectionOptions: { ...DEFAULT_RECONNECTION_OPTIONS, ...config.reconnectionOptions } }
+                    : {}),
+                // When an orgJwt is present, inject fresh auth per request for
+                // Salesforce Platform URLs (a no-op passthrough for other hosts);
+                // the config's static headers ride through `requestInit`.
+                ...(orgJwt !== undefined ? { fetch: createAuthFetch(url, orgJwt, innerFetch, config.headers) } : {}),
+                ...(config.headers !== undefined ? { requestInit: { headers: config.headers } } : {}),
+            },
+        };
+    }
+    // Exhaustiveness guard: a new discriminant must be handled here explicitly.
+    throw new Error(`Unsupported MCP server config type "${config.type ?? 'unknown'}". ` +
+        'Update toOpenAIMcpServerOptions to handle this type.');
+}
+/**
+ * Converts an {@link MCPConfiguration} into live `@openai/agents` {@link MCPServer}
+ * instances keyed by config server name. Servers with `enabled === false` are
+ * omitted so no client is constructed for them. Construction does no I/O
+ * (`@openai/agents` connects lazily); the harness owns the `connect()` /
+ * `close()` lifecycle.
+ */
+export function mapToOpenAIMcpServers(config, orgJwt, innerFetch = fetch) {
+    const servers = new Map();
+    for (const [name, serverConfig] of Object.entries(config)) {
+        if (serverConfig.enabled === false)
+            continue;
+        const mapped = toOpenAIMcpServerOptions(name, serverConfig, orgJwt, innerFetch);
+        const server = mapped.kind === 'stdio' ? new MCPServerStdio(mapped.options) : new MCPServerStreamableHttp(mapped.options);
+        servers.set(name, server);
+    }
+    return servers;
+}
+/**
+ * Build a `fetch` that resolves fresh MCP auth headers per request. Copied from
+ * the Mastra harness's `createAuthFetch` — {@link resolveMcpServerHeaders}
+ * injects the rotating JWT only for Salesforce Platform MCP URLs and passes
+ * every other URL through unchanged, so this is safe to wire on any remote
+ * server whenever an `orgJwt` is available.
+ */
+function createAuthFetch(serverUrl, orgJwt, innerFetch, existingHeaders) {
+    return async (url, init) => {
+        const authHeaders = await resolveMcpServerHeaders(serverUrl, orgJwt, existingHeaders);
+        const merged = new Headers(init?.headers);
+        for (const [key, value] of Object.entries(authHeaders)) {
+            merged.set(key, value);
+        }
+        return innerFetch(url, { ...init, headers: merged });
+    };
+}
+//# sourceMappingURL=openai-mcp-config-mapper.js.map

package/dist/openai-mcp-config-mapper.js.map

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

package/dist/openai-mcp-state.d.ts

@@ -0,0 +1,67 @@
+import type { MCPServer } from '@openai/agents';
+import type { MCPServerConfig, McpServerErrorDetail, McpServerStatus, McpToolAnnotations, McpToolInfo } from '@salesforce/sfdx-agent-sdk';
+/**
+ * Per-agent, per-server MCP state the harness tracks, keyed by the server name
+ * (the key in `AgentConfig.mcpServers`). Holds the live `@openai/agents`
+ * {@link MCPServer} instance — the unit `updateAgent` preserves when the config
+ * is structurally unchanged (#541) — alongside the discovery snapshot
+ * `getMcpServerInfo` reads.
+ *
+ * Deliberately simpler than the Mastra harness's `McpServerState`:
+ * - **No `epoch` counter.** Orphaned writes from a superseded discovery are
+ *   guarded by an instance-identity check (`state.mcpServers.get(name)?.server
+ *   === capturedServer`) rather than a monotonic epoch — a cycle always
+ *   constructs a fresh instance, so identity is sufficient.
+ * - **No `httpErrorCapture`.** The `@mastra/mcp` transport discards the HTTP
+ *   status on its SSE-fallback path (#617), forcing Mastra to wrap the fetch to
+ *   recover it; the `@openai/agents` `MCPServerStreamableHttp` transport does
+ *   not have that wart, so the classifier works from the thrown error's
+ *   message/code alone (and the same message/code feeds the discovery telemetry).
+ * - **No `settled` flag.** Folded into {@link status} (`Connecting` until the
+ *   background discovery resolves to `Connected` or `Error`).
+ */
+export type OpenAIMcpServerState = {
+    /**
+     * The live `@openai/agents` MCP client. Harness-owned (the SDK never closes
+     * it independently); a rebuilt `Agent` reusing this same connected instance
+     * skips `tools/list` because `cacheToolsList: true` caches on the instance.
+     * This is the preserve unit for the #541 `updateAgent` contract.
+     */
+    readonly server: MCPServer;
+    /**
+     * The `MCPServerConfig` that produced this instance. Retained so
+     * `updateAgent` can diff the next config against it via
+     * `mcpServerConfigEqual` to decide preserve vs. cycle.
+     */
+    config: MCPServerConfig;
+    /** Source-of-truth connection status for `getMcpServerInfo`. */
+    status: McpServerStatus;
+    /** Discovered tools (bare names) as `McpToolInfo[]`; populated on discovery settle. */
+    tools: McpToolInfo[];
+    /** Sanitized, single-line error message; set when {@link status} is `Error`. */
+    error?: string;
+    /** Structured error projection for programmatic routing; set alongside {@link error}. */
+    errorDetail?: McpServerErrorDetail;
+    /**
+     * The in-flight (or settled) background discovery promise. Awaited by
+     * `destroyAgent` / `shutdown` before `close()` so teardown never races an
+     * in-flight `connect()` / `listTools()`.
+     */
+    ready: Promise<void>;
+};
+/**
+ * One entry in the per-agent MCP tool catalog: the mapping from a bare tool name
+ * to its originating server + declared annotations. The per-turn event adapter
+ * reads this to enrich `tool-call` / `tool-result` ChatEvents with `serverName`
+ * / `bareToolName` / `annotations` for MCP-sourced tools.
+ *
+ * The `@openai/agents` native MCP attach registers tools under their **bare**
+ * name (no `${server}_` namespacing), so the catalog key IS the bare tool name
+ * and equals the display `toolName` on the run-item events.
+ */
+export type McpCatalogEntry = {
+    /** The originating MCP server name (the `AgentConfig.mcpServers` key). */
+    readonly serverName: string;
+    /** Behavioral / UI-presentation hints the server declared for the tool, when present. */
+    readonly annotations?: McpToolAnnotations;
+};

package/dist/openai-mcp-state.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export {};
+//# sourceMappingURL=openai-mcp-state.js.map

package/dist/openai-mcp-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-mcp-state.js","sourceRoot":"","sources":["../src/openai-mcp-state.ts"],"names":[],"mappings":"AAAA;;;GAGG"}