@shardflux/cli 0.8.1 → 0.10.0

package/dist/commands.js

@@ -16,7 +16,7 @@ import { updateCheckDisabled } from "./update-check.js";
 import { initTemplateYaml, recipeYaml } from "./template-yaml.js";
 import { BuildTimer, buildTimingJson, buildTimingText, progressLine } from "./timing.js";
 import { timingJson } from "./timing.js";
-import { bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, executionJson, executionSummary, fileInfoText, fileTable, languageTable, json, kv, memoryGrowText, burstText, modeText, operationDetail, pairs, operationTable, packageTable, searchText, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, durableText, suspendRequestText, suspendWhenIdleText, templateDetailText, templateEntryText, templateFileTable, templateTable, usageEstimateText, usageSeriesText, usageText, workspaceDetail, workspaceTable, } from "./format.js";
+import { bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, executionJson, executionSummary, fileInfoText, fileTable, languageTable, json, kv, memoryGrowText, burstText, modeText, operationDetail, pairs, resizeJson, resizeText, operationTable, packageTable, searchText, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, durableText, exposedPortText, portTable, suspendRequestText, suspendWhenIdleText, templateDetailText, templateEntryText, templateFileTable, templateTable, time, usageEstimateText, usageSeriesText, usageText, workspaceDetail, workspaceTable, } from "./format.js";
 const DEFAULT_WAIT_MS = 300_000;
 const MAX_JSON_OUTPUT = 16 * 1024 * 1024;
 const MAX_STDIN = 1024 * 1024;
@@ -67,6 +67,35 @@ function caps(values) {
     return Object.keys(c).length ? c : undefined;
 }
 const ALLOCATION_MODES = ['fixed', 'elastic'];
+/** `--resource-hint` of `workspaces exec` / `exec-start` (0.9.0): the exec's memory hint. */
+const RESOURCE_HINTS = ['auto', 'light', 'heavy'];
+/** The resources of `workspaces resize` (0.9.0): at least one, validated before any request. */
+function resizeParams(values) {
+    const p = {};
+    const memory = str(values.memory);
+    const held = str(values.held);
+    const cpu = str(values.cpu);
+    const disk = str(values.disk);
+    if (values.fixed === true && values.elastic === true)
+        throw new UsageError('--fixed and --elastic cannot be combined');
+    if (held !== undefined && values.fixed === true)
+        throw new UsageError('--held applies to elastic memory (a fixed workspace holds all of its memory)');
+    if (memory !== undefined)
+        p.memoryMib = parsePositiveInt(memory, 'memory', 16_777_216);
+    if (held !== undefined)
+        p.memoryMibHeld = parsePositiveInt(held, 'held', 16_777_216);
+    if (values.fixed === true)
+        p.allocationMode = 'fixed';
+    if (values.elastic === true)
+        p.allocationMode = 'elastic';
+    if (cpu !== undefined)
+        p.cpuMillis = parsePositiveInt(cpu, 'cpu', 1_000_000);
+    if (disk !== undefined)
+        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');
+    return p;
+}
 /**
  * The caps of `workspaces open` and `workspaces fork` (0.8.0): the resource caps plus the memory allocation. Given caps
  * replace the stored ones, so they are sent only when a flag was given.
@@ -75,8 +104,9 @@ function workspaceCaps(values) {
     const c = caps(values) ?? {};
     const mode = oneOf(values, 'allocation-mode', ALLOCATION_MODES);
     const held = str(values['memory-held']);
-    if (held !== undefined && mode !== 'elastic')
-        throw new UsageError('--memory-held needs --allocation-mode elastic (a fixed workspace holds all of --memory-mib)');
+    // Without --allocation-mode the API decides whether the workspace is elastic (requires_elastic when it is not).
+    if (held !== undefined && mode === 'fixed')
+        throw new UsageError('--memory-held applies to elastic memory (a fixed workspace holds all of --memory-mib)');
     if (mode !== undefined)
         c.allocation_mode = mode;
     if (held !== undefined)
@@ -316,6 +346,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();
@@ -566,6 +612,100 @@ function treeRevisionAfter(ws, cell) {
  * save-as-template), refused before any request as the SDK's workspace handle does: NotSupportedForModeError, printed
  * with its hint like the API's own refusal.
  */
