@picoflow/ezgraph 0.0.6 → 0.0.8

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

@@ -1,24 +1,29 @@
-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';
+import { type GraphLlmConfig } from "./graph-llm.config.js";
+import { HumanMessage } from "@langchain/core/messages";
+import type { LlmGateway } from "./llm-gateway.js";
+import { GraphNode, GraphNodeRuntime, type GraphNodeResponse } 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";
+import type { GraphNodeLocalState, GraphNodeTarget } from "./node-outcome.js";
+import type { DecisionOptions, DecisionErrorContext, DecisionProviderAdapter } from "./decision/decision-types.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<{
+export type GraphDefinition<NodeId extends string = string, State extends GraphState = GraphState & {
+    decisionUsage: NonNullable<GraphState["decisionUsage"]>;
+}> = Readonly<{
     llmConfig: GraphLlmConfig;
+    decisionConfig?: DecisionOptions;
     endNode: NodeId;
     schemaVersion?: number;
     migrations?: readonly GraphSchemaMigration<State>[];
     requiresUserMessage?: boolean;
-    responseMode?: 'chat' | 'json';
+    responseMode?: "chat" | "json";
     historySpaces?: readonly HistorySpace[];
     initialHistorySpace?: string;
     maxAgentRounds?: number;
@@ -42,7 +47,7 @@ export declare abstract class BaseGraph<State extends GraphState> {
     readonly schemaVersion: number;
     readonly llmConfig: GraphLlmConfig;
     readonly requiresUserMessage: boolean;
-    readonly responseMode: 'chat' | 'json';
+    readonly responseMode: "chat" | "json";
     readonly maxAgentRounds: number;
     readonly conversationPolicy: ConversationPolicy;
     private compiledGraph?;
@@ -50,16 +55,25 @@ export declare abstract class BaseGraph<State extends GraphState> {
     private readonly nodeMap;
     private readonly endNode;
     private readonly migrations;
-    protected constructor(llmGateway: LlmGateway, definition: GraphDefinition<State['currentNode'], State>);
+    protected constructor(llmGateway: LlmGateway, definition: GraphDefinition<State["currentNode"], State>);
+    protected onDecisionError(_context: DecisionErrorContext<State>): GraphNodeResponse<State> | null | Promise<GraphNodeResponse<State> | null>;
+    attachDecisionProviderResolver(resolve: (id: string) => DecisionProviderAdapter): void;
     get graph(): {
         invoke(input: unknown): Promise<State>;
+        stream(input: unknown, options?: {
+            streamMode?: "values";
+        }): Promise<AsyncIterable<State>>;
     };
     prepareInput(state: State | undefined, message: HumanMessage): Partial<State>;
+    saveNodeState<NodeClass extends GraphNodeTarget>(NodeClass: NodeClass, patch: Partial<GraphNodeLocalState<NodeClass>>): void;
     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 idleMs(sessionDoc: Pick<SessionDocument, "modifiedAt">): number;
     protected abstract buildGraph(): {
         invoke(input: unknown): Promise<State>;
+        stream(input: unknown, options?: {
+            streamMode?: "values";
+        }): Promise<AsyncIterable<State>>;
     };
     protected createStateGraph<StateDefinition extends StateDefinitionInit>(state: StateDefinition): StateGraphExt<StateDefinition>;
     private createNode;

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

@@ -1,18 +1,12 @@
-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>>;
+import type { ConversationRunResult } from "./conversation-runner.js";
+import { GraphNode, type GraphNodeResult } from "./graph-node.js";
+import type { GraphState } from "./graph-state.js";
+import { type ToolResponse } from "./tool-response.js";
+export type ConversationNodeRunResult = ConversationRunResult;
+export declare abstract class ConversationNode<State extends GraphState> extends GraphNode<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>;
+    }): Promise<ToolResponse>;
+    run(state: State): Promise<GraphNodeResult<State>>;
+    private resolveToolResponse;
 }

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

