@langchain/langgraph-api 1.1.17 → 1.2.1

package/dist/protocol/session/internal-types.d.mts

@@ -0,0 +1,67 @@
+import type { AgentStatus, MessageMetadata, Namespace, ProtocolEventByMethod, SupportedChannel, UpdatesEvent } from "../types.mjs";
+/**
+ * Scalar metadata values that can be forwarded directly in protocol events.
+ */
+export type ProtocolMetadataScalar = string | number | boolean | null;
+/**
+ * Concise message metadata shape exposed to protocol clients.
+ */
+export type ProtocolCompatibleMessageMetadata = MessageMetadata & Record<string, ProtocolMetadataScalar>;
+/**
+ * Subscription state tracked for each connected client.
+ */
+export type SubscriptionChannel = SupportedChannel | `custom:${string}`;
+export type Subscription = {
+    id: string;
+    channels: Set<SubscriptionChannel>;
+    namespaces?: Namespace[];
+    depth?: number;
+    active: boolean;
+};
+/**
+ * Cached lifecycle information for a namespace in the agent tree.
+ */
+export type NamespaceInfo = {
+    namespace: Namespace;
+    status: AgentStatus;
+    graphName: string;
+};
+/**
+ * Normalized representation of an updates payload emitted by the run stream.
+ */
+export type NormalizedUpdatesData = {
+    node?: string;
+    values: UpdatesEvent["params"]["data"]["values"];
+};
+/**
+ * Mapping between supported event methods and their payload shapes.
+ */
+export type ProtocolEventDataMap = {
+    values: ProtocolEventByMethod<"values">["params"]["data"];
+    updates: ProtocolEventByMethod<"updates">["params"]["data"] | UpdatesEvent["params"]["data"]["values"];
+    checkpoints: ProtocolEventByMethod<"checkpoints">["params"]["data"];
+    messages: ProtocolEventByMethod<"messages">["params"]["data"];
+    tools: ProtocolEventByMethod<"tools">["params"]["data"];
+    custom: ProtocolEventByMethod<"custom">["params"]["data"];
+    lifecycle: ProtocolEventByMethod<"lifecycle">["params"]["data"];
+    input: ProtocolEventByMethod<"input">["params"]["data"];
+    tasks: ProtocolEventByMethod<"tasks">["params"]["data"];
+};
+/**
+ * Channel names supported by the run-scoped protocol session.
+ */
+export declare const SUPPORTED_CHANNELS: Set<SupportedChannel>;
+/**
+ * Checks whether a value is a non-null object record.
+ *
+ * @param value - Candidate value to inspect.
+ * @returns Whether the value can be treated as a keyed object.
+ */
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+/**
+ * Checks whether a channel name is supported by the session transport.
+ *
+ * @param value - Raw channel name.
+ * @returns Whether the name matches a supported protocol channel.
+ */
+export declare const isSupportedChannel: (value: string) => value is SupportedChannel;

package/dist/protocol/session/internal-types.mjs

@@ -0,0 +1,28 @@
+/**
+ * Channel names supported by the run-scoped protocol session.
+ */
+export const SUPPORTED_CHANNELS = new Set([
+    "values",
+    "updates",
+    "checkpoints",
+    "messages",
+    "tools",
+    "custom",
+    "lifecycle",
+    "input",
+    "tasks",
+]);
+/**
+ * Checks whether a value is a non-null object record.
+ *
+ * @param value - Candidate value to inspect.
+ * @returns Whether the value can be treated as a keyed object.
+ */
+export const isRecord = (value) => typeof value === "object" && value !== null;
+/**
+ * Checks whether a channel name is supported by the session transport.
+ *
+ * @param value - Raw channel name.
+ * @returns Whether the name matches a supported protocol channel.
+ */
+export const isSupportedChannel = (value) => SUPPORTED_CHANNELS.has(value);

package/dist/protocol/session/metadata.d.mts

