@relkit/langchain 0.0.0-stage → 0.7.11

package/dist/define-graph-node.js

@@ -0,0 +1,97 @@
+/** Creates typed native graph node descriptors from author callbacks and records their execution metadata for later graph compilation. */
+import { normalizeId } from "@relkit/contracts";
+import { Effect } from "effect";
+import { observeAgent } from "@relkit/agents/internal/agent-telemetry";
+import { isAgentSchemaEffect } from "@relkit/agents/internal/agent-validation-schema";
+import { validateGraphNodeSchemasEffect } from "./graph-node-schema-validation.js";
+import { isRecordEffect } from "@relkit/agents/internal/agent-validation-value";
+import { graphNodeValidationFailure } from "./graph-node-validation-error.js";
+import { copyGraphNodeEndsEffect, validateGraphNodeResultEffect, validatedGraphNodeInputEffect, } from "./graph-node-validation.js";
+import { RELKIT_GRAPH_NODE } from "./graph-node-symbol.js";
+export { assertGraphNodeDestinations } from "./graph-node-validation.js";
+/** Runs input validation, the user handler, and output validation in one Effect.
+ * @param options - The node schemas and user implementation.
+ * @param ends - Validated dynamic destinations.
+ * @param input - Candidate node input.
+ * @param config - LangGraph runnable configuration.
+ * @returns A validated node result or GraphNodeValidationFailure.
+ * @example await Effect.runPromise(runGraphNodeHandlerEffect(options, [], input));
+ */
+export const runGraphNodeHandlerEffect = Effect.fn("Agents.graphNode.handle")(function* (options, ends, input, config) {
+    const projectedInput = yield* validatedGraphNodeInputEffect(options.input, input);
+    const result = yield* Effect.tryPromise({
+        try: () => Promise.resolve(options.handler(projectedInput, config)),
+        catch: graphNodeValidationFailure,
+    });
+    return yield* validateGraphNodeResultEffect(options.output, ends, result);
+}, (effect) => observeAgent("graph-node.handle", effect));
+/** Defines a native LangGraph node with RELKIT schemas and declared dynamic routes.
+ * @param options - Node identity, schemas, destinations, and implementation.
+ * @returns An Effect with an immutable descriptor or GraphNodeValidationFailure.
+ * @example Effect.runSync(defineGraphNodeEffect({ id: "step", input, output, handler }));
+ */
+export const defineGraphNodeEffect = Effect.fn("Agents.graphNode.define")(function* (options) {
+    if (!(yield* isRecordEffect(options))) {
+        return yield* Effect.fail(graphNodeValidationFailure(new TypeError("Graph node options must be an object")));
+    }
+    yield* validateGraphNodeSchemasEffect(options);
+    if (typeof options.handler !== "function") {
+        return yield* Effect.fail(graphNodeValidationFailure(new TypeError("Graph node handler is required")));
+    }
+    const id = yield* Effect.try({
+        try: () => normalizeId(options.id),
+        catch: graphNodeValidationFailure,
+    });
+    const ends = (yield* copyGraphNodeEndsEffect(options.ends));
+    const handler = (input, config) => Effect.runPromise(runGraphNodeHandlerEffect(options, ends, input, config).pipe(Effect.catchTag("GraphNodeValidationFailure", (failure) => Effect.fail(failure.cause))));
+    return Object.freeze({
+        [RELKIT_GRAPH_NODE]: true,
+        kind: "graph-node",
+        id,
+        input: options.input,
+        output: options.output,
+        ...(options.resume === undefined ? {} : { resume: options.resume }),
+        ends,
+        handler,
+        ...(options.title === undefined ? {} : { title: options.title }),
+        ...(options.description === undefined ? {} : { description: options.description }),
+        ...(options.tags === undefined ? {} : { tags: Object.freeze([...options.tags]) }),
+    });
+}, (effect) => observeAgent("graph-node.define", effect));
+/** Defines a graph node for existing synchronous authoring callers.
+ * @param options - Node identity, schemas, destinations, and implementation.
+ * @returns An immutable graph node descriptor.
+ * @throws The original authoring error for invalid options.
+ * @example const node = defineGraphNode({ id: "step", input, output, handler });
+ */
+export function defineGraphNode(options) {
+    return Effect.runSync(defineGraphNodeEffect(options).pipe(Effect.catchTag("GraphNodeValidationFailure", (failure) => Effect.fail(failure.cause))));
+}
+/** Checks whether a value is a native graph node descriptor.
+ * @param value - Candidate descriptor.
+ * @returns An Effect with a boolean and no typed failure.
+ * @example Effect.runSync(isGraphNodeDescriptorEffect(value));
+ */
+export const isGraphNodeDescriptorEffect = Effect.fn("Agents.graphNode.isDescriptor")(function* (value) {
+    if (!(yield* isRecordEffect(value)))
+        return false;
+    const record = value;
+    return (record[RELKIT_GRAPH_NODE] === true &&
+        record.kind === "graph-node" &&
+        typeof record.id === "string" &&
+        Array.isArray(record.ends) &&
+        record.ends.every((destination) => typeof destination === "string") &&
+        (yield* isAgentSchemaEffect(record.input)) &&
+        (yield* isAgentSchemaEffect(record.output)) &&
+        (record.resume === undefined || (yield* isAgentSchemaEffect(record.resume))) &&
+        typeof record.handler === "function");
+}, (effect) => observeAgent("graph-node.is-descriptor", effect));
+/** Checks a graph node descriptor for existing synchronous callers.
+ * @param value - Candidate descriptor.
+ * @returns Whether the value is a native graph node descriptor.
+ * @example if (isGraphNodeDescriptor(value)) useNode(value);
+ */
+export function isGraphNodeDescriptor(value) {
+    return Effect.runSync(isGraphNodeDescriptorEffect(value));
+}
+//# sourceMappingURL=define-graph-node.js.map

