@telnyx/agent-harness 0.1.0-beta.0

package/dist/contract.js

@@ -0,0 +1,278 @@
+import { describe, expect, it } from "vitest";
+import { AGENT_HARNESS_PORTS_VERSION, } from "./ports.js";
+export { AGENT_HARNESS_PORTS_VERSION } from "./ports.js";
+const initialContractState = {
+    nested: { keep: true },
+    remove: "delete-me",
+};
+async function withFixture(factory, run) {
+    const fixture = await factory();
+    try {
+        await run(fixture);
+    }
+    finally {
+        await fixture.close();
+    }
+}
+/**
+ * Register the executable v2 ports contract against an adapter factory.
+ *
+ * Runtime and plain-Node adapters call this same function; adapter-specific
+ * tests may add stricter checks, but may not weaken these shared semantics.
+ */
+export function defineAgentHarnessPortsContract(label, factory) {
+    describe(`${label} — AgentHarnessPorts v2 contract`, () => {
+        it("advertises the exact contract version, stable host identity, deterministic clock, and selected environment", async () => {
+            await withFixture(factory, async ({ ports, reopen, rewrapLive }) => {
+                expect(ports.version).toBe(AGENT_HARNESS_PORTS_VERSION);
+                expect(ports.identity.id).toBe("contract-agent");
+                expect(ports.clock.now()).toBe(1_700_000_000_000);
+                expect(ports.environment).toEqual({ MODEL: "deterministic-model" });
+                expect("SECRET" in ports.environment).toBe(false);
+                expect(rewrapLive()).not.toBe(ports);
+                expect(rewrapLive().activation).toBe(ports.activation);
+                const reopened = await reopen();
+                expect(reopened.version).toBe(AGENT_HARNESS_PORTS_VERSION);
+                expect(reopened.identity.id).toBe("contract-agent");
+                expect(reopened.activation).not.toBe(ports.activation);
+            });
+        });
+        it("preserves AgentMessage/StoredMessage fields and monotonic insertion order across reopen", async () => {
+            await withFixture(factory, async ({ ports, reopen }) => {
+                await expect(ports.messages.append({ role: "user", content: "first" })).resolves.toBe(1);
+                await expect(ports.messages.append({ role: "assistant", content: "second" })).resolves.toBe(2);
+                await expect(ports.messages.appendMany([
+                    {
+                        role: "assistant",
+                        content: "tool request",
+                        toolCalls: [{ id: "call-1", name: "lookup", args: { q: "x" } }],
+                    },
+                    {
+                        role: "tool",
+                        content: "tool result",
+                        name: "lookup",
+                        toolCallId: "call-1",
+                    },
+                ])).resolves.toBe(4);
+                const firstRead = await ports.messages.all();
+                expect(firstRead.map((message) => message.seq)).toEqual([1, 2, 3, 4]);
+                expect(firstRead.map((message) => message.content)).toEqual([
+                    "first",
+                    "second",
+                    "tool request",
+                    "tool result",
+                ]);
+                expect(firstRead[2]?.toolCalls?.[0]).toEqual({
+                    id: "call-1",
+                    name: "lookup",
+                    args: { q: "x" },
+                });
+                expect(firstRead.every((message) => message.at instanceof Date)).toBe(true);
+                const reopened = await reopen();
+                expect((await reopened.messages.all()).map((message) => message.seq)).toEqual([1, 2, 3, 4]);
+                expect((await reopened.messages.last(2)).map((message) => message.seq)).toEqual([3, 4]);
+            });
+        });
+        it("rolls back rows and sequence state after failed single and batch message writes", async () => {
+            await withFixture(factory, async ({ ports }) => {
+                const invalid = {
+                    role: "assistant",
+                    content: "invalid",
+                    toolCalls: [{ id: "bad", name: "bad", args: () => "not storage-safe" }],
+                };
+                await expect(ports.messages.append({ role: "user", content: "kept" })).resolves.toBe(1);
+                const beforeSingle = await ports.messages.all();
+                await expect(ports.messages.append(invalid)).rejects.toThrow();
+                await expect(ports.messages.all()).resolves.toEqual(beforeSingle);
+                await expect(ports.messages.count()).resolves.toBe(1);
+                await expect(ports.messages.append({ role: "assistant", content: "after single failure" })).resolves.toBe(2);
+                const beforeBatch = await ports.messages.all();
+                await expect(ports.messages.appendMany([{ role: "user", content: "valid" }, invalid])).rejects.toThrow();
+                await expect(ports.messages.all()).resolves.toEqual(beforeBatch);
+                await expect(ports.messages.count()).resolves.toBe(2);
+                await expect(ports.messages.append({ role: "assistant", content: "after batch failure" })).resolves.toBe(3);
+                expect((await ports.messages.all()).map((message) => message.seq)).toEqual([1, 2, 3]);
+            });
+        });
+        it("uses durable RFC 7396 merge and replace state semantics across reopen", async () => {
+            await withFixture(factory, async ({ ports, reopen }) => {
+                await expect(ports.state.merge({ nested: { added: "yes" }, remove: null })).resolves.toEqual({ nested: { keep: true, added: "yes" } });
+                const reopened = await reopen();
+                await expect(reopened.state.get()).resolves.toEqual({
+                    nested: { keep: true, added: "yes" },
+                });
+                await expect(reopened.state.replace({ nested: {}, replacement: true })).resolves.toEqual({ nested: {}, replacement: true });
+                await expect(reopened.state.get()).resolves.toEqual({
+                    nested: {},
+                    replacement: true,
+                });
+            });
+        });
+        it("can reject after merge and replace commit when the post-commit state hook fails", async () => {
+            await withFixture(factory, async ({ ports, stateHook }) => {
+                stateHook.failNext();
+                await expect(ports.state.merge({ nested: { added: "committed-before-hook" }, remove: null })).rejects.toThrow("injected state hook failure");
+                await expect(ports.state.get()).resolves.toEqual({
+                    nested: { keep: true, added: "committed-before-hook" },
+                });
+                stateHook.failNext();
+                await expect(ports.state.replace({ nested: {}, replacement: true })).rejects.toThrow("injected state hook failure");
+                await expect(ports.state.get()).resolves.toEqual({
+                    nested: {},
+                    replacement: true,
+                });
+                expect(stateHook.calls()).toEqual([
+                    {
+                        prev: initialContractState,
+                        next: { nested: { keep: true, added: "committed-before-hook" } },
+                    },
+                    {
+                        prev: { nested: { keep: true, added: "committed-before-hook" } },
+                        next: { nested: {}, replacement: true },
+                    },
+                ]);
+            });
+        });
+        it("propagates state persistence failures without replacing the last durable value", async () => {
+            await withFixture(factory, async ({ ports }) => {
+                const before = await ports.state.get();
+                await expect(ports.state.replace({ nested: {}, invalid: () => "not storage-safe" })).rejects.toThrow();
+                await expect(ports.state.get()).resolves.toEqual(before);
+            });
+        });
+        it("exposes synchronous SQL exec and commits or rolls back transactionSync atomically", async () => {
+            await withFixture(factory, async ({ ports, reopen }) => {
+                ports.sql.exec("CREATE TABLE ledger (value INTEGER NOT NULL)");
+                const result = ports.sql.transactionSync(() => {
+                    ports.sql.exec("INSERT INTO ledger VALUES (?)", 1);
+                    ports.sql.exec("INSERT INTO ledger VALUES (?)", 2);
+                    return "committed";
+                });
+                expect(result).toBe("committed");
+                expect(ports.sql.exec("SELECT value FROM ledger ORDER BY value").toArray()).toEqual([
+                    { value: 1 },
+                    { value: 2 },
+                ]);
+                const boom = new Error("transaction failed");
+                expect(() => ports.sql.transactionSync(() => {
+                    ports.sql.exec("INSERT INTO ledger VALUES (?)", 3);
+                    throw boom;
+                })).toThrow(boom);
+                expect(ports.sql.exec("SELECT count(*) AS count FROM ledger").toArray()).toEqual([
+                    { count: 2 },
+                ]);
+                const reopened = await reopen();
+                expect(reopened.sql.exec("SELECT count(*) AS count FROM ledger").toArray()).toEqual([
+                    { count: 2 },
+                ]);
+            });
+        });
+        it("maps queue, delayed schedule, recurrence, stable-id upsert, cancel, and pending durability without a run-status ledger", async () => {
+            await withFixture(factory, async ({ ports, reopen }) => {
+                expect(ports.tasks.delivery).toBe("at-least-once");
+                await expect(ports.tasks.queue("process", { version: 1 }, { id: "stable", maxRetries: 2 })).resolves.toBe("stable");
+                await expect(ports.tasks.queue("process", { version: 2 }, { id: "stable", maxRetries: 3 })).resolves.toBe("stable");
+                await expect(ports.tasks.schedule(5, "later", { delay: true }, { id: "later" })).resolves.toBe("later");
+                await expect(ports.tasks.every(3, "repeat", { recurring: true }, { id: "repeat" })).resolves.toBe("repeat");
+                const pending = await ports.tasks.list();
+                expect(pending).toHaveLength(3);
+                expect(pending.every((task) => task.createdAt instanceof Date)).toBe(true);
+                expect(pending.find((task) => task.id === "stable")).toMatchObject({
+                    name: "process",
+                    payload: { version: 2 },
+                    due: 1_700_000_000_000,
+                    attempts: 0,
+                    maxRetries: 3,
+                });
+                expect(pending.find((task) => task.id === "later")).toMatchObject({
+                    due: 1_700_000_005_000,
+                    everyMs: undefined,
+                });
+                expect(pending.find((task) => task.id === "repeat")).toMatchObject({
+                    due: 1_700_000_003_000,
+                    everyMs: 3_000,
+                });
+                expect(pending.every((task) => !("status" in task))).toBe(true);
+                const reopened = await reopen();
+                expect((await reopened.tasks.list()).map((task) => task.id).sort()).toEqual([
+                    "later",
+                    "repeat",
+                    "stable",
+                ]);
+                await expect(reopened.tasks.cancel("later")).resolves.toBe(true);
+                await expect(reopened.tasks.cancel("later")).resolves.toBe(false);
+            });
+        });
+        it("propagates scheduler validation failures for invalid recurrence and non-finite deadlines", async () => {
+            await withFixture(factory, async ({ ports }) => {
+                await expect(ports.tasks.every(0, "invalid", undefined, { id: "invalid" })).rejects.toThrow("positive");
+                await expect(ports.tasks.schedule(Number.NaN, "invalid", undefined, { id: "nan" })).rejects.toThrow();
+                await expect(ports.tasks.schedule(Number.POSITIVE_INFINITY, "invalid", undefined, { id: "infinite" })).rejects.toThrow();
+                await expect(ports.tasks.every(Number.POSITIVE_INFINITY, "invalid", undefined, { id: "every-infinite" })).rejects.toThrow();
+            });
+        });
+        it("redelivers a failed due task without inventing a run-status ledger", async () => {
+            await withFixture(factory, async ({ ports, delivery }) => {
+                delivery.failNext();
+                await ports.tasks.queue("contractDelivery", "payload", {
+                    id: "retry-id",
+                    maxRetries: 1,
+                });
+                expect(await delivery.drainDue()).toBe(1);
+                expect(delivery.calls()).toEqual(["payload"]);
+                expect(await ports.tasks.list()).toMatchObject([
+                    { id: "retry-id", attempts: 1, due: 1_700_000_001_000 },
+                ]);
+                delivery.advanceBy(1_000);
+                expect(await delivery.drainDue()).toBe(1);
+                expect(delivery.calls()).toEqual(["payload", "payload"]);
+                expect(await ports.tasks.list()).toEqual([]);
+            });
+        });
+        it("keeps a recurring task cancelled when its handler cancels itself and throws", async () => {
+            await withFixture(factory, async ({ ports, delivery }) => {
+                await ports.tasks.every(1, "selfCancel", undefined, { id: "self-cancel" });
+                delivery.advanceBy(1_000);
+                expect(await delivery.selfCancelAndThrow()).toBe(1);
+                expect(await ports.tasks.list()).toEqual([]);
+            });
+        });
+        it("keeps a throwing handler's same-id replacement while carrying retry accounting", async () => {
+            await withFixture(factory, async ({ ports, delivery }) => {
+                await ports.tasks.queue("selfReplace", { version: 1 }, {
+                    id: "self-replace",
+                    maxRetries: 3,
+                });
+                expect(await delivery.selfReplaceAndThrow()).toBe(1);
+                expect(await ports.tasks.list()).toMatchObject([
+                    {
+                        id: "self-replace",
+                        name: "replacement",
+                        payload: { version: 2 },
+                        due: 1_700_000_060_000,
+                        attempts: 1,
+                        maxRetries: 3,
+                    },
+                ]);
+            });
+        });
+        it("preserves monotonic EventLog ordering across reopen", async () => {
+            await withFixture(factory, async ({ ports, reopen }) => {
+                await expect(ports.events.emit("progress", { step: 1 })).resolves.toBe(1);
+                await expect(ports.events.emit("progress", { step: 2 })).resolves.toBe(2);
+                expect((await ports.events.read(0)).map((event) => event.seq)).toEqual([1, 2]);
+                expect((await ports.events.read(1)).map((event) => event.seq)).toEqual([2]);
+                expect((await ports.events.read()).every((event) => event.at instanceof Date)).toBe(true);
+                const beforeFailure = await ports.events.read();
+                await expect(ports.events.emit("invalid", { callback: () => undefined })).rejects.toThrow();
+                await expect(ports.events.read()).resolves.toEqual(beforeFailure);
+                await expect(ports.events.count()).resolves.toBe(2);
+                await expect(ports.events.emit("progress", { step: 3 })).resolves.toBe(3);
+                expect((await ports.events.read()).map((event) => event.seq)).toEqual([1, 2, 3]);
+                const reopened = await reopen();
+                expect((await reopened.events.read()).map((event) => event.seq)).toEqual([1, 2, 3]);
+            });
+        });
+    });
+}
+//# sourceMappingURL=contract.js.map