@@ -0,0 +1,24 @@
+import type { Namespace } from "../types.mjs";
+import { type ProtocolCompatibleMessageMetadata, type ProtocolMetadataScalar } from "./internal-types.mjs";
+/**
+ * Checks whether a metadata field can be sent as-is in protocol events.
+ *
+ * @param value - Candidate metadata value.
+ * @returns Whether the value is a supported scalar.
+ */
+export declare const isMetadataScalar: (value: unknown) => value is ProtocolMetadataScalar;
+/**
+ * Extracts concise protocol-facing message metadata from a raw payload.
+ *
+ * @param value - Message-like payload or metadata wrapper.
+ * @returns Normalized protocol metadata when at least one supported field
+ * exists.
+ */
+export declare const toProtocolMessageMetadata: (value: unknown) => ProtocolCompatibleMessageMetadata | undefined;
+/**
+ * Derives a namespace from checkpoint metadata attached to a message payload.
+ *
+ * @param value - Message-like payload or metadata wrapper.
+ * @returns Namespace segments when checkpoint metadata is present.
+ */
+export declare const toProtocolMessageNamespace: (value: unknown) => Namespace | undefined;

package/dist/protocol/session/metadata.mjs

@@ -0,0 +1,95 @@
+import { isRecord, } from "./internal-types.mjs";
+const PROTOCOL_METADATA_KEY_MAP = {
+    provider: ["provider", "ls_provider"],
+    model: ["model", "model_name", "ls_model_name"],
+    modelType: ["modelType", "model_type", "ls_model_type"],
+    runId: ["runId", "run_id"],
+    threadId: ["threadId", "thread_id"],
+    systemFingerprint: ["systemFingerprint", "system_fingerprint"],
+    serviceTier: ["serviceTier", "service_tier"],
+};
+const PROTOCOL_METADATA_SOURCE_KEYS = new Set(Object.values(PROTOCOL_METADATA_KEY_MAP).flat());
+const PROTOCOL_METADATA_EXCLUDED_KEYS = new Set([
+    "assistant_id",
+    "checkpoint_ns",
+    "created_by",
+    "graph_id",
+    "langgraph_api_url",
+    "langgraph_checkpoint_ns",
+    "langgraph_host",
+    "langgraph_node",
+    "langgraph_path",
+    "langgraph_plan",
+    "langgraph_step",
+    "langgraph_triggers",
+    "langgraph_version",
+    "ls_integration",
+    "run_attempt",
+    "tags",
+    "versions",
+    "__pregel_task_id",
+]);
+/**
+ * Checks whether a metadata field can be sent as-is in protocol events.
+ *
+ * @param value - Candidate metadata value.
+ * @returns Whether the value is a supported scalar.
+ */
+export const isMetadataScalar = (value) => value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean";
+/**
+ * Extracts concise protocol-facing message metadata from a raw payload.
+ *
+ * @param value - Message-like payload or metadata wrapper.
+ * @returns Normalized protocol metadata when at least one supported field
+ * exists.
+ */
+export const toProtocolMessageMetadata = (value) => {
+    if (!isRecord(value))
+        return undefined;
+    const metadata = isRecord(value.metadata) ? value.metadata : value;
+    const concise = {};
+    for (const [targetKey, sourceKeys] of Object.entries(PROTOCOL_METADATA_KEY_MAP)) {
+        const mappedValue = sourceKeys
+            .map((sourceKey) => metadata[sourceKey])
+            .find((candidate) => isMetadataScalar(candidate));
+        if (mappedValue !== undefined) {
+            concise[targetKey] = mappedValue;
+        }
+    }
+    for (const [key, rawValue] of Object.entries(metadata)) {
+        if (key in PROTOCOL_METADATA_KEY_MAP ||
+            PROTOCOL_METADATA_SOURCE_KEYS.has(key) ||
+            PROTOCOL_METADATA_EXCLUDED_KEYS.has(key) ||
+            key.startsWith("langgraph_") ||
+            key.startsWith("__pregel_") ||
+            key.startsWith("checkpoint_")) {
+            continue;
+        }
+        if (isMetadataScalar(rawValue)) {
+            concise[key] = rawValue;
+        }
+    }
+    return Object.keys(concise).length > 0 ? concise : undefined;
+};
+/**
+ * Derives a namespace from checkpoint metadata attached to a message payload.
+ *
+ * @param value - Message-like payload or metadata wrapper.
+ * @returns Namespace segments when checkpoint metadata is present.
+ */
+export const toProtocolMessageNamespace = (value) => {
+    if (!isRecord(value))
+        return undefined;
+    const metadata = isRecord(value.metadata) ? value.metadata : value;
+    const checkpointNs = typeof metadata.langgraph_checkpoint_ns === "string"
+        ? metadata.langgraph_checkpoint_ns
+        : typeof metadata.checkpoint_ns === "string"
+            ? metadata.checkpoint_ns
+            : undefined;
+    if (!checkpointNs)
+        return undefined;
+    return checkpointNs.split("|").filter((segment) => segment.length > 0);
+};