package/dist/define-graph-node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-graph-node.js","sourceRoot":"","sources":["../src/define-graph-node.ts"],"names":[],"mappings":"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"}

package/dist/define-graph-node.types.d.ts

@@ -0,0 +1,38 @@
+/** Creates typed native graph node descriptors from author callbacks and records their execution metadata for later graph compilation. This companion preserves the native input and output types without starting runtime work. */
+import type { Command, LangGraphRunnableConfig } from "@langchain/langgraph";
+import type { DescriptorMetadata, MaybePromise } from "@relkit/contracts";
+import type { InferInput, InferOutput, StandardSchemaV1 } from "@relkit/schema";
+import type { RELKIT_GRAPH_NODE } from "./graph-node-symbol.js";
+type NodeUpdateInput<Schema extends StandardSchemaV1> = Extract<InferInput<Schema>, Record<string, unknown>>;
+type NodeUpdate<Schema extends StandardSchemaV1> = Extract<InferOutput<Schema>, Record<string, unknown>>;
+type CommandNodes<Ends extends readonly string[]> = Ends extends readonly [] ? string : Extract<Ends[number], string>;
+/** Validated graph node result or native routing command. */
+export type GraphNodeResult<OutputSchema extends StandardSchemaV1, Ends extends readonly string[]> = NodeUpdate<OutputSchema> | Command<unknown, NodeUpdate<OutputSchema>, CommandNodes<Ends>>;
+/** Validated handler stored on a graph node descriptor. */
+export type GraphNodeHandler<InputSchema extends StandardSchemaV1, OutputSchema extends StandardSchemaV1, Ends extends readonly string[]> = (input: InferOutput<InputSchema>, config?: LangGraphRunnableConfig) => MaybePromise<GraphNodeResult<OutputSchema, Ends>>;
+/** User implementation before RELKIT input and output validation. */
+export type GraphNodeImplementation<InputSchema extends StandardSchemaV1, OutputSchema extends StandardSchemaV1, Ends extends readonly string[]> = (input: InferOutput<InputSchema>, config?: LangGraphRunnableConfig) => MaybePromise<NodeUpdateInput<OutputSchema> | Command<unknown, NodeUpdateInput<OutputSchema>, CommandNodes<Ends>>>;
+/** Immutable native graph node descriptor. */
+export interface GraphNodeDescriptor<Id extends string = string, InputSchema extends StandardSchemaV1 = StandardSchemaV1, OutputSchema extends StandardSchemaV1 = StandardSchemaV1, ResumeSchema extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined, Ends extends readonly string[] = readonly string[]> extends DescriptorMetadata {
+    readonly [RELKIT_GRAPH_NODE]: true;
+    readonly kind: "graph-node";
+    readonly id: Id;
+    readonly input: InputSchema;
+    readonly output: OutputSchema;
+    readonly resume?: ResumeSchema;
+    readonly ends: Ends;
+    readonly handler: GraphNodeHandler<InputSchema, OutputSchema, Ends>;
+}
+/** Erased graph node descriptor for runtime validation. */
+export type GraphNodeAny = GraphNodeDescriptor<string, StandardSchemaV1, StandardSchemaV1, StandardSchemaV1 | undefined, readonly string[]>;
+/** Authoring options for a native LangGraph node. */
+export interface DefineGraphNodeOptions<Id extends string, InputSchema extends StandardSchemaV1, OutputSchema extends StandardSchemaV1, ResumeSchema extends StandardSchemaV1 | undefined, Ends extends readonly string[]> extends DescriptorMetadata {
+    readonly id: Id;
+    readonly input: InputSchema;
+    readonly output: OutputSchema;
+    readonly resume?: ResumeSchema;
+    readonly ends?: Ends;
+    readonly handler: GraphNodeImplementation<InputSchema, OutputSchema, Ends>;
+}
+export {};
+//# sourceMappingURL=define-graph-node.types.d.ts.map