+/** `<port>` of the port commands: a TCP port number, 1-65535. */
+export function portArg(text) {
+    if (!/^\d{1,5}$/.test(text) || Number(text) < 1 || Number(text) > 65_535)
+        throw new UsageError(`<port> must be a TCP port number between 1 and 65535 (got "${text}")`);
+    return Number(text);
+}
+const PORT_TOKEN_TTL = { option: 'ttl', min: 60, max: 86_400, range: '1m and 24h' };
+const PORT_LINK_TTL = { option: 'ttl', min: 60, max: 604_800, range: '1m and 7d' };
+/** `--ttl <duration>` of port tokens and links: whole seconds within the API's bounds (undefined: the API's default). */
+export function ttlSeconds(values, b) {
+    const text = str(values[b.option]);
+    if (text === undefined)
+        return undefined;
+    const ms = parseDuration(text, b.option);
+    if (ms % 1000 !== 0)
+        throw new UsageError(`--${b.option} must be a whole number of seconds (e.g. 15m, 2h)`);
+    const seconds = ms / 1000;
+    if (seconds < b.min || seconds > b.max)
+        throw new UsageError(`--${b.option} must be between ${b.range} (got "${text}")`);
+    return seconds;
+}
+/** The workspace of a port command; a file-first workspace has no ports (refused before any port request). */
+async function portWorkspace(ctx, ref) {
+    const ws = await resolveWorkspace(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) {
     if (ws.mode !== 'file_first')
         return;
@@ -683,6 +823,12 @@ export const KEY_HANDLERS = {
         out(ctx, JSON.stringify(ws.labels, null, 2) + '\n', ws.labels);
         return 0;
     },
+    async 'workspaces hint'(ctx, _values, [ref]) {
+        const ws = await resolveWorkspace(ctx, ref);
+        const result = await ws.cell({ wake: null }).wakeHint(ctx.signal);
+        out(ctx, JSON.stringify(result, null, 2) + '\n', result);
+        return 0;
+    },
     async 'workspaces idle'(ctx, values, [ref]) {
         const ws = await resolveWorkspace(ctx, ref);
         const policy = str(values.policy);
@@ -702,8 +848,10 @@ export const KEY_HANDLERS = {
     async 'workspaces exec-start'(ctx, values, [ref, ...argv]) {
         const timeout = str(values.timeout);
         const timeoutMs = timeout === undefined ? undefined : parseDuration(timeout, 'timeout');
-        const ws = await resolveWorkspace(ctx, ref);
+        const resourceHint = oneOf(values, 'resource-hint', RESOURCE_HINTS);
+        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) } : {}),
             ...(timeoutMs !== undefined ? { timeout_ms: timeoutMs } : {}) }, ctx.signal);
         out(ctx, JSON.stringify(session, null, 2) + '\n', session);
@@ -791,6 +939,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);
@@ -808,6 +960,7 @@ export const KEY_HANDLERS = {
             ...(inputs ? { inputs } : {}),
             ...(lifetime ? { lifetime } : {}),
             ...(mode ? { mode } : {}),
+            ...(computerUse !== undefined ? { computerUse } : {}),
             agentLabel: ctx.agentLabel,
             wait: values.wait === false ? false : { timeoutMs, signal: ctx.signal },
         }));
