@telnyx/agent-harness 0.1.0-beta.0 → 0.1.0-beta.2

package/dist/harness.js

@@ -1,15 +1,26 @@
 import { GatewayError } from "@ai-sdk/gateway";
-import { AISDKError, APICallError, RetryError, asSchema, generateText, jsonSchema, stepCountIs, wrapLanguageModel, } from "ai";
+import { AISDKError, APICallError, RetryError, asSchema, generateText, streamText, jsonSchema, stepCountIs, wrapLanguageModel, } from "ai";
 import { z } from "zod/v4";
+import { traceActive, traceBind, voiceTraceContext, traceAttempt, traceStage } from "@telnyx/edge-runtime/internal";
+import { traceModel, traceToolExecution } from "./voice-trace.js";
 import { isToolOutputSerializationFailure } from "./steps.js";
+import { inspectHarnessRun } from "./diagnostics.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";
+import { HarnessSpeculationUnsupportedError, serializeTurn, speculativeTurn, } from "./speculative.js";
+export { HarnessSpeculationConflictError, HarnessSpeculationUnsupportedError, } from "./speculative.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";
+function assertSpeculativeSdkHooks() {
+    if (globalThis.AI_SDK_TELEMETRY_INTEGRATIONS?.length
+        || typeof globalThis.AI_SDK_LOG_WARNINGS === "function") {
+        throw new HarnessSpeculationUnsupportedError("global AI SDK lifecycle integrations or custom warning callbacks");
+    }
+}
 /** Raised after the final allowed model step still requests executable tools. */
 export class HarnessStepLimitError extends Error {
     maxSteps;
@@ -66,6 +77,45 @@ export class HarnessObserverError extends Error {
         this.name = "HarnessObserverError";
     }
 }