package/dist/define-graph-node.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-graph-node.types.d.ts","sourceRoot":"","sources":["../src/define-graph-node.types.ts"],"names":[],"mappings":"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"}

package/dist/define-graph-node.types.js

@@ -0,0 +1,3 @@
+/** Creates typed native graph node descriptors from author callbacks and records their execution metadata for later graph compilation. This companion preserves the native input and output types without starting runtime work. */
+export {};
+//# sourceMappingURL=define-graph-node.types.js.map

package/dist/define-graph-node.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-graph-node.types.js","sourceRoot":"","sources":["../src/define-graph-node.types.ts"],"names":[],"mappings":"AAAA,oOAAoO"}

package/dist/define-graph.d.ts

@@ -0,0 +1,44 @@
+/** Exposes typed LangGraph authoring and delegates descriptor validation and construction before any graph execution can begin. */
+import type { AnyStateSchema } from "@langchain/langgraph";
+import type { StandardSchemaV1 } from "@relkit/schema";
+import { Effect } from "effect";
+import type { DefineGraphOptions, GraphDescriptor, GraphExecution, GraphNodeLike } from "./define-graph.types.js";
+export type * from "./define-graph.types.js";
+/** Defines an inspectable agent backed by native LangGraph.
+ * @param options - Graph state, nodes, edges, limits, and client policy.
+ * @returns An Effect with a frozen graph descriptor or GraphDefinitionFailure.
+ * @example Effect.runSync(defineGraphEffect({ id: "flow", state, input, output, nodes, edges, limits }));
+ */
+export declare const defineGraphEffect: <const Id extends string, const InputSchema extends StandardSchemaV1, const OutputSchema extends StandardSchemaV1, const State extends AnyStateSchema, const Nodes extends readonly GraphNodeLike[]>(options: DefineGraphOptions<Id, InputSchema, OutputSchema, State, Nodes>) => Effect.Effect<GraphDescriptor<Id, InputSchema, OutputSchema, State, Nodes>, import("./define-graph-error.js").GraphDefinitionFailure, never>;
+/** Defines a graph for existing synchronous authoring callers.
+ * @param options - Graph state, nodes, edges, limits, and client policy.
+ * @returns A frozen inspectable graph descriptor.
+ * @throws The original invalid graph authoring or identity error.
+ * @example const graph = defineGraph({ id: "flow", state, input, output, nodes, edges, limits });
+ */
+export declare function defineGraph<const Id extends string, const InputSchema extends StandardSchemaV1, const OutputSchema extends StandardSchemaV1, const State extends AnyStateSchema, const Nodes extends readonly GraphNodeLike[]>(options: DefineGraphOptions<Id, InputSchema, OutputSchema, State, Nodes>): GraphDescriptor<Id, InputSchema, OutputSchema, State, Nodes>;
+/** Reads the hidden runtime state of an authored graph.
+ * @param value - Valid graph descriptor.
+ * @returns An Effect with graph state and persistence declarations.
+ * @example Effect.runSync(graphExecutionEffect(graph));
+ */
+export declare const graphExecutionEffect: (value: GraphDescriptor<string, StandardSchemaV1<unknown, unknown>, StandardSchemaV1<unknown, unknown>, AnyStateSchema, readonly GraphNodeLike[]>) => Effect.Effect<GraphExecution<import("@langchain/langgraph").InferStateSchemaValue<any>>, never, never>;
+/** Reads graph runtime state for existing synchronous callers.
+ * @param value - Valid graph descriptor.
+ * @returns Hidden graph state and persistence declarations.
+ * @example graphExecution(graph);
+ */
+export declare function graphExecution(value: GraphDescriptor): GraphExecution;
+/** Checks whether a value is a native graph descriptor.
+ * @param value - Candidate descriptor.
+ * @returns An Effect with a boolean and no typed failure.
+ * @example Effect.runSync(isGraphDescriptorEffect(candidate));
+ */
+export declare const isGraphDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
+/** Checks a graph descriptor for existing synchronous callers.
+ * @param value - Candidate descriptor.
+ * @returns Whether the value is a native graph descriptor.
+ * @example if (isGraphDescriptor(candidate)) invokeGraph(candidate);
+ */
+export declare function isGraphDescriptor(value: unknown): value is GraphDescriptor;
+//# sourceMappingURL=define-graph.d.ts.map

