@telnyx/agent-harness 0.1.0-beta.0

package/dist/approvals.js

@@ -0,0 +1,699 @@
+import { ensureHarnessDurabilitySchema } from "./durable.js";
+export const HARNESS_APPROVAL_STATUSES = ["pending", "granted", "denied", "expired", "consumed"];
+export class HarnessAuthorizationError extends Error {
+    code;
+    constructor(code) {
+        super(`Harness authorization ${code}`);
+        this.code = code;
+        this.name = "HarnessAuthorizationError";
+    }
+}
+export class HarnessApprovalError extends Error {
+    code;
+    constructor(code) {
+        super(`Harness approval ${code}`);
+        this.code = code;
+        this.name = "HarnessApprovalError";
+    }
+}
+const REDACTED = "[REDACTED]";
+const SENSITIVE_KEY = /(?:authorization|bearer|credential|password|secret|token|api[_.-]?key)/i;
+const MAX_ARGUMENT_BYTES = 64 * 1024;
+const MAX_ID_BYTES = 512;
+const APPROVAL_ACTIONS = Object.freeze({
+    read: "agent_harness.approvals.read",
+    grant: "agent_harness.approvals.grant",
+    deny: "agent_harness.approvals.deny",
+});
+function first(rows) { return rows[0]; }
+function nonblank(value, name) {
+    if (!value.trim())
+        throw new Error(`${name} must not be blank`);
+    if (Buffer.byteLength(value, "utf8") > MAX_ID_BYTES)
+        throw new Error(`${name} exceeds ${MAX_ID_BYTES} UTF-8 bytes`);
+}
+function redacted(value) {
+    // COMPUTE-905: Use path-scoped cycle detection. A shared object referenced
+    // from multiple branches is acyclic and must be accepted. Only genuine
+    // cycles — where an object appears on its own ancestor path — are rejected.
+    const ancestors = new Set();
+    let nodes = 0;
+    const copy = (current, depth) => {
+        if (depth > 32)
+            throw new TypeError("approval arguments exceed the nesting limit");
+        if (current === null || typeof current === "string" || typeof current === "boolean")
+            return current;
+        if (typeof current === "number") {
+            if (!Number.isFinite(current))
+                throw new TypeError("approval arguments must be JSON-safe");
+            return current;
+        }
+        if (typeof current !== "object")
+            throw new TypeError("approval arguments must be JSON-safe");
+        if (ancestors.has(current))
+            throw new TypeError("approval arguments must not contain cycles");
+        ancestors.add(current);
+        nodes += 1;
+        if (nodes > 10_000)
+            throw new TypeError("approval arguments exceed the node limit");
+        try {
+            if (Array.isArray(current)) {
+                if (Object.getPrototypeOf(current) !== Array.prototype)
+                    throw new TypeError("approval arguments must not contain inherited arrays");
+                const allowed = new Set(["length", ...Array.from({ length: current.length }, (_, index) => String(index))]);
+                for (const key of Object.getOwnPropertyNames(current)) {
+                    if (!allowed.has(key))
+                        throw new TypeError("approval arguments must not contain non-index array properties");
+                    const descriptor = Object.getOwnPropertyDescriptor(current, key);
+                    if (descriptor === undefined || !("value" in descriptor))
+                        throw new TypeError("approval arguments must not contain accessors");
+                }
+                const output = [];
+                for (let index = 0; index < current.length; index += 1) {
+                    const descriptor = Object.getOwnPropertyDescriptor(current, String(index));
+                    if (descriptor === undefined)
+                        throw new TypeError("approval arguments must not contain sparse arrays");
+                    if (!("value" in descriptor))
+                        throw new TypeError("approval arguments must not contain accessors");
+                    output.push(copy(descriptor.value, depth + 1));
+                }
+                return Object.freeze(output);
+            }
+            const prototype = Object.getPrototypeOf(current);
+            if (prototype !== Object.prototype && prototype !== null)
+                throw new TypeError("approval arguments must be plain JSON data");
+            const output = {};
+            for (const key of Object.keys(current)) {
+                if (Buffer.byteLength(key, "utf8") > MAX_ID_BYTES)
+                    throw new TypeError(`approval argument key exceeds ${MAX_ID_BYTES} UTF-8 bytes`);
+                const descriptor = Object.getOwnPropertyDescriptor(current, key);
+                if (descriptor === undefined || !("value" in descriptor))
+                    throw new TypeError("approval arguments must not contain accessors");
+                output[key] = SENSITIVE_KEY.test(key) ? REDACTED : copy(descriptor.value, depth + 1);
+            }
+            return Object.freeze(output);
+        }
+        finally {
+            ancestors.delete(current);
+        }
+    };
+    return copy(value, 0);
+}
+/** Private execution snapshot: validate/copy JSON without applying public redaction. */
+function canonicalJson(value) {
+    // COMPUTE-905: Use path-scoped cycle detection, same as redacted().
+    const ancestors = new Set();
+    let nodes = 0;
+    const copy = (current, depth) => {
+        if (depth > 32)
+            throw new TypeError("canonical approval input exceeds the nesting limit");
+        if (current === null || typeof current === "string" || typeof current === "boolean")
+            return current;
+        if (typeof current === "number") {
+            if (!Number.isFinite(current))
+                throw new TypeError("canonical approval input must be JSON-safe");
+            return current;
+        }
+        if (typeof current !== "object")
+            throw new TypeError("canonical approval input must be JSON-safe");
+        if (ancestors.has(current))
+            throw new TypeError("canonical approval input must not contain cycles");
+        ancestors.add(current);
+        nodes += 1;
+        if (nodes > 10_000)
+            throw new TypeError("canonical approval input exceeds the node limit");
+        try {
+            if (Array.isArray(current)) {
+                if (Object.getPrototypeOf(current) !== Array.prototype)
+                    throw new TypeError("canonical approval input must not contain inherited arrays");
+                const allowed = new Set(["length", ...Array.from({ length: current.length }, (_, index) => String(index))]);
+                for (const key of Object.getOwnPropertyNames(current)) {
+                    if (!allowed.has(key))
+                        throw new TypeError("canonical approval input must not contain non-index array properties");
+                    const descriptor = Object.getOwnPropertyDescriptor(current, key);
+                    if (descriptor === undefined || !("value" in descriptor))
+                        throw new TypeError("canonical approval input must not contain accessors");
+                }
+                const output = [];
+                for (let index = 0; index < current.length; index += 1) {
+                    const descriptor = Object.getOwnPropertyDescriptor(current, String(index));
+                    if (descriptor === undefined)
+                        throw new TypeError("canonical approval input must not contain sparse arrays");
+                    if (!("value" in descriptor))
+                        throw new TypeError("canonical approval input must not contain accessors");
+                    output.push(copy(descriptor.value, depth + 1));
+                }
+                return Object.freeze(output);
+            }
+            const prototype = Object.getPrototypeOf(current);
+            if (prototype !== Object.prototype && prototype !== null)
+                throw new TypeError("canonical approval input must be plain JSON data");
+            const output = {};
+            for (const key of Object.keys(current).sort()) {
+                if (Buffer.byteLength(key, "utf8") > MAX_ID_BYTES)
+                    throw new TypeError(`canonical approval key exceeds ${MAX_ID_BYTES} UTF-8 bytes`);
+                const descriptor = Object.getOwnPropertyDescriptor(current, key);
+                if (descriptor === undefined || !("value" in descriptor))
+                    throw new TypeError("canonical approval input must not contain accessors");
+                output[key] = copy(descriptor.value, depth + 1);
+            }
+            return Object.freeze(output);
+        }
+        finally {
+            ancestors.delete(current);
+        }
+    };
+    return copy(value, 0);
+}
+function parseArguments(value) {
+    try {
+        return redacted(JSON.parse(value));
+    }
+    catch {
+        throw new Error("stored approval arguments are invalid");
+    }
+}
+function publicApproval(row) {
+    return Object.freeze({
+        id: row.id, runId: row.run_id, toolName: row.tool_name, toolCallId: row.tool_call_id,
+        arguments: parseArguments(row.arguments), requiredAction: row.required_action,
+        authorization: Object.freeze({ serviceAccountId: row.service_account_id, organizationId: row.organization_id }),
+        status: row.status, expiresAt: row.expires_at, createdAt: row.created_at, updatedAt: row.updated_at,
+    });
+}
+function ensureApprovalSchema(ports) {
+    ensureHarnessDurabilitySchema(ports);
+}
+function authIdentity(ports) {
+    const identity = ports.authorization?.identity();
+    if (identity === undefined)
+        throw new HarnessAuthorizationError("identity_unavailable");
+    if (!identity.serviceAccountId.trim() || !identity.organizationId.trim())
+        throw new HarnessAuthorizationError("unauthenticated");
+    return identity;
+}
+async function authorize(ports, action, row, persistedSubject = false) {
+    const liveIdentity = authIdentity(ports);
+    const identity = persistedSubject
+        ? Object.freeze({ serviceAccountId: row.service_account_id, organizationId: row.organization_id })
+        : liveIdentity;
+    nonblank(identity.serviceAccountId, "approval service account id");
+    nonblank(identity.organizationId, "approval organization id");
+    const decision = await ports.authorization?.authorize({
+        identity, action, resource: `agent_harness/approvals/${row.id}`, runId: row.run_id, approvalId: row.id,
+    });
+    if (decision?.kind === "allow")
+        return;
+    if (decision?.kind === "deny")
+        throw new HarnessAuthorizationError("forbidden");
+    throw new HarnessAuthorizationError("policy_unavailable");
+}
+export function createHarnessApprovalLedger(ports) {
+    const execution = createHarnessApprovalExecutionLedger(ports);
+    return Object.freeze({
+        inspect: execution.inspect,
+        grant: execution.grant,
+        deny: execution.deny,
+    });
+}
+export function createHarnessApprovalExecutionLedger(ports) {
+    let initialized = false;
+    const ensure = () => { if (!initialized) {
+        ensureApprovalSchema(ports);
+        initialized = true;
+    } };
+    const read = (id) => first(ports.sql.exec("SELECT id,run_id,tool_name,tool_call_id,arguments,required_action,service_account_id,organization_id,status,expires_at,created_at,updated_at FROM __telnyx_agent_harness_approvals WHERE id = ?", id).toArray());
+    const readEffect = (runId, toolCallId) => first(ports.sql.exec("SELECT id,run_id,tool_name,tool_call_id,arguments,required_action,service_account_id,organization_id,status,expires_at,created_at,updated_at FROM __telnyx_agent_harness_approvals WHERE run_id = ? AND tool_call_id = ?", runId, toolCallId).toArray());
+    const recordAudit = (id, event) => {
+        let actor = null;
+        try {
+            actor = ports.authorization?.identity()?.serviceAccountId ?? null;
+        }
+        catch { /* audit must not amplify an unavailable identity */ }
+        const normalized = event === "requested" ? "request_allowed"
+            : event === "granted" ? "grant_allowed"
+                : event === "denied" ? "deny_allowed"
+                    : event === "expired" ? "expiry_expired"
+                        : event === "consumed" ? "effect_consume_allowed"
+                            : event === "conflicting" ? "effect_reauthorize_conflicting"
+                                : event;
+        const operation = ["effect_reauthorize", "effect_consume", "inspect", "audit", "request", "grant", "deny", "expiry", "recovery"]
+            .find((candidate) => normalized.startsWith(`${candidate}_`));
+        if (operation === undefined)
+            throw new Error("approval audit event has no fixed operation class");
+        const outcome = normalized.slice(operation.length + 1);
+        if (!outcome)
+            throw new Error("approval audit event has no fixed outcome class");
+        // COMPUTE-904: Use a monotonic per-approval sequence as the causal
+        // tie-breaker instead of a random UUID. Same-millisecond events are
+        // returned in insertion order, preserving causal chronology.
+        const seqRow = first(ports.sql.exec("SELECT COALESCE(MAX(seq), 0) + 1 AS next FROM __telnyx_agent_harness_approval_audit WHERE approval_id = ?", id).toArray());
+        const seq = seqRow === undefined ? 1 : seqRow.next;
+        ports.sql.exec("INSERT INTO __telnyx_agent_harness_approval_audit(id,approval_id,event,actor,action,outcome,at,seq) VALUES (?,?,?,?,?,?,?,?)", crypto.randomUUID(), id, normalized, actor, operation, outcome, ports.clock.now(), seq);
+    };
+    const authorizeRead = async (surface, row) => {
+        try {
+            await authorize(ports, APPROVAL_ACTIONS.read, row);
+        }
+        catch (error) {
+            ports.sql.transactionSync(() => recordAudit(row.id, `${surface}_${error instanceof HarnessAuthorizationError ? error.code : "policy_unavailable"}`));
+            throw error;
+        }
+        ports.sql.transactionSync(() => recordAudit(row.id, `${surface}_allowed`));
+    };
+    const expiry = (row) => ports.sql.transactionSync(() => {
+        const current = read(row.id);
+        if ((current.status === "pending" || current.status === "granted") && current.expires_at <= ports.clock.now()) {
+            ports.sql.exec("UPDATE __telnyx_agent_harness_approvals SET status = 'expired', updated_at = ? WHERE id = ? AND status IN ('pending','granted')", ports.clock.now(), current.id);
+            recordAudit(current.id, "expired");
+        }
+        return read(row.id);
+    });
+    const rejectedDecision = (status, requested) => {
+        if (status === "expired")
+            return new HarnessApprovalError("expired");
+        if (status === "consumed")
+            return new HarnessApprovalError("consumed");
+        return new HarnessApprovalError(status === requested ? "replayed" : "conflicting");
+    };
+    return Object.freeze({
+        async request(request) {
+            return requestApproval(request);
+        },
+        async requestWithPause(request, pause) {
+            return requestApproval(request, pause);
+        },
+        async requestBatchWithPause(requests, pause) {
+            ensure();
+            if (requests.length === 0)
+                throw new Error("approval request batch is empty");
+            return ports.sql.transactionSync(() => {
+                const created = requests.map((request) => requestApproval(request));
+                pause(created);
+                return Object.freeze(created);
+            });
+        },
+        async inspect(id) {
+            ensure();
+            // Authenticate before target lookup to prevent existence disclosure.
+            authIdentity(ports);
+            const row = read(id);
+            if (!row)
+                throw new Error("approval not found");
+            await authorizeRead("inspect", row);
+            return publicApproval(expiry(row));
+        },
+        async inspectUnchecked(id) { ensure(); const row = read(id); return row === undefined ? undefined : publicApproval(expiry(row)); },
+        async grant(id) {
+            return grantApproval(id);
+        },
+        async grantWithResume(id, decide, resume) {
+            return grantApproval(id, (approval) => {
+                decide(approval);
+                if (runReadyToResume(approval.runId))
+                    resume(approval);
+            });
+        },
+        async denyWithCancel(id, cancel) {
+            return denyApproval(id, cancel);
+        },
+        async deny(id) {
+            return denyApproval(id);
+        },
+        async reauthorizeEffect(runId, toolCallId, toolName, input) {
+            ensure();
+            if (toolCallId === undefined)
+                return undefined;
+            const row = readEffect(runId, toolCallId);
+            if (row === undefined)
+                return undefined;
+            const current = expiry(row);
+            if (current.status === "expired")
+                throw new HarnessApprovalError("expired");
+            if (current.status !== "granted")
+                throw new HarnessApprovalError(current.status === "consumed" ? "consumed" : "replayed");
+            let approvedInput;
+            try {
+                const message = first(ports.sql.exec("SELECT approval_id,codec_version,run_id,tool_call_id,tool_name,journal_seq,after_message_seq,approval_epoch,canonical_tool_call,signature,approved,reason,response_at FROM __telnyx_agent_harness_approval_messages WHERE approval_id = ? AND run_id = ? AND tool_call_id = ? AND approval_epoch = (SELECT MAX(approval_epoch) FROM __telnyx_agent_harness_approval_messages WHERE run_id = ?)", current.id, runId, toolCallId, runId).toArray());
+                if (message === undefined || message.approved !== 1 || message.response_at === null)
+                    throw new Error("approval envelope is unavailable");
+                const linkage = first(ports.sql.exec("SELECT run_id,approval_epoch,tool_name,ordinal,journal_marker,provider_call_id,private_sequence,canonical_tool_call FROM __telnyx_agent_harness_approval_linkage WHERE approval_id = ?", current.id).toArray());
+                const durableRunExists = ports.sql.exec("SELECT 1 AS present FROM __telnyx_agent_harness_runs WHERE id = ?", runId).toArray().length > 0;
+                if (durableRunExists && (linkage === undefined
+                    || linkage.run_id !== runId
+                    || linkage.approval_epoch !== message.approval_epoch
+                    || linkage.tool_name !== message.tool_name
+                    || linkage.provider_call_id !== toolCallId
+                    || linkage.private_sequence !== message.journal_seq
+                    || linkage.ordinal !== message.journal_seq
+                    || linkage.journal_marker !== `approval:${current.id}:${message.journal_seq}`
+                    || linkage.canonical_tool_call !== message.canonical_tool_call))
+                    throw new Error("approval durable linkage is invalid");
+                const approved = approvalCanonicalToolCall(message);
+                const resumed = canonicalToolCall({ toolCallId, toolName, input });
+                if (approved.toolCallId !== resumed.toolCallId || approved.toolName !== resumed.toolName || JSON.stringify(approved.input) !== JSON.stringify(resumed.input)) {
+                    throw new Error("approval envelope conflicts");
+                }
+                approvedInput = approved.input;
+            }
+            catch {
+                ports.sql.transactionSync(() => recordAudit(current.id, "conflicting"));
+                throw new HarnessApprovalError("conflicting");
+            }
+            try {
+                await authorize(ports, current.required_action, current, true);
+            }
+            catch (error) {
+                ports.sql.transactionSync(() => recordAudit(current.id, `effect_reauthorize_${error instanceof HarnessAuthorizationError ? error.code : "policy_unavailable"}`));
+                throw error;
+            }
+            ports.sql.transactionSync(() => recordAudit(current.id, "effect_reauthorize_allowed"));
+            return Object.freeze({ id: current.id, input: approvedInput });
+        },
+        consumeAuthorizedEffect(runId, approvalId) {
+            ensure();
+            if (approvalId === undefined)
+                return;
+            // COMPUTE-906: Return a typed HarnessApprovalError for missing approvals
+            // instead of an untyped TypeError from the `!` assertion.
+            const row = read(approvalId);
+            if (row === undefined)
+                throw new HarnessApprovalError("missing");
+            const granted = expiry(row);
+            if (granted.run_id !== runId)
+                throw new HarnessApprovalError("conflicting");
+            if (granted.status === "expired")
+                throw new HarnessApprovalError("expired");
+            if (granted.status !== "granted")
+                throw new HarnessApprovalError(granted.status === "consumed" ? "consumed" : "replayed");
+            ports.sql.exec("UPDATE __telnyx_agent_harness_approvals SET status = 'consumed', updated_at = ? WHERE id = ? AND status = 'granted'", ports.clock.now(), granted.id);
+            if (read(granted.id)?.status !== "consumed")
+                throw new HarnessApprovalError("consumed");
+            recordAudit(granted.id, "consumed");
+        },
+        async audit(id) {
+            ensure();
+            authIdentity(ports);
+            const row = read(id);
+            if (!row)
+                throw new Error("approval not found");
+            await authorizeRead("audit", row);
+            // COMPUTE-904: Order by at, seq to preserve causal insertion order for
+            // same-timestamp events, instead of the random UUID id tie-breaker.
+            return Object.freeze(ports.sql.exec("SELECT event,action,outcome,at FROM __telnyx_agent_harness_approval_audit WHERE approval_id = ? ORDER BY at,seq", id).toArray().map((audit) => Object.freeze(audit)));
+        },
+    });
+    function requestApproval(request, afterCreate) {
+        ensure();
+        if (request.id !== undefined)
+            nonblank(request.id, "approval id");
+        nonblank(request.runId, "run id");
+        nonblank(request.toolName, "tool name");
+        nonblank(request.toolCallId, "tool call id");
+        nonblank(request.requiredAction, "tool action");
+        if (!Number.isSafeInteger(request.expiresAt) || request.expiresAt <= ports.clock.now())
+            throw new Error("approval expiry must be in the future");
+        const originalSubject = first(ports.sql.exec("SELECT service_account_id,organization_id FROM __telnyx_agent_harness_run_authority WHERE run_id = ?", request.runId).toArray());
+        const identity = originalSubject === undefined
+            ? authIdentity(ports)
+            : Object.freeze({ serviceAccountId: originalSubject.service_account_id, organizationId: originalSubject.organization_id });
+        const argumentsValue = redacted(request.arguments);
+        const serializedArguments = JSON.stringify(argumentsValue);
+        if (Buffer.byteLength(serializedArguments, "utf8") > MAX_ARGUMENT_BYTES)
+            throw new Error(`approval arguments exceed ${MAX_ARGUMENT_BYTES} UTF-8 bytes`);
+        const created = ports.sql.transactionSync(() => {
+            const existing = first(ports.sql.exec("SELECT id,run_id,tool_name,tool_call_id,arguments,required_action,service_account_id,organization_id,status,expires_at,created_at,updated_at FROM __telnyx_agent_harness_approvals WHERE run_id = ? AND tool_call_id = ?", request.runId, request.toolCallId).toArray());
+            if (existing !== undefined) {
+                if (existing.tool_name !== request.toolName || existing.arguments !== serializedArguments || existing.required_action !== request.requiredAction || existing.expires_at !== request.expiresAt)
+                    throw new HarnessApprovalError("conflicting");
+                if (existing.status !== "pending")
+                    throw new HarnessApprovalError(existing.status === "consumed" ? "consumed" : "replayed");
+                return existing;
+            }
+            const now = ports.clock.now();
+            const id = request.id ?? `approval-${ports.identity.id}-${now}-${crypto.randomUUID()}`;
+            ports.sql.exec("INSERT INTO __telnyx_agent_harness_approvals(id,run_id,tool_name,tool_call_id,arguments,required_action,service_account_id,organization_id,status,expires_at,created_at,updated_at) VALUES (?,?,?,?,?,?,?,?,'pending',?,?,?)", id, request.runId, request.toolName, request.toolCallId, serializedArguments, request.requiredAction, identity.serviceAccountId, identity.organizationId, request.expiresAt, now, now);
+            recordAudit(id, "requested");
+            afterCreate?.();
+            return read(id);
+        });
+        return Object.freeze({ id: created.id, status: "pending" });
+    }
+    function runReadyToResume(runId) {
+        nonblank(runId, "run id");
+        // COMPUTE-906: Centralize continuation readiness validation. This must
+        // match the exhaustive outcome contract in durable.ts approvalRunReady,
+        // including the invalidLinkage check that was previously omitted here.
+        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 = first(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());
+        const incompleteResponse = first(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());
+        const invalidLinkage = first(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());
+        return incompleteApproval === undefined
+            && incompleteResponse === undefined
+            && invalidLinkage === undefined;
+    }
+    async function grantApproval(id, afterGrant) {
+        ensure();
+        authIdentity(ports);
+        const row = read(id);
+        if (!row)
+            throw new Error("approval not found");
+        try {
+            await authorize(ports, APPROVAL_ACTIONS.grant, row);
+        }
+        catch (error) {
+            ports.sql.transactionSync(() => recordAudit(id, `grant_${error instanceof HarnessAuthorizationError ? error.code : "policy_unavailable"}`));
+            throw error;
+        }
+        const current = expiry(read(id));
+        if (current.status !== "pending") {
+            const error = rejectedDecision(current.status, "granted");
+            ports.sql.transactionSync(() => recordAudit(id, `grant_${error.code}`));
+            throw error;
+        }
+        let decided;
+        try {
+            decided = ports.sql.transactionSync(() => {
+                const current = read(id);
+                if (current.status !== "pending")
+                    throw rejectedDecision(current.status, "granted");
+                ports.sql.exec("UPDATE __telnyx_agent_harness_approvals SET status = 'granted', updated_at = ? WHERE id = ? AND status = 'pending'", ports.clock.now(), id);
+                recordAudit(id, "granted");
+                const granted = read(id);
+                afterGrant?.(publicApproval(granted));
+                return granted;
+            });
+        }
+        catch (error) {
+            if (error instanceof HarnessApprovalError)
+                ports.sql.transactionSync(() => recordAudit(id, `grant_${error.code}`));
+            throw error;
+        }
+        return publicApproval(decided);
+    }
+    async function denyApproval(id, afterDeny) {
+        ensure();
+        authIdentity(ports);
+        const row = read(id);
+        if (!row)
+            throw new Error("approval not found");
+        try {
+            await authorize(ports, APPROVAL_ACTIONS.deny, row);
+        }
+        catch (error) {
+            ports.sql.transactionSync(() => recordAudit(id, `deny_${error instanceof HarnessAuthorizationError ? error.code : "policy_unavailable"}`));
+            throw error;
+        }
+        const current = expiry(read(id));
+        if (current.status !== "pending") {
+            const error = rejectedDecision(current.status, "denied");
+            ports.sql.transactionSync(() => recordAudit(id, `deny_${error.code}`));
+            throw error;
+        }
+        let decided;
+        try {
+            decided = ports.sql.transactionSync(() => {
+                const current = read(id);
+                if (current.status !== "pending")
+                    throw rejectedDecision(current.status, "denied");
+                ports.sql.exec("UPDATE __telnyx_agent_harness_approvals SET status = 'denied', updated_at = ? WHERE id = ? AND status = 'pending'", ports.clock.now(), id);
+                recordAudit(id, "denied");
+                const denied = read(id);
+                afterDeny?.(publicApproval(denied));
+                return denied;
+            });
+        }
+        catch (error) {
+            if (error instanceof HarnessApprovalError)
+                ports.sql.transactionSync(() => recordAudit(id, `deny_${error.code}`));
+            throw error;
+        }
+        return publicApproval(decided);
+    }
+}
+const APPROVAL_MESSAGE_CODEC_VERSION = 1;
+const MAX_APPROVAL_REASON_BYTES = 4 * 1024;
+function canonicalToolCall(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("canonical approval tool call is invalid");
+    }
+    const input = value;
+    if (typeof input.toolCallId !== "string" || typeof input.toolName !== "string") {
+        throw new Error("canonical approval tool call is invalid");
+    }
+    nonblank(input.toolCallId, "canonical tool call id");
+    nonblank(input.toolName, "canonical tool name");
+    return Object.freeze({ toolCallId: input.toolCallId, toolName: input.toolName, input: canonicalJson(input.input) });
+}
+function serializedCanonicalToolCall(value) {
+    const serialized = JSON.stringify(canonicalToolCall(value));
+    if (Buffer.byteLength(serialized, "utf8") > MAX_ARGUMENT_BYTES) {
+        throw new Error(`canonical approval tool call exceeds ${MAX_ARGUMENT_BYTES} UTF-8 bytes`);
+    }
+    return serialized;
+}
+function approvalCanonicalToolCall(row) {
+    if (row.canonical_tool_call === null)
+        throw new Error("approval canonical tool call is unavailable");
+    let call;
+    try {
+        call = canonicalToolCall(JSON.parse(row.canonical_tool_call));
+    }
+    catch {
+        throw new Error("approval canonical tool call is malformed");
+    }
+    if (call.toolCallId !== row.tool_call_id || call.toolName !== row.tool_name) {
+        throw new Error("approval canonical tool call linkage is invalid");
+    }
+    return call;
+}
+function approvalMessage(row) {
+    if (row.codec_version !== APPROVAL_MESSAGE_CODEC_VERSION)
+        throw new Error("approval message codec is unsupported");
+    if (row.approved === null || row.response_at === null)
+        throw new Error("approval response is unavailable");
+    if (row.approved !== 0 && row.approved !== 1)
+        throw new Error("approval response is malformed");
+    if (row.reason !== null && Buffer.byteLength(row.reason, "utf8") > MAX_APPROVAL_REASON_BYTES)
+        throw new Error("approval response is malformed");
+    const call = approvalCanonicalToolCall(row);
+    return Object.freeze([
+        Object.freeze({ role: "assistant", content: Object.freeze([
+                Object.freeze({ type: "tool-call", toolCallId: call.toolCallId, toolName: call.toolName, input: call.input }),
+                Object.freeze({ type: "tool-approval-request", approvalId: row.approval_id, toolCallId: row.tool_call_id, ...(row.signature === null ? {} : { signature: row.signature }) }),
+            ]) }),
+        Object.freeze({ role: "tool", content: Object.freeze([Object.freeze({ type: "tool-approval-response", approvalId: row.approval_id, approved: row.approved === 1, ...(row.reason === null ? {} : { reason: row.reason }) })]) }),
+    ]);
+}
+/** Private SQL codec for the pinned AI SDK approval-message subset only. */
+export function createHarnessApprovalMessageJournal(ports) {
+    let initialized = false;
+    const ensure = () => { if (!initialized) {
+        ensureApprovalSchema(ports);
+        initialized = true;
+    } };
+    const read = (approvalId) => first(ports.sql.exec("SELECT approval_id,codec_version,run_id,tool_call_id,tool_name,journal_seq,after_message_seq,approval_epoch,canonical_tool_call,signature,approved,reason,response_at FROM __telnyx_agent_harness_approval_messages WHERE approval_id = ?", approvalId).toArray());
+    return Object.freeze({
+        nextRunSequence(runId) {
+            ensure();
+            nonblank(runId, "run id");
+            return ports.sql.transactionSync(() => {
+                const row = first(ports.sql.exec("SELECT COALESCE(MAX(journal_seq), 0) + 1 AS next FROM __telnyx_agent_harness_approval_messages WHERE run_id = ?", runId).toArray());
+                if (row === undefined || !Number.isSafeInteger(row.next) || row.next < 1) {
+                    throw new Error("approval journal sequence is invalid");
+                }
+                return row.next;
+            });
+        },
+        nextRunApprovalEpoch(runId) {
+            ensure();
+            nonblank(runId, "run id");
+            const row = first(ports.sql.exec("SELECT COALESCE(MAX(approval_epoch), 0) + 1 AS next FROM __telnyx_agent_harness_approval_messages WHERE run_id = ?", runId).toArray());
+            if (row === undefined || !Number.isSafeInteger(row.next) || row.next < 1)
+                throw new Error("approval epoch is invalid");
+            return row.next;
+        },
+        async request(request) {
+            recordRequest(request);
+        },
+        requestInTransaction(request) {
+            recordRequest(request);
+        },
+        async decide(decision) {
+            recordDecision(decision);
+        },
+        decideInTransaction(decision) {
+            recordDecision(decision);
+        },
+        async restore(runId, toolCallId, journalSeq) {
+            ensure();
+            const row = first(ports.sql.exec("SELECT approval_id,codec_version,run_id,tool_call_id,tool_name,journal_seq,after_message_seq,approval_epoch,canonical_tool_call,signature,approved,reason,response_at FROM __telnyx_agent_harness_approval_messages WHERE run_id = ? AND tool_call_id = ? AND journal_seq = ?", runId, toolCallId, journalSeq).toArray());
+            if (row === undefined)
+                throw new Error("approval message linkage is missing");
+            return approvalMessage(row);
+        },
+        async restoreRun(runId) {
+            ensure();
+            nonblank(runId, "run id");
+            const rows = ports.sql.exec("SELECT approval_id,codec_version,run_id,tool_call_id,tool_name,journal_seq,after_message_seq,approval_epoch,canonical_tool_call,signature,approved,reason,response_at FROM __telnyx_agent_harness_approval_messages WHERE run_id = ? AND approved IS NOT NULL ORDER BY after_message_seq,journal_seq,approval_id", runId).toArray();
+            return Object.freeze(rows.map((row) => Object.freeze({ afterMessageSeq: row.after_message_seq, journalSeq: row.journal_seq, approvalId: row.approval_id, toolCall: approvalCanonicalToolCall(row), messages: approvalMessage(row) })));
+        },
+    });
+    function recordRequest(request) {
+        ensure();
+        nonblank(request.runId, "run id");
+        nonblank(request.approvalId, "approval id");
+        nonblank(request.toolCallId, "tool call id");
+        nonblank(request.toolName, "tool name");
+        const approvalEpoch = request.approvalEpoch ?? 0;
+        if (!Number.isSafeInteger(request.journalSeq) || request.journalSeq < 0 || !Number.isSafeInteger(request.afterMessageSeq) || request.afterMessageSeq < 0 || !Number.isSafeInteger(approvalEpoch) || approvalEpoch < 0)
+            throw new Error("approval journal sequence is invalid");
+        if (request.signature !== undefined)
+            nonblank(request.signature, "approval signature");
+        const canonical = serializedCanonicalToolCall(request.canonicalToolCall);
+        const call = canonicalToolCall(JSON.parse(canonical));
+        if (call.toolCallId !== request.toolCallId || call.toolName !== request.toolName)
+            throw new Error("canonical approval tool call linkage is invalid");
+        ports.sql.transactionSync(() => {
+            const existing = read(request.approvalId);
+            if (existing !== undefined) {
+                if (existing.run_id !== request.runId || existing.tool_call_id !== request.toolCallId || existing.tool_name !== request.toolName || existing.journal_seq !== request.journalSeq || existing.after_message_seq !== request.afterMessageSeq || existing.approval_epoch !== approvalEpoch || existing.canonical_tool_call !== canonical || existing.signature !== (request.signature ?? null))
+                    throw new HarnessApprovalError("conflicting");
+                return;
+            }
+            ports.sql.exec("INSERT INTO __telnyx_agent_harness_approval_messages(approval_id,codec_version,run_id,tool_call_id,tool_name,journal_seq,after_message_seq,approval_epoch,canonical_tool_call,signature,approved,reason,response_at) VALUES (?,?,?,?,?,?,?,?, ?,?,NULL,NULL,NULL)", request.approvalId, APPROVAL_MESSAGE_CODEC_VERSION, request.runId, request.toolCallId, request.toolName, request.journalSeq, request.afterMessageSeq, approvalEpoch, canonical, request.signature ?? null);
+            // The message journal is independently testable and can record an
+            // envelope before a durable run exists. Linkage is required only when
+            // the approval/run pair exists and can therefore satisfy both FKs.
+            const approvalExists = ports.sql.exec("SELECT 1 AS present FROM __telnyx_agent_harness_approvals WHERE id = ? AND run_id = ?", request.approvalId, request.runId).toArray().length > 0;
+            const runExists = ports.sql.exec("SELECT 1 AS present FROM __telnyx_agent_harness_runs WHERE id = ?", request.runId).toArray().length > 0;
+            if (approvalExists && runExists) {
+                ports.sql.exec("INSERT INTO __telnyx_agent_harness_approval_linkage(approval_id,run_id,approval_epoch,tool_name,ordinal,journal_marker,provider_call_id,private_sequence,canonical_tool_call) VALUES (?,?,?,?,?,?,?,?,?)", request.approvalId, request.runId, approvalEpoch, request.toolName, request.journalSeq, `approval:${request.approvalId}:${request.journalSeq}`, request.toolCallId, request.journalSeq, canonical);
+            }
+        });
+    }
+    function recordDecision(decision) {
+        ensure();
+        nonblank(decision.approvalId, "approval id");
+        if (typeof decision.approved !== "boolean")
+            throw new Error("approval decision is invalid");
+        if (decision.reason !== undefined && Buffer.byteLength(decision.reason, "utf8") > MAX_APPROVAL_REASON_BYTES)
+            throw new Error(`approval reason exceeds ${MAX_APPROVAL_REASON_BYTES} UTF-8 bytes`);
+        ports.sql.transactionSync(() => {
+            const current = read(decision.approvalId);
+            if (current === undefined)
+                throw new Error("approval message not found");
+            if (current.approved !== null)
+                throw new HarnessApprovalError("replayed");
+            ports.sql.exec("UPDATE __telnyx_agent_harness_approval_messages SET approved = ?, reason = ?, response_at = ? WHERE approval_id = ? AND approved IS NULL", decision.approved ? 1 : 0, decision.reason ?? null, ports.clock.now(), decision.approvalId);
+            if (read(decision.approvalId)?.approved === null)
+                throw new HarnessApprovalError("replayed");
+        });
+    }
+}
+//# sourceMappingURL=approvals.js.map