@morsehq-dev/sdk 0.4.0-rc.1

package/dist/langgraph/index.d.cts

@@ -0,0 +1,324 @@
+import { S as SpanHandle } from '../tracing-BYAqjT5Q.cjs';
+import '../spans-DZtMuBvc.cjs';
+
+/**
+ * Structural types for `@langchain/langgraph` (langgraphjs) + `@langchain/core`
+ * callback handlers.
+ *
+ * No hard import — both are optional peer deps. We mirror the
+ * `BaseCallbackHandler` method surface our `MorseCallbackHandler`
+ * needs to extend (or duck-type when the base class isn't installed).
+ */
+/** Subset of `Serialized` from `@langchain/core/load/serializable`. */
+interface SerializedLike {
+    id?: string[];
+    name?: string;
+    kwargs?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+/** Subset of `LLMResult` from `@langchain/core/outputs`. */
+interface LLMResultLike {
+    generations?: Array<Array<{
+        text?: string;
+        [k: string]: unknown;
+    }>>;
+    llmOutput?: {
+        tokenUsage?: {
+            promptTokens?: number;
+            completionTokens?: number;
+            totalTokens?: number;
+            [k: string]: unknown;
+        };
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+/** Subset of `BaseMessage` shape passed to `handleChatModelStart`. */
+interface BaseMessageLike {
+    _getType?(): string;
+    content?: string | unknown[];
+    [k: string]: unknown;
+}
+/**
+ * The methods we override on `BaseCallbackHandler`. We list them with
+ * loose signatures because the real base class is conditionally imported.
+ */
+interface CallbackHandlerSurface {
+    handleChainStart?(chain: SerializedLike, inputs: Record<string, unknown>, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runType?: string, runName?: string): void | Promise<void>;
+    handleChainEnd?(outputs: Record<string, unknown>, runId: string, parentRunId?: string, tags?: string[], kwargs?: Record<string, unknown>): void | Promise<void>;
+    handleChainError?(err: unknown, runId: string, parentRunId?: string): void | Promise<void>;
+    handleLLMStart?(llm: SerializedLike, prompts: string[], runId: string, parentRunId?: string, extra?: Record<string, unknown>): void | Promise<void>;
+    handleChatModelStart?(llm: SerializedLike, messages: BaseMessageLike[][], runId: string, parentRunId?: string, extra?: Record<string, unknown>): void | Promise<void>;
+    handleLLMEnd?(output: LLMResultLike, runId: string, parentRunId?: string): void | Promise<void>;
+    handleLLMError?(err: unknown, runId: string, parentRunId?: string): void | Promise<void>;
+    handleLLMNewToken?(token: string, idx: {
+        prompt: number;
+        completion: number;
+    }, runId: string, parentRunId?: string, tags?: string[]): void | Promise<void>;
+    handleToolStart?(tool: SerializedLike, input: string, runId: string, parentRunId?: string): void | Promise<void>;
+    handleToolEnd?(output: string, runId: string, parentRunId?: string): void | Promise<void>;
+    handleToolError?(err: unknown, runId: string, parentRunId?: string): void | Promise<void>;
+}
+/** Module-shape probe for `@langchain/core/callbacks/base`. */
+interface LangChainCoreCallbacksModuleLike {
+    BaseCallbackHandler?: {
+        new (...args: unknown[]): CallbackHandlerSurface & {
+            name: string;
+        };
+        prototype: CallbackHandlerSurface;
+    };
+    [k: string]: unknown;
+}
+
+/**
+ * `@morsehq-dev/sdk/langgraph` — `MorseCallbackHandler` (W2-L.1).
+ *
+ * The handler is registered by LangGraph users via:
+ *
+ * ```ts
+ * import { MorseCallbackHandler } from "@morsehq-dev/sdk/langgraph";
+ * await app.invoke(input, { callbacks: [new MorseCallbackHandler()] });
+ * ```
+ *
+ * LangGraph type-checks handlers structurally (by method presence on the
+ * instance), not via `instanceof BaseCallbackHandler`. We therefore:
+ *
+ *   1. Always export a duck-typed class implementing `CallbackHandlerSurface`
+ *      — works without `@langchain/core` installed.
+ *   2. Provide `getCallbackHandlerClass()` for users who rely on
+ *      `instanceof BaseCallbackHandler` — it dynamically loads
+ *      `@langchain/core/callbacks/base` (optional peer dep) and returns a
+ *      subclass whose prototype chain includes the real base class.
+ *
+ * Scope of THIS file (W2-L.1): chain spans only. `handleChainStart` opens
+ * an `agent` span (the LangGraph chain IS the agent run); `handleChainEnd`
+ * / `handleChainError` closes it. Nested chains nest via the per-runId
+ * span map — LangGraph guarantees well-ordered start/end pairs so the
+ * tracing-state span stack handles `parent_span_id` linkage for us.
+ *
+ * `handleLLMStart/End`, `handleToolStart/End`, and streaming callbacks
+ * are implemented in W2-L.2 / W2-L.3 as separate methods on the same
+ * class (composed in Wave 3-L).
+ */
+
+interface MorseCallbackHandlerOptions {
+    /**
+     * Override the agent name on the outer chain span. Falls back, in order,
+     * to: `runName` (LangGraph-supplied per-invocation name), `chain.name`
+     * (the serialized class name), then `"langgraph-agent"`.
+     */
+    defaultAgentName?: string;
+}
+/**
+ * Duck-typed LangGraph `BaseCallbackHandler`. Implements `CallbackHandlerSurface`
+ * with chain-start / chain-end / chain-error wired to the Morse trace.
+ *
+ * LangGraph routes callbacks to instance methods by name; it does NOT require
+ * an `instanceof` check against the real `BaseCallbackHandler`. Users who
+ * need that (rare; `instanceof` checks in custom middleware) should obtain
+ * the class via `getCallbackHandlerClass()` instead.
+ */
+declare class MorseCallbackHandler$1 implements CallbackHandlerSurface {
+    /** Required by LangGraph's `BaseCallbackHandler` interface. */
+    readonly name: string;
+    private readonly defaultAgentName;
+    /** Open chain spans, keyed by LangGraph `runId`. */
+    private readonly chainSpans;
+    constructor(options?: MorseCallbackHandlerOptions);
+    handleChainStart(chain: SerializedLike, _inputs: Record<string, unknown>, runId: string, _parentRunId?: string, _tags?: string[], _metadata?: Record<string, unknown>, _runType?: string, runName?: string): void;
+    handleChainEnd(_outputs: Record<string, unknown>, runId: string, parentRunId?: string): void;
+    handleChainError(err: unknown, runId: string, parentRunId?: string): void;
+    /** @internal */
+    _setSpan(runId: string, handle: SpanHandle): void;
+    /** @internal */
+    _takeSpan(runId: string): SpanHandle | undefined;
+    /** @internal */
+    _resolveAgentName(chain: SerializedLike | undefined, runName: string | undefined): string;
+}
+/**
+ * Best-effort: if `@langchain/core/callbacks/base` is installed at runtime,
+ * return an `MorseCallbackHandler`-shaped class whose prototype chain
+ * includes the real `BaseCallbackHandler` (for users relying on
+ * `instanceof BaseCallbackHandler` checks). Otherwise return the
+ * duck-typed `MorseCallbackHandler` defined above.
+ */
+declare function getCallbackHandlerClass(): Promise<typeof MorseCallbackHandler$1>;
+
+/**
+ * `langgraph/llm-and-tool-callbacks.ts` — W2-L.2.
+ *
+ * LangGraph JS callback handler fragment that owns the llm + tool surface
+ * of `BaseCallbackHandler`. The class shell (constructor + chain methods)
+ * is owned by W2-L.1 (`callback-handler.ts`); streaming + checkpoint by
+ * W2-L.3 (`streaming-and-checkpoint.ts`). All three are composed together
+ * by W3-L (`langgraph/index.ts`).
+ *
+ * To stay file-disjoint across the three W2-L tasks, each fragment exports
+ * a `createX` factory that returns plain method implementations operating
+ * on a shared mutable `LangGraphRunState`. The host class threads its
+ * `state` reference through each factory in its constructor and copies the
+ * methods onto its prototype/instance.
+ *
+ * Logical span mapping (per design.md §LangGraph JS):
+ *   handleLLMStart       / handleChatModelStart  → open `type=llm` span
+ *   handleLLMEnd         / handleLLMError        → close active llm span
+ *   handleToolStart                              → open `type=tool` span
+ *   handleToolEnd        / handleToolError       → close active tool span
+ *
+ * MHQ-750: `handleChatModelStart` also decomposes the flattened messages
+ * (+ any bound `tools`) into `context_segments` via the shared
+ * `_agent-sdk-common/context-decomposer`, mirroring the Python adapter's
+ * `on_chat_model_start` (`adapters/langgraph.py`), which calls the same
+ * `decompose_openai_messages` for the same reason: LangGraph JS messages
+ * are `@langchain/core` `BaseMessage`s, which decompose cleanly under the
+ * OpenAI-chat-format decomposer's `_getType()`/`.type` duck-typing.
+ *
+ * All bodies are wrapped in `absorbErrorsSync` so telemetry can never
+ * throw at the host LangGraph runtime.
+ */
+
+/**
+ * Shared per-instance state for the composed `MorseCallbackHandler`.
+ * Owned/instantiated by W3-L (`langgraph/index.ts`); each W2-L fragment
+ * mutates it in place.
+ */
+interface LangGraphRunState {
+    /** Map of runId → SpanHandle for open llm spans. */
+    llmSpans: Map<string, SpanHandle>;
+    /** Map of runId → SpanHandle for open tool spans. */
+    toolSpans: Map<string, SpanHandle>;
+    /** Map of runId → SpanHandle for open chain spans (populated by W2-L.1). */
+    chainSpans: Map<string, SpanHandle>;
+}
+interface LlmAndToolHandlerOptions {
+    /** Max bytes for tool input summary. Falls through to module default if unset. */
+    toolInputMaxBytes?: number;
+    /** Max bytes for tool output summary. Falls through to module default if unset. */
+    toolOutputMaxBytes?: number;
+}
+/** Convenient public type alias for the slice of methods this file owns. */
+type LlmAndToolHandlers = Pick<CallbackHandlerSurface, "handleLLMStart" | "handleChatModelStart" | "handleLLMEnd" | "handleLLMError" | "handleToolStart" | "handleToolEnd" | "handleToolError">;
+/**
+ * Build the llm + tool slice of an `MorseCallbackHandler`. The
+ * returned object can be merged onto the host class instance (W3-L); each
+ * method mutates `state` in place so all three fragments share the same
+ * `runId → SpanHandle` maps.
+ *
+ * Every method body is wrapped in `absorbErrorsSync` — telemetry never
+ * throws into the LangGraph runtime.
+ */
+declare function createLlmAndToolHandlers(state: LangGraphRunState, options?: LlmAndToolHandlerOptions): LlmAndToolHandlers;
+
+/**
+ * `langgraph/streaming-and-checkpoint.ts` — Phase 13 W2-L.3.
+ *
+ * Implements streaming-token aggregation for LangGraph JS. Per the design
+ * doc, streaming tokens fire `handleLLMNewToken` at very high frequency —
+ * we do NOT emit a span per token (would explode volume). Instead we
+ * aggregate them onto the parent llm span's `metadata.tokens_streamed`
+ * counter so downstream consumers can observe streaming activity without
+ * the cardinality blowup.
+ *
+ * Checkpoint hooks (PostgresSaver / SqliteSaver / MemorySaver) are
+ * deferred to v1.5 per the design doc. The surface is left empty here;
+ * W3-L composes this module with the others and may add checkpoint
+ * instrumentation in a follow-up wave without touching the wiring.
+ *
+ * All wrappers route through `absorbErrorsSync` — telemetry MUST NOT
+ * throw at the caller.
+ */
+
+/** State carried across streaming-token events for an in-flight chain run. */
+interface StreamingState {
+    /** Map of `runId` → SpanHandle (the in-flight llm span W2-L.2 opened). */
+    llmSpans: Map<string, SpanHandle>;
+}
+interface StreamingHandlerOptions {
+    /**
+     * If true, emit a single `tokens_streamed` metadata count on the parent
+     * llm span; default true. If false, the handler is a no-op (useful when
+     * the host already tracks streaming elsewhere or wants to minimise
+     * mutation under hot streaming loops).
+     */
+    trackStreamingTokens?: boolean;
+}
+/**
+ * Returns the streaming-related callback method implementations.
+ *
+ * Currently exposes only `handleLLMNewToken`. Checkpoint methods
+ * (`handleCheckpointStart` / `handleCheckpointEnd`) are not on the
+ * `CallbackHandlerSurface` for v1 — they will land in v1.5 when we wire
+ * the PostgresSaver/SqliteSaver hooks. Keeping this module in place
+ * means W3-L's composition does not change shape when those land.
+ */
+declare function createStreamingHandlers(state: StreamingState, options?: StreamingHandlerOptions): Pick<CallbackHandlerSurface, "handleLLMNewToken">;
+
+/**
+ * `@morsehq-dev/sdk/langgraph` — adapter for `@langchain/langgraph` (langgraphjs).
+ *
+ * W3-L: composes the three W2-L surfaces into a single
+ * `MorseCallbackHandler` class exposing the full
+ * `BaseCallbackHandler` shape LangGraph requires:
+ *
+ *   - chain start/end/error  — from W2-L.1 (`callback-handler.ts`)
+ *   - llm + tool start/end/error — from W2-L.2 (`llm-and-tool-callbacks.ts`)
+ *   - llm new-token streaming — from W2-L.3 (`streaming-and-checkpoint.ts`)
+ *
+ * Users get a single class to register with LangGraph:
+ *
+ * ```ts
+ * import { MorseCallbackHandler } from "@morsehq-dev/sdk/langgraph";
+ * await app.invoke(input, { callbacks: [new MorseCallbackHandler()] });
+ * ```
+ *
+ * The W2-L.1 base class keeps its own private map of open chain spans
+ * (since it predates the shared `LangGraphRunState`). To keep things
+ * coherent for advanced consumers reading `state`, the composed class
+ * overrides `handleChainStart` / `handleChainEnd` / `handleChainError`
+ * to ALSO maintain `state.chainSpans` in addition to calling the
+ * super-class method. The base-class behavior is unchanged.
+ */
+
+/** Combined options for the composed handler. */
+type ComposedMorseCallbackHandlerOptions = MorseCallbackHandlerOptions & LlmAndToolHandlerOptions & StreamingHandlerOptions;
+/**
+ * Composed `MorseCallbackHandler` — the user-facing class.
+ *
+ * Inherits chain handlers from `BaseMorseCallbackHandler` (W2-L.1)
+ * and attaches the W2-L.2 llm/tool methods and W2-L.3 streaming method
+ * onto each instance. All four sources share a single
+ * `LangGraphRunState` so future cross-method correlation can read
+ * llm/tool/chain maps from one place.
+ */
+declare class MorseCallbackHandler extends MorseCallbackHandler$1 implements CallbackHandlerSurface {
+    private readonly _state;
+    handleLLMStart: NonNullable<CallbackHandlerSurface["handleLLMStart"]>;
+    handleChatModelStart: NonNullable<CallbackHandlerSurface["handleChatModelStart"]>;
+    handleLLMEnd: NonNullable<CallbackHandlerSurface["handleLLMEnd"]>;
+    handleLLMError: NonNullable<CallbackHandlerSurface["handleLLMError"]>;
+    handleToolStart: NonNullable<CallbackHandlerSurface["handleToolStart"]>;
+    handleToolEnd: NonNullable<CallbackHandlerSurface["handleToolEnd"]>;
+    handleToolError: NonNullable<CallbackHandlerSurface["handleToolError"]>;
+    handleLLMNewToken: NonNullable<CallbackHandlerSurface["handleLLMNewToken"]>;
+    constructor(options?: ComposedMorseCallbackHandlerOptions);
+    /**
+     * The W2-L.1 base maintains its own private chain-span map. We
+     * mirror chain handles into the shared `LangGraphRunState` so future
+     * cross-fragment logic can correlate by runId. Never throws — the
+     * map mutation is in-process and the super method already absorbs
+     * errors via `absorbErrorsSync`.
+     */
+    handleChainStart(chain: SerializedLike, inputs: Record<string, unknown>, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runType?: string, runName?: string): void;
+    handleChainEnd(outputs: Record<string, unknown>, runId: string, parentRunId?: string): void;
+    handleChainError(err: unknown, runId: string, parentRunId?: string): void;
+    /**
+     * Marker insertion for the shared chainSpans map. The W2-L.1 base
+     * holds the real `SpanHandle` privately; for the shared map we just
+     * need *presence* keyed by runId so downstream fragments can detect
+     * an in-flight chain. We stash a sentinel handle whose `end()` is a
+     * no-op — the base owns the real lifecycle.
+     */
+    private _shadowSetChainSpan;
+}
+
+export { type BaseMessageLike, MorseCallbackHandler$1 as BaseMorseCallbackHandler, type CallbackHandlerSurface, type ComposedMorseCallbackHandlerOptions, type LLMResultLike, type LangChainCoreCallbacksModuleLike, type LangGraphRunState, type LlmAndToolHandlerOptions, MorseCallbackHandler, type MorseCallbackHandlerOptions, type SerializedLike, type StreamingHandlerOptions, createLlmAndToolHandlers, createStreamingHandlers, getCallbackHandlerClass };

package/dist/langgraph/index.d.ts

@@ -0,0 +1,324 @@
+import { S as SpanHandle } from '../tracing-rz9cWQ8d.js';
+import '../spans-DZtMuBvc.js';
+
+/**
+ * Structural types for `@langchain/langgraph` (langgraphjs) + `@langchain/core`
+ * callback handlers.
+ *
+ * No hard import — both are optional peer deps. We mirror the
+ * `BaseCallbackHandler` method surface our `MorseCallbackHandler`
+ * needs to extend (or duck-type when the base class isn't installed).
+ */
+/** Subset of `Serialized` from `@langchain/core/load/serializable`. */
+interface SerializedLike {
+    id?: string[];
+    name?: string;
+    kwargs?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+/** Subset of `LLMResult` from `@langchain/core/outputs`. */
+interface LLMResultLike {
+    generations?: Array<Array<{
+        text?: string;
+        [k: string]: unknown;
+    }>>;
+    llmOutput?: {
+        tokenUsage?: {
+            promptTokens?: number;
+            completionTokens?: number;
+            totalTokens?: number;
+            [k: string]: unknown;
+        };
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+/** Subset of `BaseMessage` shape passed to `handleChatModelStart`. */
+interface BaseMessageLike {
+    _getType?(): string;
+    content?: string | unknown[];
+    [k: string]: unknown;
+}
+/**
+ * The methods we override on `BaseCallbackHandler`. We list them with
+ * loose signatures because the real base class is conditionally imported.
+ */
+interface CallbackHandlerSurface {
+    handleChainStart?(chain: SerializedLike, inputs: Record<string, unknown>, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runType?: string, runName?: string): void | Promise<void>;
+    handleChainEnd?(outputs: Record<string, unknown>, runId: string, parentRunId?: string, tags?: string[], kwargs?: Record<string, unknown>): void | Promise<void>;
+    handleChainError?(err: unknown, runId: string, parentRunId?: string): void | Promise<void>;
+    handleLLMStart?(llm: SerializedLike, prompts: string[], runId: string, parentRunId?: string, extra?: Record<string, unknown>): void | Promise<void>;
+    handleChatModelStart?(llm: SerializedLike, messages: BaseMessageLike[][], runId: string, parentRunId?: string, extra?: Record<string, unknown>): void | Promise<void>;
+    handleLLMEnd?(output: LLMResultLike, runId: string, parentRunId?: string): void | Promise<void>;
+    handleLLMError?(err: unknown, runId: string, parentRunId?: string): void | Promise<void>;
+    handleLLMNewToken?(token: string, idx: {
+        prompt: number;
+        completion: number;
+    }, runId: string, parentRunId?: string, tags?: string[]): void | Promise<void>;
+    handleToolStart?(tool: SerializedLike, input: string, runId: string, parentRunId?: string): void | Promise<void>;
+    handleToolEnd?(output: string, runId: string, parentRunId?: string): void | Promise<void>;
+    handleToolError?(err: unknown, runId: string, parentRunId?: string): void | Promise<void>;
+}
+/** Module-shape probe for `@langchain/core/callbacks/base`. */
+interface LangChainCoreCallbacksModuleLike {
+    BaseCallbackHandler?: {
+        new (...args: unknown[]): CallbackHandlerSurface & {
+            name: string;
+        };
+        prototype: CallbackHandlerSurface;
+    };
+    [k: string]: unknown;
+}
+
+/**
+ * `@morsehq-dev/sdk/langgraph` — `MorseCallbackHandler` (W2-L.1).
+ *
+ * The handler is registered by LangGraph users via:
+ *
+ * ```ts
+ * import { MorseCallbackHandler } from "@morsehq-dev/sdk/langgraph";
+ * await app.invoke(input, { callbacks: [new MorseCallbackHandler()] });
+ * ```
+ *
+ * LangGraph type-checks handlers structurally (by method presence on the
+ * instance), not via `instanceof BaseCallbackHandler`. We therefore:
+ *
+ *   1. Always export a duck-typed class implementing `CallbackHandlerSurface`
+ *      — works without `@langchain/core` installed.
+ *   2. Provide `getCallbackHandlerClass()` for users who rely on
+ *      `instanceof BaseCallbackHandler` — it dynamically loads
+ *      `@langchain/core/callbacks/base` (optional peer dep) and returns a
+ *      subclass whose prototype chain includes the real base class.
+ *
+ * Scope of THIS file (W2-L.1): chain spans only. `handleChainStart` opens
+ * an `agent` span (the LangGraph chain IS the agent run); `handleChainEnd`
+ * / `handleChainError` closes it. Nested chains nest via the per-runId
+ * span map — LangGraph guarantees well-ordered start/end pairs so the
+ * tracing-state span stack handles `parent_span_id` linkage for us.
+ *
+ * `handleLLMStart/End`, `handleToolStart/End`, and streaming callbacks
+ * are implemented in W2-L.2 / W2-L.3 as separate methods on the same
+ * class (composed in Wave 3-L).
+ */
+
+interface MorseCallbackHandlerOptions {
+    /**
+     * Override the agent name on the outer chain span. Falls back, in order,
+     * to: `runName` (LangGraph-supplied per-invocation name), `chain.name`
+     * (the serialized class name), then `"langgraph-agent"`.
+     */
+    defaultAgentName?: string;
+}
+/**
+ * Duck-typed LangGraph `BaseCallbackHandler`. Implements `CallbackHandlerSurface`
+ * with chain-start / chain-end / chain-error wired to the Morse trace.
+ *
+ * LangGraph routes callbacks to instance methods by name; it does NOT require
+ * an `instanceof` check against the real `BaseCallbackHandler`. Users who
+ * need that (rare; `instanceof` checks in custom middleware) should obtain
+ * the class via `getCallbackHandlerClass()` instead.
+ */
+declare class MorseCallbackHandler$1 implements CallbackHandlerSurface {
+    /** Required by LangGraph's `BaseCallbackHandler` interface. */
+    readonly name: string;
+    private readonly defaultAgentName;
+    /** Open chain spans, keyed by LangGraph `runId`. */
+    private readonly chainSpans;
+    constructor(options?: MorseCallbackHandlerOptions);
+    handleChainStart(chain: SerializedLike, _inputs: Record<string, unknown>, runId: string, _parentRunId?: string, _tags?: string[], _metadata?: Record<string, unknown>, _runType?: string, runName?: string): void;
+    handleChainEnd(_outputs: Record<string, unknown>, runId: string, parentRunId?: string): void;
+    handleChainError(err: unknown, runId: string, parentRunId?: string): void;
+    /** @internal */
+    _setSpan(runId: string, handle: SpanHandle): void;
+    /** @internal */
+    _takeSpan(runId: string): SpanHandle | undefined;
+    /** @internal */
+    _resolveAgentName(chain: SerializedLike | undefined, runName: string | undefined): string;
+}
+/**
+ * Best-effort: if `@langchain/core/callbacks/base` is installed at runtime,
+ * return an `MorseCallbackHandler`-shaped class whose prototype chain
+ * includes the real `BaseCallbackHandler` (for users relying on
+ * `instanceof BaseCallbackHandler` checks). Otherwise return the
+ * duck-typed `MorseCallbackHandler` defined above.
+ */
+declare function getCallbackHandlerClass(): Promise<typeof MorseCallbackHandler$1>;
+
+/**
+ * `langgraph/llm-and-tool-callbacks.ts` — W2-L.2.
+ *
+ * LangGraph JS callback handler fragment that owns the llm + tool surface
+ * of `BaseCallbackHandler`. The class shell (constructor + chain methods)
+ * is owned by W2-L.1 (`callback-handler.ts`); streaming + checkpoint by
+ * W2-L.3 (`streaming-and-checkpoint.ts`). All three are composed together
+ * by W3-L (`langgraph/index.ts`).
+ *
+ * To stay file-disjoint across the three W2-L tasks, each fragment exports
+ * a `createX` factory that returns plain method implementations operating
+ * on a shared mutable `LangGraphRunState`. The host class threads its
+ * `state` reference through each factory in its constructor and copies the
+ * methods onto its prototype/instance.
+ *
+ * Logical span mapping (per design.md §LangGraph JS):
+ *   handleLLMStart       / handleChatModelStart  → open `type=llm` span
+ *   handleLLMEnd         / handleLLMError        → close active llm span
+ *   handleToolStart                              → open `type=tool` span
+ *   handleToolEnd        / handleToolError       → close active tool span
+ *
+ * MHQ-750: `handleChatModelStart` also decomposes the flattened messages
+ * (+ any bound `tools`) into `context_segments` via the shared
+ * `_agent-sdk-common/context-decomposer`, mirroring the Python adapter's
+ * `on_chat_model_start` (`adapters/langgraph.py`), which calls the same
+ * `decompose_openai_messages` for the same reason: LangGraph JS messages
+ * are `@langchain/core` `BaseMessage`s, which decompose cleanly under the
+ * OpenAI-chat-format decomposer's `_getType()`/`.type` duck-typing.
+ *
+ * All bodies are wrapped in `absorbErrorsSync` so telemetry can never
+ * throw at the host LangGraph runtime.
+ */
+
+/**
+ * Shared per-instance state for the composed `MorseCallbackHandler`.
+ * Owned/instantiated by W3-L (`langgraph/index.ts`); each W2-L fragment
+ * mutates it in place.
+ */
+interface LangGraphRunState {
+    /** Map of runId → SpanHandle for open llm spans. */
+    llmSpans: Map<string, SpanHandle>;
+    /** Map of runId → SpanHandle for open tool spans. */
+    toolSpans: Map<string, SpanHandle>;
+    /** Map of runId → SpanHandle for open chain spans (populated by W2-L.1). */
+    chainSpans: Map<string, SpanHandle>;
+}
+interface LlmAndToolHandlerOptions {
+    /** Max bytes for tool input summary. Falls through to module default if unset. */
+    toolInputMaxBytes?: number;
+    /** Max bytes for tool output summary. Falls through to module default if unset. */
+    toolOutputMaxBytes?: number;
+}
+/** Convenient public type alias for the slice of methods this file owns. */
+type LlmAndToolHandlers = Pick<CallbackHandlerSurface, "handleLLMStart" | "handleChatModelStart" | "handleLLMEnd" | "handleLLMError" | "handleToolStart" | "handleToolEnd" | "handleToolError">;
+/**
+ * Build the llm + tool slice of an `MorseCallbackHandler`. The
+ * returned object can be merged onto the host class instance (W3-L); each
+ * method mutates `state` in place so all three fragments share the same
+ * `runId → SpanHandle` maps.
+ *
+ * Every method body is wrapped in `absorbErrorsSync` — telemetry never
+ * throws into the LangGraph runtime.
+ */
+declare function createLlmAndToolHandlers(state: LangGraphRunState, options?: LlmAndToolHandlerOptions): LlmAndToolHandlers;
+
+/**
+ * `langgraph/streaming-and-checkpoint.ts` — Phase 13 W2-L.3.
+ *
+ * Implements streaming-token aggregation for LangGraph JS. Per the design
+ * doc, streaming tokens fire `handleLLMNewToken` at very high frequency —
+ * we do NOT emit a span per token (would explode volume). Instead we
+ * aggregate them onto the parent llm span's `metadata.tokens_streamed`
+ * counter so downstream consumers can observe streaming activity without
+ * the cardinality blowup.
+ *
+ * Checkpoint hooks (PostgresSaver / SqliteSaver / MemorySaver) are
+ * deferred to v1.5 per the design doc. The surface is left empty here;
+ * W3-L composes this module with the others and may add checkpoint
+ * instrumentation in a follow-up wave without touching the wiring.
+ *
+ * All wrappers route through `absorbErrorsSync` — telemetry MUST NOT
+ * throw at the caller.
+ */
+
+/** State carried across streaming-token events for an in-flight chain run. */
+interface StreamingState {
+    /** Map of `runId` → SpanHandle (the in-flight llm span W2-L.2 opened). */
+    llmSpans: Map<string, SpanHandle>;
+}
+interface StreamingHandlerOptions {
+    /**
+     * If true, emit a single `tokens_streamed` metadata count on the parent
+     * llm span; default true. If false, the handler is a no-op (useful when
+     * the host already tracks streaming elsewhere or wants to minimise
+     * mutation under hot streaming loops).
+     */
+    trackStreamingTokens?: boolean;
+}
+/**
+ * Returns the streaming-related callback method implementations.
+ *
+ * Currently exposes only `handleLLMNewToken`. Checkpoint methods
+ * (`handleCheckpointStart` / `handleCheckpointEnd`) are not on the
+ * `CallbackHandlerSurface` for v1 — they will land in v1.5 when we wire
+ * the PostgresSaver/SqliteSaver hooks. Keeping this module in place
+ * means W3-L's composition does not change shape when those land.
+ */
+declare function createStreamingHandlers(state: StreamingState, options?: StreamingHandlerOptions): Pick<CallbackHandlerSurface, "handleLLMNewToken">;
+
+/**
+ * `@morsehq-dev/sdk/langgraph` — adapter for `@langchain/langgraph` (langgraphjs).
+ *
+ * W3-L: composes the three W2-L surfaces into a single
+ * `MorseCallbackHandler` class exposing the full
+ * `BaseCallbackHandler` shape LangGraph requires:
+ *
+ *   - chain start/end/error  — from W2-L.1 (`callback-handler.ts`)
+ *   - llm + tool start/end/error — from W2-L.2 (`llm-and-tool-callbacks.ts`)
+ *   - llm new-token streaming — from W2-L.3 (`streaming-and-checkpoint.ts`)
+ *
+ * Users get a single class to register with LangGraph:
+ *
+ * ```ts
+ * import { MorseCallbackHandler } from "@morsehq-dev/sdk/langgraph";
+ * await app.invoke(input, { callbacks: [new MorseCallbackHandler()] });
+ * ```
+ *
+ * The W2-L.1 base class keeps its own private map of open chain spans
+ * (since it predates the shared `LangGraphRunState`). To keep things
+ * coherent for advanced consumers reading `state`, the composed class
+ * overrides `handleChainStart` / `handleChainEnd` / `handleChainError`
+ * to ALSO maintain `state.chainSpans` in addition to calling the
+ * super-class method. The base-class behavior is unchanged.
+ */
+
+/** Combined options for the composed handler. */
+type ComposedMorseCallbackHandlerOptions = MorseCallbackHandlerOptions & LlmAndToolHandlerOptions & StreamingHandlerOptions;
+/**
+ * Composed `MorseCallbackHandler` — the user-facing class.
+ *
+ * Inherits chain handlers from `BaseMorseCallbackHandler` (W2-L.1)
+ * and attaches the W2-L.2 llm/tool methods and W2-L.3 streaming method
+ * onto each instance. All four sources share a single
+ * `LangGraphRunState` so future cross-method correlation can read
+ * llm/tool/chain maps from one place.
+ */
+declare class MorseCallbackHandler extends MorseCallbackHandler$1 implements CallbackHandlerSurface {
+    private readonly _state;
+    handleLLMStart: NonNullable<CallbackHandlerSurface["handleLLMStart"]>;
+    handleChatModelStart: NonNullable<CallbackHandlerSurface["handleChatModelStart"]>;
+    handleLLMEnd: NonNullable<CallbackHandlerSurface["handleLLMEnd"]>;
+    handleLLMError: NonNullable<CallbackHandlerSurface["handleLLMError"]>;
+    handleToolStart: NonNullable<CallbackHandlerSurface["handleToolStart"]>;
+    handleToolEnd: NonNullable<CallbackHandlerSurface["handleToolEnd"]>;
+    handleToolError: NonNullable<CallbackHandlerSurface["handleToolError"]>;
+    handleLLMNewToken: NonNullable<CallbackHandlerSurface["handleLLMNewToken"]>;
+    constructor(options?: ComposedMorseCallbackHandlerOptions);
+    /**
+     * The W2-L.1 base maintains its own private chain-span map. We
+     * mirror chain handles into the shared `LangGraphRunState` so future
+     * cross-fragment logic can correlate by runId. Never throws — the
+     * map mutation is in-process and the super method already absorbs
+     * errors via `absorbErrorsSync`.
+     */
+    handleChainStart(chain: SerializedLike, inputs: Record<string, unknown>, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runType?: string, runName?: string): void;
+    handleChainEnd(outputs: Record<string, unknown>, runId: string, parentRunId?: string): void;
+    handleChainError(err: unknown, runId: string, parentRunId?: string): void;
+    /**
+     * Marker insertion for the shared chainSpans map. The W2-L.1 base
+     * holds the real `SpanHandle` privately; for the shared map we just
+     * need *presence* keyed by runId so downstream fragments can detect
+     * an in-flight chain. We stash a sentinel handle whose `end()` is a
+     * no-op — the base owns the real lifecycle.
+     */
+    private _shadowSetChainSpan;
+}
+
+export { type BaseMessageLike, MorseCallbackHandler$1 as BaseMorseCallbackHandler, type CallbackHandlerSurface, type ComposedMorseCallbackHandlerOptions, type LLMResultLike, type LangChainCoreCallbacksModuleLike, type LangGraphRunState, type LlmAndToolHandlerOptions, MorseCallbackHandler, type MorseCallbackHandlerOptions, type SerializedLike, type StreamingHandlerOptions, createLlmAndToolHandlers, createStreamingHandlers, getCallbackHandlerClass };