package/dist/define-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-graph.d.ts","sourceRoot":"","sources":["../src/define-graph.ts"],"names":[],"mappings":"AAAA,mIAAmI;AAEnI,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAKhC,OAAO,KAAK,EACV,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,yBAAyB,CAAC;AAGjC,mBAAmB,yBAAyB,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,SAEpB,EAAE,SAAS,MAAM,QACjB,WAAW,SAAS,gBAAgB,QACpC,YAAY,SAAS,gBAAgB,QACrC,KAAK,SAAS,cAAc,QAC5B,KAAK,SAAS,SAAS,aAAa,EAAE,2NAuB/C,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,CAAC,EAAE,SAAS,MAAM,EACvB,KAAK,CAAC,WAAW,SAAS,gBAAgB,EAC1C,KAAK,CAAC,YAAY,SAAS,gBAAgB,EAC3C,KAAK,CAAC,KAAK,SAAS,cAAc,EAClC,KAAK,CAAC,KAAK,SAAS,SAAS,aAAa,EAAE,EAE5C,OAAO,EAAE,kBAAkB,CAAC,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,CAAC,GACvE,eAAe,CAAC,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,CAAC,CAM9D;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,8PAGhC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,cAAc,CAErE;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,0DAYnC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E"}

package/dist/define-graph.js

@@ -0,0 +1,72 @@
+/** Exposes typed LangGraph authoring and delegates descriptor validation and construction before any graph execution can begin. */
+import { createUnboundIdentityEffect } from "@relkit/invocation";
+import { Effect } from "effect";
+import { observeAgent } from "@relkit/agents/internal/agent-telemetry";
+import { isRecordEffect } from "@relkit/agents/internal/agent-validation-value";
+import { prepareGraphDescriptor } from "./define-graph-build.js";
+import { graphDefinitionFailure } from "./define-graph-error.js";
+import { GRAPH_EXECUTION } from "./graph-execution-symbol.js";
+/** Defines an inspectable agent backed by native LangGraph.
+ * @param options - Graph state, nodes, edges, limits, and client policy.
+ * @returns An Effect with a frozen graph descriptor or GraphDefinitionFailure.
+ * @example Effect.runSync(defineGraphEffect({ id: "flow", state, input, output, nodes, edges, limits }));
+ */
+export const defineGraphEffect = Effect.fn("Agents.graph.define")(function* (options) {
+    if (!(yield* isRecordEffect(options))) {
+        return yield* Effect.fail(graphDefinitionFailure(new TypeError("Graph options must be an object")));
+    }
+    const assemble = yield* Effect.try({
+        try: () => prepareGraphDescriptor(options),
+        catch: graphDefinitionFailure,
+    });
+    const id = options.id === undefined
+        ? yield* createUnboundIdentityEffect().pipe(Effect.mapError((failure) => graphDefinitionFailure(failure.cause)))
+        : options.id;
+    return yield* Effect.try({
+        try: () => assemble(id),
+        catch: graphDefinitionFailure,
+    });
+}, (effect) => observeAgent("graph.define", effect));
+/** Defines a graph for existing synchronous authoring callers.
+ * @param options - Graph state, nodes, edges, limits, and client policy.
+ * @returns A frozen inspectable graph descriptor.
+ * @throws The original invalid graph authoring or identity error.
+ * @example const graph = defineGraph({ id: "flow", state, input, output, nodes, edges, limits });
+ */
+export function defineGraph(options) {
+    return Effect.runSync(defineGraphEffect(options).pipe(Effect.catchTag("GraphDefinitionFailure", (failure) => Effect.fail(failure.cause))));
+}
+/** Reads the hidden runtime state of an authored graph.
+ * @param value - Valid graph descriptor.
+ * @returns An Effect with graph state and persistence declarations.
+ * @example Effect.runSync(graphExecutionEffect(graph));
+ */
+export const graphExecutionEffect = Effect.fn("Agents.graph.execution")((value) => Effect.sync(() => value[GRAPH_EXECUTION]), (effect) => observeAgent("graph.execution", effect));
+/** Reads graph runtime state for existing synchronous callers.
+ * @param value - Valid graph descriptor.
+ * @returns Hidden graph state and persistence declarations.
+ * @example graphExecution(graph);
+ */
+export function graphExecution(value) {
+    return Effect.runSync(graphExecutionEffect(value));
+}
+/** Checks whether a value is a native graph descriptor.
+ * @param value - Candidate descriptor.
+ * @returns An Effect with a boolean and no typed failure.
+ * @example Effect.runSync(isGraphDescriptorEffect(candidate));
+ */
+export const isGraphDescriptorEffect = Effect.fn("Agents.graph.isDescriptor")((value) => Effect.sync(() => value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    value.execution === "graph" &&
+    value.kind === "agent" &&
+    value[GRAPH_EXECUTION] !== undefined), (effect) => observeAgent("graph.is-descriptor", effect));
+/** Checks a graph descriptor for existing synchronous callers.
+ * @param value - Candidate descriptor.
+ * @returns Whether the value is a native graph descriptor.
+ * @example if (isGraphDescriptor(candidate)) invokeGraph(candidate);
+ */
+export function isGraphDescriptor(value) {
+    return Effect.runSync(isGraphDescriptorEffect(value));
+}
+//# sourceMappingURL=define-graph.js.map

