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

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/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.0",
+  "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"
   },