@morsehq-dev/sdk 0.4.0-rc.1

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

@@ -0,0 +1,502 @@
+/**
+ * Structural types for `@openai/agents` (OpenAI Agents SDK for TypeScript).
+ *
+ * No hard import — `@openai/agents` is an optional peer. Each interface
+ * captures the minimum surface our `wrapRunner` and event listeners need.
+ */
+/** Event payload emitted by `Runner` during `run()`. */
+interface RunnerEventLike {
+    type: "agent_start" | "agent_end" | "llm_call_start" | "llm_call_end" | "tool_call_start" | "tool_call_end" | "handoff" | "guardrail_check" | string;
+    agent?: {
+        name?: string;
+        model?: string;
+        [k: string]: unknown;
+    };
+    llm?: {
+        model?: string;
+        provider?: string;
+        usage?: {
+            input_tokens?: number;
+            output_tokens?: number;
+            total_tokens?: number;
+            [k: string]: unknown;
+        };
+        /**
+         * OpenAI-chat-completions-shaped request messages, when the host
+         * `Runner` surfaces them on the `llm_call_start` event (MHQ-750). Used
+         * to populate `context_segments` via the shared
+         * `_agent-sdk-common/context-decomposer`. Optional — hosts that don't
+         * surface this (or an older `@openai/agents` version) simply produce
+         * no context_segments, same as today.
+         */
+        messages?: unknown;
+        /** Tool definitions bound to this LLM call, OpenAI `tools` shape. */
+        tools?: unknown;
+        [k: string]: unknown;
+    };
+    tool?: {
+        name?: string;
+        input?: unknown;
+        output?: unknown;
+        duration_ms?: number;
+        success?: boolean;
+        [k: string]: unknown;
+    };
+    handoff?: {
+        from_agent?: string;
+        to_agent?: string;
+        reason?: string;
+        [k: string]: unknown;
+    };
+    guardrail?: {
+        name?: string;
+        passed?: boolean;
+        reason?: string;
+        [k: string]: unknown;
+    };
+    error?: unknown;
+    [k: string]: unknown;
+}
+/** Structural shape of an OpenAI Agents `Agent`. */
+interface AgentLike {
+    name?: string;
+    model?: string | {
+        id?: string;
+        [k: string]: unknown;
+    };
+    instructions?: string | (() => string);
+    tools?: Array<{
+        name?: string;
+        [k: string]: unknown;
+    }>;
+    [k: string]: unknown;
+}
+/** Structural shape of a `RunResult`. */
+interface RunResultLike {
+    finalOutput?: unknown;
+    newItems?: Array<{
+        type?: string;
+        [k: string]: unknown;
+    }>;
+    usage?: {
+        input_tokens?: number;
+        output_tokens?: number;
+        total_tokens?: number;
+        [k: string]: unknown;
+    };
+    /**
+     * MHQ-787: one entry per model round trip, in call order. The real SDK's
+     * default (Responses API) tracing spans carry a `response_id` but no
+     * `model`/`usage` of their own (see `trace-processor.ts`'s file doc) —
+     * this is where that data actually lives, keyed back to a span via
+     * `responseId` matching the span's `spanData.response_id`.
+     */
+    rawResponses?: Array<{
+        responseId?: string;
+        usage?: {
+            inputTokens?: number;
+            outputTokens?: number;
+            totalTokens?: number;
+            [k: string]: unknown;
+        };
+        [k: string]: unknown;
+    }>;
+    [k: string]: unknown;
+}
+/** Structural shape of `Runner`. */
+interface RunnerLike {
+    run(agent: AgentLike, input: unknown, options?: Record<string, unknown>): Promise<RunResultLike>;
+    on?(event: string, handler: (payload: RunnerEventLike) => void): void;
+    off?(event: string, handler: (payload: RunnerEventLike) => void): void;
+}
+/** Module-shape probe for `instrumentOpenAIAgents({ openaiAgentsModule })`. */
+interface OpenAIAgentsModuleLike {
+    Runner?: {
+        prototype: {
+            run: unknown;
+            [k: string]: unknown;
+        };
+    };
+    run?: (...args: unknown[]) => unknown;
+    default?: unknown;
+    [k: string]: unknown;
+}
+
+/**
+ * `@morsehq-dev/sdk/openai-agents` — OpenAI Agents SDK runner wrapper.
+ *
+ * This module implements ONLY the outer-span (agent) instrumentation around
+ * `Runner.run()`. Sibling files (`llm-and-tool.ts`, `handoff.ts`,
+ * `guardrail.ts`) layer the inner llm / tool / handoff / guardrail spans;
+ * Wave 3-O composes them via `src/openai-agents/index.ts`.
+ *
+ * Two entry points (mirroring `src/anthropic-agent-sdk/client-wrapper.ts`):
+ *
+ *   - `wrapRunner(runner)` — returns a Proxy that intercepts `run()` and
+ *     opens an outer `agent` span around the returned Promise. The rest of
+ *     the runner surface (`on`, `off`, anything else) is forwarded.
+ *
+ *   - `instrumentOpenAIAgents(runnerOrOptions, options?)` — two-mode
+ *     installer. With a runner, equivalent to `wrapRunner`. With
+ *     `{ openaiAgentsModule }`, best-effort patches
+ *     `Runner.prototype.run`. Always returns the wrapped runner or a
+ *     boolean; never throws.
+ *
+ * All telemetry paths are wrapped in `absorbErrors*` — a tracing failure
+ * MUST NEVER break the customer's `run()`.
+ */
+
+interface WrapRunnerOptions {
+    /** Override the agent name on the outer span when `agent.name` is absent. */
+    defaultAgentName?: string;
+    /**
+     * MHQ-787: called with the resolved `RunResult` and the agent's
+     * configured model after each `run()` succeeds, so callers can enrich
+     * already-closed LLM spans with usage/model data that only becomes
+     * available on the result (not on the SDK's own tracing spans). Never
+     * called on a failed run. Errors from this callback are swallowed —
+     * telemetry must never break the customer's `run()`.
+     */
+    onRunResult?: (result: RunResultLike, model: string | undefined) => void;
+}
+/**
+ * Wrap a `Runner` so each `run()` call opens an outer `agent` span (via
+ * `emitAgentSpan` from `_agent-sdk-common`). The Proxy forwards the rest
+ * of the runner surface (event subscription via `on`/`off`, etc.) so
+ * customers see no behavior change. Idempotent.
+ *
+ * THIS WRAPPER ONLY HANDLES THE OUTER AGENT SPAN. llm / tool / handoff /
+ * guardrail spans are layered by sibling files (W2-O.2/.3/.4) and composed
+ * via `src/openai-agents/index.ts` in Wave 3-O.
+ */
+declare function wrapRunner<R extends RunnerLike>(runner: R, options?: WrapRunnerOptions): R;
+interface InstrumentOpenAIAgentsOptions extends WrapRunnerOptions {
+    openaiAgentsModule?: unknown;
+}
+type InstrumentRunnerArg = RunnerLike | InstrumentOpenAIAgentsOptions | undefined;
+/**
+ * Top-level installer. Two modes:
+ *
+ *   - `instrumentOpenAIAgents(runner)` — equivalent to `wrapRunner(runner)`.
+ *   - `instrumentOpenAIAgents({ openaiAgentsModule: mod })` — best-effort
+ *     prototype patch on `Runner.prototype.run`. Prefer the wrap form when
+ *     possible.
+ *
+ * Always returns the wrapped runner, `true`/`false` for the module path, or
+ * `undefined` on absorbed error. Never throws.
+ */
+declare const instrumentOpenAIAgents: (runnerOrOptions?: InstrumentRunnerArg, maybeOptions?: WrapRunnerOptions) => Promise<unknown>;
+/**
+ * Restore the prototype patch and clear the install sentinel. Pass the same
+ * module reference given to `instrumentOpenAIAgents`. No-op when called with
+ * no module or on a wrapped-runner (vs. module) install — just discard the
+ * wrapper.
+ */
+declare const uninstallOpenAIAgents: (openaiAgentsModule?: unknown) => void;
+/** True when a wrapped OpenAI Agents `Runner` is passed in. */
+declare function isOpenAIAgentsWrapped(runner: unknown): boolean;
+
+/**
+ * `openai-agents/llm-and-tool.ts` — Phase 13 W2-O.2.
+ *
+ * Subscribes to the OpenAI Agents `Runner`'s event channel and emits `llm`
+ * and `tool` spans for each `*_call_start` / `*_call_end` pair.
+ *
+ * The real `@openai/agents` Runner fires events on both typed channels
+ * (e.g. `runner.on("llm_call_start", ...)`) and a catch-all `"event"`
+ * channel. We register on the typed channels only — the FakeRunner used
+ * in tests mirrors that behaviour, and using typed-only avoids the
+ * double-emit risk if a host has wired both.
+ *
+ * Call matching is FIFO via two per-installation stacks (one for llm,
+ * one for tool). Within a single `Runner.run` the SDK does not interleave
+ * calls, so FIFO is sufficient — and it tolerates orphan `_end` events
+ * (no matching `_start`) by simply ignoring them.
+ *
+ * All span emission goes through the shared `_agent-sdk-common/span-emitter`
+ * helpers which are themselves wrapped in `absorbErrorsSync` — telemetry
+ * MUST NOT throw at the caller.
+ *
+ * MHQ-750: when the `llm_call_start` event carries `event.llm.messages`
+ * (OpenAI-chat-completions-shaped, since `@openai/agents` is built on the
+ * same request format), they're decomposed into `context_segments` via the
+ * shared `_agent-sdk-common/context-decomposer` — the same decomposer used
+ * by `../langgraph/` and `../langchain/`. `event.llm.messages` is optional
+ * on the structural `RunnerEventLike` type; hosts that don't surface it
+ * simply produce no `context_segments`, same as before this change.
+ */
+
+interface InstallLlmAndToolInstrumentationOptions {
+    /** Max bytes for serialized tool input summary. Defaults to redaction helper's cap. */
+    toolInputMaxBytes?: number;
+    /** Max bytes for serialized tool output summary. Defaults to redaction helper's cap. */
+    toolOutputMaxBytes?: number;
+}
+/**
+ * Subscribe to the runner's event channel and emit `llm` and `tool` spans
+ * for each `_call_start`/`_call_end` pair.
+ *
+ * Returns an unsubscribe function. If `runner.on` is not a function (e.g.
+ * the host injected a mock), returns a no-op unsubscriber.
+ */
+declare function installLlmAndToolInstrumentation(runner: RunnerLike, options?: InstallLlmAndToolInstrumentationOptions): () => void;
+
+/**
+ * `openai-agents/handoff.ts` — OpenAI Agents SDK handoff-span instrumentation.
+ *
+ * Subscribes to the Runner's "handoff" event channel and emits a
+ * `subagent.spawn`-shape span per handoff:
+ *
+ *   - wire `type = "agent"`
+ *   - `metadata.spawn_kind = "subagent"`
+ *   - `metadata.parent_agent_name = handoff.from_agent`
+ *   - `metadata.subagent_name     = handoff.to_agent`
+ *   - `metadata.handoff_from      = handoff.from_agent` (alias for UI clarity)
+ *   - `metadata.task_description  = handoff.reason` (via emitSubagentSpan)
+ *   - `metadata.handoff_reason    = handoff.reason` (when present)
+ *
+ * The handoff event in the OpenAI Agents SDK is instantaneous — the to_agent's
+ * subsequent work is captured by separate llm/tool spans (W2-O.2). The span
+ * opened here is therefore closed immediately (duration_ms = 0).
+ *
+ * Errors emitted from inside the listener never propagate back to the runner —
+ * `absorbErrorsSync` swallows them and `emitSubagentSpan` itself is wrapped.
+ */
+
+/**
+ * Subscribe to a Runner's "handoff" events and emit a `subagent.spawn`-shape
+ * span for each. Returns an unsubscribe function. Safely no-ops when
+ * `runner.on` is missing (e.g., a wrapped Runner without an event channel).
+ */
+declare function installHandoffInstrumentation(runner: RunnerLike): () => void;
+
+/**
+ * `openai-agents/guardrail.ts` — W2-O.4
+ *
+ * Subscribes to the `Runner`'s `"guardrail_check"` event channel and emits
+ * one guardrail-shaped span per check. Guardrails are wire-`tool` spans
+ * tagged with `metadata.tool_kind="guardrail"` so the dashboard can render
+ * them distinctly from regular tool calls and hook spans.
+ *
+ * Spans close immediately on emission. When the guardrail reports
+ * `passed === false`, the span closes with `failed` status and the
+ * reason (when present) lands in both the synthetic error message and
+ * `metadata.guardrail.reason`.
+ *
+ * Every emission is wrapped in `absorbErrorsSync` per the foundational
+ * "telemetry must never break the host" guarantee.
+ */
+
+/**
+ * Subscribe to the runner's `"guardrail_check"` events. Emit one
+ * tool-shape span per check:
+ *
+ *   - wire `type = "tool"`
+ *   - `metadata.tool_kind = "guardrail"`
+ *   - `metadata.guardrail.passed: boolean`
+ *   - `metadata.guardrail.name: string` (when present)
+ *   - `metadata.guardrail.reason: string` (when present, typically on fail)
+ *
+ * On failure, the span closes with `failed` status. Returns an
+ * unsubscribe function. No-op when `runner.on` is missing.
+ */
+declare function installGuardrailInstrumentation(runner: RunnerLike): () => void;
+
+/**
+ * `openai-agents/trace-processor.ts` — translate `@openai/agents` SDK spans
+ * into Morse spans via the SDK's first-class TraceProcessor pipeline.
+ *
+ * The SDK exposes `addTraceProcessor(p)` / `setTraceProcessors([p])` where
+ * `p` implements:
+ *
+ *   - `onTraceStart(trace)`
+ *   - `onTraceEnd(trace)`
+ *   - `onSpanStart(span)`
+ *   - `onSpanEnd(span)`
+ *   - `shutdown()`
+ *   - `forceFlush()`
+ *
+ * Each `span` carries `span.spanId` + `span.spanData.{type,name,model,usage,...}`.
+ * Span types observed in the SDK: `agent`, `response`, `generation`,
+ * `function`, `handoff`, `guardrail`, `mcp_list_tools`, `custom`.
+ *
+ * **Why this exists.** The original W2-O surfaces in this directory
+ * (llm-and-tool.ts, handoff.ts, guardrail.ts) listened to a hypothetical
+ * `runner.on('llm_call_start', ...)` event channel that the real SDK
+ * doesn't expose. Phase 13 Option A dogfood (commit 9e53731) confirmed
+ * the old installers never fired. This TraceProcessor is the canonical
+ * replacement — see `openspec/changes/2026-05-26-phase-13-ts-agent-sdk-adapters/`.
+ *
+ * **Telemetry containment.** Every processor method is wrapped — a
+ * translation failure must never bubble back into the customer's
+ * Runner.run().
+ */
+/**
+ * Structural shape of a span passed to the processor. We avoid importing
+ * the real SDK types so this file builds without `@openai/agents` installed.
+ */
+interface OpenAISpanLike {
+    spanId?: string;
+    parentId?: string;
+    traceId?: string;
+    spanData?: {
+        type?: string;
+        name?: string;
+        model?: string;
+        input?: unknown;
+        output?: unknown;
+        usage?: {
+            input_tokens?: number;
+            output_tokens?: number;
+            total_tokens?: number;
+            prompt_tokens?: number;
+            completion_tokens?: number;
+            [k: string]: unknown;
+        };
+        from_agent?: string;
+        to_agent?: string;
+        passed?: boolean;
+        reason?: string;
+        [k: string]: unknown;
+    };
+    error?: unknown;
+    [k: string]: unknown;
+}
+interface OpenAITraceLike {
+    traceId?: string;
+    name?: string;
+    [k: string]: unknown;
+}
+interface MorseTraceProcessorOptions {
+    toolInputMaxBytes?: number;
+    toolOutputMaxBytes?: number;
+}
+/**
+ * Translate OpenAI Agents SDK spans into Morse spans.
+ *
+ * Pass to the SDK via `addTraceProcessor(new MorseTraceProcessor())`
+ * (or via `wrapRunnerWithFullInstrumentation` which installs it for you).
+ *
+ * The processor is idempotent: registering the same instance twice is
+ * harmless. Multiple instances can coexist (each will translate spans
+ * independently — useful if you need to fan out to several backends).
+ */
+declare class MorseTraceProcessor {
+    private readonly options;
+    private readonly openSpans;
+    /**
+     * MHQ-787: `'response'`-type spans (the SDK's default Responses-API path)
+     * carry a `response_id` but no `model`/`usage` of their own — that data
+     * only becomes available on `Runner.run()`'s resolved result
+     * (`result.rawResponses`), which arrives AFTER `onSpanEnd` already fired.
+     * Keep already-closed response spans around, keyed by `response_id`, so
+     * `enrichFromRunResult()` can patch them in place once the real usage
+     * data is available. Spans stay mutable (their span-tree object isn't
+     * exported until the outer trace closes), so a late patch still lands.
+     */
+    private readonly closedResponseSpans;
+    constructor(options?: MorseTraceProcessorOptions);
+    /**
+     * MHQ-787: called by `wrapRunnerWithFullInstrumentation` after each
+     * `Runner.run()` resolves. Matches `rawResponses[].responseId` back to
+     * the `'response'`-type span it belongs to and fills in the model/usage/
+     * cost fields `onSpanEnd` couldn't populate at the time. `fallbackModel`
+     * is the model configured on the `Agent` (known at call time in
+     * `runner-wrapper.ts`) — used only when the span still has no model.
+     * Never throws; a translation failure must not surface to the caller.
+     */
+    enrichFromRunResult(rawResponses: Array<{
+        responseId?: string;
+        usage?: {
+            inputTokens?: number;
+            outputTokens?: number;
+            totalTokens?: number;
+        };
+    }>, fallbackModel?: string): void;
+    onTraceStart(_trace: OpenAITraceLike): void;
+    onTraceEnd(_trace: OpenAITraceLike): void;
+    onSpanStart(span: OpenAISpanLike): void;
+    onSpanEnd(span: OpenAISpanLike): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+    private openSpanFor;
+    private populateSpanFromData;
+}
+interface AgentsModuleLike {
+    addTraceProcessor?(processor: unknown): void;
+    setTraceProcessors?(processors: unknown[]): void;
+}
+/**
+ * Best-effort installation of an MorseTraceProcessor with the real
+ * `@openai/agents` SDK. Returns true if installation succeeded.
+ *
+ * Loads the module via runtime-eval'd dynamic import so the SDK is a
+ * pure optional peer dep — bundlers won't try to resolve it at build
+ * time when the customer hasn't installed it.
+ *
+ * Idempotent at the registration level: the SDK's `addTraceProcessor`
+ * appends to a list, so calling this twice will install two processors.
+ * Production callers should call once at app bootstrap.
+ */
+declare function installMorseTraceProcessor(options?: MorseTraceProcessorOptions): Promise<{
+    installed: boolean;
+    processor: MorseTraceProcessor | null;
+}>;
+
+/**
+ * `@morsehq-dev/sdk/openai-agents` — adapter for `@openai/agents`.
+ *
+ * Wave 3-O composes the W2-O surfaces (`runner-wrapper`, `llm-and-tool`,
+ * `handoff`, `guardrail`) into a single public entry point.
+ *
+ * Two usage modes:
+ *
+ *   1. **Granular** — import any of the four installers individually and
+ *      compose them yourself (`wrapRunner`, `installLlmAndToolInstrumentation`,
+ *      `installHandoffInstrumentation`, `installGuardrailInstrumentation`).
+ *
+ *   2. **Full convenience** — call `wrapRunnerWithFullInstrumentation(runner)`
+ *      to get an outer-span-wrapped Runner with llm + tool + handoff +
+ *      guardrail event listeners pre-installed, plus a single `dispose()`
+ *      that unsubscribes all three event installers.
+ *
+ * See `openspec/changes/2026-05-26-phase-13-ts-agent-sdk-adapters/`.
+ */
+
+interface FullOpenAIInstrumentationOptions {
+    /** Override the agent name on the outer span when `agent.name` is absent. */
+    defaultAgentName?: string;
+    /** Max bytes for serialized tool input summary. */
+    toolInputMaxBytes?: number;
+    /** Max bytes for serialized tool output summary. */
+    toolOutputMaxBytes?: number;
+}
+/**
+ * Wrap an OpenAI Agents `Runner` with the full instrumentation stack:
+ *
+ *   1. Outer `agent` span via `wrapRunner` (provides the trace context).
+ *   2. SDK-native span translation via `MorseTraceProcessor`
+ *      registered through the SDK's `addTraceProcessor()` pipeline —
+ *      catches `agent` / `response` / `generation` / `function` /
+ *      `handoff` / `guardrail` / `mcp_list_tools` / `custom` spans.
+ *   3. Legacy event-listener installers (`installLlmAndToolInstrumentation`,
+ *      `installHandoffInstrumentation`, `installGuardrailInstrumentation`)
+ *      remain wired as no-ops when the real SDK doesn't expose a
+ *      `runner.on()` channel — they only fire against the mock fixture
+ *      in unit tests. Real-SDK usage flows through the TraceProcessor.
+ *
+ * Returns the wrapped runner and a single `dispose()` that unsubscribes
+ * the legacy event installers. The TraceProcessor stays registered for
+ * the lifetime of the process — the SDK's `addTraceProcessor` API has no
+ * symmetric `removeTraceProcessor` (you'd have to `setTraceProcessors([])`
+ * which would nuke any other processors too).
+ *
+ * Telemetry failures NEVER propagate to the host — every emission path
+ * is wrapped in `absorbErrorsSync` upstream.
+ */
+declare function wrapRunnerWithFullInstrumentation<R extends RunnerLike>(runner: R, options?: FullOpenAIInstrumentationOptions): {
+    runner: R;
+    dispose: () => void;
+};
+
+export { type AgentLike, type AgentsModuleLike, type FullOpenAIInstrumentationOptions, MorseTraceProcessor, type MorseTraceProcessorOptions, type OpenAIAgentsModuleLike, type OpenAISpanLike, type OpenAITraceLike, type RunResultLike, type RunnerEventLike, type RunnerLike, installGuardrailInstrumentation, installHandoffInstrumentation, installLlmAndToolInstrumentation, installMorseTraceProcessor, instrumentOpenAIAgents, isOpenAIAgentsWrapped, uninstallOpenAIAgents, wrapRunner, wrapRunnerWithFullInstrumentation };