@shardflux/cli 0.9.0 → 0.11.0

package/dist/commands.js

@@ -5,10 +5,11 @@
  * for yet (GET /v1/operations/{id}, usage summary). The account plane (0.5.0) is in account-commands.ts; handlers.ts
  * joins both tables.
  */
+import { computerStreamCache } from "./computer-stream-cache.js";
 import { randomUUID } from 'node:crypto';
 import { access, readFile, writeFile } from 'node:fs/promises';
 import { basename, dirname, resolve as resolvePath } from 'node:path';
-import { EXECUTION_ID, ExecStartError, FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH, NotSupportedForModeError, SDK_VERSION, ShardfluxApiError, ShardfluxProtocolError, newExecutionId } from '@shardflux/sdk';
+import { EXECUTION_ID, ExecStartError, FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH, NotSupportedForModeError, SDK_VERSION, ShardfluxApiError, ShardfluxProtocolError, newExecutionId, exitCodePosix } from '@shardflux/sdk';
 import { parse as parseYaml } from 'yaml';
 import { CLI_VERSION, SECRET_NAME, UUID, parseDuration, parseEnvPairs, parsePositiveInt } from "./args.js";
 import { ExecSessionRunningError, ExecutionFailedError, ExecutionPendingError, InterruptedError, NotFoundError, UsageError } from "./errors.js";
@@ -94,6 +95,10 @@ function resizeParams(values) {
         p.diskGib = parsePositiveInt(disk, 'disk', 1_000_000);
     if (Object.keys(p).length === 0)
         throw new UsageError('nothing to resize: give --memory, --held, --fixed, --elastic, --cpu or --disk');
+    if (values['at-least'] === true)
+        p.atLeast = true;
+    if (values.wait === false)
+        p.wait = false;
     return p;
 }
 /**
@@ -346,6 +351,22 @@ async function waitOperation(ctx, operationId, timeoutMs) {
  * Runs an SDK call that waits itself (a waited open or lifecycle call). Ctrl-C reports the operation it was waiting
  * for, as the SDK observed it; a held open interrupted before the server answered has none yet (`unnamed`).
  */
