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

package/README.md

@@ -7,7 +7,7 @@ execution. The Node-only test adapter is intentionally isolated to a subpath.
 ## Beta and release gate
 
 This source change does not publish a package. The planned initial release is
-`0.1.0-beta.0` under the `beta` tag. The package remains `UNLICENSED`; an owner
+`0.1.0-beta.1` under the `beta` tag. The package remains `UNLICENSED`; an owner
 must approve npm organization/package ownership, distribution terms, and trusted
 publisher bootstrap before the main-only publication workflow is dispatched. A
 registry-installed `@telnyx/edge-runtime@0.15.2` is required: the runtime
@@ -61,6 +61,56 @@ const harness = createHarness({
 const result = await harness.turn("Summarize this input");
 console.log(result.text);
 ```
+## Speculative turns (begin / commit / discard)
+
+`harness.begin(input, { signal })` starts the model once its activation is available and returns a
+speculative turn handle. Nothing durable is written until `commit(confirmed)`
+is called — no user row, no assistant row, no tool-result row, no SQL run row.
+The handle exposes a `textStream` (async iterable of text deltas), a `result`
+promise, `commit(confirmedText)`, and `discard()`.
+
+```ts
+const turn = harness.begin("guess", { signal });
+// confirmedTranscript is the recognizer's Promise<string | undefined>.
+// Confirmation must run concurrently: stream completion can wait for commit.
+const commitment = confirmedTranscript.then((text) =>
+  text === undefined ? turn.discard() : turn.commit(text));
+void commitment.catch(() => {}); // observe even if the consumer exits early
+try {
+  for await (const delta of turn.textStream) prepareProvisionalText(delta);
+  await commitment;
+  await turn.result;
+} finally {
+  turn.discard(); // no-op if commitment already won
+}
+```
+
+`commit` publishes the confirmed text (not the guess) as the user row, then
+allows completed assistant/tool steps to publish. In-flight model work continues
+without restarting; all tools are deferred until commitment. Provisional text
+can be synthesized early, but audio must be held until confirmation. `discard`
+before commitment aborts the model, fences late callbacks, and leaves no durable trace; the next
+turn's `seq` follows the previous confirmed turn's with no hole. All tools —
+including read-only tools — wait until commit; there is no tool opt-in
+framework. Durable step contexts, pre-model lifecycle hooks, turn/model-step
+middleware, and structured output fail closed on `begin`; use `turn` for those.
+A static output or any nonempty construction-captured `outputs` catalog makes
+`begin` refuse synchronously, even with no runtime output currently selected.
+The default voice hook waits for confirmation and falls back to `turn` on that
+refusal; absent or empty captured catalogs still permit speculation.
+Unread text is cleared when its single consumer returns. Total text is limited
+to 1,048,576 UTF-8 bytes / 16,384 deltas, failing with `RangeError` on excess.
+Always commit/discard/abort held work. Cancellation cannot undo issued host
+effects; they retain activation ownership until they settle. Recursive turns
+across that exclusive reservation are rejected rather than deadlocking.
+An error after commit may leave partial history, and repeated commit does not retry.
+Speculation reserves exclusive ownership in FIFO order: an already-active
+ordinary turn on the same activation can delay the voice model start even after
+confirmation. All earlier ordinary turns must finish first; later turns remain
+blocked until exclusive ownership is released. Ordinary turns run concurrently
+only when no exclusive reservation intervenes. Other activations are unaffected.
+See the [transactional voice contract](https://github.com/team-telnyx/edge-compute-statefulactor/blob/compute-953/transactional-voice-turn/docs/agent-harness/transactional-voice-turn.md)
+for the full design.
 
 A harness captures its ports, model, instructions, and tool map at construction.
 Each completed model step is committed before callbacks run. This beta does not

package/dist/harness.d.ts

@@ -5,6 +5,8 @@ import { type HarnessCheckpoint, type HarnessRunLedger } from "./durable.js";
 import { type HarnessMiddleware } from "./lifecycle.js";
 import { type HarnessRuntimeConfig } from "./runtime-config.js";
 import type { HarnessStepContext } from "./steps.js";
+import { type HarnessSpeculativeTurn } from "./speculative.js";
+export { HarnessSpeculationConflictError, HarnessSpeculationUnsupportedError, type HarnessSpeculativeTurn, } from "./speculative.js";
 /** Structural subset of an AI SDK output definition used for parsed-result inference. */
 interface HarnessOutputDefinition<Parsed = unknown> {
     parseCompleteOutput(options: {
@@ -189,11 +191,12 @@ export interface HarnessTurnOptions<TOOLS extends ToolSet = ToolSet, OutputDefin
 }
 /** Portable harness constructed by {@link createHarness}. */
 export interface Harness<TOOLS extends ToolSet = ToolSet, OutputDefinition extends HarnessOutputDefinition | undefined = undefined> extends HarnessRunLedger {
+    /** Start a provisional streaming direct turn, with no writes or tools until commitment. */
+    begin(input: string, options?: HarnessTurnOptions<TOOLS, OutputDefinition>): HarnessSpeculativeTurn<HarnessTurnResult<HarnessParsedOutput<OutputDefinition>>>;
     turn(input: string, options?: HarnessTurnOptions<TOOLS, OutputDefinition>): Promise<HarnessTurnResult<HarnessParsedOutput<OutputDefinition>>>;
     /** Durable, authorization-gated approval inspection and decisions. */
     readonly approvals: HarnessApprovalLedger;
 }
 /** Construct a portable AI SDK v6 turn engine over an explicit ports object. */
 export declare function createHarness<State extends Record<string, unknown>, TOOLS extends ToolSet, OutputDefinition extends HarnessOutputDefinition | undefined = undefined>(spec: HarnessSpec<State, TOOLS, OutputDefinition>): Harness<TOOLS, OutputDefinition>;
-export {};
 //# sourceMappingURL=harness.d.ts.map

package/dist/harness.js

@@ -1,5 +1,5 @@
 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 { isToolOutputSerializationFailure } from "./steps.js";
 import { HarnessApprovalError, createHarnessApprovalExecutionLedger, createHarnessApprovalMessageJournal, } from "./approvals.js";
@@ -7,9 +7,17 @@ import { createHarnessRunExecutionLedger, HarnessApprovalPause, } from "./durabl
 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 +74,41 @@ 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 (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 +695,10 @@ 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 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 +741,24 @@ 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 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 +777,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 +825,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 +894,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 +925,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 +954,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,12 +974,20 @@ 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))
+                                            ? cloneToolOutput(toolName, await committedEffect(async () => await execute.apply(this, effectArgs)))
                                             : 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),
@@ -895,7 +996,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,7 +1038,7 @@ export function createHarness(spec) {
                         durableSteps.nextToolCallOrdinal(event.toolCall.toolName, event.toolCall.toolCallId);
                         await options.callbacks?.onToolCallStart?.(event);
                     };
-                const generation = generateText({
+                const generationOptions = {
                     model: modelForTurn,
                     tools: toolsForTurn,
                     ...(runtimeConfig.output === undefined ? {} : { output: runtimeConfig.output }),
@@ -948,9 +1049,9 @@ export function createHarness(spec) {
                     experimental_onStepStart: options.callbacks?.onStepStart,
                     experimental_onToolCallStart: onToolCallStart,
                     experimental_onToolCallFinish: options.callbacks?.onToolCallFinish,
-                    prepareStep() {
+                    prepareStep({ messages: stepMessages }) {
                         assertBoundary();
-                        return undefined;
+                        return speculation && confirmedForModel !== undefined ? { messages: confirmedMessages(stepMessages) } : undefined;
                     },
                     async stopWhen(context) {
                         assertBoundary();
@@ -961,6 +1062,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 +1144,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 +1161,38 @@ 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")
+                                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;
@@ -1089,7 +1227,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 +1242,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 +1253,22 @@ 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,
+        })), 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
@@ -1209,6 +1359,7 @@ export function createHarness(spec) {
     });
     return Object.freeze({
         turn,
+        begin,
         accept: ledger.accept,
         get: ledger.get,
         status: ledger.status,

package/dist/index.d.ts

@@ -2,6 +2,7 @@
 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 * from "./steps.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/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

package/dist/speculative.js

@@ -0,0 +1,272 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/** In-memory ownership and commitment; never opens a storage transaction. */
+export class HarnessSpeculationConflictError extends Error {
+    code = "HARNESS_SPECULATION_CONFLICT";
+    constructor() { super("Speculative turn already has a different terminal decision"); this.name = "HarnessSpeculationConflictError"; }
+}
+export class HarnessSpeculationUnsupportedError extends Error {
+    code = "HARNESS_SPECULATION_UNSUPPORTED";
+    constructor(detail) { super(`Speculation does not support ${detail}`); this.name = "HarnessSpeculationUnsupportedError"; }
+}
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
+    void promise.catch(() => { });
+    return { promise, resolve, reject };
+}
+const contexts = new AsyncLocalStorage();
+const owners = new WeakMap();
+function drain(owner) {
+    if (owner.draining)
+        return;
+    owner.draining = true;
+    try {
+        while (!owner.exclusive) {
+            const next = owner.pending.values().next().value;
+            if (!next || (next.exclusive && owner.active > 0))
+                return;
+            owner.pending.delete(next);
+            next.start();
+        }
+    }
+    finally {
+        owner.draining = false;
+    }
+}
+/** FIFO exclusive reservations; ordinary callers still run concurrently. */
+export function serializeTurn(activation, work, exclusive = true, signal, onQueuedCancel) {
+    let owner = owners.get(activation);
+    if (!owner) {
+        owner = { active: 0, exclusive: false, draining: false, pending: new Set() };
+        owners.set(activation, owner);
+    }
+    const completion = deferred();
+    const inherited = contexts.getStore() ?? [];
+    if (inherited.some((context) => context.activation === activation && context.active
+        && (exclusive || context.exclusive || [...owner.pending].some((entry) => entry.exclusive)))) {
+        completion.reject(new HarnessSpeculationUnsupportedError("recursive turns across an exclusive reservation"));
+        return completion.promise;
+    }
+    const context = { activation, exclusive, active: false };
+    const reservation = {
+        exclusive,
+        start() {
+            signal?.removeEventListener("abort", cancel);
+            context.active = true;
+            owner.active++;
+            owner.exclusive = exclusive;
+            const release = () => {
+                context.active = false;
+                owner.active--;
+                if (exclusive)
+                    owner.exclusive = false;
+                drain(owner);
+            };
+            try {
+                const result = contexts.run([...inherited, context], work);
+                void Promise.resolve(result).then((value) => { release(); completion.resolve(value); }, (error) => { release(); completion.reject(error); });
+            }
+            catch (error) {
+                release();
+                completion.reject(error);
+            }
+        },
+    };
+    const cancel = () => {
+        if (!owner.pending.delete(reservation))
+            return;
+        signal?.removeEventListener("abort", cancel);
+        // Deletion is the pending/start winner. Never run execution or acquire
+        // ownership for cancellation, nor inherit the abort dispatcher's context.
+        try {
+            if (onQueuedCancel) {
+                void contexts.run(inherited, onQueuedCancel).then(completion.resolve, completion.reject);
+            }
+            else
+                completion.reject(signal?.reason);
+        }
+        catch (error) {
+            completion.reject(error);
+        }
+        finally {
+            drain(owner);
+        }
+    };
+    owner.pending.add(reservation);
+    signal?.addEventListener("abort", cancel, { once: true });
+    if (signal?.aborted)
+        cancel();
+    // Register before invoking work, including synchronous reentry.
+    else
+        drain(owner);
+    return completion.promise;
+}
+// The AI SDK also retains stream content, even when our consumer drains it.
+// Bound total text, not just the currently unread queue. A separate chunk cap
+// bounds object overhead for small provider deltas.
+const MAX_TEXT_BYTES = 1_048_576;
+const MAX_TEXT_CHUNKS = 16_384;
+export function speculativeTurn(activation, signal, cancellation, execute) {
+    const controller = new AbortController();
+    const confirmation = deferred();
+    const stopped = deferred();
+    let decision = "held";
+    let confirmedInput;
+    let failure;
+    let failed = false;
+    let ended = false;
+    let executionClosed = false;
+    let taken = false;
+    let textBytes = 0;
+    let textChunks = 0;
+    let streamClosed = false;
+    const chunks = [];
+    const writes = new Set();
+    let changed = deferred();
+    const wake = () => { changed.resolve(); changed = deferred(); };
+    const stopWith = (error) => {
+        if (ended || controller.signal.aborted)
+            return;
+        if (decision === "held")
+            decision = "discarded";
+        failed = true;
+        failure = error;
+        chunks.length = 0;
+        confirmation.reject(error);
+        stopped.reject(error);
+        controller.abort(error);
+        wake();
+    };
+    const stop = () => stopWith(cancellation());
+    if (signal?.aborted)
+        stop();
+    else
+        signal?.addEventListener("abort", stop, { once: true });
+    const assertLive = () => {
+        if (controller.signal.aborted)
+            throw failure;
+        if (executionClosed)
+            throw new Error("Speculative execution already finished");
+    };
+    const control = {
+        signal: controller.signal,
+        assertLive,
+        fail: stopWith,
+        write(work) {
+            assertLive();
+            if (decision !== "committed")
+                throw new Error("Speculative writes require commitment");
+            const completion = deferred();
+            writes.add(completion.promise);
+            void completion.promise.then(() => { writes.delete(completion.promise); }, () => { writes.delete(completion.promise); });
+            try {
+                void work().then(completion.resolve, completion.reject);
+            }
+            catch (error) {
+                completion.reject(error);
+            }
+            return completion.promise;
+        },
+        confirmed: async () => { const input = await confirmation.promise; assertLive(); return input; },
+        text(delta) {
+            assertLive();
+            textBytes += Buffer.byteLength(delta, "utf8");
+            textChunks++;
+            if (textBytes > MAX_TEXT_BYTES || textChunks > MAX_TEXT_CHUNKS) {
+                stopWith(new RangeError("Speculative text limit exceeded"));
+                throw failure;
+            }
+            if (!delta)
+                return;
+            if (!streamClosed) {
+                chunks.push(delta);
+                wake();
+            }
+        },
+    };
+    const owned = serializeTurn(activation, async () => {
+        assertLive();
+        try {
+            return await Promise.race([execute(control).catch((error) => {
+                    stopWith(error);
+                    throw error;
+                }), stopped.promise]);
+        }
+        finally {
+            executionClosed = true;
+            // Issued host effects cannot be undone. Cancellation settles the public
+            // result promptly but cannot let a later turn overtake those effects.
+            // Recheck: an admitted callback can issue another tracked effect while
+            // an earlier batch is settling. The abort fence rejects new admissions.
+            while (writes.size)
+                await Promise.allSettled([...writes]);
+        }
+    }, true, controller.signal);
+    // Cancellation removes queued reservations and settles active callers
+    // promptly, independently of the ownership drain for issued effects.
+    const result = Promise.race([owned, stopped.promise]);
+    void result.then(() => { ended = true; signal?.removeEventListener("abort", stop); wake(); }, (error) => {
+        // A failed speculative model can never later publish its user input.
+        stopWith(error);
+        ended = true;
+        signal?.removeEventListener("abort", stop);
+        wake();
+    });
+    return Object.freeze({
+        result,
+        textStream: {
+            [Symbol.asyncIterator]() {
+                if (taken)
+                    throw new Error("Speculative text stream already has a consumer");
+                taken = true;
+                const iterator = (async function* () {
+                    while (true) {
+                        if (failed)
+                            throw failure;
+                        if (streamClosed)
+                            return;
+                        const chunk = chunks.shift();
+                        if (chunk !== undefined)
+                            yield chunk;
+                        else if (ended)
+                            return;
+                        else
+                            await changed.promise;
+                    }
+                })();
+                return {
+                    next: () => iterator.next(),
+                    return: async () => {
+                        streamClosed = true;
+                        chunks.length = 0;
+                        if (decision === "held")
+                            stop();
+                        wake();
+                        return iterator.return();
+                    },
+                };
+            },
+        },
+        commit(input) {
+            if (decision === "discarded" || (decision === "committed" && input !== confirmedInput)) {
+                const conflict = Promise.reject(new HarnessSpeculationConflictError());
+                void conflict.catch(() => { });
+                return conflict;
+            }
+            if (decision === "held") {
+                decision = "committed";
+                confirmedInput = input;
+                confirmation.resolve(input);
+            }
+            return result;
+        },
+        discard() {
+            if (decision === "committed")
+                return false;
+            stop();
+            return true;
+        },
+    });
+}
+//# sourceMappingURL=speculative.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telnyx/agent-harness",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.1",
   "description": "Telnyx Agent Harness beta: portable ports, bounded turns, and Node test-host adapter.",
   "type": "module",
   "license": "UNLICENSED",