@picoflow/ezgraph 0.0.4

package/dist/types/npmlib/src/index.d.ts

@@ -0,0 +1,27 @@
+export { BaseGraph, type GraphDefinition, type GraphNodeConstructor, type GraphSchemaMigration, type HistorySpace, } from "../../src/framework/base-graph.js";
+export { GRAPH_NODE_CLASS, GraphNode, GraphNodeRuntime, Tool, type EmptyModelResponseContext, type GraphNodeUpdate, type InvalidJsonResponseContext, type ToolDefinition, type ToolInput, type GraphNodeLocalState, type GraphNodeTarget, type NodeOutcomeBuilder, type OutcomeRouteTarget, } from "../../src/framework/graph-node.js";
+export { ConversationNode, type ConversationNodeRunResult, } from "../../src/framework/conversation-node.js";
+export { LLM_GATEWAY_FACTORY, assertLlmTimeoutMs, type LlmCallOptions, type LlmGateway, type LlmGatewayFactory, type LlmGatewayTool, type LlmGatewayToolCall, } from "../../src/framework/llm-gateway.js";
+export { ConversationRunner, DEFAULT_CONVERSATION_POLICY, DEFAULT_EMPTY_HISTORY_SEED, DEFAULT_EMPTY_RESPONSE_RECOVERY, DEFAULT_MAX_AGENT_ROUNDS, EmptyModelResponseError, assertEmptyResponseRetries, assertMaxAgentRounds, type ConversationPolicy, type ConversationRunResult, type ConversationToolResult, type EmptyResponseRecovery, } from "../../src/framework/conversation-runner.js";
+export { describeStopReason, isRetryableStopReason, modelStopReason, type ModelStopCategory, type ModelStopReason, } from "../../src/framework/model-stop-reason.js";
+export { currentTurnContext, currentTurnSignal, withTurnContext, type TurnContext, } from "../../src/framework/turn-context.js";
+export { type ConversationToolResultBuilder } from "../../src/framework/conversation-tool-result.js";
+export { GraphStateSupport } from "../../src/framework/graph-state-support.js";
+export { GRAPH_END_NODE, createGraphStateAnnotation, type GraphState, } from "../../src/framework/graph-state.js";
+export { GraphRegistry, type RegisteredGraph, } from "../../src/framework/graph-registry.js";
+export { GraphEngine, type GraphConstructor, type GraphEngineCreateOptions, type GraphEngineOptions, type RunResult, } from "../../src/framework/graph-engine.js";
+export { ConfigManager, type ConfigManagerOptions, } from "../../src/framework/config-manager.js";
+export { StateGraphExt, type CurrentNodeBranchOptions, type CurrentNodeSelector, type GraphEndpoint, type GraphNodeClass, type GraphNodeFactory, type RegisteredNode, } from "../../src/framework/state-graph-ext.js";
+export { TerminateSessionNode } from "../../src/framework/terminate-session.node.js";
+export { SessionLogError, SessionLogWarning, createSessionLogs, withSessionLogs, type SessionLogEntry, type SessionLogs, } from "../../src/framework/session-log.js";
+export { ProviderFileManager, type LlmFile, } from "../../src/framework/llm-file.js";
+export { SessionManager, SessionTurnError, SESSION_BUSY, SESSION_CONFLICT, SESSION_COMPLETED, SESSION_DOCUMENT_VERSION, MemorySessionDocumentContainer, sessionTurnLeaseMs, sessionRevision, isLiveSessionTurn, matchesSessionWritePredicate, type SessionGraphMetadata, type SessionGraphDocument, type SessionGraphStatus, type SessionDocument, type SessionDocumentContainer, type SessionTurnLease, type SessionTurnCode, type SessionWritePredicate, type SessionWriteResult, type SessionWriteOptions, type BeginTurnResult, } from "../../src/framework/persistence/session-manager.js";
+export { MongoDbSessionDocumentContainer } from "../../src/framework/persistence/mongodb-session-document.container.js";
+export { SqliteSessionDocumentContainer } from "../../src/framework/persistence/sqlite-session-document.container.js";
+export { CosmosSessionDocumentContainer } from "../../src/framework/persistence/cosmos-session-document.container.js";
+export { mergeNodeStates, type GraphNodeStates, type NodeStateValue, } from "../../src/framework/node-state.js";
+export { LangChainLlmGateway, type LangChainLlmGatewayOptions, } from "../../src/framework/langchain-llm-gateway.js";
+export { ModelProvider, type BuiltInModelProviderConfigs, type CustomModelProviderOptions, type ModelProviderRuntimeConfig, type RegisteredModelProviderAdapter, } from "../../src/framework/model-provider.js";
+export { langChainModelInitialization, type LangChainModelInitialization, } from "../../src/framework/langchain-provider.adapter.js";
+export { GRAPH_LLM_PROVIDERS, GRAPH_LLM_FAMILIES, GRAPH_LLM_CAPABILITIES, BUILT_IN_MODEL_CATALOG, GraphLlm, ModelCatalog, ModelProviderRegistry, type BuiltInGraphLlmConfig, type BuiltInModelId, type BuiltInModelParameters, type CommonModelParameters, type GraphLlmConfig, type GraphLlmConfigOverride, type GraphLlmCapability, type GraphLlmFamily, type GraphLlmModelMetadata, type GraphLlmParameters, type GraphLlmProvider, type GraphLlmRequiredCapabilities, type ModelCatalogDocument, type ModelParameterProfile, type ModelProviderAdapter, type ModelProviderInitialization, type RuntimeGraphLlmConfig, } from "../../src/framework/graph-llm.config.js";
+export { addTokenUsage, emptyTokenUsage, modelExecution, normalizeTokenUsage, tokenUsageFromMessage, type ModelExecution, type ModelResult, type TokenUsage, } from "../../src/framework/token-usage.js";