@@ -1,16 +1,16 @@
-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';
+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 ToolResponse } from "./tool-response.js";
+import { type ModelStopReason } from "./model-stop-reason.js";
 export type ConversationRunResult = {
     messages: BaseMessage[];
     usage: TokenUsage;
     response?: string;
     stoppedAfterTool: boolean;
+    toolResponse?: ToolResponse;
     stopReason?: ModelStopReason;
 };
 export declare class EmptyModelResponseError extends Error {
@@ -40,7 +40,7 @@ export declare class ConversationRunner {
         history: readonly BaseMessage[];
         tools: readonly LlmGatewayTool[];
         llmConfig: GraphLlmConfig;
-        executeTool: (call: ToolCall) => Promise<ConversationToolResult>;
+        executeTool: (call: ToolCall) => Promise<ToolResponse>;
         maxAgentRounds?: number;
         emptyHistorySeed?: string | null;
         emptyResponseRecovery?: EmptyResponseRecovery | null;

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

@@ -0,0 +1,17 @@
+import type { ConversationRunResult } from "../conversation-runner.js";
+import { GraphNode, type GraphNodeResponse, type GraphNodeResult } from "../graph-node.js";
+import type { GraphState } from "../graph-state.js";
+import { type DecisionAnswers, type DecisionContext, type DecisionEvidence, type DecisionErrorContext, type DecisionOptions, type DecisionQuestionMap } from "./decision-types.js";
+export declare abstract class DecisionNode<State extends GraphState, Questions extends DecisionQuestionMap = DecisionQuestionMap, LocalState extends object = Record<string, unknown>> extends GraphNode<State, LocalState> {
+    abstract defineQuestions(state: State): Questions;
+    getPrompt(_state: State): string;
+    protected getDecisionEvidence(_state: State): DecisionEvidence;
+    getDecisionConfig(): DecisionOptions;
+    abstract onDecision(answers: DecisionAnswers<Questions>, context: DecisionContext, state: State): GraphNodeResponse<State> | Promise<GraphNodeResponse<State>>;
+    protected onDecisionError(_context: DecisionErrorContext<State>): GraphNodeResponse<State> | null | Promise<GraphNodeResponse<State> | null>;
+    run(state: State): Promise<GraphNodeResult<State>>;
+    validateTools(): void;
+    private assertNoChatConfiguration;
+    protected usesChatModel(): boolean;
+    protected runConversation(_state: State, _context: Record<string, unknown>): Promise<ConversationRunResult>;
+}

package/dist/types/src/framework/decision/decision-provider.d.ts

@@ -0,0 +1,14 @@
+import { type DecisionProviderAdapter } from "./decision-types.js";
+import { type TypeSafeProviderOptions } from "./typesafe-provider.js";
+export type BuiltinDecisionProviderConfigs = Readonly<{
+    typesafe?: TypeSafeProviderOptions | undefined;
+}>;
+export declare class DecisionProvider {
+    private constructor();
+    static create(configs: BuiltinDecisionProviderConfigs): readonly DecisionProviderAdapter[];
+}
+export declare class DecisionProviderRegistry {
+    private readonly providers;
+    constructor(adapters?: readonly DecisionProviderAdapter[]);
+    resolve(id: string): DecisionProviderAdapter;
+}

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

@@ -0,0 +1,18 @@
+import type { GraphState } from "../graph-state.js";
+import type { GraphNodeResult } from "../graph-node.js";
+import { type DecisionAnswers, type DecisionContext, type DecisionConversation, type DecisionErrorContext, type DecisionProviderAdapter, type DecisionQuestionMap, type DecisionState, type ResolvedDecisionOptions } from "./decision-types.js";
+export type DecisionRunOptions<State extends GraphState, Questions extends DecisionQuestionMap> = Readonly<{
+    nodeId: string;
+    state: State;
+    conversation: DecisionConversation;
+    providerState: DecisionState;
+    questions: Questions;
+    provider: DecisionProviderAdapter;
+    options: ResolvedDecisionOptions;
+    callerSignal?: AbortSignal | undefined;
+    onDecision(answers: DecisionAnswers<Questions>, context: DecisionContext, state: State): GraphNodeResult<State> | Promise<GraphNodeResult<State>>;
+    onError(context: DecisionErrorContext<State>): GraphNodeResult<State> | Promise<GraphNodeResult<State>>;
+}>;
+export declare class DecisionRunner {
+    static run<State extends GraphState, Questions extends DecisionQuestionMap>(run: DecisionRunOptions<State, Questions>): Promise<GraphNodeResult<State>>;
+}

package/dist/types/src/framework/decision/decision-types.d.ts

@@ -0,0 +1,126 @@
+import type { GraphState } from "../graph-state.js";
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type JsonObject = Readonly<Record<string, JsonValue>>;
+export type DecisionState = string | JsonObject | readonly JsonValue[];
+export type DecisionConversation = Readonly<{
+    request: string;
+    priorRequests: readonly string[];
+}>;
+export type DecisionEvidence = JsonObject;
+export type Choice = Readonly<{
+    type: "choice";
+    criteria: Readonly<Record<string, JsonValue>>;
+    instructions?: DecisionState;
+}>;
+export type Score = Readonly<{
+    type: "score";
+    criteria: readonly JsonValue[];
+    instructions?: DecisionState;
+}>;
+export type Noul = Readonly<{
+    type: "noul";
+    instructions?: DecisionState;
+    criteria?: Readonly<{
+        true?: JsonValue;
+        false?: JsonValue;
+    }>;
+}>;
+export type DecisionQuestion = Choice | Score | Noul;
+export type DecisionQuestionMap = Readonly<Record<string, DecisionQuestion>>;
+export type ChoiceAnswer<Label extends string = string> = {
+    type: "choice";
+    choice: Label;
+    probabilities: Record<Label, number>;
+    confidence: number;
+};
+export type ScoreAnswer = {
+    type: "score";
+    score: number;
+    legend: Record<string, JsonValue>;
+    probabilities: Record<string, number>;
+    confidence: number;
+};
+export type NoulAnswer = {
+    type: "noul";
+    noul: number;
+};
+export type DecisionAnswer = ChoiceAnswer | ScoreAnswer | NoulAnswer;
+type AnswerFor<Question extends DecisionQuestion> = Question extends Choice ? ChoiceAnswer<Extract<keyof Question["criteria"], string>> : Question extends Score ? ScoreAnswer : NoulAnswer;
+export type DecisionAnswers<Questions extends DecisionQuestionMap> = {
+    -readonly [Key in keyof Questions]: AnswerFor<Questions[Key]>;
+};
+export type DecisionTokenUsage = Readonly<{
+    inputTokens?: number;
+    outputTokens?: number;
+}>;
+export type DecisionUsage = {
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+};
+export declare function emptyDecisionUsage(): DecisionUsage;
+export declare function normalizeDecisionUsage(usage?: Partial<DecisionUsage>): DecisionUsage;
+export declare function addDecisionUsage(current: DecisionUsage | undefined, addition: DecisionUsage | undefined): DecisionUsage;
+export declare function decisionUsage(usage?: DecisionTokenUsage): DecisionUsage;
+export type DecisionOptions = Readonly<{
+    provider?: string;
+    model?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+}>;
+export type ResolvedDecisionOptions = Required<DecisionOptions>;
+export declare const DEFAULT_DECISION_OPTIONS: ResolvedDecisionOptions;
+export declare function resolveDecisionOptions(defaults?: DecisionOptions, overrides?: DecisionOptions): ResolvedDecisionOptions;
+export type DecisionRequest = Readonly<{
+    model: string;
+    state: DecisionState;
+    questions: DecisionQuestionMap;
+}>;
+export type DecisionCallOptions = Readonly<{
+    signal: AbortSignal;
+    timeoutMs: number;
+}>;
+export type DecisionResult = Readonly<{
+    model: string;
+    answers: Record<string, DecisionAnswer>;
+    usage?: DecisionTokenUsage;
+    requestId?: string;
+}>;
+export type DecisionProviderAdapter = Readonly<{
+    id: string;
+    decide(input: DecisionRequest, options: DecisionCallOptions): Promise<DecisionResult>;
+    shouldRetry?(error: Error): boolean;
+}>;
+export type DecisionMetadata = Readonly<{
+    provider: string;
+    model: string;
+    durationMs: number;
+    attempts: number;
+    usage: DecisionTokenUsage;
+    requestId?: string;
+}>;
+export type DecisionContext = DecisionMetadata & DecisionConversation;
+export type DecisionFailure = "configuration" | "provider" | "timeout" | "validation";
+export type DecisionErrorContext<State extends GraphState = GraphState> = Readonly<{
+    nodeId: string;
+    provider: string;
+    model: string;
+    failure: DecisionFailure;
+    attempts: number;
+    error: Error;
+    state: Readonly<State>;
+}>;
+export declare class DecisionValidationError extends Error {
+    constructor(message: string);
+}
+export declare class DecisionConfigurationError extends Error {
+    constructor(message: string);
+}
+export declare class DecisionTimeoutError extends Error {
+    constructor(message?: string);
+}
+export {};

package/dist/types/src/framework/decision/decision-validation.d.ts

@@ -0,0 +1,4 @@
+import { type DecisionQuestionMap, type DecisionResult } from "./decision-types.js";
+export declare function assertJsonCompatible(value: unknown, label: string): void;
+export declare function validateDecisionQuestions(questions: DecisionQuestionMap): void;
+export declare function validateDecisionResult(result: DecisionResult, questions: DecisionQuestionMap): void;

package/dist/types/src/framework/decision/typesafe-provider.d.ts

@@ -0,0 +1,12 @@
+import { type DecisionCallOptions, type DecisionProviderAdapter, type DecisionRequest, type DecisionResult } from "./decision-types.js";
+export type TypeSafeProviderOptions = Readonly<{
+    apiKey?: string | undefined;
+    fetch?: typeof fetch | undefined;
+}>;
+export declare class TypeSafeClassifierAdapter implements DecisionProviderAdapter {
+    private readonly options;
+    readonly id = "typesafe";
+    constructor(options?: TypeSafeProviderOptions);
+    decide(input: DecisionRequest, options: DecisionCallOptions): Promise<DecisionResult>;
+    shouldRetry(error: Error): boolean;
+}

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

@@ -5,6 +5,7 @@ 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";
+import type { DecisionProviderAdapter } from "./decision/decision-types.js";
 export type GraphConstructor = {
     new (llmGateway: LlmGateway): RegisteredGraph;
     getGraphDefinition(): GraphDefinition;
@@ -14,12 +15,14 @@ export type GraphEngineOptions = Readonly<{
     llmGatewayFactory?: LlmGatewayFactory;
     graphs?: readonly GraphConstructor[];
     providers?: readonly RegisteredModelProviderAdapter[];
+    decisionProviders?: readonly DecisionProviderAdapter[];
 }>;
 export type GraphEngineCreateOptions = Readonly<{
     configManager?: ConfigManager;
     llmGatewayFactory?: LlmGatewayFactory;
     graphs?: readonly GraphConstructor[];
     providers?: readonly RegisteredModelProviderAdapter[];
+    decisionProviders?: readonly DecisionProviderAdapter[];
 }>;
 export type RunResult = {
     status: number;
@@ -38,6 +41,7 @@ export declare class GraphEngine {
     private readonly registry;
     private readonly sessions;
     private readonly llmGatewayFactory;
+    private readonly decisionProviders;
     private readonly inflightSessions;
     constructor(options?: GraphEngineOptions);
     static create(options?: GraphEngineCreateOptions): Promise<GraphEngine>;

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

@@ -1,6 +1,6 @@
-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 OpenAIAuthReasoningParameters, type OpenAIChatParameters, type OpenAIReasoningParameters, type ResolvedModelDescriptor, type RuntimeGraphLlmConfig, } from './model-catalog.js';
+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 OpenAIAuthReasoningParameters, 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>>;

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

@@ -1,18 +1,22 @@
-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';
+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 { Command } from "@langchain/langgraph";
+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 } from "./conversation-runner.js";
+import type { ModelStopReason } from "./model-stop-reason.js";
+import { GRAPH_NODE_LOCAL_STATE, type GraphNodeLocalState, type GraphNodeTarget, type GraphNodeUpdate } from "./node-outcome.js";
+import { type ToolResponse } from "./tool-response.js";
+import { type DecisionConversation, type DecisionErrorContext, type DecisionOptions, type DecisionProviderAdapter, type ResolvedDecisionOptions } from "./decision/decision-types.js";
+export { GRAPH_NODE_LOCAL_STATE, type GraphNodeLocalState, type GraphNodeTarget, type GraphNodeUpdate, } 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 GraphNodeResult<State extends GraphState> = GraphNodeUpdate<State> | Command<unknown, GraphNodeUpdate<State>, string>;
+export type GraphNodeResponse<State extends GraphState> = GraphNodeResult<State> | ToolResponse;
 export type InvalidJsonResponseContext<State extends GraphState> = Readonly<{
     state: Readonly<State>;
     update: Readonly<GraphNodeUpdate<State>>;
@@ -26,69 +30,73 @@ export type EmptyModelResponseContext<State extends GraphState> = Readonly<{
 }>;
 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>> {
+export declare abstract class GraphNode<State extends GraphState, LocalState extends object = Record<string, unknown>, ToolContext extends object = Record<string, unknown>> {
     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>);
+    protected get graph(): 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>;
+    protected handleTool(state: State, call: ToolCall, context: ToolContext): Promise<ToolResponse>;
     private rejectToolCall;
-    abstract run(state: State): GraphNodeUpdate<State> | Promise<GraphNodeUpdate<State>>;
+    abstract run(state: State): GraphNodeResponse<State> | Promise<GraphNodeResponse<State>>;
+    protected usesChatModel(): boolean;
     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>>;
+    readonly invoke: (state: State) => Promise<GraphNodeResult<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 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 resolveNodeResponse(result: GraphNodeResponse<State>): GraphNodeResult<State>;
+    protected state(state: Pick<State, "nodes">): NodeStateValue<LocalState>;
+    protected getState(): Readonly<NodeStateValue<LocalState>>;
+    protected saveState(patch: Partial<LocalState>): void;
     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']> {
+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 decisionOptions;
+    private readonly decisionErrorHandler?;
     private readonly tools;
-    constructor(endNode: State['currentNode'], defaultLlmConfig: GraphLlmConfig, historySpaces?: Readonly<Record<string, string>>, initialHistorySpace?: string, responseMode?: 'chat' | 'json', maxAgentRounds?: number, conversationPolicy?: ConversationPolicy);
+    constructor(endNode: State["currentNode"], defaultLlmConfig: GraphLlmConfig, historySpaces?: Readonly<Record<string, string>>, initialHistorySpace?: string, responseMode?: "chat" | "json", maxAgentRounds?: number, conversationPolicy?: ConversationPolicy, decisionOptions?: DecisionOptions, decisionErrorHandler?: ((context: DecisionErrorContext<State>) => GraphNodeResponse<State> | null | Promise<GraphNodeResponse<State> | null>) | undefined);
     llmCallOptions(): LlmCallOptions;
     expectsJsonResponse(): boolean;
     historySpace(currentNode?: string): string;
     resolveLlmConfig(override?: GraphLlmConfigOverride): GraphLlmConfig;
+    resolveDecisionOptions(override?: DecisionOptions): ResolvedDecisionOptions;
+    private decisionProviderResolver?;
+    attachDecisionProviderResolver(resolve: (id: string) => DecisionProviderAdapter): void;
+    resolveDecisionProvider(id: string): DecisionProviderAdapter;
+    handleDecisionError(context: DecisionErrorContext<State>): Promise<GraphNodeResponse<State> | null>;
     registerTools(owner: string, definitions: readonly ToolDefinition[]): void;
     requireTool(name: string): ToolDefinition;
-    input(state: Pick<State, 'histories' | 'currentNode'>): string;
+    input(state: Pick<State, "histories" | "currentNode">): string;
+    getConversation(space: string): DecisionConversation;
     respond(message: string): {
         response: string;
         inputConsumed: boolean;
@@ -99,8 +107,15 @@ export declare class GraphNodeRuntime<State extends GraphState> extends GraphSta
         response: string;
         inputConsumed: boolean;
     };
-    saveNode(nodeName: string, values: NodeStateValue): {
-        nodes: State["nodes"];
-    };
-    removeNode(nodeName: string, ...keys: string[]): NonNullable<State["nodes"][keyof State["nodes"]]>;
+    withInvocation<Result>(nodeId: string, state: State, run: () => Promise<Result>): Promise<Result>;
+    nodeState(nodeName: string): Record<string, unknown>;
+    hasInvocation(): boolean;
+    graphState(): State;
+    appendHistory(space: string, messages: readonly BaseMessage[]): void;
+    invocationHistory(space: string): BaseMessage[];
+    stagedUpdate(): GraphNodeUpdate<State>;
+    stageNodeEntries(nodes: State["nodes"] | undefined): void;
+    saveNode(nodeName: string, values: NodeStateValue): GraphNodeUpdate<State>;
+    saveNodeState<NodeClass extends GraphNodeTarget>(NodeClass: NodeClass, patch: Partial<GraphNodeLocalState<NodeClass>>): void;
+    removeNode(nodeName: string, ...keys: string[]): Partial<State>;
 }

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

@@ -1,18 +1,23 @@
-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';
+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";
+import type { DecisionProviderAdapter } from "./decision/decision-types.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 responseMode?: "chat" | "json";
     readonly graph: {
         invoke(input: any): Promise<State>;
+        stream?(input: any, options?: {
+            streamMode?: "values";
+        }): Promise<AsyncIterable<State>>;
     };
     prepareInput(state: State | undefined, message: HumanMessage): Partial<State>;
+    attachDecisionProviderResolver?(resolve: (id: string) => DecisionProviderAdapter): void;
     restoreSessionDoc?(sessionDoc: SessionDocument<State>): Promise<SessionDocument<State> | null>;
 }
 export declare class GraphRegistry {

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

@@ -1,4 +1,4 @@
-import { type BaseMessage } from '@langchain/core/messages';
+import { type BaseMessage } from "@langchain/core/messages";
 type MessageState = {
     messages: BaseMessage[];
 };

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

@@ -1,6 +1,7 @@
-import type { BaseMessage } from '@langchain/core/messages';
-import { type GraphNodeStates } from './node-state.js';
-import { type TokenUsage } from './token-usage.js';
+import type { BaseMessage } from "@langchain/core/messages";
+import { type GraphNodeStates } from "./node-state.js";
+import { type TokenUsage } from "./token-usage.js";
+import { type DecisionUsage } from "./decision/decision-types.js";
 export declare const GRAPH_END_NODE: "end";
 export type GraphState<CurrentNode extends string = string, Nodes extends object = GraphNodeStates> = {
     histories: Record<string, BaseMessage[]>;
@@ -8,10 +9,10 @@ export type GraphState<CurrentNode extends string = string, Nodes extends object
     config: Record<string, unknown>;
     nodes: Nodes;
     tokens: TokenUsage;
+    decisionUsage?: DecisionUsage;
     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>;
@@ -19,8 +20,8 @@ export declare function createGraphStateAnnotation<CurrentNode extends string =
     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>;
+    decisionUsage: import("@langchain/langgraph").BaseChannel<DecisionUsage, DecisionUsage | import("@langchain/langgraph").OverwriteValue<DecisionUsage>, 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/langchain-provider.adapter.d.ts

@@ -1,4 +1,4 @@
-import type { GraphLlmConfig, ModelProviderInitialization } from './graph-llm.config.js';
-import { type RegisteredModelProviderAdapter } from './model-provider.js';
+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;