@shardflux/sdk 0.14.0 → 0.16.0

package/dist/tools.js

@@ -10,6 +10,7 @@
  * application; toOpenAITools/toAnthropicTools export the definitions in those
  * providers' formats and executeToolCall dispatches a model's tool call.
  */
+import { runComputerActions } from "./computer.js";
 import { CAPTURE_BARRIER, burstFailure } from "./cell.js";
 import { ExecStartError, ShardfluxApiError } from "./errors.js";
 import { newExecutionId } from "./executions.js";
@@ -82,6 +83,8 @@ export function validateArgs(schema, value, path = '$') {
         issues.push(`${path} must be one of ${schema.enum.join(', ')}`);
     return issues;
 }
+// Without a token yet (no grantedTools) and no opts.tools, every tool but computer: computer is offered only when a
+// token grants it (the workspace's computer use is on) or opts.tools names it.
 const ALL = ['exec', 'files', 'pty', 'process', 'git', 'browser'];
 /** The tool permissions whose tools work on a file-first workspace: files and executions. */
 const FILE_FIRST_TOOLS = ['exec', 'files'];
@@ -97,6 +100,45 @@ const RESOURCE_HINTS = new Set(['auto', 'light', 'heavy']);
 /** Tools served from a sleeping workspace's disk without waking it: the runner sends no hint. */
 const DISK_READS = new Set(['read_file', 'list_files', 'search_files']);
 const obj = (properties, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
+/** One computer toolset action's parameters (the computer tool's and each computer_batch item's). */
+const COMPUTER_ACTION = {
+    action: {
+        type: 'string',
+        enum: ['screenshot', 'zoom', 'left_click', 'right_click', 'middle_click', 'double_click', 'triple_click', 'left_click_drag', 'mouse_move',
+            'left_mouse_down', 'left_mouse_up', 'cursor_position', 'scroll', 'type', 'key', 'hold_key', 'wait'],
+    },
+    coordinate: { type: 'array', items: { type: 'integer', minimum: 0 }, minItems: 2, maxItems: 2, description: '[x, y]. Required for mouse_move and as the end of left_click_drag; optional for clicks and scroll (default: at the pointer).' },
+    start_coordinate: { type: 'array', items: { type: 'integer', minimum: 0 }, minItems: 2, maxItems: 2, description: 'left_click_drag: where the drag starts.' },
+    region: { type: 'array', items: { type: 'integer', minimum: 0 }, minItems: 4, maxItems: 4, description: 'zoom: [x0, y0, x1, y1], shown enlarged.' },
+    text: { type: 'string', maxLength: 20_000, description: 'type: the text. key, hold_key: keys such as "Return", "ctrl+s", "alt+Tab" (space-separated for a sequence). Clicks, drag, scroll: modifiers held, e.g. "shift".' },
+    scroll_direction: { type: 'string', enum: ['up', 'down', 'left', 'right'] },
+    scroll_amount: { type: 'integer', minimum: 1, maximum: 100, description: 'scroll: wheel clicks.' },
+    duration: { type: 'number', minimum: 0, maximum: 300, description: 'Seconds: wait, hold_key.' },
+    repeat: { type: 'integer', minimum: 1, maximum: 100, description: 'key: presses (default 1).' },
+};
+/** The screenshot after input actions (0.15.0+). */
+const COMPUTER_LOOK = {
+    screenshot: { type: 'boolean', description: 'Take a screenshot after the input actions (default true); false when you do not need to look.' },
+    settle_ms: { type: 'integer', minimum: 0, maximum: 10_000, description: 'Wait this long before that screenshot when the screen may change (default 250).' },
+    format: { type: 'string', enum: ['png', 'jpeg'], description: 'Image format (default png; jpeg is smaller).' },
+    quality: { type: 'integer', minimum: 1, maximum: 100, description: 'JPEG quality (default 80).' },
+};
+const COMPUTER_ACTION_KEYS = ['coordinate', 'start_coordinate', 'region', 'text', 'scroll_direction', 'scroll_amount', 'duration', 'repeat'];
+function computerAction(a) {
+    const action = { action: a.action };
+    for (const k of COMPUTER_ACTION_KEYS)
+        if (a[k] !== undefined && a[k] !== null)
+            action[k] = a[k];
+    return action;
+}
+function computerImage(a) {
+    return {
+        ...(typeof a.settle_ms === 'number' ? { settle_ms: a.settle_ms } : {}),
+        ...(a.format === 'png' || a.format === 'jpeg' ? { format: a.format } : {}),
+        ...(typeof a.quality === 'number' ? { quality: a.quality } : {}),
+    };
+}
+const imageView = (img) => ({ mime_type: img.format === 'jpeg' ? 'image/jpeg' : 'image/png', width: img.width, height: img.height, data_base64: img.data });
 const path = (description = 'Absolute path inside the workspace, e.g. /home/user/project/main.py') => ({ type: 'string', minLength: 1, maxLength: 4096, description });
 const signal = { type: 'string', description: 'Signal name such as SIGTERM, SIGINT or SIGKILL.', minLength: 2, maxLength: 12 };
 function clip(text, max) {
@@ -245,7 +287,7 @@ async function waitForExit(c, s, waitMs, signal) {
 }
 /** Builds the tool list for a workspace. Synchronous: tokens are fetched on first use. */
 export function workspaceTools(workspace, opts = {}) {
-    const cell = () => workspace.cell({
+    const cell = async () => workspace.cell({
         ...(opts.agentLabel !== undefined ? { agentLabel: opts.agentLabel } : {}),
         ...(opts.wake !== undefined ? { wake: opts.wake } : {}),
         ...(opts.transitionTimeoutMs !== undefined ? { transitionTimeoutMs: opts.transitionTimeoutMs } : {}),
@@ -297,7 +339,7 @@ export function workspaceTools(workspace, opts = {}) {
                 run: async (a, o) => {
                     const executionId = newExecutionId();
                     opts.onExecution?.(executionId);
-                    const r = await cell().executions.run(['bash', '-lc', String(a.command)], {
+                    const r = await (await cell()).executions.run(['bash', '-lc', String(a.command)], {
                         executionId,
                         ...(typeof a.cwd === 'string' ? { cwd: a.cwd } : opts.defaultCwd ? { cwd: opts.defaultCwd } : {}),
                         timeoutMs: typeof a.timeout_ms === 'number' ? a.timeout_ms : 600_000,
@@ -343,7 +385,7 @@ export function workspaceTools(workspace, opts = {}) {
                     if (a.background === true) {
                         // A session of its own: the start answers at once, and exec_read / exec_cancel find it by session_id.
                         // The command runs until it exits or its timeout_ms, if one is set. (Never a burst: refused above.)
-                        const s = await cell().exec.start({
+                        const s = await (await cell()).exec.start({
                             argv: ['bash', '-lc', String(a.command)],
                             ...(cwd !== undefined ? { cwd } : {}),
                             ...(typeof a.timeout_ms === 'number' ? { timeout_ms: a.timeout_ms } : {}),
@@ -359,7 +401,7 @@ export function workspaceTools(workspace, opts = {}) {
                     }
                     let r;
                     try {
-                        r = await cell().exec.run(['bash', '-lc', String(a.command)], {
+                        r = await (await cell()).exec.run(['bash', '-lc', String(a.command)], {
                             ...(cwd !== undefined ? { cwd } : {}),
                             timeoutMs: typeof a.timeout_ms === 'number' ? a.timeout_ms : 600_000,
                             ...(typeof a.stdin === 'string' ? { stdin: a.stdin } : {}),
@@ -411,7 +453,7 @@ export function workspaceTools(workspace, opts = {}) {
                     description: 'Read a command started with exec background: true: its state, exit code and output. Without offsets it returns the end of each stream; pass next_stdout_offset and next_stderr_offset back to read only new output. wait_ms waits up to that long for the command to exit and returns as soon as it does.',
                     parameters: obj({ session_id: sessionId, stdout_offset: { type: 'integer', minimum: 0 }, stderr_offset: { type: 'integer', minimum: 0 }, wait_ms: { type: 'integer', minimum: 0, maximum: 60_000 } }, ['session_id']),
                     run: async (a, o) => {
-                        const c = cell();
+                        const c = await cell();
                         const id = String(a.session_id);
                         let s = await c.exec.get(id);
                         if (typeof a.wait_ms === 'number' && a.wait_ms > 0 && running(s))
@@ -461,7 +503,7 @@ export function workspaceTools(workspace, opts = {}) {
                     // The workspace waits 5 s without a grace and at most 60 s.
                     parameters: obj({ session_id: sessionId, grace_ms: { type: 'integer', minimum: 1, maximum: 60_000 } }, ['session_id']),
                     run: async (a) => {
-                        const s = await cell().exec.cancel(String(a.session_id), typeof a.grace_ms === 'number' ? a.grace_ms : undefined);
+                        const s = await (await cell()).exec.cancel(String(a.session_id), typeof a.grace_ms === 'number' ? a.grace_ms : undefined);
                         return { session_id: s.session_id, state: s.state, exit_code: running(s) ? null : (s.exit_code ?? null), canceled: s.canceled ?? false };
                     },
                 },
@@ -472,7 +514,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'Read a text file from the workspace (UTF-8). Use offset/length for large files.',
             parameters: obj({ path: path(), offset: { type: 'integer', minimum: 0 }, length: { type: 'integer', minimum: 1, maximum: 10_485_760 } }, ['path']),
             run: async (a) => {
-                const bytes = await cell().files.read(String(a.path), {
+                const bytes = await (await cell()).files.read(String(a.path), {
                     ...(typeof a.offset === 'number' ? { offset: a.offset } : {}),
                     length: typeof a.length === 'number' ? Math.min(a.length, max) : max + 1,
                 });
@@ -491,7 +533,7 @@ export function workspaceTools(workspace, opts = {}) {
                 create_parents: { type: 'boolean', description: 'Create missing parent directories (default true).' },
             }, ['path', 'content']),
             run: async (a) => {
-                const r = await cell().files.write(String(a.path), String(a.content), { append: a.append === true, createParents: a.create_parents !== false });
+                const r = await (await cell()).files.write(String(a.path), String(a.content), { append: a.append === true, createParents: a.create_parents !== false });
                 return { path: r.path, bytes_written: r.bytes_written, sha256: r.sha256, durable: r.durable };
             },
         },
@@ -501,7 +543,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'List a directory in the workspace.',
             parameters: obj({ path: path('Absolute directory path.'), limit: { type: 'integer', minimum: 1, maximum: 10_000 } }, ['path']),
             run: async (a) => {
-                const r = await cell().files.list(String(a.path), typeof a.limit === 'number' ? { limit: a.limit } : { limit: 500 });
+                const r = await (await cell()).files.list(String(a.path), typeof a.limit === 'number' ? { limit: a.limit } : { limit: 500 });
                 return { entries: r.entries.map((e) => ({ name: e.name, path: e.path, type: e.type, size: e.size, modified_at: e.modified_at })), truncated: r.truncated };
             },
         },
@@ -520,7 +562,7 @@ export function workspaceTools(workspace, opts = {}) {
                 context_lines: { type: 'integer', minimum: 0, maximum: 5, description: 'Lines of context to return before and after each match.' },
             }, ['path', 'pattern']),
             run: async (a, o) => {
-                const r = await cell().files.search(String(a.path), String(a.pattern), {
+                const r = await (await cell()).files.search(String(a.path), String(a.pattern), {
                     ...(typeof a.regex === 'boolean' ? { regex: a.regex } : {}),
                     ...(typeof a.case_insensitive === 'boolean' ? { caseInsensitive: a.case_insensitive } : {}),
                     ...(Array.isArray(a.include) ? { include: a.include } : {}),
@@ -566,7 +608,7 @@ export function workspaceTools(workspace, opts = {}) {
                 },
             }, ['path', 'edits']),
             run: async (a, o) => {
-                const c = cell();
+                const c = await cell();
                 const file = String(a.path);
                 // Without a revision from the model, pin the edit to the content current now, so a concurrent change between
                 // this read and the patch is refused (revision_mismatch) instead of edited blindly.
@@ -582,7 +624,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'List processes running in the workspace.',
             parameters: obj({}),
             run: async () => {
-                const r = await cell().processes.list();
+                const r = await (await cell()).processes.list();
                 return { processes: r.data.map((p) => ({ pid: p.pid, ppid: p.ppid, comm: p.comm, cmdline: p.cmdline, state: p.state, rss_bytes: p.rss_bytes })) };
             },
         },
@@ -592,7 +634,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'Send a signal to a process in the workspace (e.g. stop a server).',
             parameters: obj({ pid: { type: 'integer', minimum: 2 }, signal }, ['pid', 'signal']),
             run: async (a) => {
-                await cell().processes.signal(Number(a.pid), String(a.signal));
+                await (await cell()).processes.signal(Number(a.pid), String(a.signal));
                 return { signalled: true };
             },
         },
@@ -602,7 +644,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'Open an interactive terminal (PTY) in the workspace; returns a session_id for terminal_send/terminal_read.',
             parameters: obj({ command: { type: 'string', maxLength: 10_000, description: 'Program to run (default: login shell).' }, rows: { type: 'integer', minimum: 1, maximum: 1000 }, cols: { type: 'integer', minimum: 1, maximum: 1000 } }),
             run: async (a) => {
-                const s = await cell().pty.open({
+                const s = await (await cell()).pty.open({
                     ...(typeof a.command === 'string' ? { argv: ['bash', '-lc', a.command] } : {}),
                     ...(typeof a.rows === 'number' ? { rows: a.rows } : {}),
                     ...(typeof a.cols === 'number' ? { cols: a.cols } : {}),
@@ -616,7 +658,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'Type input into a terminal session (include "\\n" to press Enter).',
             parameters: obj({ session_id: { type: 'string', minLength: 1, maxLength: 64 }, input: { type: 'string', maxLength: 1_000_000 } }, ['session_id', 'input']),
             run: async (a) => {
-                const s = await cell().pty.input(String(a.session_id), String(a.input));
+                const s = await (await cell()).pty.input(String(a.session_id), String(a.input));
                 return { state: s.state, next_offset: s.output_size };
             },
         },
@@ -626,7 +668,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'Read terminal output from an offset (returns next_offset to continue). Waits briefly for new output.',
             parameters: obj({ session_id: { type: 'string', minLength: 1, maxLength: 64 }, offset: { type: 'integer', minimum: 0 }, wait_ms: { type: 'integer', minimum: 0, maximum: 60_000 } }, ['session_id']),
             run: async (a) => {
-                const r = await cell().pty.read(String(a.session_id), {
+                const r = await (await cell()).pty.read(String(a.session_id), {
                     offset: typeof a.offset === 'number' ? a.offset : 0,
                     timeoutMs: typeof a.wait_ms === 'number' ? Math.max(100, a.wait_ms) : 3_000,
                     maxBytes: max,
@@ -640,7 +682,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'Close a terminal session.',
             parameters: obj({ session_id: { type: 'string', minLength: 1, maxLength: 64 } }, ['session_id']),
             run: async (a) => {
-                const s = await cell().pty.close(String(a.session_id));
+                const s = await (await cell()).pty.close(String(a.session_id));
                 return { state: s.state };
             },
         },
@@ -650,7 +692,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'Clone a git repository (HTTPS) into the workspace.',
             parameters: obj({ url: { type: 'string', minLength: 9, maxLength: 2048, description: 'https:// remote URL.' }, path: path('Destination directory.'), branch: { type: 'string', maxLength: 255 }, depth: { type: 'integer', minimum: 1 } }, ['url', 'path']),
             run: async (a) => {
-                const r = await cell().git.clone({
+                const r = await (await cell()).git.clone({
                     url: String(a.url),
                     path: String(a.path),
                     ...(typeof a.branch === 'string' ? { branch: a.branch } : {}),
@@ -664,7 +706,7 @@ export function workspaceTools(workspace, opts = {}) {
             permission: 'git',
             description: 'Show the git status of a repository in the workspace.',
             parameters: obj({ path: path('Repository directory.') }, ['path']),
-            run: async (a) => cell().git.status(String(a.path)),
+            run: async (a) => (await cell()).git.status(String(a.path)),
         },
         {
             name: 'git_commit',
@@ -672,17 +714,66 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'Stage all changes and commit in a repository in the workspace.',
             parameters: obj({ path: path('Repository directory.'), message: { type: 'string', minLength: 1, maxLength: 65_536 } }, ['path', 'message']),
             run: async (a) => {
-                const r = await cell().git.commit({ path: String(a.path), message: String(a.message), all: true });
+                const r = await (await cell()).git.commit({ path: String(a.path), message: String(a.message), all: true });
                 return { exit_code: r.exit_code, commit: r.commit ?? null, stdout: clip(r.stdout, max).text, stderr: clip(r.stderr, max).text };
             },
         },
+        {
+            name: 'computer',
+            permission: 'computer',
+            description: 'Use the workspace desktop: its screen, mouse and keyboard. One action per call (computer_batch runs several); input actions answer with a screenshot taken after them, screenshot and zoom answer with the image, cursor_position with the pointer. Coordinates are screen pixels from the top-left of the latest screenshot. Start with action "screenshot". Programs started with exec in the background (e.g. "chromium https://example.com &") open on this desktop.',
+            parameters: obj({ ...COMPUTER_ACTION, ...COMPUTER_LOOK }, ['action']),
+            run: async (a, o) => {
+                const look = a.action === 'screenshot' || a.action === 'zoom' || a.action === 'cursor_position';
+                const r = await runComputerActions(async (actions, options) => (await cell()).computer.act({ actions, screenshot: options.screenshot, ...computerImage(a) }, o.signal), [computerAction(a)], { screenshot: !look && a.screenshot !== false }, opts.computer?.beforeAction);
+                const res = r.results[0];
+                const img = res?.image ?? r.screenshot;
+                return {
+                    ok: res?.ok ?? false,
+                    ...(res?.output !== undefined ? { output: res.output } : {}),
+                    ...(res?.error ? { error: res.error.message } : {}),
+                    cursor: r.cursor,
+                    display: r.display,
+                    ...(img ? { screenshot: imageView(img) } : {}),
+                };
+            },
+        },
+        {
+            name: 'computer_batch',
+            permission: 'computer',
+            description: 'Run several actions of the computer tool on the workspace desktop in one call, in order (e.g. click a field, type, press Return). The first failure stops the batch and the rest come back skipped. Answers with each action\'s result (zoom with its image, cursor_position with the pointer) and one screenshot after the last action that ran (screenshot: false skips it).',
+            parameters: obj({
+                actions: { type: 'array', minItems: 1, maxItems: 50, items: obj(COMPUTER_ACTION, ['action']), description: 'Actions with the computer tool\'s parameters, run in order.' },
+                ...COMPUTER_LOOK,
+            }, ['actions']),
+            run: async (a, o) => {
+                const actions = a.actions.map(computerAction);
+                const lastLooks = ['screenshot', 'zoom'].includes(actions.at(-1)?.action ?? '');
+                const r = await runComputerActions(async (batch, options) => (await cell()).computer.act({ actions: batch, screenshot: options.screenshot, ...computerImage(a) }, o.signal), actions, { screenshot: !lastLooks && a.screenshot !== false }, opts.computer?.beforeAction);
+                return {
+                    ok: r.results.every((x) => x.ok),
+                    results: r.results.map((x) => ({
+                        action: x.action,
+                        ok: x.ok,
+                        ...(x.skipped ? { skipped: true } : {}),
+                        ...(x.output !== undefined ? { output: x.output } : {}),
+                        ...(x.error ? { error: x.error.message } : {}),
+                        took_ms: x.took_ms,
+                        ...(x.image ? { image: imageView(x.image) } : {}),
+                    })),
+                    cursor: r.cursor,
+                    display: r.display,
+                    ...(r.screenshot ? { screenshot: imageView(r.screenshot) } : {}),
+                };
+            },
+        },
         {
             name: 'browser_screenshot',
             permission: 'browser',
             description: 'Open a URL in the workspace’s headless browser and return a PNG screenshot (base64).',
             parameters: obj({ url: { type: 'string', minLength: 8, maxLength: 8192 }, width: { type: 'integer', minimum: 100, maximum: 3840 }, height: { type: 'integer', minimum: 100, maximum: 2160 } }, ['url']),
             run: async (a) => {
-                const png = await cell().browser.screenshot({
+                const png = await (await cell()).browser.screenshot({
                     url: String(a.url),
                     ...(typeof a.width === 'number' ? { width: a.width } : {}),
                     ...(typeof a.height === 'number' ? { height: a.height } : {}),
@@ -696,7 +787,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'Open a URL in the workspace’s headless browser and return the rendered page as text or HTML.',
             parameters: obj({ url: { type: 'string', minLength: 8, maxLength: 8192 }, format: { type: 'string', enum: ['text', 'html'] } }, ['url']),
             run: async (a) => {
-                const r = await cell().browser.content({ url: String(a.url), format: a.format === 'html' ? 'html' : 'text' });
+                const r = await (await cell()).browser.content({ url: String(a.url), format: a.format === 'html' ? 'html' : 'text' });
                 const c = clip(r.content, max);
                 return { url: r.url, format: r.format, content: c.text, truncated: r.truncated || c.truncated };
             },

package/dist/tunnel-assets.d.ts

@@ -0,0 +1,10 @@
+export declare const TUNNEL_ASSETS: {
+    readonly x86_64: {
+        readonly file: "linux-amd64.gz";
+        readonly sha256: "e7b8a88b27c36b2605ee9e8182dae7700f816d9058d92bd87d6ae66781303650";
+    };
+    readonly aarch64: {
+        readonly file: "linux-arm64.gz";
+        readonly sha256: "740ce49febb1ab0e614a520d8daff68fa7b4ac32adf18dc93d5ff16b2dc57735";
+    };
+};

package/dist/tunnel-assets.js

@@ -0,0 +1,11 @@
+// Generated by scripts/build-tunnel-helper.py.
+export const TUNNEL_ASSETS = {
+    "x86_64": {
+        "file": "linux-amd64.gz",
+        "sha256": "e7b8a88b27c36b2605ee9e8182dae7700f816d9058d92bd87d6ae66781303650"
+    },
+    "aarch64": {
+        "file": "linux-arm64.gz",
+        "sha256": "740ce49febb1ab0e614a520d8daff68fa7b4ac32adf18dc93d5ff16b2dc57735"
+    }
+};

package/dist/tunnel-packet.d.ts

@@ -0,0 +1,3 @@
+export declare function packetCrc(bytes: Uint8Array): number;
+/** Delimit both ends so a replay discards any truncated preceding packet before decoding. */
+export declare function tunnelPacket(offset: number, bytes: Uint8Array): Buffer;

package/dist/tunnel-packet.js

@@ -0,0 +1,43 @@
+const table = Uint32Array.from({ length: 256 }, (_, value) => {
+    let crc = value;
+    for (let n = 0; n < 8; n++)
+        crc = (crc >>> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
+    return crc >>> 0;
+});
+export function packetCrc(bytes) {
+    let crc = 0xffffffff;
+    for (const b of bytes)
+        crc = (crc >>> 8) ^ table[(crc ^ b) & 255];
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/** Delimit both ends so a replay discards any truncated preceding packet before decoding. */
+export function tunnelPacket(offset, bytes) {
+    if (!Number.isSafeInteger(offset) || offset < 0 || bytes.length > 65536)
+        throw new Error('invalid tunnel packet');
+    const data = Buffer.alloc(bytes.length + 16);
+    data.write('SFRT');
+    data.writeBigUInt64BE(BigInt(offset), 4);
+    data.set(bytes, 12);
+    data.writeUInt32BE(packetCrc(data.subarray(0, -4)), data.length - 4);
+    const result = Buffer.alloc(data.length + Math.ceil(data.length / 254) + 3);
+    let write = 2, codeAt = 1, code = 1;
+    for (const b of data) {
+        if (b === 0) {
+            result[codeAt] = code;
+            codeAt = write++;
+            code = 1;
+        }
+        else {
+            result[write++] = b;
+            code++;
+            if (code === 255) {
+                result[codeAt] = code;
+                codeAt = write++;
+                code = 1;
+            }
+        }
+    }
+    result[codeAt] = code;
+    result[write++] = 0;
+    return result.subarray(0, write);
+}

package/dist/tunnel-pty.d.ts

@@ -0,0 +1,86 @@
+import { WebSocket } from 'undici';
+import type { CellClient, ExecSession, OutputEvent } from './cell.js';
+import type { TunnelTransport } from './tunnels.js';
+/** Native PTY owns the channel; helper acknowledgements own bytes, independently of an HTTP request outcome. */
+export declare class PtyTunnelTransport implements TunnelTransport {
+    #private;
+    readonly maxInputConcurrency = 64;
+    readonly kind: "pty";
+    constructor(cell: CellClient, open?: (url: string, opts: NonNullable<ConstructorParameters<typeof WebSocket>[1]>) => WebSocket);
+    readonly files: {
+        remove: (path: string, opts?: {
+            recursive?: boolean;
+        }) => Promise<void>;
+    };
+    readonly exec: {
+        start: (req: {
+            session_id?: import("./index.js").CellComponents["schemas"]["SessionIdValue"];
+            argv: string[];
+            env?: {
+                [key: string]: string;
+            };
+            cwd?: string;
+            user?: string;
+            stdin_open?: boolean;
+            stdin?: string;
+            timeout_ms?: number;
+            kill_grace_ms?: number;
+            secret_refs?: import("./index.js").CellComponents["schemas"]["SecretRefs"];
+            execution_id?: import("./index.js").CellComponents["schemas"]["ExecutionIdValue"];
+            output_limit_bytes?: number;
+            burst?: "never" | "always";
+            burst_vcpus?: number;
+            burst_memory_mib?: number;
+            resource_hint?: "auto" | "light" | "heavy";
+        }, signal?: AbortSignal | undefined) => Promise<{
+            session_id: string;
+            state: import("./index.js").CellComponents["schemas"]["SessionState"];
+            created: boolean;
+            pid?: number;
+            exit_code?: number | null;
+            term_signal?: number | null;
+            timed_out?: boolean;
+            canceled?: boolean;
+            stdout_size: number;
+            stderr_size: number;
+            created_at?: string;
+            started_at?: string | null;
+            ended_at?: string | null;
+            error?: string;
+            memory_grow?: import("./index.js").CellComponents["schemas"]["MemoryGrow"];
+            burst?: import("./index.js").CellComponents["schemas"]["BurstSummary"];
+        }>;
+        input: (id: string, bytes: string | Uint8Array, opts: {
+            offset: number;
+            close?: boolean;
+            signal?: AbortSignal;
+        }) => Promise<{
+            offset: number;
+            closed: false;
+        }>;
+        output: (id: string, opts?: {
+            stdoutOffset?: number;
+            stderrOffset?: number;
+            follow?: boolean;
+            signal?: AbortSignal;
+        }) => Promise<AsyncGenerator<{
+            type: "output" | "exit" | "heartbeat" | "error";
+            stream?: "stdout" | "stderr";
+            offset?: number;
+            data?: string;
+            session?: import("./index.js").CellComponents["schemas"]["ExecSession"];
+            error?: import("./index.js").CellComponents["schemas"]["ErrorBody"];
+        }, any, any>>;
+        cancel: (id: string) => Promise<ExecSession>;
+    };
+    input(id: string, value: string | Uint8Array, opts: {
+        offset: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        offset: number;
+        closed: false;
+    }>;
+    output(id: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<AsyncGenerator<OutputEvent>>;
+}