@relkit/langchain 0.0.0-stage → 0.7.10

package/dist/signal.d.ts

@@ -0,0 +1,64 @@
+/** Builds and validates RELKIT signal descriptors used by native agent execution while retaining their payload schema and stable identity. */
+import type { MaybePromise } from "@relkit/contracts";
+import { Context, Effect, Layer } from "effect";
+import { AgentRuntimeError } from "./runtime-errors.js";
+import type { ExecutionSignalClockService, ExecutionSignalHandle, ExecutionSignalOptions } from "./signal.types.js";
+export type * from "./signal.types.js";
+declare const ExecutionSignalClock_base: Context.ServiceClass<ExecutionSignalClock, "relkit/agents/ExecutionSignalClock", ExecutionSignalClockService>;
+/** Replaceable clock and timer boundary for execution deadlines.
+ * @example Effect.provide(createExecutionSignalEffect(options), ExecutionSignalClockLive);
+ */
+export declare class ExecutionSignalClock extends ExecutionSignalClock_base {
+}
+/** Live wall clock and timer implementation.
+ * @example Effect.runSync(Effect.provide(createExecutionSignalEffect(options), ExecutionSignalClockLive));
+ */
+export declare const ExecutionSignalClockLive: Layer.Layer<ExecutionSignalClock, never, never>;
+/** Converts an abort reason to a safe invocation error.
+ * @param signal - Aborted invocation signal.
+ * @returns An Effect with a timeout or cancellation error.
+ * @example Effect.runSync(signalFailureEffect(signal));
+ */
+export declare const signalFailureEffect: (signal: AbortSignal) => Effect.Effect<AgentRuntimeError, never, never>;
+/** Converts an abort reason for existing synchronous callers.
+ * @param signal - Aborted invocation signal.
+ * @returns A safe timeout or cancellation error.
+ * @example signalFailure(signal);
+ */
+export declare function signalFailure(signal: AbortSignal): AgentRuntimeError;
+/** Creates a live execution signal with an owned timer and caller listener.
+ * @param options - Invocation limits, deadline, and caller signal.
+ * @returns An Effect with a closeable signal or AgentInvocationFailure.
+ * @example Effect.runSync(Effect.provide(createExecutionSignalEffect(options), testClock));
+ */
+export declare const createExecutionSignalEffect: (options: ExecutionSignalOptions) => Effect.Effect<ExecutionSignalHandle, import("./runtime-effect-error.js").AgentInvocationFailure, ExecutionSignalClock>;
+/** Acquires an execution signal whose owner closes it with its Effect scope.
+ * @param options - Invocation limits, deadline, and caller signal.
+ * @returns A scoped Effect with a signal or AgentInvocationFailure.
+ * @example Effect.scoped(Effect.gen(function* () { const active = yield* acquireExecutionSignalEffect(options); }));
+ */
+export declare const acquireExecutionSignalEffect: (options: ExecutionSignalOptions) => Effect.Effect<ExecutionSignalHandle, import("./runtime-effect-error.js").AgentInvocationFailure, import("effect/Scope").Scope | ExecutionSignalClock>;
+/** Creates a live signal for existing callers that own and close the handle.
+ * @param options - Invocation limits, deadline, and caller signal.
+ * @returns A closeable execution signal.
+ * @throws The original invalid deadline error.
+ * @example const active = createExecutionSignal(options); try { await work(active.signal); } finally { active.close(); }
+ */
+export declare function createExecutionSignal(options: ExecutionSignalOptions): ExecutionSignalHandle;
+/** Races Promise work with caller and Effect cancellation.
+ * @param work - Already started Promise or immediate value.
+ * @param signal - Caller cancellation signal.
+ * @param linkEffectSignal - Whether to link direct Effect interruption.
+ * @returns An Effect with the value or AgentInvocationFailure.
+ * @example await Effect.runPromise(withSignalEffect(work, signal));
+ */
+export declare const withSignalEffect: <T>(work: MaybePromise<T>, signal: AbortSignal, linkEffectSignal?: boolean | undefined) => Effect.Effect<T, import("./runtime-effect-error.js").AgentInvocationFailure, never>;
+/** Races work with a caller signal for existing Promise callers.
+ * @param work - Already started Promise or immediate value.
+ * @param signal - Caller cancellation signal.
+ * @returns The value when work completes before cancellation.
+ * @throws The original work error or AgentRuntimeError on cancellation.
+ * @example await withSignal(fetchData(), signal);
+ */
+export declare function withSignal<T>(work: MaybePromise<T>, signal: AbortSignal): Promise<T>;
+//# sourceMappingURL=signal.d.ts.map

