@telnyx/agent-harness 0.1.0-beta.0

package/dist/harness.js

@@ -0,0 +1,1223 @@
+import { GatewayError } from "@ai-sdk/gateway";
+import { AISDKError, APICallError, RetryError, asSchema, generateText, jsonSchema, stepCountIs, wrapLanguageModel, } from "ai";
+import { z } from "zod/v4";
+import { isToolOutputSerializationFailure } from "./steps.js";
+import { HarnessApprovalError, createHarnessApprovalExecutionLedger, createHarnessApprovalMessageJournal, } from "./approvals.js";
+import { createHarnessRunExecutionLedger, HarnessApprovalPause, } from "./durable.js";
+import { runMiddleware } from "./lifecycle.js";
+import { withHarnessToolContext } from "./tool-context.js";
+import { resolveHarnessRuntimeConfig, } from "./runtime-config.js";
+const maxStepsSchema = z.number().int().positive();
+const TOOL_OUTPUT_PREFIX = "\u001e@telnyx/agent-harness:tool-output:v1:";
+const DURABLE_TOOL_STEP_VERSION = "tool-execution-v1";
+/** Raised after the final allowed model step still requests executable tools. */
+export class HarnessStepLimitError extends Error {
+    maxSteps;
+    completedSteps;
+    lastToolCalls;
+    code = "HARNESS_STEP_LIMIT";
+    constructor(maxSteps, completedSteps, lastToolCalls) {
+        super(`Harness exhausted its ${maxSteps}-step limit after ${completedSteps} completed steps`);
+        this.maxSteps = maxSteps;
+        this.completedSteps = completedSteps;
+        this.lastToolCalls = lastToolCalls;
+        this.name = "HarnessStepLimitError";
+    }
+}
+/** Stable provider-boundary error containing only allowlisted diagnostics. */
+export class HarnessProviderError extends Error {
+    diagnostics;
+    code = "HARNESS_PROVIDER_ERROR";
+    constructor(diagnostics) {
+        super("Model provider request failed");
+        this.diagnostics = diagnostics;
+        this.name = "HarnessProviderError";
+    }
+}
+/** Local tool failure used when a successful execution returns an unsafe output. */
+export class HarnessToolOutputError extends Error {
+    toolName;
+    code = "HARNESS_TOOL_OUTPUT_ERROR";
+    constructor(toolName) {
+        super(`Harness tool ${toolName} returned output that is not JSON-safe`);
+        this.toolName = toolName;
+        this.name = "HarnessToolOutputError";
+    }
+}
+/** Stable cancellation classification for an aborted caller-owned turn signal. */
+export class HarnessCancellationError extends Error {
+    code = "HARNESS_CANCELLED";
+    constructor() {
+        super("Harness turn was cancelled");
+        this.name = "HarnessCancellationError";
+    }
+}
+/** Stable aggregate retaining a primary turn failure when its observer also fails. */
+export class HarnessObserverError extends Error {
+    primary;
+    observer;
+    phase;
+    code = "HARNESS_OBSERVER_ERROR";
+    constructor(primary, observer, phase) {
+        super(`Harness ${phase} observer failed after the primary turn failure`);
+        this.primary = primary;
+        this.observer = observer;
+        this.phase = phase;
+        this.name = "HarnessObserverError";
+    }
+}
+function historyMessages(stored) {
+    return stored.map((message) => {
+        if (message.role === "assistant") {
+            const content = [];
+            if (message.content.length > 0 || message.toolCalls === undefined) {
+                content.push({ type: "text", text: message.content });
+            }
+            content.push(...(message.toolCalls ?? []).map((call) => ({
+                type: "tool-call",
+                toolCallId: call.id,
+                toolName: call.name,
+                input: call.args,
+            })));
+            return { role: "assistant", content };
+        }
+        if (message.role === "tool") {
+            if (message.name === undefined || message.toolCallId === undefined) {
+                throw new Error("Persisted tool messages require name and toolCallId");
+            }
+            return {
+                role: "tool",
+                content: [
+                    {
+                        type: "tool-result",
+                        toolCallId: message.toolCallId,
+                        toolName: message.name,
+                        output: decodeToolOutput(message.content),
+                    },
+                ],
+            };
+        }
+        return { role: message.role, content: message.content };
+    });
+}
+function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    try {
+        return JSON.stringify(error) ?? String(error);
+    }
+    catch {
+        return "Tool execution failed";
+    }
+}
+function encodeToolOutput(output) {
+    return `${TOOL_OUTPUT_PREFIX}${JSON.stringify(output)}`;
+}
+const TOOL_OUTPUT_MAX_DEPTH = 64;
+const TOOL_OUTPUT_MAX_NODES = 10_000;
+function cloneToolOutput(toolName, value) {
+    const ancestors = new Set();
+    let nodes = 0;
+    const clone = (candidate, depth) => {
+        nodes += 1;
+        if (nodes > TOOL_OUTPUT_MAX_NODES || depth > TOOL_OUTPUT_MAX_DEPTH) {
+            throw new HarnessToolOutputError(toolName);
+        }
+        if (candidate === null || typeof candidate === "string" || typeof candidate === "boolean") {
+            return candidate;
+        }
+        if (typeof candidate === "number") {
+            if (!Number.isFinite(candidate))
+                throw new HarnessToolOutputError(toolName);
+            return candidate;
+        }
+        if (typeof candidate !== "object" || ancestors.has(candidate)) {
+            throw new HarnessToolOutputError(toolName);
+        }
+        let prototype;
+        try {
+            prototype = Object.getPrototypeOf(candidate);
+        }
+        catch {
+            throw new HarnessToolOutputError(toolName);
+        }
+        if (!Array.isArray(candidate) && prototype !== Object.prototype && prototype !== null) {
+            throw new HarnessToolOutputError(toolName);
+        }
+        ancestors.add(candidate);
+        try {
+            if (Array.isArray(candidate)) {
+                const result = [];
+                for (let index = 0; index < candidate.length; index += 1) {
+                    result.push(clone(safeProperty(candidate, index), depth + 1));
+                }
+                return result;
+            }
+            const result = {};
+            let keys;
+            try {
+                keys = Object.keys(candidate);
+            }
+            catch {
+                throw new HarnessToolOutputError(toolName);
+            }
+            for (const key of keys) {
+                Object.defineProperty(result, key, {
+                    configurable: true,
+                    enumerable: true,
+                    value: clone(safeProperty(candidate, key), depth + 1),
+                    writable: true,
+                });
+            }
+            return result;
+        }
+        finally {
+            ancestors.delete(candidate);
+        }
+    };
+    try {
+        return clone(value, 0);
+    }
+    catch (error) {
+        if (error instanceof HarnessToolOutputError)
+            throw error;
+        throw new HarnessToolOutputError(toolName);
+    }
+}
+function toJsonValue(value) {
+    const encoded = JSON.stringify(value ?? null);
+    if (encoded === undefined)
+        throw new Error("Tool output is not JSON-safe");
+    return JSON.parse(encoded);
+}
+function decodeToolOutputEnvelope(content) {
+    if (!content.startsWith(TOOL_OUTPUT_PREFIX)) {
+        return { output: { type: "text", value: content } };
+    }
+    try {
+        const parsed = JSON.parse(content.slice(TOOL_OUTPUT_PREFIX.length));
+        const record = objectRecord(parsed);
+        const type = record?.type;
+        const value = record?.value;
+        if ((type === "text" || type === "error-text") && typeof value === "string") {
+            return { output: { type, value }, ...(typeof record?.journalMarker === "string" ? { journalMarker: record.journalMarker } : {}) };
+        }
+        if (type === "json" || type === "error-json") {
+            return { output: { type, value: value }, ...(typeof record?.journalMarker === "string" ? { journalMarker: record.journalMarker } : {}) };
+        }
+    }
+    catch {
+        // Fall through to the stable corruption error below.
+    }
+    throw new Error("Persisted harness tool output is invalid");
+}
+function decodeToolOutput(content) {
+    return decodeToolOutputEnvelope(content).output;
+}
+function journalForStep(step, journalMarkers = new Map(), calls = step.toolCalls) {
+    const messages = [
+        {
+            role: "assistant",
+            content: step.text,
+            ...(calls.length > 0
+                ? {
+                    toolCalls: calls.map((call) => ({
+                        id: call.toolCallId,
+                        name: call.toolName,
+                        args: call.input,
+                    })),
+                }
+                : {}),
+        },
+    ];
+    const outputByCallId = new Map(step.content
+        .filter((part) => part.type === "tool-result" || part.type === "tool-error")
+        .map((part) => [part.toolCallId, part]));
+    for (const call of calls) {
+        const output = outputByCallId.get(call.toolCallId);
+        if (output === undefined) {
+            throw new Error(`Completed tool call ${call.toolCallId} has no result or error`);
+        }
+        const stored = output.type === "tool-error"
+            ? { type: "error-text", value: errorMessage(output.error) }
+            : typeof output.output === "string"
+                ? { type: "text", value: output.output }
+                : { type: "json", value: toJsonValue(output.output) };
+        messages.push({
+            role: "tool",
+            content: encodeToolOutput({ ...stored, ...(journalMarkers.get(call.toolCallId) === undefined ? {} : { journalMarker: journalMarkers.get(call.toolCallId) }) }),
+            name: call.toolName,
+            toolCallId: call.toolCallId,
+        });
+    }
+    return messages;
+}
+function journalForApprovedToolCalls(calls, journalMarkers) {
+    if (calls.length === 0)
+        return [];
+    return [
+        { role: "assistant", content: "", toolCalls: calls.map((call) => ({ id: call.toolCallId, name: call.toolName, args: call.input })) },
+        ...calls.map((call) => ({
+            role: "tool",
+            content: encodeToolOutput({ ...call.output, ...(journalMarkers.get(call.toolCallId) === undefined ? {} : { journalMarker: journalMarkers.get(call.toolCallId) }) }),
+            name: call.toolName,
+            toolCallId: call.toolCallId,
+        })),
+    ];
+}
+function observedStep(step, journalThrough) {
+    const outputByCallId = new Map(step.content
+        .filter((part) => part.type === "tool-result" || part.type === "tool-error")
+        .map((part) => [part.toolCallId, part]));
+    return Object.freeze({
+        number: step.stepNumber + 1,
+        text: step.text,
+        finishReason: step.finishReason,
+        journalThrough,
+        toolCalls: Object.freeze(step.toolCalls.map((call) => Object.freeze({
+            id: call.toolCallId,
+            name: call.toolName,
+            input: freezeJsonValue(cloneToolOutput(call.toolName, call.input)),
+        }))),
+        toolResults: Object.freeze(step.toolCalls.flatMap((call) => {
+            const result = outputByCallId.get(call.toolCallId);
+            if (result === undefined)
+                return [];
+            return [
+                Object.freeze({
+                    id: call.toolCallId,
+                    name: call.toolName,
+                    output: freezeJsonValue(result.type === "tool-error"
+                        ? errorMessage(result.error)
+                        : typeof result.output === "string"
+                            ? result.output
+                            : toJsonValue(result.output)),
+                    isError: result.type === "tool-error",
+                }),
+            ];
+        })),
+    });
+}
+function objectRecord(value) {
+    return typeof value === "object" && value !== null
+        ? value
+        : undefined;
+}
+const DIAGNOSTIC_MAX_DEPTH = 4;
+const DIAGNOSTIC_MAX_NODES = 24;
+const DIAGNOSTIC_MAX_ARRAY_ITEMS = 8;
+const DIAGNOSTIC_IDENTIFIER_MAX_LENGTH = 64;
+const GATEWAY_CAUSE_NAMES = new Set([
+    "GatewayError",
+    "GatewayAuthenticationError",
+    "GatewayFailedDependencyError",
+    "GatewayForbiddenError",
+    "GatewayInternalServerError",
+    "GatewayInvalidRequestError",
+    "GatewayModelNotFoundError",
+    "GatewayRateLimitError",
+    "GatewayResponseError",
+    "GatewayTimeoutError",
+]);
+const AI_SDK_GATEWAY_AUTH_PRODUCTION_MESSAGE = "Unauthenticated. Configure AI_GATEWAY_API_KEY or use a provider module. Learn more: https://ai-sdk.dev/unauthenticated-ai-gateway";
+const AI_SDK_GATEWAY_AUTH_DEVELOPMENT_MESSAGE = "\u001b[1m\u001b[31mUnauthenticated request to AI Gateway.\u001b[0m\n\n" +
+    "To authenticate, set the \u001b[33mAI_GATEWAY_API_KEY\u001b[0m environment variable with your API key.\n\n" +
+    "Alternatively, you can use a provider module instead of the AI Gateway.\n\n" +
+    "Learn more: \u001b[34mhttps://ai-sdk.dev/unauthenticated-ai-gateway\u001b[0m\n\n";
+const SENSITIVE_IDENTIFIER = /(?:authorization|bearer|credential|password|secret|token|api[_.-]?key)/i;
+const SAFE_IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:/-]*$/;
+function safeProperty(record, property) {
+    try {
+        return record[property];
+    }
+    catch {
+        return undefined;
+    }
+}
+function isExactWrappedGatewayAuthenticationError(error) {
+    const record = objectRecord(error);
+    if (record === undefined)
+        return false;
+    const name = safeProperty(record, "name");
+    const message = safeProperty(record, "message");
+    if (name === "GatewayAuthenticationError") {
+        return message === AI_SDK_GATEWAY_AUTH_DEVELOPMENT_MESSAGE;
+    }
+    try {
+        return (name === "GatewayError" &&
+            message === AI_SDK_GATEWAY_AUTH_PRODUCTION_MESSAGE &&
+            AISDKError.isInstance(error));
+    }
+    catch {
+        return false;
+    }
+}
+function knownCauseName(error) {
+    try {
+        if (APICallError.isInstance(error))
+            return "AI_APICallError";
+    }
+    catch {
+        // Hostile proxies are not trusted provider errors.
+    }
+    try {
+        if (RetryError.isInstance(error))
+            return "AI_RetryError";
+    }
+    catch {
+        // Hostile proxies are not trusted provider errors.
+    }
+    try {
+        if (GatewayError.isInstance(error)) {
+            const name = safeProperty(error, "name");
+            return typeof name === "string" && GATEWAY_CAUSE_NAMES.has(name)
+                ? name
+                : "GatewayError";
+        }
+    }
+    catch {
+        // Hostile proxies are not trusted Gateway errors.
+    }
+    return isExactWrappedGatewayAuthenticationError(error)
+        ? "GatewayAuthenticationError"
+        : undefined;
+}
+function validStatusCode(value) {
+    return (typeof value === "number" &&
+        Number.isInteger(value) &&
+        value >= 100 &&
+        value <= 599);
+}
+function diagnosticSource(error) {
+    const queue = [{ value: error, depth: 0 }];
+    const visited = new Set();
+    let nodes = 0;
+    let fallbackCauseName = knownCauseName(error) ?? "UnknownError";
+    let fallback = { causeName: fallbackCauseName };
+    const enqueueArray = (value, depth) => {
+        if (!Array.isArray(value) || depth > DIAGNOSTIC_MAX_DEPTH)
+            return;
+        const count = Math.min(value.length, DIAGNOSTIC_MAX_ARRAY_ITEMS);
+        for (let index = 0; index < count; index += 1) {
+            queue.push({ value: safeProperty(value, index), depth });
+        }
+    };
+    while (queue.length > 0 && nodes < DIAGNOSTIC_MAX_NODES) {
+        const item = queue.shift();
+        if (item === undefined || item.depth > DIAGNOSTIC_MAX_DEPTH)
+            continue;
+        const candidate = item.value;
+        if (visited.has(candidate))
+            continue;
+        visited.add(candidate);
+        nodes += 1;
+        if (Array.isArray(candidate)) {
+            enqueueArray(candidate, item.depth + 1);
+            continue;
+        }
+        const record = objectRecord(candidate);
+        if (record === undefined)
+            continue;
+        const causeName = knownCauseName(candidate);
+        const statusCode = safeProperty(record, "statusCode");
+        const retryable = safeProperty(record, "isRetryable") ?? safeProperty(record, "retryable");
+        if (causeName !== undefined) {
+            fallbackCauseName = causeName;
+            fallback = {
+                causeName,
+                ...(validStatusCode(statusCode) ? { statusCode } : {}),
+                ...(typeof retryable === "boolean" ? { retryable } : {}),
+            };
+            if (validStatusCode(statusCode))
+                return fallback;
+        }
+        if (item.depth >= DIAGNOSTIC_MAX_DEPTH)
+            continue;
+        queue.push({ value: safeProperty(record, "lastError"), depth: item.depth + 1 });
+        queue.push({ value: safeProperty(record, "cause"), depth: item.depth + 1 });
+        enqueueArray(safeProperty(record, "errors"), item.depth + 1);
+    }
+    return fallback.causeName === fallbackCauseName
+        ? fallback
+        : { causeName: fallbackCauseName };
+}
+function safeIdentifier(value, fallback) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > DIAGNOSTIC_IDENTIFIER_MAX_LENGTH ||
+        !SAFE_IDENTIFIER.test(value) ||
+        value.includes("://") ||
+        SENSITIVE_IDENTIFIER.test(value)) {
+        return fallback;
+    }
+    return value;
+}
+function isProviderFailure(error) {
+    try {
+        if (APICallError.isInstance(error) || RetryError.isInstance(error))
+            return true;
+    }
+    catch {
+        return false;
+    }
+    return knownCauseName(error) !== undefined;
+}
+function providerDiagnostics(model, error) {
+    const source = diagnosticSource(error);
+    const provider = typeof model === "string"
+        ? "gateway"
+        : safeIdentifier(safeProperty(model, "provider"), "unknown-provider");
+    const modelId = typeof model === "string"
+        ? safeIdentifier(model, "unknown-model")
+        : safeIdentifier(safeProperty(model, "modelId"), "unknown-model");
+    return Object.freeze({
+        provider,
+        modelId,
+        causeName: source.causeName,
+        ...(source.statusCode !== undefined ? { statusCode: source.statusCode } : {}),
+        ...(source.retryable !== undefined ? { retryable: source.retryable } : {}),
+    });
+}
+function freezeJsonValue(value) {
+    if (typeof value !== "object" || value === null || Object.isFrozen(value))
+        return value;
+    for (const child of Object.values(value)) {
+        if (child !== undefined)
+            freezeJsonValue(child);
+    }
+    return Object.freeze(value);
+}
+function cloneFrozenToolData(toolName, field, value) {
+    try {
+        return freezeJsonValue(cloneToolOutput(toolName, value));
+    }
+    catch {
+        throw new TypeError(`Harness tool ${toolName} ${field} must be JSON-safe`);
+    }
+}
+function promiseLike(value) {
+    if ((typeof value !== "object" || value === null) && typeof value !== "function") {
+        return false;
+    }
+    return typeof value.then === "function";
+}
+function snapshotSchema(toolName, field, flexibleSchema) {
+    const source = asSchema(flexibleSchema);
+    const validate = source.validate;
+    let materialized;
+    try {
+        const captured = source.jsonSchema;
+        materialized = promiseLike(captured)
+            ? Promise.resolve(captured).then((value) => ({
+                ok: true,
+                value: cloneFrozenToolData(toolName, `${field} JSON Schema`, value),
+            }), (error) => ({ ok: false, error }))
+            : {
+                ok: true,
+                value: cloneFrozenToolData(toolName, `${field} JSON Schema`, captured),
+            };
+    }
+    catch (error) {
+        materialized = { ok: false, error };
+    }
+    const resolveSchema = async () => {
+        const result = await materialized;
+        if (!result.ok)
+            throw result.error;
+        return result.value;
+    };
+    const schema = Object.freeze(jsonSchema(resolveSchema, {
+        ...(validate === undefined
+            ? {}
+            : { validate: (value) => validate.call(source, value) }),
+    }));
+    return Object.freeze({
+        schema,
+        async preflight() {
+            await schema.jsonSchema;
+        },
+    });
+}
+function snapshotTools(tools) {
+    const schemas = new Map();
+    const entries = Object.entries(tools).map(([name, tool]) => {
+        const candidate = objectRecord(tool);
+        if (candidate === undefined) {
+            throw new TypeError(`Harness tool ${name} must be an object`);
+        }
+        const inputSchema = snapshotSchema(name, "inputSchema", candidate.inputSchema);
+        const toolSchemas = [inputSchema];
+        const outputSchema = candidate.outputSchema === undefined
+            ? undefined
+            : snapshotSchema(name, "outputSchema", candidate.outputSchema);
+        if (outputSchema !== undefined)
+            toolSchemas.push(outputSchema);
+        schemas.set(name, Object.freeze(toolSchemas));
+        const execute = candidate.execute;
+        const capturedTool = Object.freeze({
+            ...(candidate.type === "function" ? { type: "function" } : {}),
+            ...(candidate.description !== undefined ? { description: candidate.description } : {}),
+            ...(candidate.title !== undefined ? { title: candidate.title } : {}),
+            ...(candidate.providerOptions !== undefined
+                ? {
+                    providerOptions: cloneFrozenToolData(name, "providerOptions", candidate.providerOptions),
+                }
+                : {}),
+            ...(candidate.metadata !== undefined
+                ? { metadata: cloneFrozenToolData(name, "metadata", candidate.metadata) }
+                : {}),
+            ...(candidate.needsApproval === true ? { needsApproval: true } : {}),
+            inputSchema: inputSchema.schema,
+            ...(candidate.inputExamples !== undefined
+                ? {
+                    inputExamples: cloneFrozenToolData(name, "inputExamples", candidate.inputExamples),
+                }
+                : {}),
+            ...(candidate.strict !== undefined ? { strict: candidate.strict } : {}),
+            ...(outputSchema !== undefined ? { outputSchema: outputSchema.schema } : {}),
+            async execute(...args) {
+                return await execute.apply(this, args);
+            },
+        });
+        return [name, capturedTool];
+    });
+    const capturedTools = Object.freeze(Object.fromEntries(entries));
+    return Object.freeze({
+        tools: capturedTools,
+        preflight(names) {
+            return Promise.all(names.flatMap((name) => schemas.get(name) ?? []).map((schema) => schema.preflight()))
+                .then(() => undefined);
+        },
+    });
+}
+const ACTION_MAX_BYTES = 512;
+const ACTION_PATTERN = /^[A-Za-z0-9]+(?:\.[A-Za-z0-9]+)*$/;
+const APPROVAL_TTL_MIN_MS = 300_000;
+const APPROVAL_TTL_MAX_MS = 86_400_000;
+function validateTools(tools, authorization) {
+    const names = Object.keys(tools);
+    const requiresApproval = names.some((name) => objectRecord(tools[name])?.needsApproval === true);
+    const mapped = authorization?.toolActions;
+    const approvalTtlMs = authorization?.approvalTtlMs ?? Number.NaN;
+    if (requiresApproval && mapped === undefined) {
+        throw new TypeError("Harness approval-capable tools require a private tool action map");
+    }
+    if (requiresApproval && (!Number.isSafeInteger(approvalTtlMs)
+        || approvalTtlMs < APPROVAL_TTL_MIN_MS
+        || approvalTtlMs > APPROVAL_TTL_MAX_MS)) {
+        throw new TypeError("Harness approval TTL must be a host-owned safe integer between 300000 and 86400000 ms");
+    }
+    if (mapped !== undefined) {
+        const mappedNames = Object.keys(mapped);
+        if (mappedNames.length !== names.length || mappedNames.some((name) => !Object.hasOwn(tools, name))) {
+            throw new TypeError("Harness tool action map must cover the exact supplied tool set");
+        }
+        for (const name of names) {
+            const action = mapped[name];
+            if (typeof action !== "string" || !action.trim() || Buffer.byteLength(action, "utf8") > ACTION_MAX_BYTES || !ACTION_PATTERN.test(action)) {
+                throw new TypeError(`Harness tool ${name} action is invalid`);
+            }
+        }
+    }
+    for (const [name, tool] of Object.entries(tools)) {
+        const candidate = objectRecord(tool);
+        if (candidate === undefined) {
+            throw new TypeError(`Harness tool ${name} must be an object`);
+        }
+        if (candidate.type !== undefined && candidate.type !== "function") {
+            throw new TypeError(`Harness tool ${name} must be an ordinary function tool`);
+        }
+        if (typeof candidate.execute !== "function") {
+            throw new TypeError(`Harness tool ${name} must define execute`);
+        }
+        if (candidate.needsApproval !== undefined && candidate.needsApproval !== true) {
+            throw new TypeError(`Harness tool ${name} needsApproval must be true when supplied`);
+        }
+        if (candidate.supportsDeferredResults !== undefined) {
+            throw new TypeError(`Harness tool ${name} cannot use deferred results`);
+        }
+        for (const extension of [
+            "onInputStart",
+            "onInputDelta",
+            "onInputAvailable",
+            "toModelOutput",
+        ]) {
+            if (candidate[extension] !== undefined) {
+                throw new TypeError(`Harness tool ${name} cannot use ${extension}`);
+            }
+        }
+    }
+}
+/** Construct a portable AI SDK v6 turn engine over an explicit ports object. */
+export function createHarness(spec) {
+    const messagePort = spec.ports.messages;
+    const appendMessage = messagePort.append.bind(messagePort);
+    const appendMessages = messagePort.appendMany.bind(messagePort);
+    const allMessages = messagePort.all.bind(messagePort);
+    const getState = spec.ports.state.get.bind(spec.ports.state);
+    const model = spec.model;
+    const instructions = spec.instructions;
+    validateTools(spec.tools, spec.authorization);
+    // Authorization is a construction-time host capability. Copy its validated
+    // values before any asynchronous turn can observe mutable host input.
+    const authorization = spec.authorization === undefined
+        ? undefined
+        : Object.freeze({
+            toolActions: Object.freeze({ ...spec.authorization.toolActions }),
+            ...(spec.authorization.approvalTtlMs === undefined ? {} : { approvalTtlMs: spec.authorization.approvalTtlMs }),
+        });
+    const requiresApprovalIdentity = Object.values(spec.tools).some((tool) => objectRecord(tool)?.needsApproval === true);
+    const toolSnapshot = snapshotTools(spec.tools);
+    const tools = toolSnapshot.tools;
+    const models = Object.freeze({ ...(spec.models ?? {}) });
+    const outputs = Object.freeze({ ...(spec.outputs ?? {}) });
+    const maxSteps = maxStepsSchema.parse(spec.limits.steps);
+    const approvals = createHarnessApprovalExecutionLedger(spec.ports);
+    const approvalMessages = createHarnessApprovalMessageJournal(spec.ports);
+    const staticRuntimeConfig = Object.freeze({
+        model,
+        instructions,
+        tools,
+        limits: Object.freeze({ steps: maxSteps }),
+        models,
+        outputs,
+        ...(spec.output === undefined ? {} : { output: spec.output }),
+        ...(spec.activeTools === undefined ? {} : { activeTools: Object.freeze([...spec.activeTools]) }),
+    });
+    const lifecycleMiddleware = Object.freeze({
+        turn: Object.freeze([...(spec.middleware?.turn ?? [])]),
+        modelStep: Object.freeze([...(spec.middleware?.modelStep ?? [])]),
+        tool: Object.freeze([...(spec.middleware?.tool ?? [])]),
+    });
+    if (typeof model === "string" && lifecycleMiddleware.modelStep.length > 0) {
+        throw new TypeError("Harness model-step middleware requires an executable LanguageModel");
+    }
+    let lastValidRuntimeConfig = resolveHarnessRuntimeConfig(staticRuntimeConfig, undefined).config;
+    let runtimeConfigReadSequence = 0;
+    let lastPublishedRuntimeConfigReadSequence = 0;
+    const turn = async (input, options = {}) => {
+        if (options.signal?.aborted) {
+            const cancellation = new HarnessCancellationError();
+            try {
+                await options.onCancel?.(cancellation);
+            }
+            catch (observer) {
+                throw new HarnessObserverError(cancellation, observer, "cancel");
+            }
+            throw cancellation;
+        }
+        try {
+            const runtimeConfigReadSequenceForTurn = ++runtimeConfigReadSequence;
+            const state = await getState();
+            const resolution = resolveHarnessRuntimeConfig(staticRuntimeConfig, state.__telnyx_agent_harness, lastValidRuntimeConfig);
+            const runtimeConfig = resolution.config;
+            if (typeof runtimeConfig.model === "string" && lifecycleMiddleware.modelStep.length > 0) {
+                throw new TypeError("Harness model-step middleware requires an executable LanguageModel");
+            }
+            if (options.steps === undefined && Object.values(runtimeConfig.tools ?? {}).some((tool) => objectRecord(tool)?.needsApproval === true)) {
+                throw new TypeError("Harness approval-capable tools require durable runs");
+            }
+            if (resolution.valid && runtimeConfigReadSequenceForTurn > lastPublishedRuntimeConfigReadSequence) {
+                lastValidRuntimeConfig = resolution.config;
+                lastPublishedRuntimeConfigReadSequence = runtimeConfigReadSequenceForTurn;
+            }
+            const turnContext = Object.freeze({
+                phase: "turn",
+                input,
+                config: runtimeConfig,
+                signal: options.signal,
+            });
+            return await runMiddleware(turnContext, lifecycleMiddleware.turn, async () => {
+                await toolSnapshot.preflight(Object.keys(runtimeConfig.tools ?? {}));
+                const priorMessages = await allMessages();
+                const inputSteps = options.steps;
+                const inputJournal = inputSteps === undefined
+                    ? undefined
+                    : spec.ports.sql.transactionSync(() => {
+                        const ownedRun = spec.ports.sql.exec("SELECT id FROM __telnyx_agent_harness_runs WHERE id = ?", inputSteps.runId).toArray()[0];
+                        // Direct internal turn tests can project historical approval envelopes
+                        // without owning a durable run. Only ledger-owned runs use this fence.
+                        if (ownedRun === undefined)
+                            return undefined;
+                        const existing = spec.ports.sql.exec("SELECT journal_seq FROM __telnyx_agent_harness_run_inputs WHERE run_id = ?", inputSteps.runId).toArray()[0];
+                        if (existing !== undefined)
+                            return existing;
+                        const legacy = spec.ports.sql.exec("SELECT run_id FROM __telnyx_agent_harness_legacy_run_inputs WHERE run_id = ?", inputSteps.runId).toArray()[0];
+                        if (legacy !== undefined)
+                            return { legacy: true };
+                        const journalSeq = (priorMessages.at(-1)?.seq ?? 0) + 1;
+                        spec.ports.sql.exec("INSERT INTO __telnyx_agent_harness_run_inputs(run_id,journal_seq) VALUES (?,?)", inputSteps.runId, journalSeq);
+                        return { journal_seq: journalSeq };
+                    });
+                const journaledInput = inputJournal === undefined
+                    ? undefined
+                    : "legacy" in inputJournal
+                        ? priorMessages.at(-1)?.role === "user" && priorMessages.at(-1)?.content === input
+                            ? priorMessages.at(-1)
+                            : undefined
+                        : priorMessages.find((message) => message.seq === inputJournal.journal_seq);
+                if (inputJournal !== undefined && "legacy" in inputJournal && journaledInput === undefined) {
+                    throw new Error("legacy durable input journal cannot be safely recovered");
+                }
+                if (inputJournal !== undefined && "legacy" in inputJournal && journaledInput !== undefined) {
+                    spec.ports.sql.transactionSync(() => {
+                        spec.ports.sql.exec("INSERT INTO __telnyx_agent_harness_run_inputs(run_id,journal_seq) VALUES (?,?)", inputSteps.runId, journaledInput.seq);
+                        spec.ports.sql.exec("DELETE FROM __telnyx_agent_harness_legacy_run_inputs WHERE run_id = ?", inputSteps.runId);
+                    });
+                }
+                if (journaledInput !== undefined && (journaledInput.role !== "user" || journaledInput.content !== input)) {
+                    throw new Error("durable input journal does not match admitted input");
+                }
+                // A run-owned reserved sequence distinguishes a retry before append from
+                // a retry after append. Actor-global history is never a replay fence.
+                const replaysJournaledInput = journaledInput !== undefined;
+                let journalThrough = replaysJournaledInput
+                    ? priorMessages.at(-1).seq
+                    : await appendMessage({ role: "user", content: input });
+                const storedMessages = !replaysJournaledInput
+                    ? await allMessages()
+                    : priorMessages;
+                const restoredApprovals = options.steps === undefined
+                    ? []
+                    : await approvalMessages.restoreRun(options.steps.runId);
+                const messages = [];
+                let restoredApprovalIndex = 0;
+                const projectedRestoredToolCallIds = new Set();
+                const restoredApprovalCalls = new Map(restoredApprovals.map(({ toolCall }) => [toolCall.toolCallId, toolCall]));
+                const completedApprovedToolCalls = new Map();
+                const replayedCompletedApprovalToolCallIds = new Set();
+                for (const stored of storedMessages) {
+                    messages.push(...historyMessages([stored]));
+                    const restoredAtBoundary = [];
+                    while (restoredApprovals[restoredApprovalIndex]?.afterMessageSeq === stored.seq) {
+                        restoredAtBoundary.push(...restoredApprovals[restoredApprovalIndex++].messages);
+                    }
+                    if (restoredAtBoundary.length > 0) {
+                        const assistantParts = [];
+                        const toolParts = [];
+                        for (const message of restoredAtBoundary) {
+                            if (message.role === "assistant") {
+                                if (typeof message.content === "string")
+                                    throw new Error("approval message chronology is invalid");
+                                assistantParts.push(...message.content);
+                            }
+                            if (message.role === "tool")
+                                toolParts.push(...message.content);
+                        }
+                        if (assistantParts.length === 0 || toolParts.length === 0)
+                            throw new Error("approval message chronology is invalid");
+                        messages.push({ role: "assistant", content: assistantParts }, { role: "tool", content: toolParts });
+                    }
+                }
+                if (restoredApprovalIndex !== restoredApprovals.length)
+                    throw new Error("approval message chronology is invalid");
+                const journaledToolCallMarkers = new Set(storedMessages.flatMap((message) => message.role === "tool" ? [decodeToolOutputEnvelope(message.content).journalMarker].filter((marker) => marker !== undefined) : []));
+                const projectedToolCallIds = new Set(storedMessages.flatMap((message) => message.role === "tool" && message.toolCallId !== undefined ? [message.toolCallId] : []));
+                options.steps?.reconcileToolCallJournal(journaledToolCallMarkers);
+                // Provider call IDs are correlation values. Durable logical positions are
+                // owned by the run-scoped step context so unrelated runs cannot move them.
+                const durableToolCallCounts = new Map();
+                let boundaryFailed = false;
+                let boundaryError;
+                let capReached = false;
+                let modelStepNumber = 0;
+                const limitReached = stepCountIs(runtimeConfig.limits.steps);
+                const assertBoundary = () => {
+                    if (boundaryFailed)
+                        throw boundaryError;
+                };
+                const modelForTurn = lifecycleMiddleware.modelStep.length === 0 || typeof runtimeConfig.model === "string"
+                    ? runtimeConfig.model
+                    : wrapLanguageModel({
+                        model: runtimeConfig.model,
+                        middleware: {
+                            wrapGenerate: async ({ doGenerate }) => (await runMiddleware(Object.freeze({
+                                phase: "modelStep",
+                                config: runtimeConfig,
+                                stepNumber: ++modelStepNumber,
+                                signal: options.signal,
+                            }), lifecycleMiddleware.modelStep, async () => await doGenerate())),
+                        },
+                    });
+                const toolsForTurn = Object.freeze(Object.fromEntries(Object.entries(runtimeConfig.tools ?? {}).map(([toolName, candidate]) => {
+                    const execute = candidate.execute;
+                    return [
+                        toolName,
+                        Object.freeze({
+                            ...candidate,
+                            async execute(...args) {
+                                const toolCallOptions = args[1];
+                                const toolCallId = typeof toolCallOptions?.toolCallId === "string"
+                                    ? toolCallOptions.toolCallId
+                                    : undefined;
+                                const durableToolCallOrdinal = options.steps === undefined
+                                    ? (durableToolCallCounts.get(toolName) ?? 0)
+                                    : options.steps.nextToolCallOrdinal(toolName, toolCallId);
+                                if (options.steps === undefined) {
+                                    durableToolCallCounts.set(toolName, durableToolCallOrdinal + 1);
+                                }
+                                let coreStarted = false;
+                                let coreCompleted = false;
+                                let replayingCompletedApproval = false;
+                                try {
+                                    const output = await runMiddleware(Object.freeze({
+                                        phase: "tool",
+                                        config: runtimeConfig,
+                                        toolName,
+                                        toolCallId,
+                                        signal: options.signal,
+                                    }), lifecycleMiddleware.tool, async () => {
+                                        const stepName = `tool:${toolName}:${durableToolCallOrdinal}`;
+                                        const stepVersion = spec.durability?.toolStepVersion ?? DURABLE_TOOL_STEP_VERSION;
+                                        const restoringCompletedApproval = options.steps !== undefined
+                                            && toolCallId !== undefined
+                                            && restoredApprovalCalls.has(toolCallId)
+                                            && !projectedToolCallIds.has(toolCallId)
+                                            && options.steps.isCompleted(stepName, { input: args[0], version: stepVersion });
+                                        replayingCompletedApproval = restoringCompletedApproval;
+                                        const authorizedEffect = options.steps === undefined || restoringCompletedApproval
+                                            ? undefined
+                                            : await approvals.reauthorizeEffect(options.steps.runId, toolCallId, toolName, args[0]);
+                                        const approvalId = authorizedEffect?.id;
+                                        const effectArgs = authorizedEffect === undefined
+                                            ? args
+                                            : [authorizedEffect.input, ...args.slice(1)];
+                                        coreStarted = true;
+                                        const result = options.steps === undefined
+                                            ? cloneToolOutput(toolName, await execute.apply(this, args))
+                                            : await options.steps.step(stepName, async () => await withHarnessToolContext(Object.freeze({ runId: options.steps.runId, toolName, ordinal: durableToolCallOrdinal }), async () => await execute.apply(this, effectArgs)), {
+                                                external: true,
+                                                beforeEffect: () => approvals.consumeAuthorizedEffect(options.steps.runId, approvalId),
+                                                input: args[0],
+                                                version: stepVersion,
+                                            });
+                                        coreCompleted = true;
+                                        return result;
+                                    });
+                                    const restoredCall = toolCallId === undefined ? undefined : restoredApprovalCalls.get(toolCallId);
+                                    if (restoredCall !== undefined) {
+                                        const approvedOutput = typeof output === "string"
+                                            ? { type: "text", value: output }
+                                            : { type: "json", value: toJsonValue(output) };
+                                        completedApprovedToolCalls.set(toolCallId, Object.freeze({
+                                            ...restoredCall,
+                                            output: approvedOutput,
+                                        }));
+                                        if (replayingCompletedApproval)
+                                            replayedCompletedApprovalToolCallIds.add(toolCallId);
+                                    }
+                                    return cloneToolOutput(toolName, output);
+                                }
+                                catch (error) {
+                                    // AI SDK represents ordinary tool execution failures as durable tool-error
+                                    // parts. A middleware short-circuit failure has no core execution to encode,
+                                    // so preserve it as the turn's authoritative boundary error instead.
+                                    const durableToolOutputSerializationFailure = isToolOutputSerializationFailure(error);
+                                    if ((options.steps !== undefined || !coreStarted || coreCompleted)
+                                        && !boundaryFailed) {
+                                        boundaryFailed = true;
+                                        boundaryError = durableToolOutputSerializationFailure ? new HarnessToolOutputError(toolName) : error;
+                                    }
+                                    throw error;
+                                }
+                            },
+                        }),
+                    ];
+                })));
+                const durableSteps = options.steps;
+                const onToolCallStart = durableSteps === undefined
+                    ? options.callbacks?.onToolCallStart
+                    : async (event) => {
+                        // AI SDK executes the per-call callback synchronously in model order
+                        // before any awaited callback can permit a later call to execute.
+                        // Reserve here rather than in wrapped execute(), whose start order is
+                        // concurrent and therefore not durable identity.
+                        durableSteps.nextToolCallOrdinal(event.toolCall.toolName, event.toolCall.toolCallId);
+                        await options.callbacks?.onToolCallStart?.(event);
+                    };
+                const generation = generateText({
+                    model: modelForTurn,
+                    tools: toolsForTurn,
+                    ...(runtimeConfig.output === undefined ? {} : { output: runtimeConfig.output }),
+                    abortSignal: options.signal,
+                    system: runtimeConfig.instructions,
+                    messages,
+                    experimental_onStart: options.callbacks?.onStart,
+                    experimental_onStepStart: options.callbacks?.onStepStart,
+                    experimental_onToolCallStart: onToolCallStart,
+                    experimental_onToolCallFinish: options.callbacks?.onToolCallFinish,
+                    prepareStep() {
+                        assertBoundary();
+                        return undefined;
+                    },
+                    async stopWhen(context) {
+                        assertBoundary();
+                        const reached = await limitReached(context);
+                        if (reached)
+                            capReached = true;
+                        return reached;
+                    },
+                    async onStepFinish(step) {
+                        try {
+                            assertBoundary();
+                            const approvalRequests = step.content.filter((part) => part.type === "tool-approval-request");
+                            const pendingRequests = options.steps === undefined ? [] : await Promise.all(approvalRequests.map(async (request) => replayedCompletedApprovalToolCallIds.has(request.toolCall.toolCallId)
+                                || (await approvals.inspectUnchecked(request.approvalId))?.status === "granted"
+                                ? undefined
+                                : request));
+                            if (pendingRequests.some((request) => request !== undefined) && options.steps !== undefined) {
+                                const requests = pendingRequests.filter((request) => request !== undefined).map((request) => {
+                                    const call = step.toolCalls.find((candidate) => candidate.toolCallId === request.toolCall.toolCallId);
+                                    const action = call === undefined ? undefined : authorization?.toolActions[call.toolName];
+                                    const ttl = authorization?.approvalTtlMs;
+                                    if (call === undefined || action === undefined || ttl === undefined)
+                                        throw new Error("approval request linkage is invalid");
+                                    return { request, call, action, ttl };
+                                });
+                                if (requests.length !== approvalRequests.length)
+                                    throw new Error("approval request batch mixes granted and pending requests");
+                                const pendingToolCallIds = new Set(requests.map(({ call }) => call.toolCallId));
+                                const restoredCalls = [...completedApprovedToolCalls.values()]
+                                    .filter((call) => !projectedRestoredToolCallIds.has(call.toolCallId));
+                                const restoredToolCallIds = new Set(restoredCalls.map((call) => call.toolCallId));
+                                const completedCalls = [
+                                    ...step.toolCalls.filter((call) => !pendingToolCallIds.has(call.toolCallId) && !restoredToolCallIds.has(call.toolCallId)),
+                                    ...restoredCalls,
+                                ];
+                                if (completedCalls.length > 0) {
+                                    const journalMarkers = options.steps.associateToolCallJournal(completedCalls.map((call) => ({
+                                        toolName: call.toolName,
+                                        toolCallId: call.toolCallId,
+                                    })));
+                                    journalThrough = await appendMessages([
+                                        ...journalForApprovedToolCalls(restoredCalls, journalMarkers),
+                                        ...journalForStep(step, journalMarkers, step.toolCalls.filter((call) => !pendingToolCallIds.has(call.toolCallId) && !restoredToolCallIds.has(call.toolCallId))),
+                                    ]);
+                                    for (const marker of journalMarkers.values())
+                                        journaledToolCallMarkers.add(marker);
+                                    for (const call of completedCalls)
+                                        projectedToolCallIds.add(call.toolCallId);
+                                    for (const call of restoredCalls)
+                                        projectedRestoredToolCallIds.add(call.toolCallId);
+                                }
+                                await approvals.requestBatchWithPause(requests.map(({ request, call, action, ttl }) => ({
+                                    id: request.approvalId, runId: options.steps.runId, toolName: call.toolName, toolCallId: call.toolCallId,
+                                    arguments: call.input, requiredAction: action, expiresAt: spec.ports.clock.now() + ttl,
+                                })), () => {
+                                    const firstJournalSeq = approvalMessages.nextRunSequence(options.steps.runId);
+                                    const approvalEpoch = approvalMessages.nextRunApprovalEpoch(options.steps.runId);
+                                    for (const [index, { request, call }] of requests.entries())
+                                        approvalMessages.requestInTransaction({
+                                            runId: options.steps.runId, approvalId: request.approvalId, toolCallId: call.toolCallId, toolName: call.toolName,
+                                            journalSeq: firstJournalSeq + index, afterMessageSeq: journalThrough, approvalEpoch,
+                                            canonicalToolCall: { toolCallId: call.toolCallId, toolName: call.toolName, input: call.input },
+                                            ...(request.signature === undefined ? {} : { signature: request.signature }),
+                                        });
+                                    ledger.pauseForApproval(options.steps.runId);
+                                });
+                                throw new HarnessApprovalPause();
+                            }
+                            const restoredCalls = [...completedApprovedToolCalls.values()]
+                                .filter((call) => !projectedRestoredToolCallIds.has(call.toolCallId));
+                            const restoredToolCallIds = new Set(restoredCalls.map((call) => call.toolCallId));
+                            const completedCalls = [
+                                ...step.toolCalls.filter((call) => !restoredToolCallIds.has(call.toolCallId)),
+                                ...restoredCalls,
+                            ];
+                            const journalMarkers = completedCalls.length === 0
+                                ? new Map()
+                                : options.steps?.associateToolCallJournal(completedCalls.map((call) => ({
+                                    toolName: call.toolName,
+                                    toolCallId: call.toolCallId,
+                                }))) ?? new Map();
+                            journalThrough = await appendMessages([
+                                ...journalForApprovedToolCalls(restoredCalls, journalMarkers),
+                                ...journalForStep(step, journalMarkers, step.toolCalls.filter((call) => !restoredToolCallIds.has(call.toolCallId))),
+                            ]);
+                            for (const marker of journalMarkers.values())
+                                journaledToolCallMarkers.add(marker);
+                            for (const call of completedCalls)
+                                projectedToolCallIds.add(call.toolCallId);
+                            for (const call of restoredCalls)
+                                projectedRestoredToolCallIds.add(call.toolCallId);
+                            await options.onStepCommitted?.(observedStep(step, journalThrough));
+                            await options.callbacks?.onStepFinish?.(step);
+                        }
+                        catch (error) {
+                            if (!boundaryFailed) {
+                                boundaryFailed = true;
+                                boundaryError = error;
+                            }
+                            throw error;
+                        }
+                    },
+                    onFinish: options.callbacks?.onFinish,
+                });
+                let result;
+                try {
+                    result = await generation;
+                }
+                catch (error) {
+                    if (boundaryFailed)
+                        throw boundaryError;
+                    if (isProviderFailure(error)) {
+                        throw new HarnessProviderError(providerDiagnostics(runtimeConfig.model, error));
+                    }
+                    throw error;
+                }
+                assertBoundary();
+                if (capReached) {
+                    const lastStep = result.steps.at(-1);
+                    throw new HarnessStepLimitError(runtimeConfig.limits.steps, result.steps.length, (lastStep?.toolCalls ?? []).map((call) => ({
+                        id: call.toolCallId,
+                        name: call.toolName,
+                    })));
+                }
+                const output = Object.freeze({
+                    text: result.text,
+                    stepCount: result.steps.length,
+                    finishReason: result.finishReason,
+                    journalThrough,
+                    usage: Object.freeze({
+                        inputTokens: result.totalUsage.inputTokens,
+                        outputTokens: result.totalUsage.outputTokens,
+                        totalTokens: result.totalUsage.totalTokens,
+                    }),
+                    ...(runtimeConfig.output === undefined
+                        ? {}
+                        : { output: result.output }),
+                });
+                await options.onOutput?.(output);
+                return output;
+            });
+        }
+        catch (error) {
+            const cancellation = error instanceof HarnessCancellationError
+                || (options.signal?.aborted === true
+                    && error instanceof Error
+                    && error.name === "AbortError");
+            if (cancellation) {
+                const classified = error instanceof HarnessCancellationError
+                    ? error
+                    : new HarnessCancellationError();
+                try {
+                    await options.onCancel?.(classified);
+                }
+                catch (observer) {
+                    throw new HarnessObserverError(classified, observer, "cancel");
+                }
+                throw classified;
+            }
+            try {
+                await options.onError?.(error);
+            }
+            catch (observer) {
+                throw new HarnessObserverError(error, observer, "error");
+            }
+            throw error;
+        }
+    };
+    const ledger = createHarnessRunExecutionLedger(spec.ports, async (input, signal, steps) => {
+        // Journal correlation enriches scheduling recovery, but it must not turn
+        // an otherwise executable durable run into a failed one when the journal
+        // port is temporarily unavailable.
+        let journalBefore;
+        try {
+            journalBefore = await spec.ports.messages.count();
+        }
+        catch { /* correlation is repairable */ }
+        const persistJournal = (journalSeq) => {
+            spec.ports.sql.transactionSync(() => spec.ports.sql.exec("INSERT INTO __telnyx_agent_harness_run_journal(run_id,journal_seq) VALUES (?,?) ON CONFLICT(run_id) DO UPDATE SET journal_seq = excluded.journal_seq", steps.runId, journalSeq));
+        };
+        // A cancellation can terminalize this claimed run before the model turn
+        // reaches a later journal boundary. Persist the known pre-turn boundary
+        // first, so restart correlation never depends on a post-cancel port read.
+        if (journalBefore !== undefined)
+            persistJournal(journalBefore);
+        try {
+            const result = await turn(input, {
+                signal,
+                steps,
+                ...(spec.durability?.onToolCallStart === undefined
+                    ? {}
+                    : { callbacks: { onToolCallStart: spec.durability.onToolCallStart } }),
+            });
+            // This is written within the durable turn before ledger.run() marks the
+            // run completed. A scheduler occurrence can recover its exact journal
+            // linkage by run id even if its post-dispatch wrapper never resumes.
+            persistJournal(result.journalThrough);
+            return result;
+        }
+        catch (error) {
+            // A terminal turn can fail after durably appending the admitted input or
+            // a tool boundary. The serialized actor journal advanced only for this
+            // run, so persist that exact boundary for recovery; failures before any
+            // append intentionally have no journal correlation to invent.
+            const hasScheduledJournalMarker = spec.ports.sql.exec("SELECT run_id FROM __telnyx_agent_harness_run_journal WHERE run_id = ?", steps.runId).toArray().length > 0;
+            if (journalBefore !== undefined || hasScheduledJournalMarker) {
+                try {
+                    const journalAfter = await spec.ports.messages.count();
+                    if (journalBefore === undefined || journalAfter > journalBefore)
+                        persistJournal(journalAfter);
+                }
+                catch { /* correlation is repairable */ }
+            }
+            throw error;
+        }
+    }, { checkpoints: spec.durability?.checkpoints, requireApprovalIdentity: requiresApprovalIdentity });
+    const approvalService = Object.freeze({
+        inspect: approvals.inspect,
+        async grant(id) {
+            let approval;
+            try {
+                approval = await approvals.grantWithResume(id, (granted) => {
+                    approvalMessages.decideInTransaction({ approvalId: id, approved: true });
+                }, (granted) => ledger.resumeForApproval(granted.runId));
+            }
+            catch (error) {
+                if (error instanceof HarnessApprovalError && error.code === "expired") {
+                    const expired = await approvals.inspectUnchecked(id);
+                    if (expired?.status === "expired")
+                        await ledger.expireForApproval(expired.runId);
+                }
+                throw error;
+            }
+            await ledger.resume(approval.runId);
+            return approval;
+        },
+        async deny(id) {
+            let approval;
+            try {
+                approval = await approvals.denyWithCancel(id, (denied) => {
+                    approvalMessages.decideInTransaction({ approvalId: id, approved: false, reason: "denied" });
+                    ledger.resumeForApproval(denied.runId);
+                });
+            }
+            catch (error) {
+                if (error instanceof HarnessApprovalError && error.code === "expired") {
+                    const expired = await approvals.inspectUnchecked(id);
+                    if (expired?.status === "expired")
+                        await ledger.expireForApproval(expired.runId);
+                }
+                throw error;
+            }
+            await ledger.resume(approval.runId);
+            return approval;
+        },
+    });
+    return Object.freeze({
+        turn,
+        accept: ledger.accept,
+        get: ledger.get,
+        status: ledger.status,
+        list: ledger.list,
+        cancel: ledger.cancel,
+        recover: ledger.recover,
+        run: ledger.run,
+        dispatch: ledger.dispatch,
+        approvals: approvalService,
+    });
+}
+//# sourceMappingURL=harness.js.map