@shardflux/cli 0.15.2 → 0.17.0

package/dist/args.js

@@ -12,7 +12,8 @@
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.15.2';
+import { DEFAULT_CHOICE, MODEL_CHOICES } from "./agent-models.js";
+export const CLI_VERSION = '0.17.0';
 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).' },
@@ -57,7 +58,7 @@ const IF_REVISION = {
 };
 const WAIT = {
     wait: { type: 'boolean', description: 'Wait until the operation finishes.' },
-    timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (e.g. 90s, 5m; default 5m). The operation continues server side (a start waiting for capacity until its deadline, 15 minutes after it began; then it fails with capacity_unavailable).' },
+    timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (e.g. 90s, 5m; default 5m, and a start queued for capacity is waited for until its deadline, its place in the queue shown on stderr). The operation continues server side (a start waiting for capacity until its deadline, 15 minutes after it began; then it fails with capacity_unavailable).' },
     ...TIMING,
 };
 const REF = { name: 'id|key', required: true };
@@ -158,6 +159,11 @@ const KEY_COMMANDS = [
         } },
     { path: ['conversations', 'land'], summary: 'Record the landing action performed by the agent', positionals: [{ name: 'id', required: true }, { name: 'action', required: true }], options: { into: { type: 'string', value: '<ref>', description: 'Destination branch or PR URL.' } } },
     { path: ['conversations', 'move'], summary: 'Move at the end of the turn', positionals: [{ name: 'id', required: true }, { name: 'to', required: true }], options: {} },