package/dist/types/npmlib/src/testing.d.ts

@@ -0,0 +1,2 @@
+export { ScriptedGateway, SCRIPTED_MODEL, SCRIPTED_TOKEN_USAGE, scriptedGateway, type ScriptedCall, } from "../../src/testing/scripted-gateway.js";
+export { createTurnHarness, type HarnessTurn, type TurnHarness, } from "../../src/testing/turn-harness.js";

package/dist/types/src/framework/base-graph.d.ts

@@ -0,0 +1,66 @@
+import { type GraphLlmConfig } from './graph-llm.config.js';
+import { HumanMessage } from '@langchain/core/messages';
+import type { LlmGateway } from './llm-gateway.js';
+import { GraphNode, GraphNodeRuntime } from './graph-node.js';
+import type { GraphState } from './graph-state.js';
+import { StateGraphExt, type GraphNodeClass } from './state-graph-ext.js';
+import type { StateDefinitionInit } from '@langchain/langgraph';
+import type { SessionDocument } from './persistence/session-manager.js';
+import { type ConversationPolicy } from './conversation-runner.js';
+export type HistorySpace = readonly [GraphNodeClass, string];
+export type GraphSchemaMigration<State extends GraphState = GraphState> = Readonly<{
+    from: number;
+    migrate(sessionDoc: SessionDocument<State>): SessionDocument<State> | Promise<SessionDocument<State>>;
+}>;
+export type GraphDefinition<NodeId extends string = string, State extends GraphState = GraphState> = Readonly<{
+    llmConfig: GraphLlmConfig;
+    endNode: NodeId;
+    schemaVersion?: number;
+    migrations?: readonly GraphSchemaMigration<State>[];
+    requiresUserMessage?: boolean;
+    responseMode?: 'chat' | 'json';
+    historySpaces?: readonly HistorySpace[];
+    initialHistorySpace?: string;
+    maxAgentRounds?: number;
+    llmTimeoutMs?: number;
+    emptyHistorySeed?: string | null;
+    emptyResponseRecovery?: Readonly<{
+        retries: number;
+        nudge: string;
+    }> | null;
+}>;
+export type GraphNodeConstructor<State extends GraphState> = GraphNodeClass & {
+    new (llmGateway: LlmGateway, runtime: GraphNodeRuntime<State>): GraphNode<State>;
+};
+export declare abstract class BaseGraph<State extends GraphState> {
+    protected readonly llmGateway: LlmGateway;
+    static id(): string;
+    static assertName(value: string): string;
+    static assertId(value: string): string;
+    readonly name: string;
+    readonly id: string;
+    readonly schemaVersion: number;
+    readonly llmConfig: GraphLlmConfig;
+    readonly requiresUserMessage: boolean;
+    readonly responseMode: 'chat' | 'json';
+    readonly maxAgentRounds: number;
+    readonly conversationPolicy: ConversationPolicy;
+    private compiledGraph?;
+    protected readonly runtime: GraphNodeRuntime<State>;
+    private readonly nodeMap;
+    private readonly endNode;
+    private readonly migrations;
+    protected constructor(llmGateway: LlmGateway, definition: GraphDefinition<State['currentNode'], State>);
+    get graph(): {
+        invoke(input: unknown): Promise<State>;
+    };
+    prepareInput(state: State | undefined, message: HumanMessage): Partial<State>;
+    restoreSessionDoc(sessionDoc: SessionDocument<State>): Promise<SessionDocument<State> | null>;
+    protected onRestoreSessionDoc(sessionDoc: SessionDocument<State>): Promise<SessionDocument<State> | null>;
+    protected idleMs(sessionDoc: Pick<SessionDocument, 'modifiedAt'>): number;
+    protected abstract buildGraph(): {
+        invoke(input: unknown): Promise<State>;
+    };
+    protected createStateGraph<StateDefinition extends StateDefinitionInit>(state: StateDefinition): StateGraphExt<StateDefinition>;
+    private createNode;
+}