package/dist/signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../src/signal.ts"],"names":[],"mappings":"AAAA,8IAA8I;AAG9I,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAGhD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EACV,2BAA2B,EAC3B,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,mBAAmB,CAAC;AAE3B,mBAAmB,mBAAmB,CAAC;;AAEvC;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,yBAGD;CAAG;AAE5C;;GAEG;AACH,eAAO,MAAM,wBAAwB,iDAOpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,yEAQ/B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,iBAAiB,CAEpE;AAED;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,6JAwCvC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,4LAMxC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAO5F;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC1B,CAAC,4KAOH,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAMpF"}

package/dist/signal.js

@@ -0,0 +1,136 @@
+/** Builds and validates RELKIT signal descriptors used by native agent execution while retaining their payload schema and stable identity. */
+import { executionDeadline } from "./signal-deadline.js";
+import { Context, Effect, Layer } from "effect";
+import { observeAgent } from "@relkit/agents/internal/agent-telemetry";
+import { agentInvocationFailure } from "./runtime-effect-error.js";
+import { AgentRuntimeError } from "./runtime-errors.js";
+/** Replaceable clock and timer boundary for execution deadlines.
+ * @example Effect.provide(createExecutionSignalEffect(options), ExecutionSignalClockLive);
+ */
+export class ExecutionSignalClock extends Context.Service()("relkit/agents/ExecutionSignalClock") {
+}
+/** Live wall clock and timer implementation.
+ * @example Effect.runSync(Effect.provide(createExecutionSignalEffect(options), ExecutionSignalClockLive));
+ */
+export const ExecutionSignalClockLive = Layer.succeed(ExecutionSignalClock, ExecutionSignalClock.of({
+    now: () => Date.now(),
+    setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+    clearTimeout: (handle) => clearTimeout(handle),
+}));
+/** Converts an abort reason to a safe invocation error.
+ * @param signal - Aborted invocation signal.
+ * @returns An Effect with a timeout or cancellation error.
+ * @example Effect.runSync(signalFailureEffect(signal));
+ */
+export const signalFailureEffect = Effect.fn("Agents.signal.failure")((signal) => Effect.sync(() => signal.reason instanceof AgentRuntimeError && signal.reason.code === "RELKIT_AGENT_TIMEOUT"
+    ? signal.reason
+    : new AgentRuntimeError("RELKIT_AGENT_CANCELLED", "Agent invocation cancelled")), (effect) => observeAgent("signal.failure", effect));
+/** Converts an abort reason for existing synchronous callers.
+ * @param signal - Aborted invocation signal.
+ * @returns A safe timeout or cancellation error.
+ * @example signalFailure(signal);
+ */
+export function signalFailure(signal) {
+    return Effect.runSync(signalFailureEffect(signal));
+}
+/** Creates a live execution signal with an owned timer and caller listener.
+ * @param options - Invocation limits, deadline, and caller signal.
+ * @returns An Effect with a closeable signal or AgentInvocationFailure.
+ * @example Effect.runSync(Effect.provide(createExecutionSignalEffect(options), testClock));
+ */
+export const createExecutionSignalEffect = Effect.fn("Agents.signal.create")(function* (options) {
+    const clock = yield* ExecutionSignalClock;
+    return yield* Effect.try({
+        try: () => {
+            const controller = new AbortController();
+            const listeners = [];
+            const now = clock.now();
+            const deadline = executionDeadline(options, now);
+            const timeout = new AgentRuntimeError("RELKIT_AGENT_TIMEOUT", "Agent deadline exceeded");
+            if (deadline <= now)
+                controller.abort(timeout);
+            const timer = clock.setTimeout(() => controller.abort(timeout), Math.max(0, deadline - now));
+            const signal = options.signal;
+            if (signal !== undefined) {
+                const abort = () => controller.abort(signal.reason);
+                if (signal.aborted)
+                    abort();
+                else {
+                    signal.addEventListener("abort", abort, { once: true });
+                    listeners.push([signal, abort]);
+                }
+            }
+            let closed = false;
+            return {
+                signal: controller.signal,
+                close: () => {
+                    if (closed)
+                        return;
+                    closed = true;
+                    clock.clearTimeout(timer);
+                    for (const [source, listener] of listeners)
+                        source.removeEventListener("abort", listener);
+                },
+            };
+        },
+        catch: agentInvocationFailure,
+    });
+}, (effect) => observeAgent("signal.create", effect));
+/** Acquires an execution signal whose owner closes it with its Effect scope.
+ * @param options - Invocation limits, deadline, and caller signal.
+ * @returns A scoped Effect with a signal or AgentInvocationFailure.
+ * @example Effect.scoped(Effect.gen(function* () { const active = yield* acquireExecutionSignalEffect(options); }));
+ */
+export const acquireExecutionSignalEffect = Effect.fn("Agents.signal.acquire")((options) => Effect.acquireRelease(createExecutionSignalEffect(options), (active) => Effect.sync(() => active.close())), (effect) => observeAgent("signal.acquire", effect));
+/** Creates a live signal for existing callers that own and close the handle.
+ * @param options - Invocation limits, deadline, and caller signal.
+ * @returns A closeable execution signal.
+ * @throws The original invalid deadline error.
+ * @example const active = createExecutionSignal(options); try { await work(active.signal); } finally { active.close(); }
+ */
+export function createExecutionSignal(options) {
+    return Effect.runSync(createExecutionSignalEffect(options).pipe(Effect.catchTag("AgentInvocationFailure", (failure) => Effect.fail(failure.cause)), Effect.provide(ExecutionSignalClockLive)));
+}
+/** Races Promise work with caller and Effect cancellation.
+ * @param work - Already started Promise or immediate value.
+ * @param signal - Caller cancellation signal.
+ * @param linkEffectSignal - Whether to link direct Effect interruption.
+ * @returns An Effect with the value or AgentInvocationFailure.
+ * @example await Effect.runPromise(withSignalEffect(work, signal));
+ */
+export const withSignalEffect = Effect.fn("Agents.signal.withSignal")((work, signal, linkEffectSignal = true) => Effect.tryPromise({
+    try: (effectSignal) => withSignalCore(work, linkEffectSignal ? AbortSignal.any([signal, effectSignal]) : signal),
+    catch: agentInvocationFailure,
+}), (effect) => observeAgent("signal.with-signal", effect));
+/** Races work with a caller signal for existing Promise callers.
+ * @param work - Already started Promise or immediate value.
+ * @param signal - Caller cancellation signal.
+ * @returns The value when work completes before cancellation.
+ * @throws The original work error or AgentRuntimeError on cancellation.
+ * @example await withSignal(fetchData(), signal);
+ */
+export function withSignal(work, signal) {
+    return Effect.runPromise(withSignalEffect(work, signal, false).pipe(Effect.catchTag("AgentInvocationFailure", (failure) => Effect.fail(failure.cause))));
+}
+function withSignalCore(work, signal) {
+    if (signal.aborted)
+        return Promise.reject(signalFailure(signal));
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (complete) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", abort);
+            complete();
+        };
+        const abort = () => finish(() => reject(signalFailure(signal)));
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted) {
+            abort();
+            return;
+        }
+        Promise.resolve(work).then((value) => finish(() => resolve(value)), (error) => finish(() => reject(error)));
+    });
+}
+//# sourceMappingURL=signal.js.map

