@morsehq-dev/sdk 0.4.0-rc.1

package/dist/langchain/index.d.cts

@@ -0,0 +1,265 @@
+import { S as SpanHandle } from '../tracing-BYAqjT5Q.cjs';
+import '../spans-DZtMuBvc.cjs';
+
+/**
+ * Structural types for `@langchain/core` (plain LangChain — chains, LLMs,
+ * tools, retrievers) callback handlers.
+ *
+ * MHQ-482: port of `apps/sdk/python/src/morse_ai/adapters/langchain.py`.
+ *
+ * No hard import — `@langchain/core` is an optional peer dep. We mirror the
+ * `BaseCallbackHandler` method surface our `MorseCallbackHandler` needs to
+ * implement (or duck-type when the base class isn't installed). Verified
+ * against `@langchain/core/dist/callbacks/base.d.ts` — method names and
+ * argument order match exactly (this is the SAME base class LangGraph JS's
+ * `MorseCallbackHandler` in `../langgraph/` implements; the two adapters
+ * are structurally siblings, not a subclass relationship, because
+ * `@langchain/core`'s `BaseCallbackHandler` surface is identical whether a
+ * handler is registered on a plain chain or a LangGraph graph).
+ */
+/** Subset of `Serialized` from `@langchain/core/load/serializable`. */
+interface SerializedLike {
+    id?: string[];
+    name?: string;
+    kwargs?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+/** Subset of `BaseMessage` shape passed on `LLMResult.generations[].message`. */
+interface BaseMessageLike {
+    content?: string | unknown[];
+    /** LC v0.3 standard usage shape — snake_case, matches the Python SDK. */
+    usage_metadata?: {
+        input_tokens?: number;
+        output_tokens?: number;
+        total_tokens?: number;
+        input_token_details?: {
+            cache_read?: number;
+            cache_creation?: number;
+            [k: string]: unknown;
+        };
+        [k: string]: unknown;
+    };
+    response_metadata?: {
+        model_name?: string;
+        model?: string;
+        token_usage?: {
+            prompt_tokens?: number;
+            completion_tokens?: number;
+            total_tokens?: number;
+            input_tokens?: number;
+            output_tokens?: number;
+            [k: string]: unknown;
+        };
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+/** Subset of `Generation` / `ChatGeneration` from `@langchain/core/outputs`. */
+interface GenerationLike {
+    text?: string;
+    message?: BaseMessageLike;
+    [k: string]: unknown;
+}
+/** Subset of `LLMResult` from `@langchain/core/outputs`. */
+interface LLMResultLike {
+    generations?: GenerationLike[][];
+    llmOutput?: {
+        tokenUsage?: Record<string, unknown>;
+        token_usage?: Record<string, unknown>;
+        usage?: Record<string, unknown>;
+        model_name?: string;
+        model?: string;
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+/** Subset of `DocumentInterface` from `@langchain/core/documents`. */
+interface DocumentLike {
+    pageContent?: string;
+    metadata?: {
+        source?: string;
+        score?: number;
+        relevance_score?: number;
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+/**
+ * The methods we implement from `BaseCallbackHandler`. Loose signatures
+ * because the real base class is conditionally imported; argument order
+ * mirrors `@langchain/core/dist/callbacks/base.d.ts` exactly.
+ */
+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, tags?: string[], kwargs?: Record<string, unknown>): void | Promise<void>;
+    handleLLMStart?(llm: SerializedLike, prompts: string[], runId: string, parentRunId?: string, extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): void | Promise<void>;
+    handleChatModelStart?(llm: SerializedLike, messages: BaseMessageLike[][], runId: string, parentRunId?: string, extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): void | Promise<void>;
+    handleLLMEnd?(output: LLMResultLike, runId: string, parentRunId?: string, tags?: string[], extraParams?: Record<string, unknown>): void | Promise<void>;
+    handleLLMError?(err: unknown, runId: string, parentRunId?: string, tags?: string[], extraParams?: Record<string, unknown>): void | Promise<void>;
+    handleToolStart?(tool: SerializedLike, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string): void | Promise<void>;
+    handleToolEnd?(output: unknown, runId: string, parentRunId?: string, tags?: string[]): void | Promise<void>;
+    handleToolError?(err: unknown, runId: string, parentRunId?: string, tags?: string[]): void | Promise<void>;
+    handleRetrieverStart?(retriever: SerializedLike, query: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, name?: string): void | Promise<void>;
+    handleRetrieverEnd?(documents: DocumentLike[], runId: string, parentRunId?: string, tags?: string[]): void | Promise<void>;
+    handleRetrieverError?(err: unknown, runId: string, parentRunId?: string, tags?: 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/langchain` — `MorseCallbackHandler` for plain LangChain
+ * (chains, LLMs, tools, retrievers). Port of
+ * `apps/sdk/python/src/morse_ai/adapters/langchain.py` (MHQ-482).
+ *
+ * Usage:
+ *
+ * ```ts
+ * import { MorseCallbackHandler } from "@morsehq-dev/sdk/langchain";
+ * import { runAsync } from "@morsehq-dev/sdk"; // or morse.run()
+ *
+ * const handler = new MorseCallbackHandler({ agentName: "my-agent" });
+ * await runAsync({ agentName: "my-agent" }, async () => {
+ *   await chain.invoke(input, { callbacks: [handler] });
+ * });
+ * ```
+ *
+ * Span mapping (mirrors the Python adapter):
+ *   - handleChainStart / handleChainEnd / handleChainError → `type=agent`
+ *   - handleLLMStart / handleChatModelStart / handleLLMEnd / handleLLMError → `type=llm`
+ *   - handleToolStart / handleToolEnd / handleToolError → `type=tool`
+ *   - handleRetrieverStart / handleRetrieverEnd / handleRetrieverError (@beta)
+ *     → `type=retriever`
+ *
+ * ## Deviations from the Python adapter (see PR report for full rationale)
+ *
+ * 1. **No auto-trace creation.** Python's `MorseCallbackHandler` calls
+ *    `morse_ai.tracing.run(...)` itself when no trace is active (contextvars
+ *    support manually entering/exiting a context across independent callback
+ *    invocations). The TS SDK's trace context is `AsyncLocalStorage`-based
+ *    (`_internal/tracing.ts`), which only supports the `als.run(store, fn)`
+ *    callback shape — there is no way to open a trace and leave it open
+ *    across separate, unwrapped callback calls. Callers MUST wrap the
+ *    LangChain invocation in `morse.run()` / `runAsync()`. This mirrors the
+ *    constraint the existing `../langgraph/` adapter already operates under
+ *    (see its file-header comments) — every span helper silently no-ops
+ *    (returns `null`) when there is no active trace, exactly like this file.
+ * 2. **No structural subclass relationship with `../langgraph/`.** The task
+ *    brief notes that Python's `langgraph.py::LangGraphCallbackHandler`
+ *    subclasses `langchain.py::MorseCallbackHandler`. `@langchain/core`'s
+ *    `BaseCallbackHandler` surface is identical for plain chains and for
+ *    LangGraph graphs (LangGraph JS is built on `@langchain/core`
+ *    callbacks), so structurally the two TS adapters COULD share a base.
+ *    But the existing `../langgraph/` files are off-limits for this task
+ *    (a separate, already-shipped gap) and refactoring them to extract a
+ *    shared base is out of scope / higher risk than the value it buys right
+ *    now. This adapter is therefore a structural sibling, not a subclass —
+ *    same conventions (span-emission via `startSpan`, `absorbErrorsSync`
+ *    everywhere, `metadata.adapter` tagging), independently implemented.
+ * 3. **No cost computation.** Python's `on_llm_end` calls
+ *    `morse_ai.pricing.calculate_cost` and `merge_provider_reported_cost`.
+ *    Neither has a TS port yet (owned by a separate parallel MHQ-482 gap).
+ *    Token counts/model are still captured; `cost_usd` is left unset until
+ *    the pricing gap lands.
+ * 4. **`type=retriever` uses a real, added `SpanType` variant** (see
+ *    `_internal/spans.ts`) rather than the `type=tool` +
+ *    `metadata.tool_kind` fallback pattern used for `hook`/`subagent` — the
+ *    backend already accepts `"retriever"` (Python's `SpanType.RETRIEVER`
+ *    has shipped since the Python adapter), so no fallback is needed.
+ *
+ * All public methods absorb internal errors (never throw into the LangChain
+ * runtime) — mirrors Python's `try/except Exception: logger.debug(...)`
+ * wrapping on every callback.
+ */
+
+interface MorseCallbackHandlerOptions {
+    /** Falls back to `"langchain-agent"` when unset. Only used for documentation
+     * purposes on this handler instance — the actual trace's agent name is set
+     * by whatever `morse.run()` / `runAsync()` call wraps the invocation. */
+    agentName?: string;
+}
+/**
+ * Coerce arbitrary LangChain chain/tool/retriever input or output into a
+ * dict payload the wire schema requires (`SpanData.input_data` /
+ * `output_data`). Port of Python's `MorseCallbackHandler._ensure_dict`:
+ *
+ * - `null` / `undefined`           → `undefined` (legitimately absent)
+ * - plain object                   → unchanged
+ * - object with a callable `toJSON()` returning a plain object → that result
+ *   (JS analogue of Python's Pydantic `model_dump()` / `dict()` duck typing)
+ * - other (string / number / array / class instance) → `{ value: String(x) }`
+ *
+ * Oversized payloads (JSON > `MAX_STATE_PAYLOAD_BYTES`) are replaced with a
+ * truncation marker so the transport queue stays bounded but the dashboard
+ * still shows a usable preview — never silently dropped to `undefined`.
+ */
+declare function coerceStateValue(data: unknown): Record<string, unknown> | undefined;
+interface TokenUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    cachedInputTokens?: number;
+}
+/**
+ * Returns token usage across the provider shapes LangChain JS integrations
+ * use in practice. Field names below are snake_case because — unlike most
+ * of the JS ecosystem — `@langchain/core`'s `usage_metadata` /
+ * `response_metadata` fields ARE snake_case (verified against
+ * `@langchain/core/dist/messages/ai.d.ts`), matching the Python SDK 1:1.
+ * `llmOutput` is a free-form provider bag; we also check the camelCase
+ * `tokenUsage` key the existing `../langgraph/` adapter established.
+ */
+declare function extractTokenUsage(response: LLMResultLike | null | undefined): TokenUsage;
+/** Best-effort model-name extraction from an `LLMResult`. */
+declare function extractModel(response: LLMResultLike | null | undefined): string | undefined;
+/** Best-effort output-text extraction from an `LLMResult`, for `output_data.text`. */
+declare function extractOutputText(response: LLMResultLike | null | undefined): string;
+declare class MorseCallbackHandler implements CallbackHandlerSurface {
+    /** Required by LangChain's `BaseCallbackHandler` interface. */
+    readonly name: string;
+    readonly agentName: string;
+    /** Map of `runId` → open `SpanHandle`, spanning chain/llm/tool/retriever
+     * spans together (mirrors Python's single `_span_stack` dict). */
+    private readonly spanStack;
+    constructor(options?: MorseCallbackHandlerOptions);
+    private openSpan;
+    private closeSpan;
+    handleChainStart(chain: SerializedLike, inputs: Record<string, unknown>, runId: string): void;
+    handleChainEnd(outputs: Record<string, unknown>, runId: string): void;
+    handleChainError(err: unknown, runId: string): void;
+    handleLLMStart(llm: SerializedLike, prompts: string[], runId: string, _parentRunId?: string, extraParams?: Record<string, unknown>): void;
+    handleChatModelStart(llm: SerializedLike, messages: BaseMessageLike[][], runId: string, _parentRunId?: string, extraParams?: Record<string, unknown>): void;
+    handleLLMEnd(output: LLMResultLike, runId: string): void;
+    handleLLMError(err: unknown, runId: string): void;
+    handleToolStart(tool: SerializedLike, input: string, runId: string): void;
+    handleToolEnd(output: unknown, runId: string): void;
+    handleToolError(err: unknown, runId: string): void;
+    handleRetrieverStart(retriever: SerializedLike, query: string, runId: string): void;
+    handleRetrieverEnd(documents: DocumentLike[], runId: string): void;
+    handleRetrieverError(err: unknown, runId: string): void;
+    /** @internal */
+    _openSpan(runId: string, name: string, type: "agent" | "llm" | "tool" | "retriever", inputData?: unknown, extraMetadata?: Record<string, unknown>): SpanHandle | null;
+    /** @internal */
+    _closeSpan(runId: string, outputData?: unknown, error?: unknown): void;
+    /** @internal */
+    _getSpan(runId: string): SpanHandle | undefined;
+}
+/**
+ * Best-effort: if `@langchain/core/callbacks/base` is installed at runtime,
+ * return a `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. Mirrors `../langgraph/callback-handler.ts`'s
+ * `getCallbackHandlerClass()`.
+ */
+declare function getCallbackHandlerClass(): Promise<typeof MorseCallbackHandler>;
+
+export { type BaseMessageLike, type CallbackHandlerSurface, type DocumentLike, type GenerationLike, type LLMResultLike, type LangChainCoreCallbacksModuleLike, MorseCallbackHandler, type MorseCallbackHandlerOptions, type SerializedLike, type TokenUsage, coerceStateValue, extractModel, extractOutputText, extractTokenUsage, getCallbackHandlerClass };

package/dist/langchain/index.d.ts

@@ -0,0 +1,265 @@
+import { S as SpanHandle } from '../tracing-rz9cWQ8d.js';
+import '../spans-DZtMuBvc.js';
+
+/**
+ * Structural types for `@langchain/core` (plain LangChain — chains, LLMs,
+ * tools, retrievers) callback handlers.
+ *
+ * MHQ-482: port of `apps/sdk/python/src/morse_ai/adapters/langchain.py`.
+ *
+ * No hard import — `@langchain/core` is an optional peer dep. We mirror the
+ * `BaseCallbackHandler` method surface our `MorseCallbackHandler` needs to
+ * implement (or duck-type when the base class isn't installed). Verified
+ * against `@langchain/core/dist/callbacks/base.d.ts` — method names and
+ * argument order match exactly (this is the SAME base class LangGraph JS's
+ * `MorseCallbackHandler` in `../langgraph/` implements; the two adapters
+ * are structurally siblings, not a subclass relationship, because
+ * `@langchain/core`'s `BaseCallbackHandler` surface is identical whether a
+ * handler is registered on a plain chain or a LangGraph graph).
+ */
+/** Subset of `Serialized` from `@langchain/core/load/serializable`. */
+interface SerializedLike {
+    id?: string[];
+    name?: string;
+    kwargs?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+/** Subset of `BaseMessage` shape passed on `LLMResult.generations[].message`. */
+interface BaseMessageLike {
+    content?: string | unknown[];
+    /** LC v0.3 standard usage shape — snake_case, matches the Python SDK. */
+    usage_metadata?: {
+        input_tokens?: number;
+        output_tokens?: number;
+        total_tokens?: number;
+        input_token_details?: {
+            cache_read?: number;
+            cache_creation?: number;
+            [k: string]: unknown;
+        };
+        [k: string]: unknown;
+    };
+    response_metadata?: {
+        model_name?: string;
+        model?: string;
+        token_usage?: {
+            prompt_tokens?: number;
+            completion_tokens?: number;
+            total_tokens?: number;
+            input_tokens?: number;
+            output_tokens?: number;
+            [k: string]: unknown;
+        };
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+/** Subset of `Generation` / `ChatGeneration` from `@langchain/core/outputs`. */
+interface GenerationLike {
+    text?: string;
+    message?: BaseMessageLike;
+    [k: string]: unknown;
+}
+/** Subset of `LLMResult` from `@langchain/core/outputs`. */
+interface LLMResultLike {
+    generations?: GenerationLike[][];
+    llmOutput?: {
+        tokenUsage?: Record<string, unknown>;
+        token_usage?: Record<string, unknown>;
+        usage?: Record<string, unknown>;
+        model_name?: string;
+        model?: string;
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+/** Subset of `DocumentInterface` from `@langchain/core/documents`. */
+interface DocumentLike {
+    pageContent?: string;
+    metadata?: {
+        source?: string;
+        score?: number;
+        relevance_score?: number;
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+/**
+ * The methods we implement from `BaseCallbackHandler`. Loose signatures
+ * because the real base class is conditionally imported; argument order
+ * mirrors `@langchain/core/dist/callbacks/base.d.ts` exactly.
+ */
+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, tags?: string[], kwargs?: Record<string, unknown>): void | Promise<void>;
+    handleLLMStart?(llm: SerializedLike, prompts: string[], runId: string, parentRunId?: string, extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): void | Promise<void>;
+    handleChatModelStart?(llm: SerializedLike, messages: BaseMessageLike[][], runId: string, parentRunId?: string, extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): void | Promise<void>;
+    handleLLMEnd?(output: LLMResultLike, runId: string, parentRunId?: string, tags?: string[], extraParams?: Record<string, unknown>): void | Promise<void>;
+    handleLLMError?(err: unknown, runId: string, parentRunId?: string, tags?: string[], extraParams?: Record<string, unknown>): void | Promise<void>;
+    handleToolStart?(tool: SerializedLike, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string): void | Promise<void>;
+    handleToolEnd?(output: unknown, runId: string, parentRunId?: string, tags?: string[]): void | Promise<void>;
+    handleToolError?(err: unknown, runId: string, parentRunId?: string, tags?: string[]): void | Promise<void>;
+    handleRetrieverStart?(retriever: SerializedLike, query: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, name?: string): void | Promise<void>;
+    handleRetrieverEnd?(documents: DocumentLike[], runId: string, parentRunId?: string, tags?: string[]): void | Promise<void>;
+    handleRetrieverError?(err: unknown, runId: string, parentRunId?: string, tags?: 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/langchain` — `MorseCallbackHandler` for plain LangChain
+ * (chains, LLMs, tools, retrievers). Port of
+ * `apps/sdk/python/src/morse_ai/adapters/langchain.py` (MHQ-482).
+ *
+ * Usage:
+ *
+ * ```ts
+ * import { MorseCallbackHandler } from "@morsehq-dev/sdk/langchain";
+ * import { runAsync } from "@morsehq-dev/sdk"; // or morse.run()
+ *
+ * const handler = new MorseCallbackHandler({ agentName: "my-agent" });
+ * await runAsync({ agentName: "my-agent" }, async () => {
+ *   await chain.invoke(input, { callbacks: [handler] });
+ * });
+ * ```
+ *
+ * Span mapping (mirrors the Python adapter):
+ *   - handleChainStart / handleChainEnd / handleChainError → `type=agent`
+ *   - handleLLMStart / handleChatModelStart / handleLLMEnd / handleLLMError → `type=llm`
+ *   - handleToolStart / handleToolEnd / handleToolError → `type=tool`
+ *   - handleRetrieverStart / handleRetrieverEnd / handleRetrieverError (@beta)
+ *     → `type=retriever`
+ *
+ * ## Deviations from the Python adapter (see PR report for full rationale)
+ *
+ * 1. **No auto-trace creation.** Python's `MorseCallbackHandler` calls
+ *    `morse_ai.tracing.run(...)` itself when no trace is active (contextvars
+ *    support manually entering/exiting a context across independent callback
+ *    invocations). The TS SDK's trace context is `AsyncLocalStorage`-based
+ *    (`_internal/tracing.ts`), which only supports the `als.run(store, fn)`
+ *    callback shape — there is no way to open a trace and leave it open
+ *    across separate, unwrapped callback calls. Callers MUST wrap the
+ *    LangChain invocation in `morse.run()` / `runAsync()`. This mirrors the
+ *    constraint the existing `../langgraph/` adapter already operates under
+ *    (see its file-header comments) — every span helper silently no-ops
+ *    (returns `null`) when there is no active trace, exactly like this file.
+ * 2. **No structural subclass relationship with `../langgraph/`.** The task
+ *    brief notes that Python's `langgraph.py::LangGraphCallbackHandler`
+ *    subclasses `langchain.py::MorseCallbackHandler`. `@langchain/core`'s
+ *    `BaseCallbackHandler` surface is identical for plain chains and for
+ *    LangGraph graphs (LangGraph JS is built on `@langchain/core`
+ *    callbacks), so structurally the two TS adapters COULD share a base.
+ *    But the existing `../langgraph/` files are off-limits for this task
+ *    (a separate, already-shipped gap) and refactoring them to extract a
+ *    shared base is out of scope / higher risk than the value it buys right
+ *    now. This adapter is therefore a structural sibling, not a subclass —
+ *    same conventions (span-emission via `startSpan`, `absorbErrorsSync`
+ *    everywhere, `metadata.adapter` tagging), independently implemented.
+ * 3. **No cost computation.** Python's `on_llm_end` calls
+ *    `morse_ai.pricing.calculate_cost` and `merge_provider_reported_cost`.
+ *    Neither has a TS port yet (owned by a separate parallel MHQ-482 gap).
+ *    Token counts/model are still captured; `cost_usd` is left unset until
+ *    the pricing gap lands.
+ * 4. **`type=retriever` uses a real, added `SpanType` variant** (see
+ *    `_internal/spans.ts`) rather than the `type=tool` +
+ *    `metadata.tool_kind` fallback pattern used for `hook`/`subagent` — the
+ *    backend already accepts `"retriever"` (Python's `SpanType.RETRIEVER`
+ *    has shipped since the Python adapter), so no fallback is needed.
+ *
+ * All public methods absorb internal errors (never throw into the LangChain
+ * runtime) — mirrors Python's `try/except Exception: logger.debug(...)`
+ * wrapping on every callback.
+ */
+
+interface MorseCallbackHandlerOptions {
+    /** Falls back to `"langchain-agent"` when unset. Only used for documentation
+     * purposes on this handler instance — the actual trace's agent name is set
+     * by whatever `morse.run()` / `runAsync()` call wraps the invocation. */
+    agentName?: string;
+}
+/**
+ * Coerce arbitrary LangChain chain/tool/retriever input or output into a
+ * dict payload the wire schema requires (`SpanData.input_data` /
+ * `output_data`). Port of Python's `MorseCallbackHandler._ensure_dict`:
+ *
+ * - `null` / `undefined`           → `undefined` (legitimately absent)
+ * - plain object                   → unchanged
+ * - object with a callable `toJSON()` returning a plain object → that result
+ *   (JS analogue of Python's Pydantic `model_dump()` / `dict()` duck typing)
+ * - other (string / number / array / class instance) → `{ value: String(x) }`
+ *
+ * Oversized payloads (JSON > `MAX_STATE_PAYLOAD_BYTES`) are replaced with a
+ * truncation marker so the transport queue stays bounded but the dashboard
+ * still shows a usable preview — never silently dropped to `undefined`.
+ */
+declare function coerceStateValue(data: unknown): Record<string, unknown> | undefined;
+interface TokenUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    cachedInputTokens?: number;
+}
+/**
+ * Returns token usage across the provider shapes LangChain JS integrations
+ * use in practice. Field names below are snake_case because — unlike most
+ * of the JS ecosystem — `@langchain/core`'s `usage_metadata` /
+ * `response_metadata` fields ARE snake_case (verified against
+ * `@langchain/core/dist/messages/ai.d.ts`), matching the Python SDK 1:1.
+ * `llmOutput` is a free-form provider bag; we also check the camelCase
+ * `tokenUsage` key the existing `../langgraph/` adapter established.
+ */
+declare function extractTokenUsage(response: LLMResultLike | null | undefined): TokenUsage;
+/** Best-effort model-name extraction from an `LLMResult`. */
+declare function extractModel(response: LLMResultLike | null | undefined): string | undefined;
+/** Best-effort output-text extraction from an `LLMResult`, for `output_data.text`. */
+declare function extractOutputText(response: LLMResultLike | null | undefined): string;
+declare class MorseCallbackHandler implements CallbackHandlerSurface {
+    /** Required by LangChain's `BaseCallbackHandler` interface. */
+    readonly name: string;
+    readonly agentName: string;
+    /** Map of `runId` → open `SpanHandle`, spanning chain/llm/tool/retriever
+     * spans together (mirrors Python's single `_span_stack` dict). */
+    private readonly spanStack;
+    constructor(options?: MorseCallbackHandlerOptions);
+    private openSpan;
+    private closeSpan;
+    handleChainStart(chain: SerializedLike, inputs: Record<string, unknown>, runId: string): void;
+    handleChainEnd(outputs: Record<string, unknown>, runId: string): void;
+    handleChainError(err: unknown, runId: string): void;
+    handleLLMStart(llm: SerializedLike, prompts: string[], runId: string, _parentRunId?: string, extraParams?: Record<string, unknown>): void;
+    handleChatModelStart(llm: SerializedLike, messages: BaseMessageLike[][], runId: string, _parentRunId?: string, extraParams?: Record<string, unknown>): void;
+    handleLLMEnd(output: LLMResultLike, runId: string): void;
+    handleLLMError(err: unknown, runId: string): void;
+    handleToolStart(tool: SerializedLike, input: string, runId: string): void;
+    handleToolEnd(output: unknown, runId: string): void;
+    handleToolError(err: unknown, runId: string): void;
+    handleRetrieverStart(retriever: SerializedLike, query: string, runId: string): void;
+    handleRetrieverEnd(documents: DocumentLike[], runId: string): void;
+    handleRetrieverError(err: unknown, runId: string): void;
+    /** @internal */
+    _openSpan(runId: string, name: string, type: "agent" | "llm" | "tool" | "retriever", inputData?: unknown, extraMetadata?: Record<string, unknown>): SpanHandle | null;
+    /** @internal */
+    _closeSpan(runId: string, outputData?: unknown, error?: unknown): void;
+    /** @internal */
+    _getSpan(runId: string): SpanHandle | undefined;
+}
+/**
+ * Best-effort: if `@langchain/core/callbacks/base` is installed at runtime,
+ * return a `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. Mirrors `../langgraph/callback-handler.ts`'s
+ * `getCallbackHandlerClass()`.
+ */
+declare function getCallbackHandlerClass(): Promise<typeof MorseCallbackHandler>;
+
+export { type BaseMessageLike, type CallbackHandlerSurface, type DocumentLike, type GenerationLike, type LLMResultLike, type LangChainCoreCallbacksModuleLike, MorseCallbackHandler, type MorseCallbackHandlerOptions, type SerializedLike, type TokenUsage, coerceStateValue, extractModel, extractOutputText, extractTokenUsage, getCallbackHandlerClass };