@@ -878,13 +1031,16 @@ export const KEY_HANDLERS = {
         const outputLimit = limitText === undefined ? undefined : parsePositiveInt(limitText, 'output-limit', MAX_OUTPUT_LIMIT);
         const stdinSource = str(values.stdin);
         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') {
             if (burst)
                 throw new UsageError(`--burst applies to processful workspaces only; ${ws.key} is ${modeText(ws.mode)}`);
+            if (resourceHint)
+                throw new UsageError(`--resource-hint applies to processful workspaces only; ${ws.key} is ${modeText(ws.mode)} (each execution runs in a fresh VM)`);
             // An execution: answered when the command ended. The id is ours, so Ctrl-C can name it.
             const id = executionId ?? newExecutionId();
             let r;
@@ -920,6 +1076,7 @@ export const KEY_HANDLERS = {
                 ...(Object.keys(env).length ? { env } : {}),
                 ...(timeoutMs !== undefined ? { timeoutMs } : {}),
                 ...(stdin !== undefined ? { stdin } : {}),
+                ...(resourceHint !== undefined ? { resourceHint } : {}),
                 ...(burst ?? {}),
                 maxOutputBytes: ctx.json ? MAX_JSON_OUTPUT : 0,
                 ...(ctx.json ? {} : { onOutput: (stream, chunk) => void (stream === 'stderr' ? ctx.io.stderr : ctx.io.stdout).write(chunk) }),
@@ -1642,6 +1799,16 @@ export const KEY_HANDLERS = {
         out(ctx, lifecycleText(`Forking ${source.key} into`, res.workspace, op), { operation: op, workspace: res.workspace.data });
         return 0;
     },
+    // Resize (0.9.0+): PATCH /v1/workspaces/{id}/caps through the SDK, which waits until the resize has finished.
+    async 'workspaces resize'(ctx, values, [ref]) {
+        const params = resizeParams(values);
+        const timeoutMs = waitTimeout(values);
+        const ws = await resolveWorkspace(ctx, ref);
+        requireProcessful(ws, 'resize', 'Resize');
+        const r = await waited(ctx, 'the resize continues server side.', () => ws.resize({ ...params, timeoutMs, signal: ctx.signal }));
+        out(ctx, resizeText(ws, r), resizeJson(r));
+        return 0;
+    },
     async 'workspaces sessions'(ctx, _values, [ref]) {
         const ws = await resolveWorkspace(ctx, ref);
         const sessions = [];
@@ -1654,6 +1821,218 @@ export const KEY_HANDLERS = {
         out(ctx, sessions.length ? sessionTable(sessions) : 'No agent sessions (no tool token was issued for this workspace yet).\n', { data: sessions });
         return 0;
     },
+    // ---- inbound ports (0.9.0; contracts §39.3) ----
+    async 'workspaces port expose'(ctx, _values, [ref, portText]) {
+        const port = portArg(portText);
+        const ws = await portWorkspace(ctx, ref);
+        const p = await ws.ports.expose(port);
+        out(ctx, exposedPortText(ws, p), portJson(p));
+        return 0;
+    },
+    async 'workspaces port ls'(ctx, _values, [ref]) {
+        const ws = await portWorkspace(ctx, ref);
+        const ports = await ws.ports.list();
+        out(ctx, portTable(ws, ports), { ports: ports.map(portJson) });
+        return 0;
+    },
+    async 'workspaces port close'(ctx, _values, [ref, portText]) {
+        const port = portArg(portText);
+        const ws = await portWorkspace(ctx, ref);
+        await ws.ports.close(port);
+        out(ctx, `Closed port ${port} of ${ws.key} (${ws.id}): its tokens, links and callback URL no longer work.\n`, { workspace_id: ws.id, port, closed: true });
+        return 0;
+    },
+    async 'workspaces port token'(ctx, values, [ref, portText]) {
+        const port = portArg(portText);
+        const ttl = ttlSeconds(values, PORT_TOKEN_TTL);
+        const ws = await portWorkspace(ctx, ref);
+        const t = await ws.ports.token(port, ttl !== undefined ? { ttlSeconds: ttl } : {});
+        out(ctx, `${t.token}\n`, { token: t.token, expires_at: t.expiresAt, url: t.url });
+        // The token alone on stdout (for $(...)); how to use it on stderr.
+        if (!ctx.json)
+            ctx.io.stderr.write(`Port token for ${t.url}, valid until ${time(t.expiresAt)}: send it as "Authorization: Bearer <token>".\n`);
+        return 0;
+    },
+    async 'workspaces port link'(ctx, values, [ref, portText]) {
+        const port = portArg(portText);
+        const ttl = ttlSeconds(values, PORT_LINK_TTL);
+        const path = str(values.path);
+        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 } : {}) });
+        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`);
+        return 0;
+    },
+    async 'workspaces port callback'(ctx, values, [ref, portText]) {
+        const port = portArg(portText);
+        const ws = await portWorkspace(ctx, ref);
+        if (values.revoke === true) {
+            await ws.ports.revokeCallbackUrl(port);
+            out(ctx, `Revoked the callback URL of port ${port} of ${ws.key} (${ws.id}).\n`, { workspace_id: ws.id, port, revoked: true });
+            return 0;
+        }
+        const c = await ws.ports.createCallbackUrl(port);
+        out(ctx, `${c.url}\n`, { url: c.url, created_at: c.createdAt });
+        if (!ctx.json) {
+            ctx.io.stderr.write(`Callback URL of port ${port} of ${ws.key}: register it plus your own path (e.g. ${c.url}webhooks/github) with your webhook or OAuth provider; a request to it reaches /<path> of the port without a token. It is shown only now; running this again replaces it, --revoke removes it.\n`);
+        }
+        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);
+        if (values.stop === true) {
+            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 s = await ws.computer.stream({ interactive: values.interactive === true, ...(ttl !== undefined ? { ttlSeconds: ttl } : {}) });
+        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;

package/dist/format.d.ts

@@ -1,5 +1,14 @@
-import type { AgentSession, ApiKey, AuditEvent, AuthSessionInfo, BillingCatalog, BillingInvoicePage, BillingSubscription, DataExport, DraftState, ExecutionChange, ExecutionResult, FileInfo, EgressPolicyVersion, Invitation, Member, Organization, Project, ProjectEgressPolicy, Volume, VolumeAttachment, WorkspaceEgressPolicy, FileList, FileSearchResponse, Operation, Secret, SecretAccessEvent, SecretVersion, SpendPolicy, SuspendRequest, TemplateBuild, TemplateDetail, TemplateDiffEntry, TemplateDraft, TemplateFileEntry, TemplateLanguages, TemplatePackagePage, TemplateSettings, TemplateSummary, TemplateVersion, WorkspaceChange, WorkspaceSecretBindings, WorkspaceMemory, WorkspaceView, MemoryGrow, BurstSummary } from '@shardflux/sdk';
+import type { AgentSession, ApiKey, AuditEvent, AuthSessionInfo, BillingCatalog, BillingInvoicePage, BillingSubscription, DataExport, DraftState, ExecutionChange, ExecutionResult, FileInfo, EgressPolicyVersion, Invitation, Member, Organization, Project, ProjectEgressPolicy, Volume, VolumeAttachment, WorkspaceEgressPolicy, FileList, FileSearchResponse, Operation, Secret, SecretAccessEvent, SecretVersion, SpendPolicy, SuspendRequest, TemplateBuild, TemplateDetail, TemplateDiffEntry, TemplateDraft, TemplateFileEntry, TemplateLanguages, TemplatePackagePage, TemplateSettings, TemplateSummary, TemplateVersion, WorkspaceChange, WorkspaceSecretBindings, WorkspaceMemory, WorkspaceView, MemoryGrow, BurstSummary, ResizeResult, ExposePortResult, ExposedPort } from '@shardflux/sdk';
 import type { ErrorInfo } from './errors.js';
+/** A workspace as the port commands name it. */
+interface PortWorkspace {
+    key: string;
+    id: string;
+}
+/** `shard ws port expose` (0.9.0): the URL, and how a request gets in. */
+export declare function exposedPortText(w: PortWorkspace, p: ExposePortResult): string;
+/** `shard ws port ls` (0.9.0). */
+export declare function portTable(w: PortWorkspace, ports: readonly ExposedPort[]): string;
 /** A size for people: `512 B`, `10.0 KiB`, `128.0 MiB`, `1.50 GiB`. */
 export declare function byteSize(n: number): string;
 export declare function json(value: unknown): string;
@@ -35,6 +44,17 @@ export declare function suspendWhenIdleText(w: {
     suspend_request: SuspendRequest | null;
     operation: Operation | null;
 }): string;
+/**
+ * `shard ws resize` (0.9.0): per resource the change and when it applies, e.g.
+ * `memory  2048 → 6144 MiB  now` / `cpu     2000 → 4000 millis  next start (boot vCPUs)`, plus what was clamped or
+ * applied in part (requested above a limit, a partial grow, a shrink the guest did not finish).
+ */
+export declare function resizeText(w: {
+    key: string;
+    id: string;
+}, r: ResizeResult): string;
+/** `shard ws resize --json`: the API's result (only the resources the request named), the stored caps, and the operation when one was waited for. */
+export declare function resizeJson(r: ResizeResult): Record<string, unknown>;
 /** `fixed 4096 MiB`, or `elastic: promised 8192 MiB, held 1024 MiB, plugged +2048 MiB` (plugged: above the held floor now). */
 export declare function memoryText(m: WorkspaceMemory): string;
 /** The grow an exec's start waited for: `delivered 1024 -> 4096 MiB in 175 ms`, `partial 1024 -> 3072 of 4096 MiB in 175 ms`. */

package/dist/format.js

@@ -4,6 +4,18 @@
  * these functions only shape what people read.
  */
 import { durabilityOf, isDurable } from '@shardflux/sdk';
+/** `shard ws port expose` (0.9.0): the URL, and how a request gets in. */
+export function exposedPortText(w, p) {
+    return (`${p.created ? `Exposed port ${p.port} of ${w.key} (${w.id})` : `Port ${p.port} of ${w.key} (${w.id}) is exposed`}: ${p.url}\n` +
+        `Requests need a token (shard ws port token ${w.key} ${p.port}), a browser link (shard ws port link ${w.key} ${p.port}) or the callback URL (shard ws port callback ${w.key} ${p.port}).\n` +
+        `The server in the workspace listens on 0.0.0.0:${p.port}.\n`);
+}
+/** `shard ws port ls` (0.9.0). */
+export function portTable(w, ports) {
+    if (ports.length === 0)
+        return `No ports of ${w.key} (${w.id}) are exposed; expose one with: shard ws port expose ${w.key} <port>\n`;
+    return table(['PORT', 'URL', 'EXPOSED', 'CALLBACK URL'], ports.map((p) => [String(p.port), p.url, time(p.createdAt), p.callback ? `created ${time(p.callback.createdAt)}` : '-']));
+}
 /** A size for people: `512 B`, `10.0 KiB`, `128.0 MiB`, `1.50 GiB`. */
 export function byteSize(n) {
     return n < 1024 ? `${n} B` : n < 1024 ** 2 ? `${(n / 1024).toFixed(1)} KiB` : n < 1024 ** 3 ? `${(n / 1024 ** 2).toFixed(1)} MiB` : `${(n / 1024 ** 3).toFixed(2)} GiB`;
@@ -133,6 +145,55 @@ export function suspendWhenIdleText(w, r) {
     return `A suspend of ${w.key} (${w.id}) is already in progress (operation ${op.id} ${op.kind} ${op.state}); nothing was scheduled.\nwait with: shard operations wait ${op.id}\n`;
 }
 const mib = (n) => (n === null ? '-' : `${n} MiB`);
+const APPLIES_AT = { now: 'now', resume: 'on resume', next_start: 'next start' };
+const LIMIT_TEXT = { plan: 'plan limit', template: 'template limit', host_capacity: 'host capacity', shrink_stalled: 'the guest kept memory in use' };
+/** Why a resource applies later; `suspended` and `stopped` are what `on resume` / `next start` already say. */
+const deferText = (r) => (r === null || r === 'suspended' || r === 'stopped' ? '' : r === 'boot_vcpus' ? ' (boot vCPUs)' : ` (${r.replace(/_/g, ' ')})`);
+/**
+ * `shard ws resize` (0.9.0): per resource the change and when it applies, e.g.
+ * `memory  2048 → 6144 MiB  now` / `cpu     2000 → 4000 millis  next start (boot vCPUs)`, plus what was clamped or
+ * applied in part (requested above a limit, a partial grow, a shrink the guest did not finish).
+ */
+export function resizeText(w, r) {
+    const rows = [];
+    const row = (name, unit, x, extra = '', converged = null) => {
+        const notes = [];
+        if (x.requested !== null && x.target !== null && x.requested !== x.target)
+            notes.push(`requested ${x.requested} ${unit}${x.limit === 'plan' || x.limit === 'template' ? `, ${LIMIT_TEXT[x.limit]}` : ''}`);
+        if (x.applies_at === 'now' && x.applied !== null && x.applied !== x.target)
+            notes.push(`${x.applied} ${unit} applied${x.limit === 'host_capacity' || x.limit === 'shrink_stalled' ? `: ${LIMIT_TEXT[x.limit]}` : ''}`);
+        else if (converged === false)
+            notes.push('not converged');
+        rows.push([name, `${x.previous ?? '-'} → ${x.target ?? '-'} ${unit}${extra}`, `${APPLIES_AT[x.applies_at]}${deferText(x.reason)}${notes.length ? `; ${notes.join('; ')}` : ''}`]);
+    };
+    const m = r.memory;
+    if (m) {
+        const extra = m.allocation_mode === 'elastic' ? ` elastic${m.held_mib !== null ? `, held ${m.held_mib} MiB` : ''}` : '';
+        row('memory', 'MiB', { applies_at: m.applies_at, requested: m.requested_mib, target: m.target_mib, previous: m.previous_mib, applied: m.applied_mib, limit: m.limit_reason, reason: m.reason }, extra, m.converged);
+    }
+    const c = r.cpu;
+    if (c)
+        row('cpu', 'millis', { applies_at: c.applies_at, requested: c.requested_millis, target: c.target_millis, previous: c.previous_millis, applied: c.applied_millis, limit: c.limit_reason, reason: c.reason });
+    const d = r.disk;
+    if (d)
+        row('disk', 'GiB', { applies_at: d.applies_at, requested: d.requested_gib, target: d.target_gib, previous: d.previous_gib, applied: d.applied_gib, limit: d.limit_reason, reason: d.reason });
+    const width = Math.max(0, ...rows.map(([, change]) => change.length));
+    const lines = rows.map(([name, change, when]) => `${name.padEnd(6)}  ${change.padEnd(width)}  ${when}`);
+    return `Resized ${w.key} (${w.id}), ${r.state}:\n${lines.map((l) => `${l}\n`).join('')}`;
+}
+/** `shard ws resize --json`: the API's result (only the resources the request named), the stored caps, and the operation when one was waited for. */
+export function resizeJson(r) {
+    return {
+        workspace_id: r.workspaceId,
+        operation_id: r.operationId,
+        state: r.state,
+        ...(r.memory ? { memory: r.memory } : {}),
+        ...(r.cpu ? { cpu: r.cpu } : {}),
+        ...(r.disk ? { disk: r.disk } : {}),
+        caps: r.caps,
+        ...(r.operation ? { operation: r.operation } : {}),
+    };
+}
 /** `fixed 4096 MiB`, or `elastic: promised 8192 MiB, held 1024 MiB, plugged +2048 MiB` (plugged: above the held floor now). */
 export function memoryText(m) {
     if (m.allocation_mode !== 'elastic')

package/dist/main.js

@@ -104,6 +104,11 @@ function hintFor(info, cred, file) {
         return 'the workspace cannot be woken right now and the call did not run; retry in a few seconds';
     if (reason === 'host_feature_unavailable')
         return hostFeatureHint(info.details?.feature);
+    // Inbound ports (0.9.0): the next step names the command.
+    if (reason === 'port_not_exposed')
+        return `expose it first: shard ws port expose <id|key> ${typeof info.details?.port === 'number' ? info.details.port : '<port>'}`;
+    if (reason === 'port_limit')
+        return 'close a port first (shard ws port ls <id|key>, then shard ws port close <id|key> <port>)';
     // A processful command that could not start (0.5.1): what to change, from the workspace's reason.
     if (info.code === 'conflict' && reason === 'exec_failed_to_start')
         return startFailureHint(typeof info.details?.error === 'string' ? info.details.error : info.message, false);
@@ -312,6 +317,9 @@ const NO_NUDGE_REASONS = new Set([
     'version_mismatch',
     // A write under an immutable path (0.8.0): the hint says where to change it.
     'read_only_path',
+    // Inbound ports (0.9.0): the hint names the command to expose or close a port.
+    'port_not_exposed',
+    'port_limit',
 ]);
 /**
  * Whether a failure ends with the `feedback:` line (0.5.0+): every failure except the expected flow above (feedback

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.8.1",
+  "version": "0.10.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.",
   "license": "Apache-2.0",
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.13.1"
+    "@shardflux/sdk": "^0.15.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",