Big News: Socket raises $60M Series C at a $1B valuation to secure software supply chains for AI-driven development.Announcement →
Sign In

@langchain/protocol

Package Overview
Dependencies
Maintainers
13
Versions
17
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@langchain/protocol - npm Package Compare versions

Comparing version
0.0.10
 to
0.0.11
+1
-1
package.json
{
"name": "@langchain/protocol",
"version": "0.0.10",
"version": "0.0.11",
"description": "TypeScript bindings for the LangChain agent streaming protocol",

@@ -5,0 +5,0 @@ "license": "MIT",

+231
-127
protocol.ts

@@ -55,6 +55,6 @@ // ==========================================================================

// protocol changes.
// "Chunk" variants (ToolCallChunkBlock, ServerToolCallChunkBlock) carry
// "Chunk" variants (ToolCallChunk, ServerToolCallChunk) carry
// partial/incremental data during streaming. "Standard" variants carry
// finalized data. ContentBlockFinish events upgrade chunks to their
// standard counterparts (e.g. ToolCallChunkBlock -> ToolCallBlock).
// standard counterparts (e.g. ToolCallChunk -> ToolCall).
// ==========================================================================

@@ -72,19 +72,33 @@ export interface MessageMetadata {

// Union of all multimodal data content block types.
export type ContentBlock = TextContentBlock | InvalidToolCall | ReasoningContentBlock | NonStandardContentBlock | DataContentBlock | ToolContentBlock;
// Union of all tool-related content block types (chunk and finalized).
export type DataContentBlock = ImageContentBlock | VideoContentBlock | AudioContentBlock | PlainTextContentBlock | FileContentBlock;
// Finalized content blocks (non-chunk types). Used in content-block-finish.
export type ContentBlock = TextBlock | ReasoningBlock | ToolCallBlock | ToolCallChunkBlock | InvalidToolCallBlock | ServerToolCallBlock | ServerToolCallChunkBlock | ServerToolCallResultBlock | ImageBlock | AudioBlock | VideoBlock | FileBlock | NonStandardBlock;
export type ToolContentBlock = ToolCall | ToolCallChunk | ServerToolCall | ServerToolCallChunk | ServerToolResult;
export type FinalizedContentBlock = TextBlock | ReasoningBlock | ToolCallBlock | InvalidToolCallBlock | ServerToolCallBlock | ServerToolCallResultBlock | ImageBlock | AudioBlock | VideoBlock | FileBlock | NonStandardBlock;
// Index of a block in an aggregate response. Used during streaming.
export type FinalizedContentBlock = TextContentBlock | ReasoningContentBlock | ToolCall | InvalidToolCall | ServerToolCall | ServerToolResult | DataContentBlock | NonStandardContentBlock;
export type TextBlock = Extensible & {
// Provider-specific metadata bag carried on content blocks and annotations.
export type BlockIndex = JsInt | string;
export type Extras = Record<string, any>;
export type TextContentBlock = Extensible & {
type: string;
text: string;
id?: string;
index?: JsInt;
index?: BlockIndex;
annotations?: Annotation[];
extras?: Extras;
};
export type Annotation = Citation | ContentBlock;
export type Annotation = Citation | NonStandardAnnotation;
export type Citation = Extensible & {
type: "citation";
id?: string;
url?: string;

@@ -94,47 +108,61 @@ title?: string;

end_index?: number;
cited_text?: string;
extras?: Extras;
};
export type ReasoningBlock = Extensible & {
export type NonStandardAnnotation = Extensible & {
type: "non_standard_annotation";
id?: string;
value: Record<string, any>;
};
export type ReasoningContentBlock = Extensible & {
type: "reasoning";
reasoning: string;
reasoning?: string;
id?: string;
index?: JsInt;
signature?: string;
redacted?: boolean;
index?: BlockIndex;
extras?: Extras;
};
export type ToolCallBlock = Extensible & {
export type ToolCall = Extensible & {
type: "tool_call";
id: string;
id: string | null;
name: string;
args: any;
args: Record<string, any>;
index?: BlockIndex;
extras?: Extras;
};
export type ToolCallChunkBlock = Extensible & {
export type ToolCallChunk = Extensible & {
type: "tool_call_chunk";
id?: string;
name?: string;
id: string | null;
name: string | null;
/**
* Partial JSON string
*/
args?: string;
index?: JsInt;
args: string | null;
index?: BlockIndex;
extras?: Extras;
};
export type InvalidToolCallBlock = Extensible & {
export type InvalidToolCall = Extensible & {
type: "invalid_tool_call";
id?: string;
name?: string;
args?: string;
error?: string;
id: string | null;
name: string | null;
args: string | null;
error: string | null;
index?: BlockIndex;
extras?: Extras;
};
export type ServerToolCallBlock = Extensible & {
export type ServerToolCall = Extensible & {
type: "server_tool_call";
id: string;
name: string;
args: any;
args: Record<string, any>;
index?: BlockIndex;
extras?: Extras;
};
export type ServerToolCallChunkBlock = Extensible & {
export type ServerToolCallChunk = Extensible & {
type: "server_tool_call_chunk";

@@ -144,14 +172,20 @@ id?: string;

args?: string;
index?: BlockIndex;
extras?: Extras;
};
export type ServerToolCallResultBlock = Extensible & {
type: "server_tool_call_result";
export type ServerToolResult = Extensible & {
type: "server_tool_result";
tool_call_id: string;
status: "success" | "error";
output: any;
id?: string;
output?: any;
index?: BlockIndex;
extras?: Extras;
};
export type ImageBlock = Extensible & {
export type ImageContentBlock = Extensible & {
type: "image";
id?: string;
file_id?: string;
url?: string;

@@ -161,11 +195,12 @@ /**

*/
data?: string;
base64?: string;
mime_type?: string;
width?: number;
height?: number;
index?: BlockIndex;
extras?: Extras;
};
export type AudioBlock = Extensible & {
export type AudioContentBlock = Extensible & {
type: "audio";
id?: string;
file_id?: string;
url?: string;

@@ -175,10 +210,14 @@ /**

*/
data?: string;
base64?: string;
mime_type?: string;
transcript?: string;
index?: BlockIndex;
extras?: Extras;
};
export type VideoBlock = Extensible & {
// Plaintext document data (e.g., .txt/.md). Distinct from TextContentBlock,
// which carries model-authored text output.
export type VideoContentBlock = Extensible & {
type: "video";
id?: string;
file_id?: string;
url?: string;

@@ -188,10 +227,33 @@ /**

*/
data?: string;
base64?: string;
mime_type?: string;
index?: BlockIndex;
extras?: Extras;
};
export type PlainTextContentBlock = Extensible & {
type: "text-plain";
mime_type: "text/plain";
id?: string;
file_id?: string;
url?: string;
/**
* Base64-encoded file data
*/
base64?: string;
/**
* Inline plaintext (optional if base64 is provided)
*/
text?: string;
title?: string;
context?: string;
index?: BlockIndex;
extras?: Extras;
};
// Provider-specific escape hatch for content blocks not modeled above.
export type FileBlock = Extensible & {
export type FileContentBlock = Extensible & {
type: "file";
id?: string;
file_id?: string;
url?: string;

@@ -201,5 +263,6 @@ /**

*/
data?: string;
base64?: string;
mime_type?: string;
filename?: string;
index?: BlockIndex;
extras?: Extras;
};

@@ -216,6 +279,7 @@

// --- Client -> Server ---
export type NonStandardBlock = Extensible & {
export type NonStandardContentBlock = Extensible & {
type: "non_standard";
value: Record<string, any>;
id?: string;
index?: BlockIndex;
};

@@ -228,3 +292,3 @@

// --- Server -> Client ---
export type CommandData = RunCommand | SubscriptionCommand | FlowCommand | AgentCommand | InputCommand | StateCommand;
export type CommandData = RunCommand | SubscriptionCommand | AgentCommand | InputCommand | StateCommand;

@@ -385,3 +449,3 @@ export type Message = CommandResponse | ErrorResponse | Event;

// The server responds with `Content-Type: text/event-stream`.
export type Channel = "values" | "updates" | "messages" | "tools" | "lifecycle" | "input" | "tasks" | "custom" | `custom:${string}`;
export type Channel = "values" | "updates" | "messages" | "tools" | "lifecycle" | "input" | "debug" | "checkpoints" | "tasks" | "custom" | `custom:${string}`;

@@ -470,28 +534,10 @@ // --- WebSocket-only subscription commands ---

// ==========================================================================
// 7. Flow Module
// Backpressure and flow control for high fan-out scenarios.
// ==========================================================================
export type SubscriptionResult = SubscribeResult | ReconnectResult | EmptyResult;
export type FlowCommand = FlowSetCapacity;
export interface FlowSetCapacity {
method: "flow.setCapacity";
params: FlowCapacityParams;
}
export type FlowCapacityParams = Extensible & {
max_buffer_size: number;
strategy: FlowStrategy;
};
// Deliver every Nth event under pressure
// ==========================================================================
// 8. Agent / Lifecycle Module
// 7. Agent / Lifecycle Module
// Hierarchy discovery and lifecycle tracking. The lifecycle channel
// tracks the status of every namespace in the agent tree and provides
// parent→child correlation for subgraph discovery via triggerCallId.
// parent→child correlation for subgraph discovery via the `cause`
// field on `started` events.
// See proposal §17 (Channel Architecture) for the design rationale.
// ==========================================================================
export type FlowStrategy = "drop-oldest" | "pause-producer" | "sample";
export type SubscriptionResult = SubscribeResult | ReconnectResult | EmptyResult;

@@ -528,8 +574,18 @@ // --- agent.getTree ---

// Lifecycle events track the status of the root run and all subgraphs.
// The optional triggerCallId field correlates a child namespace's "started"
// event with the tool call on the parent namespace that triggered it,
// enabling over-the-wire clients to reconstruct the subgraph tree without
// product-specific knowledge.
export type EventData = LifecycleEvent | MessagesEvent | ToolsEvent | InputEvent | ValuesEvent | UpdatesEvent | CustomEvent | TasksEvent;
// The optional `cause` field on `started` events correlates a child
// namespace back to whatever on the parent namespace triggered it,
// enabling over-the-wire clients to reconstruct the subgraph tree
// without product-specific knowledge.
export type EventData = LifecycleEvent | MessagesEvent | ToolsEvent | InputEvent | ValuesEvent | UpdatesEvent | CustomEvent | DebugEvent | CheckpointsEvent | TasksEvent;
// Causation edge for a subgraph's `started` lifecycle event.
// Identifies what on the parent namespace caused this subgraph to
// start. Populated by product-specific stream transformers (e.g.
// deepagents' SubagentTransformer) before events reach the wire.
// langgraph core and langgraph-api are product-agnostic and do not
// populate this field. Optional — absent for the root graph and
// for subgraphs whose spawning mechanism isn't yet modelled.
// Extensible via new variants; consumers MUST default-case unknown
// `type` values to "unknown cause" rather than erroring, so future
// additions don't break pinned clients.
export interface LifecycleEvent {

@@ -544,2 +600,66 @@ method: "lifecycle";

// A tool call on the parent namespace spawned this subgraph.
// How it's produced in code:
// A tool node's handler body invokes a compiled subgraph — e.g.
// `await subagent.ainvoke(...)` or `subagent.astream(...)` from
// inside a `@tool`-decorated function. Deepagents' `task` tool
// is the canonical example: it calls `subagent.ainvoke(input)`
// to execute a nested agent, and each call becomes one subgraph
// run correlated back to the originating `tool_call_id`.
// Populated by: product-specific stream transformer (e.g.
// deepagents' SubagentTransformer / createSubagentTransformer).
export type LifecycleCause = LifecycleCauseToolCall | LifecycleCauseSend | LifecycleCauseEdge;
// A `Send` dispatched from a parent node spawned this subgraph.
// How it's produced in code:
// A parent node returns/yields one or more `Send(node, state)`
// objects (langgraph's fan-out primitive). Each `Send` creates a
// parallel pregel task; when the target node embeds a compiled
// subgraph, each `Send` instance spawns its own subgraph run.
// Typical in supervisor/worker patterns where the supervisor
// yields `Send("worker", work_item)` once per item.
// Populated by: (no transformer in current releases; declared for
// future supervisor-pattern transformers to emit).
export interface LifecycleCauseToolCall {
/**
* The `tool_call_id` from the originating `tool-started` event
*/
type: "toolCall";
/**
* on the parent namespace. Matches the `id` field of the
* originating `tool_call` content block in the parent AI message.
*/
tool_call_id: string;
}
// A graph edge transitioned into this subgraph's entry node.
// How it's produced in code:
// A static edge (`graph.add_edge("a", "b")`) or a conditional
// edge (`graph.add_conditional_edges("a", router_fn)`) routes
// control into a node that embeds a compiled subgraph. Unlike
// `Send`, edge transitions are single-successor and do not
// fan out — one edge traversal produces exactly one subgraph run.
// Populated by: (no transformer in current releases; declared for
// future embedded-subgraph transformers to emit).
export interface LifecycleCauseSend {
/**
* Name of the parent node that issued the `Send`. Multiple Sends
*/
type: "send";
/**
* from the same node in the same superstep share this value;
* future protocol versions may add a disambiguating `sendIndex`
* if per-Send identity is needed on the wire.
*/
from_node: string;
}
export interface LifecycleCauseEdge {
/**
* Name of the parent node the edge originated from.
*/
type: "edge";
from_node: string;
}
// ==========================================================================

@@ -570,5 +690,5 @@ // 8. Messages Module

/**
* Call on parent namespace that started this subgraph
* Causation edge (see LifecycleCause)
*/
trigger_call_id?: string;
cause?: LifecycleCause;
error?: string;

@@ -631,4 +751,4 @@ /**

// Emitted when a content block is complete. The contentBlock carries
// the finalized block. For tool calls, this upgrades ToolCallChunkBlock
// to ToolCallBlock with parsed args.
// the finalized block. For tool calls, this upgrades ToolCallChunk
// to ToolCall with parsed args.
export type ContentBlockDeltaData = Extensible & {

@@ -640,4 +760,3 @@ event: "content-block-delta";

// Emitted once when the message is complete. Human/system replays SHOULD
// use reason="stop".
// Emitted once when the message is complete.
export type ContentBlockFinishData = Extensible & {

@@ -651,3 +770,2 @@ event: "content-block-finish";

event: "message-finish";
reason: FinishReason;
/**

@@ -660,4 +778,2 @@ * Token usage for AI-authored messages

export type FinishReason = "stop" | "length" | "tool_use" | "content_filter";
// Emitted on unrecoverable errors within a model call.

@@ -892,21 +1008,9 @@ export type UsageInfo = Extensible & {

// apply subsequent deltas against.
// The `values` channel also carries an optional lightweight checkpoint
// envelope that identifies which checkpoint captures the emitted state.
// Clients reconstruct a branching/time-travel history from this metadata
// without needing to stream full checkpoint snapshots: the envelope
// provides the fork target (`id`), tree linkage (`parentId`), timeline
// sort/label (`step`, `source`), and the client recovers full channel
// state on demand via `state.get` or bulk via `state.listCheckpoints`.
// ==========================================================================
// --- values (channel: "values") ---
// Full graph state after each step or initial snapshot.
// The optional `checkpoint` envelope identifies which checkpoint captures
// the emitted state. It is present for events that correspond to a newly
// persisted checkpoint; it is omitted for synthetic events such as
// interrupt-signalling emissions that are not tied to a new checkpoint.
export type StateResult = StateGetResult | ListCheckpointsResult | StateForkResult | EmptyResult;
// Lightweight checkpoint envelope carried on `values` events. Supplies
// just enough metadata for clients to build a branching/time-travel UI
// and to target `state.fork` without streaming full channel snapshots.
// --- updates (channel: "updates") ---
// Per-node state deltas.
export interface ValuesEvent {

@@ -921,34 +1025,5 @@ method: "values";

data: any;
/**
* Checkpoint envelope for branching/time-travel
*/
checkpoint?: ValuesCheckpoint;
};
}
// Origin tag matching LangGraph's CheckpointMetadata.source.
export type ValuesCheckpoint = Extensible & {
/**
* Fork target: pass to state.fork / configurable.checkpoint_id
*/
id: string;
/**
* Parent checkpoint id for tree linkage
*/
parent_id?: string;
/**
* Superstep number (-1 for first input, 0 for first loop step, ...)
*/
step: number;
/**
* Origin of the checkpoint
*/
source: CheckpointSource;
};
// Created as a copy of another checkpoint
// --- updates (channel: "updates") ---
// Per-node state deltas.
export type CheckpointSource = "input" | "loop" | "update" | "fork";
export interface UpdatesEvent {

@@ -985,4 +1060,4 @@ method: "updates";

// --- tasks (channel: "tasks") ---
// Pregel task creation or result events from the graph runtime.
// --- debug (channel: "debug") ---
// Verbose execution traces for development.
export type CustomData = Extensible & {

@@ -999,2 +1074,31 @@ /**

// --- checkpoints (channel: "checkpoints") ---
// Checkpoint metadata emitted after each graph step.
export interface DebugEvent {
method: "debug";
params: {
namespace: Namespace;
timestamp: Timestamp;
data: {
step: number;
type: "checkpoint" | "task" | "task_result";
payload?: any;
};
};
}
// --- tasks (channel: "tasks") ---
// Pregel task creation or result events from the graph runtime.
export interface CheckpointsEvent {
method: "checkpoints";
params: {
namespace: Namespace;
timestamp: Timestamp;
/**
* Checkpoint metadata
*/
data: any;
};
}
export interface TasksEvent {

@@ -1001,0 +1105,0 @@ method: "tasks";