package/dist/signal.js.map

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

package/dist/signal.types.d.ts

@@ -0,0 +1,35 @@
+/** Builds and validates RELKIT signal descriptors used by native agent execution while retaining their payload schema and stable identity. This companion preserves the native input and output types without starting runtime work. */
+import type { AgentInvocationOptions, AgentRuntimeOptions } from "./runtime.js";
+/** Options whose limits and caller signal determine an execution deadline. */
+export type ExecutionSignalOptions = AgentRuntimeOptions & AgentInvocationOptions;
+/** Live execution signal whose owner must call close once finished. */
+export interface ExecutionSignalHandle {
+    readonly signal: AbortSignal;
+    /** Clears the deadline timer and caller signal listener.
+     * @returns Nothing; repeated calls are safe.
+     * @example handle.close();
+     */
+    readonly close: () => void;
+}
+/** Replaceable deadline timer and current time boundary. */
+export interface ExecutionSignalClockService {
+    /** Reads the current wall time in milliseconds.
+     * @returns Epoch milliseconds.
+     * @example clock.now();
+     */
+    readonly now: () => number;
+    /** Schedules a deadline callback.
+     * @param callback - Deadline action.
+     * @param delayMs - Nonnegative delay.
+     * @returns Opaque timer handle.
+     * @example clock.setTimeout(onDeadline, 1000);
+     */
+    readonly setTimeout: (callback: () => void, delayMs: number) => unknown;
+    /** Cancels a scheduled callback.
+     * @param handle - Opaque timer handle.
+     * @returns Nothing.
+     * @example clock.clearTimeout(handle);
+     */
+    readonly clearTimeout: (handle: unknown) => void;
+}
+//# sourceMappingURL=signal.types.d.ts.map

