@langchain/langgraph-api 1.2.2 → 1.2.3

package/dist/src/protocol/session/index.d.mts

@@ -1,261 +0,0 @@
-import type { AuthContext } from "../../auth/index.mjs";
-import type { Run } from "../../storage/types.mjs";
-import type { ProtocolCommand, ProtocolError, ProtocolResponseMeta, ProtocolSuccess, SourceStreamEvent } from "../types.mjs";
-/**
- * Normalizes one LangGraph run into protocol events and manages per-run
- * subscriptions, buffering, and replay.
- *
- * This class is transport-agnostic: callers provide a `send()` function and an
- * optional source stream, and the session handles command processing plus event
- * fan-out for both direct run-scoped sockets and the shared `v2` session
- * service.
- */
-export declare class RunProtocolSession {
-    private readonly initialRun;
-    private readonly getRun;
-    private readonly getThreadState?;
-    private readonly send;
-    private readonly source?;
-    private readonly subscriptions;
-    private readonly namespaces;
-    private readonly abortController;
-    private readonly buffer;
-    private sendQueue;
-    private sourceTask?;
-    private nextSeq;
-    private rootGraphName;
-    private terminalLifecycleEmitted;
-    private readonly pendingInterruptIds;
-    /**
-     * When true, every event is sent unconditionally via {@link sendJson}
-     * regardless of subscription state. Used for SSE transports where
-     * per-connection filtering is handled by the outer service layer.
-     */
-    private readonly passthrough;
-    /**
-     * Creates a run-scoped protocol session.
-     *
-     * @param options - Session construction options and transport bindings.
-     */
-    constructor(options: {
-        runId: string;
-        threadId?: string;
-        auth?: AuthContext;
-        initialRun: Run;
-        getRun: () => Promise<Run | null>;
-        getThreadState?: () => Promise<{
-            tasks?: Array<{
-                interrupts?: unknown[];
-            }>;
-        } | null>;
-        send: (payload: string) => Promise<void> | void;
-        source?: AsyncIterable<SourceStreamEvent>;
-        startSeq?: number;
-        passthrough?: boolean;
-    });
-    /**
-     * Starts consuming the bound run source and seeds the root lifecycle state.
-     */
-    start(): Promise<void>;
-    /**
-     * Stops consuming the run source and waits for queued writes to settle.
-     */
-    close(): Promise<void>;
-    /**
-     * Parses and handles a raw JSON command coming from the transport.
-     *
-     * @param rawPayload - Raw JSON protocol command payload.
-     */
-    handleCommand(rawPayload: string): Promise<void>;
-    /**
-     * Handles a structured protocol command and returns a typed response.
-     *
-     * When `options.deliverResponseInline` is `true`, a
-     * `subscription.subscribe` resolves to `null` — the success response
-     * has already been written through the shared transport queue ahead
-     * of the replay events (see `handleSubscribeForResponse` for
-     * rationale). Callers that forward the response onto a separate wire
-     * (the WS `onMessage` handler) must treat `null` as
-     * "nothing more to send".
-     *
-     * @param command - Parsed protocol command.
-     * @param meta - Optional response metadata from the outer transport.
-     * @param options - Server-internal delivery flags.
-     * @returns A typed success/error response, or `null` when the
-     *     response was already sent inline.
-     */
-    handleProtocolCommand(command: ProtocolCommand, meta?: ProtocolResponseMeta, options?: {
-        deliverResponseInline?: boolean;
-    }): Promise<ProtocolSuccess | ProtocolError | null>;
-    /**
-     * Injects a raw run stream event into the protocol session.
-     *
-     * @param event - Raw source stream event to normalize.
-     */
-    ingestSourceEvent(event: SourceStreamEvent): Promise<void>;
-    /**
-     * Consumes the bound source stream until completion or cancellation.
-     */
-    private consumeSource;
-    /**
-     * Emits the terminal root lifecycle event once the underlying run
-     * finishes.  Child namespaces are cascaded upstream by core's
-     * `LifecycleTransformer` — the session only owns the root because
-     * terminal status depends on API-only signals (persisted run
-     * status, thread-level pending interrupts).
-     */
-    private emitTerminalLifecycle;
-    /**
-     * Normalizes a single raw source event into protocol events.
-     *
-     * @param event - Raw source stream event.
-     */
-    private handleSourceEvent;
-    /**
-     * Forwards events already converted by core's
-     * `streamEvents(..., { version: "v3" })` pipeline.
-     *
-     * Only events marked by `streamStateV2` after `convertToProtocolEvent` and
-     * the built-in stream transformers have run take this path.
-     */
-    private forwardNormalizedSourceEvent;
-    /**
-     * Ensures the session is tracking each prefix of `namespace` so
-     * agent-tree queries and message routing can resolve it.
-     *
-     * Does **not** emit any wire events: authoritative
-     * `lifecycle.started` events are produced upstream by core's
-     * `LifecycleTransformer` and observed by the session's lifecycle
-     * handler in {@link RunProtocolSession.handleSourceEvent}.  This
-     * method is a defensive fallback for event paths that reference a namespace
-     * before the corresponding `lifecycle` event has been ingested.
-     *
-     * @param namespace - Namespace whose prefixes should be tracked.
-     */
-    private ensureNamespaces;
-    /**
-     * Updates cached namespace metadata used for lifecycle and tree responses.
-     *
-     * @param namespace - Namespace to update.
-     * @param status - New lifecycle status for the namespace.
-     * @param options - Optional graph name override.
-     */
-    private setNamespaceInfo;
-    private createEvent;
-    /**
-     * Buffers an event and delivers it to all matching subscriptions.
-     * Applies the active flow-control strategy when the buffer is at capacity.
-     *
-     * @param event - Protocol event to buffer and fan out.
-     */
-    private pushEvent;
-    /**
-     * Checks whether an event should be delivered to a subscription.
-     *
-     * @param subscription - Subscription to test.
-     * @param event - Candidate protocol event.
-     * @returns Whether the event matches channel and namespace filters.
-     */
-    private matchesSubscription;
-    private hasStatePayload;
-    private emitInputRequestedEvents;
-    /**
-     * Builds the agent tree view rooted at a namespace.
-     *
-     * @param namespace - Namespace to build from.
-     * @returns A recursively assembled agent tree node.
-     */
-    private buildTree;
-    /**
-     * Handles a subscribe command and writes the response to the transport.
-     *
-     * @param command - Subscribe command to process.
-     */
-    private handleSubscribe;
-    /**
-     * Handles a subscribe command and (optionally) writes the
-     * success/error response inline through the shared transport
-     * queue, signalling to callers (via a `null` return) that no
-     * further send is required.
-     *
-     * When `options.deliverResponseInline` is `true`, the success
-     * response is emitted via `sendJson` BEFORE the replay events and
-     * the method returns `null`. This ordering is critical on
-     * single-channel transports like WebSocket where the command
-     * response and event frames share one ordered wire: if events
-     * preceded the response, the client would receive events whose
-     * `subscription_id` it hasn't yet registered (the awaiter in
-     * `#subscribeViaCommand` only adds the subscription to its local
-     * map after the response resolves) and drop them in the per-sub
-     * fan-out.
-     *
-     * When `deliverResponseInline` is absent/`false` (the default, used
-     * by HTTP `/commands`), the response is returned so the caller can
-     * place it in the HTTP response body, matching the prior behaviour.
-     * Input-validation errors always return normally regardless of the
-     * flag so they surface consistently in both modes.
-     *
-     * @param command - Subscribe command to process.
-     * @param meta - Optional response metadata from the outer transport.
-     * @param options - Server-internal delivery flags.
-     * @returns `null` when the response was sent inline; a typed
-     *     success/error response otherwise.
-     */
-    private handleSubscribeForResponse;
-    /**
-     * Handles an unsubscribe command and writes the response to the transport.
-     *
-     * @param command - Unsubscribe command to process.
-     */
-    private handleUnsubscribe;
-    /**
-     * Handles an unsubscribe command and returns a typed response.
-     *
-     * @param command - Unsubscribe command to process.
-     * @param meta - Optional response metadata from the outer transport.
-     * @returns A typed success or error response.
-     */
-    private handleUnsubscribeForResponse;
-    /**
-     * Sends a success response over the bound transport.
-     *
-     * @param id - Command identifier being acknowledged.
-     * @param result - Typed success payload.
-     */
-    private sendSuccess;
-    /**
-     * Sends an error response over the bound transport.
-     *
-     * @param id - Command identifier, when available.
-     * @param error - Protocol error code.
-     * @param message - Human-readable error message.
-     * @param stacktrace - Optional stack trace for debugging.
-     */
-    private sendError;
-    /**
-     * Serializes and writes a protocol payload using the session transport queue.
-     *
-     * @param message - Protocol message to send.
-     */
-    private sendJson;
-    /**
-     * Creates a typed success response object.
-     *
-     * @param id - Command identifier being acknowledged.
-     * @param result - Typed success payload.
-     * @param meta - Optional response metadata from the outer transport.
-     * @returns A typed protocol success response.
-     */
-    private success;
-    /**
-     * Creates a typed error response object.
-     *
-     * @param id - Command identifier, when available.
-     * @param error - Protocol error code.
-     * @param message - Human-readable error message.
-     * @param meta - Optional response metadata from the outer transport.
-     * @param stacktrace - Optional stack trace for debugging.
-     * @returns A typed protocol error response.
-     */
-    private error;
-}