package/dist/define-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-graph.js","sourceRoot":"","sources":["../src/define-graph.ts"],"names":[],"mappings":"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"}

package/dist/define-graph.types.d.ts

@@ -0,0 +1,69 @@
+/** Exposes typed LangGraph authoring and delegates descriptor validation and construction before any graph execution can begin. This companion preserves the native input and output types without starting runtime work. */
+import type { AnyStateSchema, BaseCheckpointSaver, BaseStore } from "@langchain/langgraph";
+import type { DescriptorBase, DescriptorMetadata } from "@relkit/contracts";
+import type { AgentRef, FunctionGraphNodeDescriptor } from "@relkit/functions";
+import type { InferInput, InferOutput, StandardSchemaV1 } from "@relkit/schema";
+import type { AgentClientPolicy, AgentControl } from "@relkit/agents/internal/agent-client";
+import type { AgentLimits } from "./define-agent.types.js";
+import type { GraphNodeAny } from "./define-graph-node.js";
+import type { GraphEdgeBuilder, GraphEdgeOperation } from "./graph-edges.js";
+import type { GraphWorkflow } from "./graph-workflow.types.js";
+import type { CheckpointerResource, MemoryResource } from "./define-persistence.types.js";
+import type { AgentClientContractMetadata } from "./client-contract-metadata.js";
+import type { GraphAsNodeOptions, SubgraphNodeDescriptor } from "./graph-subgraph.js";
+import type { GRAPH_EXECUTION } from "./graph-execution-symbol.js";
+/** Authored node accepted by a graph descriptor. */
+export type GraphNodeLike = GraphNodeAny | FunctionGraphNodeDescriptor | SubgraphNodeDescriptor;
+/** ID union of a graph's authored nodes. */
+export type GraphNodeId<Nodes extends readonly GraphNodeLike[]> = Nodes[number]["id"];
+/** State value inferred from a LangGraph StateSchema. */
+export type GraphState<State extends AnyStateSchema> = State["State"];
+/** Public state keys selected from a LangGraph StateSchema. */
+export type GraphStateKey<State extends AnyStateSchema> = Extract<keyof GraphState<State>, string>;
+type UniqueNodes<Nodes extends readonly GraphNodeLike[], Seen extends string = never> = number extends Nodes["length"] ? Nodes : Nodes extends readonly [infer Head extends GraphNodeLike, ...infer Tail extends GraphNodeLike[]] ? Head["id"] extends Seen ? never : UniqueNodes<Tail, Seen | Head["id"]> extends never ? never : Nodes : Nodes;
+/** Runtime state and persistence declarations hidden on a graph descriptor. */
+export interface GraphExecution<State = any> {
+    readonly state: AnyStateSchema;
+    readonly operations: readonly GraphEdgeOperation<string, State>[];
+    readonly checkpointer?: BaseCheckpointSaver | CheckpointerResource;
+    readonly store?: BaseStore | MemoryResource;
+}
+/** Inspectable agent descriptor backed by a native LangGraph graph. */
+export interface GraphDescriptor<Id extends string = string, InputSchema extends StandardSchemaV1 = StandardSchemaV1, OutputSchema extends StandardSchemaV1 = StandardSchemaV1, State extends AnyStateSchema = AnyStateSchema, Nodes extends readonly GraphNodeLike[] = readonly GraphNodeLike[]> extends DescriptorBase<"agent", Id>, AgentRef<Id, InputSchema, OutputSchema> {
+    readonly execution: "graph";
+    readonly input: InputSchema;
+    readonly output: OutputSchema;
+    readonly nodes: Nodes;
+    readonly workflow: GraphWorkflow;
+    readonly instructions: "";
+    readonly tools: readonly [];
+    readonly middleware: readonly [];
+    readonly limits: AgentLimits;
+    readonly stateProfile?: string;
+    readonly client?: AgentClientPolicy<(...args: any[]) => unknown, GraphStateKey<State>>;
+    readonly controls?: readonly AgentControl[];
+    readonly clientContract: AgentClientContractMetadata;
+    readonly [GRAPH_EXECUTION]: GraphExecution<GraphState<State>>;
+    readonly asGraphNode: <const NodeId extends string = Id>(options?: GraphAsNodeOptions<NodeId>) => SubgraphNodeDescriptor<NodeId, InputSchema, OutputSchema>;
+}
+/** Authoring options for a native LangGraph agent descriptor. */
+export interface DefineGraphOptions<Id extends string, InputSchema extends StandardSchemaV1, OutputSchema extends StandardSchemaV1, State extends AnyStateSchema, Nodes extends readonly GraphNodeLike[]> extends DescriptorMetadata {
+    readonly id?: Id;
+    readonly state: State;
+    readonly input: InputSchema;
+    readonly output: OutputSchema;
+    readonly nodes: Nodes & UniqueNodes<Nodes>;
+    readonly edges: (graph: GraphEdgeBuilder<NoInfer<Extract<GraphNodeId<Nodes>, string>>, GraphState<State>>) => unknown;
+    readonly limits: AgentLimits;
+    readonly stateProfile?: string;
+    readonly client?: AgentClientPolicy<(...args: any[]) => unknown, GraphStateKey<State>>;
+    readonly controls?: readonly AgentControl[];
+    readonly checkpointer?: BaseCheckpointSaver | CheckpointerResource;
+    readonly store?: BaseStore | MemoryResource;
+}
+/** Input inferred from a graph descriptor. */
+export type GraphInput<Graph extends GraphDescriptor> = InferInput<Graph["input"]>;
+/** Output inferred from a graph descriptor. */
+export type GraphOutput<Graph extends GraphDescriptor> = InferOutput<Graph["output"]>;
+export {};
+//# sourceMappingURL=define-graph.types.d.ts.map

