@telnyx/agent-harness 0.1.0-beta.0

package/dist/steps.js

@@ -0,0 +1,310 @@
+import { createHash } from "node:crypto";
+import { ensureHarnessDurabilitySchema, HarnessInjectedCrash } from "./durable.js";
+const MAX_STEP_NAME_BYTES = 512;
+const MAX_VERSION_BYTES = 512;
+const TOOL_OUTPUT_SERIALIZATION_FAILURE = "tool_output_serialization_failure";
+/** Private durable marker that never shares the tool-output value channel. */
+export class HarnessStepOutputSerializationError extends Error {
+    constructor() {
+        super("external step output is not JSON-safe");
+        this.name = "HarnessStepOutputSerializationError";
+    }
+}
+// Step contexts are reconstructed freely within one ports activation. Keep the
+// live-effect claim with that activation, not with an individual context; a
+// reopened ports instance intentionally starts fresh so durable crash recovery
+// can replay a left-behind prepared row.
+const activeStepsByActivation = new WeakMap();
+function first(rows) { return rows[0]; }
+function boundedNonblank(value, name, limit) {
+    if (!value.trim())
+        throw new Error(`${name} must not be blank`);
+    if (Buffer.byteLength(value, "utf8") > limit)
+        throw new Error(`${name} exceeds ${limit} UTF-8 bytes`);
+}
+function canonicalJson(value, seen = new WeakSet()) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error("step input must be JSON-safe");
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            throw new Error("step input must be JSON-safe");
+        seen.add(value);
+        try {
+            const values = [];
+            for (let index = 0; index < value.length; index += 1) {
+                if (!Object.hasOwn(value, index))
+                    throw new Error("step input must be JSON-safe");
+                values.push(canonicalJson(value[index], seen));
+            }
+            return `[${values.join(",")}]`;
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    if (typeof value === "object") {
+        if (Object.getPrototypeOf(value) !== Object.prototype)
+            throw new Error("step input must be JSON-safe");
+        if (seen.has(value))
+            throw new Error("step input must be JSON-safe");
+        seen.add(value);
+        const record = value;
+        try {
+            return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key], seen)}`).join(",")}}`;
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    throw new Error("step input must be JSON-safe");
+}
+export function isToolOutputSerializationFailure(value) {
+    return value instanceof HarnessStepOutputSerializationError;
+}
+function serializeStepOutput(value, external) {
+    try {
+        return { output: canonicalJson(external && value === undefined ? null : value), failure: null };
+    }
+    catch (error) {
+        if (!external)
+            throw error;
+        return { output: null, failure: TOOL_OUTPUT_SERIALIZATION_FAILURE };
+    }
+}
+function fingerprint(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function checkpoint(callback, point) {
+    try {
+        callback?.(point);
+    }
+    catch (error) {
+        throw new HarnessInjectedCrash(error);
+    }
+}
+export function createHarnessStepContext(ports, options) {
+    boundedNonblank(options.runId, "run id", MAX_STEP_NAME_BYTES);
+    boundedNonblank(options.version, "step version", MAX_VERSION_BYTES);
+    const defaultInputFingerprint = fingerprint(canonicalJson(options.input));
+    const readRun = () => first(ports.sql.exec("SELECT status FROM __telnyx_agent_harness_runs WHERE id = ?", options.runId).toArray());
+    const readStep = (name) => first(ports.sql.exec("SELECT run_id,name,identity,input_fingerprint,version,status,output,output_failure,journal_seq FROM __telnyx_agent_harness_steps WHERE run_id = ? AND name = ?", options.runId, name).toArray());
+    let activeSteps = activeStepsByActivation.get(ports.activation);
+    if (activeSteps === undefined) {
+        activeSteps = new Map();
+        activeStepsByActivation.set(ports.activation, activeSteps);
+    }
+    const claimedToolCallOrdinals = new Set();
+    // Each pending reservation carries the provider toolCallId (when available)
+    // so associateToolCallJournal can match by identity instead of position.
+    // The AI SDK 6.0.266 executes tools concurrently via Promise.all, so
+    // execution-start order can diverge from model-emission order in step.toolCalls.
+    const pendingToolCalls = [];
+    const pendingByToolCallId = new Map();
+    let journaledToolCallMarkers = new Set();
+    const markerFor = (toolName, ordinal) => fingerprint(`${options.runId}\u0000${toolName}\u0000${ordinal}`);
+    const toolCallOrdinal = (toolName, toolCallId) => {
+        boundedNonblank(toolName, "tool name", MAX_STEP_NAME_BYTES);
+        if (toolCallId !== undefined) {
+            const existing = pendingByToolCallId.get(toolCallId);
+            if (existing !== undefined) {
+                if (existing.toolName !== toolName)
+                    throw new Error("durable tool call journal does not match executed calls");
+                return existing.ordinal;
+            }
+        }
+        ensureHarnessDurabilitySchema(ports);
+        const rows = ports.sql.exec("SELECT ordinal,journal_marker FROM __telnyx_agent_harness_tool_calls WHERE run_id = ? AND tool_name = ? ORDER BY ordinal", options.runId, toolName).toArray();
+        const pending = rows.find((row) => !claimedToolCallOrdinals.has(`${toolName}\u0000${row.ordinal}`)
+            && (row.journal_marker === null || !journaledToolCallMarkers.has(row.journal_marker)));
+        if (pending !== undefined) {
+            claimedToolCallOrdinals.add(`${toolName}\u0000${pending.ordinal}`);
+            pendingToolCalls.push({ toolName, ordinal: pending.ordinal, toolCallId });
+            if (toolCallId !== undefined)
+                pendingByToolCallId.set(toolCallId, { toolName, ordinal: pending.ordinal });
+            return pending.ordinal;
+        }
+        const ordinal = (rows.at(-1)?.ordinal ?? -1) + 1;
+        ports.sql.transactionSync(() => {
+            ports.sql.exec("INSERT INTO __telnyx_agent_harness_tool_calls(run_id,tool_name,ordinal,provider_call_id,journal_marker) VALUES (?,?,?,NULL,?)", options.runId, toolName, ordinal, markerFor(toolName, ordinal));
+        });
+        claimedToolCallOrdinals.add(`${toolName}\u0000${ordinal}`);
+        pendingToolCalls.push({ toolName, ordinal, toolCallId });
+        if (toolCallId !== undefined)
+            pendingByToolCallId.set(toolCallId, { toolName, ordinal });
+        return ordinal;
+    };
+    const associateToolCallJournal = (calls) => {
+        if (calls.length !== pendingToolCalls.length)
+            throw new Error("durable tool call journal does not match executed calls");
+        ports.sql.transactionSync(() => {
+            for (const call of calls) {
+                // Match by toolCallId when the reservation recorded one, so the
+                // association is independent of concurrent execution-start order.
+                const pending = call.toolCallId !== undefined && pendingByToolCallId.has(call.toolCallId)
+                    ? pendingByToolCallId.get(call.toolCallId)
+                    : pendingToolCalls.find((p) => p.toolName === call.toolName && p.toolCallId === undefined);
+                if (pending === undefined)
+                    throw new Error("durable tool call journal does not match executed calls");
+                const existing = first(ports.sql.exec("SELECT provider_call_id FROM __telnyx_agent_harness_tool_calls WHERE run_id = ? AND tool_name = ? AND ordinal = ?", options.runId, pending.toolName, pending.ordinal).toArray());
+                if (existing === undefined || (existing.provider_call_id !== null && journaledToolCallMarkers.has(markerFor(pending.toolName, pending.ordinal))
+                    && existing.provider_call_id !== call.toolCallId)) {
+                    throw new Error("durable tool call journal conflicts with committed history");
+                }
+                ports.sql.exec("UPDATE __telnyx_agent_harness_tool_calls SET provider_call_id = ? WHERE run_id = ? AND tool_name = ? AND ordinal = ?", call.toolCallId, options.runId, pending.toolName, pending.ordinal);
+            }
+        });
+        // Build the marker map keyed by toolCallId, using the matched pending record.
+        const markers = new Map();
+        for (const call of calls) {
+            const pending = call.toolCallId !== undefined && pendingByToolCallId.has(call.toolCallId)
+                ? pendingByToolCallId.get(call.toolCallId)
+                : pendingToolCalls.find((p) => p.toolName === call.toolName && p.toolCallId === undefined);
+            if (pending === undefined)
+                throw new Error("durable tool call journal does not match executed calls");
+            markers.set(call.toolCallId, markerFor(pending.toolName, pending.ordinal));
+        }
+        pendingToolCalls.length = 0;
+        pendingByToolCallId.clear();
+        return markers;
+    };
+    const executeStep = async (name, fn, stepOptions) => {
+        boundedNonblank(name, "step name", MAX_STEP_NAME_BYTES);
+        const version = stepOptions.version ?? options.version;
+        boundedNonblank(version, "step version", MAX_VERSION_BYTES);
+        const inputFingerprint = stepOptions.input === undefined
+            ? defaultInputFingerprint
+            : fingerprint(canonicalJson(stepOptions.input));
+        ensureHarnessDurabilitySchema(ports);
+        const identity = fingerprint(`${options.runId}\u0000${name}`);
+        const existing = ports.sql.transactionSync(() => {
+            const run = readRun();
+            if (run === undefined)
+                throw new Error("step run does not exist");
+            if (run.status === "outcome_unknown")
+                throw new Error("step outcome unknown; reconcile before retrying");
+            if (run.status !== "accepted" && run.status !== "running") {
+                throw new Error("step run is no longer executable");
+            }
+            const row = readStep(name);
+            if (row === undefined)
+                return undefined;
+            if (row.input_fingerprint !== inputFingerprint)
+                throw new Error("step input fingerprint does not match committed record");
+            if (row.version !== version)
+                throw new Error("step version does not match committed record");
+            if (row.status === "effect_started") {
+                return row;
+            }
+            if (row.status === "prepared") {
+                ports.sql.exec("DELETE FROM __telnyx_agent_harness_steps WHERE run_id = ? AND name = ? AND status = 'prepared'", options.runId, name);
+                return undefined;
+            }
+            return row;
+        });
+        if (existing?.status === "effect_started") {
+            ports.sql.transactionSync(() => {
+                ports.sql.exec("UPDATE __telnyx_agent_harness_runs SET status = 'outcome_unknown', failure_code = 'HARNESS_OUTCOME_UNKNOWN', updated_at = ? WHERE id = ? AND status IN ('accepted','running')", ports.clock.now(), options.runId);
+            });
+            throw new Error("step outcome unknown; reconcile before retrying");
+        }
+        if (existing !== undefined) {
+            if (existing.output_failure === TOOL_OUTPUT_SERIALIZATION_FAILURE)
+                throw new HarnessStepOutputSerializationError();
+            return JSON.parse(existing.output);
+        }
+        ports.sql.transactionSync(() => {
+            const next = first(ports.sql.exec("SELECT COALESCE(MAX(journal_seq), 0) + 1 AS next FROM __telnyx_agent_harness_steps WHERE run_id = ?", options.runId).toArray()).next;
+            ports.sql.exec("INSERT INTO __telnyx_agent_harness_steps(run_id,name,identity,input_fingerprint,version,status,output,journal_seq) VALUES (?,?,?,?,?,'prepared',NULL,?)", options.runId, name, identity, inputFingerprint, version, next);
+        });
+        checkpoint(options.checkpoints, "before_effect");
+        if (stepOptions.external === true) {
+            ports.sql.transactionSync(() => {
+                // This conditional transition is the cancellation fence: when it
+                // wins, cancel observes effect_started and preserves uncertainty;
+                // when cancellation wins first, no external effect may begin. An
+                // accepted row is also eligible for direct durable-context callers.
+                stepOptions.beforeEffect?.();
+                ports.sql.exec("UPDATE __telnyx_agent_harness_steps SET status = 'effect_started' WHERE run_id = ? AND name = ? AND status = 'prepared' AND EXISTS (SELECT 1 FROM __telnyx_agent_harness_runs WHERE id = ? AND status IN ('accepted','running'))", options.runId, name, options.runId);
+                if (readStep(name)?.status !== "effect_started") {
+                    throw new Error("external step cannot start after run is no longer executable");
+                }
+            });
+        }
+        const output = await fn();
+        checkpoint(options.checkpoints, "after_effect_before_memo");
+        const serialized = serializeStepOutput(output, stepOptions.external === true);
+        ports.sql.transactionSync(() => {
+            ports.sql.exec("UPDATE __telnyx_agent_harness_steps SET status = 'completed', output = ?, output_failure = ? WHERE run_id = ? AND name = ?", serialized.output, serialized.failure, options.runId, name);
+        });
+        checkpoint(options.checkpoints, "after_memo");
+        if (serialized.failure !== null)
+            throw new HarnessStepOutputSerializationError();
+        return (stepOptions.external === true && output === undefined ? null : output);
+    };
+    return Object.freeze({
+        runId: options.runId,
+        isContinuation: options.isContinuation === true,
+        isCompleted(name, stepOptions = {}) {
+            boundedNonblank(name, "step name", MAX_STEP_NAME_BYTES);
+            const version = stepOptions.version ?? options.version;
+            boundedNonblank(version, "step version", MAX_VERSION_BYTES);
+            const inputFingerprint = stepOptions.input === undefined
+                ? defaultInputFingerprint
+                : fingerprint(canonicalJson(stepOptions.input));
+            ensureHarnessDurabilitySchema(ports);
+            const row = readStep(name);
+            if (row === undefined)
+                return false;
+            if (row.input_fingerprint !== inputFingerprint)
+                throw new Error("step input fingerprint does not match committed record");
+            if (row.version !== version)
+                throw new Error("step version does not match committed record");
+            return row.status === "completed";
+        },
+        nextToolCallOrdinal(toolName, toolCallId) {
+            return toolCallOrdinal(toolName, toolCallId);
+        },
+        associateToolCallJournal(calls) {
+            return associateToolCallJournal(calls);
+        },
+        reconcileToolCallJournal(journalMarkers) {
+            journaledToolCallMarkers = new Set(journalMarkers);
+        },
+        async step(name, fn, stepOptions = {}) {
+            boundedNonblank(name, "step name", MAX_STEP_NAME_BYTES);
+            const version = stepOptions.version ?? options.version;
+            boundedNonblank(version, "step version", MAX_VERSION_BYTES);
+            const inputFingerprint = stepOptions.input === undefined
+                ? defaultInputFingerprint
+                : fingerprint(canonicalJson(stepOptions.input));
+            const activeKey = `${options.runId}\u0000${name}`;
+            const inFlight = activeSteps.get(activeKey);
+            if (inFlight !== undefined) {
+                if (inFlight.inputFingerprint !== inputFingerprint)
+                    throw new Error("step input fingerprint does not match committed record");
+                if (inFlight.version !== version)
+                    throw new Error("step version does not match committed record");
+                return inFlight.execution;
+            }
+            // Promise scheduling defers executeStep until the live claim is visible,
+            // so a synchronous fn reentry cannot erase its prepared row or start a
+            // second effect.
+            const execution = Promise.resolve().then(() => executeStep(name, fn, stepOptions));
+            const active = { inputFingerprint, version, execution };
+            activeSteps.set(activeKey, active);
+            try {
+                return await execution;
+            }
+            finally {
+                if (activeSteps.get(activeKey) === active)
+                    activeSteps.delete(activeKey);
+            }
+        },
+    });
+}
+//# sourceMappingURL=steps.js.map

package/dist/tool-context.d.ts

@@ -0,0 +1,8 @@
+export type HarnessToolContext = Readonly<{
+    runId: string;
+    toolName: string;
+    ordinal: number;
+}>;
+export declare function withHarnessToolContext<T>(value: HarnessToolContext, operation: () => Promise<T>): Promise<T>;
+export declare function currentHarnessToolContext(): HarnessToolContext | undefined;
+//# sourceMappingURL=tool-context.d.ts.map

package/dist/tool-context.js

@@ -0,0 +1,9 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const context = new AsyncLocalStorage();
+export function withHarnessToolContext(value, operation) {
+    return context.run(value, operation);
+}
+export function currentHarnessToolContext() {
+    return context.getStore();
+}
+//# sourceMappingURL=tool-context.js.map

package/dist/workspace.d.ts

@@ -0,0 +1,151 @@
+import type { AgentHarnessPorts } from "./ports.js";
+declare const TOOL_WORKSPACE_CAPABILITY: unique symbol;
+export interface VirtualWorkspaceLimits {
+    readonly maxFileBytes?: number;
+    readonly maxWorkspaceBytes?: number;
+    readonly maxOutputBytes?: number;
+    readonly maxResults?: number;
+}
+export interface WorkspaceWriteOptions {
+    readonly expectedRevision?: number;
+}
+export interface WorkspaceEntry {
+    readonly path: string;
+    readonly bytes: number;
+    readonly revision: number;
+}
+export interface WorkspaceToolEntry extends WorkspaceEntry {
+    readonly origin: "workspace";
+}
+export interface WorkspaceRead extends WorkspaceEntry {
+    readonly content: string;
+    readonly truncated?: true;
+}
+export interface WorkspaceJournalEntry {
+    readonly sequence: number;
+    readonly operation: "write" | "edit";
+    readonly path: string;
+    readonly revision: number;
+    readonly bytes: number;
+}
+export interface WorkspaceSkill {
+    readonly name: string;
+    readonly path: string;
+    readonly origin: "workspace";
+}
+export interface WorkspaceSkillCatalog {
+    readonly skills: readonly WorkspaceSkill[];
+    readonly truncated?: true;
+}
+export interface ActivatedWorkspaceSkill {
+    readonly name: string;
+    readonly path: string;
+    readonly origin: "activated-skill";
+    readonly content: string;
+}
+export type PromptSource = Readonly<{
+    origin: "application";
+}> | Readonly<{
+    origin: "activated-skill";
+    name: string;
+    path: string;
+}>;
+export interface VirtualWorkspace {
+    read(path: string): Promise<WorkspaceRead | undefined>;
+    write(path: string, content: string, options?: WorkspaceWriteOptions): Promise<WorkspaceEntry>;
+    edit(path: string, oldText: string, newText: string, options?: WorkspaceWriteOptions): Promise<WorkspaceEntry>;
+    list(): Promise<Readonly<{
+        entries: readonly WorkspaceEntry[];
+        truncated?: true;
+    }>>;
+    find(needle: string): Promise<Readonly<{
+        matches: readonly WorkspaceEntry[];
+        truncated?: true;
+    }>>;
+    grep(needle: string): Promise<Readonly<{
+        matches: readonly {
+            path: string;
+            line: number;
+            text: string;
+        }[];
+        truncated?: true;
+    }>>;
+    journal(options?: Readonly<{
+        limit?: number;
+    }>): Promise<readonly WorkspaceJournalEntry[]>;
+    discoverSkills(): Promise<WorkspaceSkillCatalog>;
+    activateSkill(name: string): Promise<ActivatedWorkspaceSkill>;
+    assemblePrompt(base: string, skills: readonly string[]): Promise<Readonly<{
+        text: string;
+        sources: readonly PromptSource[];
+    }>>;
+}
+/** A concrete workspace that can atomically preflight tool mutation results. */
+export interface ToolVirtualWorkspace extends VirtualWorkspace {
+    readonly [TOOL_WORKSPACE_CAPABILITY]: true;
+}
+/**
+ * Persistent, actor-local text workspace over the existing private harness SQL
+ * port. It intentionally exposes no filesystem, process, module-loading, or
+ * dynamic-extension capability.
+ */
+export declare function createVirtualWorkspace(ports: AgentHarnessPorts, limits?: VirtualWorkspaceLimits): ToolVirtualWorkspace;
+/**
+ * Explicit server-side tools backed only by a {@link VirtualWorkspace}. Skill
+ * documents remain returned data; this factory never evaluates their content.
+ */
+export declare function createVirtualWorkspaceTools(workspace: ToolVirtualWorkspace): Readonly<{
+    read_file: import("ai").Tool<{
+        path: string;
+    }, Readonly<{
+        content: string;
+        truncated?: true;
+        path: string;
+        bytes: number;
+        revision: number;
+        origin: "workspace";
+    } | {
+        path: string;
+        found: false;
+        origin: "workspace";
+    }>>;
+    write_file: import("ai").Tool<{
+        path: string;
+        content: string;
+        expectedRevision?: number | undefined;
+    }, WorkspaceToolEntry>;
+    edit_file: import("ai").Tool<{
+        path: string;
+        oldText: string;
+        newText: string;
+        expectedRevision?: number | undefined;
+    }, WorkspaceToolEntry>;
+    list_files: import("ai").Tool<Record<string, never>, Readonly<{
+        entries: readonly WorkspaceEntry[];
+        truncated?: true;
+        origin: "workspace";
+    }>>;
+    find_files: import("ai").Tool<{
+        needle: string;
+    }, Readonly<{
+        matches: readonly WorkspaceEntry[];
+        truncated?: true;
+        origin: "workspace";
+    }>>;
+    grep_files: import("ai").Tool<{
+        needle: string;
+    }, Readonly<{
+        matches: readonly {
+            path: string;
+            line: number;
+            text: string;
+        }[];
+        truncated?: true;
+        origin: "workspace";
+    }>>;
+    activate_skill: import("ai").Tool<{
+        name: string;
+    }, ActivatedWorkspaceSkill>;
+}>;
+export {};
+//# sourceMappingURL=workspace.d.ts.map