package/dist/protocol/session/namespace.d.mts

@@ -0,0 +1,47 @@
+import type { Namespace } from "../types.mjs";
+/**
+ * Converts a namespace array into a stable internal lookup key.
+ *
+ * @param namespace - Namespace segments to encode.
+ * @returns A string key that preserves segment boundaries.
+ */
+export declare const toNamespaceKey: (namespace: Namespace) => string;
+/**
+ * Strips dynamic suffixes from a namespace segment for display purposes.
+ *
+ * @param segment - Raw namespace segment.
+ * @returns The stable graph-oriented portion of the segment.
+ */
+export declare const normalizeNamespaceSegment: (segment: string) => string;
+/**
+ * Preserves raw namespace segments in protocol events.
+ *
+ * @param namespace - Namespace segments parsed from the source event.
+ * @returns The namespace exactly as it should be exposed to clients.
+ */
+export declare const normalizeNamespace: (namespace: string[]) => Namespace;
+/**
+ * Splits a stream event name into its method and namespace components.
+ *
+ * @param event - Raw event name emitted by the source stream.
+ * @returns The parsed method plus namespace segments.
+ */
+export declare const parseEventName: (event: string) => {
+    method: string;
+    namespace: string[];
+};
+/**
+ * Checks whether a namespace starts with a requested prefix.
+ *
+ * @param namespace - Event namespace to test.
+ * @param prefix - Subscription namespace prefix.
+ * @returns Whether the namespace matches the prefix semantics.
+ */
+export declare const isPrefixMatch: (namespace: Namespace, prefix: Namespace) => boolean;
+/**
+ * Guesses a human-readable graph name from a namespace.
+ *
+ * @param namespace - Namespace segments for a graph or subgraph.
+ * @returns The derived graph name, or `root` when no segments exist.
+ */
+export declare const guessGraphName: (namespace: Namespace) => string;

package/dist/protocol/session/namespace.mjs

