@morsehq-dev/sdk 0.4.0-rc.1

package/dist/anthropic-agent-sdk/index.d.ts

@@ -0,0 +1,371 @@
+import { AnthropicMessageCreateParams } from '../anthropic/index.js';
+import '../spans-DZtMuBvc.js';
+
+/**
+ * Structural types for `@anthropic-ai/claude-agent-sdk` integration.
+ *
+ * We deliberately decline to import the real types so the SDK works even
+ * when `@anthropic-ai/claude-agent-sdk` isn't installed. Each interface
+ * captures the minimum surface our wrappers need to observe.
+ *
+ * Mirrors the pattern in `src/anthropic/index.ts` (low-level Messages
+ * API adapter) and `src/openai-agents/types.ts` / `src/langgraph/types.ts`.
+ */
+
+/**
+ * One SDK event yielded from `ClaudeSDKClient.query()`. The real SDK emits
+ * an `SDKMessage` discriminated union; we keep the structural shape minimal.
+ */
+interface SDKMessageLike {
+    type: string;
+    message?: {
+        id?: string;
+        model?: string;
+        usage?: {
+            input_tokens?: number;
+            output_tokens?: number;
+            cache_creation_input_tokens?: number;
+            cache_read_input_tokens?: number;
+            [k: string]: unknown;
+        };
+        content?: Array<{
+            type: string;
+            [k: string]: unknown;
+        }>;
+        [k: string]: unknown;
+    };
+    tool_use_id?: string;
+    name?: string;
+    input?: unknown;
+    content?: unknown;
+    is_error?: boolean;
+    hook?: {
+        name: string;
+        kind: "pre_tool" | "post_tool" | "on_error";
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+interface ClaudeSDKQueryOptions {
+    systemPrompt?: string;
+    maxTurns?: number;
+    model?: string;
+    [k: string]: unknown;
+}
+/**
+ * Structural shape of `ClaudeSDKClient`. We only require `query()` returning
+ * an async iterable of `SDKMessageLike`. Hook registration is optional and
+ * accessed via `client.on(...)` if present.
+ */
+interface ClaudeSDKClientLike {
+    query(prompt: string | AnthropicMessageCreateParams, options?: ClaudeSDKQueryOptions): AsyncIterable<SDKMessageLike> | Promise<AsyncIterable<SDKMessageLike>>;
+    on?(event: string, handler: (payload: unknown) => void): void;
+    off?(event: string, handler: (payload: unknown) => void): void;
+}
+/**
+ * Subset of the SDK module shape we probe when patching via
+ * `instrumentClaudeAgentSDK({ claudeAgentSdkModule })`. Best-effort.
+ */
+interface ClaudeAgentSDKModuleLike {
+    ClaudeSDKClient?: {
+        prototype: {
+            query: unknown;
+            [k: string]: unknown;
+        };
+    };
+    query?: (...args: unknown[]) => unknown;
+    default?: unknown;
+    [k: string]: unknown;
+}
+
+/**
+ * `@morsehq-dev/sdk/anthropic-agent-sdk` — Claude Agent SDK client wrapper.
+ *
+ * This module implements ONLY the outer-span (agent) instrumentation around
+ * `ClaudeSDKClient.query()`. Sibling files (`llm-instrumentation.ts`,
+ * `tool-and-subagent.ts`, `hook-instrumentation.ts`) layer the inner llm /
+ * tool / hook spans; Wave 3-A composes them via `src/anthropic-agent-sdk/index.ts`.
+ *
+ * Two entry points (mirroring `src/anthropic/index.ts`):
+ *
+ *   - `wrapClaudeAgentSDK(client)` — returns a Proxy-of-Proxy that
+ *     intercepts `query()` and opens an outer `agent` span around the async
+ *     iteration. The rest of the client surface (`on`, `off`, anything
+ *     else) is forwarded unchanged.
+ *
+ *   - `instrumentClaudeAgentSDK(clientOrOptions, options?)` — two-mode
+ *     installer. With a client, equivalent to `wrapClaudeAgentSDK`. With
+ *     `{ claudeAgentSdkModule }`, best-effort patches
+ *     `ClaudeSDKClient.prototype.query`. Always returns the wrapped client
+ *     or a boolean; never throws.
+ *
+ * All telemetry paths are wrapped in `absorbErrors*` — a tracing failure
+ * MUST NEVER break the customer's `query()`.
+ */
+
+interface WrapClaudeAgentSDKOptions {
+    /** Override the agent name on the outer span. Default: `"claude-agent-sdk"`. */
+    defaultAgentName?: string;
+    /** Override the model name passed to the outer span metadata. Default: inferred. */
+    defaultModel?: string;
+}
+/**
+ * Wrap a `ClaudeSDKClient` so each `query()` call opens an outer `agent`
+ * span (via `emitAgentSpan` from `_agent-sdk-common`). The rest of the
+ * client's surface is forwarded unchanged via a Proxy. Idempotent.
+ *
+ * THIS WRAPPER ONLY HANDLES THE OUTER AGENT SPAN. llm / tool / hook spans
+ * are layered by sibling files in the same directory and composed via
+ * `src/anthropic-agent-sdk/index.ts` in Wave 3.
+ */
+declare function wrapClaudeAgentSDK<C extends ClaudeSDKClientLike>(client: C, options?: WrapClaudeAgentSDKOptions): C;
+/**
+ * Top-level installer. Two modes:
+ *
+ *   - `instrumentClaudeAgentSDK(client)` — equivalent to `wrapClaudeAgentSDK(client)`.
+ *   - `instrumentClaudeAgentSDK({ claudeAgentSdkModule: mod })` — best-effort
+ *     prototype patch on `ClaudeSDKClient.prototype.query`. Prefer the
+ *     wrap form when possible.
+ *
+ * Always returns the wrapped client, `true`/`false` for the module path, or
+ * `undefined` on absorbed error. Never throws.
+ */
+type InstrumentClientArg = ClaudeSDKClientLike | (WrapClaudeAgentSDKOptions & {
+    claudeAgentSdkModule?: unknown;
+}) | undefined;
+declare const instrumentClaudeAgentSDK: (clientOrOptions?: InstrumentClientArg, maybeOptions?: WrapClaudeAgentSDKOptions) => Promise<unknown | undefined>;
+/**
+ * Restore the prototype patch and clear the install sentinel. Pass the
+ * same module reference given to `instrumentClaudeAgentSDK`, or omit and
+ * the function will best-effort do nothing (no-op). Calling on a wrapped
+ * client (vs. a module) is a no-op — just discard the wrapped client.
+ */
+declare const uninstallClaudeAgentSDK: (claudeAgentSdkModule?: unknown) => void | undefined;
+/** True when a wrapped Claude Agent SDK client is passed in. */
+declare function isClaudeAgentSDKWrapped(client: unknown): boolean;
+
+/**
+ * `anthropic-agent-sdk/hook-instrumentation.ts` — W2-A.4
+ *
+ * Subscribes to `ClaudeSDKClient`'s `"hook"` event channel and emits one
+ * `hook`-shaped span (wire `type=tool` + `metadata.tool_kind="hook"`) per
+ * fired hook. Hooks logically bracket a tool invocation (`pre_tool` /
+ * `post_tool`) or react to a failure (`on_error`); we therefore emit them
+ * as SIBLINGS of the wrapped tool span (sharing the tool's parent), not
+ * nested under it.
+ *
+ * When the caller provides a `toolSpanLookup` (typically wired in by the
+ * tool-and-subagent W2-A.3 integration), we use `emitAsToolSibling` so
+ * the hook attaches to the tool's parent. When no lookup is provided —
+ * or the lookup returns null for an unknown tool_use_id — we fall back
+ * to `emitHookSpan` which attaches to whatever parent is on top of the
+ * active span stack.
+ *
+ * Hooks are synchronous from our perspective: we emit and immediately
+ * close the span. When the hook payload reports `duration_ms`, it lands
+ * in `metadata.hook.duration_ms` (the span's own `duration_ms` reflects
+ * our emit/close roundtrip, which is effectively zero).
+ *
+ * Every emission is wrapped in `absorbErrorsSync` per the foundational
+ * "telemetry must never break the host" guarantee.
+ */
+
+interface InstallHookInstrumentationOptions {
+    /**
+     * Map of toolUseId → spanId for the currently-open tool spans.
+     * Provided by W2-A.3 (tool-and-subagent.ts) when the integration layer
+     * composes both. When omitted, hook spans are emitted without sibling
+     * linkage (they attach to whatever parent is on top of the stack).
+     */
+    toolSpanLookup?: (toolUseId: string) => string | null;
+}
+interface HookEventLike {
+    /** Hook name (user-defined identifier from their hook registration). */
+    name: string;
+    /** Hook kind. */
+    kind: "pre_tool" | "post_tool" | "on_error";
+    /** When known, the tool_use_id this hook wraps (for sibling linkage). */
+    tool_use_id?: string;
+    /** Duration in ms reported by the hook callback, if available. */
+    duration_ms?: number;
+}
+/**
+ * Subscribe to the client's `"hook"` event channel and emit one hook
+ * span per fired hook. Returns an unsubscribe function.
+ *
+ * If `client.on` is not a function (the user didn't wire hooks at all),
+ * returns a no-op unsubscriber.
+ */
+declare function installHookInstrumentation(client: ClaudeSDKClientLike, options?: InstallHookInstrumentationOptions): () => void;
+
+/**
+ * `anthropic-agent-sdk/llm-instrumentation.ts` — taps `message_start` /
+ * `message_stop` event pairs in a Claude Agent SDK stream and emits one
+ * `llm` span per pair.
+ *
+ * The wrapper is a passthrough generator: every event is yielded to the
+ * downstream caller unchanged. Span emission is a side-effect.
+ *
+ * One agent run can contain MULTIPLE llm calls (the agent loops on
+ * tool-use → tool-result), so we emit one span PER message_start /
+ * message_stop pair, not one for the whole stream.
+ *
+ * `context_segments` are extracted via `extractAnthropicSegments` from the
+ * low-level Anthropic adapter (`../anthropic`) when the caller provides the
+ * original request params. We DO NOT duplicate that logic here.
+ *
+ * Sibling W2-A files in this directory handle agent / tool / subagent /
+ * hook spans separately.
+ */
+
+interface InstrumentLlmCallsOptions {
+    /** Override the model name when the SDK doesn't report one on `message_start`. */
+    fallbackModel?: string;
+    /**
+     * Original request params (the prompt + messages + tools the user passed
+     * to `query()`). When provided, allows `extractAnthropicSegments` to
+     * build `context_segments`. When omitted, `context_segments` is left
+     * unset on the emitted span.
+     */
+    requestParams?: AnthropicMessageCreateParams;
+}
+/**
+ * Wrap an async iterable of `SDKMessageLike` events: pass each event through
+ * unchanged, but tap `message_start` / `message_stop` pairs and emit one
+ * `llm` span per pair.
+ *
+ * Behaviour:
+ *
+ *   - The span opens at `message_start` (model is read from `event.message.model`
+ *     or falls back to `options.fallbackModel`).
+ *   - Token usage is read from `event.message.usage` on `message_stop` —
+ *     the start-event usage is only partial. `input_tokens` sums
+ *     `input_tokens + cache_creation_input_tokens + cache_read_input_tokens`.
+ *   - If `requestParams` is provided, `context_segments` is populated via
+ *     `extractAnthropicSegments(requestParams, response)`.
+ *   - Orphan `message_stop` events (with no preceding start) are tolerated:
+ *     no span, no error.
+ *   - If the iterator ends with an open span (a start without a matching
+ *     stop), the span is closed as failed.
+ *   - All telemetry is wrapped in try/catch — it MUST NOT break iteration.
+ */
+declare function instrumentLlmCalls(events: AsyncIterable<SDKMessageLike>, options?: InstrumentLlmCallsOptions): AsyncIterable<SDKMessageLike>;
+
+/**
+ * `anthropic-agent-sdk/tool-and-subagent.ts` — instrument the `tool_use` /
+ * `tool_result` event pairs emitted by `@anthropic-ai/claude-agent-sdk`'s
+ * `ClaudeSDKClient.query()`.
+ *
+ * Phase 13 W2-A.3. The Anthropic Agent SDK streams a discriminated union
+ * of `SDKMessage` events; this module wraps such a stream as a tap that
+ * (a) passes every event through unchanged and (b) emits matching
+ * Morse spans for tool invocations:
+ *
+ *   - `tool_use` with `name !== "Task"` → `type=tool` span (held open
+ *     until the matching `tool_result` arrives, indexed by
+ *     `tool_use_id`).
+ *   - `tool_use` with `name === "Task"` → `type=agent` span carrying
+ *     `metadata.spawn_kind="subagent"` (the canonical subagent.spawn
+ *     pattern from `_agent-sdk-common/span-emitter.ts`). The span is also
+ *     held open until the matching `tool_result`.
+ *   - `tool_result` → look up the open span by `tool_use_id`, stamp the
+ *     output summary + success flag, close with the appropriate status.
+ *
+ * **Task-tool fan-out parent pinning.** When the agent loop spawns more
+ * than one subagent in the same turn it emits N Task `tool_use` blocks
+ * sequentially before any matching `tool_result`. The default
+ * top-of-stack parent lookup in `startSpan` would (incorrectly) make
+ * later subagent spans children of the earlier siblings. We snapshot
+ * the current top-of-stack at the first Task `tool_use` via
+ * `captureParentForFanOut` and route every subagent span through
+ * `emitWithPinnedParent` so they all share the same parent. The
+ * snapshot is cleared once all open Task spans close (or the iterator
+ * ends).
+ *
+ * **Error containment.** All emission is wrapped — telemetry MUST NOT
+ * break iteration. If an internal helper throws, the event still flows
+ * through to the caller and the offending span is best-effort skipped.
+ *
+ * **Orphan tolerance.** `tool_result` without a matching `tool_use` is
+ * silently ignored. `tool_use` without a matching `tool_result` is
+ * closed as failed when the iterator ends.
+ */
+
+interface InstrumentToolsOptions {
+    /** Override input byte cap passed to `summarizeToolInput`. */
+    toolInputMaxBytes?: number;
+    /** Override output byte cap passed to `summarizeToolOutput`. */
+    toolOutputMaxBytes?: number;
+}
+/**
+ * Wrap an async iterable of `SDKMessageLike` events: yield every event
+ * unchanged but tap `tool_use` / `tool_result` pairs and emit matching
+ * `tool` and `subagent` spans against the active Morse trace.
+ *
+ * No-op outside an active trace (the emitter helpers return `null`).
+ * Iterator order and timing are preserved; emission errors are
+ * absorbed.
+ */
+declare function instrumentTools(events: AsyncIterable<SDKMessageLike>, options?: InstrumentToolsOptions): AsyncIterable<SDKMessageLike>;
+
+/**
+ * `@morsehq-dev/sdk/anthropic-agent-sdk` — public surface for the
+ * `@anthropic-ai/claude-agent-sdk` adapter.
+ *
+ * Composes the four W2-A surfaces:
+ *
+ *   - `client-wrapper.ts` opens the outer `agent` span around `query()`.
+ *   - `llm-instrumentation.ts` taps `message_start` / `message_stop` pairs
+ *     and emits `llm` spans.
+ *   - `tool-and-subagent.ts` taps `tool_use` / `tool_result` pairs and
+ *     emits `tool` spans (regular tools) or `agent` spans with
+ *     `metadata.spawn_kind="subagent"` (Task fan-out).
+ *   - `hook-instrumentation.ts` subscribes to the client's `"hook"` event
+ *     channel and emits one `tool`-typed `tool_kind="hook"` span per hook.
+ *
+ * The convenience composer `wrapClaudeAgentSDKWithFullInstrumentation`
+ * stacks them in the correct order: outer `wrapClaudeAgentSDK` opens the
+ * agent span; inner generators (`instrumentLlmCalls`, `instrumentTools`)
+ * are chained around the underlying query iterator so events flow once
+ * through both taps before reaching the caller. Hook subscription is
+ * event-based (decoupled).
+ *
+ * See `openspec/changes/2026-05-26-phase-13-ts-agent-sdk-adapters/`.
+ */
+
+interface FullInstrumentationOptions extends WrapClaudeAgentSDKOptions, InstrumentLlmCallsOptions, InstrumentToolsOptions, InstallHookInstrumentationOptions {
+}
+interface FullInstrumentationResult<C extends ClaudeSDKClientLike> {
+    /** The Proxy-wrapped client. Drop-in replacement for the original. */
+    client: C;
+    /**
+     * Tear-down. Currently disconnects the hook listener. The outer-span
+     * Proxy and generator wrapping are inert when not invoked, so there's
+     * no other cleanup required — subsequent `query()` calls on the
+     * returned client will still emit telemetry until callers drop the
+     * reference.
+     */
+    dispose: () => void;
+}
+/**
+ * Compose all four W2-A instrumentation layers on a single
+ * `ClaudeSDKClient`. Returns the wrapped client plus a `dispose()` that
+ * removes the hook listener.
+ *
+ * Idempotent: re-wrapping a previously full-wrapped client returns the
+ * original result (same `client` reference, same `dispose`).
+ *
+ * Composition order (outer → inner):
+ *
+ *   1. `wrapClaudeAgentSDK` — opens the outer `agent` span around the
+ *      whole iteration and ensures a trace is active.
+ *   2. `instrumentLlmCalls` — taps `message_start` / `message_stop`
+ *      pairs.
+ *   3. `instrumentTools` — taps `tool_use` / `tool_result` pairs.
+ *   4. The underlying `client.query()` iterator.
+ *
+ * `installHookInstrumentation` runs in parallel via the event channel.
+ */
+declare function wrapClaudeAgentSDKWithFullInstrumentation<C extends ClaudeSDKClientLike>(client: C, options?: FullInstrumentationOptions): FullInstrumentationResult<C>;
+
+export { type ClaudeAgentSDKModuleLike, type ClaudeSDKClientLike, type ClaudeSDKQueryOptions, type FullInstrumentationOptions, type FullInstrumentationResult, type HookEventLike, type InstallHookInstrumentationOptions, type InstrumentLlmCallsOptions, type InstrumentToolsOptions, type SDKMessageLike, type WrapClaudeAgentSDKOptions, installHookInstrumentation, instrumentClaudeAgentSDK, instrumentLlmCalls, instrumentTools, isClaudeAgentSDKWrapped, uninstallClaudeAgentSDK, wrapClaudeAgentSDK, wrapClaudeAgentSDKWithFullInstrumentation };