package/dist/define-graph.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-graph.types.d.ts","sourceRoot":"","sources":["../src/define-graph.types.ts"],"names":[],"mappings":"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"}

package/dist/define-graph.types.js

@@ -0,0 +1,3 @@
+/** Exposes typed LangGraph authoring and delegates descriptor validation and construction before any graph execution can begin. This companion preserves the native input and output types without starting runtime work. */
+export {};
+//# sourceMappingURL=define-graph.types.js.map

package/dist/define-graph.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-graph.types.js","sourceRoot":"","sources":["../src/define-graph.types.ts"],"names":[],"mappings":"AAAA,6NAA6N"}

package/dist/define-persistence-guards.d.ts

@@ -0,0 +1,32 @@
+/** Recognizes supported native checkpointer and store shapes before persistence descriptors accept them, preserving SDK identity rather than cloning resources. */
+import type { BaseCheckpointSaver, BaseStore } from "@langchain/langgraph";
+import { Effect } from "effect";
+import type { PersistenceResource } from "./define-persistence.types.js";
+/** Checks whether a value is a RELKIT persistence resource descriptor.
+ * @param value - Candidate descriptor.
+ * @returns An Effect with a boolean and no typed failure.
+ * @example Effect.runSync(isPersistenceResourceEffect(candidate));
+ */
+export declare const isPersistenceResourceEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
+/** Checks a resource for existing synchronous callers.
+ * @param value - Candidate descriptor.
+ * @returns Whether the descriptor follows the persistence protocol.
+ * @example if (isPersistenceResource(value)) await value.acquire(context);
+ */
+export declare function isPersistenceResource(value: unknown): value is PersistenceResource<any, any>;
+/** Validates a resolved LangGraph checkpointer or memory store.
+ * @param resource - Expected persistence role.
+ * @param value - Resolved client handle.
+ * @returns An Effect with void or AgentPersistenceFailure.
+ * @example Effect.runSync(assertPersistenceProtocolEffect("memory", store));
+ */
+export declare const assertPersistenceProtocolEffect: (resource: "checkpointer" | "memory", value: unknown) => Effect.Effect<void, import("./persistence-error.js").AgentPersistenceFailure, never>;
+/** Validates a resolved handle for existing synchronous callers.
+ * @param resource - Expected persistence role.
+ * @param value - Resolved client handle.
+ * @returns Nothing when the protocol is present.
+ * @throws The original protocol TypeError.
+ * @example assertPersistenceProtocol("memory", store);
+ */
+export declare function assertPersistenceProtocol(resource: "checkpointer" | "memory", value: unknown): asserts value is BaseCheckpointSaver | BaseStore;
+//# sourceMappingURL=define-persistence-guards.d.ts.map

package/dist/define-persistence-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-persistence-guards.d.ts","sourceRoot":"","sources":["../src/define-persistence-guards.ts"],"names":[],"mappings":"AAAA,mKAAmK;AAEnK,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAGzE;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,0DAYvC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAAC,GAAG,EAAE,GAAG,CAAC,CAE5F;AAED;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,+IAe3C,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,cAAc,GAAG,QAAQ,EACnC,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,KAAK,IAAI,mBAAmB,GAAG,SAAS,CAMlD"}