package/dist/signal.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal.types.d.ts","sourceRoot":"","sources":["../src/signal.types.ts"],"names":[],"mappings":"AAAA,wOAAwO;AAExO,OAAO,KAAK,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEhF,8EAA8E;AAC9E,MAAM,MAAM,sBAAsB,GAAG,mBAAmB,GAAG,sBAAsB,CAAC;AAElF,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED,4DAA4D;AAC5D,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACxE;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CAClD"}

package/dist/signal.types.js

@@ -0,0 +1,3 @@
+/** Builds and validates RELKIT signal descriptors used by native agent execution while retaining their payload schema and stable identity. This companion preserves the native input and output types without starting runtime work. */
+export {};
+//# sourceMappingURL=signal.types.js.map

package/dist/signal.types.js.map

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

package/dist/testing/agent-approvals.d.ts

@@ -0,0 +1,8 @@
+import type { TestAgentApproval } from "./agents-types.js";
+import type { AgentApprovalState } from "./agent-approvals.types.js";
+/** Creates isolated native approval controls.
+ * @param choice - Existing fixed, pending or caller-defined policy.
+ * @returns Controls retaining selection errors and cancellation behavior.
+ */
+export declare function createAgentApprovalState(choice: TestAgentApproval | undefined): AgentApprovalState;
+//# sourceMappingURL=agent-approvals.d.ts.map

package/dist/testing/agent-approvals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-approvals.d.ts","sourceRoot":"","sources":["../../src/testing/agent-approvals.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAA2B,MAAM,4BAA4B,CAAC;AAE9F;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,iBAAiB,GAAG,SAAS,GACpC,kBAAkB,CAuBpB"}

package/dist/testing/agent-approvals.js

@@ -0,0 +1,98 @@
+/**
+ * Owns native pending decisions and cancellation listeners for one test agent.
+ * Settlement removes its listener before completing the same deferred decision.
+ */
+import { Deferred, Effect, Ref } from "effect";
+/** Creates isolated native approval controls.
+ * @param choice - Existing fixed, pending or caller-defined policy.
+ * @returns Controls retaining selection errors and cancellation behavior.
+ */
+export function createAgentApprovalState(choice) {
+    const state = Ref.makeUnsafe({
+        pending: new Map(),
+        decisions: new Map(),
+        signals: new Map(),
+    });
+    const handler = approvalHandler(choice, state);
+    return Object.freeze({
+        ...(handler === undefined ? {} : { handler }),
+        pending: () => Object.freeze([...Ref.getUnsafe(state).pending.values()]),
+        approve: (id) => resolvePending(state, id, "approved"),
+        deny: (id) => resolvePending(state, id, "denied"),
+        reset: () => {
+            const current = Ref.getUnsafe(state);
+            for (const key of [...current.decisions.keys()])
+                settle(state, key, "denied");
+            current.signals.clear();
+        },
+        registerSignal: (id, signal) => Ref.getUnsafe(state).signals.set(id, signal),
+        releaseSignal: (id) => {
+            Ref.getUnsafe(state).signals.delete(id);
+        },
+    });
+}
+/** Selects the existing policy without acquiring a pending decision prematurely.
+ * @param choice - Authored policy.
+ * @param state - This owner's pending callback state.
+ * @returns The same optional approval callback.
+ */
+function approvalHandler(choice, state) {
+    if (choice === undefined)
+        return undefined;
+    if (typeof choice === "function")
+        return choice;
+    if (choice !== "pending")
+        return () => choice;
+    return (approval) => waitForApproval(state, approval);
+}
+/** Acquires a deferred decision linked to its invocation's cancellation.
+ * @param state - Owner state.
+ * @param approval - Canonical pending request.
+ * @returns The original native decision Promise.
+ */
+function waitForApproval(state, approval) {
+    const current = Ref.getUnsafe(state);
+    const key = `${approval.invocationId}:${approval.toolCallId}`;
+    const signal = current.signals.get(approval.invocationId);
+    const done = Deferred.makeUnsafe();
+    const abort = () => settle(state, key, "denied");
+    current.pending.set(key, approval);
+    current.decisions.set(key, { done, abort, ...(signal === undefined ? {} : { signal }) });
+    if (signal?.aborted)
+        abort();
+    else
+        signal?.addEventListener("abort", abort, { once: true });
+    return Effect.runPromise(Deferred.await(done));
+}
+/** Completes a decision after removing its native callback listener.
+ * @param state - Owner state.
+ * @param key - Invocation/tool-call identity.
+ * @param decision - Canonical native result.
+ * @returns Nothing; repeated completion is harmless.
+ */
+function settle(state, key, decision) {
+    const current = Ref.getUnsafe(state);
+    const entry = current.decisions.get(key);
+    if (entry === undefined)
+        return;
+    entry.signal?.removeEventListener("abort", entry.abort);
+    current.pending.delete(key);
+    current.decisions.delete(key);
+    Effect.runSync(Deferred.succeed(entry.done, decision));
+}
+/** Selects exactly one matching request before settling it once.
+ * @param state - Owner state.
+ * @param toolCallId - Optional tool-call, tool or resolver identity.
+ * @param decision - Canonical result.
+ * @returns Nothing after removing the matching resolver.
+ */
+function resolvePending(state, toolCallId, decision) {
+    const matches = [...Ref.getUnsafe(state).pending.entries()].filter(([key, approval]) => toolCallId === undefined ||
+        approval.toolCallId === toolCallId ||
+        approval.toolId === toolCallId ||
+        key === toolCallId);
+    if (matches.length !== 1)
+        throw new Error("Expected exactly one matching pending approval");
+    settle(state, matches[0][0], decision);
+}
+//# sourceMappingURL=agent-approvals.js.map