package/dist/types/src/framework/config-manager.d.ts

@@ -0,0 +1,13 @@
+export type ConfigManagerOptions = Readonly<{
+    envFilePath?: string | string[];
+    ignoreEnvFile?: boolean;
+    environment?: Readonly<Record<string, string | undefined>>;
+    values?: Readonly<Record<string, string | undefined>>;
+}>;
+export declare class ConfigManager {
+    private readonly values;
+    constructor(options?: ConfigManagerOptions);
+    get(key: string): string | undefined;
+    get(key: string, defaultValue: string): string;
+    require(key: string): string;
+}

package/dist/types/src/framework/conversation-node.d.ts

@@ -0,0 +1,18 @@
+import type { ConversationRunResult, ConversationToolResult } from './conversation-runner.js';
+import { GraphNode, type GraphNodeUpdate, type NodeOutcomeBuilder } from './graph-node.js';
+import type { GraphState } from './graph-state.js';
+export type ConversationNodeRunResult = ConversationRunResult & {
+    quitRequested: boolean;
+};
+export declare abstract class ConversationNode<State extends GraphState, LocalState extends object = Record<string, never>, Context extends object = Record<string, never>> extends GraphNode<State, LocalState, Context> {
+    private readonly quitRequests;
+    readonly supportsAutomaticOutcomeRouting = true;
+    protected abstract createContext(state: State): Context;
+    protected abstract nextStep(state: State, context: Context, conversation: ConversationNodeRunResult): GraphNodeUpdate<State> | Promise<GraphNodeUpdate<State>>;
+    protected endChat(input: {
+        message?: string;
+    }, context: Context): Promise<ConversationToolResult>;
+    protected quit(conversation: ConversationRunResult): NodeOutcomeBuilder<State, LocalState>;
+    run(state: State): Promise<GraphNodeUpdate<State>>;
+    protected runConversation(state: State, context: Context): Promise<ConversationNodeRunResult>;
+}

package/dist/types/src/framework/conversation-runner.d.ts

@@ -0,0 +1,49 @@
+import { type BaseMessage } from '@langchain/core/messages';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type { GraphLlmConfig } from './graph-llm.config.js';
+import type { LlmCallOptions, LlmGateway, LlmGatewayTool } from './llm-gateway.js';
+import { type TokenUsage } from './token-usage.js';
+import type { ConversationToolResult } from './conversation-tool-result.js';
+import { type ModelStopReason } from './model-stop-reason.js';
+export type { ConversationToolResult } from './conversation-tool-result.js';
+export type ConversationRunResult = {
+    messages: BaseMessage[];
+    usage: TokenUsage;
+    response?: string;
+    stoppedAfterTool: boolean;
+    stopReason?: ModelStopReason;
+};
+export declare class EmptyModelResponseError extends Error {
+    readonly reason: ModelStopReason;
+    constructor(reason: ModelStopReason);
+}
+export declare const DEFAULT_MAX_AGENT_ROUNDS = 8;
+export declare function assertMaxAgentRounds(value: number): number;
+export declare const DEFAULT_EMPTY_HISTORY_SEED = "Start";
+export type EmptyResponseRecovery = Readonly<{
+    retries: number;
+    nudge: string;
+}>;
+export declare const DEFAULT_EMPTY_RESPONSE_RECOVERY: EmptyResponseRecovery;
+export declare function assertEmptyResponseRetries(value: number): number;
+export type ConversationPolicy = Readonly<{
+    llmTimeoutMs?: number;
+    emptyHistorySeed: string | null;
+    emptyResponseRecovery: EmptyResponseRecovery | null;
+}>;
+export declare const DEFAULT_CONVERSATION_POLICY: ConversationPolicy;
+export declare class ConversationRunner {
+    private readonly llmGateway;
+    constructor(llmGateway: LlmGateway);
+    run(options: {
+        systemPrompt: string;
+        history: readonly BaseMessage[];
+        tools: readonly LlmGatewayTool[];
+        llmConfig: GraphLlmConfig;
+        executeTool: (call: ToolCall) => Promise<ConversationToolResult>;
+        maxAgentRounds?: number;
+        emptyHistorySeed?: string | null;
+        emptyResponseRecovery?: EmptyResponseRecovery | null;
+        callOptions?: LlmCallOptions;
+    }): Promise<ConversationRunResult>;
+}

package/dist/types/src/framework/conversation-tool-result.d.ts

