@salesforce/sfdx-agent-harness-openai 0.0.1

package/dist/openai-agents-harness.d.ts

@@ -0,0 +1,302 @@
+import { type Clock, type LogRecord, type Unsubscribe, type UniqueIDGenerator } from '@salesforce/agentic-common';
+import { type MCPServer, type ModelProvider } from '@openai/agents';
+import { type ChatStreamResult, type HarnessAgentConfig, type MCPConfiguration, type McpServerInfo, type Message, type MessagePart, type ModelConnectivityInfo, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo, type WithAgentConfig, type WireCommunicationEventCallback } from '@salesforce/sfdx-agent-sdk';
+import type { AgentHarness } from '@salesforce/sfdx-agent-sdk';
+import type { AgentHooks } from '@salesforce/sfdx-agent-sdk';
+/**
+ * The branded harness subtype consumers see when they pass
+ * `OpenAIAgentsHarnessFactory` to `createAgentManager`. The harness ships no
+ * config extensions, so the config type stays the base `HarnessAgentConfig`.
+ */
+export type OpenAIAgentsAgentHarness = WithAgentConfig<AgentHarness & {
+    readonly harnessId: 'openai-agents';
+    readonly extensions: Record<string, never>;
+}, HarnessAgentConfig>;
+/** Internal constructor options (test seam; not part of the public surface). */
+export type OpenAIAgentsHarnessOptions = {
+    /** Proxy-aware inner fetch (honors HTTPS_PROXY / NO_PROXY). */
+    innerFetch?: typeof fetch;
+    /** ID generator for thread ids; defaults to `UUIDGenerator`. */
+    idGenerator?: UniqueIDGenerator;
+    /** Time source for `createdAt` stamping; defaults to `RealClock`. */
+    clock?: Clock;
+    /**
+     * Builds the `@openai/agents` model provider for an agent. Defaults to the
+     * gateway-bound {@link buildOpenAIModelProvider}. Unit tests pass a factory
+     * returning a scripted-`Model` provider so the real run loop executes with
+     * no network and no credentials.
+     */
+    modelProviderFactory?: (getInfo: () => ModelConnectivityInfo) => ModelProvider;
+    /**
+     * Builds the live `@openai/agents` MCP server instances for a config.
+     * Defaults to {@link mapToOpenAIMcpServers}. Unit tests pass a factory
+     * returning fake `MCPServer`s so MCP discovery / lifecycle / preservation
+     * can be exercised with no subprocess and no network (mirrors
+     * {@link modelProviderFactory}).
+     */
+    mcpServerFactory?: (config: MCPConfiguration, orgJwt?: HarnessAgentConfig['orgJwt']) => Map<string, MCPServer>;
+    /**
+     * Per-`toolCallId` tool-approval timeout, in milliseconds, forwarded to each
+     * turn's `OpenAIApprovalCoordinator`. Defaults to the coordinator's own
+     * 600_000 ms when unset. Threaded from `OpenAIAgentsHarnessFactoryConfig`.
+     */
+    toolApprovalTimeoutMs?: number;
+};
+/**
+ * OpenAI Agents SDK-backed implementation of the SDK's `AgentHarness` contract.
+ *
+ * Implements connectivity, streamed turns, disk-backed sessions, thread
+ * lifecycle, message history (with `createdAt`/`isError` persistence), tool
+ * approval (`approveToolCall` / `declineToolCall`), consumer-executed tools
+ * (`submitToolResult`), MCP server lifecycle (`getMcpServerInfo` /
+ * `reconnectMcpServer` / `updateAgent` preservation), and thread compaction
+ * (`compactThread`). A per-`(agentId, threadId)` {@link OpenAIApprovalCoordinator}
+ * owns each turn's run loop, the approval suspend/resume flow, the opt-in policy
+ * gate, the per-`toolCallId` timeout, and the consumer-tool parker.
+ *
+ * MCP tools attach via the SDK's native `Agent({ mcpServers })` path and are
+ * observable (`tool-call` / `tool-result`, enriched with `serverName` /
+ * `bareToolName`) but are NOT approval-gated this milestone — the native attach
+ * exposes no per-tool `needsApproval` hook, so gating is a deferred follow-up.
+ * MCP discovery/status telemetry and wire-communication events emit on their
+ * respective seams, and the `options.hooks.onToolResult` redaction hook fires
+ * per tool result (consumer tools at the parked `execute`; MCP tools via a
+ * `getAllMcpTools` materialize-and-wrap when a redactor is set). Every
+ * agent-scoped method throws `AGENT_NOT_FOUND` on an unregistered id first (SDK
+ * invariant).
+ */
+export declare class OpenAIAgentsHarness implements OpenAIAgentsAgentHarness {
+    private readonly storageRootFolder;
+    readonly harnessId: "openai-agents";
+    readonly protocolVersion: 1;
+    readonly extensions: Record<string, never>;
+    private readonly buses;
+    private readonly agents;
+    private readonly idGenerator;
+    private readonly clock;
+    private readonly innerFetch?;
+    private readonly modelProviderFactory;
+    private readonly mcpServerFactory;
+    private readonly sessions;
+    private readonly toolApprovalTimeoutMs?;
+    private shuttingDown;
+    constructor(storageRootFolder: string, options?: OpenAIAgentsHarnessOptions);
+    onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
+    onLog(callback: (record: LogRecord) => void): Unsubscribe;
+    onWireCommunication(callback: WireCommunicationEventCallback): Unsubscribe;
+    shutdown(): Promise<void>;
+    createAgent(agentId: string, projectRoot: string, modelConnectivityInfo: ModelConnectivityInfo, config?: HarnessAgentConfig, options?: {
+        abortSignal?: AbortSignal;
+        hooks?: AgentHooks;
+    }): Promise<void>;
+    destroyAgent(agentId: string): Promise<boolean>;
+    getAgentIds(): Promise<string[]>;
+    createThread(agentId: string, threadId?: string): Promise<string>;
+    getThreadIds(agentId: string): Promise<string[]>;
+    destroyThread(agentId: string, threadId: string): Promise<void>;
+    cloneThread(agentId: string, sourceThreadId: string): Promise<string>;
+    stream(agentId: string, threadId: string, message: string | MessagePart[], options?: StreamOptions): Promise<ChatStreamResult>;
+    getMessages(agentId: string, threadId: string): Promise<Message[]>;
+    clearMessages(agentId: string, threadId: string): Promise<void>;
+    addContext(agentId: string, threadId: string, messages: Message[]): Promise<void>;
+    /**
+     * Apply a new connectivity bag + config to a live agent, preserving any MCP
+     * client whose config is structurally unchanged (#541) and cycling only the
+     * changed/added/removed servers. No eager `Agent` rebuild is needed: this
+     * harness constructs a fresh `Agent` on every `stream()` (see
+     * {@link buildAgent}) reading `state.config` / `state.modelConnectivityInfo`
+     * / `state.mcpServers` live, so mutating state here is sufficient — the next
+     * turn picks up the change. Does NOT dispose in-flight coordinators, touch
+     * sessions, or persist (persistence is the SDK's responsibility).
+     */
+    updateAgent(agentId: string, modelConnectivityInfo: ModelConnectivityInfo, config?: HarnessAgentConfig, options?: {
+        abortSignal?: AbortSignal;
+        hooks?: AgentHooks;
+    }): Promise<void>;
+    /**
+     * Synchronous snapshot of the agent's MCP servers: connected servers with
+     * their discovered tools, errored servers with a sanitized message +
+     * structured `errorDetail`, in-flight servers as `Connecting` /
+     * `Reconnecting`, and configured-but-disabled servers (never constructed) as
+     * `Disabled`. Status is updated asynchronously by background discovery, so a
+     * caller polls this to observe a `createAgent` / `reconnectMcpServer` result.
+     */
+    getMcpServerInfo(agentId: string): McpServerInfo[];
+    /**
+     * Cycle one MCP server's transport and re-discover its tools. Eager: awaits
+     * the close → connect → `invalidateToolsCache` → `listTools` round-trip, but
+     * a transient transport / discovery failure is recorded on per-server state
+     * (surfaced via `getMcpServerInfo`) rather than rejected — only the three
+     * programming errors throw. `getAgentOrThrow` runs first (AGENT_NOT_FOUND
+     * wins), then an unconfigured server throws `MCP_SERVER_NOT_FOUND` and a
+     * disabled one `MCP_SERVER_DISABLED`.
+     */
+    reconnectMcpServer(agentId: string, serverName: string): Promise<void>;
+    /**
+     * Compact a thread's history into a fresh thread seeded with an LLM-generated
+     * summary, then destroy the source (the `AgentHarness` contract). The OpenAI
+     * Agents SDK ships a server-side `OpenAIResponsesCompactionAwareSession.runCompaction`
+     * (via `responses.compact`), but it relies on `previous_response_id` /
+     * stored responses — unavailable against the stateless Salesforce gateway
+     * (`store: false`, the same reason the coordinator pins `reasoningItemIdPolicy: 'omit'`).
+     * So this hand-rolls summarize+seed+destroy, mirroring the Mastra/Claude harnesses.
+     *
+     * `getAgentOrThrow` runs first (AGENT_NOT_FOUND). An empty source is compacted
+     * to a fresh empty thread (leaving it attached would leak). A summarization or
+     * seed failure surfaces as `AgentSDKError(COMPACTION_FAILED)` with the source
+     * left intact; the source is destroyed best-effort only after the new thread
+     * is safely seeded.
+     */
+    compactThread(agentId: string, threadId: string): Promise<string>;
+    /**
+     * Feed a consumer-executed tool's result back into the thread's in-flight
+     * turn. `getAgentOrThrow` runs FIRST (AGENT_NOT_FOUND wins over the
+     * coordinator lookup, per the SDK invariant); a thread with no in-flight
+     * coordinator throws `TOOL_CALL_NOT_FOUND`. The coordinator resolves the
+     * parked `execute` keyed by `toolCallId`, the run continues on the SAME
+     * eventStream the consumer is already iterating, and idempotency (#589) is
+     * owned downstream. `error` rides through as an error-shaped outcome so a
+     * consumer-reported failure reaches the tool call.
+     */
+    submitToolResult(agentId: string, threadId: string, toolResult: ToolResultInfo): Promise<void>;
+    approveToolCall(agentId: string, threadId: string, toolCallId: string): Promise<void>;
+    declineToolCall(agentId: string, threadId: string, toolCallId: string): Promise<void>;
+    /**
+     * Forward an approve / decline to the thread's in-flight coordinator.
+     * `getAgentOrThrow` runs FIRST so an unregistered agent surfaces
+     * `AGENT_NOT_FOUND` (the SDK invariant: agent-registry check before the
+     * per-`(agentId, threadId)` coordinator lookup) — distinguishable from a
+     * registered agent with no in-flight run, which throws `TOOL_CALL_NOT_FOUND`.
+     * The coordinator owns idempotency (#589): a repeat / post-teardown settle is
+     * a silent no-op there. Post-resume events flow through the SAME eventStream
+     * the consumer is already iterating from `stream()`.
+     */
+    private settleToolApproval;
+    /**
+     * Build the `@openai/agents` `Agent` + `Runner` a turn runs against. One seam
+     * for the pair so a `stream()` constructs them identically each turn. The
+     * `Runner` binds the agent's live `modelProvider` (JWT rotation lands per
+     * request) with tracing off. `tools` carries the turn's consumer-executed
+     * tools (mapped from `config.tools`).
+     *
+     * **MCP attach, two paths.** Without a redaction hook (`redaction`
+     * undefined — the common case), the agent's live MCP server instances attach
+     * via the native `mcpServers` field; the SDK fetches their tools per run.
+     * Because each instance has `cacheToolsList: true` (cache keyed by
+     * `server.name`) and this harness reuses the SAME connected instances across
+     * turns, a rebuilt `Agent` here does not re-run `tools/list` for a preserved
+     * server — the #541 preservation mechanic. MCP tools are NOT approval-gated
+     * this milestone (the native attach exposes no per-tool `needsApproval`).
+     *
+     * **When a redaction hook is set,** the native attach exposes no per-result
+     * rewrite seam, so MCP tools are materialized via `getAllMcpTools(...)` and
+     * their `invoke` wrapped with the redactor (see {@link buildRedactedMcpTools});
+     * they attach as `tools` rather than `mcpServers`. #541 is preserved because
+     * `getAllMcpTools` reads each server's warm `cacheToolsList` cache with no
+     * network `tools/list`. This makes the method async (the materialize awaits
+     * `listTools()`), so `stream()` awaits it.
+     */
+    private buildAgent;
+    /**
+     * One-shot, non-agentic summarization for `compactThread`. Builds a throwaway
+     * `Agent` (summarization-role instructions, NO tools, NO MCP servers) bound to
+     * the agent's live `modelProvider`, and runs it non-streaming with no
+     * `session` (the summary call must not leak into the thread's persisted
+     * history). Returns the model's final text; throws if it produced none.
+     *
+     * `reasoningItemIdPolicy: 'omit'` is load-bearing for the same reason the
+     * turn coordinator pins it — the stateless gateway (`store: false`) rejects
+     * reasoning items sent by id reference.
+     */
+    private summarize;
+    /**
+     * Two-pass summarization for transcripts above {@link MAX_TRANSCRIPT_CHARS}.
+     * Splits on line boundaries, summarizes each chunk, then summarizes the
+     * concatenated chunk-summaries (recursing if the merge itself is still over
+     * budget). Mirrors the sibling harnesses' map/reduce so cross-harness
+     * compaction behavior matches.
+     */
+    private summarizeInChunks;
+    /**
+     * Best-effort `destroyThread`: swallows the error so `compactThread`'s outer
+     * flow isn't aborted by a teardown blip, but logs it at `warn` so a future
+     * `destroyThread` regression stays observable. Used on both the empty-source
+     * and non-empty compaction paths.
+     */
+    private destroyThreadBestEffort;
+    /**
+     * Construct the agent's enabled MCP servers and kick off background discovery
+     * for each. Synchronous: it inserts every server entry (status `Connecting`)
+     * then assigns its background discovery promise to `entry.ready`, so
+     * `createAgent` / `updateAgent` never block on `connect()` / `listTools()`.
+     * A no-op when the config declares no enabled servers.
+     */
+    private startMcpServers;
+    /**
+     * Connect + list tools for one MCP server, recording the outcome on
+     * per-server state and emitting the discovery telemetry triple
+     * (`started` → `completed` | `failed`) plus the terminal `status-changed`.
+     * Guards against an orphaned write by re-checking the server instance
+     * identity after each await — a superseded cycle replaces the entry with a
+     * fresh instance, so a stale discovery must neither clobber state nor emit
+     * (every terminal emit sits behind the `isCurrent()` guard). Discovery
+     * failure is recorded on state (status `Error`, sanitized message +
+     * structured detail) and never rethrown — matching the "failed server ≠
+     * failed create/reconnect" contract; an aborted run records the state but
+     * emits no `failed` telemetry.
+     */
+    private runMcpDiscovery;
+    /**
+     * Emit an MCP telemetry event, swallowing only the typed `DISPOSED` error a
+     * post-`shutdown()` background discovery callback would hit (the bus is gone).
+     * Any other emit failure rethrows so a real regression surfaces. Every MCP
+     * emit is background / racing shutdown, so all route through here.
+     */
+    private emitMcpTelemetry;
+    /**
+     * Flip a server's status synchronously and return a closure that emits the
+     * matching `mcp-server-status-changed` telemetry — or `undefined` when the
+     * status is unchanged (same-status transitions are deduped here so callers
+     * don't have to). Splitting the flip from the emit lets callers order the
+     * emit AFTER the discovery-terminal event (#373), while a synchronous reader
+     * of `getMcpServerInfo()` already sees the post-flip status.
+     */
+    private prepareMcpStatusChange;
+    /**
+     * Diff the next MCP config against the applied one and preserve / cycle / add
+     * / remove servers accordingly. `mcpServerConfigEqual` (SDK-exported, uniform
+     * across harnesses) is the preserve predicate: an equal server is left
+     * completely untouched (its live instance + warm tool-list cache survive — no
+     * `close`, no `tools/list`, the #541 checkpoint). A changed / removed server
+     * is closed and dropped; a changed / added enabled server is constructed
+     * fresh and discovered in the background.
+     */
+    private diffMcpServers;
+    /** Close every MCP server on an agent, awaiting in-flight discovery first. */
+    private closeMcpServers;
+    /** Rebuild the catalog entries for one server from its freshly-discovered tools. */
+    private refreshCatalogForServer;
+    /** Drop every catalog entry that points at `serverName`. */
+    private removeCatalogForServer;
+    /**
+     * Decide whether the tool-approval gate engages this turn and, if so, return
+     * the per-tool policy decider the coordinator consults. `undefined` ⇒ gate
+     * inactive; the coordinator suspends nothing and tools run free (the SDK's
+     * "no policy ⇒ no gating" back-compat invariant), avoiding a suspend/resume
+     * round-trip per call.
+     *
+     * Gating is **opt-in**: it engages only when the consumer set
+     * `config.toolPolicies` (non-empty) or `config.defaultToolDecision`. Whether
+     * the gate engaged is frozen at stream start (the closure is built iff gating
+     * is active now), but the closure itself reads `state.config` **live on every
+     * call** rather than a snapshot — a mid-turn `updateAgentConfig` (notably the
+     * `source: 'remember'` rule an "Allow always" click appends) reassigns
+     * `state.config` in place on this same `state` without disposing the in-flight
+     * coordinator, so a snapshot would leave approvals 2..N in that turn
+     * re-prompting even though the rule is persisted (#638). Reading live makes
+     * the remembered decision auto-resolve subsequent matching calls.
+     * `OPENAI_BUILT_IN_TOOL_POLICIES` is the `tiers.harness` slice (empty today).
+     */
+    private buildPolicyGate;
+    private getAgentOrThrow;
+}