@agentforge/core 0.16.51 → 0.16.52

package/dist/index.cjs

@@ -2107,8 +2107,10 @@ function createToolSimulator(config) {
   };
 }
 
-// src/langgraph/state.ts
+// src/langgraph/state-annotation.ts
 var import_langgraph = require("@langchain/langgraph");
+
+// src/langgraph/state-shared.ts
 function entriesOf(value) {
   return Object.entries(value);
 }
@@ -2127,6 +2129,8 @@ function setStateValue(target, key, value) {
 function setStateDefinitionValue(target, key, value) {
   target[key] = value;
 }
+
+// src/langgraph/state-annotation.ts
 function createChannel(channelConfig) {
   if (channelConfig.reducer) {
     return (0, import_langgraph.Annotation)({
@@ -2153,6 +2157,8 @@ function createStateAnnotation(config) {
   }
   return import_langgraph.Annotation.Root(stateDefinition);
 }
+
+// src/langgraph/state-validation.ts
 function validateState(state, config) {
   const validated = {};
   for (const [key, channelConfig] of entriesOf(config)) {
@@ -2170,6 +2176,8 @@ function validateState(state, config) {
   }
   return validated;
 }
+
+// src/langgraph/state-merge.ts
 function mergeState(currentState, update, config) {
   const merged = { ...currentState };
   for (const key of keysOf(update)) {

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { z, ZodTypeAny, output, ZodType, ZodTypeDef } from 'zod';
 import * as _langchain_core_tools from '@langchain/core/tools';
 import { DynamicStructuredTool } from '@langchain/core/tools';
 import * as _langchain_langgraph from '@langchain/langgraph';
-import { AnnotationRoot, BaseChannel, StateDefinition, UpdateType, StateGraph, END, MemorySaver, BaseCheckpointSaver, CheckpointTuple } from '@langchain/langgraph';
+import { BaseChannel, AnnotationRoot, StateDefinition, UpdateType, StateGraph, END, MemorySaver, BaseCheckpointSaver, CheckpointTuple } from '@langchain/langgraph';
 import { RunnableConfig } from '@langchain/core/runnables';
 
 /**
@@ -1093,15 +1093,6 @@ declare function getToolJsonSchema<TInput, TOutput>(tool: Tool<TInput, TOutput>)
  */
 declare function getToolDescription<TInput, TOutput>(tool: Tool<TInput, TOutput>): string;
 
-/**
- * LangGraph State Utilities
- *
- * Type-safe helpers for working with LangGraph state management.
- * These utilities wrap LangGraph's Annotation API to provide better TypeScript ergonomics.
- *
- * @module langgraph/state
- */
-
 /**
  * State channel configuration with optional Zod schema validation
  */
@@ -1150,6 +1141,16 @@ type ReducerUpdate<TChannel extends StateChannelConfigLike> = TChannel extends {
 } ? TUpdate : never;
 type ChannelValue<TChannel extends StateChannelConfigLike> = HasReducer<TChannel> extends true ? ReducerValue<TChannel> : [SchemaValue<TChannel>] extends [never] ? [DefaultValue<TChannel>] extends [never] ? unknown : DefaultValue<TChannel> : SchemaValue<TChannel>;
 type ChannelUpdate<TChannel extends StateChannelConfigLike> = HasReducer<TChannel> extends true ? ReducerUpdate<TChannel> : ChannelValue<TChannel>;
+type SchemaMatchesValue<TChannel extends StateChannelConfigLike> = [
+    SchemaValue<TChannel>
+] extends [never] ? true : [ChannelValue<TChannel>] extends [SchemaValue<TChannel>] ? true : false;
+type DefaultMatchesValue<TChannel extends StateChannelConfigLike> = [
+    DefaultValue<TChannel>
+] extends [never] ? true : [DefaultValue<TChannel>] extends [ChannelValue<TChannel>] ? true : false;
+type ValidStateChannel<TChannel extends StateChannelConfigLike> = HasReducer<TChannel> extends true ? [ChannelValue<TChannel>] extends [never] ? never : SchemaMatchesValue<TChannel> extends true ? DefaultMatchesValue<TChannel> extends true ? TChannel : never : never : TChannel;
+type ValidStateConfig<TConfig extends StateConfigMap> = {
+    [K in keyof TConfig]: ValidStateChannel<TConfig[K]>;
+};
 type StateShape<TConfig extends StateConfigMap> = {
     [K in keyof TConfig]: ChannelValue<TConfig[K]>;
 };
@@ -1169,6 +1170,7 @@ type InputStateKeys<TConfig extends StateConfigMap, TState> = Extract<keyof TCon
 type ValidatedState<TConfig extends StateConfigMap, TState extends Partial<Record<keyof TConfig, unknown>>> = {
     [K in InputStateKeys<TConfig, TState> | DefaultedKeys<TConfig>]: ChannelValue<TConfig[K]>;
 };
+
 /**
  * Create a type-safe state annotation with optional Zod validation
  *
@@ -1176,75 +1178,16 @@ type ValidatedState<TConfig extends StateConfigMap, TState extends Partial<Recor
  * - Zod schema validation support
  * - Better TypeScript inference
  * - Documentation/description support
- *
- * @example
- * ```typescript
- * import { createStateAnnotation } from '@agentforge/core';
- * import { z } from 'zod';
- *
- * const AgentState = createStateAnnotation({
- *   messages: {
- *     schema: z.array(z.string()),
- *     reducer: (left, right) => [...left, ...right],
- *     default: () => [],
- *     description: 'Chat messages'
- *   },
- *   context: {
- *     schema: z.record(z.any()),
- *     default: () => ({}),
- *     description: 'Agent context'
- *   }
- * });
- *
- * type State = typeof AgentState.State;
- * ```
  */
-declare function createStateAnnotation<TConfig extends StateConfigMap>(config: TConfig): AnnotationRoot<StateAnnotationDefinition<TConfig>>;
+declare function createStateAnnotation<TConfig extends StateConfigMap>(config: ValidStateConfig<TConfig>): AnnotationRoot<StateAnnotationDefinition<TConfig>>;
+
 /**
  * Validate state against Zod schemas
- *
- * @param state - The state object to validate
- * @param config - The state channel configuration with schemas
- * @returns Validated state
- * @throws {z.ZodError} If validation fails
- *
- * @example
- * ```typescript
- * const config = {
- *   messages: { schema: z.array(z.string()) },
- *   count: { schema: z.number() }
- * };
- *
- * const validatedState = validateState(
- *   { messages: ['hello'], count: 42 },
- *   config
- * );
- * ```
  */
 declare function validateState<TConfig extends StateConfigMap, TState extends Partial<Record<keyof TConfig, unknown>>>(state: TState, config: TConfig): ValidatedState<TConfig, TState>;
+
 /**
  * Merge state updates using configured reducers
- *
- * @param currentState - Current state
- * @param update - State update
- * @param config - State channel configuration
- * @returns Merged state
- *
- * @example
- * ```typescript
- * const config = {
- *   messages: {
- *     reducer: (left, right) => [...left, ...right]
- *   }
- * };
- *
- * const merged = mergeState(
- *   { messages: ['a', 'b'] },
- *   { messages: ['c'] },
- *   config
- * );
- * // Result: { messages: ['a', 'b', 'c'] }
- * ```
  */
 declare function mergeState<TConfig extends StateConfigMap>(currentState: Partial<StateShape<TConfig>>, update: StateUpdateShape<TConfig>, config: TConfig): Partial<StateShape<TConfig>>;
 

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { z, ZodTypeAny, output, ZodType, ZodTypeDef } from 'zod';
 import * as _langchain_core_tools from '@langchain/core/tools';
 import { DynamicStructuredTool } from '@langchain/core/tools';
 import * as _langchain_langgraph from '@langchain/langgraph';
-import { AnnotationRoot, BaseChannel, StateDefinition, UpdateType, StateGraph, END, MemorySaver, BaseCheckpointSaver, CheckpointTuple } from '@langchain/langgraph';
+import { BaseChannel, AnnotationRoot, StateDefinition, UpdateType, StateGraph, END, MemorySaver, BaseCheckpointSaver, CheckpointTuple } from '@langchain/langgraph';
 import { RunnableConfig } from '@langchain/core/runnables';
 
 /**
@@ -1093,15 +1093,6 @@ declare function getToolJsonSchema<TInput, TOutput>(tool: Tool<TInput, TOutput>)
  */
 declare function getToolDescription<TInput, TOutput>(tool: Tool<TInput, TOutput>): string;
 
-/**
- * LangGraph State Utilities
- *
- * Type-safe helpers for working with LangGraph state management.
- * These utilities wrap LangGraph's Annotation API to provide better TypeScript ergonomics.
- *
- * @module langgraph/state
- */
-
 /**
  * State channel configuration with optional Zod schema validation
  */
@@ -1150,6 +1141,16 @@ type ReducerUpdate<TChannel extends StateChannelConfigLike> = TChannel extends {
 } ? TUpdate : never;
 type ChannelValue<TChannel extends StateChannelConfigLike> = HasReducer<TChannel> extends true ? ReducerValue<TChannel> : [SchemaValue<TChannel>] extends [never] ? [DefaultValue<TChannel>] extends [never] ? unknown : DefaultValue<TChannel> : SchemaValue<TChannel>;
 type ChannelUpdate<TChannel extends StateChannelConfigLike> = HasReducer<TChannel> extends true ? ReducerUpdate<TChannel> : ChannelValue<TChannel>;
+type SchemaMatchesValue<TChannel extends StateChannelConfigLike> = [
+    SchemaValue<TChannel>
+] extends [never] ? true : [ChannelValue<TChannel>] extends [SchemaValue<TChannel>] ? true : false;
+type DefaultMatchesValue<TChannel extends StateChannelConfigLike> = [
+    DefaultValue<TChannel>
+] extends [never] ? true : [DefaultValue<TChannel>] extends [ChannelValue<TChannel>] ? true : false;
+type ValidStateChannel<TChannel extends StateChannelConfigLike> = HasReducer<TChannel> extends true ? [ChannelValue<TChannel>] extends [never] ? never : SchemaMatchesValue<TChannel> extends true ? DefaultMatchesValue<TChannel> extends true ? TChannel : never : never : TChannel;
+type ValidStateConfig<TConfig extends StateConfigMap> = {
+    [K in keyof TConfig]: ValidStateChannel<TConfig[K]>;
+};
 type StateShape<TConfig extends StateConfigMap> = {
     [K in keyof TConfig]: ChannelValue<TConfig[K]>;
 };
@@ -1169,6 +1170,7 @@ type InputStateKeys<TConfig extends StateConfigMap, TState> = Extract<keyof TCon
 type ValidatedState<TConfig extends StateConfigMap, TState extends Partial<Record<keyof TConfig, unknown>>> = {
     [K in InputStateKeys<TConfig, TState> | DefaultedKeys<TConfig>]: ChannelValue<TConfig[K]>;
 };
+
 /**
  * Create a type-safe state annotation with optional Zod validation
  *
@@ -1176,75 +1178,16 @@ type ValidatedState<TConfig extends StateConfigMap, TState extends Partial<Recor
  * - Zod schema validation support
  * - Better TypeScript inference
  * - Documentation/description support
- *
- * @example
- * ```typescript
- * import { createStateAnnotation } from '@agentforge/core';
- * import { z } from 'zod';
- *
- * const AgentState = createStateAnnotation({
- *   messages: {
- *     schema: z.array(z.string()),
- *     reducer: (left, right) => [...left, ...right],
- *     default: () => [],
- *     description: 'Chat messages'
- *   },
- *   context: {
- *     schema: z.record(z.any()),
- *     default: () => ({}),
- *     description: 'Agent context'
- *   }
- * });
- *
- * type State = typeof AgentState.State;
- * ```
  */
-declare function createStateAnnotation<TConfig extends StateConfigMap>(config: TConfig): AnnotationRoot<StateAnnotationDefinition<TConfig>>;
+declare function createStateAnnotation<TConfig extends StateConfigMap>(config: ValidStateConfig<TConfig>): AnnotationRoot<StateAnnotationDefinition<TConfig>>;
+
 /**
  * Validate state against Zod schemas
- *
- * @param state - The state object to validate
- * @param config - The state channel configuration with schemas
- * @returns Validated state
- * @throws {z.ZodError} If validation fails
- *
- * @example
- * ```typescript
- * const config = {
- *   messages: { schema: z.array(z.string()) },
- *   count: { schema: z.number() }
- * };
- *
- * const validatedState = validateState(
- *   { messages: ['hello'], count: 42 },
- *   config
- * );
- * ```
  */
 declare function validateState<TConfig extends StateConfigMap, TState extends Partial<Record<keyof TConfig, unknown>>>(state: TState, config: TConfig): ValidatedState<TConfig, TState>;
+
 /**
  * Merge state updates using configured reducers
- *
- * @param currentState - Current state
- * @param update - State update
- * @param config - State channel configuration
- * @returns Merged state
- *
- * @example
- * ```typescript
- * const config = {
- *   messages: {
- *     reducer: (left, right) => [...left, ...right]
- *   }
- * };
- *
- * const merged = mergeState(
- *   { messages: ['a', 'b'] },
- *   { messages: ['c'] },
- *   config
- * );
- * // Result: { messages: ['a', 'b', 'c'] }
- * ```
  */
 declare function mergeState<TConfig extends StateConfigMap>(currentState: Partial<StateShape<TConfig>>, update: StateUpdateShape<TConfig>, config: TConfig): Partial<StateShape<TConfig>>;
 

package/dist/index.js

@@ -1932,8 +1932,10 @@ function createToolSimulator(config) {
   };
 }
 
-// src/langgraph/state.ts
+// src/langgraph/state-annotation.ts
 import { Annotation } from "@langchain/langgraph";
+
+// src/langgraph/state-shared.ts
 function entriesOf(value) {
   return Object.entries(value);
 }
@@ -1952,6 +1954,8 @@ function setStateValue(target, key, value) {
 function setStateDefinitionValue(target, key, value) {
   target[key] = value;
 }
+
+// src/langgraph/state-annotation.ts
 function createChannel(channelConfig) {
   if (channelConfig.reducer) {
     return Annotation({
@@ -1978,6 +1982,8 @@ function createStateAnnotation(config) {
   }
   return Annotation.Root(stateDefinition);
 }
+
+// src/langgraph/state-validation.ts
 function validateState(state, config) {
   const validated = {};
   for (const [key, channelConfig] of entriesOf(config)) {
@@ -1995,6 +2001,8 @@ function validateState(state, config) {
   }
   return validated;
 }
+
+// src/langgraph/state-merge.ts
 function mergeState(currentState, update, config) {
   const merged = { ...currentState };
   for (const key of keysOf(update)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge/core",
-  "version": "0.16.51",
+  "version": "0.16.52",
   "description": "Production-ready TypeScript agent framework built on LangGraph with orchestration, middleware, and typed abstractions.",
   "type": "module",
   "main": "./dist/index.cjs",