@@ -0,0 +1,19 @@
+import type { BaseMessage } from '@langchain/core/messages';
+export type ConversationToolResult = {
+    output: unknown;
+    messages?: BaseMessage[];
+    cleanup?: () => Promise<void>;
+    stopAfterBatch?: boolean;
+};
+type ContextEffect<Context extends object> = Partial<Context> | ((context: Readonly<Context>) => Partial<Context>);
+type StopPredicate<Context extends object> = boolean | ((context: Readonly<Context>) => boolean);
+export type ConversationToolResultBuilder<Context extends object> = ConversationToolResult & {
+    withContext(effect: ContextEffect<Context>): ConversationToolResultBuilder<Context>;
+    withMessages(messages: BaseMessage | readonly BaseMessage[]): ConversationToolResultBuilder<Context>;
+    withCleanup(cleanup: () => Promise<void>): ConversationToolResultBuilder<Context>;
+    haltAfterBatch(): ConversationToolResultBuilder<Context>;
+    stopAfterBatchWhen(predicate: StopPredicate<Context>): ConversationToolResultBuilder<Context>;
+};
+export declare function createConversationToolResult<Context extends object>(output: unknown): ConversationToolResultBuilder<Context>;
+export declare function resolveConversationToolResult<Context extends object>(result: ConversationToolResult, context: Context): ConversationToolResult;
+export {};

package/dist/types/src/framework/graph-engine.d.ts

@@ -0,0 +1,82 @@
+import { ConfigManager } from "./config-manager.js";
+import type { GraphDefinition } from "./base-graph.js";
+import type { LlmGateway, LlmGatewayFactory } from "./llm-gateway.js";
+import type { GraphState } from "./graph-state.js";
+import type { RegisteredGraph } from "./graph-registry.js";
+import type { RegisteredModelProviderAdapter } from "./model-provider.js";
+import { SessionManager, type SessionDocument } from "./persistence/session-manager.js";
+export type GraphConstructor = {
+    new (llmGateway: LlmGateway): RegisteredGraph;
+    getGraphDefinition(): GraphDefinition;
+};
+export type GraphEngineOptions = Readonly<{
+    sessionManager?: SessionManager;
+    llmGatewayFactory?: LlmGatewayFactory;
+    graphs?: readonly GraphConstructor[];
+    providers?: readonly RegisteredModelProviderAdapter[];
+}>;
+export type GraphEngineCreateOptions = Readonly<{
+    configManager?: ConfigManager;
+    llmGatewayFactory?: LlmGatewayFactory;
+    graphs?: readonly GraphConstructor[];
+    providers?: readonly RegisteredModelProviderAdapter[];
+}>;
+export type RunResult = {
+    status: number;
+    body: {
+        success: boolean;
+        completed: boolean;
+        message: string;
+        bot?: string;
+        session?: string;
+        code?: string;
+    } | Record<string, unknown>;
+    session?: string;
+    contentType?: "application/json";
+};
+export declare class GraphEngine {
+    private readonly registry;
+    private readonly sessions;
+    private readonly llmGatewayFactory;
+    private readonly inflightSessions;
+    constructor(options?: GraphEngineOptions);
+    static create(options?: GraphEngineCreateOptions): Promise<GraphEngine>;
+    registerGraph(graphClasses: readonly GraphConstructor[]): this;
+    getGraphs(): string[];
+    getSession<State extends GraphState = GraphState>(sessionId: string): Promise<SessionDocument<State> | undefined>;
+    run(input: {
+        graphName?: string;
+        userMessage?: string;
+        config?: Record<string, unknown>;
+        sessionId?: string;
+        signal?: AbortSignal;
+    }): Promise<RunResult>;
+    private withTurnScope;
+    deleteSession(sessionId?: string): Promise<{
+        status: number;
+        body: {
+            success: boolean;
+            message: string;
+            session?: never;
+        };
+    } | {
+        status: number;
+        body: {
+            success: boolean;
+            session: string;
+            message?: never;
+        };
+    } | {
+        status: number;
+        body: {
+            success: boolean;
+            session: string;
+            message: string;
+        };
+    }>;
+    close(): Promise<void>;
+    private conflictResult;
+    private completedSessionResult;
+    private jsonResult;
+    private chatResult;
+}

package/dist/types/src/framework/graph-llm.config.d.ts

