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

package/README.md

@@ -7,10 +7,11 @@ 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.2` 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
+registry-installed `@telnyx/edge-runtime@^0.16.0` is required — one copy,
+shared with whatever extends `Agent`, or the host key will not match: the runtime
 adapter uses its `./internal` `getAgentHarnessHost` and
 `getAgentHarnessAuthorizationProvider` seams. Source validation is not evidence
 that the beta is published or live; see `docs/agent-harness/beta-release.md` for
@@ -19,7 +20,7 @@ fresh preflight, publication, and rollback gates.
 ## Installation
 
 ```bash
-npm install @telnyx/agent-harness@beta @telnyx/edge-runtime@^0.15.2
+npm install @telnyx/agent-harness@beta @telnyx/edge-runtime@^0.16.0
 ```
 
 The package requires Node 22.13 or newer.
@@ -61,6 +62,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
@@ -68,6 +119,16 @@ claim exactly-once external effects or crash recovery; production durability,
 concurrency ownership, and provider configuration remain responsibilities of
 the selected host.
 
+## Bounded host diagnostics
+
+See [bounded host diagnostics](../../docs/agent-harness/diagnostics.md) for
+filtered waiting-run discovery, known-run `get`/`status`, known-approval-ID
+inspection, and active schedule listing. These are trusted in-process host
+capabilities, not authenticated remote endpoints. The guide explains inspection's
+authorization/audit/expiry boundaries and the missing pending-approval discovery,
+run pagination, host step inventory, and schedule-occurrence APIs. Run discovery
+alone does not supply an approval ID.
+
 ## Scheduling dispatch and recovery lifecycle
 
 `createHarnessWithScheduling` constructs a durable harness with bounded
@@ -171,6 +232,47 @@ accepted, and records the run's journal sequence after completion. This
 makes the occurrence → run → journal relationship recoverable without
 inferring from actor-global history.
 
+## Virtual workspace skill activation
+
+`createVirtualWorkspace(ports)` stores inert skill documents at
+`skills/<name>/SKILL.md`. Use the exact `name` returned by
+`workspace.discoverSkills()` when calling `workspace.activateSkill(name)` or
+the `activate_skill({ name })` tool from `createVirtualWorkspaceTools(workspace)`.
+Names are case-sensitive: there is no trimming, aliasing, fuzzy matching, or
+conversion from a path or document title. For example, the registered name for
+`skills/Guide-v1/SKILL.md` is `Guide-v1`, not `guide-v1`, `Guide`, or the file
+path. Discovery can return a bounded prefix with `truncated: true`; absence
+from a truncated catalog does not prove the document does not exist.
+
+Activation returns `{ name, path, origin: "activated-skill", content }` as prompt
+data; it does not execute the document. Both the raw UTF-8 content and the full
+JSON result including metadata must fit `maxOutputBytes`. Content is not
+silently truncated during activation.
+
+Activation validation/lookup/bound rejections use the root-exported
+`HarnessSkillActivationError`, with a fixed `code` and fixed message:
+
+| Code | Meaning |
+| --- | --- |
+| `HARNESS_SKILL_INVALID_NAME` | Empty, non-string, slash, backslash, or NUL-containing name. |
+| `HARNESS_SKILL_NOT_FOUND` | No document exists at the exact registered path. |
+| `HARNESS_SKILL_CONTENT_BOUND` | Raw UTF-8 content exceeds `maxOutputBytes`. |
+| `HARNESS_SKILL_OUTPUT_BOUND` | Full serialized activation result exceeds `maxOutputBytes`. |
+
+These errors do not include the requested name, arguments, prompt, content, or
+raw cause. Input-schema rejection before tool execution and unrelated storage
+errors are not converted into activation errors. Direct callers can inspect
+`error instanceof HarnessSkillActivationError` and `error.code`; existing tool
+middleware can catch the same local error from `await next()` and rethrow it.
+Do not log arbitrary errors or tool arguments as part of this diagnostic path.
+
+These are **local diagnostics, not persisted run causes**. A durable tool that
+throws after its effect-start fence still produces
+`outcome_unknown / HARNESS_OUTCOME_UNKNOWN`. The typed error does not make that
+run safe to retry: duplicate dispatch, `run`, and recovery do not re-execute it.
+This does not recover a historical exception or establish why an earlier run
+failed; investigate already-retained evidence without blindly retrying effects.
+
 ## Validation
 
 Package development and release preparation are validated with the repository's

package/dist/approvals.d.ts

@@ -41,7 +41,28 @@ export interface HarnessApprovalAudit {
     readonly outcome: string;
     readonly at: number;
 }
+export interface HarnessPendingApprovalSummary {
+    readonly id: string;
+    readonly runId: string;
+    readonly toolName: string;
+    readonly status: "pending";
+    readonly expiresAt: number;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+export interface HarnessPendingApprovalListOptions {
+    /** Safe integer from 1 through 100; defaults to 50. */
+    readonly limit?: number;
+    /** Opaque actor/organization/caller/run-bound keyset continuation. */
+    readonly cursor?: string;
+}
+export interface HarnessPendingApprovalPage {
+    readonly items: readonly HarnessPendingApprovalSummary[];
+    readonly nextCursor?: string;
+}
 export interface HarnessApprovalLedger {
+    /** Enumerate minimal unexpired pending summaries with explicit host collection authority. */
+    listPending(runId: string, options?: HarnessPendingApprovalListOptions): Promise<HarnessPendingApprovalPage>;
     inspect(id: string): Promise<HarnessApproval>;
     grant(id: string): Promise<HarnessApproval>;
     deny(id: string): Promise<HarnessApproval>;

package/dist/approvals.js

@@ -1,4 +1,4 @@
-import { ensureHarnessDurabilitySchema } from "./durable.js";
+import { ensureHarnessDurabilitySchema, HARNESS_DURABILITY_SCHEMA_VERSION } from "./durable.js";
 export const HARNESS_APPROVAL_STATUSES = ["pending", "granted", "denied", "expired", "consumed"];
 export class HarnessAuthorizationError extends Error {
     code;
@@ -208,9 +208,27 @@ async function authorize(ports, action, row, persistedSubject = false) {
         throw new HarnessAuthorizationError("forbidden");
     throw new HarnessAuthorizationError("policy_unavailable");
 }
+function collectionIdentity(ports) {
+    let identity;
+    try {
+        identity = ports.authorization?.identity();
+    }
+    catch {
+        throw new HarnessAuthorizationError("identity_unavailable");
+    }
+    if (identity === undefined)
+        throw new HarnessAuthorizationError("identity_unavailable");
+    if (identity === null || typeof identity.serviceAccountId !== "string" || typeof identity.organizationId !== "string"
+        || !identity.serviceAccountId.trim() || !identity.organizationId.trim()
+        || Buffer.byteLength(identity.serviceAccountId, "utf8") > MAX_ID_BYTES
+        || Buffer.byteLength(identity.organizationId, "utf8") > MAX_ID_BYTES)
+        throw new HarnessAuthorizationError("unauthenticated");
+    return Object.freeze({ serviceAccountId: identity.serviceAccountId, organizationId: identity.organizationId });
+}
 export function createHarnessApprovalLedger(ports) {
     const execution = createHarnessApprovalExecutionLedger(ports);
     return Object.freeze({
+        listPending: execution.listPending,
         inspect: execution.inspect,
         grant: execution.grant,
         deny: execution.deny,
@@ -277,6 +295,80 @@ export function createHarnessApprovalExecutionLedger(ports) {
         return new HarnessApprovalError(status === requested ? "replayed" : "conflicting");
     };
     return Object.freeze({
+        async listPending(runId, options = {}) {
+            if (typeof runId !== "string")
+                throw new Error("run id must be a string");
+            nonblank(runId, "run id");
+            if (options === null || typeof options !== "object" || Array.isArray(options)
+                || Object.keys(options).some((key) => key !== "limit" && key !== "cursor"))
+                throw new Error("invalid pending approval options");
+            const limit = options.limit === undefined ? 50 : options.limit;
+            if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+                throw new Error("pending approval limit must be an integer from 1 through 100");
+            const identity = collectionIdentity(ports);
+            const scope = Buffer.from(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify([ports.identity.id, identity.organizationId, identity.serviceAccountId, runId])))).toString("hex");
+            let afterAt = -1;
+            let afterId = "";
+            if (options.cursor !== undefined) {
+                try {
+                    if (typeof options.cursor !== "string" || options.cursor.length > 8192 || !/^[A-Za-z0-9_-]+$/.test(options.cursor))
+                        throw new Error();
+                    const decoded = Buffer.from(options.cursor, "base64url");
+                    if (decoded.toString("base64url") !== options.cursor)
+                        throw new Error();
+                    const value = JSON.parse(decoded.toString("utf8"));
+                    if (!Array.isArray(value) || value.length !== 4 || value[0] !== 1 || value[1] !== scope
+                        || !Number.isSafeInteger(value[2]) || value[2] < 0 || typeof value[3] !== "string")
+                        throw new Error();
+                    nonblank(value[3], "cursor id");
+                    afterAt = value[2];
+                    afterId = value[3];
+                }
+                catch {
+                    throw new Error("invalid pending approval cursor");
+                }
+            }
+            let decision;
+            try {
+                decision = await ports.authorization?.authorizePendingApprovalSummaries?.({
+                    identity, actorId: ports.identity.id, action: "agent_harness.approvals.list_pending",
+                    resource: `agent_harness/runs/${encodeURIComponent(runId)}/pending_approval_summaries`, runId,
+                });
+            }
+            catch {
+                throw new HarnessAuthorizationError("policy_unavailable");
+            }
+            if (decision?.kind === "deny")
+                throw new HarnessAuthorizationError("forbidden");
+            if (decision?.kind !== "allow")
+                throw new HarnessAuthorizationError("policy_unavailable");
+            const live = collectionIdentity(ports);
+            if (live.organizationId !== identity.organizationId || live.serviceAccountId !== identity.serviceAccountId) {
+                throw new HarnessAuthorizationError("unauthenticated");
+            }
+            // Discovery is SELECT-only: never initialize/migrate a database on a read.
+            const schemaExists = ports.sql.exec("SELECT name FROM sqlite_master WHERE type = 'table' AND name = '__telnyx_agent_harness_schema'").toArray().length > 0;
+            if (!schemaExists)
+                return Object.freeze({ items: Object.freeze([]) });
+            const versions = ports.sql.exec("SELECT version FROM __telnyx_agent_harness_schema LIMIT 2").toArray();
+            if (versions.length !== 1 || versions[0]?.version !== HARNESS_DURABILITY_SCHEMA_VERSION)
+                throw new Error("pending approval schema is unsupported");
+            const rows = ports.sql.exec("SELECT id,run_id,tool_name,status,expires_at,created_at,updated_at FROM __telnyx_agent_harness_approvals WHERE run_id = ? AND organization_id = ? AND status = 'pending' AND expires_at > ? AND (created_at > ? OR (created_at = ? AND id > ?)) ORDER BY created_at,id LIMIT ?", runId, identity.organizationId, ports.clock.now(), afterAt, afterAt, afterId, limit + 1).toArray();
+            for (const row of rows) {
+                if ([row.id, row.run_id, row.tool_name].some((value) => typeof value !== "string" || !value.trim() || Buffer.byteLength(value, "utf8") > MAX_ID_BYTES)
+                    || [row.created_at, row.updated_at, row.expires_at].some((value) => !Number.isSafeInteger(value) || value < 0)) {
+                    throw new Error("invalid pending approval summary");
+                }
+            }
+            const selected = rows.slice(0, limit);
+            const last = selected.at(-1);
+            return Object.freeze({ items: Object.freeze(selected.map((row) => Object.freeze({
+                    id: row.id, runId: row.run_id, toolName: row.tool_name, status: "pending",
+                    expiresAt: row.expires_at, createdAt: row.created_at, updatedAt: row.updated_at,
+                }))), ...(rows.length > limit && last !== undefined ? {
+                    nextCursor: Buffer.from(JSON.stringify([1, scope, last.created_at, last.id])).toString("base64url"),
+                } : {}) });
+        },
         async request(request) {
             return requestApproval(request);
         },

package/dist/diagnostics.d.ts

@@ -0,0 +1,33 @@
+import { type HarnessRunStatus } from "./durable.js";
+import type { AgentHarnessPorts } from "./ports.js";
+export interface HarnessRunInspectionOptions {
+    /** Step-page size, default 25, maximum 50. */
+    readonly limit?: number;
+    /** Opaque actor/run-scoped continuation; not authority or an atomic snapshot. */
+    readonly cursor?: string;
+}
+/** Bounded persisted metadata only; identifiers can still be sensitive. */
+export interface HarnessRunInspection {
+    readonly run: Readonly<{
+        id: string;
+        status: HarnessRunStatus;
+        failureCode?: string;
+    }>;
+    readonly journalSeq?: number;
+    readonly scheduleOccurrences: readonly Readonly<{
+        scheduleId: string;
+        scheduledFor: number;
+        journalSeq?: number;
+    }>[];
+    readonly steps: readonly Readonly<{
+        name: string;
+        version: string;
+        phase: "prepared" | "effect_started" | "completed";
+        journalSeq: number;
+        outputFailure?: "tool_output_serialization_failure";
+    }>[];
+    readonly nextCursor?: string;
+}
+/** Private implementation of the trusted host read; never initializes storage. */
+export declare function inspectHarnessRun(ports: AgentHarnessPorts, runId: string, options?: HarnessRunInspectionOptions): Promise<HarnessRunInspection | undefined>;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.js

@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+import { HARNESS_DURABILITY_SCHEMA_VERSION, HARNESS_RUN_STATUSES } from "./durable.js";
+const failures = new Set(["HARNESS_CANCELLED", "HARNESS_OBSERVER_ERROR", "HARNESS_PROVIDER_ERROR", "HARNESS_STEP_LIMIT", "HARNESS_TOOL_OUTPUT_ERROR", "HARNESS_APPROVAL_INVALID", "HARNESS_APPROVAL_EXPIRED", "HARNESS_AUTHORIZATION_REVOKED", "HARNESS_RUN_FAILED", "HARNESS_OUTCOME_UNKNOWN"]);
+function text(value) {
+    if (typeof value !== "string" || !value.trim() || Buffer.byteLength(value, "utf8") > 512)
+        throw new Error("Invalid run inspection data");
+}
+function sequence(value) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new Error("Invalid run inspection data");
+}
+/** Private implementation of the trusted host read; never initializes storage. */
+export async function inspectHarnessRun(ports, runId, options = {}) {
+    let limit;
+    let after = 0;
+    let afterName = "";
+    let scope;
+    try {
+        text(runId);
+        text(ports.identity.id);
+        scope = createHash("sha256").update(JSON.stringify(["run-inspection-v1", ports.identity.id, runId])).digest("hex");
+        if (options === null || typeof options !== "object" || Object.getPrototypeOf(options) !== Object.prototype)
+            throw new Error();
+        for (const key of Reflect.ownKeys(options)) {
+            if (key !== "limit" && key !== "cursor")
+                throw new Error();
+            if (!("value" in Object.getOwnPropertyDescriptor(options, key)))
+                throw new Error();
+        }
+        limit = options.limit === undefined ? 25 : options.limit;
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 50)
+            throw new Error();
+        if (options.cursor !== undefined) {
+            if (typeof options.cursor !== "string" || options.cursor.length > 8192 || !/^[A-Za-z0-9_-]+$/.test(options.cursor))
+                throw new Error();
+            const decoded = Buffer.from(options.cursor, "base64url");
+            if (decoded.toString("base64url") !== options.cursor)
+                throw new Error();
+            const tuple = JSON.parse(decoded.toString("utf8"));
+            if (!Array.isArray(tuple) || tuple.length !== 4 || tuple[0] !== 1 || tuple[1] !== scope)
+                throw new Error();
+            sequence(tuple[2]);
+            text(tuple[3]);
+            after = tuple[2];
+            afterName = tuple[3];
+            if (Buffer.from(JSON.stringify(tuple)).toString("base64url") !== options.cursor)
+                throw new Error();
+        }
+    }
+    catch {
+        throw new Error("Invalid run inspection options");
+    }
+    try {
+        const present = ports.sql.exec("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = '__telnyx_agent_harness_schema'").toArray();
+        if (present.length === 0)
+            return undefined;
+        const versions = ports.sql.exec("SELECT version FROM __telnyx_agent_harness_schema LIMIT 2").toArray();
+        if (versions.length !== 1 || versions[0]?.version !== HARNESS_DURABILITY_SCHEMA_VERSION)
+            throw new Error();
+        const row = ports.sql.exec("SELECT id,status,failure_code FROM __telnyx_agent_harness_runs WHERE id = ?", runId).toArray()[0];
+        if (row === undefined)
+            return undefined;
+        text(row.id);
+        if (!HARNESS_RUN_STATUSES.includes(row.status) || (row.failure_code !== null && !failures.has(row.failure_code)))
+            throw new Error();
+        const rows = ports.sql.exec("SELECT name,version,status,journal_seq,output_failure FROM __telnyx_agent_harness_steps WHERE run_id = ? AND (journal_seq > ? OR (journal_seq = ? AND name > ?)) ORDER BY journal_seq,name LIMIT ?", runId, after, after, afterName, limit + 1).toArray();
+        const steps = rows.slice(0, limit).map(step => {
+            text(step.name);
+            text(step.version);
+            sequence(step.journal_seq);
+            if (!["prepared", "effect_started", "completed"].includes(step.status) || (step.output_failure !== null && step.output_failure !== "tool_output_serialization_failure"))
+                throw new Error();
+            return Object.freeze({ name: step.name, version: step.version, phase: step.status, journalSeq: step.journal_seq, ...(step.output_failure === null ? {} : { outputFailure: "tool_output_serialization_failure" }) });
+        });
+        const last = steps.at(-1);
+        const journal = ports.sql.exec("SELECT journal_seq FROM __telnyx_agent_harness_run_journal WHERE run_id = ?", runId).toArray()[0];
+        if (journal !== undefined)
+            sequence(journal.journal_seq);
+        const hasOccurrences = ports.sql.exec("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = '__telnyx_agent_harness_schedule_occurrences'").toArray().length > 0;
+        const occurrences = hasOccurrences ? ports.sql.exec("SELECT schedule_id,scheduled_for,journal_seq FROM __telnyx_agent_harness_schedule_occurrences WHERE run_id = ? ORDER BY scheduled_for,schedule_id LIMIT 33", runId).toArray() : [];
+        if (occurrences.length > 32)
+            throw new Error();
+        const scheduleOccurrences = Object.freeze(occurrences.map(occurrence => {
+            text(occurrence.schedule_id);
+            sequence(occurrence.scheduled_for);
+            if (occurrence.journal_seq !== null)
+                sequence(occurrence.journal_seq);
+            return Object.freeze({ scheduleId: occurrence.schedule_id, scheduledFor: occurrence.scheduled_for, ...(occurrence.journal_seq === null ? {} : { journalSeq: occurrence.journal_seq }) });
+        }));
+        const result = Object.freeze({
+            run: Object.freeze({ id: row.id, status: row.status, ...(row.failure_code === null ? {} : { failureCode: row.failure_code }) }),
+            ...(journal === undefined ? {} : { journalSeq: journal.journal_seq }),
+            scheduleOccurrences,
+            steps: Object.freeze(steps),
+            ...(rows.length <= limit || last === undefined ? {} : {
+                nextCursor: Buffer.from(JSON.stringify([1, scope, last.journalSeq, last.name])).toString("base64url"),
+            }),
+        });
+        if (Buffer.byteLength(JSON.stringify(result), "utf8") > 262144)
+            throw new Error();
+        return result;
+    }
+    catch {
+        throw new Error("Run inspection unavailable: unsupported schema or invalid stored data");
+    }
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/durable.d.ts

@@ -74,6 +74,7 @@ export interface HarnessRunLedgerOptions {
     /** Approval-capable harnesses bind admission to a host-attested subject. */
     readonly requireApprovalIdentity?: boolean;
 }
+export declare const HARNESS_DURABILITY_SCHEMA_VERSION = 8;
 export declare function ensureHarnessDurabilitySchema(ports: AgentHarnessPorts): void;
 export declare function createHarnessRunLedger(ports: AgentHarnessPorts, execute: (input: string, signal: AbortSignal, steps: HarnessStepContext) => Promise<unknown>, options?: HarnessRunLedgerOptions): HarnessRunLedger;
 export declare function createHarnessRunExecutionLedger(ports: AgentHarnessPorts, execute: (input: string, signal: AbortSignal, steps: HarnessStepContext) => Promise<unknown>, options?: HarnessRunLedgerOptions): HarnessRunExecutionLedger;

package/dist/durable.js

@@ -39,7 +39,8 @@ function scheduleRollbackStep(error) {
 const APPROVAL_SCHEMA_VERSION = 6;
 // v7 records the run-owned sequence for the admitted input. v8 adds an
 // out-of-band durable tool-output failure marker.
-const SCHEMA_VERSION = 8;
+export const HARNESS_DURABILITY_SCHEMA_VERSION = 8;
+const SCHEMA_VERSION = HARNESS_DURABILITY_SCHEMA_VERSION;
 const MAX_INPUT_BYTES = 64 * 1024;
 const MAX_KEY_BYTES = 512;
 const TASK_METHOD = "__telnyx_agent_harness_run";

package/dist/harness.d.ts

@@ -1,10 +1,14 @@
 import { type FinishReason, type GenerateTextOnFinishCallback, type GenerateTextOnStartCallback, type GenerateTextOnStepFinishCallback, type GenerateTextOnStepStartCallback, type GenerateTextOnToolCallFinishCallback, type GenerateTextOnToolCallStartCallback, type LanguageModel, type ToolSet } from "ai";
+import { voiceTraceContext, type VoiceTraceScope, type VoiceTraceContext } from "@telnyx/edge-runtime/internal";
 import type { AgentHarnessPorts } from "./ports.js";
+import { type HarnessRunInspection, type HarnessRunInspectionOptions } from "./diagnostics.js";
 import { type HarnessApprovalLedger } from "./approvals.js";
 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: {
@@ -66,6 +70,8 @@ export interface HarnessSpec<State extends Record<string, unknown>, TOOLS extend
     ports: AgentHarnessPorts<State>;
     /** AI SDK v6 language model. */
     model: LanguageModel;
+    /** Construction-only, in-memory metadata diagnostics. Never selected from runtime state. */
+    diagnostics?: VoiceTraceScope;
     /** Host-owned models selectable only by a named runtime configuration key. */
     models?: Readonly<Record<string, LanguageModel>>;
     /** The one explicit, flat tool set available to the model. */
@@ -167,6 +173,7 @@ export interface HarnessStep {
 export interface HarnessTurnOptions<TOOLS extends ToolSet = ToolSet, OutputDefinition extends HarnessOutputDefinition | undefined = undefined> {
     /** Caller-owned cancellation signal passed to AI SDK without transport coupling. */
     signal?: AbortSignal;
+    [voiceTraceContext]?: VoiceTraceContext;
     /** Durable context supplied only by the harness run ledger. */
     steps?: HarnessStepContext;
     /** Runs after the completed step has been durably journaled. */
@@ -189,11 +196,14 @@ 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 {
+    /** SELECT-only persisted phases for a known run; trusted host capability, not caller authorization. */
+    inspectRun(runId: string, options?: HarnessRunInspectionOptions): Promise<HarnessRunInspection | undefined>;
+    /** 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