@telnyx/agent-harness 0.1.0-beta.0

package/dist/durable.js

@@ -0,0 +1,650 @@
+import { createHash } from "node:crypto";
+import { AGENT_HARNESS_PORTS_VERSION } from "./ports.js";
+import { createHarnessStepContext } from "./steps.js";
+export const HARNESS_RUN_STATUSES = ["accepted", "running", "awaiting_approval", "resume_pending", "completed", "failed", "canceled", "outcome_unknown"];
+/** Internal control signal: the caller's durable admission fence rejected this run. */
+export class HarnessAdmissionRejected extends Error {
+    constructor() {
+        super("harness admission was rejected by its durable fence");
+        this.name = "HarnessAdmissionRejected";
+    }
+}
+/** Internal deterministic crash signal. It intentionally leaves durable state at the interrupted boundary. */
+export class HarnessInjectedCrash extends Error {
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : "injected crash");
+        this.name = "HarnessInjectedCrash";
+    }
+}
+/** Internal control signal: approval state was durably recorded before pausing. */
+export class HarnessApprovalPause extends Error {
+    constructor() {
+        super("Harness run is awaiting durable approval");
+        this.name = "HarnessApprovalPause";
+    }
+}
+const scheduleRollbackSteps = new WeakMap();
+/** Internal schedule-only rollback signal that never inspects arbitrary caught errors. */
+export function createScheduleAdmissionRollbackError(step, cause) {
+    const error = new Error("schedule admission rolled back", { cause });
+    scheduleRollbackSteps.set(error, step);
+    return error;
+}
+function scheduleRollbackStep(error) {
+    return error !== null && typeof error === "object" ? scheduleRollbackSteps.get(error) : undefined;
+}
+// v6 owns the whole private approval topology. Keeping every table in this
+// transaction prevents a run schema from claiming v6 while approval linkage,
+// envelopes, or audit history are missing or from another protocol.
+const APPROVAL_SCHEMA_VERSION = 6;
+// v7 records the run-owned sequence for the admitted input. v8 adds an
+// out-of-band durable tool-output failure marker.
+const SCHEMA_VERSION = 8;
+const MAX_INPUT_BYTES = 64 * 1024;
+const MAX_KEY_BYTES = 512;
+const TASK_METHOD = "__telnyx_agent_harness_run";
+const APPROVAL_RESUME_TASK_METHOD = "__telnyx_agent_harness_approval_resume";
+const SAFE_FAILURE_CODES = new Set([
+    "HARNESS_CANCELLED",
+    "HARNESS_OBSERVER_ERROR",
+    "HARNESS_PROVIDER_ERROR",
+    "HARNESS_STEP_LIMIT",
+    "HARNESS_TOOL_OUTPUT_ERROR",
+    "HARNESS_APPROVAL_INVALID",
+]);
+function first(rows) { return rows[0]; }
+function requireBoundedString(value, name, limit) {
+    if (Buffer.byteLength(value, "utf8") > limit)
+        throw new Error(`${name} exceeds ${limit} UTF-8 bytes`);
+}
+function requireNonblankBoundedString(value, name, limit) {
+    if (!value.trim())
+        throw new Error(`${name} must not be blank`);
+    requireBoundedString(value, name, limit);
+}
+function failureCode(error) {
+    try {
+        if (error !== null && typeof error === "object") {
+            const code = error.code;
+            if (code === "expired")
+                return "HARNESS_APPROVAL_EXPIRED";
+            if (code === "forbidden" || code === "unauthenticated" || code === "identity_unavailable")
+                return "HARNESS_AUTHORIZATION_REVOKED";
+            if (code === "missing" || code === "replayed" || code === "conflicting" || code === "consumed")
+                return "HARNESS_APPROVAL_INVALID";
+            if (typeof code === "string" && SAFE_FAILURE_CODES.has(code))
+                return code;
+        }
+    }
+    catch {
+        // Executor-thrown objects may expose hostile getters or Proxy traps.
+    }
+    return "HARNESS_RUN_FAILED";
+}
+function isPolicyUnavailable(error) {
+    try {
+        return error !== null && typeof error === "object" && error.code === "policy_unavailable";
+    }
+    catch {
+        return false;
+    }
+}
+function dispatchedRun(task) {
+    if (task.name !== TASK_METHOD && task.name !== APPROVAL_RESUME_TASK_METHOD)
+        throw new Error("task is not a harness run task");
+    if (task.payload === null || typeof task.payload !== "object" || Array.isArray(task.payload)) {
+        throw new Error("harness run task payload is invalid");
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(task.payload, "runId");
+    if (descriptor === undefined || !("value" in descriptor) || typeof descriptor.value !== "string" || !descriptor.value) {
+        throw new Error("harness run task payload is invalid");
+    }
+    if (task.name === TASK_METHOD)
+        return Object.freeze({ runId: descriptor.value });
+    const batch = Object.getOwnPropertyDescriptor(task.payload, "batch");
+    if (batch === undefined || !("value" in batch) || typeof batch.value !== "string" || !/^[a-f0-9]{64}$/.test(batch.value)) {
+        throw new Error("harness approval resume task payload is invalid");
+    }
+    return Object.freeze({ runId: descriptor.value, batch: batch.value });
+}
+function publicRun(row) {
+    return Object.freeze({
+        id: row.id, key: row.key, status: row.status, attempts: row.attempts,
+        inputBytes: row.input_bytes, createdAt: row.created_at, updatedAt: row.updated_at,
+        ...(row.failure_code === null ? {} : { failureCode: row.failure_code }),
+    });
+}
+function createV6ApprovalTopology(ports) {
+    ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_run_authority (run_id TEXT PRIMARY KEY NOT NULL, service_account_id TEXT NOT NULL, organization_id TEXT NOT NULL, required_action TEXT NOT NULL, FOREIGN KEY(run_id) REFERENCES __telnyx_agent_harness_runs(id))");
+    ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_approvals (id TEXT PRIMARY KEY, run_id TEXT NOT NULL, tool_name TEXT NOT NULL, tool_call_id TEXT NOT NULL, arguments TEXT NOT NULL, required_action TEXT NOT NULL, service_account_id TEXT NOT NULL, organization_id TEXT NOT NULL, status TEXT NOT NULL CHECK(status IN ('pending','granted','denied','expired','consumed')), expires_at INTEGER NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, UNIQUE(run_id,tool_call_id))");
+    ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_approval_audit (id TEXT PRIMARY KEY, approval_id TEXT NOT NULL, event TEXT NOT NULL, actor TEXT, action TEXT, outcome TEXT, at INTEGER NOT NULL, seq INTEGER NOT NULL DEFAULT 0, FOREIGN KEY(approval_id) REFERENCES __telnyx_agent_harness_approvals(id))");
+    // COMPUTE-904: Add the monotonic seq column to existing audit tables.
+    const auditColumns = new Set((ports.sql.exec("PRAGMA table_info('__telnyx_agent_harness_approval_audit')").toArray()).map((column) => column.name));
+    if (!auditColumns.has("seq"))
+        ports.sql.exec("ALTER TABLE __telnyx_agent_harness_approval_audit ADD COLUMN seq INTEGER NOT NULL DEFAULT 0");
+    ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_approval_messages (approval_id TEXT PRIMARY KEY, codec_version INTEGER NOT NULL CHECK(codec_version = 1), run_id TEXT NOT NULL, tool_call_id TEXT NOT NULL, tool_name TEXT NOT NULL, journal_seq INTEGER NOT NULL CHECK(journal_seq >= 0), after_message_seq INTEGER NOT NULL CHECK(after_message_seq >= 0), approval_epoch INTEGER NOT NULL CHECK(approval_epoch >= 0), canonical_tool_call TEXT NOT NULL, signature TEXT, approved INTEGER, reason TEXT, response_at INTEGER, UNIQUE(run_id,tool_call_id,journal_seq))");
+    ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_approval_linkage (approval_id TEXT PRIMARY KEY, run_id TEXT NOT NULL, approval_epoch INTEGER NOT NULL CHECK(approval_epoch >= 0), tool_name TEXT NOT NULL, ordinal INTEGER NOT NULL CHECK(ordinal >= 0), journal_marker TEXT NOT NULL, provider_call_id TEXT NOT NULL, private_sequence INTEGER NOT NULL CHECK(private_sequence >= 0), canonical_tool_call TEXT NOT NULL, FOREIGN KEY(approval_id) REFERENCES __telnyx_agent_harness_approvals(id), FOREIGN KEY(run_id) REFERENCES __telnyx_agent_harness_runs(id))");
+}
+export function ensureHarnessDurabilitySchema(ports) {
+    ports.sql.transactionSync(() => {
+        ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_schema (version INTEGER PRIMARY KEY)");
+        const version = first(ports.sql.exec("SELECT version FROM __telnyx_agent_harness_schema ORDER BY version DESC LIMIT 1").toArray())?.version;
+        if (version !== undefined && version > SCHEMA_VERSION) {
+            throw new Error("harness ledger schema is newer than this harness");
+        }
+        if (version !== undefined && version < 1) {
+            throw new Error("harness ledger schema migration is unavailable");
+        }
+        let currentVersion = version;
+        let rebuiltV4ChildLedger = false;
+        if (currentVersion === undefined) {
+            ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_runs (id TEXT PRIMARY KEY, key TEXT NOT NULL UNIQUE, input TEXT NOT NULL, input_bytes INTEGER NOT NULL, status TEXT NOT NULL CHECK(status IN ('accepted','running','awaiting_approval','resume_pending','completed','failed','canceled','outcome_unknown')), attempts INTEGER NOT NULL, task_id TEXT NOT NULL UNIQUE, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, failure_code TEXT)");
+            ports.sql.exec("INSERT INTO __telnyx_agent_harness_schema(version) VALUES (?)", SCHEMA_VERSION);
+            currentVersion = SCHEMA_VERSION;
+        }
+        else if (currentVersion === 1) {
+            ports.sql.exec("CREATE TABLE __telnyx_agent_harness_runs_v2 (id TEXT PRIMARY KEY, key TEXT NOT NULL UNIQUE, input TEXT NOT NULL, input_bytes INTEGER NOT NULL, status TEXT NOT NULL CHECK(status IN ('accepted','running','completed','failed','canceled','outcome_unknown')), attempts INTEGER NOT NULL, task_id TEXT NOT NULL UNIQUE, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, failure_code TEXT)");
+            ports.sql.exec("INSERT INTO __telnyx_agent_harness_runs_v2 SELECT id,key,input,input_bytes,status,attempts,task_id,created_at,updated_at,failure_code FROM __telnyx_agent_harness_runs");
+            ports.sql.exec("DROP TABLE __telnyx_agent_harness_runs");
+            ports.sql.exec("ALTER TABLE __telnyx_agent_harness_runs_v2 RENAME TO __telnyx_agent_harness_runs");
+            ports.sql.exec("UPDATE __telnyx_agent_harness_schema SET version = 2");
+            currentVersion = 2;
+        }
+        if (currentVersion !== undefined && currentVersion < APPROVAL_SCHEMA_VERSION) {
+            // Every pre-v6 run ledger has the legacy status CHECK. SQLite CHECK
+            // constraints cannot be altered in place, so rebuild it before v6
+            // introduces approval-only states. A populated child ledger would retain
+            // a foreign key to the dropped table; reject it before any migration
+            // write so callers can reconcile that history without partial state.
+            const childTables = [
+                "__telnyx_agent_harness_steps",
+                "__telnyx_agent_harness_tool_positions",
+                "__telnyx_agent_harness_tool_calls",
+                "__telnyx_agent_harness_run_authority",
+                "__telnyx_agent_harness_approvals",
+                "__telnyx_agent_harness_approval_messages",
+                "__telnyx_agent_harness_approval_audit",
+                "__telnyx_agent_harness_approval_linkage",
+            ];
+            const v4OwnedChildren = new Set([
+                "__telnyx_agent_harness_steps",
+                "__telnyx_agent_harness_tool_positions",
+                "__telnyx_agent_harness_tool_calls",
+            ]);
+            for (const table of childTables) {
+                const exists = ports.sql.exec("SELECT 1 AS present FROM sqlite_master WHERE type = 'table' AND name = ?", table).toArray().length > 0;
+                if ((currentVersion !== 4 || !v4OwnedChildren.has(table)) && exists && ports.sql.exec(`SELECT 1 AS present FROM ${table} LIMIT 1`).toArray().length > 0) {
+                    throw new Error(`cannot migrate populated v${currentVersion} run ledger with child rows`);
+                }
+            }
+            ports.sql.exec("CREATE TABLE __telnyx_agent_harness_runs_v6 (id TEXT PRIMARY KEY, key TEXT NOT NULL UNIQUE, input TEXT NOT NULL, input_bytes INTEGER NOT NULL, status TEXT NOT NULL CHECK(status IN ('accepted','running','awaiting_approval','resume_pending','completed','failed','canceled','outcome_unknown')), attempts INTEGER NOT NULL, task_id TEXT NOT NULL UNIQUE, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, failure_code TEXT)");
+            ports.sql.exec("INSERT INTO __telnyx_agent_harness_runs_v6 SELECT id,key,input,input_bytes,status,attempts,task_id,created_at,updated_at,failure_code FROM __telnyx_agent_harness_runs");
+            if (currentVersion === 4) {
+                // v4 has a known, fully-owned child topology. Rebuild each child table
+                // against the v6 parent in this transaction, retaining its rows so the
+                // existing NULL-marker quarantine can run below without losing history.
+                ports.sql.exec("CREATE TABLE __telnyx_agent_harness_steps_v6 (run_id TEXT NOT NULL, name TEXT NOT NULL, identity TEXT NOT NULL, input_fingerprint TEXT NOT NULL, version TEXT NOT NULL, status TEXT NOT NULL CHECK(status IN ('prepared','effect_started','completed')), output TEXT, journal_seq INTEGER NOT NULL, PRIMARY KEY(run_id,name), UNIQUE(run_id,journal_seq), FOREIGN KEY(run_id) REFERENCES __telnyx_agent_harness_runs_v6(id))");
+                ports.sql.exec("INSERT INTO __telnyx_agent_harness_steps_v6 SELECT run_id,name,identity,input_fingerprint,version,status,output,journal_seq FROM __telnyx_agent_harness_steps");
+                ports.sql.exec("CREATE TABLE __telnyx_agent_harness_tool_positions_v6 (run_id TEXT NOT NULL, tool_name TEXT NOT NULL, committed_count INTEGER NOT NULL CHECK(committed_count >= 0), PRIMARY KEY(run_id,tool_name), FOREIGN KEY(run_id) REFERENCES __telnyx_agent_harness_runs_v6(id))");
+                ports.sql.exec("INSERT INTO __telnyx_agent_harness_tool_positions_v6 SELECT run_id,tool_name,committed_count FROM __telnyx_agent_harness_tool_positions");
+                ports.sql.exec("CREATE TABLE __telnyx_agent_harness_tool_calls_v6 (run_id TEXT NOT NULL, tool_name TEXT NOT NULL, ordinal INTEGER NOT NULL CHECK(ordinal >= 0), provider_call_id TEXT, journal_marker TEXT, PRIMARY KEY(run_id,tool_name,ordinal), FOREIGN KEY(run_id) REFERENCES __telnyx_agent_harness_runs_v6(id))");
+                ports.sql.exec("INSERT INTO __telnyx_agent_harness_tool_calls_v6(run_id,tool_name,ordinal,provider_call_id) SELECT run_id,tool_name,ordinal,provider_call_id FROM __telnyx_agent_harness_tool_calls");
+                ports.sql.exec("DROP TABLE __telnyx_agent_harness_steps");
+                ports.sql.exec("DROP TABLE __telnyx_agent_harness_tool_positions");
+                ports.sql.exec("DROP TABLE __telnyx_agent_harness_tool_calls");
+                rebuiltV4ChildLedger = true;
+            }
+            ports.sql.exec("DROP TABLE __telnyx_agent_harness_runs");
+            ports.sql.exec("ALTER TABLE __telnyx_agent_harness_runs_v6 RENAME TO __telnyx_agent_harness_runs");
+            if (rebuiltV4ChildLedger) {
+                ports.sql.exec("ALTER TABLE __telnyx_agent_harness_steps_v6 RENAME TO __telnyx_agent_harness_steps");
+                ports.sql.exec("ALTER TABLE __telnyx_agent_harness_tool_positions_v6 RENAME TO __telnyx_agent_harness_tool_positions");
+                ports.sql.exec("ALTER TABLE __telnyx_agent_harness_tool_calls_v6 RENAME TO __telnyx_agent_harness_tool_calls");
+            }
+        }
+        if (currentVersion !== undefined && currentVersion < APPROVAL_SCHEMA_VERSION) {
+            // Approval records are v6-owned. Empty pre-v6 tables have no history to
+            // preserve, so replace them instead of stamping their incomplete shapes.
+            // Populated variants are rejected above before any migration write.
+            for (const table of [
+                "__telnyx_agent_harness_approval_linkage",
+                "__telnyx_agent_harness_approval_messages",
+                "__telnyx_agent_harness_approval_audit",
+                "__telnyx_agent_harness_approvals",
+                "__telnyx_agent_harness_run_authority",
+            ])
+                ports.sql.exec(`DROP TABLE IF EXISTS ${table}`);
+        }
+        ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_steps (run_id TEXT NOT NULL, name TEXT NOT NULL, identity TEXT NOT NULL, input_fingerprint TEXT NOT NULL, version TEXT NOT NULL, status TEXT NOT NULL CHECK(status IN ('prepared','effect_started','completed')), output TEXT, output_failure TEXT, journal_seq INTEGER NOT NULL, PRIMARY KEY(run_id,name), UNIQUE(run_id,journal_seq), FOREIGN KEY(run_id) REFERENCES __telnyx_agent_harness_runs(id))");
+        const stepColumns = ports.sql.exec("PRAGMA table_info(__telnyx_agent_harness_steps)").toArray();
+        if (!stepColumns.some((column) => column.name === "output_failure")) {
+            ports.sql.exec("ALTER TABLE __telnyx_agent_harness_steps ADD COLUMN output_failure TEXT");
+        }
+        if (currentVersion === 4) {
+            if (!rebuiltV4ChildLedger)
+                ports.sql.exec("ALTER TABLE __telnyx_agent_harness_tool_calls ADD COLUMN journal_marker TEXT");
+            // A v4 tool-call row has no harness-owned journal marker. After migration
+            // its journal_marker is NULL, which v5 treats as "pending" (not journaled).
+            // A nonterminal run with such a row could silently replay a stale memo
+            // (the provider legitimately re-emits the same tool/input, and the NULL
+            // marker lets nextToolCallOrdinal reuse the ordinal). Because v4 history
+            // has no harness-controlled marker and actor-global provider IDs are not
+            // authoritative, the journal state of these rows cannot be safely
+            // determined. Fail-closed: quarantine nonterminal runs that have v4
+            // tool-call rows as outcome_unknown before they can reuse a memo.
+            ports.sql.exec("UPDATE __telnyx_agent_harness_runs SET status = 'outcome_unknown', failure_code = 'HARNESS_OUTCOME_UNKNOWN', updated_at = ? WHERE status IN ('accepted','running') AND id IN (SELECT DISTINCT run_id FROM __telnyx_agent_harness_tool_calls)", ports.clock.now());
+            ports.sql.exec("UPDATE __telnyx_agent_harness_schema SET version = ?", APPROVAL_SCHEMA_VERSION);
+        }
+        else if (currentVersion === 2 || currentVersion === 3 || currentVersion === 5)
+            ports.sql.exec("UPDATE __telnyx_agent_harness_schema SET version = ?", APPROVAL_SCHEMA_VERSION);
+        ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_tool_positions (run_id TEXT NOT NULL, tool_name TEXT NOT NULL, committed_count INTEGER NOT NULL CHECK(committed_count >= 0), PRIMARY KEY(run_id,tool_name), FOREIGN KEY(run_id) REFERENCES __telnyx_agent_harness_runs(id))");
+        ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_tool_calls (run_id TEXT NOT NULL, tool_name TEXT NOT NULL, ordinal INTEGER NOT NULL CHECK(ordinal >= 0), provider_call_id TEXT, journal_marker TEXT, PRIMARY KEY(run_id,tool_name,ordinal), FOREIGN KEY(run_id) REFERENCES __telnyx_agent_harness_runs(id))");
+        // A harness turn records its final actor-journal boundary before the run
+        // completion transaction. Consumers that correlate durable admissions must
+        // join through this run-scoped marker, never infer from actor-global state.
+        ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_run_journal (run_id TEXT PRIMARY KEY NOT NULL, journal_seq INTEGER NOT NULL CHECK(journal_seq >= 0), FOREIGN KEY(run_id) REFERENCES __telnyx_agent_harness_runs(id))");
+        // Reserve the exact sequence where this run's admitted input belongs before
+        // appending it. Recovery can then determine whether the append committed.
+        ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_run_inputs (run_id TEXT PRIMARY KEY NOT NULL, journal_seq INTEGER NOT NULL CHECK(journal_seq > 0), FOREIGN KEY(run_id) REFERENCES __telnyx_agent_harness_runs(id))");
+        // v6 has no run-owned input boundary. Keep nonterminal v6 runs and accepted
+        // runs with a prior attempt in explicit migration state rather than
+        // interpreting a missing v7 marker as proof their input was never appended.
+        // The turn path can backfill only an exact tail match; every other legacy
+        // state fails closed. A never-attempted accepted run remains a fresh input.
+        ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_legacy_run_inputs (run_id TEXT PRIMARY KEY NOT NULL, FOREIGN KEY(run_id) REFERENCES __telnyx_agent_harness_runs(id))");
+        if (currentVersion !== undefined && currentVersion < SCHEMA_VERSION) {
+            ports.sql.exec("INSERT OR IGNORE INTO __telnyx_agent_harness_legacy_run_inputs(run_id) SELECT id FROM __telnyx_agent_harness_runs WHERE status IN ('running','awaiting_approval','resume_pending') OR (status = 'accepted' AND attempts > 0)");
+        }
+        createV6ApprovalTopology(ports);
+        ports.sql.exec("UPDATE __telnyx_agent_harness_schema SET version = ? WHERE version < ?", SCHEMA_VERSION, SCHEMA_VERSION);
+    });
+}
+const activeControllersByActivation = new WeakMap();
+function activeControllers(ports) {
+    let controllers = activeControllersByActivation.get(ports.activation);
+    if (controllers === undefined) {
+        controllers = new Map();
+        activeControllersByActivation.set(ports.activation, controllers);
+    }
+    return controllers;
+}
+function assertDurableAdmissionPorts(ports) {
+    if (ports.version !== AGENT_HARNESS_PORTS_VERSION) {
+        throw new Error(`AgentHarnessPorts v${AGENT_HARNESS_PORTS_VERSION} is required for durable admission`);
+    }
+    if (ports.activation === null || (typeof ports.activation !== "object" && typeof ports.activation !== "function")) {
+        throw new Error("AgentHarnessPorts activation must be a host-owned object");
+    }
+}
+export function createHarnessRunLedger(ports, execute, options = {}) {
+    const execution = createHarnessRunExecutionLedger(ports, execute, options);
+    return Object.freeze({
+        accept: execution.accept,
+        get: execution.get,
+        status: execution.status,
+        list: execution.list,
+        cancel: execution.cancel,
+        recover: execution.recover,
+        run: execution.run,
+        dispatch: execution.dispatch,
+    });
+}
+export function createHarnessRunExecutionLedger(ports, execute, options = {}) {
+    let initialized = false;
+    let controllers;
+    const ensureInitialized = () => {
+        if (initialized)
+            return;
+        assertDurableAdmissionPorts(ports);
+        ensureHarnessDurabilitySchema(ports);
+        controllers = activeControllers(ports);
+        initialized = true;
+    };
+    // Port wrappers from one live activation share claims. A fresh activation has
+    // no in-memory claim and deliberately replays interrupted work.
+    const active = () => {
+        if (controllers === undefined)
+            throw new Error("harness ledger is not initialized");
+        return controllers;
+    };
+    const read = (runId) => first(ports.sql.exec("SELECT id,key,input,input_bytes,status,attempts,task_id,created_at,updated_at,failure_code FROM __telnyx_agent_harness_runs WHERE id = ?", runId).toArray());
+    const approvalRunReady = (runId) => {
+        const approvals = ports.sql.exec("SELECT approvals.id FROM __telnyx_agent_harness_approvals AS approvals JOIN __telnyx_agent_harness_approval_messages AS messages ON messages.approval_id = approvals.id WHERE approvals.run_id = ? AND messages.run_id = ? AND messages.approval_epoch = (SELECT MAX(approval_epoch) FROM __telnyx_agent_harness_approval_messages WHERE run_id = ?)", runId, runId, runId).toArray();
+        if (approvals.length === 0)
+            return false;
+        const messages = ports.sql.exec("SELECT approval_id FROM __telnyx_agent_harness_approval_messages WHERE run_id = ? AND approval_epoch = (SELECT MAX(approval_epoch) FROM __telnyx_agent_harness_approval_messages WHERE run_id = ?)", runId, runId).toArray();
+        if (messages.length !== approvals.length)
+            return false;
+        const incompleteApproval = ports.sql.exec("SELECT approvals.id FROM __telnyx_agent_harness_approvals AS approvals JOIN __telnyx_agent_harness_approval_messages AS messages ON messages.approval_id = approvals.id WHERE approvals.run_id = ? AND messages.run_id = ? AND messages.approval_epoch = (SELECT MAX(approval_epoch) FROM __telnyx_agent_harness_approval_messages WHERE run_id = ?) AND approvals.status NOT IN ('granted','denied') LIMIT 1", runId, runId, runId).toArray()[0];
+        const incompleteResponse = ports.sql.exec("SELECT approval_id FROM __telnyx_agent_harness_approval_messages WHERE run_id = ? AND approval_epoch = (SELECT MAX(approval_epoch) FROM __telnyx_agent_harness_approval_messages WHERE run_id = ?) AND approved IS NULL LIMIT 1", runId, runId).toArray()[0];
+        const invalidLinkage = ports.sql.exec("SELECT messages.approval_id FROM __telnyx_agent_harness_approval_messages AS messages LEFT JOIN __telnyx_agent_harness_approval_linkage AS linkage ON linkage.approval_id = messages.approval_id WHERE messages.run_id = ? AND messages.approval_epoch = (SELECT MAX(approval_epoch) FROM __telnyx_agent_harness_approval_messages WHERE run_id = ?) AND (linkage.approval_id IS NULL OR linkage.run_id <> messages.run_id OR linkage.approval_epoch <> messages.approval_epoch OR linkage.tool_name <> messages.tool_name OR linkage.provider_call_id <> messages.tool_call_id OR linkage.private_sequence <> messages.journal_seq OR linkage.ordinal <> messages.journal_seq OR linkage.journal_marker <> ('approval:' || messages.approval_id || ':' || messages.journal_seq) OR linkage.canonical_tool_call <> messages.canonical_tool_call) LIMIT 1", runId, runId).toArray()[0];
+        return incompleteApproval === undefined && incompleteResponse === undefined && invalidLinkage === undefined;
+    };
+    const approvalResumeBatch = (runId) => {
+        if (!approvalRunReady(runId))
+            return undefined;
+        const rows = ports.sql.exec("SELECT approvals.id,messages.approval_epoch FROM __telnyx_agent_harness_approvals AS approvals JOIN __telnyx_agent_harness_approval_messages AS messages ON messages.approval_id = approvals.id WHERE approvals.run_id = ? AND messages.run_id = ? AND messages.approval_epoch = (SELECT MAX(approval_epoch) FROM __telnyx_agent_harness_approval_messages WHERE run_id = ?) AND approvals.status IN ('granted','denied') AND messages.approved IS NOT NULL ORDER BY approvals.id", runId, runId, runId).toArray();
+        if (rows.length === 0)
+            return undefined;
+        return createHash("sha256").update([runId, String(rows[0].approval_epoch), ...rows.map((row) => row.id)].join("\0")).digest("hex");
+    };
+    const enqueue = async (run) => {
+        if (run.status !== "accepted")
+            return;
+        await ports.tasks.queue(TASK_METHOD, { runId: run.id }, { id: run.task_id, maxRetries: 5 });
+    };
+    const enqueueApprovalResume = async (run) => {
+        if (run.status !== "resume_pending")
+            return;
+        const batch = approvalResumeBatch(run.id);
+        if (batch === undefined)
+            return;
+        await ports.tasks.queue(APPROVAL_RESUME_TASK_METHOD, { runId: run.id, batch }, {
+            id: `${APPROVAL_RESUME_TASK_METHOD}/${batch}`,
+            maxRetries: 5,
+        });
+    };
+    let ledger;
+    ledger = {
+        async accept(input, acceptance) {
+            ensureInitialized();
+            requireBoundedString(input, "input", MAX_INPUT_BYTES);
+            requireNonblankBoundedString(acceptance.key, "idempotency key", MAX_KEY_BYTES);
+            const admission = ports.sql.transactionSync(() => {
+                const existing = first(ports.sql.exec("SELECT id,key,input,input_bytes,status,attempts,task_id,created_at,updated_at,failure_code FROM __telnyx_agent_harness_runs WHERE key = ?", acceptance.key).toArray());
+                if (existing !== undefined) {
+                    if (existing.input !== input)
+                        throw new Error("idempotency key is already bound to different input");
+                    return Object.freeze({ run: existing, duplicate: true });
+                }
+                if (acceptance.admit !== undefined && !acceptance.admit())
+                    throw new HarnessAdmissionRejected();
+                const now = ports.clock.now();
+                const id = `run-${ports.identity.id}-${now}-${crypto.randomUUID()}`;
+                const run = Object.freeze({
+                    id, key: acceptance.key, input, input_bytes: Buffer.byteLength(input, "utf8"), status: "accepted",
+                    attempts: 0, task_id: `${TASK_METHOD}/${id}`, created_at: now, updated_at: now, failure_code: null,
+                });
+                ports.sql.exec("INSERT INTO __telnyx_agent_harness_runs(id,key,input,input_bytes,status,attempts,task_id,created_at,updated_at,failure_code) VALUES (?,?,?,?,?,?,?,?,?,?)", run.id, run.key, run.input, run.input_bytes, run.status, run.attempts, run.task_id, run.created_at, run.updated_at, run.failure_code);
+                if (acceptance.journalSeq !== undefined) {
+                    if (!Number.isSafeInteger(acceptance.journalSeq) || acceptance.journalSeq < 0)
+                        throw new Error("journal sequence is invalid");
+                    ports.sql.exec("INSERT INTO __telnyx_agent_harness_run_journal(run_id,journal_seq) VALUES (?,?)", run.id, acceptance.journalSeq);
+                }
+                const identity = ports.authorization?.identity();
+                if (options.requireApprovalIdentity && identity === undefined) {
+                    throw Object.assign(new Error("Harness authorization identity_unavailable"), { code: "identity_unavailable" });
+                }
+                if (identity !== undefined) {
+                    requireNonblankBoundedString(identity.serviceAccountId, "service account id", MAX_KEY_BYTES);
+                    requireNonblankBoundedString(identity.organizationId, "organization id", MAX_KEY_BYTES);
+                    ports.sql.exec("INSERT INTO __telnyx_agent_harness_run_authority(run_id,service_account_id,organization_id,required_action) VALUES (?,?,?,?)", run.id, identity.serviceAccountId, identity.organizationId, "agent_harness.run");
+                }
+                return Object.freeze({ run, duplicate: false });
+            });
+            // This is intentionally outside the SQL transaction: a queue failure leaves an accepted record for recover().
+            await enqueue(admission.run);
+            return Object.freeze({ runId: admission.run.id, duplicate: admission.duplicate, status: admission.run.status });
+        },
+        async get(runId) {
+            ensureInitialized();
+            const run = read(runId);
+            return run === undefined ? undefined : publicRun(run);
+        },
+        async status(runId) {
+            ensureInitialized();
+            return read(runId)?.status;
+        },
+        async list(options = {}) {
+            ensureInitialized();
+            const limit = options.limit ?? 100;
+            if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1_000)
+                throw new Error("list limit must be 1..1000");
+            const rows = options.status === undefined
+                ? ports.sql.exec("SELECT id,key,input,input_bytes,status,attempts,task_id,created_at,updated_at,failure_code FROM __telnyx_agent_harness_runs ORDER BY created_at,id LIMIT ?", limit).toArray()
+                : ports.sql.exec("SELECT id,key,input,input_bytes,status,attempts,task_id,created_at,updated_at,failure_code FROM __telnyx_agent_harness_runs WHERE status = ? ORDER BY created_at,id LIMIT ?", options.status, limit).toArray();
+            return Object.freeze(rows.map(publicRun));
+        },
+        async cancel(runId) {
+            ensureInitialized();
+            const preExecutionCancellation = read(runId)?.status === "accepted";
+            const canceled = ports.sql.transactionSync(() => {
+                const current = read(runId);
+                if (current === undefined || current.status === "completed" || current.status === "failed" || current.status === "canceled" || current.status === "outcome_unknown")
+                    return current;
+                const externalEffectStarted = ports.sql.exec("SELECT run_id FROM __telnyx_agent_harness_steps WHERE run_id = ? AND status = 'effect_started' LIMIT 1", runId).toArray().length > 0;
+                if (externalEffectStarted) {
+                    ports.sql.exec("UPDATE __telnyx_agent_harness_runs SET status = 'outcome_unknown', failure_code = 'HARNESS_OUTCOME_UNKNOWN', updated_at = ? WHERE id = ? AND status IN ('accepted','running','awaiting_approval','resume_pending')", ports.clock.now(), runId);
+                }
+                else {
+                    ports.sql.exec("UPDATE __telnyx_agent_harness_runs SET status = 'canceled', updated_at = ? WHERE id = ? AND status IN ('accepted','running','awaiting_approval','resume_pending')", ports.clock.now(), runId);
+                    if (current.status === "accepted") {
+                        // An accepted run has not entered execution, so sequence zero is
+                        // its exact run-owned pre-execution boundary. Commit it with the
+                        // terminal state so a read fault cannot lose correlation.
+                        ports.sql.exec("INSERT INTO __telnyx_agent_harness_run_journal(run_id,journal_seq) VALUES (?,0) ON CONFLICT(run_id) DO NOTHING", runId);
+                    }
+                }
+                return read(runId);
+            });
+            if (canceled === undefined)
+                return undefined;
+            active().get(runId)?.abort();
+            // Queue cancellation is best-effort; the durable canceled state fences later delivery.
+            try {
+                await ports.tasks.cancel(canceled.task_id);
+            }
+            catch { /* durable state is authoritative */ }
+            if (canceled.status === "canceled" && !preExecutionCancellation) {
+                // An executing or resumed run can already own journal entries, so
+                // preserve the existing exact-boundary capture after it is fenced.
+                // The terminal durable state is authoritative; recovery can repair
+                // this correlation if the journal read is temporarily unavailable.
+                try {
+                    const journalBoundary = await ports.messages.count();
+                    ports.sql.transactionSync(() => ports.sql.exec("INSERT INTO __telnyx_agent_harness_run_journal(run_id,journal_seq) VALUES (?,?) ON CONFLICT(run_id) DO NOTHING", runId, journalBoundary));
+                }
+                catch { /* retain durable cancellation; correlation is repairable */ }
+            }
+            return publicRun(canceled);
+        },
+        async recover() {
+            ensureInitialized();
+            const recovered = ports.sql.transactionSync(() => {
+                const uncertain = ports.sql.exec("SELECT DISTINCT runs.id FROM __telnyx_agent_harness_runs AS runs JOIN __telnyx_agent_harness_steps AS steps ON steps.run_id = runs.id WHERE runs.status IN ('accepted','running') AND steps.status = 'effect_started'").toArray();
+                for (const run of uncertain) {
+                    if (active().has(run.id))
+                        continue;
+                    ports.sql.exec("UPDATE __telnyx_agent_harness_runs SET status = 'outcome_unknown', failure_code = 'HARNESS_OUTCOME_UNKNOWN', updated_at = ? WHERE id = ?", ports.clock.now(), run.id);
+                }
+                // A process crash may leave a running claim. Replaying it is explicitly at-least-once.
+                const interrupted = ports.sql.exec("SELECT id FROM __telnyx_agent_harness_runs WHERE status = 'running'").toArray();
+                for (const run of interrupted) {
+                    if (active().has(run.id))
+                        continue;
+                    ports.sql.exec("UPDATE __telnyx_agent_harness_runs SET status = 'accepted', updated_at = ? WHERE id = ? AND status = 'running'", ports.clock.now(), run.id);
+                }
+                const recoveryExpiredApprovals = ports.sql.exec("SELECT id FROM __telnyx_agent_harness_approvals WHERE status IN ('pending','granted') AND expires_at <= ?", ports.clock.now()).toArray();
+                ports.sql.exec("UPDATE __telnyx_agent_harness_approvals SET status = 'expired', updated_at = ? WHERE status IN ('pending','granted') AND expires_at <= ?", ports.clock.now(), ports.clock.now());
+                for (const approval of recoveryExpiredApprovals) {
+                    ports.sql.exec("INSERT INTO __telnyx_agent_harness_approval_audit(id,approval_id,event,actor,action,outcome,at,seq) VALUES (?,?,?,?,?,?,?,COALESCE((SELECT MAX(seq) FROM __telnyx_agent_harness_approval_audit WHERE approval_id = ?), 0) + 1)", crypto.randomUUID(), approval.id, "recovery_expiry_expired", null, "recovery_expiry", "expired", ports.clock.now(), approval.id);
+                }
+                ports.sql.exec("UPDATE __telnyx_agent_harness_runs SET status = 'failed', failure_code = 'HARNESS_APPROVAL_EXPIRED', updated_at = ? WHERE status IN ('awaiting_approval','resume_pending') AND EXISTS (SELECT 1 FROM __telnyx_agent_harness_approvals WHERE run_id = __telnyx_agent_harness_runs.id AND status = 'expired')", ports.clock.now());
+                return ports.sql.exec("SELECT id,key,input,input_bytes,status,attempts,task_id,created_at,updated_at,failure_code FROM __telnyx_agent_harness_runs WHERE status IN ('accepted','resume_pending') ORDER BY created_at,id").toArray();
+            });
+            for (const run of recovered) {
+                if (run.status === "accepted")
+                    await enqueue(run);
+                else
+                    await enqueueApprovalResume(run);
+            }
+            return recovered.length;
+        },
+        async resume(runId) {
+            ensureInitialized();
+            const resumed = ports.sql.transactionSync(() => {
+                const current = read(runId);
+                // A final approval decision commits resume_pending before this
+                // post-transaction path runs. It still needs deterministic task
+                // admission after the original task has been acknowledged/deleted.
+                if (current === undefined || current.status === "resume_pending")
+                    return current;
+                if (current.status !== "awaiting_approval")
+                    return current;
+                if (!approvalRunReady(runId))
+                    return current;
+                ports.sql.exec("UPDATE __telnyx_agent_harness_runs SET status = 'resume_pending', updated_at = ? WHERE id = ? AND status = 'awaiting_approval'", ports.clock.now(), runId);
+                return read(runId);
+            });
+            if (resumed === undefined)
+                return undefined;
+            if (resumed.status !== "resume_pending")
+                return publicRun(resumed);
+            // A direct host dispatch can leave the original admission task visible
+            // until acknowledgement. Fence that sibling before admitting the
+            // distinct deterministic continuation task.
+            try {
+                await ports.tasks.cancel(resumed.task_id);
+            }
+            catch { /* the claim-time batch fence remains authoritative */ }
+            for (const task of await ports.tasks.list()) {
+                if (task.name !== APPROVAL_RESUME_TASK_METHOD || task.payload === null || typeof task.payload !== "object" || Array.isArray(task.payload))
+                    continue;
+                const taskRunId = Object.getOwnPropertyDescriptor(task.payload, "runId");
+                if (taskRunId !== undefined && "value" in taskRunId && taskRunId.value === runId) {
+                    try {
+                        await ports.tasks.cancel(task.id);
+                    }
+                    catch { /* the current deterministic upsert remains fenced at claim time */ }
+                }
+            }
+            await enqueueApprovalResume(resumed);
+            return publicRun(resumed);
+        },
+        pauseForApproval(runId) {
+            ensureInitialized();
+            ports.sql.transactionSync(() => {
+                ports.sql.exec("UPDATE __telnyx_agent_harness_runs SET status = 'awaiting_approval', updated_at = ? WHERE id = ? AND status = 'running'", ports.clock.now(), runId);
+                if (read(runId)?.status !== "awaiting_approval")
+                    throw new Error("approval run transition is invalid");
+            });
+        },
+        resumeForApproval(runId) {
+            ensureInitialized();
+            ports.sql.transactionSync(() => {
+                if (!approvalRunReady(runId))
+                    return;
+                ports.sql.exec("UPDATE __telnyx_agent_harness_runs SET status = 'resume_pending', updated_at = ? WHERE id = ? AND status = 'awaiting_approval'", ports.clock.now(), runId);
+                if (read(runId)?.status !== "resume_pending")
+                    throw new Error("approval run transition is invalid");
+            });
+        },
+        cancelForApproval(runId) {
+            ensureInitialized();
+            ports.sql.exec("UPDATE __telnyx_agent_harness_runs SET status = 'canceled', updated_at = ? WHERE id = ? AND status = 'awaiting_approval'", ports.clock.now(), runId);
+            if (read(runId)?.status !== "canceled")
+                throw new Error("approval run transition is invalid");
+        },
+        async expireForApproval(runId) {
+            ensureInitialized();
+            ports.sql.exec("UPDATE __telnyx_agent_harness_runs SET status = 'failed', failure_code = 'HARNESS_APPROVAL_EXPIRED', updated_at = ? WHERE id = ? AND status IN ('awaiting_approval','resume_pending')", ports.clock.now(), runId);
+            const expired = read(runId);
+            if (expired?.status !== "failed" || expired.failure_code !== "HARNESS_APPROVAL_EXPIRED") {
+                throw new Error("approval expiry transition is invalid");
+            }
+            try {
+                await ports.tasks.cancel(expired.task_id);
+            }
+            catch { /* terminal durable state fences late delivery */ }
+        },
+        async cleanupCanceledRun(runId) {
+            ensureInitialized();
+            const canceled = read(runId);
+            if (canceled === undefined)
+                return;
+            active().get(runId)?.abort();
+            // Queue cancellation is best-effort; the durable canceled state fences later delivery.
+            try {
+                await ports.tasks.cancel(canceled.task_id);
+            }
+            catch { /* durable state is authoritative */ }
+        },
+        async run(runId, resumeBatch) {
+            ensureInitialized();
+            const claimed = ports.sql.transactionSync(() => {
+                const current = read(runId);
+                if (current === undefined || (current.status !== "accepted" && current.status !== "resume_pending"))
+                    return Object.freeze({ run: current, claimed: false, continuation: false });
+                if (current.status === "resume_pending" && (resumeBatch === undefined || approvalResumeBatch(runId) !== resumeBatch))
+                    return Object.freeze({ run: current, claimed: false, continuation: false });
+                const continuation = current.status === "resume_pending" || current.attempts > 0;
+                ports.sql.exec("UPDATE __telnyx_agent_harness_runs SET status = 'running', attempts = attempts + 1, updated_at = ? WHERE id = ? AND status IN ('accepted','resume_pending')", ports.clock.now(), runId);
+                return Object.freeze({ run: read(runId), claimed: true, continuation });
+            });
+            if (!claimed.claimed || claimed.run === undefined) {
+                return claimed.run === undefined ? undefined : publicRun(claimed.run);
+            }
+            const controller = new AbortController();
+            active().set(runId, controller);
+            try {
+                await execute(claimed.run.input, controller.signal, createHarnessStepContext(ports, {
+                    runId,
+                    input: claimed.run.input,
+                    version: "v1",
+                    isContinuation: claimed.continuation,
+                    checkpoints: options.checkpoints,
+                }));
+                try {
+                    options.checkpoints?.("before_final_run_commit");
+                }
+                catch (error) {
+                    throw new HarnessInjectedCrash(error);
+                }
+                const completed = ports.sql.transactionSync(() => {
+                    if (read(runId)?.status === "running")
+                        ports.sql.exec("UPDATE __telnyx_agent_harness_runs SET status = 'completed', updated_at = ? WHERE id = ?", ports.clock.now(), runId);
+                    return read(runId);
+                });
+                return publicRun(completed);
+            }
+            catch (error) {
+                if (error instanceof HarnessInjectedCrash)
+                    throw error;
+                const failed = ports.sql.transactionSync(() => {
+                    if (error instanceof HarnessApprovalPause && read(runId)?.status === "running") {
+                        ports.sql.exec("UPDATE __telnyx_agent_harness_runs SET status = 'awaiting_approval', updated_at = ? WHERE id = ? AND status = 'running'", ports.clock.now(), runId);
+                        return read(runId);
+                    }
+                    const rolledBackScheduleStep = scheduleRollbackStep(error);
+                    if (rolledBackScheduleStep !== undefined)
+                        ports.sql.exec("UPDATE __telnyx_agent_harness_steps SET status = 'prepared' WHERE run_id = ? AND name = ? AND status = 'effect_started'", runId, rolledBackScheduleStep);
+                    const uncertain = ports.sql.exec("SELECT run_id FROM __telnyx_agent_harness_steps WHERE run_id = ? AND status = 'effect_started' LIMIT 1", runId).toArray().length > 0;
+                    if (read(runId)?.status === "running") {
+                        if (uncertain) {
+                            ports.sql.exec("UPDATE __telnyx_agent_harness_runs SET status = 'outcome_unknown', failure_code = 'HARNESS_OUTCOME_UNKNOWN', updated_at = ? WHERE id = ?", ports.clock.now(), runId);
+                        }
+                        else if (isPolicyUnavailable(error)) {
+                            ports.sql.exec("UPDATE __telnyx_agent_harness_runs SET status = 'resume_pending', updated_at = ? WHERE id = ?", ports.clock.now(), runId);
+                        }
+                        else {
+                            ports.sql.exec("UPDATE __telnyx_agent_harness_runs SET status = 'failed', failure_code = ?, updated_at = ? WHERE id = ?", failureCode(error), ports.clock.now(), runId);
+                        }
+                    }
+                    return read(runId);
+                });
+                if (isPolicyUnavailable(error) && failed.status === "resume_pending")
+                    await enqueueApprovalResume(failed);
+                return publicRun(failed);
+            }
+            finally {
+                active().delete(runId);
+            }
+        },
+        async dispatch(task) {
+            const dispatched = dispatchedRun(task);
+            return ledger.run(dispatched.runId, dispatched.batch);
+        },
+    };
+    return Object.freeze(ledger);
+}
+//# sourceMappingURL=durable.js.map