@@ -0,0 +1,21 @@
+import type { ModelProfile } from '@langchain/core/language_models/profile';
+import { type GraphLlmConfig, type GraphLlmFamily, type GraphLlmParameters } from './model-catalog.js';
+export { BUILT_IN_MODEL_CATALOG, GRAPH_LLM_CAPABILITIES, GRAPH_LLM_FAMILIES, GRAPH_LLM_PROVIDERS, ModelCatalog, ModelProviderRegistry, type AnthropicChatParameters, type AnthropicThinkingParameters, type BasicChatParameters, type BuiltInGraphLlmConfig, type BuiltInModelId, type BuiltInModelParameters, type CommonModelParameters, type GoogleChatParameters, type GraphLlmCapability, type GraphLlmConfig, type GraphLlmFamily, type GraphLlmParameters, type GraphLlmProvider, type GraphLlmRequiredCapabilities, type ModelCatalogDocument, type ModelParameterProfile, type ModelProviderAdapter, type ModelProviderInitialization, type OpenAIChatParameters, type OpenAIReasoningParameters, type ResolvedModelDescriptor, type RuntimeGraphLlmConfig, } from './model-catalog.js';
+export type GraphLlmConfigOverride = GraphLlmConfig | Readonly<{
+    model?: never;
+    params?: Readonly<Record<string, unknown | null>>;
+}>;
+export type GraphLlmModelMetadata = Readonly<{
+    name: string;
+    family: GraphLlmFamily;
+    params: GraphLlmParameters;
+}>;
+export declare class GraphLlm {
+    private constructor();
+    static validateConfig(config: GraphLlmConfig): GraphLlmConfig;
+    static resolveConfig(defaults: GraphLlmConfig, override?: GraphLlmConfigOverride): GraphLlmConfig;
+    static modelIdentifier(config: GraphLlmConfig): string;
+    static parameters(config: GraphLlmConfig): GraphLlmParameters;
+    static modelMetadata(config: GraphLlmConfig): GraphLlmModelMetadata;
+    static validateProfile(config: GraphLlmConfig, profile: Readonly<ModelProfile>): void;
+}

package/dist/types/src/framework/graph-node.d.ts

