@shardflux/cli 0.18.0-next.4 → 0.18.0

package/dist/args.js

@@ -13,7 +13,7 @@ import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
 import { DEFAULT_CHOICE, MODEL_CHOICES } from "./agent-models.js";
-export const CLI_VERSION = '0.18.0-next.4';
+export const CLI_VERSION = '0.18.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).' },
@@ -173,6 +173,9 @@ const KEY_COMMANDS = [
             } },
         { path: [level, 'rollback'], summary: `Restore a saved ${level} version`, positionals: [], options: { to: { type: 'string', value: '<version>', description: 'Version to restore (default previous saved version).' } } },
     ]),
+    { path: ['machine', 'open'], summary: 'Create or resume your machine VM without attaching to it, and print its workspace key (0.17.1+)', positionals: [], options: {},
+        description: 'For an agent building your machine from a terminal it does not attach to: install with "shard ws exec <key> -- bash -lc ...", write dotfiles and secret files with "shard files write <key> <path> --from -" (contents on standard input), then "shard machine save --wait". The first open copies your Claude and Codex settings into it, as "shard machine" does.',
+        examples: ['shard machine open --json', "shard ws exec \"$(shard machine open)\" -- bash -lc 'sudo apt-get install -y ripgrep'", 'shard machine save --wait --json'] },
     { path: ['agents', 'list'], summary: 'List coding agent sessions.', positionals: [], options: {
             ...PAGE,
             state: { type: 'string', value: '<working|waiting|exited>', description: 'Agent state filter.' },
@@ -1181,6 +1184,25 @@ const AGENT_CREDENTIAL_COMMANDS = [
     ...['sync', 'status', 'forget'].map((action) => ({ path: ['agents', 'credentials', action], summary: `${action} Codex copies and the account's cloud Claude login (contents never printed)`, positionals: [], options: {} })),
     { path: ['agents', 'credentials', 'login'], summary: 'Sign in once to cloud Claude for this account', positionals: [{ name: 'app', required: true }], options: { workspace: { type: 'string', value: '<id|key>', description: 'Use this workspace for the cloud sign-in.' } } },
 ];
+const ACCOUNT_PROVIDER = { type: 'string', value: '<claude|codex>', description: 'Only this provider’s accounts.' };
+/** Claude and ChatGPT/Codex accounts with their usage windows, resets and threads (0.18.0+). */
+const AGENT_ACCOUNT_COMMANDS = [
+    { path: ['agents', 'accounts'], summary: 'Claude and ChatGPT/Codex accounts with usage, resets and status (0.18.0+)', positionals: [], options: { provider: ACCOUNT_PROVIDER },
+        examples: ['shard agents accounts', 'shard agents accounts usage', 'shard agents accounts add claude', 'pbpaste | shard agents accounts add codex --api-key-stdin'] },
+    { path: ['agents', 'accounts', 'list'], summary: 'List the accounts: status, usage windows and when they reset (0.18.0+)', positionals: [], options: { provider: ACCOUNT_PROVIDER } },
+    { path: ['agents', 'accounts', 'usage'], summary: 'Every usage window of every account, with its reset time (0.18.0+)', positionals: [], options: { provider: ACCOUNT_PROVIDER } },
+    { path: ['agents', 'accounts', 'add'], summary: 'Sign in a Claude or ChatGPT account, or add an API key (0.18.0+)', positionals: [{ name: 'provider', required: true }], options: {
+            'api-key-stdin': { type: 'boolean', description: 'Add an API key read from standard input instead of signing in.' },
+            label: { type: 'string', value: '<name>', description: 'The account’s name in lists (default its email).' },
+            scope: { type: 'string', value: '<personal|team>', description: 'personal: only your threads use it; team: any member’s (default: team for team plans and API keys, else personal).' },
+            workspace: { type: 'string', value: '<id|key>', description: 'Run the sign-in in this workspace (default your machine VM, from any folder).' },
+        } },
+    { path: ['agents', 'accounts', 'remove'], summary: 'Remove an account and its login (0.18.0+)', positionals: [{ name: 'account', required: true }], options: {} },
+    { path: ['agents', 'accounts', 'move'], summary: 'Move an account up or down in its provider’s order (0.18.0+)', positionals: [{ name: 'account', required: true }, { name: 'direction', required: true }], options: {} },
+    { path: ['agents', 'accounts', 'pool'], hidden: true, summary: 'Pool accounts: each new thread on the account with the most room', positionals: [{ name: 'state', required: true }], options: {} },
+];
+/** `shard accounts …`: the same commands, as the menu bar and the design name them. */
+const ACCOUNT_ALIASES = AGENT_ACCOUNT_COMMANDS.map(c => ({ ...c, path: c.path.slice(1), hidden: true }));
 const COMPUTER_OPTION = { type: 'boolean', description: 'Give the new conversation a desktop with a browser its agent drives (computer use).' };
 const AGENT_OPTIONS = {
     prompt: { type: 'string', value: '<text>', description: 'First user message for a new conversation.' },
@@ -1227,6 +1249,8 @@ function projectExample(rest, 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: {} };
+/** Bare `shard` without a terminal, or in a coding agent's shell (0.17.1+): the setup question and both paths' steps. */
+export const GUIDE_COMMAND = { path: ['<guide>'], summary: 'Show how to set up Shardflux with a coding agent', 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: action === 'approve' ? { always: { type: 'boolean', description: 'Allow matching requests for this project; never for outside-folder access.' } } : {} })),
@@ -1289,7 +1313,7 @@ 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, ...CLI_PROXY_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, ...AGENT_ACCOUNT_COMMANDS, ...ACCOUNT_ALIASES, ...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',
@@ -1534,8 +1558,22 @@ 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.platform ?? process.platform) === 'linux' || options.tty || head.includes('--json')))
-            command = (options.platform ?? process.platform) === 'linux' && !head.includes('--json') ? ONBOARDING_COMMAND : CENTER_COMMAND;
+        else if (path === undefined && !wantsHelp && !head.includes('--version') && !head.includes('-V')) {
+            const linux = (options.platform ?? process.platform) === 'linux';
+            // Linux's terminal onboarding takes --accept-terms and --apps; without them and without a terminal (or in a
+            // coding agent's shell, where options.tty is false) bare shard prints the setup guide (0.17.1+).
+            const onboarding = linux && head.some((a) => /^--(accept-terms|apps)(=|$)/.test(a));
+            // The guide takes the global options only: anything else keeps its "unknown option" error.
+            const globalsOnly = rest.every((a) => !a.startsWith('-') || a === '-h' || a === '-V' || (/^--(?:no-)?([a-z-]+)(?:=|$)/.exec(a)?.[1] ?? '') in GLOBAL_OPTIONS);
+            if (head.includes('--json'))
+                command = CENTER_COMMAND;
+            else if (onboarding || (linux && options.tty))
+                command = ONBOARDING_COMMAND;
+            else if (options.tty)
+                command = CENTER_COMMAND;
+            else if (globalsOnly)
+                command = GUIDE_COMMAND;
+        }
     }
     if (!command) {
         if (words.length === 0) {
@@ -1681,7 +1719,7 @@ 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', 'device', 'cli-proxy', 'ssh-proxy'] },
+    { title: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'machine', 'template', 'agents', 'accounts', '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'] },
@@ -1696,12 +1734,19 @@ export function topHelp() {
         '       shard <path> [claude|codex] [--approvals]',
         'Terminal: detach with Ctrl-] then d; /exit ends the agent session.',
         '',
+        'Setting Shardflux up with a coding agent? Ask your user one question first: is it for a SaaS platform (their',
+        'product runs VMs for its own customers through the API, SDK or MCP) or for their personal setup (their own cloud',
+        'coding agents: each Claude or Codex conversation gets its own VM)? "shard setup --guide" prints the steps of both',
+        '(0.17.1+; --json for a list); so does "shard" in a shell without a terminal.',
+        '',
         'Feedback: shard feedback [options] <message...>',
         ...FEEDBACK_WHY.map((l) => `  ${l}`),
         '  shard feedback --category bug --request-id req-5c7744b2bb5c457b86b76101 --error-code template_not_found "ws open --template python-node failed; expected a suggestion of the closest slug"',
         '  shard feedback --category idea "user would like shard ws open to remember the last template they used"',
         '',
         'Start here (everything the web app does, from a terminal; a person only opens the emailed link and pays in Checkout):',
+        '  shard signup --accept-terms                   # account, session and API key with this computer’s Codex login',
+        '  shard auth login --browser                    # or approve this computer in the browser (--no-wait: print the link, return)',
         `  printf '%s\\n' "$PASSWORD" | shard auth register --email you@example.com`,
         `  shard auth verify-email '<link from the email>'`,
         `  printf '%s\\n' "$PASSWORD" | shard auth login --email you@example.com`,

package/dist/claude-cloud-login.d.ts

@@ -10,6 +10,17 @@ export declare function claudeLoginUrls(output: string): string[];
  * already holds this account is left as it is.
  */
 export declare function mergeClaudeAccount(cell: Pick<CellClient, 'files'>, oauthAccount: unknown, signal?: AbortSignal): Promise<void>;
+/**
+ * Runs a provider's own sign-in (`claude auth login`, `codex login --device-auth`) in a workspace PTY attached to this
+ * terminal, opening each sign-in link `urls` finds in its output in the browser. True when it exited 0.
+ */
+export declare function runWorkspaceLogin(ctx: Ctx, ws: Workspace, cell: CellClient, login: {
+    session: string;
+    argv: string[];
+    env: Record<string, string>;
+    cwd: string;
+    urls: (output: string) => string[];
+}): Promise<boolean>;
 /** A transient Linux profile holds the initial pair; it is removed before an agent starts. */
 export declare function loginClaudeInWorkspace(ctx: Ctx, ws: Workspace): Promise<AgentCredentialMetadata>;
 export declare function ensureCloudClaude(ctx: Ctx, ws: Workspace): Promise<void>;

package/dist/claude-cloud-login.js

@@ -3,11 +3,14 @@ import { ShardfluxApiError } from '@shardflux/sdk';
 import { UsageError } from "./errors.js";
 import { openUrl } from "./browser.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.';
+import { codingAgentShell } from "./agent-setup.js";
+const NEED_TERMINAL = 'Claude sign-in needed: run shard agents credentials login claude in a terminal, once for the account (a claude.ai link, then its code).';
+const NEED_TERMINAL_HINT = 'a coding agent asks its user to run it in their own terminal, then checks it with shard setup --inspect --json --apps claude';
 const VERSION = '2.1.289';
 export function requireClaudeTerminal(ctx) {
-    if (ctx.json || !ctx.io.stdin.isTTY || !ctx.io.stdin.setRawMode || !ctx.io.stdin.on)
-        throw new UsageError(NEED_TERMINAL);
+    // A coding agent's shell (0.17.1+) may be a PTY, but the person who reads the code is not typing into it.
+    if (ctx.json || !ctx.io.stdin.isTTY || !ctx.io.stdin.setRawMode || !ctx.io.stdin.on || codingAgentShell(ctx.io.env))
+        throw new UsageError(NEED_TERMINAL, NEED_TERMINAL_HINT);
 }
 export async function cloudClaudeLogin(ctx) {
     return (await ctx.cloud().agentCredentials.list()).find(row => row.app === 'claude' && row.scope === 'account' && row.status === 'ready');
@@ -76,6 +79,48 @@ export async function mergeClaudeAccount(cell, oauthAccount, signal) {
     }
     throw new UsageError('Claude account configuration kept changing in the workspace. Run shard agents credentials login claude again.');
 }
+/**
+ * Runs a provider's own sign-in (`claude auth login`, `codex login --device-auth`) in a workspace PTY attached to this
+ * terminal, opening each sign-in link `urls` finds in its output in the browser. True when it exited 0.
+ */
+export async function runWorkspaceLogin(ctx, ws, cell, login) {
+    await cell.pty.open({ session_id: login.session, argv: login.argv, env: login.env, cwd: login.cwd, rows: 24, cols: 100 });
+    const connect = cellConnector(cell, login.session);
+    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 }), asleep: () => workspaceAsleep(ws), invalidate: () => { },
+        sleep: (ms, signal) => new Promise(resolve => {
+            const done = () => { clearTimeout(timer); signal.removeEventListener('abort', done); resolve(); };
+            const timer = setTimeout(done, ms);
+            signal.addEventListener('abort', done, { once: true });
+            if (signal.aborted)
+                done();
+        }),
+        connect: async (offset, signal) => {
+            const connection = await connect(offset, signal);
+            return {
+                input: bytes => connection.input(bytes), resize: (rows, cols) => connection.resize(rows, cols), close: () => connection.close(),
+                messages: async function* () {
+                    for await (const message of connection.messages()) {
+                        const bytes = cursor.consume(message);
+                        if (bytes) {
+                            output = (output + bytes.toString()).slice(-16384);
+                            for (const url of login.urls(output))
+                                if (!opened.has(url)) {
+                                    opened.add(url);
+                                    openUrl(url, ctx.io.env);
+                                }
+                        }
+                        yield message;
+                    }
+                },
+            };
+        },
+    });
+    const ended = await cell.pty.get(login.session);
+    return code === 0 && ended.state === 'exited' && ended.exit_code === 0;
+}
 /** A transient Linux profile holds the initial pair; it is removed before an agent starts. */
 export async function loginClaudeInWorkspace(ctx, ws) {
     requireClaudeTerminal(ctx);
@@ -102,42 +147,7 @@ export async function loginClaudeInWorkspace(ctx, ws) {
         const version = await cell.exec.run(['claude', '--version'], { env, cwd: root, signal: ctx.signal, timeoutMs: 10_000 });
         if (version.exitCode !== 0 || version.stdout.trim() !== `${VERSION} (Claude Code)`)
             throw new UsageError(`Cloud Claude sign-in requires Claude Code ${VERSION} in the workspace image.`);
-        await cell.pty.open({ session_id: session, argv: ['claude', 'auth', 'login', '--claudeai'], env, cwd: root, rows: 24, cols: 100 });
-        const connect = cellConnector(cell, session);
-        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 }), asleep: () => workspaceAsleep(ws), invalidate: () => { },
-            sleep: (ms, signal) => new Promise(resolve => {
-                const done = () => { clearTimeout(timer); signal.removeEventListener('abort', done); resolve(); };
-                const timer = setTimeout(done, ms);
-                signal.addEventListener('abort', done, { once: true });
-                if (signal.aborted)
-                    done();
-            }),
-            connect: async (offset, signal) => {
-                const connection = await connect(offset, signal);
-                return {
-                    input: bytes => connection.input(bytes), resize: (rows, cols) => connection.resize(rows, cols), close: () => connection.close(),
-                    messages: async function* () {
-                        for await (const message of connection.messages()) {
-                            const bytes = cursor.consume(message);
-                            if (bytes) {
-                                output = (output + bytes.toString()).slice(-16384);
-                                for (const url of claudeLoginUrls(output))
-                                    if (!opened.has(url)) {
-                                        opened.add(url);
-                                        openUrl(url, ctx.io.env);
-                                    }
-                            }
-                            yield message;
-                        }
-                    },
-                };
-            },
-        });
-        const ended = await cell.pty.get(session);
-        if (code !== 0 || ended.state !== 'exited' || ended.exit_code !== 0)
+        if (!await runWorkspaceLogin(ctx, ws, cell, { session, argv: ['claude', 'auth', 'login', '--claudeai'], env, cwd: root, urls: claudeLoginUrls }))
             throw new UsageError('Claude cloud sign-in was interrupted. Run shard agents credentials login claude again.');
         const credential = JSON.parse(await cell.files.readText(`${root}/.claude/.credentials.json`));
         const config = JSON.parse(await cell.files.readText(`${root}/.claude/.claude.json`));

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