+/**
+ * The workspace of `ws exec` / `exec-start`: with `--template <slug>` (0.10.0+) the key is opened first (created on first
+ * use, resumed if suspended; stderr says when it was created), else `<id|key>` must name an existing workspace.
+ */
+async function execTarget(ctx, values, ref) {
+    const template = str(values.template);
+    if (template === undefined)
+        return resolveWorkspace(ctx, ref);
+    const ws = await waited(ctx, 'the open continues server side (run the command again to keep waiting).', () => ctx
+        .cloud()
+        .workspace(ref, { template, agentLabel: ctx.agentLabel, wait: { timeoutMs: DEFAULT_WAIT_MS, signal: ctx.signal } })
+        .open());
+    if (ws.created === true && !ctx.json)
+        ctx.io.stderr.write(`created workspace ${ws.key} (template ${template})\n`);
+    return ws;
+}
 async function waited(ctx, unnamed, call) {
     try {
         return await call();
@@ -477,13 +498,7 @@ function feedbackContext(ctx, values) {
 }
 /** The exit code `shard exec` returns for a finished command. */
 export function execExitCode(r) {
-    if (r.timedOut)
-        return 124;
-    if (typeof r.exitCode === 'number' && r.exitCode >= 0)
-        return Math.min(r.exitCode, 255);
-    if (typeof r.termSignal === 'number' && r.termSignal > 0)
-        return 128 + r.termSignal;
-    return 1;
+    return Math.min(exitCodePosix(r), 255);
 }
 /** The longest cancel grace the workspace applies (it waits 5 s without one). */
 const MAX_CANCEL_GRACE_MS = 60_000;
@@ -623,6 +638,71 @@ async function portWorkspace(ctx, ref) {
     requireProcessful(ws, 'inbound_ports', 'Serving a port');
     return ws;
 }
+/** The workspace of a computer command; a file-first workspace has no desktop (refused before any request). */
+/** --format/--quality of a desktop image (0.10.0+). */
+function imageOpts(values) {
+    const format = str(values.format);
+    if (format !== undefined && format !== 'png' && format !== 'jpeg')
+        throw new UsageError(`--format must be png or jpeg (got "${format}")`);
+    const quality = str(values.quality);
+    return { ...(format !== undefined ? { format } : {}), ...(quality !== undefined ? { quality: parsePositiveInt(quality, 'quality', 100) } : {}) };
+}
+/** --screenshot <file>, --settle and the image options: the screenshot after a computer action or batch. */
+function lookOpts(values) {
+    const shotTo = str(values.screenshot);
+    const settle = str(values.settle);
+    if (settle !== undefined && (!/^\d+$/.test(settle.trim()) || Number(settle) > 10_000))
+        throw new UsageError(`--settle must be 0 to 10000 milliseconds (got "${settle}")`);
+    return { shotTo, req: { screenshot: shotTo !== undefined, ...(settle !== undefined ? { settle_ms: Number(settle) } : {}), ...imageOpts(values) } };
+}
+/** A screen coordinate argument (pixels from the top-left). */
+function pixel(text, name) {
+    if (!/^\d+$/.test(text.trim()))
+        throw new UsageError(`<${name}> must be a whole number of pixels (got "${text}")`);
+    return Number(text);
+}
+/** <x> <y> as a coordinate; neither means at the pointer. */
+function pointAt(x, y) {
+    if (x === undefined)
+        return {};
+    if (y === undefined)
+        throw new UsageError('pass both <x> and <y>, or neither to act at the pointer');
+    return { coordinate: [pixel(x, 'x'), pixel(y, 'y')] };
+}
+const modsOf = (values) => (str(values.mods) !== undefined ? { text: str(values.mods) } : {});
+function secondsOf(text, name) {
+    if (!/^\d+(\.\d+)?$/.test(text.trim()) || Number(text) > 300)
+        throw new UsageError(`${name} must be 0 to 300 seconds (got "${text}")`);
+    return Number(text);
+}
+/** Runs computer actions as one batch and prints one line per action; exit 1 when one failed. */
+async function runComputer(ctx, ref, actions, look) {
+    const ws = await computerWorkspace(ctx, ref);
+    const r = await cellOf(ctx, ws).computer.act({ actions, ...look.req });
+    if (look.shotTo !== undefined && r.screenshot)
+        await writeFile(look.shotTo, Buffer.from(r.screenshot.data, 'base64'));
+    const lines = r.results.map((x, i) => {
+        const state = x.skipped ? 'skipped' : x.ok ? 'ok' : `failed: ${x.error?.message ?? ''}`;
+        return `${String(i + 1).padStart(3)}  ${x.action.padEnd(16)} ${state}${x.output ? `  ${x.output}` : ''}${x.image ? '  (image)' : ''}  ${x.took_ms} ms`;
+    });
+    const tail = `cursor ${r.cursor[0]},${r.cursor[1]} on a ${r.display.width}x${r.display.height} screen${look.shotTo !== undefined && r.screenshot ? `; screenshot written to ${look.shotTo}` : ''}`;
+    out(ctx, `${lines.join('\n')}${lines.length ? '\n' : ''}${tail}\n`, r);
+    return r.results.every((x) => x.ok) ? 0 : 1;
+}
+async function computerWorkspace(ctx, ref) {
+    const ws = await resolveWorkspace(ctx, ref);
+    requireProcessful(ws, 'computer_use', 'Computer use');
+    return ws;
+}
+async function setComputerUse(ctx, ref, enabled) {
+    const ws = await computerWorkspace(ctx, ref);
+    await ws.setComputerUse(enabled);
+    const cu = ws.computerUse;
+    const why = cu.workspace === null ? `following its template (${cu.template ? 'on' : 'off'})` : 'set on the workspace';
+    const note = !cu.available ? ' Its template version cannot run a desktop.' : '';
+    out(ctx, `Computer use is ${cu.enabled ? 'on' : 'off'} for ${ws.key}, ${why}.${note}\n`, cu);
+    return 0;
+}
 /** A port as the API sends it (`--json`). */
 const portJson = (p) => ({ port: p.port, url: p.url, created_at: p.createdAt, callback: p.callback ? { created_at: p.callback.createdAt } : null });
 function requireProcessful(ws, operation, what) {
@@ -768,7 +848,7 @@ export const KEY_HANDLERS = {
         const timeout = str(values.timeout);
         const timeoutMs = timeout === undefined ? undefined : parseDuration(timeout, 'timeout');
         const resourceHint = oneOf(values, 'resource-hint', RESOURCE_HINTS);
-        const ws = await resolveWorkspace(ctx, ref);
+        const ws = await execTarget(ctx, values, ref);
         const session = await cellOf(ctx, ws).exec.start({ argv, stdin_open: values['stdin-open'] === true,
             ...(resourceHint !== undefined ? { resource_hint: resourceHint } : {}),
             ...(str(values['session-id']) ? { session_id: str(values['session-id']) } : {}), ...(str(values.cwd) ? { cwd: str(values.cwd) } : {}),
@@ -779,6 +859,35 @@ export const KEY_HANDLERS = {
             ctx.io.stderr.write(`read it with: shard ws exec-read ${ref} ${session.session_id} --follow; stop it with: shard ws exec-cancel ${ref} ${session.session_id}\n`);
         return 0;
     },
+    async 'workspaces tunnel'(ctx, values, [ref]) {
+        const remote = str(values.remote);
+        const target = str(values.to);
+        if (!remote || !target)
+            throw new UsageError('tunnel requires --remote <port> and --to <host:port>');
+        const remotePort = parsePositiveInt(remote, 'remote');
+        if (remotePort > 65535)
+            throw new UsageError('--remote must be 1..65535');
+        const bindAddress = oneOf(values, 'bind', ['127.0.0.1', '0.0.0.0']);
+        const transport = oneOf(values, 'transport', ['auto', 'pty', 'exec']);
+        const terminated = new AbortController();
+        const onTerm = () => terminated.abort(new Error('terminated'));
+        process.once('SIGTERM', onTerm);
+        try {
+            const ws = await resolveWorkspace(ctx, ref);
+            const tunnel = await ws.tunnels.reverse({ remotePort, target, ...(bindAddress ? { bindAddress } : {}), ...(transport ? { transport } : {}), signal: AbortSignal.any([ctx.signal, terminated.signal]) });
+            out(ctx, `${bindAddress ?? '127.0.0.1'}:${remotePort} in ${ws.key} → ${target} on this machine; Ctrl-C closes the tunnel\n`, { remote_port: remotePort, target, session_id: tunnel.sessionId, transport: tunnel.transport });
+            try {
+                await tunnel.closed;
+            }
+            finally {
+                await tunnel.close();
+            }
+            return terminated.signal.aborted ? 143 : ctx.signal.aborted ? 130 : 0;
+        }
+        finally {
+            process.removeListener('SIGTERM', onTerm);
+        }
+    },
     async 'workspaces exec-read'(ctx, values, [ref, sessionId]) {
         const ws = await resolveWorkspace(ctx, ref);
         const cell = cellOf(ctx, ws);
@@ -823,7 +932,7 @@ export const KEY_HANDLERS = {
         if (s.state === 'starting' || s.state === 'running') {
             throw new ExecSessionRunningError(`Exec session ${s.session_id} is still ${s.state}.`, s, `follow it to its end with: shard ws exec-read ${ref} ${s.session_id} --follow`);
         }
-        const result = { exitCode: s.exit_code ?? null, termSignal: s.term_signal ?? null, timedOut: s.timed_out ?? false };
+        const result = { exitCode: s.exit_code ?? null, termSignal: s.term_signal ?? null, timedOut: s.timed_out ?? false, canceled: s.canceled ?? false };
         if (!ctx.json && result.exitCode === null && !result.timedOut && !(result.termSignal !== null && result.termSignal > 0)) {
             ctx.io.stderr.write(`exec session ${s.session_id} ended ${s.state} without an exit code${s.error ? `: ${s.error}` : ''}\n`);
         }
@@ -850,6 +959,22 @@ export const KEY_HANDLERS = {
         out(ctx, JSON.stringify(ack) + '\n', ack);
         return 0;
     },
+    async 'workspaces retention'(ctx, _values, [ref, policy]) {
+        const ws = await resolveWorkspace(ctx, ref);
+        await ws.setRetention(retentionDays(policy));
+        out(ctx, `${JSON.stringify(ws.retention)}\n`, ws.data);
+        return 0;
+    },
+    async 'projects retention'(ctx, values, [projectId, policy]) {
+        const api = ctx.cloud().projects;
+        if (policy === 'off' && values.labels !== undefined)
+            throw new UsageError('--labels cannot be combined with off');
+        if (policy === undefined && values.labels !== undefined)
+            throw new UsageError('--labels requires a retention policy');
+        const retention = policy === undefined ? await api.getRetention(projectId) : await api.setRetention(projectId, policy === 'off' ? null : { ...openRetentionDays(policy), ...(str(values.labels) === undefined ? {} : { labels: labelMap(str(values.labels)) }) });
+        out(ctx, `${JSON.stringify(retention)}\n`, retention);
+        return 0;
+    },
     async 'workspaces open'(ctx, values, [key]) {
         const template = str(values.template);
         if (!template)
@@ -858,6 +983,10 @@ export const KEY_HANDLERS = {
         const bind = secretNames(strs(values.secret), '--secret');
         const lifetime = oneOf(values, 'lifetime', LIFETIMES);
         const mode = modeFlag(values);
+        const cuText = str(values['computer-use']);
+        if (cuText !== undefined && !['on', 'off', 'inherit'].includes(cuText))
+            throw new UsageError(`--computer-use must be on, off or inherit (got "${cuText}")`);
+        const computerUse = cuText === undefined ? undefined : cuText === 'inherit' ? null : cuText === 'on';
         if (mode === 'file_first' && lifetime === 'session')
             throw new UsageError('a file-first workspace is persistent: --lifetime session is for processful workspaces');
         const inputs = await inputsFrom(ctx, values);
@@ -869,12 +998,14 @@ export const KEY_HANDLERS = {
             key: key,
             template,
             ...(str(values.labels) !== undefined ? { labels: labelMap(str(values.labels)) } : {}),
+            ...(str(values['delete-after-idle']) !== undefined ? { retention: openRetentionDays(str(values['delete-after-idle'])) } : {}),
             ...(str(values['idle-policy']) ? { idlePolicy: str(values['idle-policy']) } : {}),
             ...(c ? { caps: c } : {}),
             ...(bind.length ? { secrets: bind } : {}),
             ...(inputs ? { inputs } : {}),
             ...(lifetime ? { lifetime } : {}),
             ...(mode ? { mode } : {}),
+            ...(computerUse !== undefined ? { computerUse } : {}),
             agentLabel: ctx.agentLabel,
             wait: values.wait === false ? false : { timeoutMs, signal: ctx.signal },
         }));
@@ -947,7 +1078,7 @@ export const KEY_HANDLERS = {
         const burst = burstOptions(values, stdinSource !== undefined);
         const resourceHint = oneOf(values, 'resource-hint', RESOURCE_HINTS);
         const stdin = stdinSource === undefined ? undefined : await readInput(ctx, stdinSource, MAX_STDIN, '--stdin');
-        const ws = await resolveWorkspace(ctx, ref);
+        const ws = await execTarget(ctx, values, ref);
         const cell = cellOf(ctx, ws);
         const cwd = str(values.cwd);
         if (ws.mode === 'file_first') {
@@ -1215,6 +1346,12 @@ export const KEY_HANDLERS = {
     async 'workspaces close'(ctx, values, [ref]) {
         return lifecycle(ctx, values, ref, 'Closing', (ws, o) => ctx.cloud().workspaces.close(ws.id, o));
     },
+    async 'workspaces upgrade'(ctx, values, [ref]) {
+        const at = str(values.at) ?? 'now';
+        if (at !== 'now' && at !== 'next-resume')
+            throw new UsageError('--at must be now or next-resume');
+        return lifecycle(ctx, values, ref, at === 'now' ? 'Upgrading' : 'Scheduling upgrade for', (ws, o) => ctx.cloud().workspaces.upgrade(ws.id, { ...o, at: at === 'next-resume' ? 'next_resume' : 'now' }), ['upgrade', 'Upgrade']);
+    },
     async 'workspaces reset'(ctx, values, [ref]) {
         if (values.yes !== true)
             throw new UsageError('refusing to reset without --yes (reset wipes every change in the workspace and restarts it on its template)');
@@ -1774,7 +1911,7 @@ export const KEY_HANDLERS = {
         if (path !== undefined && !path.startsWith('/'))
             throw new UsageError(`--path must start with / (got "${path}")`);
         const ws = await portWorkspace(ctx, ref);
-        const l = await ws.ports.link(port, { ...(ttl !== undefined ? { ttlSeconds: ttl } : {}), ...(path !== undefined ? { path } : {}) });
+        const l = await ws.ports.link(port, { ...(values['embed-origin'] !== undefined ? { embed: { origins: values['embed-origin'] } } : {}), ...(ttl !== undefined ? { ttlSeconds: ttl } : {}), ...(path !== undefined ? { path } : {}) });
         out(ctx, `${l.url}\n`, { url: l.url, expires_at: l.expiresAt });
         if (!ctx.json)
             ctx.io.stderr.write(`Opens port ${port} of ${ws.key} in a browser until ${time(l.expiresAt)}; anyone with the link can open it until then.\n`);
@@ -1795,6 +1932,165 @@ export const KEY_HANDLERS = {
         }
         return 0;
     },
+    // ---- computer use (0.10.0; contracts §45) ----
+    async 'workspaces computer status'(ctx, _values, [ref]) {
+        const ws = await computerWorkspace(ctx, ref);
+        const st = await cellOf(ctx, ws).computer.status();
+        const views = [st.streams.view ? 'view only' : null, st.streams.interactive ? 'interactive' : null].filter(Boolean);
+        out(ctx, st.running
+            ? `Desktop of ${ws.key}: running ${st.width}x${st.height} since ${time(st.started_at ?? '')}; viewers: ${views.length ? views.join(', ') : 'none'}.\n`
+            : `Desktop of ${ws.key}: not running (the first computer call starts it).\n`, st);
+        return 0;
+    },
+    async 'workspaces computer screenshot'(ctx, values, [ref]) {
+        const img = imageOpts(values);
+        const dest = str(values.out) ?? (img.format === 'jpeg' ? 'screenshot.jpg' : 'screenshot.png');
+        const ws = await computerWorkspace(ctx, ref);
+        const r = await cellOf(ctx, ws).computer.act({ actions: [], screenshot: true, ...img });
+        if (!r.screenshot)
+            throw new ShardfluxProtocolError('the desktop returned no screenshot', 200, 'cell');
+        const bytes = Buffer.from(r.screenshot.data, 'base64');
+        await writeFile(dest, bytes);
+        out(ctx, `Wrote a ${r.screenshot.width}x${r.screenshot.height} screenshot of ${ws.key} to ${dest}.\n`, {
+            out: dest, format: r.screenshot.format, width: r.screenshot.width, height: r.screenshot.height, bytes: bytes.length,
+        });
+        return 0;
+    },
+    async 'workspaces computer act'(ctx, values, [ref, source]) {
+        const text = source === '-' ? Buffer.from(await readInput(ctx, '-', 1 << 20, 'actions')).toString('utf8') : source;
+        let actions;
+        try {
+            actions = JSON.parse(text);
+        }
+        catch {
+            throw new UsageError('<actions-json> must be a JSON array of actions, e.g. [{"action":"screenshot"}]');
+        }
+        if (!Array.isArray(actions))
+            throw new UsageError('<actions-json> must be a JSON array of actions');
+        return runComputer(ctx, ref, actions, lookOpts(values));
+    },
+    async 'workspaces computer click'(ctx, values, [ref, x, y]) {
+        const button = str(values.button) ?? 'left';
+        if (button !== 'left' && button !== 'right' && button !== 'middle')
+            throw new UsageError(`--button must be left, right or middle (got "${button}")`);
+        const count = str(values.count) !== undefined ? parsePositiveInt(str(values.count), 'count', 3) : 1;
+        if (count > 1 && button !== 'left')
+            throw new UsageError('--count 2 or 3 is a double or triple click of the left button');
+        const action = button === 'right' ? 'right_click' : button === 'middle' ? 'middle_click' : ['left_click', 'double_click', 'triple_click'][count - 1];
+        return runComputer(ctx, ref, [{ action, ...pointAt(x, y), ...modsOf(values) }], lookOpts(values));
+    },
+    async 'workspaces computer type'(ctx, values, [ref, source]) {
+        const text = source === '-' ? Buffer.from(await readInput(ctx, '-', 256 << 10, 'text')).toString('utf8') : source;
+        if (text === '')
+            throw new UsageError('<text> must not be empty');
+        return runComputer(ctx, ref, [{ action: 'type', text }], lookOpts(values));
+    },
+    async 'workspaces computer key'(ctx, values, [ref, keys]) {
+        const repeat = str(values.repeat) !== undefined ? parsePositiveInt(str(values.repeat), 'repeat', 100) : undefined;
+        return runComputer(ctx, ref, [{ action: 'key', text: keys, ...(repeat !== undefined ? { repeat } : {}) }], lookOpts(values));
+    },
+    async 'workspaces computer scroll'(ctx, values, [ref, direction, x, y]) {
+        if (direction !== 'up' && direction !== 'down' && direction !== 'left' && direction !== 'right') {
+            throw new UsageError(`expected up, down, left or right (got "${direction}")`);
+        }
+        const amount = str(values.amount) !== undefined ? parsePositiveInt(str(values.amount), 'amount', 100) : 3;
+        return runComputer(ctx, ref, [{ action: 'scroll', scroll_direction: direction, scroll_amount: amount, ...pointAt(x, y), ...modsOf(values) }], lookOpts(values));
+    },
+    async 'workspaces computer move'(ctx, values, [ref, x, y]) {
+        return runComputer(ctx, ref, [{ action: 'mouse_move', ...pointAt(x, y) }], lookOpts(values));
+    },
+    async 'workspaces computer drag'(ctx, values, [ref, x1, y1, x2, y2]) {
+        const start = pointAt(x1, y1).coordinate;
+        return runComputer(ctx, ref, [{ action: 'left_click_drag', start_coordinate: start, ...pointAt(x2, y2), ...modsOf(values) }], lookOpts(values));
+    },
+    async 'workspaces computer mouse-down'(ctx, values, [ref]) {
+        return runComputer(ctx, ref, [{ action: 'left_mouse_down' }], lookOpts(values));
+    },
+    async 'workspaces computer mouse-up'(ctx, values, [ref]) {
+        return runComputer(ctx, ref, [{ action: 'left_mouse_up' }], lookOpts(values));
+    },
+    async 'workspaces computer hold-key'(ctx, values, [ref, keys, seconds]) {
+        return runComputer(ctx, ref, [{ action: 'hold_key', text: keys, duration: secondsOf(seconds, '<seconds>') }], lookOpts(values));
+    },
+    async 'workspaces computer wait'(ctx, values, [ref, seconds]) {
+        return runComputer(ctx, ref, [{ action: 'wait', duration: secondsOf(seconds, '<seconds>') }], lookOpts(values));
+    },
+    async 'workspaces computer zoom'(ctx, values, [ref, x0, y0, x1, y1]) {
+        const img = imageOpts(values);
+        const region = [pixel(x0, 'x0'), pixel(y0, 'y0'), pixel(x1, 'x1'), pixel(y1, 'y1')];
+        const dest = str(values.out) ?? (img.format === 'jpeg' ? 'zoom.jpg' : 'zoom.png');
+        const ws = await computerWorkspace(ctx, ref);
+        const r = await cellOf(ctx, ws).computer.act({ actions: [{ action: 'zoom', region }], ...img });
+        const res = r.results[0];
+        if (!res?.ok || !res.image) {
+            out(ctx, `zoom failed: ${res?.error?.message ?? 'no image'}\n`, r);
+            return 1;
+        }
+        const bytes = Buffer.from(res.image.data, 'base64');
+        await writeFile(dest, bytes);
+        out(ctx, `Wrote a ${res.image.width}x${res.image.height} view of [${region.join(', ')}] on ${ws.key} to ${dest}.\n`, {
+            out: dest, format: res.image.format, width: res.image.width, height: res.image.height, bytes: bytes.length,
+        });
+        return 0;
+    },
+    async 'workspaces computer cursor'(ctx, _values, [ref]) {
+        const ws = await computerWorkspace(ctx, ref);
+        const r = await cellOf(ctx, ws).computer.act({ actions: [{ action: 'cursor_position' }] });
+        out(ctx, `${r.cursor[0]} ${r.cursor[1]}\n`, { x: r.cursor[0], y: r.cursor[1], display: r.display });
+        return 0;
+    },
+    async 'workspaces computer start'(ctx, values, [ref]) {
+        const width = str(values.width) !== undefined ? parsePositiveInt(str(values.width), '--width') : undefined;
+        const height = str(values.height) !== undefined ? parsePositiveInt(str(values.height), '--height') : undefined;
+        const ws = await computerWorkspace(ctx, ref);
+        const st = await cellOf(ctx, ws).computer.start({ ...(width !== undefined ? { width } : {}), ...(height !== undefined ? { height } : {}) });
+        out(ctx, `Desktop of ${ws.key}: running ${st.width}x${st.height}.\n`, st);
+        return 0;
+    },
+    async 'workspaces computer stop'(ctx, _values, [ref]) {
+        const ws = await computerWorkspace(ctx, ref);
+        await cellOf(ctx, ws).computer.stop();
+        out(ctx, `Stopped the desktop of ${ws.key}.\n`, { workspace_id: ws.id, stopped: true });
+        return 0;
+    },
+    async 'workspaces computer stream'(ctx, values, [ref]) {
+        const ws = await computerWorkspace(ctx, ref);
+        const credential = ctx.io.env.SHARDFLUX_API_KEY?.trim() ?? ctx.store.profile(ctx.apiUrl).api_key?.token ?? '';
+        const cache = computerStreamCache(ctx.io.env, ctx.apiUrl, ws.id, credential);
+        if (values.stop === true) {
+            cache.clear();
+            await ws.computer.stopStream();
+            out(ctx, `Ended every view of the desktop of ${ws.key}.\n`, { workspace_id: ws.id, stopped: true });
+            return 0;
+        }
+        const ttl = ttlSeconds(values, PORT_LINK_TTL);
+        const streamOptions = { fresh: values.fresh === true, interactive: values.interactive === true,
+            ...(values['embed-origin'] !== undefined ? { embed: { origins: values['embed-origin'] } } : {}),
+            ...(ttl !== undefined ? { ttlSeconds: ttl } : {}) };
+        const s = (values.fresh !== true ? cache.get(values.interactive === true, streamOptions) : undefined) ?? await ws.computer.stream(streamOptions);
+        cache.set(s, streamOptions);
+        out(ctx, `${s.url}\n`, { url: s.url, expires_at: s.expiresAt, port: s.port, interactive: s.interactive });
+        if (!ctx.json) {
+            ctx.io.stderr.write(`${s.interactive ? 'Uses' : 'Watches'} the desktop of ${ws.key} until ${time(s.expiresAt)}; anyone with the link can open it until then.\n`);
+        }
+        return 0;
+    },
+    async 'workspaces computer enable'(ctx, _values, [ref]) {
+        return setComputerUse(ctx, ref, true);
+    },
+    async 'workspaces computer disable'(ctx, _values, [ref]) {
+        return setComputerUse(ctx, ref, false);
+    },
+    async 'workspaces computer inherit'(ctx, _values, [ref]) {
+        return setComputerUse(ctx, ref, null);
+    },
+    async 'templates computer-use'(ctx, _values, [slug, state]) {
+        if (state !== 'on' && state !== 'off')
+            throw new UsageError(`expected on or off (got "${state}")`);
+        const r = await ctx.cloud().templates.setComputerUse(slug, state === 'on');
+        out(ctx, `Computer use is ${r.enabled ? 'on' : 'off'} for the workspaces of ${slug} (a workspace's own setting wins).\n`, r);
+        return 0;
+    },
     async 'workspaces secrets'(ctx, values, [ref]) {
         const set = secretNames(strs(values.set), '--set');
         const clear = values.clear === true;
@@ -2096,3 +2392,18 @@ function labelMap(value) {
         throw new UsageError('labels must be a JSON object of strings');
     return parsed;
 }
+function retentionDays(value) {
+    if (value === 'off')
+        return null;
+    const match = /^([0-9]+)d$/.exec(value);
+    const days = match ? Number(match[1]) : NaN;
+    if (!Number.isInteger(days) || days < 1 || days > 3650)
+        throw new UsageError('retention must be 1d..3650d or off');
+    return { delete_after_idle_days: days };
+}
+function openRetentionDays(value) {
+    const policy = retentionDays(value);
+    if (policy === null)
+        throw new UsageError('--delete-after-idle requires 1d..3650d; clear an own policy with shard ws retention KEY off');
+    return policy;
+}

package/dist/computer-stream-cache.d.ts

@@ -0,0 +1,8 @@
+import type { ComputerStream, ComputerStreamOptions } from '@shardflux/sdk';
+type StreamOptions = Pick<ComputerStreamOptions, 'embed' | 'ttlSeconds'>;
+export declare function computerStreamCache(env: Record<string, string | undefined>, apiUrl: string, workspaceId: string, credential: string): {
+    get(interactive: boolean, options?: StreamOptions): ComputerStream | undefined;
+    set(link: ComputerStream, options?: StreamOptions): void;
+    clear(): void;
+};
+export {};

package/dist/computer-stream-cache.js

@@ -0,0 +1,34 @@
+/** Viewer links survive CLI invocations in the private config directory, scoped to API/workspace/credential. */
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { configDir } from "./credentials.js";
+export function computerStreamCache(env, apiUrl, workspaceId, credential) {
+    const digest = (text) => createHash('sha256').update(text).digest('hex');
+    const dir = join(configDir(env), 'computer-streams', digest(`${apiUrl}\0${workspaceId}`));
+    const path = (interactive, options = {}) => join(dir, `${digest(credential)}-${interactive ? 'interactive' : 'view'}-${digest(JSON.stringify({ ttlSeconds: options.ttlSeconds, embed: options.embed }))}.json`);
+    return {
+        get(interactive, options = {}) {
+            try {
+                const link = JSON.parse(readFileSync(path(interactive, options), 'utf8'));
+                if (typeof link.url === 'string' && typeof link.expiresAt === 'string' && Number.isInteger(link.port) && link.interactive === interactive && Date.parse(link.expiresAt) - Date.now() > 60_000)
+                    return link;
+            }
+            catch { /* cache misses are ordinary; mint through the SDK */ }
+            return undefined;
+        },
+        set(link, options = {}) {
+            const temp = `${path(link.interactive, options)}.${randomUUID()}.tmp`;
+            try {
+                mkdirSync(dir, { recursive: true, mode: 0o700 });
+                writeFileSync(temp, JSON.stringify(link), { mode: 0o600, flag: 'wx' });
+                renameSync(temp, path(link.interactive, options));
+            }
+            catch { /* caching is optional; the minted link remains usable */ }
+            finally {
+                rmSync(temp, { force: true });
+            }
+        },
+        clear() { rmSync(dir, { recursive: true, force: true }); },
+    };
+}

package/dist/format.js

@@ -155,6 +155,9 @@ const deferText = (r) => (r === null || r === 'suspended' || r === 'stopped' ? '
  * applied in part (requested above a limit, a partial grow, a shrink the guest did not finish).
  */
 export function resizeText(w, r) {
+    if (r.operation && !['succeeded', 'failed', 'canceled'].includes(r.operation.state)) {
+        return `Resize accepted for ${w.key} (${w.id}); operation ${r.operation.id} is ${r.operation.state}.\n`;
+    }
     const rows = [];
     const row = (name, unit, x, extra = '', converged = null) => {
         const notes = [];

package/dist/main.js

@@ -415,7 +415,7 @@ export async function run(argv, io, opts = {}) {
     let ctx;
     let updates = null;
     try {
-        const apiUrl = resolveApiUrl(parsed.global.apiUrl, io.env.SHARDFLUX_API_URL);
+        const apiUrl = resolveApiUrl(parsed.global.apiUrl, io.env.SHARDFLUX_API_URL ?? io.env.SHARDFLUX_BASE_URL);
         apiUrlForCleanup = apiUrl;
         const agentLabel = parsed.global.agentLabel ?? io.env.SHARDFLUX_AGENT_LABEL ?? 'cli';
         if (!isLabel(agentLabel))
@@ -609,7 +609,8 @@ export async function run(argv, io, opts = {}) {
     const running = handler(ctx, parsed.values, parsed.positionals).then((code) => ({ code }), (err) => ({ err }));
     // On Ctrl-C give the command a moment to clean up (exec sends a cancel), then stop regardless.
     const interrupted = new Promise((resolve) => {
-        const onAbort = () => setTimeout(() => resolve({ interrupted: true }), 4_000).unref();
+        const cleanupMs = parsed.command.path.join(' ') === 'workspaces tunnel' ? 90_000 : 4_000;
+        const onAbort = () => setTimeout(() => resolve({ interrupted: true }), cleanupMs).unref();
         if (signal.aborted)
             onAbort();
         else

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "type": "module",
-  "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork persistent agent workspaces.",
+  "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork serverless agent workspaces.",
   "license": "Apache-2.0",
   "homepage": "https://shardflux.dev",
   "bugs": {
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.14.0"
+    "@shardflux/sdk": "^0.16.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",