@telnyx/agent-harness 0.1.0-beta.0

package/dist/workspace.js

@@ -0,0 +1,404 @@
+import { Buffer } from "node:buffer";
+import { tool } from "ai";
+import { z } from "zod/v4";
+const DEFAULT_MAX_FILE_BYTES = 64 * 1024;
+const DEFAULT_MAX_WORKSPACE_BYTES = 1024 * 1024;
+const DEFAULT_MAX_OUTPUT_BYTES = 16 * 1024;
+const DEFAULT_MAX_RESULTS = 100;
+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 workspaceOutputBounds = new WeakMap();
+function one(rows) {
+    return rows[0];
+}
+function boundedPositiveInteger(value, fallback, name) {
+    const selected = value ?? fallback;
+    if (!Number.isSafeInteger(selected) || selected < 1)
+        throw new TypeError(`${name} must be a positive safe integer`);
+    return selected;
+}
+function normalizePath(input) {
+    if (typeof input !== "string" || !input || input.startsWith("/") || input.includes("\\") || input.includes("\0")) {
+        throw new Error("workspace path is invalid");
+    }
+    const segments = [];
+    for (const segment of input.split("/")) {
+        if (!segment || segment === "..")
+            throw new Error("workspace path is invalid");
+        if (segment !== ".")
+            segments.push(segment);
+    }
+    if (segments.length === 0)
+        throw new Error("workspace path is invalid");
+    const normalized = segments.join("/");
+    if (Buffer.byteLength(normalized, "utf8") > MAX_PATH_BYTES)
+        throw new Error("workspace path exceeds configured bound");
+    return normalized;
+}
+function requireText(value, name) {
+    if (typeof value !== "string" || value.includes("\0"))
+        throw new Error(`${name} must be text`);
+}
+function boundedText(value, maxBytes, name) {
+    requireText(value, name);
+    const bytes = Buffer.byteLength(value, "utf8");
+    if (bytes > maxBytes)
+        throw new Error(`${name} exceeds configured bound`);
+    return bytes;
+}
+function truncateUtf8(value, maxBytes) {
+    let output = "";
+    for (const codePoint of value) {
+        if (Buffer.byteLength(output, "utf8") + Buffer.byteLength(codePoint, "utf8") > maxBytes)
+            break;
+        output += codePoint;
+    }
+    return output;
+}
+function takeBounded(values, maxBytes) {
+    const selected = [];
+    let usedBytes = 0;
+    for (const value of values) {
+        const bytes = Buffer.byteLength(JSON.stringify(value), "utf8");
+        if (bytes > maxBytes || usedBytes + bytes > maxBytes) {
+            return Object.freeze({ values: Object.freeze(selected), truncated: true });
+        }
+        selected.push(value);
+        usedBytes += bytes;
+    }
+    return Object.freeze({ values: Object.freeze(selected) });
+}
+function boundedResult(value, maxBytes) {
+    if (Buffer.byteLength(JSON.stringify(value), "utf8") > maxBytes) {
+        throw new Error("workspace output exceeds configured bound");
+    }
+    return value;
+}
+/**
+ * COMPUTE-902: Calculate the maximum content bytes that can fit inside a
+ * serialized read envelope without exceeding the output budget.
+ *
+ * When `includeTruncated` is true, the budget accounts for the
+ * `,"truncated":true` field (17 bytes). When false, it assumes no
+ * truncated field is present (content fits fully).
+ */
+function readContentBudget(entry, maxOutputBytes, includeTruncated) {
+    if (maxOutputBytes <= 0)
+        return 0;
+    // Measure overhead with null content. JSON.stringify(null) === "null" (4 bytes).
+    const envelope = JSON.stringify({ ...entry, content: null });
+    const overhead = Buffer.byteLength(envelope, "utf8") - 4;
+    const truncatedReserve = includeTruncated ? 17 : 0; // ,"truncated":true
+    return Math.max(0, maxOutputBytes - overhead - truncatedReserve);
+}
+/**
+ * COMPUTE-902/903 followup: Iteratively truncate content so the JSON-serialized
+ * read envelope fits within maxOutputBytes.
+ *
+ * Characters like `"`, `\`, and control codes expand during JSON encoding
+ * (e.g. `"` → `\"`), so raw-byte truncation alone is insufficient. This
+ * function builds the serialized envelope, measures its actual byte length,
+ * and shrinks the content until the serialized form fits the budget.
+ *
+ * Returns the truncated content and whether truncation occurred.
+ */
+function readBoundedContent(entry, content, maxOutputBytes) {
+    // Phase 1: Try full content without the truncated flag.
+    const fullResult = Object.freeze({ ...entry, content });
+    if (Buffer.byteLength(JSON.stringify(fullResult), "utf8") <= maxOutputBytes) {
+        return fullResult;
+    }
+    // Phase 2: Content needs truncation. Iteratively shrink until the
+    // serialized envelope (with the truncated:true field) fits.
+    const truncatedFlag = Object.freeze({ ...entry, content: "", truncated: true });
+    const minOverhead = Buffer.byteLength(JSON.stringify(truncatedFlag), "utf8");
+    if (minOverhead > maxOutputBytes) {
+        // Even empty content with the truncated flag exceeds the budget.
+        throw new Error("workspace output exceeds configured bound");
+    }
+    // Binary search for the largest content prefix that fits the serialized
+    // envelope. The raw-byte budget is an upper bound; the actual fitting size
+    // may be smaller because JSON escaping expands characters like " and \.
+    let lo = 0;
+    let hi = readContentBudget(entry, maxOutputBytes, true);
+    // Check whether any non-empty prefix fits before entering the search.
+    if (hi > 0) {
+        const hiTruncated = truncateUtf8(content, hi);
+        const hiCandidate = Object.freeze({ ...entry, content: hiTruncated, truncated: true });
+        if (Buffer.byteLength(JSON.stringify(hiCandidate), "utf8") <= maxOutputBytes) {
+            return hiCandidate;
+        }
+    }
+    // Binary search: lo always fits (or is 0), hi never fits (or is 0).
+    while (lo < hi) {
+        const mid = lo + Math.floor((hi - lo + 1) / 2);
+        const midTruncated = truncateUtf8(content, mid);
+        const midCandidate = Object.freeze({ ...entry, content: midTruncated, truncated: true });
+        if (Buffer.byteLength(JSON.stringify(midCandidate), "utf8") <= maxOutputBytes) {
+            lo = mid; // mid fits — try larger
+        }
+        else {
+            hi = mid - 1; // mid doesn't fit — try smaller
+        }
+    }
+    if (lo > 0) {
+        const truncated = truncateUtf8(content, lo);
+        return Object.freeze({ ...entry, content: truncated, truncated: true });
+    }
+    // No non-empty content slice fit. Return the empty truncated envelope if
+    // it fits the budget (exact-fit case); only throw if it does not.
+    if (minOverhead <= maxOutputBytes) {
+        return truncatedFlag;
+    }
+    throw new Error("workspace output exceeds configured bound");
+}
+function boundedToolResult(workspace, value) {
+    return boundedResult(value, workspaceOutputBounds.get(workspace) ?? DEFAULT_MAX_OUTPUT_BYTES);
+}
+function toolMutationOptions(expectedRevision) {
+    return Object.freeze({
+        ...(expectedRevision === undefined ? {} : { expectedRevision }),
+        [TOOL_MUTATION_RESULT]: true,
+    });
+}
+function fileEntry(row) {
+    return Object.freeze({ path: row.path, bytes: row.bytes, revision: row.revision });
+}
+/**
+ * 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 function createVirtualWorkspace(ports, limits = {}) {
+    const maxFileBytes = boundedPositiveInteger(limits.maxFileBytes, DEFAULT_MAX_FILE_BYTES, "maxFileBytes");
+    const maxWorkspaceBytes = boundedPositiveInteger(limits.maxWorkspaceBytes, DEFAULT_MAX_WORKSPACE_BYTES, "maxWorkspaceBytes");
+    const maxOutputBytes = boundedPositiveInteger(limits.maxOutputBytes, DEFAULT_MAX_OUTPUT_BYTES, "maxOutputBytes");
+    const maxResults = boundedPositiveInteger(limits.maxResults, DEFAULT_MAX_RESULTS, "maxResults");
+    ports.sql.transactionSync(() => {
+        ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_workspace_files (path TEXT PRIMARY KEY NOT NULL, content TEXT NOT NULL, bytes INTEGER NOT NULL CHECK(bytes >= 0), revision INTEGER NOT NULL CHECK(revision > 0))");
+        ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_workspace_journal (sequence INTEGER PRIMARY KEY AUTOINCREMENT, operation TEXT NOT NULL CHECK(operation IN ('write','edit')), path TEXT NOT NULL, revision INTEGER NOT NULL CHECK(revision > 0), bytes INTEGER NOT NULL CHECK(bytes >= 0))");
+    });
+    const get = (path) => one(ports.sql.exec("SELECT path,content,bytes,revision FROM __telnyx_agent_harness_workspace_files WHERE path = ?", path).toArray());
+    const write = async (inputPath, content, options = {}) => {
+        const path = normalizePath(inputPath);
+        const bytes = boundedText(content, maxFileBytes, "workspace file") + Buffer.byteLength(path, "utf8");
+        return ports.sql.transactionSync(() => {
+            const existing = get(path);
+            if (options.expectedRevision !== undefined && (!Number.isSafeInteger(options.expectedRevision) || options.expectedRevision < 1 || existing?.revision !== options.expectedRevision)) {
+                throw new Error("workspace revision conflict");
+            }
+            const total = one(ports.sql.exec("SELECT COALESCE(SUM(bytes), 0) AS total FROM __telnyx_agent_harness_workspace_files WHERE path <> ?", path).toArray())?.total ?? 0;
+            if (total + bytes > maxWorkspaceBytes)
+                throw new Error("workspace quota exceeded");
+            const revision = (existing?.revision ?? 0) + 1;
+            const entry = boundedResult(Object.freeze({ path, bytes, revision }), maxOutputBytes);
+            const result = options[TOOL_MUTATION_RESULT]
+                ? boundedToolResult(workspace, Object.freeze({ origin: "workspace", ...entry }))
+                : entry;
+            ports.sql.exec("INSERT INTO __telnyx_agent_harness_workspace_files(path,content,bytes,revision) VALUES (?,?,?,?) ON CONFLICT(path) DO UPDATE SET content=excluded.content,bytes=excluded.bytes,revision=excluded.revision", path, content, bytes, revision);
+            ports.sql.exec("INSERT INTO __telnyx_agent_harness_workspace_journal(operation,path,revision,bytes) VALUES ('write',?,?,?)", path, revision, bytes);
+            return result;
+        });
+    };
+    const workspace = Object.freeze({
+        [TOOL_WORKSPACE_CAPABILITY]: true,
+        async read(inputPath) {
+            const row = get(normalizePath(inputPath));
+            if (row === undefined)
+                return undefined;
+            // COMPUTE-902/903 followup: Budget reads against the serialized JSON
+            // envelope, not raw content bytes. Characters like " and \ expand
+            // during JSON encoding, so raw-byte budgeting alone can return a
+            // payload whose serialized form exceeds maxOutputBytes.
+            const entry = fileEntry(row);
+            return readBoundedContent(entry, row.content, maxOutputBytes);
+        },
+        write,
+        async edit(inputPath, oldText, newText, options = {}) {
+            const path = normalizePath(inputPath);
+            requireText(oldText, "edit source");
+            requireText(newText, "edit replacement");
+            if (!oldText)
+                throw new Error("edit source must not be empty");
+            return ports.sql.transactionSync(() => {
+                const existing = get(path);
+                if (existing === undefined)
+                    throw new Error("workspace file does not exist");
+                if (options.expectedRevision !== undefined && existing.revision !== options.expectedRevision)
+                    throw new Error("workspace revision conflict");
+                const first = existing.content.indexOf(oldText);
+                if (first < 0)
+                    throw new Error("edit source was not found");
+                if (existing.content.indexOf(oldText, first + 1) >= 0)
+                    throw new Error("edit source is ambiguous");
+                const content = `${existing.content.slice(0, first)}${newText}${existing.content.slice(first + oldText.length)}`;
+                const bytes = boundedText(content, maxFileBytes, "workspace file") + Buffer.byteLength(path, "utf8");
+                const total = one(ports.sql.exec("SELECT COALESCE(SUM(bytes), 0) AS total FROM __telnyx_agent_harness_workspace_files WHERE path <> ?", path).toArray())?.total ?? 0;
+                if (total + bytes > maxWorkspaceBytes)
+                    throw new Error("workspace quota exceeded");
+                const revision = existing.revision + 1;
+                const entry = boundedResult(Object.freeze({ path, bytes, revision }), maxOutputBytes);
+                const result = options[TOOL_MUTATION_RESULT]
+                    ? boundedToolResult(workspace, Object.freeze({ origin: "workspace", ...entry }))
+                    : entry;
+                ports.sql.exec("UPDATE __telnyx_agent_harness_workspace_files SET content = ?,bytes = ?,revision = ? WHERE path = ?", content, bytes, revision, path);
+                ports.sql.exec("INSERT INTO __telnyx_agent_harness_workspace_journal(operation,path,revision,bytes) VALUES ('edit',?,?,?)", path, revision, bytes);
+                return result;
+            });
+        },
+        async list() {
+            const rows = ports.sql.exec("SELECT path,content,bytes,revision FROM __telnyx_agent_harness_workspace_files ORDER BY path LIMIT ?", maxResults + 1).toArray();
+            const bounded = takeBounded(rows.slice(0, maxResults).map(fileEntry), maxOutputBytes);
+            return boundedResult(Object.freeze({ entries: bounded.values, ...(rows.length > maxResults || bounded.truncated ? { truncated: true } : {}) }), maxOutputBytes);
+        },
+        async find(needle) {
+            requireText(needle, "find query");
+            if (!needle)
+                throw new Error("find query must not be empty");
+            const rows = ports.sql.exec("SELECT path,content,bytes,revision FROM __telnyx_agent_harness_workspace_files WHERE instr(content, ?) > 0 ORDER BY path LIMIT ?", needle, maxResults + 1).toArray();
+            const bounded = takeBounded(rows.slice(0, maxResults).map(fileEntry), maxOutputBytes);
+            return boundedResult(Object.freeze({ matches: bounded.values, ...(rows.length > maxResults || bounded.truncated ? { truncated: true } : {}) }), maxOutputBytes);
+        },
+        async grep(needle) {
+            requireText(needle, "grep query");
+            if (!needle)
+                throw new Error("grep query must not be empty");
+            const rows = ports.sql.exec("SELECT path,content,bytes,revision FROM __telnyx_agent_harness_workspace_files WHERE instr(content, ?) > 0 ORDER BY path", needle).toArray();
+            const matches = [];
+            for (const row of rows) {
+                for (const [index, line] of row.content.split("\n").entries()) {
+                    if (!line.includes(needle))
+                        continue;
+                    const candidate = Object.freeze({ path: row.path, line: index + 1, text: truncateUtf8(line, maxOutputBytes) });
+                    const bounded = takeBounded([...matches, candidate], maxOutputBytes);
+                    if (bounded.truncated || matches.length >= maxResults)
+                        return boundedResult(Object.freeze({ matches: Object.freeze(matches), truncated: true }), maxOutputBytes);
+                    matches.push(candidate);
+                }
+            }
+            return boundedResult(Object.freeze({ matches: Object.freeze(matches) }), maxOutputBytes);
+        },
+        async journal(options = {}) {
+            const limit = boundedPositiveInteger(options.limit, maxResults, "journal limit");
+            if (limit > maxResults)
+                throw new Error("journal limit exceeds configured bound");
+            const rows = ports.sql.exec("SELECT sequence,operation,path,revision,bytes FROM __telnyx_agent_harness_workspace_journal ORDER BY sequence LIMIT ?", limit).toArray().map((row) => Object.freeze(row));
+            const bounded = takeBounded(rows, maxOutputBytes);
+            if (bounded.truncated)
+                throw new Error("journal output exceeds configured bound");
+            return boundedResult(Object.freeze(bounded.values), maxOutputBytes);
+        },
+        async discoverSkills() {
+            const rows = ports.sql.exec("SELECT path,content,bytes,revision FROM __telnyx_agent_harness_workspace_files WHERE path LIKE 'skills/%' ORDER BY path").toArray();
+            const skills = rows.flatMap((row) => {
+                const match = SKILL_PATH.exec(row.path);
+                return match === null ? [] : [Object.freeze({ name: match[1], path: row.path, origin: "workspace" })];
+            });
+            const selected = [];
+            for (const [index, skill] of skills.entries()) {
+                if (index >= maxResults)
+                    break;
+                const truncated = index < skills.length - 1 || index + 1 >= maxResults && skills.length > maxResults;
+                const candidate = Object.freeze({ skills: Object.freeze([...selected, skill]), ...(truncated ? { truncated: true } : {}) });
+                if (Buffer.byteLength(JSON.stringify(candidate), "utf8") > maxOutputBytes)
+                    break;
+                selected.push(skill);
+            }
+            const truncated = selected.length < skills.length;
+            return boundedResult(Object.freeze({ skills: Object.freeze(selected), ...(truncated ? { truncated: true } : {}) }), maxOutputBytes);
+        },
+        async activateSkill(name) {
+            if (typeof name !== "string" || !name || name.includes("/") || name.includes("\\") || name.includes("\0"))
+                throw new Error("skill name is invalid");
+            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);
+        },
+        async assemblePrompt(base, names) {
+            requireText(base, "application prompt");
+            const sources = [Object.freeze({ origin: "application" })];
+            const contents = [base];
+            for (const name of names) {
+                const active = await workspace.activateSkill(name);
+                sources.push(Object.freeze({ origin: "activated-skill", name: active.name, path: active.path }));
+                contents.push(active.content);
+            }
+            const text = contents.join("\n\n");
+            // COMPUTE-903: The model-visible text is bounded against maxOutputBytes
+            // because that is what the model consumes. The provenance-only sources
+            // carry no duplicated source bodies.
+            // COMPUTE-902/903 followup: The serialized { text, sources } envelope must
+            // also honor maxOutputBytes. Source metadata (origin, name, path) has a
+            // non-trivial serialized size, so we split the budget: measure the sources
+            // overhead, then bound the text to maxOutputBytes minus that overhead.
+            // This preserves COMPUTE-903 (no double-counting of source *content*)
+            // while enforcing the serialized output contract.
+            const sourcesOverhead = Buffer.byteLength(JSON.stringify(Object.freeze({ text: "", sources: Object.freeze(sources) })), "utf8");
+            if (sourcesOverhead > maxOutputBytes) {
+                // Source metadata alone exceeds the budget — cannot fit any text.
+                throw new Error("workspace output exceeds configured bound");
+            }
+            const textBudget = maxOutputBytes - sourcesOverhead;
+            boundedText(text, textBudget, "prompt");
+            return boundedResult(Object.freeze({ text, sources: Object.freeze(sources) }), maxOutputBytes);
+        },
+    });
+    workspaceOutputBounds.set(workspace, maxOutputBytes);
+    return workspace;
+}
+/**
+ * Explicit server-side tools backed only by a {@link VirtualWorkspace}. Skill
+ * documents remain returned data; this factory never evaluates their content.
+ */
+export function createVirtualWorkspaceTools(workspace) {
+    if (!workspaceOutputBounds.has(workspace)) {
+        throw new TypeError("virtual workspace tools require a concrete workspace");
+    }
+    const path = z.string().min(1);
+    return Object.freeze({
+        read_file: tool({
+            description: "Read a bounded text file from the actor-local virtual workspace.",
+            inputSchema: z.object({ path }),
+            execute: async ({ path: inputPath }) => {
+                const canonicalPath = normalizePath(inputPath);
+                return boundedToolResult(workspace, Object.freeze({ origin: "workspace", ...(await workspace.read(canonicalPath) ?? { path: canonicalPath, found: false }) }));
+            },
+        }),
+        write_file: tool({
+            description: "Write bounded text to an actor-local virtual workspace file.",
+            inputSchema: z.object({ path, content: z.string(), expectedRevision: z.number().int().positive().optional() }),
+            execute: async ({ path: inputPath, content, expectedRevision }) => workspace.write(inputPath, content, toolMutationOptions(expectedRevision)),
+        }),
+        edit_file: tool({
+            description: "Replace exactly one text occurrence in an actor-local virtual workspace file.",
+            inputSchema: z.object({ path, oldText: z.string().min(1), newText: z.string(), expectedRevision: z.number().int().positive().optional() }),
+            execute: async ({ path: inputPath, oldText, newText, expectedRevision }) => workspace.edit(inputPath, oldText, newText, toolMutationOptions(expectedRevision)),
+        }),
+        list_files: tool({
+            description: "List actor-local virtual workspace files in deterministic path order.",
+            inputSchema: z.object({}),
+            execute: async () => boundedToolResult(workspace, Object.freeze({ origin: "workspace", ...(await workspace.list()) })),
+        }),
+        find_files: tool({
+            description: "Find text in actor-local virtual workspace files in deterministic path order.",
+            inputSchema: z.object({ needle: z.string().min(1) }),
+            execute: async ({ needle }) => boundedToolResult(workspace, Object.freeze({ origin: "workspace", ...(await workspace.find(needle)) })),
+        }),
+        grep_files: tool({
+            description: "Find matching text lines in actor-local virtual workspace files without evaluating patterns.",
+            inputSchema: z.object({ needle: z.string().min(1) }),
+            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.",
+            inputSchema: z.object({ name: z.string().min(1) }),
+            execute: async ({ name }) => boundedToolResult(workspace, await workspace.activateSkill(name)),
+        }),
+    });
+}
+//# sourceMappingURL=workspace.js.map

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@telnyx/agent-harness",
+  "version": "0.1.0-beta.0",
+  "description": "Telnyx Agent Harness beta: portable ports, bounded turns, and Node test-host adapter.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./contract": {
+      "types": "./dist/contract.d.ts",
+      "import": "./dist/contract.js"
+    },
+    "./node": {
+      "types": "./dist/node-adapter.d.ts",
+      "import": "./dist/node-adapter.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && node ../../scripts/build-agent-harness-node.mjs",
+    "test": "vitest run",
+    "lint": "tsc -p tsconfig.lint.json",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@ai-sdk/gateway": "3.0.181",
+    "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
+    "@telnyx/edge-runtime": "^0.15.2",
+    "ai": "6.0.266",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@telnyx/ai-sdk-provider": "1.0.0",
+    "@telnyx/runtime-internal-tbd": "*",
+    "esbuild": "^0.28.1",
+    "vitest": "^4.1.6"
+  },
+  "peerDependencies": {
+    "vitest": "^4.1.6"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  }
+}