@shardflux/cli 0.14.3 → 0.14.5

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.14.5
+
+- An agent terminal no longer keeps its workspace awake. `shard ./` and `shard agents open` attach passively: while the agent waits, its workspace parks and suspends under the open terminal. Once it has gone to sleep, the terminal shows `asleep. Type to wake it.`, and your next keystroke wakes it and reaches the agent. A dropped connection reattaches without waking the workspace.
+- Requires `@shardflux/sdk` 0.20.0: `shard ws tunnel` and the device bridge carry a reset on either side as a reset (`ECONNRESET`), never as a clean end of stream.
+
+## 0.14.4
+
+- `shard <path> --codex` and `--claude` choose the agent like `shard <path> codex` and `claude`. An unknown option or app on `shard <path>` names the right form, e.g. `shard ./ codex`.
+
 ## 0.14.3
 
 - Poll device requests and deliver approvals independently of transcript mirroring, so a slow or failed copy cannot delay file-push approvals. Isolate mirror failures by conversation, retry with exponential backoff, and log each failure once per conversation revision with the affected entry name.

package/README.md

@@ -33,7 +33,7 @@ shard ws tunnel customer-42/main --remote 8081 --to localhost:8081
 ```
 
 Commands in the workspace can then call `http://127.0.0.1:8081`. The target is dialed on the machine running
-`shard`. Ctrl-C closes the sockets and guest process. `--bind 0.0.0.0` selects all guest interfaces; loopback is the
+`shard`. Half-close and resets pass through: a reset on either side reaches the other as `ECONNRESET` (0.14.5+). Ctrl-C closes the sockets and guest process. `--bind 0.0.0.0` selects all guest interfaces; loopback is the
 default. An open tunnel keeps the workspace awake, and persistent workspaces preserve it across explicit suspend/resume.
 
 The tunnel selects a streaming transport automatically when `pty` permission is granted. Choose `transport: 'pty'` or `transport: 'exec'` in the SDK, or `--transport pty|exec` in the CLI, to select it explicitly. The handle reports `transport`.
@@ -1163,7 +1163,7 @@ as ordinary files. Browser logins and Claude/Codex config belong to the machine.
 your agent uses the same save/rollback commands there. Every agent starts from both. Save or roll back with `shard machine save|rollback` and
 `shard template save|rollback`; changed files reach running agents live, software at the next start.
 `shard machine save --wait` and `shard template save --wait` return once the new version is ready (0.13.3+).
-`shard ./ codex` (or `claude`) starts that agent directly; `shard agents targets <project>/<agent>` lists each
+`shard ./ codex` (or `claude`; `--codex` and `--claude` also work, 0.14.4+) starts that agent directly; `shard agents targets <project>/<agent>` lists each
 connection it configured and the file it is in (0.13.3+).
 
 `shard agents fork` or `f` in the command center copies the whole running state into an independent workspace and

package/dist/agent-commands.js

@@ -5,7 +5,7 @@ import { createHash } from 'node:crypto';
 import { ShardfluxApiError } from '@shardflux/sdk';
 import { UsageError } from "./errors.js";
 import { AgentStateStore } from "./agent-state.js";
-import { attachTerminal, cellConnector } from "./agent-terminal.js";
+import { attachTerminal, cellConnector, workspaceAsleep } from "./agent-terminal.js";
 import { prepareProjectTemplate } from "./project-template-setup.js";
 import { projectIdentity, projectLabels } from "./project-identity.js";
 import { ensureProjectGit } from "./project-git.js";
@@ -120,8 +120,9 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
         ctx.io.stderr.write(`Shardflux · ${ws.key}\nDetach: Ctrl-] then d\n`);
         const attached = attachTerminal({
             ...(credentialFill ? { credentialPrompts: (ask, signal) => watchCredentialPrompts(ctx, ws, ask, signal) } : {}),
-            io: ctx.io, signal: ctx.signal, connect: cellConnector(cell, session.session_id),
+            io: ctx.io, signal: ctx.signal, connect: cellConnector(cell, session.session_id, { passive: true }),
             wake: (signal) => ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal }),