@@ -0,0 +1,106 @@
+import type { GraphState } from './graph-state.js';
+import type { LlmCallOptions, LlmGateway, LlmGatewayTool } from './llm-gateway.js';
+import 'reflect-metadata';
+import { type BaseMessage } from '@langchain/core/messages';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import { type GraphLlmConfig, type GraphLlmConfigOverride } from './graph-llm.config.js';
+import type { NodeStateValue } from './node-state.js';
+import { GraphStateSupport } from './graph-state-support.js';
+import { type ConversationPolicy, type ConversationRunResult, type ConversationToolResult } from './conversation-runner.js';
+import type { ModelStopReason } from './model-stop-reason.js';
+import { type ConversationToolResultBuilder } from './conversation-tool-result.js';
+import { GRAPH_NODE_LOCAL_STATE, type GraphNodeTarget, type GraphNodeUpdate, type NodeOutcomeBuilder } from './node-outcome.js';
+export { GRAPH_NODE_LOCAL_STATE, type GraphNodeLocalState, type GraphNodeTarget, type GraphNodeUpdate, type NodeOutcomeBuilder, type OutcomeRouteTarget, } from './node-outcome.js';
+export type ToolDefinition<Input extends Record<string, unknown> = Record<string, unknown>> = Readonly<LlmGatewayTool<Input>>;
+export type ToolInput<Tool extends ToolDefinition<any>> = Tool extends ToolDefinition<infer Input> ? Input : never;
+export type InvalidJsonResponseContext<State extends GraphState> = Readonly<{
+    state: Readonly<State>;
+    update: Readonly<GraphNodeUpdate<State>>;
+    response: string;
+    error: Error;
+}>;
+export type EmptyModelResponseContext<State extends GraphState> = Readonly<{
+    state: Readonly<State>;
+    conversation: Readonly<ConversationRunResult>;
+    reason: ModelStopReason;
+}>;
+export declare const GRAPH_NODE_CLASS: unique symbol;
+export declare function Tool(toolName: string): MethodDecorator;
+export declare abstract class GraphNode<State extends GraphState, LocalState extends object = Record<string, never>, ToolContext extends object = Record<string, never>> {
+    protected readonly llmGateway: LlmGateway;
+    private readonly runtime;
+    static readonly [GRAPH_NODE_CLASS] = true;
+    static id(): string;
+    static readonly name: string;
+    readonly [GRAPH_NODE_LOCAL_STATE]: LocalState;
+    readonly supportsAutomaticOutcomeRouting: boolean;
+    readonly name: string;
+    readonly id: string;
+    constructor(llmGateway: LlmGateway, runtime: GraphNodeRuntime<State>);
+    abstract getPrompt(state: State): string;
+    defineTool(): readonly ToolDefinition[];
+    getLlmConfig(): GraphLlmConfigOverride;
+    route(_state: State): string;
+    protected handleTool(state: State, call: ToolCall, context: ToolContext): Promise<ConversationToolResult>;
+    private rejectToolCall;
+    abstract run(state: State): GraphNodeUpdate<State> | Promise<GraphNodeUpdate<State>>;
+    protected onInvalidJsonResponse(context: InvalidJsonResponseContext<State>): GraphNodeUpdate<State> | Promise<GraphNodeUpdate<State>>;
+    protected onEmptyModelResponse(context: EmptyModelResponseContext<State>): string | Promise<string>;
+    readonly invoke: (state: State) => Promise<GraphNodeUpdate<State>>;
+    obtainTools(): readonly ToolDefinition[];
+    validateTools(): void;
+    protected llmConfig(): GraphLlmConfig;
+    protected llmCallOptions(): LlmCallOptions;
+    protected runConversation(state: State, context: ToolContext): Promise<ConversationRunResult>;
+    private runAgentLoop;
+    protected toolResult(output: unknown): ConversationToolResultBuilder<ToolContext>;
+    protected historySpace(): string;
+    protected history(state: Pick<State, 'histories'>): BaseMessage[];
+    protected historyUpdate(messages: BaseMessage[]): Pick<State, 'histories'>;
+    protected respond(message: string): GraphNodeUpdate<State>;
+    protected complete(message: string): GraphNodeUpdate<State>;
+    protected stay(conversation: ConversationRunResult, response?: string | undefined): NodeOutcomeBuilder<State, LocalState>;
+    protected resumeAt<NodeClass extends GraphNodeTarget>(NodeClass: NodeClass, conversation: ConversationRunResult): NodeOutcomeBuilder<State, LocalState>;
+    protected advance<NodeClass extends GraphNodeTarget>(NodeClass: NodeClass, conversation: ConversationRunResult): NodeOutcomeBuilder<State, LocalState, true>;
+    protected transition<NodeClass extends GraphNodeTarget>(NodeClass: NodeClass, conversation: ConversationRunResult, canForwardInput: false): NodeOutcomeBuilder<State, LocalState>;
+    protected transition<NodeClass extends GraphNodeTarget>(NodeClass: NodeClass, conversation: ConversationRunResult, canForwardInput: true): NodeOutcomeBuilder<State, LocalState, true>;
+    protected finish(response: string, conversation: ConversationRunResult): NodeOutcomeBuilder<State, LocalState>;
+    protected state(state: Pick<State, 'nodes'>): NodeStateValue<LocalState>;
+    protected save(patch: Partial<LocalState>): GraphNodeUpdate<State>;
+    protected remove(...keys: (keyof LocalState & string)[]): GraphNodeUpdate<State>;
+    private outcomeBuilder;
+    private toolHandler;
+    private resolveJsonResponse;
+    private toolHandlers;
+}
+export declare class GraphNodeRuntime<State extends GraphState> extends GraphStateSupport<State['currentNode'], State['nodes']> {
+    private readonly defaultLlmConfig;
+    private readonly historySpaces;
+    private readonly initialHistorySpace;
+    private readonly responseMode;
+    readonly maxAgentRounds: number;
+    readonly conversationPolicy: ConversationPolicy;
+    private readonly tools;
+    constructor(endNode: State['currentNode'], defaultLlmConfig: GraphLlmConfig, historySpaces?: Readonly<Record<string, string>>, initialHistorySpace?: string, responseMode?: 'chat' | 'json', maxAgentRounds?: number, conversationPolicy?: ConversationPolicy);
+    llmCallOptions(): LlmCallOptions;
+    expectsJsonResponse(): boolean;
+    historySpace(currentNode?: string): string;
+    resolveLlmConfig(override?: GraphLlmConfigOverride): GraphLlmConfig;
+    registerTools(owner: string, definitions: readonly ToolDefinition[]): void;
+    requireTool(name: string): ToolDefinition;
+    input(state: Pick<State, 'histories' | 'currentNode'>): string;
+    respond(message: string): {
+        response: string;
+        inputConsumed: boolean;
+    };
+    complete(message: string): {
+        currentNode: State["currentNode"];
+        completed: boolean;
+        response: string;
+        inputConsumed: boolean;
+    };
+    saveNode(nodeName: string, values: NodeStateValue): {
+        nodes: State["nodes"];
+    };
+    removeNode(nodeName: string, ...keys: string[]): NonNullable<State["nodes"][keyof State["nodes"]]>;
+}

package/dist/types/src/framework/graph-registry.d.ts

@@ -0,0 +1,26 @@
+import type { GraphState } from './graph-state.js';
+import type { GraphLlmConfig } from './graph-llm.config.js';
+import type { HumanMessage } from '@langchain/core/messages';
+import type { SessionDocument } from './persistence/session-manager.js';
+export interface RegisteredGraph<State extends GraphState = GraphState> {
+    readonly id?: string;
+    readonly name: string;
+    readonly schemaVersion?: number;
+    readonly llmConfig: GraphLlmConfig;
+    readonly requiresUserMessage?: boolean;
+    readonly responseMode?: 'chat' | 'json';
+    readonly graph: {
+        invoke(input: any): Promise<State>;
+    };
+    prepareInput(state: State | undefined, message: HumanMessage): Partial<State>;
+    restoreSessionDoc?(sessionDoc: SessionDocument<State>): Promise<SessionDocument<State> | null>;
+}
+export declare class GraphRegistry {
+    private readonly graphs;
+    constructor(graphs?: readonly RegisteredGraph[]);
+    register(graphs: readonly RegisteredGraph[]): void;
+    get(id?: string): RegisteredGraph | undefined;
+    names(): string[];
+}
+export declare function registeredGraphId(graph: RegisteredGraph): string;
+export declare function registeredGraphSchemaVersion(graph: RegisteredGraph): number;