package/dist/testing/agent-approvals.js.map

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

package/dist/testing/agent-approvals.types.d.ts

@@ -0,0 +1,24 @@
+/** Exercises native agent approval continuations through the harness's scoped model and execution owner, retaining resume identity and cleanup. This companion preserves the native input and output types without starting runtime work. */
+import type { AgentApprovalHandler } from "../index.js";
+import type { Deferred } from "effect";
+import type { TestAgentApprovals } from "./agents-types.js";
+/** Deferred decision authority and its native cancellation listener. */
+export interface PendingAgentDecision {
+    readonly done: Deferred.Deferred<"approved" | "denied">;
+    readonly signal?: AbortSignal;
+    readonly abort: () => void;
+}
+/** Synchronous controls over owned native approval decisions and cancellation. */
+export interface AgentApprovalState extends TestAgentApprovals {
+    readonly handler?: AgentApprovalHandler;
+    readonly reset: () => void;
+    readonly registerSignal: (id: string, signal: AbortSignal) => void;
+    readonly releaseSignal: (id: string) => void;
+}
+/** Native callback state retained by one test approval owner. */
+export interface AgentApprovalOwnedState {
+    readonly pending: Map<string, import("../index.js").PendingApproval>;
+    readonly decisions: Map<string, PendingAgentDecision>;
+    readonly signals: Map<string, AbortSignal>;
+}
+//# sourceMappingURL=agent-approvals.types.d.ts.map

package/dist/testing/agent-approvals.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-approvals.types.d.ts","sourceRoot":"","sources":["../../src/testing/agent-approvals.types.ts"],"names":[],"mappings":"AAAA,6OAA6O;AAE7O,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,wEAAwE;AACxE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,UAAU,GAAG,QAAQ,CAAC,CAAC;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED,kFAAkF;AAClF,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC5D,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;IACnE,QAAQ,CAAC,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9C;AAED,iEAAiE;AACjE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,aAAa,EAAE,eAAe,CAAC,CAAC;IACrE,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IACtD,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CAC5C"}

package/dist/testing/agent-approvals.types.js

@@ -0,0 +1,3 @@
+/** Exercises native agent approval continuations through the harness's scoped model and execution owner, retaining resume identity and cleanup. This companion preserves the native input and output types without starting runtime work. */
+export {};
+//# sourceMappingURL=agent-approvals.types.js.map

package/dist/testing/agent-approvals.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-approvals.types.js","sourceRoot":"","sources":["../../src/testing/agent-approvals.types.ts"],"names":[],"mappings":"AAAA,6OAA6O"}

package/dist/testing/agent-harness.types.d.ts