package/dist/durable.d.ts

@@ -0,0 +1,81 @@
+import type { TaskRecord } from "@telnyx/edge-runtime/internal";
+import { type AgentHarnessPorts } from "./ports.js";
+import { type HarnessStepContext } from "./steps.js";
+export declare const HARNESS_RUN_STATUSES: readonly ["accepted", "running", "awaiting_approval", "resume_pending", "completed", "failed", "canceled", "outcome_unknown"];
+export type HarnessRunStatus = (typeof HARNESS_RUN_STATUSES)[number];
+export interface HarnessRun {
+    readonly id: string;
+    readonly key: string;
+    readonly status: HarnessRunStatus;
+    readonly attempts: number;
+    readonly inputBytes: number;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    /** Redacted stable classification; no provider body, URL, header, or tool payload is retained. */
+    readonly failureCode?: string;
+}
+export interface HarnessRunAcceptance {
+    readonly runId: string;
+    readonly duplicate: boolean;
+    readonly status: HarnessRunStatus;
+}
+export interface HarnessRunListOptions {
+    readonly limit?: number;
+    readonly status?: HarnessRunStatus;
+}
+export interface HarnessRunAcceptanceOptions {
+    readonly key: string;
+    /** Evaluated inside the durable admission transaction before a run is inserted. */
+    readonly admit?: () => boolean;
+    /** Exact actor-journal boundary captured before this run can begin execution. */
+    readonly journalSeq?: number;
+}
+/** Internal control signal: the caller's durable admission fence rejected this run. */
+export declare class HarnessAdmissionRejected extends Error {
+    constructor();
+}
+export interface HarnessRunLedger {
+    accept(input: string, options: HarnessRunAcceptanceOptions): Promise<HarnessRunAcceptance>;
+    get(runId: string): Promise<HarnessRun | undefined>;
+    status(runId: string): Promise<HarnessRunStatus | undefined>;
+    list(options?: HarnessRunListOptions): Promise<readonly HarnessRun[]>;
+    cancel(runId: string): Promise<HarnessRun | undefined>;
+    /** Re-enqueue accepted and interrupted runs. Recovery is at-least-once, never exactly-once. */
+    recover(): Promise<number>;
+    /** Claim and execute an admitted run; host task handlers call this with their durable run id. */
+    run(runId: string): Promise<HarnessRun | undefined>;
+    /** Execute one task emitted by `accept()` after validating its private harness envelope. */
+    dispatch(task: Readonly<Pick<TaskRecord, "name" | "payload">>): Promise<HarnessRun | undefined>;
+}
+interface HarnessRunExecutionLedger extends HarnessRunLedger {
+    /** Private dispatch fence: only the attested approval batch can claim a continuation. */
+    run(runId: string, resumeBatch?: string): Promise<HarnessRun | undefined>;
+    resume(runId: string): Promise<HarnessRun | undefined>;
+    pauseForApproval(runId: string): void;
+    resumeForApproval(runId: string): void;
+    cancelForApproval(runId: string): void;
+    expireForApproval(runId: string): Promise<void>;
+    cleanupCanceledRun(runId: string): Promise<void>;
+}
+export type HarnessCheckpoint = (point: "before_effect" | "after_effect_before_memo" | "after_memo" | "before_final_run_commit") => void;
+/** Internal deterministic crash signal. It intentionally leaves durable state at the interrupted boundary. */
+export declare class HarnessInjectedCrash extends Error {
+    constructor(cause: unknown);
+}
+/** Internal control signal: approval state was durably recorded before pausing. */
+export declare class HarnessApprovalPause extends Error {
+    constructor();
+}
+/** Internal schedule-only rollback signal that never inspects arbitrary caught errors. */
+export declare function createScheduleAdmissionRollbackError(step: string, cause: unknown): Error;
+export interface HarnessRunLedgerOptions {
+    /** Deterministic test seam for crash-window recovery coverage. */
+    readonly checkpoints?: HarnessCheckpoint;
+    /** Approval-capable harnesses bind admission to a host-attested subject. */
+    readonly requireApprovalIdentity?: boolean;
+}
+export declare function ensureHarnessDurabilitySchema(ports: AgentHarnessPorts): void;
+export declare function createHarnessRunLedger(ports: AgentHarnessPorts, execute: (input: string, signal: AbortSignal, steps: HarnessStepContext) => Promise<unknown>, options?: HarnessRunLedgerOptions): HarnessRunLedger;
+export declare function createHarnessRunExecutionLedger(ports: AgentHarnessPorts, execute: (input: string, signal: AbortSignal, steps: HarnessStepContext) => Promise<unknown>, options?: HarnessRunLedgerOptions): HarnessRunExecutionLedger;
+export {};
+//# sourceMappingURL=durable.d.ts.map