package/dist/types/src/framework/graph-state-support.d.ts

@@ -0,0 +1,24 @@
+import { type BaseMessage } from '@langchain/core/messages';
+type MessageState = {
+    messages: BaseMessage[];
+};
+export declare abstract class GraphStateSupport<CurrentNode extends string, Nodes extends object> {
+    private readonly endNode;
+    protected constructor(endNode: CurrentNode);
+    protected saveState<NodeName extends keyof Nodes>(nodeName: NodeName, values: NonNullable<Nodes[NodeName]>): {
+        nodes: Nodes;
+    };
+    protected removeState<NodeName extends keyof Nodes, StateKey extends keyof NonNullable<Nodes[NodeName]>>(_nodeName: NodeName, ...keys: StateKey[]): NonNullable<Nodes[NodeName]>;
+    protected latestInput(state: MessageState): string;
+    protected responseUpdate(message: string): {
+        response: string;
+        inputConsumed: boolean;
+    };
+    protected endUpdate(message: string): {
+        currentNode: CurrentNode;
+        completed: boolean;
+        response: string;
+        inputConsumed: boolean;
+    };
+}
+export {};

package/dist/types/src/framework/graph-state.d.ts

@@ -0,0 +1,26 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import { type GraphNodeStates } from './node-state.js';
+import { type TokenUsage } from './token-usage.js';
+export declare const GRAPH_END_NODE: "end";
+export type GraphState<CurrentNode extends string = string, Nodes extends object = GraphNodeStates> = {
+    histories: Record<string, BaseMessage[]>;
+    currentNode: CurrentNode;
+    config: Record<string, unknown>;
+    nodes: Nodes;
+    tokens: TokenUsage;
+    inputConsumed: boolean;
+    response: string;
+    completed: boolean;
+    outcomeRoute: string | undefined;
+};
+export declare function createGraphStateAnnotation<CurrentNode extends string = string, Nodes extends object = GraphNodeStates>(defaultCurrentNode: string, createInitialNodes?: () => Nodes): import("@langchain/langgraph").AnnotationRoot<{
+    histories: import("@langchain/langgraph").BaseChannel<Record<string, BaseMessage<import("@langchain/core/messages").MessageStructure<import("@langchain/core/messages").MessageToolSet>, import("@langchain/core/messages").MessageType>[]>, Record<string, BaseMessage<import("@langchain/core/messages").MessageStructure<import("@langchain/core/messages").MessageToolSet>, import("@langchain/core/messages").MessageType>[]> | import("@langchain/langgraph").OverwriteValue<Record<string, BaseMessage<import("@langchain/core/messages").MessageStructure<import("@langchain/core/messages").MessageToolSet>, import("@langchain/core/messages").MessageType>[]>>, unknown>;
+    currentNode: import("@langchain/langgraph").BaseChannel<CurrentNode, CurrentNode | import("@langchain/langgraph").OverwriteValue<CurrentNode>, unknown>;
+    config: import("@langchain/langgraph").BaseChannel<Record<string, unknown>, Record<string, unknown> | import("@langchain/langgraph").OverwriteValue<Record<string, unknown>>, unknown>;
+    nodes: import("@langchain/langgraph").BaseChannel<Nodes, Nodes | import("@langchain/langgraph").OverwriteValue<Nodes>, unknown>;
+    tokens: import("@langchain/langgraph").BaseChannel<TokenUsage, TokenUsage | import("@langchain/langgraph").OverwriteValue<TokenUsage>, unknown>;
+    inputConsumed: import("@langchain/langgraph").BaseChannel<boolean, boolean | import("@langchain/langgraph").OverwriteValue<boolean>, unknown>;
+    response: import("@langchain/langgraph").BaseChannel<string, string | import("@langchain/langgraph").OverwriteValue<string>, unknown>;
+    completed: import("@langchain/langgraph").BaseChannel<boolean, boolean | import("@langchain/langgraph").OverwriteValue<boolean>, unknown>;
+    outcomeRoute: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+}>;

package/dist/types/src/framework/json-response.d.ts

@@ -0,0 +1 @@
+export declare function parseJsonObjectResponse(response: string): Record<string, unknown>;

package/dist/types/src/framework/langchain-llm-gateway.d.ts