+async function cancelTurn(onCancel, cancellation = new HarnessCancellationError()) {
+    try {
+        await onCancel?.(cancellation);
+    }
+    catch (observer) {
+        throw new HarnessObserverError(cancellation, observer, "cancel");
+    }
+    throw cancellation;
+}
+function captureSpeculativeOptions(options) {
+    // Inspect descriptors, not values: spreading invokes getters. A detached
+    // null-prototype snapshot cannot inherit hooks installed while queued.
+    const supported = new Set(["signal", "onStepCommitted", "onOutput"]);
+    const unsupported = new Set(["steps", "callbacks", "onCancel", "onError"]);
+    if (options === null || typeof options !== "object"
+        || ![Object.prototype, null].includes(Object.getPrototypeOf(options))) {
+        throw new HarnessSpeculationUnsupportedError("non-plain turn options");
+    }
+    const captured = Object.create(null);
+    for (const key of Reflect.ownKeys(options)) {
+        const descriptor = Object.getOwnPropertyDescriptor(options, key);
+        if (key === voiceTraceContext && descriptor.enumerable && "value" in descriptor) {
+            Object.defineProperty(captured, key, descriptor);
+            continue;
+        }
+        if (typeof key !== "string" || !descriptor.enumerable || !("value" in descriptor)
+            || (!supported.has(key) && !unsupported.has(key))
+            || (unsupported.has(key) && descriptor.value !== undefined)) {
+            throw new HarnessSpeculationUnsupportedError("accessors, inherited options, or pre-model lifecycle hooks");
+        }
+        if (supported.has(key)) {
+            if (key !== "signal" && descriptor.value !== undefined && typeof descriptor.value !== "function") {
+                throw new HarnessSpeculationUnsupportedError("non-function observers");
+            }
+            Object.defineProperty(captured, key, descriptor);
+        }
+    }
+    return Object.freeze(captured);
+}
 function historyMessages(stored) {
     return stored.map((message) => {
         if (message.role === "assistant") {
@@ -652,9 +702,11 @@ function validateTools(tools, authorization) {
 }
 /** Construct a portable AI SDK v6 turn engine over an explicit ports object. */
 export function createHarness(spec) {
+    const activation = spec.ports.activation;
+    const diagnostics = traceBind(spec.diagnostics, activation);
     const messagePort = spec.ports.messages;
-    const appendMessage = messagePort.append.bind(messagePort);
-    const appendMessages = messagePort.appendMany.bind(messagePort);
+    const appendMessagePort = messagePort.append.bind(messagePort);
+    const appendMessagesPort = messagePort.appendMany.bind(messagePort);
     const allMessages = messagePort.all.bind(messagePort);
     const getState = spec.ports.state.get.bind(spec.ports.state);
     const model = spec.model;
@@ -697,22 +749,25 @@ export function createHarness(spec) {
     let lastValidRuntimeConfig = resolveHarnessRuntimeConfig(staticRuntimeConfig, undefined).config;
     let runtimeConfigReadSequence = 0;
     let lastPublishedRuntimeConfigReadSequence = 0;
-    const turn = async (input, options = {}) => {
+    const executeTurn = async (input, options = {}, speculation) => {
+        const trace = options[voiceTraceContext]?.scope === diagnostics ? options[voiceTraceContext] : traceAttempt(diagnostics, 0, "confirmed");
+        const committedEffect = (work) => speculation ? speculation.write(work) : work();
+        const appendMessage = (message) => speculation
+            ? speculation.write(() => appendMessagePort(message)) : appendMessagePort(message);
+        const appendMessages = (batch) => speculation
+            ? speculation.write(() => appendMessagesPort(batch)) : appendMessagesPort(batch);
         if (options.signal?.aborted) {
-            const cancellation = new HarnessCancellationError();
-            try {
-                await options.onCancel?.(cancellation);
-            }
-            catch (observer) {
-                throw new HarnessObserverError(cancellation, observer, "cancel");
-            }
-            throw cancellation;
+            return cancelTurn(options.onCancel);
         }
         try {
             const runtimeConfigReadSequenceForTurn = ++runtimeConfigReadSequence;
             const state = await getState();
+            speculation?.assertLive();
             const resolution = resolveHarnessRuntimeConfig(staticRuntimeConfig, state.__telnyx_agent_harness, lastValidRuntimeConfig);
             const runtimeConfig = resolution.config;
+            if (speculation && runtimeConfig.output !== undefined) {
+                throw new HarnessSpeculationUnsupportedError("structured output");
+            }
             if (typeof runtimeConfig.model === "string" && lifecycleMiddleware.modelStep.length > 0) {
                 throw new TypeError("Harness model-step middleware requires an executable LanguageModel");
             }
@@ -731,7 +786,11 @@ export function createHarness(spec) {
             });
             return await runMiddleware(turnContext, lifecycleMiddleware.turn, async () => {
                 await toolSnapshot.preflight(Object.keys(runtimeConfig.tools ?? {}));
+                speculation?.assertLive();
                 const priorMessages = await allMessages();
+                speculation?.assertLive();
+                if (speculation)
+                    assertSpeculativeSdkHooks();
                 const inputSteps = options.steps;
                 const inputJournal = inputSteps === undefined
                     ? undefined
@@ -775,10 +834,29 @@ export function createHarness(spec) {
                 const replaysJournaledInput = journaledInput !== undefined;
                 let journalThrough = replaysJournaledInput
                     ? priorMessages.at(-1).seq
-                    : await appendMessage({ role: "user", content: input });
-                const storedMessages = !replaysJournaledInput
-                    ? await allMessages()
-                    : priorMessages;
+                    : speculation ? (priorMessages.at(-1)?.seq ?? 0) : await appendMessage({ role: "user", content: input });
+                const storedMessages = speculation
+                    ? [...priorMessages, { role: "user", content: input, seq: journalThrough + 1, at: new Date(spec.ports.clock.now()) }]
+                    : !replaysJournaledInput
+                        ? await allMessages()
+                        : priorMessages;
+                // The append-only port allocates the confirmed input's actual sequence.
+                // No speculative reservation can conflict with unrelated message writers.
+                let publication;
+                let confirmedForModel;
+                const confirmedMessages = (batch) => confirmedForModel === undefined ? batch : batch.map((message, index) => index === priorMessages.length ? { role: "user", content: confirmedForModel } : message);
+                const publishInput = () => {
+                    if (!speculation)
+                        return Promise.resolve();
+                    publication ??= (async () => {
+                        const confirmed = await speculation.confirmed();
+                        speculation.assertLive();
+                        confirmedForModel = confirmed;
+                        journalThrough = await appendMessage({ role: "user", content: confirmed });
+                        speculation.assertLive();
+                    })();
+                    return publication;
+                };
                 const restoredApprovals = options.steps === undefined
                     ? []
                     : await approvalMessages.restoreRun(options.steps.runId);
@@ -825,9 +903,18 @@ export function createHarness(spec) {
                 let modelStepNumber = 0;
                 const limitReached = stepCountIs(runtimeConfig.limits.steps);
                 const assertBoundary = () => {
+                    speculation?.assertLive();
                     if (boundaryFailed)
                         throw boundaryError;
                 };
+                if (speculation)
+                    void publishInput().catch((error) => {
+                        if (!boundaryFailed) {
+                            boundaryFailed = true;
+                            boundaryError = error;
+                        }
+                        speculation.fail(error);
+                    });
                 const modelForTurn = lifecycleMiddleware.modelStep.length === 0 || typeof runtimeConfig.model === "string"
                     ? runtimeConfig.model
                     : wrapLanguageModel({
@@ -847,7 +934,21 @@ export function createHarness(spec) {
                         toolName,
                         Object.freeze({
                             ...candidate,
+                            ...(speculation ? {
+                                inputSchema: jsonSchema(async () => await asSchema(candidate.inputSchema).jsonSchema, {
+                                    validate: async (value) => {
+                                        await publishInput();
+                                        assertBoundary();
+                                        const schema = asSchema(candidate.inputSchema);
+                                        return schema.validate
+                                            ? await committedEffect(async () => await schema.validate(value))
+                                            : { success: true, value };
+                                    },
+                                }),
+                            } : {}),
                             async execute(...args) {
+                                await publishInput();
+                                assertBoundary();
                                 const toolCallOptions = args[1];
                                 const toolCallId = typeof toolCallOptions?.toolCallId === "string"
                                     ? toolCallOptions.toolCallId
@@ -862,13 +963,14 @@ export function createHarness(spec) {
                                 let coreCompleted = false;
                                 let replayingCompletedApproval = false;
                                 try {
-                                    const output = await runMiddleware(Object.freeze({
+                                    const output = await committedEffect(() => runMiddleware(Object.freeze({
                                         phase: "tool",
                                         config: runtimeConfig,
                                         toolName,
                                         toolCallId,
                                         signal: options.signal,
                                     }), lifecycleMiddleware.tool, async () => {
+                                        assertBoundary();
                                         const stepName = `tool:${toolName}:${durableToolCallOrdinal}`;
                                         const stepVersion = spec.durability?.toolStepVersion ?? DURABLE_TOOL_STEP_VERSION;
                                         const restoringCompletedApproval = options.steps !== undefined
@@ -881,13 +983,21 @@ export function createHarness(spec) {
                                             ? undefined
                                             : await approvals.reauthorizeEffect(options.steps.runId, toolCallId, toolName, args[0]);
                                         const approvalId = authorizedEffect?.id;
-                                        const effectArgs = authorizedEffect === undefined
+                                        let effectArgs = authorizedEffect === undefined
                                             ? args
                                             : [authorizedEffect.input, ...args.slice(1)];
+                                        if (speculation) {
+                                            const callOptions = objectRecord(effectArgs[1]);
+                                            if (Array.isArray(callOptions?.messages))
+                                                effectArgs = [effectArgs[0], {
+                                                        ...callOptions, messages: confirmedMessages(callOptions.messages),
+                                                    }, ...effectArgs.slice(2)];
+                                        }
+                                        assertBoundary();
                                         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)), {
+                                            ? cloneToolOutput(toolName, await committedEffect(async () => { traceToolExecution(trace, effectArgs[1]?.experimental_context); return await execute.apply(this, effectArgs); }))
+                                            : await options.steps.step(stepName, async () => await withHarnessToolContext(Object.freeze({ runId: options.steps.runId, toolName, ordinal: durableToolCallOrdinal }), async () => { traceToolExecution(trace, effectArgs[1]?.experimental_context); return await execute.apply(this, effectArgs); }), {
                                                 external: true,
                                                 beforeEffect: () => approvals.consumeAuthorizedEffect(options.steps.runId, approvalId),
                                                 input: args[0],
@@ -895,7 +1005,7 @@ export function createHarness(spec) {
                                             });
                                         coreCompleted = true;
                                         return result;
-                                    });
+                                    }));
                                     const restoredCall = toolCallId === undefined ? undefined : restoredApprovalCalls.get(toolCallId);
                                     if (restoredCall !== undefined) {
                                         const approvedOutput = typeof output === "string"
@@ -937,8 +1047,8 @@ export function createHarness(spec) {
                         durableSteps.nextToolCallOrdinal(event.toolCall.toolName, event.toolCall.toolCallId);
                         await options.callbacks?.onToolCallStart?.(event);
                     };
-                const generation = generateText({
-                    model: modelForTurn,
+                const generationOptions = {
+                    model: traceModel(modelForTurn, trace),
                     tools: toolsForTurn,
                     ...(runtimeConfig.output === undefined ? {} : { output: runtimeConfig.output }),
                     abortSignal: options.signal,
@@ -948,9 +1058,15 @@ export function createHarness(spec) {
                     experimental_onStepStart: options.callbacks?.onStepStart,
                     experimental_onToolCallStart: onToolCallStart,
                     experimental_onToolCallFinish: options.callbacks?.onToolCallFinish,
-                    prepareStep() {
+                    prepareStep({ messages: stepMessages }) {
                         assertBoundary();
-                        return undefined;
+                        const confirmed = speculation && confirmedForModel !== undefined ? { messages: confirmedMessages(stepMessages) } : undefined;
+                        if (!traceActive(trace))
+                            return confirmed;
+                        // An empty per-step handoff carries no diagnostic metadata into results.
+                        // The source model and executor privately share its object identity.
+                        const handoff = Object.freeze({});
+                        return { ...confirmed, model: traceModel(modelForTurn, trace, handoff), experimental_context: handoff };
                     },
                     async stopWhen(context) {
                         assertBoundary();
@@ -961,6 +1077,7 @@ export function createHarness(spec) {
                     },
                     async onStepFinish(step) {
                         try {
+                            await publishInput();
                             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)
@@ -1042,7 +1159,12 @@ export function createHarness(spec) {
                                 projectedToolCallIds.add(call.toolCallId);
                             for (const call of restoredCalls)
                                 projectedRestoredToolCallIds.add(call.toolCallId);
-                            await options.onStepCommitted?.(observedStep(step, journalThrough));
+                            assertBoundary();
+                            if (options.onStepCommitted) {
+                                const snapshot = observedStep(step, journalThrough);
+                                await committedEffect(async () => { await options.onStepCommitted(snapshot); });
+                            }
+                            assertBoundary();
                             await options.callbacks?.onStepFinish?.(step);
                         }
                         catch (error) {
@@ -1054,7 +1176,40 @@ export function createHarness(spec) {
                         }
                     },
                     onFinish: options.callbacks?.onFinish,
-                });
+                };
+                const generation = speculation ? (async () => {
+                    let streamFailure;
+                    let streamFailed = false;
+                    const onStreamError = (error) => {
+                        streamFailed = true;
+                        streamFailure = boundaryFailed ? boundaryError : isProviderFailure(error)
+                            ? new HarnessProviderError(providerDiagnostics(runtimeConfig.model, error)) : error;
+                        speculation.fail(streamFailure);
+                    };
+                    const streamed = streamText({
+                        ...generationOptions,
+                        onError: ({ error }) => onStreamError(error),
+                        onChunk: ({ chunk }) => {
+                            assertBoundary();
+                            const part = objectRecord(chunk);
+                            if (part?.type === "text-delta" && typeof part.text === "string") {
+                                traceStage(trace, "text_forwarded");
+                                speculation.text(part.text);
+                            }
+                        },
+                    });
+                    await streamed.consumeStream({ onError: onStreamError });
+                    assertBoundary();
+                    if (streamFailed)
+                        throw streamFailure;
+                    return {
+                        text: await streamed.text,
+                        steps: await streamed.steps,
+                        finishReason: await streamed.finishReason,
+                        totalUsage: await streamed.totalUsage,
+                        output: undefined,
+                    };
+                })() : generateText(generationOptions);
                 let result;
                 try {
                     result = await generation;
@@ -1075,6 +1230,8 @@ export function createHarness(spec) {
                         name: call.toolName,
                     })));
                 }
+                if (!speculation)
+                    traceStage(trace, "text_forwarded");
                 const output = Object.freeze({
                     text: result.text,
                     stepCount: result.steps.length,
@@ -1089,7 +1246,9 @@ export function createHarness(spec) {
                         ? {}
                         : { output: result.output }),
                 });
-                await options.onOutput?.(output);
+                assertBoundary();
+                if (options.onOutput)
+                    await committedEffect(async () => { await options.onOutput(output); });
                 return output;
             });
         }
@@ -1102,13 +1261,7 @@ export function createHarness(spec) {
                 const classified = error instanceof HarnessCancellationError
                     ? error
                     : new HarnessCancellationError();
-                try {
-                    await options.onCancel?.(classified);
-                }
-                catch (observer) {
-                    throw new HarnessObserverError(classified, observer, "cancel");
-                }
-                throw classified;
+                return cancelTurn(options.onCancel, classified);
             }
             try {
                 await options.onError?.(error);
@@ -1119,6 +1272,23 @@ export function createHarness(spec) {
             throw error;
         }
     };
+    const turn = (input, options = {}) => serializeTurn(activation, () => executeTurn(input, options), false, options.signal, () => cancelTurn(options.onCancel));
+    const begin = (input, options = {}) => {
+        const capturedOptions = captureSpeculativeOptions(options);
+        assertSpeculativeSdkHooks();
+        // A captured catalog can select output from async runtime state. Refuse
+        // before returning a handle so voice can safely fall back after confirmation.
+        if (lifecycleMiddleware.turn.length || lifecycleMiddleware.modelStep.length
+            || staticRuntimeConfig.output !== undefined || Object.keys(outputs).length > 0) {
+            throw new HarnessSpeculationUnsupportedError("durable step contexts, pre-model lifecycle hooks, or structured output");
+        }
+        return speculativeTurn(activation, capturedOptions.signal, () => new HarnessCancellationError(), (control) => executeTurn(input, Object.freeze(Object.assign(Object.create(null), {
+            signal: control.signal,
+            onStepCommitted: capturedOptions.onStepCommitted,
+            onOutput: capturedOptions.onOutput,
+            [voiceTraceContext]: capturedOptions[voiceTraceContext],
+        })), control));
+    };
     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
@@ -1168,6 +1338,7 @@ export function createHarness(spec) {
         }
     }, { checkpoints: spec.durability?.checkpoints, requireApprovalIdentity: requiresApprovalIdentity });
     const approvalService = Object.freeze({
+        listPending: approvals.listPending,
         inspect: approvals.inspect,
         async grant(id) {
             let approval;
@@ -1209,8 +1380,10 @@ export function createHarness(spec) {
     });
     return Object.freeze({
         turn,
+        begin,
         accept: ledger.accept,
         get: ledger.get,
+        inspectRun: (runId, options) => inspectHarnessRun(spec.ports, runId, options),
         status: ledger.status,
         list: ledger.list,
         cancel: ledger.cancel,

package/dist/index.d.ts

@@ -2,9 +2,11 @@
 export * from "./ports.js";
 export * from "./runtime-adapter.js";
 export * from "./harness.js";
+export { HarnessSpeculationConflictError, HarnessSpeculationUnsupportedError, type HarnessSpeculativeTurn, } from "./speculative.js";
 export { HARNESS_RUN_STATUSES, HarnessApprovalPause, HarnessInjectedCrash, createHarnessRunLedger, ensureHarnessDurabilitySchema, type HarnessCheckpoint, type HarnessRun, type HarnessRunAcceptance, type HarnessRunLedger, type HarnessRunLedgerOptions, type HarnessRunListOptions, type HarnessRunStatus, } from "./durable.js";
-export { HARNESS_APPROVAL_STATUSES, HarnessApprovalError, HarnessAuthorizationError, type HarnessApproval, type HarnessApprovalLedger, type HarnessApprovalStatus, } from "./approvals.js";
+export { HARNESS_APPROVAL_STATUSES, HarnessApprovalError, HarnessAuthorizationError, type HarnessApproval, type HarnessApprovalLedger, type HarnessApprovalStatus, type HarnessPendingApprovalSummary, type HarnessPendingApprovalPage, type HarnessPendingApprovalListOptions, } from "./approvals.js";
 export * from "./steps.js";
+export type { HarnessRunInspection, HarnessRunInspectionOptions } from "./diagnostics.js";
 export * from "./lifecycle.js";
 export * from "./channel.js";
 export * from "./scheduling.js";

package/dist/index.js

@@ -9,6 +9,7 @@ export * from "./runtime-adapter.js";
 // "@telnyx/agent-harness/node" subpath (internal code from
 // "./node-adapter.js"). The clean-consumer CI check enforces both directions.
 export * from "./harness.js";
+export { HarnessSpeculationConflictError, HarnessSpeculationUnsupportedError, } from "./speculative.js";
 export { HARNESS_RUN_STATUSES, HarnessApprovalPause, HarnessInjectedCrash, createHarnessRunLedger, ensureHarnessDurabilitySchema, } from "./durable.js";
 export { HARNESS_APPROVAL_STATUSES, HarnessApprovalError, HarnessAuthorizationError, } from "./approvals.js";
 export * from "./steps.js";

package/dist/ports.d.ts

@@ -17,6 +17,20 @@ export interface AgentHarnessAuthorizationIdentity {
 /** Versioned private authorization capability required for approval decisions. */
 export interface HarnessAuthorizationPort {
     identity(): AgentHarnessAuthorizationIdentity | undefined;
+    /**
+     * Optional explicit authority to enumerate minimal pending summaries, including
+     * pagination lookahead, for this actor/organization/run. An individual read
+     * allow is not collection authority. Hosts must opt in and enforce run access.
+     */
+    authorizePendingApprovalSummaries?(request: Readonly<{
+        identity: AgentHarnessAuthorizationIdentity;
+        actorId: string;
+        action: "agent_harness.approvals.list_pending";
+        resource: string;
+        runId: string;
+    }>): Promise<Readonly<{
+        kind: "allow" | "deny" | "unavailable";
+    }>>;
     authorize(request: Readonly<{
         identity: AgentHarnessAuthorizationIdentity;
         action: string;

package/dist/speculative.d.ts

@@ -0,0 +1,36 @@
+/** In-memory ownership and commitment; never opens a storage transaction. */
+export declare class HarnessSpeculationConflictError extends Error {
+    readonly code: "HARNESS_SPECULATION_CONFLICT";
+    constructor();
+}
+export declare class HarnessSpeculationUnsupportedError extends Error {
+    readonly code: "HARNESS_SPECULATION_UNSUPPORTED";
+    constructor(detail: string);
+}
+/** One speculative direct turn. Text is provisional until commit succeeds. */
+export interface HarnessSpeculativeTurn<Result = {
+    text: string;
+}> {
+    /** Single-consumer, provisional text. Consuming it must not cause durable effects. */
+    readonly textStream: AsyncIterable<string>;
+    /** Observed internally even when a caller discards without awaiting it. */
+    readonly result: Promise<Result>;
+    /** First decision wins. Same text returns the same promise; different text rejects. */
+    commit(confirmed: string): Promise<Result>;
+    /** True for a discarded turn (including repeats), false after commit won. */
+    discard(): boolean;
+}
+/** FIFO exclusive reservations; ordinary callers still run concurrently. */
+export declare function serializeTurn<T>(activation: object, work: () => Promise<T>, exclusive?: boolean, signal?: AbortSignal, onQueuedCancel?: () => Promise<never>): Promise<T>;
+export interface SpeculativeControl {
+    readonly signal: AbortSignal;
+    assertLive(): void;
+    fail(error: unknown): void;
+    /** Retain ownership until an issued post-commit host effect settles. */
+    write<T>(work: () => Promise<T>): Promise<T>;
+    /** Resolves to the confirmed input; rejects on abandonment. */
+    confirmed(): Promise<string>;
+    text(delta: string): void;
+}
+export declare function speculativeTurn<Result>(activation: object, signal: AbortSignal | undefined, cancellation: () => Error, execute: (control: SpeculativeControl) => Promise<Result>): HarnessSpeculativeTurn<Result>;
+//# sourceMappingURL=speculative.d.ts.map