@@ -0,0 +1,25 @@
+/** Defines the native test harness execution and lifecycle contract shared by model, tool and approval helpers. This companion preserves the native input and output types without starting runtime work. */
+import type { Effect } from "effect";
+import type { TestAgent, TestAgentInvocationOptions } from "./agents-types.js";
+import type { AgentObservedEdge } from "../index.js";
+import type { spanSnapshot } from "@relkit/invocation";
+import type { acquireAgentHarness } from "./agent-state-setup.js";
+/** Acquired native model, state and observer dependencies for one harness owner. */
+export type AgentHarnessDependencies = Effect.Success<ReturnType<typeof acquireAgentHarness>>;
+/** Trace ledgers and native work belong to the same agent owner. */
+export interface AgentOwnedState {
+    closed: boolean;
+    invocationSequence: number;
+    readonly spans: ReturnType<typeof spanSnapshot>[];
+    readonly edges: AgentObservedEdge[];
+    readonly active: Set<AbortController>;
+    readonly pending: Set<Promise<unknown>>;
+    closing?: Promise<void>;
+}
+/** Native state facade and Effect-owned invocation/shutdown workflows. */
+export interface AgentHarnessService {
+    readonly close: Effect.Effect<void, unknown>;
+    readonly value: Omit<TestAgent, "invoke">;
+    readonly invoke: (input: unknown, invocation?: TestAgentInvocationOptions) => Effect.Effect<unknown, unknown>;
+}
+//# sourceMappingURL=agent-harness.types.d.ts.map

package/dist/testing/agent-harness.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-harness.types.d.ts","sourceRoot":"","sources":["../../src/testing/agent-harness.types.ts"],"names":[],"mappings":"AAAA,6MAA6M;AAE7M,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,SAAS,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE,oFAAoF;AACpF,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC;AAE9F,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,CAAC;IAChB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,EAAE,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,iBAAiB,EAAE,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,eAAe,CAAC,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACxC,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,CACf,KAAK,EAAE,OAAO,EACd,UAAU,CAAC,EAAE,0BAA0B,KACpC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;CACtC"}

package/dist/testing/agent-harness.types.js

@@ -0,0 +1,3 @@
+/** Defines the native test harness execution and lifecycle contract shared by model, tool and approval helpers. This companion preserves the native input and output types without starting runtime work. */
+export {};
+//# sourceMappingURL=agent-harness.types.js.map

package/dist/testing/agent-harness.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-harness.types.js","sourceRoot":"","sources":["../../src/testing/agent-harness.types.ts"],"names":[],"mappings":"AAAA,6MAA6M"}

package/dist/testing/agent-state-invocation.d.ts

@@ -0,0 +1,4 @@
+import type { AgentHarnessDependencies } from "./agent-harness.types.js";
+import type { TestAgentDescriptor, TestAgentInvocationOptions, TestAgentOptions } from "./agents-types.js";
+export declare function invokeAgentHarness<Agent extends TestAgentDescriptor>(options: TestAgentOptions<Agent>, harness: AgentHarnessDependencies, input: import("@relkit/schema").InferInput<Agent["input"]>, invocation?: TestAgentInvocationOptions): Promise<import("@relkit/schema").InferOutput<Agent["output"]>>;
+//# sourceMappingURL=agent-state-invocation.d.ts.map

package/dist/testing/agent-state-invocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-state-invocation.d.ts","sourceRoot":"","sources":["../../src/testing/agent-state-invocation.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,KAAK,EACV,mBAAmB,EACnB,0BAA0B,EAC1B,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAE3B,wBAAsB,kBAAkB,CAAC,KAAK,SAAS,mBAAmB,EACxE,OAAO,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAChC,OAAO,EAAE,wBAAwB,EAEjC,KAAK,EAAE,OAAO,gBAAgB,EAAE,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAC1D,UAAU,GAAE,0BAA+B,GAC1C,OAAO,CAAC,OAAO,gBAAgB,EAAE,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAoChE"}

package/dist/testing/agent-state-invocation.js