@@ -0,0 +1,23 @@
+import { type BaseMessage, type AIMessage } from "@langchain/core/messages";
+import type { z } from "zod";
+import { type LlmCallOptions, type LlmGateway, type LlmGatewayTool, type LlmGatewayToolCall } from "./llm-gateway.js";
+import { type GraphLlmConfig } from "./graph-llm.config.js";
+import { type RegisteredModelProviderAdapter } from "./model-provider.js";
+import { type ModelResult } from "./token-usage.js";
+export type LangChainLlmGatewayOptions = Readonly<{
+    providers?: readonly RegisteredModelProviderAdapter[];
+}>;
+export declare class LangChainLlmGateway implements LlmGateway {
+    private readonly models;
+    private readonly llmConfig;
+    private readonly providers;
+    constructor(llmConfig: GraphLlmConfig, options?: LangChainLlmGatewayOptions);
+    generate(systemPrompt: string, userPrompt: string, llmConfig?: GraphLlmConfig, callOptions?: LlmCallOptions): Promise<ModelResult<string>>;
+    structured<T extends Record<string, unknown>>(schema: z.ZodType<T>, systemPrompt: string, input: string, name: string, llmConfig?: GraphLlmConfig, history?: readonly BaseMessage[], callOptions?: LlmCallOptions): Promise<ModelResult<T>>;
+    respond(systemPrompt: string, history: readonly BaseMessage[], llmConfig?: GraphLlmConfig, callOptions?: LlmCallOptions): Promise<ModelResult<string>>;
+    agent(systemPrompt: string, history: readonly BaseMessage[], tools: readonly LlmGatewayTool[], llmConfig?: GraphLlmConfig, callOptions?: LlmCallOptions): Promise<ModelResult<AIMessage>>;
+    toolCall(systemPrompt: string, userPrompt: string, tools: readonly LlmGatewayTool[], llmConfig?: GraphLlmConfig, history?: readonly BaseMessage[], callOptions?: LlmCallOptions): Promise<ModelResult<LlmGatewayToolCall | undefined>>;
+    private messages;
+    private getModel;
+    private invoke;
+}

package/dist/types/src/framework/langchain-provider.adapter.d.ts

@@ -0,0 +1,4 @@
+import type { GraphLlmConfig, ModelProviderInitialization } from './graph-llm.config.js';
+import { type RegisteredModelProviderAdapter } from './model-provider.js';
+export type LangChainModelInitialization = ModelProviderInitialization;
+export declare function langChainModelInitialization(config: GraphLlmConfig, providers?: readonly RegisteredModelProviderAdapter[]): LangChainModelInitialization;

package/dist/types/src/framework/llm-file.d.ts

@@ -0,0 +1,13 @@
+export type LlmFile = {
+    contentPart: Record<string, unknown>;
+    fileId: string;
+    cleanup: () => Promise<void>;
+};
+export declare class ProviderFileManager {
+    private readonly provider;
+    constructor(provider: string);
+    uploadFile(filePath: string): Promise<LlmFile>;
+    private uploadToOpenAI;
+    private uploadToGoogle;
+    private uploadToAnthropic;
+}

package/dist/types/src/framework/llm-gateway.d.ts

@@ -0,0 +1,27 @@
+import type { ZodType } from 'zod';
+import type { AIMessage, BaseMessage } from '@langchain/core/messages';
+import type { GraphLlmConfig } from './graph-llm.config.js';
+import type { ModelResult } from './token-usage.js';
+export declare const LLM_GATEWAY_FACTORY: unique symbol;
+export type LlmCallOptions = Readonly<{
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}>;
+export declare function assertLlmTimeoutMs(value: number): number;
+export interface LlmGateway {
+    structured<T extends Record<string, unknown>>(schema: ZodType<T>, systemPrompt: string, input: string, name: string, llmConfig?: GraphLlmConfig, history?: readonly BaseMessage[], callOptions?: LlmCallOptions): Promise<ModelResult<T>>;
+    generate(systemPrompt: string, userPrompt: string, llmConfig?: GraphLlmConfig, callOptions?: LlmCallOptions): Promise<ModelResult<string>>;
+    respond(systemPrompt: string, history: readonly BaseMessage[], llmConfig?: GraphLlmConfig, callOptions?: LlmCallOptions): Promise<ModelResult<string>>;
+    agent(systemPrompt: string, history: readonly BaseMessage[], tools: readonly LlmGatewayTool[], llmConfig?: GraphLlmConfig, callOptions?: LlmCallOptions): Promise<ModelResult<AIMessage>>;
+    toolCall(systemPrompt: string, userPrompt: string, tools: readonly LlmGatewayTool[], llmConfig?: GraphLlmConfig, history?: readonly BaseMessage[], callOptions?: LlmCallOptions): Promise<ModelResult<LlmGatewayToolCall | undefined>>;
+}
+export type LlmGatewayFactory = (config: GraphLlmConfig) => LlmGateway;
+export type LlmGatewayTool<Input extends Record<string, unknown> = Record<string, unknown>> = {
+    name: string;
+    description: string;
+    schema: ZodType<Input>;
+};
+export type LlmGatewayToolCall = {
+    name: string;
+    args: Record<string, unknown>;
+};