+    { path: ['conversations', 'landing'], summary: 'Show or set how finished conversations reach this checkout', positionals: [{ name: 'mode' }, { name: 'backup' }], options: {
+            path: { type: 'string', value: '<path>', description: 'Local project checkout (default the current directory).' }
+        },
+        description: 'While the macOS app runs, a conversation whose turn ends with committed work lands in the local branch it started from: the branch moves to its commits and the changed files are written, keeping your uncommitted edits (auto, the default). pr opens a pull request instead; off leaves conversations in the cloud. Every file a landing rewrites is backed up first: backups lists them, restore <backup> puts the files back.',
+        examples: ['shard conversations landing', 'shard conversations landing pr', 'shard conversations landing backups', 'shard conversations landing restore 2026-10-09T12-00-00-000Z-fix-login-3fa2c1'] },
     ...['machine', 'template'].flatMap((level) => [
         { path: [level], summary: level === 'machine' ? 'Open your machine agent, or show its saved filesystem with --json' : 'Show this project’s template filesystem', positionals: [], options: {},
             description: LAYER_HELP[level] },
@@ -851,6 +857,14 @@ const KEY_COMMANDS = [
             'shard files patch acme/agent-7 /home/user/app.py --old "DEBUG = True" --new "DEBUG = False" --if-revision "$(shard ws get acme/agent-7 --json | jq .tree_revision)"',
         ],
     },
+    {
+        path: ['files', 'pull'],
+        summary: 'Download a large file a conversation committed into ~/Shardflux',
+        description: 'Each conversation’s committed changes appear in ~/Shardflux/<repository>/<base branch>/<conversation>/ while the macOS app runs. Files above the size limit are listed there as <file>.placeholder.txt; this downloads one in its place. <conversation> is its name, id or folder name.',
+        positionals: [{ name: 'conversation', required: true }, { name: 'path', required: true }],
+        options: {},
+        examples: ['shard files pull hype-video out/hype.mp4'],
+    },
     {
         path: ['operations', 'list'],
         summary: 'List a workspace’s operations, newest first',
@@ -1175,11 +1189,30 @@ const AGENT_OPTIONS = {
     reachable: { type: 'string', value: '<duration>', hidden: true, description: 'Deprecated; ignored. Claude conversations stay reachable without a time limit.' },
     approvals: { type: 'boolean', description: 'Keep the agent’s permission prompts.' },
 };
+/** `Claude fable, opus, sonnet or haiku; Codex …` from the CLI's one list (agent-models.ts), without "default". */
+function choiceIds(kind) {
+    return ['claude', 'codex'].map(app => {
+        const ids = MODEL_CHOICES[app][kind].map(c => c.id).filter(id => id !== DEFAULT_CHOICE);
+        return `${app === 'claude' ? 'Claude' : 'Codex'} ${ids.slice(0, -1).join(', ')} or ${ids.at(-1)}`;
+    }).join('; ');
+}
+/** The model and effort a new thread starts with; `shard agents targets --json` lists the choices (0.17.0+). */
+const MODEL_OPTIONS = {
+    model: { type: 'string', value: '<model>', description: `Model the new thread starts with: ${choiceIds('models')}; default is the agent’s own (0.17.0+).` },
+    effort: { type: 'string', value: '<level>', description: `Reasoning effort the new thread starts with: ${choiceIds('efforts')}; default is the agent’s own (0.17.0+).` },
+};
+/** A new thread on an existing conversation's computer (0.16.0+). */
+const ON_OPTIONS = {
+    on: { type: 'string', value: '<conversation|computer>', description: 'Start the thread on the computer of an existing conversation, sharing its packages, caches, services, ports and files, on its own branch: a conversation id, key or name, or its workspace key or id (shard agents computers lists them) (0.16.0+).' },
+    review: { type: 'boolean', description: 'With --on: a read-only Claude reviewer of that conversation’s worktree instead of a thread with its own branch (0.16.0+).' },
+};
 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,
+        ...MODEL_OPTIONS,
+        ...ON_OPTIONS,
         computer: COMPUTER_OPTION,
         new: { type: 'boolean', description: 'Start a new conversation.' },
         resume: { type: 'boolean', description: 'Continue a conversation from this project.' },
@@ -1192,10 +1225,17 @@ 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 ONBOARDING_COMMAND = { path: ['<onboarding>'], summary: 'Set up Shardflux in your terminal', positionals: [], options: { 'accept-terms': { type: 'boolean', description: 'Accept the Terms of Service and Privacy Policy.' }, apps: { type: 'string', value: '<claude,codex>', description: 'Connect Claude, Codex or both.' } } };
 export const CENTER_COMMAND = { path: ['<center>'], summary: 'Open the cloud agent command center', positionals: [], options: {} };
 const AGENT_COMMANDS = [
+    { path: ['device', 'requests'], summary: 'Review local device requests waiting for approval', positionals: [], options: {} },
+    ...['approve', 'deny'].map(action => ({ path: ['device', action], summary: `${action} a local device request`, positionals: [{ name: 'id', required: true }], options: {} })),
     { 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.' } } },
-    { path: ['agents', 'targets'], summary: 'Detect apps or configure managed desktop connections', positionals: [{ name: 'agent' }], options: { remove: { type: 'boolean', description: 'Remove this agent’s managed entries, or all entries for this API URL.' } } },
+    { path: ['agents', 'targets'], summary: 'Detect apps or configure managed desktop connections', positionals: [{ name: 'agent' }], options: {
+            remove: { type: 'boolean', description: 'Remove this agent’s managed entries, or all entries for this API URL.' },
+            'open-in': { type: 'string', value: '<app=target,…>', description: 'Where new conversations open (0.17.0+): claude=terminal|claude-desktop|web|t3, codex=codex-app|t3, e.g. claude=t3,codex=t3.' },
+            path: { type: 'string', value: '<path>', description: 'Local project folder whose T3 Code state and open_in to report, as agents new --path names it (default the current folder; the agent argument wins) (0.17.0+).' },
+        } },
     ...['claude-desktop', 'codex-app', 'web', 't3'].map(target => ({ path: ['agents', 'open', target], summary: `Open the agent in ${target}`, positionals: [{ name: 'agent' }], options: { reachable: AGENT_OPTIONS.reachable } })),
     { path: ['ssh-proxy'], summary: 'Forward SSH standard IO to a managed workspace', positionals: [{ name: 'host', required: true }], options: {} },
     ...['worktree', 'merge', 'keep', 'discard', 'restore'].map((action) => ({
@@ -1208,13 +1248,18 @@ const AGENT_COMMANDS = [
     })),
     ...['status', 'enable', 'disable'].map(action => ({ path: ['agents', 'codex', action], summary: `${action} the account's billed Codex Cloud connector`, positionals: [], options: {} })),
     { path: ['agents', 'open'], summary: 'Open a conversation (Codex Cloud or the native Claude session)', description: 'Codex opens its existing Cloud thread without waking its VM. Claude attaches its native session.', positionals: [{ name: 'agent', required: true }], options: { ...AGENT_OPTIONS, app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' }, in: { type: 'string', value: '<terminal|auto|claude-desktop|codex-app|web|t3>', description: 'Where to open it. auto (0.15.1+): the saved target, else a Claude conversation in Claude Desktop when it is installed, else in this terminal; web opens claude.ai.' } } },
-    { path: ['agents', 'new'], summary: 'Start a conversation in a fresh VM; Codex opens a genuine Cloud thread', positionals: [{ name: 'agent' }], options: {
+    { path: ['agents', 'computers'], summary: 'List the project’s computers a new thread can start on with --on, and the threads on each (0.16.0+)', positionals: [], options: {
+            path: { type: 'string', value: '<path>', description: 'Local project path (default the current directory).' },
+        } },
+    { path: ['agents', 'new'], summary: 'Start a conversation in a fresh VM, or with --on on an existing conversation’s computer; Codex opens a genuine Cloud thread', positionals: [{ name: 'agent' }], options: {
             ...AGENT_OPTIONS,
+            ...MODEL_OPTIONS,
+            ...ON_OPTIONS,
             computer: COMPUTER_OPTION,
             app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' },
             path: { type: 'string', value: '<path>', description: 'Local project path for first launch.' },
             name: { type: 'string', value: '<name>', description: 'New agent name; copies the project main workspace with --like.' },
-            in: { type: 'string', value: '<terminal|claude-desktop|codex-app|t3>', description: 'Where to open the new agent (default terminal).' },
+            in: { type: 'string', value: '<terminal|auto|claude-desktop|codex-app|t3>', description: 'Where to open the new agent (default terminal). t3 (0.17.0+): the first message starts a T3 Code thread (with --on, on that computer’s T3 server); auto: where agents targets --open-in says.' },
             like: { type: 'string', value: '<id|key>', description: 'Copy the workspace configuration onto a fresh disk.' },
         } },
     { path: ['agents', 'fork'], summary: 'Fork an agent’s memory and disk', positionals: [{ name: 'agent', required: true }, { name: 'name', required: true }], options: WAIT },
@@ -1225,13 +1270,29 @@ const AGENT_COMMANDS = [
             follow: { type: 'boolean', description: 'Follow output until interrupted.' },
         } },
 ];
+const CLI_PROXY_HELP = 'One CLIProxyAPI for your whole account: your Claude, Codex and other subscription logins live in a small hosted copy that sleeps between requests and wakes on the next one. This computer and every VM reach it at http://127.0.0.1:8317, so Claude Code, Codex and T3 Code keep their settings.';
+const CLI_PROXY_COMMANDS = [
+    { path: ['cli-proxy'], summary: 'Your hosted CLIProxyAPI: its accounts, and where it is reachable', description: CLI_PROXY_HELP, positionals: [], options: {
+            config: { type: 'string', value: '<path>', description: 'This computer’s CLIProxyAPI config file, when none is set up yet (default: found automatically).' },
+        } },
+    { path: ['cli-proxy', 'import'], summary: 'Move CLIProxyAPI from this computer into your account, reachable at 127.0.0.1:8317 everywhere', description: `${CLI_PROXY_HELP} Import brings your config and logins over, stops the local copy (one copy refreshes each login), and connects this computer and your machine template. On a second computer it connects that computer.`, positionals: [], options: {
+            config: { type: 'string', value: '<path>', description: 'Your CLIProxyAPI config file (default: the one the running CLIProxyAPI uses, else the usual locations).' },
+            yes: { type: 'boolean', description: 'Stop the local CLIProxyAPI without asking.' },
+        }, examples: ['shard cli-proxy import', 'shard cli-proxy'] },
+    { path: ['cli-proxy', 'export'], summary: 'Bring your logins back to this computer and stop the hosted CLIProxyAPI', description: 'The hosted copy stops first, so only this computer refreshes your logins from then on. Its logins, as last refreshed, go to the auth folder the import took them from (0600), this computer stops forwarding 127.0.0.1:8317, and the command that starts your local CLIProxyAPI is shown. shard cli-proxy import moves them back.', positionals: [], options: {
+            yes: { type: 'boolean', description: 'Do it without asking.' },
+        } },
+    { path: ['cli-proxy', 'forward'], hidden: true, summary: 'Forward 127.0.0.1:8317 to your hosted CLIProxyAPI (started at login)', positionals: [], options: {} },
+];
 /** Every command: the account plane first (sign in, set up), then the project-key commands. */
 const MENUBAR_COMMANDS = ['start', 'stop', 'status'].map(action => ({
     path: ['menubar', action], summary: `${action === 'start' ? 'Install and start' : action === 'stop' ? 'Stop' : 'Show'} the macOS menu bar app`,
     positionals: [], options: { login: { type: 'string', value: '<on|off>', description: 'Enable or disable launch at login.' } },
 }));
-export const COMMANDS = [...ACCOUNT_COMMANDS.filter((c) => c.path[0] !== 'templates'), ...AGENT_COMMANDS, ...AGENT_CREDENTIAL_COMMANDS, ...MENUBAR_COMMANDS, ...KEY_COMMANDS, ...ACCOUNT_COMMANDS.filter((c) => c.path[0] === 'templates')];
+export const COMMANDS = [...ACCOUNT_COMMANDS.filter((c) => c.path[0] !== 'templates'), ...AGENT_COMMANDS, ...AGENT_CREDENTIAL_COMMANDS, ...CLI_PROXY_COMMANDS, ...MENUBAR_COMMANDS, ...KEY_COMMANDS, ...ACCOUNT_COMMANDS.filter((c) => c.path[0] === 'templates')];
 const GROUPS = {
+    device: 'Local device approvals',
+    'cli-proxy': 'Your hosted CLIProxyAPI, reachable at http://127.0.0.1:8317 on this computer and in every VM',
     menubar: 'macOS menu bar app',
     conversations: 'Project conversations, branches and messages',
     agents: 'Cloud agent sessions and copied credentials',
@@ -1410,6 +1471,8 @@ export function parseCommandLine(argv, options = {}) {
     // `menubar refresh` (0.15.2+, not in help): the background step each command may start (menubar.ts).
     if (argv.length === 2 && argv[0] === 'menubar' && argv[1] === 'refresh')
         return { kind: 'run', command: { path: ['menubar', 'refresh'], summary: '', positionals: [], options: {} }, values: {}, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
+    if (argv[0] === 'device-helper' && argv.length === 2 && argv[1] === '--service')
+        return { kind: 'run', command: { path: ['device-helper'], summary: '', positionals: [], options: {} }, values: { service: true }, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
     if (argv.length === 1 && (argv[0] === 'acp' || argv[0] === 'device-helper'))
         return { kind: 'run', command: { path: [argv[0]], summary: '', positionals: [], options: {} }, values: {}, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
     const terminator = argv.indexOf('--');
@@ -1471,8 +1534,8 @@ export function parseCommandLine(argv, options = {}) {
         const path = rest.find((r, i) => !r.startsWith('-') && !GLOBAL_VALUE_FLAGS.has(rest[i - 1] ?? ''));
         if (path !== undefined && (/^(?:\.|\/|~\/)/.test(path) || options.isProjectPath?.(path)))
             command = PROJECT_COMMAND;
-        else if (path === undefined && !wantsHelp && !head.includes('--version') && !head.includes('-V') && (options.tty || head.includes('--json')))
-            command = CENTER_COMMAND;
+        else if (path === undefined && !wantsHelp && !head.includes('--version') && !head.includes('-V') && ((options.platform ?? process.platform) === 'linux' || options.tty || head.includes('--json')))
+            command = (options.platform ?? process.platform) === 'linux' && !head.includes('--json') ? ONBOARDING_COMMAND : CENTER_COMMAND;
     }
     if (!command) {
         if (words.length === 0) {
@@ -1600,7 +1663,7 @@ export function commandHelp(c) {
 export function groupHelp(prefix) {
     const words = typeof prefix === 'string' ? [prefix] : [...prefix];
     const group = words.join(' ');
-    const cmds = COMMANDS.filter((c) => words.every((w, i) => c.path[i] === w));
+    const cmds = COMMANDS.filter((c) => !c.hidden && words.every((w, i) => c.path[i] === w));
     const w = Math.max(...cmds.map((c) => usageLine(c).length));
     return [`Usage: shard ${group} <command> [options]`, '', `${GROUPS[group] ?? GROUPS[words[0]] ?? ''}.`, '', 'Commands:', ...cmds.map((c) => `  ${usageLine(c).padEnd(w)}  ${c.summary}`), ...(group === 'workspaces' ? ['', 'Also: shard workspaces files <read|write|ls|stat|search|patch> ..., shard workspaces operations <list|get|wait> ... and shard workspaces executions get ...'] : []), '', `Run "shard ${group} <command> --help" for details.`].join('\n') + '\n';
 }
@@ -1618,14 +1681,14 @@ export const EXIT_CODE_HELP = [
 /** The top help's sections: every command's group (first word) is in exactly one (args.test.ts checks). */
 export const HELP_SECTIONS = [
     { title: 'Account (a user session: shard signup or shard auth login)', groups: ['signup', 'verify', 'auth', 'setup', 'env', 'orgs', 'projects', 'api-keys', 'members', 'invitations', 'billing', 'audit', 'account'] },
-    { title: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'machine', 'template', 'agents', 'ssh-proxy'] },
+    { title: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'machine', 'template', 'agents', 'device', 'cli-proxy', 'ssh-proxy'] },
     { title: 'Workspaces for your app (a project API key: SHARDFLUX_API_KEY, else the one shard setup saved)', groups: ['login', 'whoami', 'status', 'usage', 'workspaces', 'files', 'operations', 'executions', 'secrets', 'credentials', 'volumes', 'egress'] },
     { title: 'Templates for your app’s workspaces (not for cloud agents; publish and archive use the session, the rest the API key)', groups: ['templates'] },
     { title: 'Other', groups: ['menubar', 'update', 'feedback', 'version'] },
 ];
 export function topHelp() {
     const w = Math.max(...COMMANDS.map((c) => usageLine(c).length));
-    const sections = HELP_SECTIONS.flatMap((s) => ['', `${s.title}:`, ...s.groups.flatMap((g) => COMMANDS.filter((c) => c.path[0] === g)).map((c) => `  ${usageLine(c).padEnd(w)}  ${c.summary}`)]);
+    const sections = HELP_SECTIONS.flatMap((s) => ['', `${s.title}:`, ...s.groups.flatMap((g) => COMMANDS.filter((c) => c.path[0] === g && !c.hidden)).map((c) => `  ${usageLine(c).padEnd(w)}  ${c.summary}`)]);
     return [
         `shard ${CLI_VERSION} — the Shardflux command line (built on @shardflux/sdk)`,
         '',

package/dist/cli-proxy-forward.d.ts

@@ -0,0 +1,45 @@
+import type { HubInfo } from './cli-proxy-hub.js';
+export declare const REPLAY_LIMIT: number;
+/** The forwarder answers this path itself (paths under /__shardflux/ are reserved by the edge, so no hub route is lost). */
+export declare const IDENTITY_PATH = "/__shardflux/forwarder";
+export interface ForwarderOptions {
+    /** The current hub info, read on every request (cheap: hubInfoSource caches by mtime). */
+    hub: () => HubInfo | null;
+    /** Starts CLIProxyAPI in the hub again (after `port_not_listening`). At most one runs at a time. */
+    repair?: () => Promise<void>;
+    /**
+     * Replaces the hub's callback URLs after the edge answers `callback_invalid` (the API key that created them was
+     * revoked) and gives VMs the new one. At most one runs at a time and at most one a minute; each request is renewed
+     * for once, so a URL that stays invalid is answered as is.
+     */
+    renew?: () => Promise<void>;
+    host?: string;
+    port?: number;
+    /** How long one request may be retried for (default 60 s, plus the time a repair takes). */
+    retryBudgetMs?: number;
+    /** Between attempts to bind a port another process holds (default 5 s). */
+    bindRetryMs?: number;
+    log?: (line: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+    /** Request bodies kept for a retry, in bytes (default REPLAY_LIMIT); a larger body streams and is not retried. */
+    replayLimit?: number;
+}
+/** The hub info file, re-read when it changes (a replaced callback URL takes effect on the next request). */
+export declare function hubInfoSource(dir: string): () => HubInfo | null;
+export declare class CliProxyForwarder {
+    #private;
+    constructor(opts: ForwarderOptions);
+    get address(): {
+        host: string;
+        port: number;
+    } | null;
+    /**
+     * Listens on host:port. While another program holds the port (also one listening on all interfaces, which a
+     * loopback bind would not notice), logs once and tries again every bindRetryMs (until close()); resolves once
+     * listening.
+     */
+    listen(): Promise<void>;
+    /** Closes the idle keep-alive connections to the edge (the next request opens a fresh one). */
+    dropIdleConnections(): void;
+    close(): Promise<void>;
+}