@@ -0,0 +1,62 @@
+/**
+ * Converts a namespace array into a stable internal lookup key.
+ *
+ * @param namespace - Namespace segments to encode.
+ * @returns A string key that preserves segment boundaries.
+ */
+export const toNamespaceKey = (namespace) => namespace.join("\0");
+/**
+ * Strips dynamic suffixes from a namespace segment for display purposes.
+ *
+ * @param segment - Raw namespace segment.
+ * @returns The stable graph-oriented portion of the segment.
+ */
+export const normalizeNamespaceSegment = (segment) => segment.split(":")[0];
+/**
+ * Preserves raw namespace segments in protocol events.
+ *
+ * @param namespace - Namespace segments parsed from the source event.
+ * @returns The namespace exactly as it should be exposed to clients.
+ */
+export const normalizeNamespace = (namespace) => namespace;
+/**
+ * Splits a stream event name into its method and namespace components.
+ *
+ * @param event - Raw event name emitted by the source stream.
+ * @returns The parsed method plus namespace segments.
+ */
+export const parseEventName = (event) => {
+    const [method, ...namespace] = event.split("|");
+    return { method, namespace };
+};
+/**
+ * Checks whether a namespace starts with a requested prefix.
+ *
+ * @param namespace - Event namespace to test.
+ * @param prefix - Subscription namespace prefix.
+ * @returns Whether the namespace matches the prefix semantics.
+ */
+export const isPrefixMatch = (namespace, prefix) => {
+    if (prefix.length > namespace.length)
+        return false;
+    return prefix.every((segment, index) => {
+        const candidate = namespace[index];
+        if (candidate === segment)
+            return true;
+        if (segment.includes(":"))
+            return false;
+        return normalizeNamespaceSegment(candidate) === segment;
+    });
+};
+/**
+ * Guesses a human-readable graph name from a namespace.
+ *
+ * @param namespace - Namespace segments for a graph or subgraph.
+ * @returns The derived graph name, or `root` when no segments exist.
+ */
+export const guessGraphName = (namespace) => {
+    const last = namespace.at(-1);
+    if (last == null)
+        return "root";
+    return normalizeNamespaceSegment(last);
+};

package/dist/protocol/session/state-normalizers.d.mts

@@ -0,0 +1,57 @@
+import type { ContentBlockStartData, UpdatesEvent } from "../types.mjs";
+export declare const normalizeProtocolContentBlock: (value: unknown) => ContentBlockStartData["content"] | undefined;
+export declare const normalizeProtocolMessageContent: (content: unknown, options?: {
+    additionalKwargs?: Record<string, unknown>;
+}) => unknown;
+/**
+ * Normalizes protocol message type aliases into LangChain core message types.
+ *
+ * @param value - Raw message type.
+ * @returns The normalized message type, if recognized.
+ */
+export declare const normalizeProtocolStateMessageType: (value: unknown) => string | undefined;
+/**
+ * Checks whether a value matches the message shape used in state payloads.
+ *
+ * @param value - Raw state value.
+ * @returns Whether the value is a protocol-state message object.
+ */
+export declare const isProtocolStateMessage: (value: unknown) => value is Record<string, unknown>;
+/**
+ * Normalizes invalid tool calls embedded in serialized AI messages.
+ *
+ * @param value - Raw invalid tool call list.
+ * @returns Normalized invalid tool calls.
+ */
+export declare const normalizeProtocolStateInvalidToolCalls: (value: unknown) => Record<string, unknown>[];
+/**
+ * Normalizes tool calls embedded in serialized AI messages.
+ *
+ * @param value - Raw tool call list.
+ * @returns Normalized valid and invalid tool call arrays.
+ */
+export declare const normalizeProtocolStateToolCalls: (value: unknown) => {
+    toolCalls: Record<string, unknown>[];
+    invalidToolCalls: Record<string, unknown>[];
+};
+/**
+ * Normalizes a single message embedded in protocol state payloads.
+ *
+ * @param value - Raw message object.
+ * @returns The normalized message shape.
+ */
+export declare const normalizeProtocolStateMessage: (value: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * Recursively normalizes protocol state payloads before they are emitted.
+ *
+ * @param value - Raw state payload.
+ * @returns The normalized state payload.
+ */
+export declare const normalizeProtocolStatePayload: (value: unknown) => unknown;
+/**
+ * Coerces arbitrary update payloads into the protocol values shape.
+ *
+ * @param value - Raw update payload.
+ * @returns A valid updates values payload.
+ */
+export declare const asUpdateValues: (value: unknown) => UpdatesEvent["params"]["data"]["values"];