@@ -35,11 +35,21 @@ export declare const HUB_TEMPLATE = "codex-connector";
  * logins and settings, stay) before VMs get the hub's address.
  */
 export declare const HUB_TEMPLATE_VERSION = 4;
+/**
+ * The codex-connector version whose sf-agent runs the account pool router: a hub set up for pooled accounts is created
+ * on it, or upgraded to it. HUB_TEMPLATE_VERSION moves to it once it is registered in every environment.
+ */
+export declare const POOL_HUB_TEMPLATE_VERSION = 5;
 export declare const HUB_CAPS: Caps;
 export declare const HUB_INFO_FILE = "cli-proxy.json";
 /** Paths in the hub workspace. */
 export declare const HUB_DIR = "/home/user/.cli-proxy-hub";
 export declare const HUB_AUTH_DIR = "/home/user/.cli-proxy-api";
+/** Pool mode: the router reads the API URL and the hub token (`sfh_…`) from these hub files (0600). */
+export declare const HUB_POOL_FILES: {
+    readonly apiUrl: "/home/user/.cli-proxy-hub/api-url";
+    readonly apiToken: "/home/user/.cli-proxy-hub/api-token";
+};
 export interface HubInfo {
     version: 1;
     api_url: string;
@@ -122,7 +132,7 @@ export interface HubWorkspace {
 }
 export interface HubCloud {
     /** The hub workspace, running (resumed or woken as needed); with `create`, created on first use. Null when missing. */
-    open(create: boolean): Promise<{
+    open(create: boolean, templateVersion?: number): Promise<{
         ws: HubWorkspace;
         created: boolean;
         template?: HubTemplate;
@@ -218,6 +228,15 @@ export interface EnsureOptions {
     progress?: (message: string) => void;
     /** Random management key (tests). */
     randomKey?: () => string;
+    /**
+     * Pool mode (account pool): the hub's router gets the API URL and a hub token, and CLIProxyAPI passes the providers'
+     * rate-limit headers through so the router reads usage on every answer. `hubToken` mints a token for the hub
+     * workspace (`POST /v1/agent-pool/hub-token`); it is called when the hub has none, or always with `renew`.
+     */
+    pool?: {
+        hubToken: (workspaceId: string) => Promise<string>;
+        renew?: boolean;
+    };
 }
 export interface EnsureResult {
     info: HubInfo;
@@ -238,6 +257,12 @@ export declare class HubError extends CodedError {
  * hub info locally (0600) and in the hub. Idempotent: a running, healthy hub with a valid callback URL is left as it is.
  */
 export declare function ensureCliProxyHub(cloud: Shardflux | HubCloud, opts: EnsureOptions): Promise<EnsureResult>;
+/**
+ * The hub config with the providers' rate-limit headers passed through (`requests.passthrough-headers`, or the legacy
+ * top-level key): CLIProxyAPI 8.0.23 records them per login only for non-streaming answers, so the pool router reads
+ * them on its own answers. Returns the text unchanged when it already passes them.
+ */
+export declare function poolHubConfig(text: string): string;
 /** The callback URL as the hub stores it (`callback.json`, 0600): its secret is shown only when it is created. */
 export interface StoredCallback {
     callback_url: string;

package/dist/cli-proxy-hub.js

@@ -45,11 +45,18 @@ export const HUB_TEMPLATE = 'codex-connector';
  * logins and settings, stay) before VMs get the hub's address.
  */
 export const HUB_TEMPLATE_VERSION = 4;
+/**
+ * The codex-connector version whose sf-agent runs the account pool router: a hub set up for pooled accounts is created
+ * on it, or upgraded to it. HUB_TEMPLATE_VERSION moves to it once it is registered in every environment.
+ */
+export const POOL_HUB_TEMPLATE_VERSION = 5;
 export const HUB_CAPS = { cpu_millis: 1000, memory_mib: 256, disk_gib: 2, allocation_mode: 'fixed' };
 export const HUB_INFO_FILE = 'cli-proxy.json';
 /** Paths in the hub workspace. */
 export const HUB_DIR = '/home/user/.cli-proxy-hub';
 export const HUB_AUTH_DIR = '/home/user/.cli-proxy-api';
+/** Pool mode: the router reads the API URL and the hub token (`sfh_…`) from these hub files (0600). */
+export const HUB_POOL_FILES = { apiUrl: `${HUB_DIR}/api-url`, apiToken: `${HUB_DIR}/api-token` };
 const CALLBACK_PATH = /^\/__shardflux\/callback\/sfcb_[A-Za-z0-9_-]+\/$/;
 function callbackUrlOk(cb) {
     try {
@@ -258,7 +265,7 @@ export function hubPlacement(keyProjectId, home) {
 export function sdkHubCloud(cloud, opts = {}) {
     const signal = opts.signal;
     return {
-        async open(create) {
+        async open(create, templateVersion = HUB_TEMPLATE_VERSION) {
             const existing = await cloud.workspaces.findByKey(HUB_KEY, { includeDeleted: false, ...(signal ? { signal } : {}) });
             if (!existing && !create)
                 return null;
@@ -271,7 +278,7 @@ export function sdkHubCloud(cloud, opts = {}) {
             }
             const ws = await cloud.workspaces.open({
                 key: HUB_KEY,
-                ...(existing ? {} : { template: `${HUB_TEMPLATE}@${HUB_TEMPLATE_VERSION}`, caps: HUB_CAPS, lifetime: 'persistent' }),
+                ...(existing ? {} : { template: `${HUB_TEMPLATE}@${templateVersion}`, caps: HUB_CAPS, lifetime: 'persistent' }),
                 labels: { ...existing?.labels, ...HUB_LABELS },
                 wait: { ...(opts.wakeTimeoutMs ? { timeoutMs: Math.max(opts.wakeTimeoutMs, 180_000) } : {}), ...(signal ? { signal } : {}) },
             });
@@ -593,12 +600,14 @@ export async function ensureCliProxyHub(cloud, opts) {
     const progress = opts.progress ?? (() => { });
     const local = readHubInfo(opts.dir, opts.apiUrl);
     progress('Opening the CLIProxyAPI hub…');
-    let opened = await hubCloud.open(!opts.repairOnly);
+    // Pooled accounts need the router's template; everything else keeps the general one.
+    const want = opts.pool ? POOL_HUB_TEMPLATE_VERSION : HUB_TEMPLATE_VERSION;
+    let opened = await hubCloud.open(!opts.repairOnly, want);
     if (!opened)
         throw new HubError('This account has no hosted CLIProxyAPI yet.', 'move yours: shard cli-proxy import');
     // A hub on an older template is upgraded before VMs get its address (a plain repair only starts it again).
     const template = opened.template;
-    if (!opened.created && (!opts.repairOnly || opts.renewInvalid) && hubCloud.upgrade && template?.version != null && template.version < HUB_TEMPLATE_VERSION && (template.upgradeTo ?? 0) >= HUB_TEMPLATE_VERSION) {
+    if (!opened.created && (!opts.repairOnly || opts.renewInvalid) && hubCloud.upgrade && template?.version != null && template.version < want && (template.upgradeTo ?? 0) >= want) {
         progress('Updating the CLIProxyAPI hub…');
         await hubCloud.upgrade(opened.ws.id);
         opened = await hubCloud.open(false);
@@ -645,6 +654,14 @@ export async function ensureCliProxyHub(cloud, opts) {
     }
     if ((await ws.list(HUB_AUTH_DIR)) === null)
         await ws.sh(`mkdir -p -m 0700 ${HUB_AUTH_DIR}`);
+    if (opts.pool) {
+        // The router is in the hub's sf-agent: an older hub that could not be upgraded above cannot pool.
+        const running = opened.template?.version;
+        if (running != null && running < POOL_HUB_TEMPLATE_VERSION) {
+            throw new HubError(`Pooled accounts need the hub on ${HUB_TEMPLATE} ${POOL_HUB_TEMPLATE_VERSION}; it runs ${running} and no update is published yet.`);
+        }
+        await setUpPool(ws, opts.apiUrl, opts.pool);
+    }
     const started = await ws.sh(START_SCRIPT, [restart ? '1' : '0'], { timeoutMs: 180_000 });
     const startLines = started.stdout.trim().split('\n');
     const state = startLines.find((l) => ['running', 'started', 'restarted'].includes(l));
@@ -666,6 +683,45 @@ export async function ensureCliProxyHub(cloud, opts) {
         writeHubInfo(opts.dir, info);
     return { info, created, process: state, callbackReplaced, config };
 }
+/**
+ * The hub config with the providers' rate-limit headers passed through (`requests.passthrough-headers`, or the legacy
+ * top-level key): CLIProxyAPI 8.0.23 records them per login only for non-streaming answers, so the pool router reads
+ * them on its own answers. Returns the text unchanged when it already passes them.
+ */
+export function poolHubConfig(text) {
+    let doc = parseDocument(text || '{}');
+    if (doc.errors.length > 0 || !isMap(doc.contents))
+        doc = new Document({});
+    const v8 = doc.hasIn(['config-version']) || V8_SECTIONS.some((k) => isMap(doc.getIn([k])));
+    const path = v8 ? ['requests', 'passthrough-headers'] : ['passthrough-headers'];
+    if (doc.getIn(path) === true)
+        return text;
+    if (v8 && doc.hasIn(['passthrough-headers']))
+        doc.deleteIn(['passthrough-headers']);
+    doc.setIn(path, true);
+    return doc.toString();
+}
+const HUB_TOKEN_RE = /^sfh_[A-Za-z0-9_-]{43}$/;
+/** Pool mode in the hub: the API URL, the hub token (minted once, or again with renew) and header passthrough. */
+async function setUpPool(ws, apiUrl, pool) {
+    await ws.withLock('pool', async () => {
+        if ((await ws.read(HUB_POOL_FILES.apiUrl))?.trim() !== apiUrl)
+            await ws.write(HUB_POOL_FILES.apiUrl, `${apiUrl}\n`, '0600');
+        const have = (await ws.read(HUB_POOL_FILES.apiToken))?.trim() ?? '';
+        if (pool.renew || !HUB_TOKEN_RE.test(have)) {
+            const token = (await pool.hubToken(ws.id)).trim();
+            if (!HUB_TOKEN_RE.test(token))
+                throw new HubError('The Shardflux API did not return a hub token.');
+            await ws.write(HUB_POOL_FILES.apiToken, `${token}\n`, '0600');
+        }
+        const configPath = `${HUB_DIR}/config.yaml`;
+        const config = (await ws.read(configPath)) ?? '';
+        const next = poolHubConfig(config);
+        // A running CLIProxyAPI reloads its config by itself; the router starts within a minute of the token.
+        if (next !== config)
+            await ws.write(configPath, next, '0600');
+    });
+}
 /**
  * The hub's one callback URL. Under the hub's callback lock: the stored one is kept while the port's callback still
  * has its creation time; otherwise one is created and stored before the lock is released. Every device and every

package/dist/commands.d.ts

@@ -132,9 +132,11 @@ export declare function ttlSeconds(values: Values, b: {
     max: number;
     range: string;
 }): number | undefined;
+/** A session with its conversation, and why that conversation needs you (0.18.0+, APIs that return `question`). */
 type ThreadRow = import('@shardflux/sdk').Agent & {
     conversation_id?: string | null;
     conversation_key?: string;
+    question?: string;
 };
 /**
  * Each session's own conversation: the one whose harness session it is, else the computer's only live conversation.
@@ -147,6 +149,7 @@ export declare function withConversations(rows: import('@shardflux/sdk').Agent[]
     harness_session_id: string | null;
     state: string;
     ended_at?: string | null;
+    question?: string | null;
 }[] | null): ThreadRow[];
 export declare const KEY_HANDLERS: Record<string, Handler>;
 export {};

package/dist/commands.js

@@ -817,7 +817,7 @@ export function withConversations(rows, conversations) {
         const named = a.conversation_id;
         const c = (named ? conversations.find(c => c.id === named) : undefined)
             ?? conversations.find(c => c.workspace_id === a.workspace_id && c.harness_session_id === session) ?? (bound.length === 1 ? bound[0] : undefined);
-        return c ? { ...a, conversation_id: c.id, conversation_key: c.key } : a;
+        return c ? { ...a, conversation_id: c.id, conversation_key: c.key, ...(c.state === 'needs_you' && c.question ? { question: c.question } : {}) } : a;
     });
 }
 /** The project-key commands; handlers.ts adds the account plane's. */
@@ -857,8 +857,12 @@ export const KEY_HANDLERS = {
         // A complete listing also shows sessions the projection has not picked up yet (agent-live.ts).
         if (!next && !str(values.cursor))
             rows.splice(0, rows.length, ...await withLiveAgents(ctx, rows, { ...(state ? { state } : {}), labels }));
-        // LAST MESSAGE (0.13.4+): the session's latest message, from an API that reports it.
-        const message = (a) => !a.last_message ? '-' : a.last_message.length > 60 ? `${a.last_message.slice(0, 59)}…` : a.last_message;
+        // LAST MESSAGE (0.13.4+): the session's latest message, from an API that reports it; for a conversation that
+        // needs you, why (0.18.0+): its question or the reason its turn stopped.
+        const message = (a) => {
+            const text = (a.question ?? a.last_message ?? '').replace(/\s+/g, ' ').trim();
+            return !text ? '-' : text.length > 60 ? `${text.slice(0, 59).trimEnd()}…` : text;
+        };
         const enriched = withConversations(rows, await threads);
         out(ctx, rows.length ? table(['CONVERSATION', 'COMPUTER', 'APP', 'STATE', 'TITLE', 'LAST MESSAGE'], enriched.map(a => [a.conversation_key?.split('/').at(-1) ?? '-', a.workspace_key, a.app, a.state, a.title, message(a)])) : 'No agent sessions.\n', { data: enriched, next_cursor: next });
         if (!ctx.json && next)

package/dist/conversation-commands.d.ts

@@ -1,3 +1,8 @@
 import type { Ctx, Handler } from './commands.js';
 export declare function conversationClient(ctx: Ctx): import("@shardflux/sdk").Shardflux | import("@shardflux/sdk").ShardfluxAccount;
+/** Why a conversation needs you, as one line of at most `max` characters; undefined in other states (0.18.0+). */
+export declare function questionLine(c: {
+    state: string;
+    question?: string | null;
+}, max?: number): string | undefined;
 export declare const CONVERSATION_HANDLERS: Record<string, Handler>;

package/dist/conversation-commands.js

@@ -6,16 +6,22 @@ export function conversationClient(ctx) {
     const session = Boolean(ctx.io.env.SHARDFLUX_SESSION_TOKEN?.trim()) || ctx.store.profile(ctx.apiUrl).session !== undefined;
     return key || !session ? ctx.cloud() : ctx.account();
 }
+/** Why a conversation needs you, as one line of at most `max` characters; undefined in other states (0.18.0+). */
+export function questionLine(c, max = 100) {
+    const text = c.state === 'needs_you' ? c.question?.replace(/\s+/g, ' ').trim() : undefined;
+    return !text ? undefined : text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
+}
 export const CONVERSATION_HANDLERS = {
     async 'conversations resume'(ctx, _values, [id]) { const r = await conversationClient(ctx).conversations.resume(id, { signal: ctx.signal }); out(ctx, `${r.conversation.title}: resumed.\n`, r); return 0; },
     async 'conversations reader'(ctx, _values, [id]) { const r = await conversationClient(ctx).conversations.spaceReader(id, { signal: ctx.signal }); out(ctx, `${r.workspace.workspace_key}\n`, r); return 0; },
     async 'conversations list'(ctx, values) {
         const state = str(values.state);
         const page = await conversationClient(ctx).conversations.list({ projectId: str(values.project), state, parentId: str(values.parent), cursor: str(values.cursor), limit: values.limit ? Number(values.limit) : undefined });
-        out(ctx, page.data.map(c => `${c.id}\t${c.title}\t${c.state}\t${c.branch}`).join('\n') + '\n', page);
+        // A conversation that needs you adds a fifth column: why (0.18.0+).
+        out(ctx, page.data.map(c => { const q = questionLine(c); return `${c.id}\t${c.title}\t${c.state}\t${c.branch}${q ? `\t${q}` : ''}`; }).join('\n') + '\n', page);
         return 0;
     },
-    async 'conversations get'(ctx, _values, [id]) { const c = await conversationClient(ctx).conversations.get(id); out(ctx, `${c.title}\n${c.state}\n${c.branch}\n`, c); return 0; },
+    async 'conversations get'(ctx, _values, [id]) { const c = await conversationClient(ctx).conversations.get(id); const q = questionLine(c, 200); out(ctx, `${c.title}\n${c.state}\n${c.branch}\n${q ? `${q}\n` : ''}`, c); return 0; },
     async 'conversations send'(ctx, _values, [id, text]) { const r = await conversationClient(ctx).conversations.send(id, text, { signal: ctx.signal }); out(ctx, `Message sent (${r.seq}).\n`, r); return 0; },
     async 'conversations wait'(ctx, values, [id]) {
         const seconds = values.timeout === undefined ? 900 : Number(values.timeout);

package/dist/conversations.d.ts

@@ -40,6 +40,15 @@ export interface Conversation {
     /** The model and effort its harness starts with; null is the agent's own default (0.17.0+, APIs that keep them). */
     model?: string | null;
     effort?: string | null;
+    /** The account its thread runs on and the mode it started in (0.18.0+, APIs with the account pool). */
+    account?: {
+        id: string | null;
+        label: string | null;
+        provider: Harness;
+        mode: 'direct' | 'pooled';
+    } | null;
+    /** Why it needs you, while `state` is needs_you; null otherwise (0.18.0+, APIs that return it). */
+    question?: string | null;
 }
 export interface LocalConversation {
     api_url: string;

package/dist/desktop-linux.js

@@ -53,7 +53,7 @@ export class LinuxDesktopManager {
             return null;
         }
     }
-    async status(dir) {
+    status(dir) {
         const version = this.#version(this.app), pids = [];
         try {
             const pid = Number(readFileSync(join(dir, 'desktop-linux.pid'), 'utf8'));
@@ -62,20 +62,21 @@ export class LinuxDesktopManager {
                 pids.push(pid);
         }
         catch { /* no running app */ }
-        return { installed: version !== null, version, running: pids.length > 0, pids, login: existsSync(join(this.home, '.config/autostart/shardflux.desktop')) ? 'on' : 'off' };
+        return Promise.resolve({ installed: version !== null, version, running: pids.length > 0, pids, login: existsSync(join(this.home, '.config/autostart/shardflux.desktop')) ? 'on' : 'off' });
     }
     packagedVersion() { const path = this.#source(); return path ? this.#version(path) : null; }
-    async login(on) {
+    login(on) {
         const file = join(this.home, '.config/autostart/shardflux.desktop');
         if (!on) {
             rmSync(file, { force: true });
-            return;
+            return Promise.resolve();
         }
         mkdirSync(dirname(file), { recursive: true });
         const entry = join(this.home, '.local/share/applications/dev.shardflux.Desktop.desktop');
         if (!existsSync(entry))
-            throw new UsageError('Run shard menubar start first.');
+            return Promise.reject(new UsageError('Run shard menubar start first.'));
         cpSync(entry, file);
+        return Promise.resolve();
     }
     async stop(dir) {
         const status = await this.status(dir);

package/dist/filesystem-commands.d.ts

@@ -1,7 +1,17 @@
-import type { AgentFilesystem } from '@shardflux/sdk';
-import type { Handler } from './commands.js';
+import type { AgentFilesystem, Workspace } from '@shardflux/sdk';
+import type { Ctx, Handler } from './commands.js';
 /** One line per status: what is in use and what is saving or failed, its platform base and setup cache. */
 export declare function filesystemLine(state: AgentFilesystem & {
     cache_scope?: string;
 }): string;
+/** The save's one line about software under the home that went into the image (0.18.0+), as the in-VM shard says it. */
+export declare function movedLine(state: AgentFilesystem, level: 'machine' | 'template'): string;
+/** Creates or resumes the machine VM of the saved machine version; the first one gets this computer's agent config. */
+/** The account's machine VM, created or resumed; `sync: false` skips the first-open config sync (an account sign-in). */
+export declare function openMachine(ctx: Ctx, state?: AgentFilesystem, opts?: {
+    sync?: boolean;
+}): Promise<{
+    state: AgentFilesystem;
+    ws: Workspace;
+}>;
 export declare const FILESYSTEM_HANDLERS: Record<string, Handler>;