@picoflow/ezgraph 0.0.6 → 0.0.8

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

@@ -1,7 +1,7 @@
-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';
+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;

package/dist/types/src/framework/model-stop-reason.d.ts

@@ -1,5 +1,5 @@
-import { AIMessage } from '@langchain/core/messages';
-export type ModelStopCategory = 'complete' | 'blocked' | 'truncated' | 'malformed_tool_call' | 'unspecified';
+import { AIMessage } from "@langchain/core/messages";
+export type ModelStopCategory = "complete" | "blocked" | "truncated" | "malformed_tool_call" | "unspecified";
 export type ModelStopReason = Readonly<{
     category: ModelStopCategory;
     provider?: string;

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

@@ -0,0 +1,12 @@
+import type { BaseMessage } from "@langchain/core/messages";
+import type { GraphState } from "./graph-state.js";
+export declare function hasNodeInvocation(owner: object): boolean;
+export declare function withNodeInvocation<State extends GraphState, Result>(owner: object, nodeId: string, state: State, run: () => Promise<Result>): Promise<Result>;
+export declare function invocationNodeId(owner: object): string;
+export declare function invocationNodeState(owner: object, nodeId: string): Record<string, unknown>;
+export declare function saveInvocationNodeState(owner: object, nodeId: string, patch: Record<string, unknown>): void;
+export declare function replaceInvocationNodeState(owner: object, nodeId: string, value: Record<string, unknown>): void;
+export declare function appendInvocationHistory(owner: object, space: string, messages: readonly BaseMessage[]): void;
+export declare function invocationHistory(owner: object, space: string): BaseMessage[];
+export declare function invocationGraphState<State extends GraphState>(owner: object): State;
+export declare function invocationUpdate<State extends GraphState>(owner: object): Partial<State>;

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

@@ -1,6 +1,4 @@
-import { HumanMessage, type BaseMessage } from '@langchain/core/messages';
-import { END } from '@langchain/langgraph';
-import type { GraphState } from './graph-state.js';
+import type { GraphState } from "./graph-state.js";
 export declare const GRAPH_NODE_LOCAL_STATE: unique symbol;
 export type GraphNodeTarget<LocalState extends object = object> = {
     readonly name: string;
@@ -9,33 +7,6 @@ export type GraphNodeTarget<LocalState extends object = object> = {
         readonly [GRAPH_NODE_LOCAL_STATE]: LocalState;
     };
 };
-export type GraphNodeLocalState<NodeClass extends GraphNodeTarget> = NodeClass['prototype'][typeof GRAPH_NODE_LOCAL_STATE];
+export type GraphNodeLocalState<NodeClass extends GraphNodeTarget> = NodeClass["prototype"][typeof GRAPH_NODE_LOCAL_STATE];
 export type GraphNodeUpdate<State extends GraphState> = Partial<State>;
-export type OutcomeRouteTarget = GraphNodeTarget | typeof END;
-export declare const OUTCOME_ROUTE_TARGET: unique symbol;
-type OutcomeState<State extends GraphState> = Pick<State, 'histories' | 'currentNode'>;
-export type NodeOutcomeBuilder<State extends GraphState, LocalState extends object, CanForwardInput extends boolean = false> = Readonly<GraphNodeUpdate<State>> & {
-    withState(patch: Partial<LocalState>): NodeOutcomeBuilder<State, LocalState, CanForwardInput>;
-    withStateFor<NodeClass extends GraphNodeTarget>(NodeClass: NodeClass, patch: Partial<GraphNodeLocalState<NodeClass>>): NodeOutcomeBuilder<State, LocalState, CanForwardInput>;
-    withHistory(space: string, messages: BaseMessage | readonly BaseMessage[]): NodeOutcomeBuilder<State, LocalState, CanForwardInput>;
-    via<NodeClass extends GraphNodeTarget>(NodeClass: NodeClass): NodeOutcomeBuilder<State, LocalState, CanForwardInput>;
-} & (CanForwardInput extends true ? {
-    forwardInput(state: OutcomeState<State>, fallbackMessage?: string): NodeOutcomeBuilder<State, LocalState>;
-} : object);
-type BuilderOptions<State extends GraphState, LocalState extends object, CanForwardInput extends boolean> = Readonly<{
-    update: GraphNodeUpdate<State>;
-    nodeName: string;
-    saveNode: (nodeName: string, patch: Record<string, unknown>) => GraphNodeUpdate<State>;
-    forwardInput?: (state: OutcomeState<State>, fallbackMessage?: string) => GraphNodeUpdate<State>;
-    routeTarget: OutcomeRouteTarget;
-}>;
-export declare function createNodeOutcomeBuilder<State extends GraphState, LocalState extends object, CanForwardInput extends boolean>(options: BuilderOptions<State, LocalState, CanForwardInput>): NodeOutcomeBuilder<State, LocalState, CanForwardInput>;
-export declare function outcomeRouteTarget(update: GraphNodeUpdate<GraphState>): OutcomeRouteTarget | undefined;
-export declare function preserveOutcomeRouteTarget<State extends GraphState, Update extends GraphNodeUpdate<State>>(source: GraphNodeUpdate<State>, update: Update): Update;
-export declare function forwardedHistoryUpdate<State extends GraphState>(options: {
-    sourceSpace: string;
-    targetSpace: string;
-    latestInput?: HumanMessage;
-    fallbackMessage?: string;
-}): GraphNodeUpdate<State>;
-export {};
+export declare function combineGraphNodeUpdates<State extends GraphState>(current: GraphNodeUpdate<State>, addition: GraphNodeUpdate<State>): GraphNodeUpdate<State>;

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

@@ -1,6 +1,7 @@
-import type { GraphLlmModelMetadata } from './graph-llm.config.js';
+import type { GraphLlmModelMetadata } from "./graph-llm.config.js";
 export type NodeStateValue<T extends object = Record<string, unknown>> = T & {
     model?: GraphLlmModelMetadata | undefined;
 };
 export type GraphNodeStates = Record<string, NodeStateValue>;
-export declare function mergeNodeStates<NodeStates extends object>(current: NodeStates, update: NodeStates): NodeStates;
+export declare function replaceNodeStates<NodeStates extends object>(current: NodeStates, update: Partial<NodeStates>): NodeStates;
+export declare const mergeNodeStates: typeof replaceNodeStates;

package/dist/types/src/framework/openai-auth-provider.d.ts

@@ -1,4 +1,4 @@
-import type { GraphLlmConfig, ModelProviderInitialization } from './graph-llm.config.js';
+import type { GraphLlmConfig, ModelProviderInitialization } from "./graph-llm.config.js";
 export declare const OPENAI_AUTH_PROVIDER = "openai-auth";
 export type OpenAIAuthCredentials = Readonly<{
     accessToken: string;

package/dist/types/src/framework/persistence/session-manager.d.ts

@@ -4,6 +4,7 @@ import { type GraphState } from '../graph-state.js';
 import { type GraphLlmConfig, type GraphLlmModelMetadata } from '../graph-llm.config.js';
 import { type SessionLogs } from '../session-log.js';
 import { type TokenUsage } from '../token-usage.js';
+import { type DecisionUsage } from '../decision/decision-types.js';
 export declare const SESSION_DOCUMENT_VERSION = 16;
 export declare const SESSION_BUSY = "SESSION_BUSY";
 export declare const SESSION_CONFLICT = "SESSION_CONFLICT";
@@ -33,6 +34,7 @@ export type BeginTurnResult<State extends GraphState = GraphState> = Readonly<{
 export type SessionWriteOptions = Readonly<{
     owner?: string;
     expectedRevision?: number;
+    keepTurn?: boolean;
 }>;
 export type SessionGraphStatus = 'in_progress' | 'completed' | 'error';
 export type SessionGraphDocument<State extends GraphState = GraphState> = {
@@ -50,8 +52,10 @@ export type SessionDocument<State extends GraphState = GraphState> = {
     revision: number;
     status: SessionGraphStatus;
     tokens: TokenUsage;
+    decisionUsage?: DecisionUsage;
     errors: SessionLogs['errors'];
     warnings: SessionLogs['warnings'];
+    decisions?: SessionLogs['decisions'];
     graph: SessionGraphDocument<State>;
     turn?: SessionTurnLease;
     createdAt: string;

package/dist/types/src/framework/session-log.d.ts

@@ -1,11 +1,41 @@
+import type { DecisionFailure, DecisionUsage } from "./decision/decision-types.js";
 export type SessionLogEntry = Record<string, unknown> & {
     createdAt: string;
 };
 export type SessionLogs = {
     errors: SessionLogEntry[];
     warnings: SessionLogEntry[];
+    decisions: DecisionAuditEntry[];
+};
+export type DecisionAuditOutcome = "success" | "fallback" | "decision_handler_failed" | "fallback_handler_failed";
+export type DecisionAuditEntry = SessionLogEntry & {
+    node: string;
+    provider: string;
+    configuredModel: string;
+    actualModel?: string;
+    outcome: DecisionAuditOutcome;
+    failure?: DecisionFailure;
+    attempts: number;
+    durationMs: number;
+    requestId?: string;
+    usage: DecisionUsage;
+};
+export type DecisionAuditInput = {
+    node: string;
+    provider: string;
+    configuredModel: string;
+    actualModel?: string;
+    outcome: DecisionAuditOutcome;
+    failure?: DecisionFailure;
+    attempts: number;
+    durationMs: number;
+    requestId?: string;
+    usage: DecisionUsage;
 };
 export declare function createSessionLogs(): SessionLogs;
+export declare function drainSessionLogs(logs: SessionLogs): SessionLogs;
+export declare function restoreSessionLogs(logs: SessionLogs, drained: SessionLogs): void;
 export declare function withSessionLogs<T>(logs: SessionLogs, callback: () => Promise<T>): Promise<T>;
 export declare function SessionLogError(tree: Record<string, unknown>, logs?: SessionLogs | undefined): void;
 export declare function SessionLogWarning(tree: Record<string, unknown>, logs?: SessionLogs | undefined): void;
+export declare function SessionLogDecision(entry: DecisionAuditInput, logs?: SessionLogs | undefined): DecisionAuditEntry | undefined;

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

@@ -1,11 +1,10 @@
-import { END, type ExtractStateType, type ExtractUpdateType, START, type StateDefinitionInit } from '@langchain/langgraph';
-import { GRAPH_NODE_CLASS } from './graph-node.js';
+import { type Command, END, type ExtractStateType, type ExtractUpdateType, START, type StateDefinitionInit } from "@langchain/langgraph";
+import { GRAPH_NODE_CLASS } from "./graph-node.js";
 export type RegisteredNode<State, Update> = {
     readonly id: string;
-    readonly invoke: (state: State) => Promise<Update>;
+    readonly invoke: (state: State) => Promise<Update | Command<unknown, Update & Record<string, unknown>, string>>;
     route(state: State): string;
     validateTools?(): void;
-    readonly supportsAutomaticOutcomeRouting?: boolean;
 };
 export type GraphNodeClass = {
     readonly name: string;
@@ -22,7 +21,7 @@ export type CurrentNodeBranchOptions = Readonly<{
     }[];
     otherwise: GraphEndpoint;
 }>;
-type RouteOf<NodeClass extends GraphNodeClass> = NodeClass['prototype'] extends {
+type RouteOf<NodeClass extends GraphNodeClass> = NodeClass["prototype"] extends {
     route(...args: never[]): infer Route;
 } ? Extract<Route, string> : never;
 type BranchDestinations<NodeClass extends GraphNodeClass, Destinations extends Readonly<Record<RouteOf<NodeClass>, GraphEndpoint>>> = Destinations & Record<Exclude<keyof Destinations, RouteOf<NodeClass>>, never>;
@@ -33,10 +32,7 @@ export declare class StateGraphExt<StateDefinition extends StateDefinitionInit>
     private readonly graph;
     private readonly addedNodeIds;
     private readonly nodeClasses;
-    private readonly explicitConditionalNodeIds;
     private readonly nodeInstances;
-    private automaticOutcomeRoutingRequested;
-    private automaticOutcomeRoutesAdded;
     constructor(state: StateDefinition, createGraphNode?: GraphNodeFactory<ExtractStateType<StateDefinition>, ExtractUpdateType<StateDefinition>> | undefined, endNode?: string);
     addNode(NodeClass: GraphNodeClass): this;
     nodes(...NodeClasses: readonly GraphNodeClass[]): this;
@@ -44,12 +40,10 @@ export declare class StateGraphExt<StateDefinition extends StateDefinitionInit>
     addEdge(source: GraphEndpoint | readonly GraphEndpoint[], target: GraphEndpoint): this;
     branch<NodeClass extends GraphNodeClass, Destinations extends Readonly<Record<RouteOf<NodeClass>, GraphEndpoint>>>(NodeClass: NodeClass, destinations: BranchDestinations<NodeClass, Destinations>): this;
     branchBy(NodeClass: GraphNodeClass, options: CurrentNodeBranchOptions): this;
-    configAutoRoute(): this;
     registerTurns(...NodeClasses: readonly GraphNodeClass[]): this;
     compile(): import("@langchain/langgraph").CompiledStateGraph<ExtractStateType<StateDefinition, StateDefinition> extends infer T ? { [K in keyof T]: T[K]; } : never, ExtractUpdateType<StateDefinition, StateDefinition> extends infer T_1 ? { [K_1 in keyof T_1]: T_1[K_1]; } : never, string, StateDefinition extends import("@langchain/langgraph").AnyStateSchema ? StateDefinition : StateDefinition extends StateDefinitionInit ? import("@langchain/langgraph").ToStateDefinition<StateDefinition> : import("@langchain/langgraph").StateDefinition, StateDefinition extends import("@langchain/langgraph").AnyStateSchema ? StateDefinition : StateDefinition extends StateDefinitionInit ? import("@langchain/langgraph").ToStateDefinition<StateDefinition> : import("@langchain/langgraph").StateDefinition, import("@langchain/langgraph").StateDefinition, unknown, unknown, unknown, []>;
     private addConditionalEdge;
     private registerNode;
-    private addAutomaticOutcomeRoutes;
     private assertSource;
     private assertTarget;
     private assertAddedNode;

package/dist/types/src/framework/token-usage.d.ts

@@ -1,4 +1,4 @@
-import { ModelCatalog, type GraphLlmConfig, type GraphLlmParameters } from './graph-llm.config.js';
+import { ModelCatalog, type GraphLlmConfig, type GraphLlmParameters } from "./graph-llm.config.js";
 export type TokenUsage = {
     input_tokens: number;
     output_tokens: number;
@@ -14,7 +14,7 @@ export type ModelResult<T> = {
 };
 export type ModelExecution = {
     model: string;
-    family: ReturnType<typeof ModelCatalog.resolveModelDescriptor>['family'];
+    family: ReturnType<typeof ModelCatalog.resolveModelDescriptor>["family"];
     parameters: GraphLlmParameters;
 };
 export declare function modelExecution(config: GraphLlmConfig): ModelExecution;

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

@@ -0,0 +1,29 @@
+import type { BaseMessage } from "@langchain/core/messages";
+import type { GraphNodeLocalState, GraphNodeTarget } from "./node-outcome.js";
+import type { TokenUsage } from "./token-usage.js";
+export type ToolResponseKind = "go" | "stay" | "direct" | "directTo" | "finish";
+export type ToolResponse = Readonly<{
+    kind: ToolResponseKind;
+    target?: GraphNodeTarget;
+    feedback?: string;
+    state?: Record<string, unknown>;
+    message?: BaseMessage;
+    messages?: readonly BaseMessage[];
+    cleanup?: () => Promise<void>;
+    response?: string;
+    usage?: TokenUsage;
+}>;
+export type ToolResponseBuilder<NodeClass extends GraphNodeTarget> = ToolResponse & {
+    withState(state: Partial<GraphNodeLocalState<NodeClass>>): ToolResponseBuilder<NodeClass>;
+    withMessage(message: BaseMessage): ToolResponseBuilder<NodeClass>;
+    withMessages(messages: readonly BaseMessage[]): ToolResponseBuilder<NodeClass>;
+    withCleanup(cleanup: () => Promise<void>): ToolResponseBuilder<NodeClass>;
+    withToolFeedback(feedback: string): ToolResponseBuilder<NodeClass>;
+    withUsage(usage: TokenUsage): ToolResponseBuilder<NodeClass>;
+};
+export declare function go<NodeClass extends GraphNodeTarget>(target: NodeClass): ToolResponseBuilder<NodeClass>;
+export declare function stay(feedback?: string): ToolResponseBuilder<GraphNodeTarget>;
+export declare function direct(content: string | object): ToolResponseBuilder<GraphNodeTarget>;
+export declare function directTo<NodeClass extends GraphNodeTarget>(target: NodeClass, content: string | object): ToolResponseBuilder<NodeClass>;
+export declare function finish(content: string | object): ToolResponseBuilder<GraphNodeTarget>;
+export declare function isToolResponse(value: unknown): value is ToolResponse;

package/dist/types/src/testing/scripted-decisions.d.ts

@@ -0,0 +1,24 @@
+import type { DecisionAnswer, DecisionCallOptions, DecisionProviderAdapter, DecisionRequest, DecisionResult, DecisionTokenUsage } from '../framework/decision/decision-types.js';
+export type ScriptedDecisionCall = Readonly<{
+    request: DecisionRequest;
+    options: DecisionCallOptions;
+}>;
+export declare class ScriptedDecisions implements DecisionProviderAdapter {
+    readonly id: string;
+    private readonly turns;
+    private consumed;
+    readonly calls: ScriptedDecisionCall[];
+    constructor(id?: string);
+    answers(answers: Record<string, DecisionAnswer>, options?: Readonly<{
+        model?: string;
+        usage?: DecisionTokenUsage;
+        requestId?: string;
+    }>): this;
+    result(result: DecisionResult): this;
+    fail(error: Error | string): this;
+    get drained(): boolean;
+    get remaining(): number;
+    decide(request: DecisionRequest, options: DecisionCallOptions): Promise<DecisionResult>;
+    shouldRetry(error: Error): boolean;
+}
+export declare function scriptedDecisions(id?: string): ScriptedDecisions;

package/dist/types/src/testing/turn-harness.d.ts

@@ -2,6 +2,7 @@ import { GraphEngine, type GraphConstructor, type RunResult } from '../framework
 import type { GraphState } from '../framework/graph-state.js';
 import type { LlmGateway } from '../framework/llm-gateway.js';
 import type { SessionLogs } from '../framework/session-log.js';
+import type { DecisionProviderAdapter } from '../framework/decision/decision-types.js';
 import { SessionManager, type SessionDocument } from '../framework/persistence/session-manager.js';
 export type HarnessTurn<State extends GraphState> = Readonly<{
     status: number;
@@ -30,6 +31,7 @@ export type TurnHarness<State extends GraphState> = Readonly<{
 export declare function createTurnHarness<State extends GraphState = GraphState>(options: Readonly<{
     graph: GraphConstructor;
     gateway?: LlmGateway;
+    decisions?: DecisionProviderAdapter | readonly DecisionProviderAdapter[];
     sessionManager?: SessionManager;
     sessionId?: string;
 }>): TurnHarness<State>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picoflow/ezgraph",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Provider-neutral graph primitives built on LangGraph and LangChain.",
   "type": "module",
   "main": "./dist/index.js",
@@ -37,18 +37,19 @@
     "@azure/identity": "4.13.1",
     "@google/genai": "2.14.0",
     "dotenv": "17.4.2",
-    "@langchain/core": "1.2.3",
-    "@langchain/langgraph": "1.4.8",
-    "langchain": "1.5.4",
+    "@langchain/core": "1.2.12",
+    "@langchain/langgraph": "1.4.17",
+    "langchain": "1.5.12",
     "mongodb": "6.21.0",
     "openai": "7.1.0",
     "reflect-metadata": "0.2.2",
     "zod": "4.4.3"
   },
   "peerDependencies": {
-    "@langchain/anthropic": ">=1.5.2",
-    "@langchain/google": ">=0.2.1",
-    "@langchain/openai": ">=1.5.5"
+    "@langchain/anthropic": ">=1.5.11",
+    "@langchain/google": ">=0.2.7",
+    "@langchain/openai": ">=1.5.13",
+    "@langchain/typesafe": ">=0.0.1"
   },
   "peerDependenciesMeta": {
     "@langchain/anthropic": {
@@ -59,6 +60,9 @@
     },
     "@langchain/openai": {
       "optional": true
+    },
+    "@langchain/typesafe": {
+      "optional": true
     }
   }
 }

package/dist/framework/conversation-tool-result.js

@@ -1 +0,0 @@
-var i=Object.defineProperty;var n=(o,t)=>i(o,"name",{value:t,configurable:!0});const u=Symbol("TOOL_RESULT_EFFECTS");function p(o){return l({output:o},{context:[],stops:[]})}n(p,"createConversationToolResult");function b(o,t){const s=o[u];if(!s)return o;for(const e of s.context){const r=typeof e=="function"?e(t):e;if(!r||typeof r!="object"||Array.isArray(r))throw new Error("withContext() must produce an object patch.");Object.assign(t,r)}const a=s.stops.some(e=>typeof e=="function"?e(t):e);return{...o,...a?{stopAfterBatch:!0}:{}}}n(b,"resolveConversationToolResult");function l(o,t){const s={...o},a=n((e,r=t)=>l({...o,...e},r),"derive");return Object.defineProperties(s,{[u]:{enumerable:!1,value:t},withContext:{enumerable:!1,value:n(e=>a({},{...t,context:[...t.context,e]}),"value")},withMessages:{enumerable:!1,value:n(e=>{const r=Array.isArray(e)?[...e]:[e];return a({messages:[...o.messages??[],...r]})},"value")},withCleanup:{enumerable:!1,value:n(e=>a({cleanup:e}),"value")},haltAfterBatch:{enumerable:!1,value:n(()=>a({},{...t,stops:[...t.stops,!0]}),"value")},stopAfterBatchWhen:{enumerable:!1,value:n(e=>a({},{...t,stops:[...t.stops,e]}),"value")}}),s}n(l,"createBuilder");export{p as createConversationToolResult,b as resolveConversationToolResult};

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

@@ -1,19 +0,0 @@
-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 {};