+            asleep: () => workspaceAsleep(ws),
             invalidate: () => cell.tokens.invalidate(),
             sleep: (ms, signal) => new Promise((resolve) => {
                 const done = () => { clearTimeout(timer); signal.removeEventListener('abort', done); resolve(); };

package/dist/agent-terminal.d.ts

@@ -1,4 +1,3 @@
-import { PtyConnection } from '@shardflux/sdk';
 import type { CellClient, PtyServerMessage } from '@shardflux/sdk';
 import type { Io } from './commands.js';
 export interface TerminalConnection {
@@ -7,6 +6,8 @@ export interface TerminalConnection {
     messages(): AsyncIterable<PtyServerMessage>;
     close(): Promise<void>;
 }
+/** The workspace (or the VM under this terminal) is asleep: the user's next keystroke wakes it. */
+export declare function sleepingAttach(error: unknown): boolean;
 export declare function retryableAttach(error: unknown): boolean;
 /** Offsets address bytes, including escape sequences and UTF-8 split across frames. */
 export declare class PtyOutputCursor {
@@ -19,6 +20,12 @@ export interface AttachOptions {
     signal: AbortSignal;
     connect(offset: number, signal: AbortSignal): Promise<TerminalConnection>;
     wake(signal: AbortSignal): Promise<unknown>;
+    /**
+     * Whether the workspace went to sleep under this terminal (suspended or suspending), read without waking it. With
+     * it, a dropped terminal never wakes the workspace by itself: asleep, it waits until its user types; otherwise it
+     * reattaches, and the host wakes a parked VM for it. Without it, every reattach wakes the workspace first.
+     */
+    asleep?(signal: AbortSignal): Promise<boolean>;
     invalidate(): void;
     sleep(ms: number, signal: AbortSignal): Promise<void>;
     dimensions?: () => {
@@ -32,4 +39,19 @@ export interface AttachOptions {
 }
 /** Detaching closes only this attachment; the workspace PTY and agent keep running. */
 export declare function attachTerminal(options: AttachOptions): Promise<number>;
-export declare function cellConnector(cell: CellClient, sessionId: string): (offset: number, signal: AbortSignal) => Promise<PtyConnection>;
+/** Reads the workspace without waking it: suspended, or on its way there. */
+export declare function workspaceAsleep(ws: {
+    refresh(): Promise<unknown>;
+    state: string;
+    desiredState: string;
+}): Promise<boolean>;
+/** A host without passive attach refuses it before any output; the terminal then attaches as an ordinary one. */
+export declare function passiveUnavailable(error: unknown): boolean;
+/**
+ * Attaches a PTY. `passive` (the agent terminal, 0.14.4+) holds the workspace only while bytes move through it, so a
+ * waiting agent's workspace parks and suspends under an open terminal, and input still wakes it; on a host without
+ * passive attach the next attach is an ordinary one. An ordinary attach wakes a parked workspace and holds it.
+ */
+export declare function cellConnector(cell: CellClient, sessionId: string, opts?: {
+    passive?: boolean;
+}): (offset: number, signal: AbortSignal) => Promise<TerminalConnection>;

package/dist/agent-terminal.js

@@ -1,6 +1,11 @@
 import { StringDecoder } from 'node:string_decoder';
 import { PtyConnection, ShardfluxApiError, ShardfluxProtocolError, exitCodePosix } from '@shardflux/sdk';
 import { UsageError } from "./errors.js";
+/** The workspace (or the VM under this terminal) is asleep: the user's next keystroke wakes it. */
+export function sleepingAttach(error) {
+    return error instanceof ShardfluxApiError && error.code === 'workspace_not_running';
+}
+const ASLEEP_NOTICE = '\r\n\x1b[2m· asleep. Type to wake it.\x1b[0m\r\n';
 export function retryableAttach(error) {
     if (error instanceof ShardfluxProtocolError && /invalid|byte gap|omitted/.test(error.message))
         return false;
@@ -50,6 +55,7 @@ export async function attachTerminal(options) {
         const size = dimensions();
         connection?.resize(Math.min(1000, Math.max(1, size.rows)), Math.min(1000, Math.max(1, size.cols)));
     };
+    let typed;
     const send = (bytes) => {
         if (!bytes.length)
             return;
@@ -75,10 +81,21 @@ export async function attachTerminal(options) {
                 inputFailure = new UsageError('terminal input exceeded the reconnect buffer');
                 controller.abort(inputFailure);
             }
-            else
+            else {
                 pending.push(bytes);
+                typed?.();
+            }
         }
     };
+    const untilTyped = () => new Promise((resolve) => {
+        if (pending.length || signal.aborted) {
+            resolve();
+            return;
+        }
+        const done = () => { typed = undefined; signal.removeEventListener('abort', done); resolve(); };
+        typed = done;
+        signal.addEventListener('abort', done, { once: true });
+    });
     const data = (value) => {
         const bytes = typeof value === 'string' ? Buffer.from(value) : value;
         if (promptAnswer) {
@@ -147,13 +164,25 @@ export async function attachTerminal(options) {
         controller.abort();
     } });
     let reconnects = 0;
+    let asleep = false;
     try {
         while (!signal.aborted) {
             try {
-                if (reconnects) {
+                if (asleep) {
+                    // Asleep: an open terminal is not a reason to wake the workspace. The first keystroke is.
+                    asleep = false;
+                    io.stderr.write(ASLEEP_NOTICE);
+                    await untilTyped();
+                    if (signal.aborted)
+                        break;
                     options.invalidate();
                     await options.wake(signal);
                 }
+                else if (reconnects) {
+                    options.invalidate();
+                    if (!options.asleep)
+                        await options.wake(signal);
+                }
                 connection = await options.connect(cursor.offset, signal);
                 acceptingInput = true;
                 resize();
@@ -179,6 +208,10 @@ export async function attachTerminal(options) {
                     break;
                 if (!retryableAttach(error))
                     throw error;
+                if (options.asleep && (sleepingAttach(error) || await options.asleep(signal).catch(() => false))) {
+                    asleep = true;
+                    continue;
+                }
             }
             finally {
                 const previous = connection;
@@ -204,6 +237,51 @@ export async function attachTerminal(options) {
         stdin.pause?.();
     }
 }
-export function cellConnector(cell, sessionId) {
-    return (offset, signal) => PtyConnection.attach(cell, sessionId, offset, signal);
+/** Reads the workspace without waking it: suspended, or on its way there. */
+export async function workspaceAsleep(ws) {
+    await ws.refresh();
+    return ws.desiredState === 'suspended' || ws.state === 'suspending' || ws.state === 'suspended';
+}
+/** A host without passive attach refuses it before any output; the terminal then attaches as an ordinary one. */
+export function passiveUnavailable(error) {
+    return error instanceof ShardfluxApiError && error.reason === 'host_feature_unavailable' && error.details?.feature === 'passive_pty';
+}
+/**
+ * Attaches a PTY. `passive` (the agent terminal, 0.14.4+) holds the workspace only while bytes move through it, so a
+ * waiting agent's workspace parks and suspends under an open terminal, and input still wakes it; on a host without
+ * passive attach the next attach is an ordinary one. An ordinary attach wakes a parked workspace and holds it.
+ */
+export function cellConnector(cell, sessionId, opts = {}) {
+    let passive = opts.passive === true;
+    const fallback = (error) => {
+        if (!passive || !passiveUnavailable(error))
+            return error;
+        passive = false;
+        return new ShardfluxProtocolError('agent terminal host has no passive attach', 0, 'cell');
+    };
+    return async (offset, signal) => {
+        const { url, token } = await cell.pty.attachUrl(sessionId, offset);
+        const target = new URL(url);
+        if (passive)
+            target.searchParams.set('passive', 'true');
+        const connection = new PtyConnection(target.toString(), token, signal);
+        try {
+            await connection.ready;
+        }
+        catch (error) {
+            await connection.close();
+            throw fallback(error);
+        }
+        return {
+            input: (bytes) => connection.input(bytes), resize: (rows, cols) => connection.resize(rows, cols), close: () => connection.close(),
+            async *messages() {
+                try {
+                    yield* connection.messages();
+                }
+                catch (error) {
+                    throw fallback(error);
+                }
+            },
+        };
+    };
 }

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.14.3";
+export declare const CLI_VERSION = "0.14.5";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

package/dist/args.js

@@ -12,7 +12,7 @@
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.14.3';
+export const CLI_VERSION = '0.14.5';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -1173,8 +1173,19 @@ const AGENT_OPTIONS = {
 export const PROJECT_COMMAND = {
     path: ['<path>'], summary: 'Start a conversation in its own cloud VM',
     description: 'Opens Claude Code or Codex directly. --resume continues a project conversation. With --json it starts detached and prints the session. Detach with Ctrl-] then d.',
-    positionals: [{ name: 'path', required: true }, { name: 'claude|codex' }], options: { ...AGENT_OPTIONS, new: { type: 'boolean', description: 'Start a new conversation.' }, resume: { type: 'boolean', description: 'Continue a conversation from this project.' } },
+    positionals: [{ name: 'path', required: true }, { name: 'claude|codex' }], options: {
+        ...AGENT_OPTIONS,
+        new: { type: 'boolean', description: 'Start a new conversation.' },
+        resume: { type: 'boolean', description: 'Continue a conversation from this project.' },
+        claude: { type: 'boolean', description: 'Same as the claude argument (0.14.4+).' },
+        codex: { type: 'boolean', description: 'Same as the codex argument (0.14.4+).' },
+    },
 };
+/** `shard ./ codex`, quoting the path the way it was given when a shell would need it. */
+function projectExample(rest, app) {
+    const path = rest.find((r, i) => !r.startsWith('-') && !GLOBAL_VALUE_FLAGS.has(rest[i - 1] ?? '')) ?? './';
+    return `shard ${/^[\w./~@:+,=-]+$/.test(path) ? path : `'${path.replaceAll("'", `'\\''`)}'`} ${app}`;
+}
 export const CENTER_COMMAND = { path: ['<center>'], summary: 'Open the cloud agent command center', positionals: [], options: {} };
 const AGENT_COMMANDS = [
     { path: ['conversations', 'try'], summary: 'Try a conversation in a synced local worktree', positionals: [{ name: 'conversation', required: true }], options: { path: { type: 'string', value: '<path>', description: 'Local project checkout.' }, stop: { type: 'boolean', description: 'Stop the device helper’s local sync and ports.' } } },
@@ -1479,6 +1490,9 @@ export function parseCommandLine(argv, options = {}) {
         });
     }
     catch (err) {
+        const unknown = command === PROJECT_COMMAND && err.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION' ? /'([^']+)'/.exec(String(err.message))?.[1] : undefined;
+        if (unknown !== undefined)
+            throw new UsageError(`unknown option "${unknown}" for "shard <path>"; choose the agent with "${projectExample(rest, 'codex')}" or "${projectExample(rest, 'claude')}"`);
         throw new UsageError(err instanceof Error ? err.message : String(err));
     }
     const values = parsed.values;
@@ -1487,8 +1501,20 @@ export function parseCommandLine(argv, options = {}) {
     if (values.version === true)
         return { kind: 'version' };
     const positionals = parsed.positionals;
-    if (command === PROJECT_COMMAND && positionals[1] !== undefined && !['claude', 'codex'].includes(positionals[1]))
-        throw new UsageError('agent app must be claude or codex');
+    if (command === PROJECT_COMMAND) {
+        // --claude and --codex are spellings of the app argument; the handler only sees the argument.
+        const flagged = ['claude', 'codex'].filter((app) => values[app] === true);
+        delete values.claude;
+        delete values.codex;
+        if (positionals[1] !== undefined && !['claude', 'codex'].includes(positionals[1])) {
+            throw new UsageError(`agent app must be claude or codex, as in "${projectExample(rest, 'codex')}"`);
+        }
+        const chosen = new Set([...flagged, ...(positionals[1] === undefined ? [] : [positionals[1]])]);
+        if (chosen.size > 1)
+            throw new UsageError(`choose one agent app: "${projectExample(rest, 'codex')}" or "${projectExample(rest, 'claude')}"`);
+        if (positionals[1] === undefined && flagged[0] !== undefined && positionals.length === 1)
+            positionals.push(flagged[0]);
+    }
     const specs = command.positionals;
     const variadic = specs.at(-1)?.variadic === true;
     const required = specs.filter((s) => s.required && !s.variadic).length;

package/dist/claude-cloud-login.js

@@ -2,7 +2,7 @@ import { isDeepStrictEqual } from 'node:util';
 import { ShardfluxApiError } from '@shardflux/sdk';
 import { UsageError } from "./errors.js";
 import { openUrl } from "./browser.js";
-import { attachTerminal, cellConnector, PtyOutputCursor } from "./agent-terminal.js";
+import { attachTerminal, cellConnector, PtyOutputCursor, workspaceAsleep } from "./agent-terminal.js";
 const NEED_TERMINAL = 'Claude sign-in needed. Run shard agents credentials login claude in a terminal.';
 const VERSION = '2.1.289';
 export function requireClaudeTerminal(ctx) {
@@ -107,7 +107,7 @@ export async function loginClaudeInWorkspace(ctx, ws) {
         const opened = new Set();
         const cursor = new PtyOutputCursor();
         let output = '';
-        const code = await attachTerminal({ io: ctx.io, signal: ctx.signal, wake: signal => ws.wake({ signal }), invalidate: () => { },
+        const code = await attachTerminal({ io: ctx.io, signal: ctx.signal, wake: signal => ws.wake({ signal }), asleep: () => workspaceAsleep(ws), invalidate: () => { },
             sleep: (ms, signal) => new Promise(resolve => {
                 const done = () => { clearTimeout(timer); signal.removeEventListener('abort', done); resolve(); };
                 const timer = setTimeout(done, ms);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.14.3",
+  "version": "0.14.5",
   "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 serverless agent workspaces.",
   "license": "Apache-2.0",
@@ -47,7 +47,7 @@
     "smol-toml": "1.9.0",
     "snappyjs": "0.7.0",
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.19.1"
+    "@shardflux/sdk": "^0.20.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",