@relkit/langchain 0.0.0-stage → 0.7.10

package/dist/testing/agents-utils.js

@@ -0,0 +1,79 @@
+/** Normalizes scripted native test values and observations for the agent harness without starting a separate execution owner. */
+/**
+ * Asserts selected native agent trace fields in their observed order.
+ * @param trace - Captured native trace assertion snapshot.
+ * @param expected - Existing expected status or ordered captured values.
+ * @returns Nothing when the existing assertion contract matches.
+ */
+export function assertAgentTrace(trace, expected) {
+    if (expected.spanKinds !== undefined &&
+        !same(trace.spans.map((span) => span.kind), expected.spanKinds)) {
+        throw new Error(`Unexpected agent span kinds: ${JSON.stringify(trace.spans.map((span) => span.kind))}`);
+    }
+    if (expected.names !== undefined &&
+        !same(trace.spans.map((span) => span.name), expected.names)) {
+        throw new Error(`Unexpected agent span names: ${JSON.stringify(trace.spans.map((span) => span.name))}`);
+    }
+    for (const edge of expected.edges ?? []) {
+        if (!trace.edges.some((actual) => sameEdge(actual, edge))) {
+            throw new Error(`Missing agent edge: ${JSON.stringify(edge)}`);
+        }
+    }
+}
+/**
+ * Creates isolated trace capture and the existing assertion facade.
+ * @param spans - Owner-local native span snapshots.
+ * @param edges - Compiled native graph relationships or captured agent relationship ledger.
+ * @returns A native trace helper exposing detached inspection and clear operations.
+ */
+export function createTrace(spans, edges) {
+    const trace = {
+        get spans() {
+            return Object.freeze([...spans]);
+        },
+        get edges() {
+            return Object.freeze([...edges]);
+        },
+        read: () => ({ spans: Object.freeze([...spans]), edges: Object.freeze([...edges]) }),
+        clear: () => {
+            spans.length = 0;
+            edges.length = 0;
+        },
+        assert: (expected) => assertAgentTrace(trace, expected),
+    };
+    return trace;
+}
+/**
+ * Records observed agent edges while forwarding the caller's native hooks.
+ * @param hooks - Caller-native hooks forwarded without changing ordering.
+ * @param edges - Compiled native graph relationships or captured agent relationship ledger.
+ * @returns Hooks preserving native callback order and caller behavior.
+ */
+export function captureHooks(hooks, edges) {
+    return {
+        ...hooks,
+        onObservedEdge: (edge) => {
+            edges.push(edge);
+            hooks?.onObservedEdge?.(edge);
+        },
+    };
+}
+/**
+ * Compares existing assertion values through their canonical representation.
+ * @param left - First existing assertion value.
+ * @param right - Second existing assertion value.
+ * @returns True when the expected ordered values match.
+ */
+function same(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+/**
+ * Compares the existing agent relationship and endpoint fields.
+ * @param left - First existing assertion value.
+ * @param right - Second existing assertion value.
+ * @returns True when both native observed edges match.
+ */
+function sameEdge(left, right) {
+    return (left.relationship === right.relationship && left.from === right.from && left.to === right.to);
+}
+//# sourceMappingURL=agents-utils.js.map

package/dist/testing/agents-utils.js.map

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

package/dist/testing/agents.d.ts

@@ -0,0 +1,26 @@
+/** Publishes the native agent test harness helpers from the explicit integration while sharing RELKIT testing ownership and clock boundaries. */
+import { Context, Layer } from "effect";
+import type { AgentHarnessService } from "./agent-harness.types.js";
+import type { TestAgent, TestAgentDescriptor, TestAgentOptions } from "./agents-types.js";
+export type { TestAgent, TestAgentApproval, TestAgentApprovalMode, TestAgentApprovals, TestAgentDescriptor, TestAgentInvocationOptions, TestAgentModel, TestAgentModelCall, TestAgentModelOptions, TestAgentOptions, TestAgentTrace, TestAgentTraceExpectation, TestAgentTraceSnapshot, TestModelTurn, } from "./agents-types.js";
+export { assertAgentTrace } from "./agents-utils.js";
+export { createTestModel } from "./agents-model.js";
+declare const TestAgentHarness_base: Context.ServiceClass<TestAgentHarness, "relkit/testing/AgentHarness", AgentHarnessService>;
+/** Agent decisions, approval ownership and scripted invocation share one service. */
+export declare class TestAgentHarness extends TestAgentHarness_base {
+}
+/**
+ * Acquires the network-free harness behind the public synchronous factory.
+ * @typeParam Agent Descriptor carrying input/output schema inference.
+ * @param options Script, tool engine, approval and capture policies.
+ * @returns A scoped service Layer; scope release resets outstanding work.
+ */
+export declare function testAgentLayer<Agent extends TestAgentDescriptor>(options: TestAgentOptions<Agent>): Layer.Layer<TestAgentHarness, never, never>;
+/**
+ * Creates isolated agent state with native model cancellation and owned approvals.
+ * @typeParam Agent Descriptor determining public input/output types.
+ * @param options Network-free script and native engine dependencies.
+ * @returns A synchronously ready harness preserving existing results and errors.
+ */
+export declare function createTestAgent<Agent extends TestAgentDescriptor>(options: TestAgentOptions<Agent>): TestAgent<Agent>;
+//# sourceMappingURL=agents.d.ts.map

package/dist/testing/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/testing/agents.ts"],"names":[],"mappings":"AAAA,iJAAiJ;AAIjJ,OAAO,EAAE,OAAO,EAAU,KAAK,EAAkB,MAAM,QAAQ,CAAC;AAQhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAGpE,OAAO,KAAK,EACV,SAAS,EAET,mBAAmB,EAEnB,gBAAgB,EAEjB,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,0BAA0B,EAC1B,cAAc,EACd,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,cAAc,EACd,yBAAyB,EACzB,sBAAsB,EACtB,aAAa,GACd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;;AAEpD,qFAAqF;AACrF,qBAAa,gBAAiB,SAAQ,qBAErC;CAAG;AAEJ;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,SAAS,mBAAmB,EAC9D,OAAO,EAAE,gBAAgB,CAAC,KAAK,CAAC,+CAoCjC;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,SAAS,mBAAmB,EAC/D,OAAO,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAC/B,SAAS,CAAC,KAAK,CAAC,CAoBlB"}

package/dist/testing/agents.js

@@ -0,0 +1,64 @@
+/** Publishes the native agent test harness helpers from the explicit integration while sharing RELKIT testing ownership and clock boundaries. */
+import { createAgentState } from "./agent-state.js";
+import { Context, Effect, Layer, ManagedRuntime } from "effect";
+import { observeExecution, runExecutionPromise, runExecutionSync, } from "@relkit/contracts/operation";
+import { disposeTestingOwner, testingLoggerLayer } from "@relkit/testing/internal/testing-owner";
+import { combineSignals } from "@relkit/testing/internal/runtime-clock";
+import { createTestModel } from "./agents-model.js";
+import { assertAgentTrace } from "./agents-utils.js";
+export { assertAgentTrace } from "./agents-utils.js";
+export { createTestModel } from "./agents-model.js";
+/** Agent decisions, approval ownership and scripted invocation share one service. */
+export class TestAgentHarness extends Context.Service()("relkit/testing/AgentHarness") {
+}
+/**
+ * Acquires the network-free harness behind the public synchronous factory.
+ * @typeParam Agent Descriptor carrying input/output schema inference.
+ * @param options Script, tool engine, approval and capture policies.
+ * @returns A scoped service Layer; scope release resets outstanding work.
+ */
+export function testAgentLayer(options) {
+    return Layer.effect(TestAgentHarness, Effect.acquireRelease(Effect.gen(function* () {
+        const { value, close } = yield* createAgentState(options);
+        return TestAgentHarness.of({
+            value,
+            close: observeExecution("testing", "agent.close", close),
+            invoke: (input, invocation) => observeExecution("testing", "agent.invoke", Effect.fn("Testing.agent.invoke")(() => Effect.tryPromise({
+                try: async (signal) => {
+                    const signals = combineSignals(invocation?.signal, signal);
+                    try {
+                        return await value.invoke(input, { ...invocation, signal: signals.signal });
+                    }
+                    finally {
+                        signals.dispose();
+                    }
+                },
+                catch: (cause) => cause,
+            }))()),
+        });
+    }), (service) => service.close.pipe(Effect.orDie)));
+}
+/**
+ * Creates isolated agent state with native model cancellation and owned approvals.
+ * @typeParam Agent Descriptor determining public input/output types.
+ * @param options Network-free script and native engine dependencies.
+ * @returns A synchronously ready harness preserving existing results and errors.
+ */
+export function createTestAgent(options) {
+    const owner = ManagedRuntime.make(testAgentLayer(options).pipe(Layer.provideMerge(testingLoggerLayer(options.logger))));
+    let service;
+    try {
+        service = runExecutionSync(owner, TestAgentHarness);
+    }
+    catch (error) {
+        void disposeTestingOwner(owner).catch(() => undefined);
+        throw error;
+    }
+    let closing;
+    return Object.freeze({
+        ...service.value,
+        invoke: (input, options) => runExecutionPromise(owner, service.invoke(input, options)),
+        close: () => (closing ??= disposeTestingOwner(owner)),
+    });
+}
+//# sourceMappingURL=agents.js.map

package/dist/testing/agents.js.map

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

package/dist/testing/agents.types.d.ts

@@ -0,0 +1,113 @@
+/** Publishes the native agent test harness helpers from the explicit integration while sharing RELKIT testing ownership and clock boundaries. This companion preserves the native input and output types without starting runtime work. */
+import type { AgentApprovalHandler, AgentCapturePolicy, AgentDescriptor, AgentInvocationOptions, AgentObservedEdge, AgentRuntimeHooks, AgentRuntimeOptions, PendingApproval } from "../index.js";
+import type { spanSnapshot } from "@relkit/invocation";
+import type { JsonValue } from "@relkit/contracts";
+import type { InferInput, InferOutput } from "@relkit/schema";
+import type { TestFailureControls } from "@relkit/testing/internal/fakes";
+/** Native agent descriptor vocabulary retained by public test inference. */
+export type TestAgentDescriptor = AgentDescriptor<string, unknown, unknown>;
+/** Fixed or pending native approval policy vocabulary. */
+export type TestAgentApprovalMode = "approved" | "denied" | "pending";
+/** Fixed, pending or caller-native approval decision authority. */
+export type TestAgentApproval = TestAgentApprovalMode | AgentApprovalHandler;
+/** Scripted native model outcome supporting final values, tool calls and failures. */
+export type TestModelTurn = {
+    readonly type: "tool-call";
+    readonly callId: string;
+    readonly toolId: string;
+    readonly input: JsonValue;
+} | {
+    readonly type: "final";
+    readonly output: JsonValue;
+} | {
+    readonly type: "error";
+    readonly code: string;
+    readonly message: string;
+} | {
+    readonly type: "cancelled";
+    readonly reason?: string;
+};
+/** Network-free model identity, hanging behavior and explicit logging policy. */
+export interface TestAgentModelOptions {
+    readonly logger?: NonNullable<Parameters<typeof import("@relkit/testing/internal/testing-owner").testingLoggerLayer>[0]>;
+    readonly provider?: string;
+    readonly modelId?: string;
+    readonly hang?: boolean;
+}
+/** Detached native request and scripted turn evidence captured in order. */
+export interface TestAgentModelCall {
+    readonly index: number;
+    readonly request: {
+        readonly messages: readonly unknown[];
+        readonly tools: readonly unknown[];
+    };
+    readonly turn: TestModelTurn;
+}
+/** Public model facade owning script mutation, capture and release. */
+export interface TestAgentModel {
+    readonly provider: string;
+    readonly modelId: string;
+    readonly calls: readonly TestAgentModelCall[];
+    readonly script: (turns: readonly TestModelTurn[]) => void;
+    readonly reset: () => void;
+    readonly close: () => Promise<void>;
+}
+/**
+ * Native agent, tool engine, model script and capture dependencies.
+ * @typeParam Agent - Native descriptor determining input/output schema inference.
+ */
+export interface TestAgentOptions<Agent extends TestAgentDescriptor = TestAgentDescriptor> {
+    readonly logger?: NonNullable<Parameters<typeof import("@relkit/testing/internal/testing-owner").testingLoggerLayer>[0]>;
+    readonly agent: Agent;
+    readonly tools: AgentRuntimeOptions["tools"];
+    readonly engine: AgentRuntimeOptions["engine"];
+    readonly script?: readonly TestModelTurn[];
+    readonly model?: TestAgentModelOptions;
+    readonly maxInputBytes?: number;
+    readonly maxOutputBytes?: number;
+    readonly approval?: TestAgentApproval;
+    readonly failures?: TestFailureControls;
+    readonly hooks?: AgentRuntimeHooks;
+    readonly capture?: AgentCapturePolicy;
+}
+/** Invocation-only native overrides excluding owned model and engine dependencies. */
+export type TestAgentInvocationOptions = Omit<AgentInvocationOptions, "input" | "approval" | "hooks">;
+/** Detached observed span and edge evidence for a test invocation. */
+export interface TestAgentTraceSnapshot {
+    readonly spans: readonly ReturnType<typeof spanSnapshot>[];
+    readonly edges: readonly AgentObservedEdge[];
+}
+/** Owned trace evidence with explicit read, clear and assertion operations. */
+export interface TestAgentTrace extends TestAgentTraceSnapshot {
+    readonly read: () => TestAgentTraceSnapshot;
+    readonly clear: () => void;
+    readonly assert: (expected: TestAgentTraceExpectation) => void;
+}
+/** Selected span, outcome and tool-edge evidence checked by trace assertions. */
+export interface TestAgentTraceExpectation {
+    readonly spanKinds?: readonly ReturnType<typeof spanSnapshot>["kind"][];
+    readonly names?: readonly string[];
+    readonly edges?: readonly AgentObservedEdge[];
+}
+/** Synchronous selection controls over owned pending native decisions. */
+export interface TestAgentApprovals {
+    readonly pending: () => readonly PendingApproval[];
+    readonly approve: (toolCallId?: string) => void;
+    readonly deny: (toolCallId?: string) => void;
+}
+/**
+ * Owned native agent facade preserving schema inference, approvals and trace evidence.
+ * @typeParam Agent - Native descriptor determining input/output schema inference.
+ */
+export interface TestAgent<Agent extends TestAgentDescriptor = TestAgentDescriptor> {
+    readonly model: TestAgentModel;
+    readonly failures: TestFailureControls;
+    readonly approvals: TestAgentApprovals;
+    readonly pending: () => readonly PendingApproval[];
+    readonly trace: TestAgentTrace;
+    readonly script: (turns: readonly TestModelTurn[]) => void;
+    readonly invoke: (input: InferInput<Agent["input"]>, options?: TestAgentInvocationOptions) => Promise<InferOutput<Agent["output"]>>;
+    readonly reset: () => void;
+    readonly close: () => Promise<void>;
+}
+//# sourceMappingURL=agents.types.d.ts.map

package/dist/testing/agents.types.d.ts.map

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

package/dist/testing/agents.types.js

@@ -0,0 +1,3 @@
+/** Publishes the native agent test harness helpers from the explicit integration while sharing RELKIT testing ownership and clock boundaries. This companion preserves the native input and output types without starting runtime work. */
+export {};
+//# sourceMappingURL=agents.types.js.map

package/dist/testing/agents.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.types.js","sourceRoot":"","sources":["../../src/testing/agents.types.ts"],"names":[],"mappings":"AAAA,2OAA2O"}

package/package.json

@@ -1,6 +1,193 @@
 {
   "name": "@relkit/langchain",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.10",
+  "description": "Explicit native LangChain agent execution for RELKIT.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rel-kit/relkit.git",
+    "directory": "integrations/packages/langchain"
+  },
+  "homepage": "https://github.com/rel-kit/relkit#readme",
+  "bugs": {
+    "url": "https://github.com/rel-kit/relkit/issues"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.10"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js"
+    },
+    "./continuation-validation": {
+      "types": "./dist/continuation-validation.d.ts",
+      "import": "./dist/continuation-validation.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/agents.d.ts",
+      "import": "./dist/testing/agents.js"
+    }
+  },
+  "dependencies": {
+    "@relkit/agents": "0.7.10",
+    "@cfworker/json-schema": "4.1.1",
+    "@relkit/contracts": "0.7.10",
+    "@relkit/functions": "0.7.10",
+    "@relkit/invocation": "0.7.10",
+    "@relkit/schema": "0.7.10",
+    "@relkit/tools": "0.7.10",
+    "effect": "4.0.1"
+  },
+  "peerDependencies": {
+    "deepagents": "1.13.3",
+    "@relkit/testing": "0.7.10",
+    "@langchain/core": "1.2.9",
+    "@langchain/langgraph": "1.4.14",
+    "langchain": "1.5.10",
+    "langsmith": "0.10.8"
+  },
+  "peerDependenciesMeta": {
+    "deepagents": {
+      "optional": true
+    },
+    "@relkit/testing": {
+      "optional": true
+    },
+    "@langchain/core": {
+      "optional": true
+    },
+    "@langchain/langgraph": {
+      "optional": true
+    },
+    "langchain": {
+      "optional": true
+    },
+    "langsmith": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.0.1",
+    "@vitest/coverage-v8": "5.0.1",
+    "@langchain/langgraph-checkpoint-mongodb": "1.4.1",
+    "@langchain/langgraph-checkpoint-postgres": "1.0.5",
+    "@langchain/langgraph-checkpoint-redis": "1.0.11",
+    "@langchain/langgraph-checkpoint-sqlite": "1.0.4",
+    "@relkit/buckets": "0.7.10",
+    "deepagents": "1.13.3",
+    "vitest": "5.0.1",
+    "@langchain/core": "1.2.9",
+    "@langchain/langgraph": "1.4.14",
+    "langchain": "1.5.10",
+    "langsmith": "0.10.8"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "check": "tsc -b --pretty false",
+    "typecheck": "tsc -b --pretty false",
+    "test": "vitest run --config vitest.config.ts",
+    "test:coverage": "vitest run --coverage --config vitest.config.ts"
+  },
+  "relkit": {
+    "integration": {
+      "id": "langchain",
+      "exports": {
+        "authoring": ".",
+        "runtime": {
+          "export": "./runtime",
+          "registrations": [
+            {
+              "capability": "agent-execution",
+              "adapterId": "langchain",
+              "protocolVersion": 1
+            },
+            {
+              "capability": "agent-deep",
+              "adapterId": "deepagents",
+              "protocolVersion": 1
+            }
+          ]
+        }
+      },
+      "dependencies": [
+        {
+          "package": "@langchain/core",
+          "supportedRange": "1.2.9",
+          "installSection": "dependencies",
+          "capabilities": [
+            "agent-execution"
+          ],
+          "phases": [
+            "check",
+            "build",
+            "runtime"
+          ]
+        },
+        {
+          "package": "@langchain/langgraph",
+          "supportedRange": "1.4.14",
+          "installSection": "dependencies",
+          "capabilities": [
+            "agent-execution"
+          ],
+          "phases": [
+            "check",
+            "build",
+            "runtime"
+          ]
+        },
+        {
+          "package": "langchain",
+          "supportedRange": "1.5.10",
+          "installSection": "dependencies",
+          "capabilities": [
+            "agent-execution"
+          ],
+          "phases": [
+            "check",
+            "build",
+            "runtime"
+          ]
+        },
+        {
+          "package": "langsmith",
+          "supportedRange": "0.10.8",
+          "installSection": "dependencies",
+          "capabilities": [
+            "agent-execution"
+          ],
+          "phases": [
+            "check",
+            "build",
+            "runtime"
+          ]
+        },
+        {
+          "package": "deepagents",
+          "supportedRange": "1.13.3",
+          "installSection": "dependencies",
+          "capabilities": [
+            "agent-deep"
+          ],
+          "phases": [
+            "check",
+            "build",
+            "runtime"
+          ]
+        }
+      ]
+    }
+  }
+}