package/dist/define-persistence-guards.js

@@ -0,0 +1,55 @@
+/** Recognizes supported native checkpointer and store shapes before persistence descriptors accept them, preserving SDK identity rather than cloning resources. */
+import { Effect } from "effect";
+import { observeAgent } from "@relkit/agents/internal/agent-telemetry";
+import { RELKIT_PERSISTENCE } from "./persistence-symbol.js";
+import { agentPersistenceFailure } from "./persistence-error.js";
+/** Checks whether a value is a RELKIT persistence resource descriptor.
+ * @param value - Candidate descriptor.
+ * @returns An Effect with a boolean and no typed failure.
+ * @example Effect.runSync(isPersistenceResourceEffect(candidate));
+ */
+export const isPersistenceResourceEffect = Effect.fn("Agents.persistence.isResource")((value) => Effect.sync(() => isRecord(value) &&
+    value[RELKIT_PERSISTENCE] === true &&
+    value.kind === "agent-persistence" &&
+    (value.resource === "checkpointer" || value.resource === "memory") &&
+    typeof value.acquire === "function" &&
+    typeof value.release === "function"), (effect) => observeAgent("persistence.is-resource", effect));
+/** Checks a resource for existing synchronous callers.
+ * @param value - Candidate descriptor.
+ * @returns Whether the descriptor follows the persistence protocol.
+ * @example if (isPersistenceResource(value)) await value.acquire(context);
+ */
+export function isPersistenceResource(value) {
+    return Effect.runSync(isPersistenceResourceEffect(value));
+}
+/** Validates a resolved LangGraph checkpointer or memory store.
+ * @param resource - Expected persistence role.
+ * @param value - Resolved client handle.
+ * @returns An Effect with void or AgentPersistenceFailure.
+ * @example Effect.runSync(assertPersistenceProtocolEffect("memory", store));
+ */
+export const assertPersistenceProtocolEffect = Effect.fn("Agents.persistence.assertProtocol")((resource, value) => Effect.try({
+    try: () => {
+        const methods = resource === "checkpointer"
+            ? ["getTuple", "list", "put", "putWrites", "deleteThread"]
+            : ["batch"];
+        if (!isRecord(value) || methods.some((method) => typeof value[method] !== "function")) {
+            throw new TypeError(`${resource} resource does not implement the LangGraph protocol`);
+        }
+    },
+    catch: agentPersistenceFailure,
+}), (effect) => observeAgent("persistence.assert-protocol", effect));
+/** Validates a resolved handle for existing synchronous callers.
+ * @param resource - Expected persistence role.
+ * @param value - Resolved client handle.
+ * @returns Nothing when the protocol is present.
+ * @throws The original protocol TypeError.
+ * @example assertPersistenceProtocol("memory", store);
+ */
+export function assertPersistenceProtocol(resource, value) {
+    Effect.runSync(assertPersistenceProtocolEffect(resource, value).pipe(Effect.catchTag("AgentPersistenceFailure", (failure) => Effect.fail(failure.cause))));
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+//# sourceMappingURL=define-persistence-guards.js.map

package/dist/define-persistence-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-persistence-guards.js","sourceRoot":"","sources":["../src/define-persistence-guards.ts"],"names":[],"mappings":"AAAA,mKAAmK;AAGnK,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAEjE;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,MAAM,CAAC,EAAE,CAAC,+BAA+B,CAAC,CACnF,CAAC,KAAc,EAAE,EAAE,CACjB,MAAM,CAAC,IAAI,CACT,GAAG,EAAE,CACH,QAAQ,CAAC,KAAK,CAAC;IACf,KAAK,CAAC,kBAAkB,CAAC,KAAK,IAAI;IAClC,KAAK,CAAC,IAAI,KAAK,mBAAmB;IAClC,CAAC,KAAK,CAAC,QAAQ,KAAK,cAAc,IAAI,KAAK,CAAC,QAAQ,KAAK,QAAQ,CAAC;IAClE,OAAO,KAAK,CAAC,OAAO,KAAK,UAAU;IACnC,OAAO,KAAK,CAAC,OAAO,KAAK,UAAU,CACtC,EACH,CAAC,MAAM,EAAE,EAAE,CAAC,YAAY,CAAC,yBAAyB,EAAE,MAAM,CAAC,CAC5D,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,OAAO,MAAM,CAAC,OAAO,CAAC,2BAA2B,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,MAAM,CAAC,EAAE,CAAC,mCAAmC,CAAC,CAC3F,CAAC,QAAmC,EAAE,KAAc,EAAE,EAAE,CACtD,MAAM,CAAC,GAAG,CAAC;IACT,GAAG,EAAE,GAAG,EAAE;QACR,MAAM,OAAO,GACX,QAAQ,KAAK,cAAc;YACzB,CAAC,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,cAAc,CAAC;YAC1D,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAChB,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,KAAK,CAAC,MAAM,CAAC,KAAK,UAAU,CAAC,EAAE,CAAC;YACtF,MAAM,IAAI,SAAS,CAAC,GAAG,QAAQ,qDAAqD,CAAC,CAAC;QACxF,CAAC;IACH,CAAC;IACD,KAAK,EAAE,uBAAuB;CAC/B,CAAC,EACJ,CAAC,MAAM,EAAE,EAAE,CAAC,YAAY,CAAC,6BAA6B,EAAE,MAAM,CAAC,CAChE,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CACvC,QAAmC,EACnC,KAAc;IAEd,MAAM,CAAC,OAAO,CACZ,+BAA+B,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,IAAI,CACnD,MAAM,CAAC,QAAQ,CAAC,yBAAyB,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CACpF,CACF,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

package/dist/define-persistence.d.ts

@@ -0,0 +1,33 @@
+/** Creates native persistence descriptors around authored checkpointers and stores; runtime acquisition and release remain owned by the invocation scope. */
+import type { BaseCheckpointSaver, BaseStore } from "@langchain/langgraph";
+import { Effect } from "effect";
+import type { CheckpointerResource, MemoryResource, PersistenceOptions, PersistenceResource } from "./define-persistence.types.js";
+export type * from "./define-persistence.types.js";
+export { assertPersistenceProtocol, assertPersistenceProtocolEffect, isPersistenceResource, isPersistenceResourceEffect, } from "./define-persistence-guards.js";
+/** Defines a lazily acquired checkpointer resource.
+ * @param options - Identity, client factory, ownership, and disposal policy.
+ * @returns An Effect with a resource descriptor or AgentPersistenceFailure.
+ * @example Effect.runSync(defineCheckpointerDbEffect({ id: "db", client: saver }));
+ */
+export declare const defineCheckpointerDbEffect: <Value extends BaseCheckpointSaver>(options: PersistenceOptions<Value>) => Effect.Effect<PersistenceResource<"checkpointer", Value>, import("./persistence-error.js").AgentPersistenceFailure, never>;
+/** Defines a checkpointer for existing synchronous authoring callers.
+ * @param options - Identity, client factory, ownership, and disposal policy.
+ * @returns A lazily acquired resource descriptor.
+ * @throws The original invalid options error.
+ * @example const resource = defineCheckpointerDb({ id: "db", client: saver });
+ */
+export declare function defineCheckpointerDb<Value extends BaseCheckpointSaver>(options: PersistenceOptions<Value>): CheckpointerResource<Value>;
+/** Defines a lazily acquired memory store resource.
+ * @param options - Identity, client factory, ownership, and disposal policy.
+ * @returns An Effect with a resource descriptor or AgentPersistenceFailure.
+ * @example Effect.runSync(defineMemoryDbEffect({ id: "memory", client: store }));
+ */
+export declare const defineMemoryDbEffect: <Value extends BaseStore>(options: PersistenceOptions<Value>) => Effect.Effect<PersistenceResource<"memory", Value>, import("./persistence-error.js").AgentPersistenceFailure, never>;
+/** Defines a memory store for existing synchronous authoring callers.
+ * @param options - Identity, client factory, ownership, and disposal policy.
+ * @returns A lazily acquired resource descriptor.
+ * @throws The original invalid options error.
+ * @example const resource = defineMemoryDb({ id: "memory", client: store });
+ */
+export declare function defineMemoryDb<Value extends BaseStore>(options: PersistenceOptions<Value>): MemoryResource<Value>;
+//# sourceMappingURL=define-persistence.d.ts.map

package/dist/define-persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-persistence.d.ts","sourceRoot":"","sources":["../src/define-persistence.ts"],"names":[],"mappings":"AAAA,6JAA6J;AAE7J,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE3E,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIhC,OAAO,KAAK,EACV,oBAAoB,EACpB,cAAc,EAEd,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,+BAA+B,CAAC;AAEvC,mBAAmB,+BAA+B,CAAC;AACnD,OAAO,EACL,yBAAyB,EACzB,+BAA+B,EAC/B,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,gCAAgC,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,GACpC,KAAK,SAAS,mBAAmB,mKAMnC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,SAAS,mBAAmB,EACpE,OAAO,EAAE,kBAAkB,CAAC,KAAK,CAAC,GACjC,oBAAoB,CAAC,KAAK,CAAC,CAM7B;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAC9B,KAAK,SAAS,SAAS,6JAMzB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,SAAS,SAAS,EACpD,OAAO,EAAE,kBAAkB,CAAC,KAAK,CAAC,GACjC,cAAc,CAAC,KAAK,CAAC,CAMvB"}