@telnyx/agent-harness 0.1.0-beta.1 → 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.1` 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.
@@ -118,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
@@ -221,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,5 +1,7 @@
 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";
@@ -68,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. */
@@ -169,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. */
@@ -191,6 +196,8 @@ 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>>>;

package/dist/harness.js

@@ -1,7 +1,10 @@
 import { GatewayError } from "@ai-sdk/gateway";
 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";
@@ -95,6 +98,10 @@ function captureSpeculativeOptions(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)) {
@@ -696,6 +703,7 @@ 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 appendMessagePort = messagePort.append.bind(messagePort);
     const appendMessagesPort = messagePort.appendMany.bind(messagePort);
@@ -742,6 +750,7 @@ export function createHarness(spec) {
     let runtimeConfigReadSequence = 0;
     let lastPublishedRuntimeConfigReadSequence = 0;
     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);
@@ -987,8 +996,8 @@ export function createHarness(spec) {
                                         assertBoundary();
                                         coreStarted = true;
                                         const result = options.steps === undefined
-                                            ? 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)), {
+                                            ? 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],
@@ -1039,7 +1048,7 @@ export function createHarness(spec) {
                         await options.callbacks?.onToolCallStart?.(event);
                     };
                 const generationOptions = {
-                    model: modelForTurn,
+                    model: traceModel(modelForTurn, trace),
                     tools: toolsForTurn,
                     ...(runtimeConfig.output === undefined ? {} : { output: runtimeConfig.output }),
                     abortSignal: options.signal,
@@ -1051,7 +1060,13 @@ export function createHarness(spec) {
                     experimental_onToolCallFinish: options.callbacks?.onToolCallFinish,
                     prepareStep({ messages: stepMessages }) {
                         assertBoundary();
-                        return speculation && confirmedForModel !== undefined ? { messages: confirmedMessages(stepMessages) } : 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();
@@ -1177,8 +1192,10 @@ export function createHarness(spec) {
                         onChunk: ({ chunk }) => {
                             assertBoundary();
                             const part = objectRecord(chunk);
-                            if (part?.type === "text-delta" && typeof part.text === "string")
+                            if (part?.type === "text-delta" && typeof part.text === "string") {
+                                traceStage(trace, "text_forwarded");
                                 speculation.text(part.text);
+                            }
                         },
                     });
                     await streamed.consumeStream({ onError: onStreamError });
@@ -1213,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,
@@ -1267,6 +1286,7 @@ export function createHarness(spec) {
             signal: control.signal,
             onStepCommitted: capturedOptions.onStepCommitted,
             onOutput: capturedOptions.onOutput,
+            [voiceTraceContext]: capturedOptions[voiceTraceContext],
         })), control));
     };
     const ledger = createHarnessRunExecutionLedger(spec.ports, async (input, signal, steps) => {
@@ -1318,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;
@@ -1362,6 +1383,7 @@ export function createHarness(spec) {
         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

@@ -4,8 +4,9 @@ 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/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/voice-trace.d.ts

@@ -0,0 +1,6 @@
+import type { LanguageModel } from "ai";
+import { type VoiceTraceContext } from "@telnyx/edge-runtime/internal";
+export declare function traceToolExecution(context: VoiceTraceContext | undefined, handoff: unknown): void;
+/** Observes the selected host object; never resolves or replaces a model. */
+export declare function traceModel(model: LanguageModel, context: VoiceTraceContext | undefined, handoff?: object): LanguageModel;
+//# sourceMappingURL=voice-trace.d.ts.map

package/dist/voice-trace.js

@@ -0,0 +1,160 @@
+import { traceExecution, traceGenerated, traceActive, traceGap, traceRequest, traceRequestEnd, traceProviderFields, traceNormalized, } from "@telnyx/edge-runtime/internal";
+/** Data-only projection: never execute provider-owned diagnostic accessors. */
+function ownData(value, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor && !("value" in descriptor))
+        throw new Error();
+    return descriptor?.value;
+}
+function replaceStream(result, stream, fault) {
+    try {
+        const descriptors = Object.getOwnPropertyDescriptors(result);
+        descriptors.stream = { ...descriptors.stream, value: stream };
+        delete descriptors.stream.get;
+        delete descriptors.stream.set;
+        return Object.create(Object.getPrototypeOf(result), descriptors);
+    }
+    catch {
+        fault();
+        // Never return the original stream: its raw chunks were requested by us.
+        return new Proxy({}, { get(_target, key) { return key === "stream" ? stream : Reflect.get(result, key, result); } });
+    }
+}
+const stepRequests = new WeakMap();
+export function traceToolExecution(context, handoff) {
+    const step = handoff && typeof handoff === "object" ? stepRequests.get(handoff) : undefined;
+    traceExecution(context, step && !step.ambiguous ? step.request : undefined);
+}
+function requestStarted(handoff, request) {
+    if (!handoff)
+        return;
+    const previous = stepRequests.get(handoff);
+    stepRequests.set(handoff, { request, active: (previous?.active ?? 0) + 1, ambiguous: previous?.ambiguous === true || (previous?.active ?? 0) > 0 });
+}
+function requestEnded(handoff) {
+    const step = handoff && stepRequests.get(handoff);
+    if (step)
+        step.active--;
+}
+/** Observes the selected host object; never resolves or replaces a model. */
+export function traceModel(model, context, handoff) {
+    if (!traceActive(context))
+        return model;
+    if (typeof model === "string" || model.specificationVersion !== "v3") {
+        traceGap(context, "unsupported");
+        return model;
+    }
+    // A separate extensible facade avoids fixed-own-method Proxy invariants.
+    return new Proxy({}, {
+        get(_facade, key) {
+            const target = model;
+            if (key === "doGenerate")
+                return async (params) => {
+                    if (!traceActive(context))
+                        return target.doGenerate.call(target, params);
+                    const request = traceRequest(context, "generate");
+                    requestStarted(handoff, request);
+                    try {
+                        const result = await target.doGenerate.call(target, params);
+                        traceGenerated(context, request, result);
+                        traceRequestEnd(context, request, "generate");
+                        return result;
+                    }
+                    catch (error) {
+                        traceRequestEnd(context, request, "generate", true);
+                        throw error;
+                    }
+                    finally {
+                        requestEnded(handoff);
+                    }
+                };
+            if (key === "doStream")
+                return async (params) => {
+                    if (!traceActive(context))
+                        return target.doStream.call(target, params);
+                    // Preserve pre-existing caller raw semantics without interpreting ownership.
+                    if (params.includeRawChunks === true) {
+                        traceGap(context, "unsupported");
+                        return target.doStream.call(target, params);
+                    }
+                    const request = traceRequest(context, "stream");
+                    requestStarted(handoff, request);
+                    try {
+                        const result = await target.doStream.call(target, { ...params, includeRawChunks: true });
+                        let rawSeen = false;
+                        const reader = result.stream.getReader();
+                        let ended = false;
+                        const end = (reason) => {
+                            if (ended)
+                                return;
+                            ended = true;
+                            requestEnded(handoff);
+                            if (reason)
+                                traceGap(context, reason);
+                            else if (!rawSeen)
+                                traceGap(context, "missing_raw");
+                            traceRequestEnd(context, request, "stream", reason !== undefined);
+                        };
+                        const stream = new ReadableStream({
+                            async pull(controller) {
+                                try {
+                                    // Raw-only reads satisfy this same consumer demand; never drain ahead.
+                                    while (!ended) {
+                                        const next = await reader.read();
+                                        if (ended)
+                                            return;
+                                        if (next.done) {
+                                            end();
+                                            reader.releaseLock();
+                                            controller.close();
+                                            return;
+                                        }
+                                        const part = next.value;
+                                        let type;
+                                        try {
+                                            type = ownData(part, "type");
+                                            if (type === "raw") {
+                                                rawSeen = true;
+                                                traceProviderFields(context, request, ownData(part, "rawValue"), "delta");
+                                                continue;
+                                            }
+                                        }
+                                        catch {
+                                            traceGap(context, "projection_failure");
+                                            continue;
+                                        }
+                                        traceNormalized(context, request, type);
+                                        controller.enqueue(part);
+                                        return;
+                                    }
+                                }
+                                catch (error) {
+                                    end("source_failure");
+                                    reader.releaseLock();
+                                    controller.error(error);
+                                }
+                            },
+                            async cancel(reason) {
+                                end("cancelled");
+                                try {
+                                    await reader.cancel(reason);
+                                }
+                                finally {
+                                    reader.releaseLock();
+                                }
+                            },
+                        }, { highWaterMark: 0 });
+                        return replaceStream(result, stream, () => traceGap(context, "projection_failure"));
+                    }
+                    catch (error) {
+                        requestEnded(handoff);
+                        traceGap(context, "source_failure");
+                        traceRequestEnd(context, request, "stream", true);
+                        throw error;
+                    }
+                };
+            return Reflect.get(target, key, target);
+        },
+    });
+}
+//# sourceMappingURL=voice-trace.js.map

package/dist/workspace.d.ts

@@ -1,5 +1,17 @@
 import type { AgentHarnessPorts } from "./ports.js";
 declare const TOOL_WORKSPACE_CAPABILITY: unique symbol;
+declare const SKILL_ACTIVATION_MESSAGES: Readonly<{
+    HARNESS_SKILL_INVALID_NAME: "skill name is invalid";
+    HARNESS_SKILL_NOT_FOUND: "unknown skill";
+    HARNESS_SKILL_CONTENT_BOUND: "skill content exceeds configured bound";
+    HARNESS_SKILL_OUTPUT_BOUND: "workspace output exceeds configured bound";
+}>;
+export type HarnessSkillActivationErrorCode = keyof typeof SKILL_ACTIVATION_MESSAGES;
+/** A fixed-code activation rejection with no caller input or skill content. */
+export declare class HarnessSkillActivationError extends Error {
+    readonly code: HarnessSkillActivationErrorCode;
+    constructor(code: HarnessSkillActivationErrorCode);
+}
 export interface VirtualWorkspaceLimits {
     readonly maxFileBytes?: number;
     readonly maxWorkspaceBytes?: number;
@@ -74,6 +86,7 @@ export interface VirtualWorkspace {
         limit?: number;
     }>): Promise<readonly WorkspaceJournalEntry[]>;
     discoverSkills(): Promise<WorkspaceSkillCatalog>;
+    /** Load inert prompt data using an exact, case-sensitive name from discoverSkills(). */
     activateSkill(name: string): Promise<ActivatedWorkspaceSkill>;
     assemblePrompt(base: string, skills: readonly string[]): Promise<Readonly<{
         text: string;

package/dist/workspace.js

@@ -9,6 +9,21 @@ const MAX_PATH_BYTES = 128;
 const SKILL_PATH = /^skills\/([^/]+)\/SKILL\.md$/;
 const TOOL_MUTATION_RESULT = Symbol("tool-mutation-result");
 const TOOL_WORKSPACE_CAPABILITY = Symbol("tool-workspace-capability");
+const SKILL_ACTIVATION_MESSAGES = Object.freeze({
+    HARNESS_SKILL_INVALID_NAME: "skill name is invalid",
+    HARNESS_SKILL_NOT_FOUND: "unknown skill",
+    HARNESS_SKILL_CONTENT_BOUND: "skill content exceeds configured bound",
+    HARNESS_SKILL_OUTPUT_BOUND: "workspace output exceeds configured bound",
+});
+/** A fixed-code activation rejection with no caller input or skill content. */
+export class HarnessSkillActivationError extends Error {
+    code;
+    constructor(code) {
+        super(SKILL_ACTIVATION_MESSAGES[code]);
+        this.code = code;
+        this.name = "HarnessSkillActivationError";
+    }
+}
 const workspaceOutputBounds = new WeakMap();
 function one(rows) {
     return rows[0];
@@ -311,13 +326,18 @@ export function createVirtualWorkspace(ports, limits = {}) {
         },
         async activateSkill(name) {
             if (typeof name !== "string" || !name || name.includes("/") || name.includes("\\") || name.includes("\0"))
-                throw new Error("skill name is invalid");
+                throw new HarnessSkillActivationError("HARNESS_SKILL_INVALID_NAME");
             const path = `skills/${name}/SKILL.md`;
             const row = get(path);
             if (row === undefined)
-                throw new Error("unknown skill");
-            boundedText(row.content, maxOutputBytes, "skill content");
-            return boundedResult(Object.freeze({ name, path, origin: "activated-skill", content: row.content }), maxOutputBytes);
+                throw new HarnessSkillActivationError("HARNESS_SKILL_NOT_FOUND");
+            requireText(row.content, "skill content");
+            if (Buffer.byteLength(row.content, "utf8") > maxOutputBytes)
+                throw new HarnessSkillActivationError("HARNESS_SKILL_CONTENT_BOUND");
+            const result = Object.freeze({ name, path, origin: "activated-skill", content: row.content });
+            if (Buffer.byteLength(JSON.stringify(result), "utf8") > maxOutputBytes)
+                throw new HarnessSkillActivationError("HARNESS_SKILL_OUTPUT_BOUND");
+            return result;
         },
         async assemblePrompt(base, names) {
             requireText(base, "application prompt");
@@ -395,7 +415,7 @@ export function createVirtualWorkspaceTools(workspace) {
             execute: async ({ needle }) => boundedToolResult(workspace, Object.freeze({ origin: "workspace", ...(await workspace.grep(needle)) })),
         }),
         activate_skill: tool({
-            description: "Explicitly load one inert SKILL.md document as prompt data with its provenance.",
+            description: "Explicitly load one inert SKILL.md document as prompt data with its provenance. Use the exact registered skill name, not a path or display title.",
             inputSchema: z.object({ name: z.string().min(1) }),
             execute: async ({ name }) => boundedToolResult(workspace, await workspace.activateSkill(name)),
         }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telnyx/agent-harness",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "description": "Telnyx Agent Harness beta: portable ports, bounded turns, and Node test-host adapter.",
   "type": "module",
   "license": "UNLICENSED",
@@ -37,7 +37,7 @@
   "dependencies": {
     "@ai-sdk/gateway": "3.0.181",
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@telnyx/edge-runtime": "^0.15.2",
+    "@telnyx/edge-runtime": "^0.16.1",
     "ai": "6.0.266",
     "zod": "4.3.6"
   },