@@ -0,0 +1,41 @@
+/** Runs native invocations under the harness-owned span and cancellation lifetime. */
+import { Ref } from "effect";
+import { completeSpan, runInExecutionContext, startRootSpan } from "@relkit/invocation";
+import { combineSignals } from "@relkit/testing/internal/runtime-clock";
+import { invokeAgent } from "../index.js";
+export async function invokeAgentHarness(options, harness, input, invocation = {}) {
+    const { state, approvals, spanRuntime, model, engine, hooks } = harness;
+    const approval = approvals.handler;
+    const invocationId = invocation.invocationId ?? `test-agent-${++Ref.getUnsafe(state).invocationSequence}`;
+    const controller = new AbortController();
+    Ref.getUnsafe(state).active.add(controller);
+    const signals = combineSignals(invocation.signal, controller.signal);
+    approvals.registerSignal(invocationId, signals.signal);
+    const root = startRootSpan(spanRuntime, "relkit.testing.agent", "internal");
+    try {
+        return (await runInExecutionContext({ span: root, runtime: spanRuntime }, () => invokeAgent({
+            agent: options.agent,
+            tools: options.tools,
+            engine,
+            modelRegistry: {
+                resolveModel: () => ({ id: model.modelId, model: model.languageModel }),
+            },
+            ...(options.maxInputBytes === undefined ? {} : { maxInputBytes: options.maxInputBytes }),
+            ...(options.maxOutputBytes === undefined ? {} : { maxOutputBytes: options.maxOutputBytes }),
+            ...(approval === undefined ? {} : { approval }),
+            ...(options.capture === undefined ? {} : { capture: options.capture }),
+            ...invocation,
+            signal: signals.signal,
+            input,
+            invocationId,
+            hooks,
+        })));
+    }
+    finally {
+        approvals.releaseSignal(invocationId);
+        signals.dispose();
+        Ref.getUnsafe(state).active.delete(controller);
+        completeSpan(root);
+    }
+}
+//# sourceMappingURL=agent-state-invocation.js.map

package/dist/testing/agent-state-invocation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-state-invocation.js","sourceRoot":"","sources":["../../src/testing/agent-state-invocation.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,OAAO,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxF,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AACxE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAQ1C,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAgC,EAChC,OAAiC,EAEjC,KAA0D,EAC1D,aAAyC,EAAE;IAE3C,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IACxE,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC;IACnC,MAAM,YAAY,GAChB,UAAU,CAAC,YAAY,IAAI,cAAc,EAAE,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,kBAAkB,EAAE,CAAC;IACvF,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,cAAc,CAAC,UAAU,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IACrE,SAAS,CAAC,cAAc,CAAC,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACvD,MAAM,IAAI,GAAG,aAAa,CAAC,WAAW,EAAE,sBAAsB,EAAE,UAAU,CAAC,CAAC;IAC5E,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,qBAAqB,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE,GAAG,EAAE,CAC7E,WAAW,CAAC;YACV,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM;YACN,aAAa,EAAE;gBACb,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,aAAa,EAAE,CAAC;aACxE;YACD,GAAG,CAAC,OAAO,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC;YACxF,GAAG,CAAC,OAAO,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC;YAC3F,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC;YAC/C,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;YACtE,GAAG,UAAU;YACb,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,KAAK;YACL,YAAY;YACZ,KAAK;SACN,CAAC,CACH,CAA0D,CAAC;IAC9D,CAAC;YAAS,CAAC;QACT,SAAS,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;QACtC,OAAO,CAAC,OAAO,EAAE,CAAC;QAClB,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC/C,YAAY,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/testing/agent-state-lifecycle.d.ts

@@ -0,0 +1,6 @@
+/** Stops admission before aborting and joining every native invocation and model owner. */
+import { Context, Effect } from "effect";
+import type { AgentHarnessDependencies } from "./agent-harness.types.js";
+export declare function agentHarnessClose(context: Context.Context<never>, harness: AgentHarnessDependencies): Effect.Effect<void, unknown, never>;
+export declare function resetAgentHarness(harness: AgentHarnessDependencies): void;
+//# sourceMappingURL=agent-state-lifecycle.d.ts.map

package/dist/testing/agent-state-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-state-lifecycle.d.ts","sourceRoot":"","sources":["../../src/testing/agent-state-lifecycle.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,OAAO,EAAE,OAAO,EAAY,MAAM,EAAO,MAAM,QAAQ,CAAC;AAExD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAEzE,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAC/B,OAAO,EAAE,wBAAwB,uCA4BlC;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CASzE"}

package/dist/testing/agent-state-lifecycle.js

@@ -0,0 +1,36 @@
+/** Stops admission before aborting and joining every native invocation and model owner. */
+import { Context, Deferred, Effect, Ref } from "effect";
+import { joinOwnedWork, runOwnedContext } from "@relkit/testing/internal/work-ownership";
+export function agentHarnessClose(context, harness) {
+    const { state, approvals, model } = harness;
+    return Effect.uninterruptible(Effect.fn("Testing.agent.close")(function* () {
+        const current = Ref.getUnsafe(state);
+        if (current.closing !== undefined)
+            return yield* Effect.tryPromise({
+                try: () => current.closing,
+                catch: (cause) => cause,
+            });
+        const done = yield* Deferred.make();
+        current.closing = runOwnedContext(context, Deferred.await(done));
+        void current.closing.catch(() => undefined);
+        current.closed = true;
+        return yield* Effect.gen(function* () {
+            approvals.reset();
+            yield* Effect.forEach([...current.active], (controller) => Effect.sync(() => controller.abort(new Error("Test agent closed"))), { concurrency: 1, discard: true });
+            current.active.clear();
+            yield* joinOwnedWork(current.pending);
+            yield* Effect.tryPromise({ try: () => model.close(), catch: (cause) => cause });
+        }).pipe(Effect.onExit((exit) => Deferred.done(done, exit)));
+    })());
+}
+export function resetAgentHarness(harness) {
+    const { state, model, trace, approvals } = harness;
+    for (const controller of Ref.getUnsafe(state).active)
+        controller.abort(new Error("Test agent reset"));
+    Ref.getUnsafe(state).active.clear();
+    model.reset();
+    trace.clear();
+    approvals.reset();
+    Ref.getUnsafe(state).invocationSequence = 0;
+}
+//# sourceMappingURL=agent-state-lifecycle.js.map

package/dist/testing/agent-state-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-state-lifecycle.js","sourceRoot":"","sources":["../../src/testing/agent-state-lifecycle.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAGzF,MAAM,UAAU,iBAAiB,CAC/B,OAA+B,EAC/B,OAAiC;IAEjC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAC5C,OAAO,MAAM,CAAC,eAAe,CAC3B,MAAM,CAAC,EAAE,CAAC,qBAAqB,CAAC,CAAC,QAAQ,CAAC;QACxC,MAAM,OAAO,GAAG,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;YAC/B,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC;gBAC9B,GAAG,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAQ;gBAC3B,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK;aACxB,CAAC,CAAC;QACL,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAiB,CAAC;QACnD,OAAO,CAAC,OAAO,GAAG,eAAe,CAAC,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QACjE,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC5C,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;QACtB,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;YAChC,SAAS,CAAC,KAAK,EAAE,CAAC;YAClB,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CACnB,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,EACnB,CAAC,UAAU,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC,EACnF,EAAE,WAAW,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAClC,CAAC;YACF,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YACvB,KAAK,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YACtC,KAAK,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC;QAClF,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9D,CAAC,CAAC,EAAE,CACL,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAiC;IACjE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IACnD,KAAK,MAAM,UAAU,IAAI,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,MAAM;QAClD,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC,CAAC;IAClD,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACpC,KAAK,CAAC,KAAK,EAAE,CAAC;IACd,KAAK,CAAC,KAAK,EAAE,CAAC;IACd,SAAS,CAAC,KAAK,EAAE,CAAC;IAClB,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,kBAAkB,GAAG,CAAC,CAAC;AAC9C,CAAC"}

package/dist/testing/agent-state-setup.d.ts

@@ -0,0 +1,18 @@
+/** Acquires one native test model and its trace, approval and cancellation state. */
+import { Effect, Ref } from "effect";
+import { SpanRuntime } from "@relkit/invocation";
+import type { AgentOwnedState } from "./agent-harness.types.js";
+import type { TestAgentOptions } from "./agents-types.js";
+export declare const acquireAgentHarness: (options: TestAgentOptions<import("./agents.types.js").TestAgentDescriptor>) => Effect.Effect<{
+    failures: import("@relkit/testing/internal/fakes").TestFailureControls;
+    model: import("./agents-model.types.js").RuntimeTestAgentModel;
+    state: Ref.Ref<AgentOwnedState>;
+    approvals: import("./agent-approvals.types.js").AgentApprovalState;
+    trace: import("./agents.types.js").TestAgentTrace;
+    hooks: import("@relkit/agents/internal/observability").AgentRuntimeHooks;
+    spanRuntime: SpanRuntime;
+    engine: {
+        invoke: (request: Parameters<(options: import("@relkit/tools").ToolEngineInvocation) => Promise<unknown>>[0]) => Promise<unknown>;
+    };
+}, never, import("effect/Scope").Scope>;
+//# sourceMappingURL=agent-state-setup.d.ts.map

package/dist/testing/agent-state-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-state-setup.d.ts","sourceRoot":"","sources":["../../src/testing/agent-state-setup.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,EAAE,WAAW,EAAgB,MAAM,oBAAoB,CAAC;AAK/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,eAAO,MAAM,mBAAmB;;;;;;;;;0BAmBJ,UAAU,6EAA8B,CAAC,CAAC,CAAC;;uCAOrE,CAAC"}