@shardflux/cli 0.18.0-next.5 → 0.18.0

package/dist/account-pool.js

@@ -0,0 +1,313 @@
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { out, readInput, resolveWorkspace } from "./commands.js";
+import { CodedError, UsageError, describeError } from "./errors.js";
+import { claudeLoginUrls, requireClaudeTerminal, runWorkspaceLogin } from "./claude-cloud-login.js";
+import { openMachine } from "./filesystem-commands.js";
+import { t3Install } from "./t3-mode.js";
+import { ensureCliProxyHub, sdkHubCloud } from "./cli-proxy-hub.js";
+import { homeProject } from "./cli-proxy.js";
+import { progress } from "./progress.js";
+const PROVIDERS = { claude: 'Claude', codex: 'ChatGPT / Codex' };
+const WINDOW_LABELS = { five_hour: '5-hour', seven_day: 'Weekly', seven_day_opus: 'Weekly Opus', seven_day_sonnet: 'Weekly Sonnet', primary: 'Primary', secondary: 'Secondary' };
+/** Codex names its windows primary and secondary; their length says which is the 5-hour and which the weekly one. */
+const windowLabel = (w) => (w.window === 'primary' || w.window === 'secondary') && w.window_minutes === 300 ? '5-hour'
+    : (w.window === 'primary' || w.window === 'secondary') && w.window_minutes === 10080 ? 'Weekly' : WINDOW_LABELS[w.window] ?? w.window;
+const STATUS_LABELS = { signed_in: 'Signed in', low: 'Low', limited: 'Limited', expired: 'Expired' };
+const CLAUDE_VERSION = '2.1.289';
+function provider(value, what = 'provider') {
+    if (value === 'claude' || value === 'codex')
+        return value;
+    throw new UsageError(`${what} is claude or codex`);
+}
+const optionalProvider = (value) => value === undefined ? undefined : provider(value, '--provider');
+/** "in 2h 10m", "in 4d 8h", "in 41m"; "now" once passed. */
+export function resetIn(resetsAt, now) {
+    if (!resetsAt)
+        return null;
+    const minutes = Math.round((Date.parse(resetsAt) - now) / 60_000);
+    if (!Number.isFinite(minutes))
+        return null;
+    if (minutes <= 0)
+        return 'now';
+    const d = Math.floor(minutes / 1440), h = Math.floor((minutes % 1440) / 60), m = minutes % 60;
+    return d > 0 ? `${d}d ${h}h` : h > 0 ? `${h}h ${m}m` : `${m}m`;
+}
+const pct = (w) => `${Math.round(w.used_percent)}%`;
+const plan = (a) => a.kind === 'api_key' ? 'API key' : a.plan_type ? a.plan_type.charAt(0).toUpperCase() + a.plan_type.slice(1) : '';
+const threads = (n) => `${n} ${n === 1 ? 'thread' : 'threads'}`;
+const name = (a) => a.email && a.label !== a.email ? `${a.label} (${a.email})` : a.label;
+function bar(used, width = 10) {
+    const filled = Math.max(0, Math.min(width, Math.round(used / 100 * width)));
+    return '█'.repeat(filled) + '░'.repeat(width - filled);
+}
+function asOf(a, now) {
+    if (!a.as_of || !a.stale)
+        return '';
+    const ago = resetIn(new Date(2 * now - Date.parse(a.as_of)).toISOString(), now);
+    return ago ? ` · as of ${ago} ago` : '';
+}
+/** Account references: the id, `<provider>:<n>` (its place in the list, from 1), the email or the label. */
+export function findAccount(list, ref) {
+    const byPlace = /^(claude|codex):(\d+)$/.exec(ref);
+    const matches = list.accounts.filter(a => a.id === ref || (byPlace ? a.provider === byPlace[1] && a.position === Number(byPlace[2]) - 1 : a.email === ref || a.label === ref));
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1)
+        throw new UsageError(`${ref} names ${matches.length} accounts; use its id or ${matches[0].provider}:<n> from shard agents accounts`);
+    throw new UsageError(`No account ${ref}; shard agents accounts lists them (id, claude:<n>, codex:<n>, email or label)`);
+}
+/** The compact list: one row per account, grouped by provider. */
+export function formatAccounts(list, now) {
+    if (!list.accounts.length)
+        return 'No Claude or ChatGPT/Codex accounts yet. Add one with shard agents accounts add claude|codex.\n';
+    const lines = [];
+    for (const p of ['claude', 'codex']) {
+        const rows = list.accounts.filter(a => a.provider === p);
+        if (!rows.length)
+            continue;
+        lines.push(PROVIDERS[p]);
+        for (const a of rows) {
+            const windows = a.kind === 'api_key' ? 'Pay as you go' : a.windows.filter(w => ['five_hour', 'seven_day', 'primary', 'secondary'].includes(w.window))
+                .map(w => `${windowLabel(w)} ${pct(w)}${resetIn(w.resets_at, now) ? ` (resets ${resetIn(w.resets_at, now) === 'now' ? 'now' : `in ${resetIn(w.resets_at, now)}`})` : ''}`).join(' · ') || 'No usage read yet';
+            const tags = [plan(a), a.preferred ? 'in use' : '', list.pool.pooled ? threads(a.threads) : ''].filter(Boolean).join(', ');
+            lines.push(`  ${`${p}:${a.position + 1}`.padEnd(9)} ${name(a)}${tags ? ` (${tags})` : ''} · ${STATUS_LABELS[a.status]}${a.status === 'expired' ? ': sign in again with shard agents accounts add ' + p : ''}`);
+            lines.push(`  ${''.padEnd(9)} ${windows}${asOf(a, now)}`);
+        }
+    }
+    if (list.pool.pooled) {
+        const open = list.accounts.reduce((n, a) => n + a.threads, 0), used = list.accounts.filter(a => a.threads > 0).length;
+        lines.push(`Pooled: ${threads(open)} on ${used} ${used === 1 ? 'account' : 'accounts'}; open threads remotely in T3 Code.`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** The usage view: every window of every account as a bar with its reset time. */
+export function formatUsage(list, now) {
+    if (!list.accounts.length)
+        return formatAccounts(list, now);
+    const lines = [];
+    for (const a of list.accounts) {
+        lines.push(`${PROVIDERS[a.provider]} · ${name(a)}${plan(a) ? ` · ${plan(a)}` : ''} · ${STATUS_LABELS[a.status]} · ${threads(a.threads)}${a.preferred ? ' · in use' : ''}${asOf(a, now)}`);
+        if (a.kind === 'api_key')
+            lines.push('  Pay as you go');
+        else if (!a.windows.length)
+            lines.push('  No usage read yet');
+        for (const w of a.windows) {
+            const reset = resetIn(w.resets_at, now);
+            lines.push(`  ${windowLabel(w).padEnd(13)} ${bar(w.used_percent)} ${pct(w).padStart(4)}${reset ? `  ${reset === 'now' ? 'resets now' : `resets in ${reset}`}` : ''}`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * The workspace a sign-in runs in: --workspace, else the account's machine VM, so a sign-in is the same from any
+ * folder (the menu bar starts it in Terminal in the home folder). The provider login runs in a throwaway profile there.
+ */
+async function signInWorkspace(ctx, values) {
+    if (typeof values.workspace === 'string')
+        return resolveWorkspace(ctx, values.workspace);
+    return (await openMachine(ctx, undefined, { sync: false })).ws;
+}
+function loginFile(ctx, path, value) {
+    const raw = JSON.stringify(value), content_b64 = Buffer.from(raw).toString('base64');
+    const hide = (v) => {
+        if (typeof v === 'string')
+            ctx.addSecret(v);
+        else if (Array.isArray(v))
+            v.forEach(hide);
+        else if (v && typeof v === 'object')
+            Object.values(v).forEach(hide);
+    };
+    hide(value);
+    ctx.addSecret(raw);
+    ctx.addSecret(content_b64);
+    return { path, mode: '0600', content_b64 };
+}
+/** Codex's device sign-in page, as Codex 0.160.0 prints it (test/fixtures/cloud-agents/codex-login-device-auth-0.160.0.json). */
+export function codexLoginUrls(output) {
+    const urls = new Set();
+    // eslint-disable-next-line no-control-regex
+    for (const match of output.matchAll(/https:\/\/[^\s\x00-\x20]+(?=[\s\x00-\x20])/g)) {
+        try {
+            const url = new URL(match[0]);
+            if (url.hostname === 'auth.openai.com' && url.pathname === '/codex/device' && !url.username && !url.password)
+                urls.add(url.toString());
+        }
+        catch { /* a fragment waits for the next frame */ }
+    }
+    return [...urls];
+}
+/**
+ * Adds a subscription account: the provider's own sign-in runs in a fresh profile in the workspace (Claude:
+ * `claude auth login --claudeai`; Codex: `codex login --device-auth`), its login files go to the API, and the profile
+ * is deleted. The workspace's own logins are untouched; the API delivers the account threads use.
+ */
+async function signIn(ctx, values, app) {
+    if (ctx.json || !ctx.io.stdin.isTTY || !ctx.io.stdin.setRawMode || !ctx.io.stdin.on) {
+        throw new UsageError(`Signing in to ${PROVIDERS[app]} runs in a terminal: shard agents accounts add ${app} (or --api-key-stdin for an API key).`);
+    }
+    if (app === 'claude')
+        requireClaudeTerminal(ctx);
+    const ws = await signInWorkspace(ctx, values);
+    const api = ctx.cloud().agentAccounts;
+    const claim = await api.signIn(app, ws.id, { ...(typeof values.label === 'string' ? { label: values.label } : {}), ...(values.scope === 'team' || values.scope === 'personal' ? { scope: values.scope } : {}) });
+    const root = `/tmp/shard-account-${claim.sign_in_id}`;
+    const session = `account-sign-in-${claim.sign_in_id}`;
+    const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
+    let complete = false;
+    try {
+        await cell.files.mkdir(root, { parents: true, mode: '0700' });
+        let files;
+        if (app === 'claude') {
+            const env = { HOME: root, CLAUDE_CONFIG_DIR: `${root}/.claude`, BROWSER: '/bin/false', DISABLE_AUTOUPDATER: '1' };
+            const version = await cell.exec.run(['claude', '--version'], { env, cwd: root, signal: ctx.signal, timeoutMs: 10_000 });
+            if (version.exitCode !== 0 || version.stdout.trim() !== `${CLAUDE_VERSION} (Claude Code)`)
+                throw new UsageError(`Claude sign-in requires Claude Code ${CLAUDE_VERSION} in the workspace image.`);
+            if (!await runWorkspaceLogin(ctx, ws, cell, { session, argv: ['claude', 'auth', 'login', '--claudeai'], env, cwd: root, urls: claudeLoginUrls }))
+                throw new UsageError('The Claude sign-in was interrupted. Run shard agents accounts add 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`));
+            files = [loginFile(ctx, '~/.claude/.credentials.json', credential), loginFile(ctx, '~/.claude.json', { oauthAccount: config.oauthAccount })];
+        }
+        else {
+            const env = { HOME: root, CODEX_HOME: `${root}/.codex`, BROWSER: '/bin/false' };
+            await cell.files.mkdir(`${root}/.codex`, { parents: true, mode: '0700' });
+            if (!await runWorkspaceLogin(ctx, ws, cell, { session, argv: ['codex', 'login', '--device-auth', '-c', 'cli_auth_credentials_store="file"'], env, cwd: root, urls: codexLoginUrls }))
+                throw new UsageError('The ChatGPT sign-in was interrupted. Run shard agents accounts add codex again.');
+            files = [loginFile(ctx, '~/.codex/auth.json', JSON.parse(await cell.files.readText(`${root}/.codex/auth.json`)))];
+        }
+        // The fresh profile's tokens leave the workspace before the upload; a failed upload needs a new sign-in.
+        await cell.files.remove(root, { recursive: true });
+        const account = await api.completeSignIn(claim.sign_in_id, files);
+        complete = true;
+        return account;
+    }
+    finally {
+        await cell.pty.close(session).catch(() => undefined);
+        await cell.files.remove(root, { recursive: true }).catch(() => undefined);
+        if (!complete)
+            await api.cancelSignIn(claim.sign_in_id).catch(() => undefined);
+    }
+}
+/**
+ * Pooled threads are used remotely in T3 Code (desktop, web, phone): they have no provider login for claude.ai or the
+ * ChatGPT app. Where new conversations open stays the person's choice (Settings, or agents targets --open-in).
+ */
+function remoteHint(ctx) {
+    return t3Install(ctx.io.env)
+        ? 'Use pooled threads remotely in T3 Code: shard agents targets --open-in claude=t3,codex=t3 opens new conversations there.\n'
+        : 'Use pooled threads remotely in T3 Code (desktop, web and phone): install it from https://t3.codes.\n';
+}
+const notAvailable = () => new CodedError('pool_not_available', 'Pooling accounts is not available for this organization.', 'Your accounts keep serving threads directly; shard agents accounts shows their usage.');
+export const ACCOUNT_POOL_HANDLERS = {
+    async 'agents accounts'(ctx, values) {
+        const list = await ctx.cloud().agentAccounts.list({ provider: optionalProvider(values.provider) });
+        out(ctx, formatAccounts(list, Date.now()), list);
+        return 0;
+    },
+    async 'agents accounts list'(ctx, values) {
+        const list = await ctx.cloud().agentAccounts.list({ provider: optionalProvider(values.provider) });
+        out(ctx, formatAccounts(list, Date.now()), list);
+        return 0;
+    },
+    async 'agents accounts usage'(ctx, values) {
+        const list = await ctx.cloud().agentAccounts.list({ provider: optionalProvider(values.provider) });
+        out(ctx, formatUsage(list, Date.now()), list);
+        return 0;
+    },
+    async 'agents accounts add'(ctx, values, [app]) {
+        const p = provider(app);
+        if (values.scope !== undefined && values.scope !== 'personal' && values.scope !== 'team')
+            throw new UsageError('--scope is personal or team');
+        let account;
+        if (values['api-key-stdin'] === true) {
+            const key = Buffer.from(await readInput(ctx, '-', 64 * 1024, '--api-key-stdin')).toString('utf8').trim();
+            if (!key || /\s/.test(key))
+                throw new UsageError('--api-key-stdin reads one API key from standard input, e.g. pbpaste | shard agents accounts add claude --api-key-stdin');
+            ctx.addSecret(key);
+            account = await ctx.cloud().agentAccounts.addApiKey(p, key, { ...(typeof values.label === 'string' ? { label: values.label } : {}), ...(values.scope === 'team' || values.scope === 'personal' ? { scope: values.scope } : {}) });
+        }
+        else
+            account = await signIn(ctx, values, p);
+        out(ctx, `Added ${name(account)} (${PROVIDERS[account.provider]}${plan(account) ? ` ${plan(account)}` : ''}) as ${account.provider}:${account.position + 1}.\n`, ctx.json ? { ...await ctx.cloud().agentAccounts.list(), account } : account);
+        return 0;
+    },
+    async 'agents accounts remove'(ctx, _values, [ref]) {
+        const api = ctx.cloud().agentAccounts;
+        const account = findAccount(await api.list(), ref);
+        await api.remove(account.id);
+        out(ctx, `Removed ${name(account)} (${PROVIDERS[account.provider]}).\n`, ctx.json ? { ...await api.list(), removed: account.id, provider: account.provider } : null);
+        return 0;
+    },
+    async 'agents accounts move'(ctx, _values, [ref, direction]) {
+        if (direction !== 'up' && direction !== 'down')
+            throw new UsageError('move takes an account and up or down, e.g. shard agents accounts move claude:2 up');
+        const api = ctx.cloud().agentAccounts;
+        const account = findAccount(await api.list(), ref);
+        const list = await api.move(account.id, direction);
+        const moved = list.accounts.find(a => a.id === account.id) ?? account;
+        out(ctx, moved.position === account.position ? `${name(account)} is already ${direction === 'up' ? 'first' : 'last'}.\n` : `Moved ${name(moved)} to ${moved.provider}:${moved.position + 1}.\n`, { ...list, account: moved });
+        return 0;
+    },
+    async 'agents accounts pool'(ctx, _values, [state]) {
+        if (state !== 'on' && state !== 'off')
+            throw new UsageError('pool is on or off');
+        let pool;
+        try {
+            pool = await ctx.cloud().agentPool.set({ pooled: state === 'on' });
+        }
+        catch (error) {
+            if (error instanceof ShardfluxApiError && (error.status === 404 || error.details?.reason === 'pool_not_on_plan'))
+                throw notAvailable();
+            throw error;
+        }
+        // Pooled threads run through the account hub: it needs the router (codex-connector 5) and its hub token.
+        const hub = pool.pooled ? await ensurePoolHub(ctx) : null;
+        out(ctx, pool.pooled
+            ? `Pooled: each new thread runs on the account with the most room. Running threads keep their account.\n${hub ? `The account hub is not ready (${hub}); new threads start directly until it is. Run shard agents accounts pool on again.\n` : ''}${remoteHint(ctx)}`
+            : 'Direct: new threads use your account as before. Pooled threads keep their account until they end.\n', ctx.json ? { ...await ctx.cloud().agentAccounts.list(), pool, ...(pool.pooled ? { hub: hub ? { ready: false, error: hub } : { ready: true } } : {}) } : pool);
+        return 0;
+    },
+};
+/** The `accounts` block of `shard agents targets --json` (0.18.0+): the account list for the menu bar; null when it cannot be read. */
+export async function targetsAccounts(ctx) {
+    let timer;
+    try {
+        return await Promise.race([ctx.cloud().agentAccounts.list(), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('the account list took longer than 3 s')), 3000); })]);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The conversation's thread runs on the account pool (its `account.mode`, API with the pool). */
+export function conversationPooled(conversation) {
+    const account = conversation?.account;
+    return account?.mode === 'pooled';
+}
+/** A pooled thread has no provider login on its session, so claude.ai, Claude Desktop and the Codex app cannot reach it. */
+export const pooledNeedsT3 = (ref) => new CodedError('t3_not_installed', `${ref} runs on pooled accounts; open it in T3 Code.`, `Install T3 Code from https://t3.codes, open it once, then run shard agents open t3 ${ref}.`);
+// `shard accounts …` runs the same handlers (hidden aliases in args.ts).
+for (const [path, handler] of Object.entries(ACCOUNT_POOL_HANDLERS))
+    ACCOUNT_POOL_HANDLERS[path.replace(/^agents /, '')] = handler;
+/**
+ * The account hub in pool mode (W1): created or upgraded on codex-connector 5 with its hub token (POST
+ * /v1/agent-pool/hub-token, minted for the hub workspace). Null when ready, else what stopped it.
+ */
+async function ensurePoolHub(ctx) {
+    try {
+        const cloud = ctx.cloud();
+        const hub = (accountPoolSeams.hubCloud ?? ((c) => sdkHubCloud(c.cloud(), { signal: c.signal, wakeTimeoutMs: c.wakeTimeoutMs, agentLabel: c.agentLabel, homeProject: (org) => homeProject(c, org) })))(ctx);
+        const ensured = await ensureCliProxyHub(hub, { dir: ctx.store.dir, apiUrl: ctx.apiUrl, progress: (m) => progress(ctx, m),
+            pool: { hubToken: async (workspaceId) => (await cloud.request('POST', '/v1/agent-pool/hub-token', { json: { workspace_id: workspaceId } })).token } });
+        for (const value of [ensured.info.callback_url, ensured.info.management_key])
+            ctx.addSecret(value);
+        return null;
+    }
+    catch (error) {
+        return describeError(error).message;
+    }
+}
+/** Test seam: the hub cloud the pool toggle ensures (the SDK's by default). */
+export const accountPoolSeams = {};

package/dist/agent-setup.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Set in a coding agent's shell: Claude Code (CLAUDECODE), Codex (CODEX_SANDBOX, CODEX_THREAD_ID), Cursor's agent
+ * (CURSOR_AGENT) and Gemini CLI (GEMINI_CLI). Such a shell may have a terminal (Cursor and Codex can run commands in a
+ * PTY), but nobody types into it: a full-screen view or a prompt there waits forever.
+ */
+export declare const AGENT_SHELL_VARIABLES: readonly ["CLAUDECODE", "CODEX_SANDBOX", "CODEX_THREAD_ID", "CURSOR_AGENT", "GEMINI_CLI"];
+export declare function codingAgentShell(env: Record<string, string | undefined>): boolean;
+export declare const SETUP_QUESTION = "Is Shardflux for a SaaS platform (your product runs VMs for its own customers through the API, SDK or MCP), or for your personal setup (your own cloud coding agents: each Claude or Codex conversation gets its own VM)?";
+export declare const AGENT_SETUP_DOCS = "https://docs.shardflux.dev/guides/agent-setup.md";
+/** One step of a path: what it does, what to ask the user first (if anything), and the commands in order. */
+export interface GuideStep {
+    step: string;
+    ask?: string;
+    commands: string[];
+    note?: string;
+}
+/** What `shard setup --guide --json` prints. */
+export interface SetupGuide {
+    question: string;
+    signed_in: {
+        email: string | null;
+    } | null;
+    api_key_saved: boolean;
+    account: GuideStep;
+    saas: GuideStep[];
+    personal: GuideStep[];
+    terms_url: string;
+    privacy_url: string;
+    docs: string;
+}
+/** The local state the guide adapts to: a saved (or SHARDFLUX_SESSION_TOKEN) session and a saved (or exported) key. */
+export interface GuideState {
+    signedIn: boolean;
+    email: string | null;
+    apiKey: boolean;
+}
+export declare function setupGuide(state: GuideState): SetupGuide;
+export declare function setupGuideText(g: SetupGuide): string;

package/dist/agent-setup.js

@@ -0,0 +1,116 @@
+/**
+ * Setting Shardflux up from a coding agent (0.17.1+): the one question the agent asks its user first, and the ordered
+ * steps of both answers. `shard setup --guide` prints it; so does a bare `shard` without a terminal or in a coding
+ * agent's shell, where the command center would wait for keys nobody presses. Local only: no network call and nothing
+ * to answer, so it returns at once.
+ *
+ * - SaaS platform: the user's product runs VMs for its own customers (API, SDK, MCP). An account, an API key, the
+ *   integration and templates for the customers' workspaces; no agent sign-ins, menu bar or machine.
+ * - Personal setup: the user's own cloud coding agents. Sign in, connect Claude and Codex, build the machine from what
+ *   the user asks for, set up the project and hand over `shard ./`.
+ */
+import { legalFields } from "./legal.js";
+/**
+ * Set in a coding agent's shell: Claude Code (CLAUDECODE), Codex (CODEX_SANDBOX, CODEX_THREAD_ID), Cursor's agent
+ * (CURSOR_AGENT) and Gemini CLI (GEMINI_CLI). Such a shell may have a terminal (Cursor and Codex can run commands in a
+ * PTY), but nobody types into it: a full-screen view or a prompt there waits forever.
+ */
+export const AGENT_SHELL_VARIABLES = ['CLAUDECODE', 'CODEX_SANDBOX', 'CODEX_THREAD_ID', 'CURSOR_AGENT', 'GEMINI_CLI'];
+export function codingAgentShell(env) {
+    return AGENT_SHELL_VARIABLES.some((name) => (env[name]?.trim() ?? '') !== '');
+}
+export const SETUP_QUESTION = 'Is Shardflux for a SaaS platform (your product runs VMs for its own customers through the API, SDK or MCP), or for your personal setup (your own cloud coding agents: each Claude or Codex conversation gets its own VM)?';
+export const AGENT_SETUP_DOCS = 'https://docs.shardflux.dev/guides/agent-setup.md';
+const { terms_url: TERMS, privacy_url: PRIVACY } = legalFields();
+export function setupGuide(state) {
+    const account = state.signedIn
+        ? { step: 'Account', commands: ['shard setup --json'], note: `Signed in${state.email ? ` as ${state.email}` : ''}. shard setup saves the organization, project and API key (safe to run again).` }
+        : {
+            step: 'Account',
+            ask: `Do you agree to the Terms of Service (${TERMS}) and the Privacy Policy (${PRIVACY})? Continue once they do.`,
+            commands: ['shard signup --accept-terms --json'],
+            note: 'It signs up or signs in with this computer’s Codex login and saves an API key. Without a Codex login, or for an account they already have: shard auth login --browser --no-wait --json (give your user the link and the code), then shard auth login --browser --json (returns once they approved) and shard setup --json.',
+        };
+    return {
+        question: SETUP_QUESTION,
+        signed_in: state.signedIn ? { email: state.email } : null,
+        api_key_saved: state.apiKey,
+        account,
+        saas: [
+            { step: 'API key for your product', commands: ['eval "$(shard env)"'], note: 'Exports SHARDFLUX_API_KEY for the SDKs, the MCP server and your product’s server. Keep it in server-side secrets, never in client code.' },
+            {
+                step: 'Integrate',
+                commands: ['npm install @shardflux/sdk', 'pip install shardflux'],
+                note: 'Or the HTTP API (https://api.shardflux.dev/v1) or the MCP server (https://mcp.shardflux.dev/mcp). Your customers’ workspaces start from a template: shard templates build template.yaml. Start at https://docs.shardflux.dev/quickstart.md',
+            },
+        ],
+        personal: [
+            {
+                step: 'Connect Claude and Codex',
+                ask: 'Which agents do you use: Claude, Codex or both?',
+                commands: ['shard setup --inspect --connect --json --apps claude,codex'],
+                note: 'Claude: your user runs shard agents credentials login claude in their own terminal, once (a claude.ai link and a code). Codex: codex login on this computer; --connect copies it and starts the account’s Codex remote device. Pass only the apps they use.',
+            },
+            {
+                step: 'Build the machine',
+                ask: 'What should every cloud agent start with? Languages and runtimes, CLIs and tools, dotfiles and shell, secrets and credentials, editor and agent config.',
+                commands: ['shard machine open --json', "shard ws exec <key> -- bash -lc '<install commands>'", 'shard files write <key> <path> --from -', 'shard machine save --wait --json'],
+                note: 'machine open prints the machine VM’s workspace key. Install with ws exec, write dotfiles and secret files with files write (contents on standard input, never in arguments), then save: every new conversation starts from it.',
+            },
+            {
+                step: 'Set up the project',
+                ask: 'Which repository, which project secrets, and what does a good first run look like (tests, a dev server)?',
+                commands: ['shard ./ --json --prompt "Set up this project and run its tests"', 'shard conversations wait <conversation-id> --timeout 90', 'shard template --json'],
+                note: 'Run it in the project folder (shard ./ codex … for Codex): the conversation gets its own VM, and setup installs the dependencies and saves the project template. Run the wait again while it says Still working. Project secrets: shard secrets import --from <hsec|1password|bitwarden|keychain> NAME, or printf %s "$VALUE" | shard secrets create NAME.',
+            },
+            {
+                step: 'Hand over',
+                commands: ['shard ./'],
+                note: 'Your user runs it in their own terminal (shard ./ codex for Codex). Claude conversations continue on claude.ai and in the Claude app; Codex threads in the Codex app, on the web and on the phone.',
+            },
+        ],
+        terms_url: TERMS,
+        privacy_url: PRIVACY,
+        docs: AGENT_SETUP_DOCS,
+    };
+}
+/** Wraps `text` at `width` columns, every line after the first indented by `indent`. */
+function wrap(text, indent, width = 100) {
+    const lines = [];
+    let line = '';
+    for (const word of text.split(' ')) {
+        if (line && line.length + 1 + word.length > width - (lines.length ? indent.length : 0)) {
+            lines.push(line);
+            line = word;
+        }
+        else
+            line = line ? `${line} ${word}` : word;
+    }
+    if (line)
+        lines.push(line);
+    return lines.join(`\n${indent}`);
+}
+function stepText(n, s) {
+    const head = `${n}. ${s.step}.${s.ask ? ` Ask: ${s.ask}` : ''}`;
+    return [
+        `  ${wrap(head, '     ')}`,
+        ...s.commands.map((c) => `       ${c}`),
+        ...(s.note ? [`     ${wrap(s.note, '     ', 96)}`] : []),
+    ].join('\n');
+}
+export function setupGuideText(g) {
+    return [
+        'Set up Shardflux. Ask your user one question first:',
+        `  ${wrap(g.question, '  ')}`,
+        '',
+        stepText(1, g.account),
+        '',
+        'SaaS platform:',
+        ...g.saas.map((s, i) => stepText(i + 2, s)),
+        '',
+        'Personal setup:',
+        ...g.personal.map((s, i) => stepText(i + 2, s)),
+        '',
+        `Every step in detail: ${g.docs}. Every command: shard --help.`,
+    ].join('\n') + '\n';
+}

package/dist/agent-target-commands.js

@@ -22,6 +22,7 @@ import { AgentStateStore } from "./agent-state.js";
 import { workspaceRepositoryPath } from "./agent-repository.js";
 import { openInChoices, openT3, saveOpenIn, startSshThread, t3Install, t3NotInstalled, t3OpenFailed, t3Status } from "./t3-mode.js";
 import { openT3Conversation, t3Fields, withT3Context } from "./t3-launch.js";
+import { conversationPooled, pooledNeedsT3, targetsAccounts } from "./account-pool.js";
 const missing = (e) => e instanceof ShardfluxApiError && e.status === 404;
 const keyOf = (ref) => ref.includes('/') ? ref : `${projectIdentity('./').slug}/${ref}`;
 /** How long opening a Claude conversation this computer just started waits for Claude to publish its Remote Control URL. */
@@ -229,6 +230,12 @@ const openTarget = (target) => async (ctx, values, [ref = 'main']) => {
         return openT3Conversation(ctx, ref, values);
     // A conversation id opens that conversation's own session on its computer (claude.ai, the desktop apps).
     const conversation = /^conv_[a-z0-9]{26}$/.test(ref) ? await getConversation(ctx, ref) : undefined;
+    // A pooled thread (0.18.0+) has no provider login on its session: it opens remotely in T3 Code.
+    if (conversation && conversationPooled(conversation)) {
+        if (!detected.targets.includes('t3'))
+            throw pooledNeedsT3(ref);
+        return openT3Conversation(ctx, ref, values);
+    }
     let ws = conversation ? await conversationWorkspace(ctx, conversation) : await resolveWorkspace(ctx, keyOf(ref));
     if (values.reachable !== undefined)
         ws = await ctx.cloud().workspaces.open({ key: ws.key, ...agentReachability(values), wait: false });
@@ -362,11 +369,13 @@ export const TARGET_HANDLERS = {
         // models (0.17.0+): the model and effort choices a new thread can start with; clients never hardcode them.
         // T3 Code mode (0.17.0+): T3's state for this project (the agent's, else this folder's), and where `shard ./` opens
         // each app's new conversations (--open-in sets it).
+        // accounts (0.18.0+, --json): the Claude and ChatGPT/Codex accounts with usage and resets, for the menu bar.
+        const accounts = ctx.json ? targetsAccounts(ctx) : undefined;
         const project = targetsProject(ref, typeof values.path === 'string' ? values.path : undefined);
         const t3 = t3Status(ctx, { project, lastUsed: true });
         if (typeof values['open-in'] === 'string')
             saveOpenIn(ctx, values['open-in'], t3, found.clients);
-        const detected = { ...found, t3, open_in: openInChoices(ctx, project, { clients: found.clients }) };
+        const detected = { ...found, t3, open_in: openInChoices(ctx, project, { clients: found.clients }), ...(accounts ? { accounts: await accounts } : {}) };
         const targets = new AgentTargets(ctx.io.env, ctx.store.dir);
         const key = ref ? keyOf(ref) : undefined;
         const before = values.remove === true ? await targets.configure(undefined, ctx.apiUrl, [], false, ctx.signal) : [];

package/dist/agent-targets.d.ts

@@ -23,6 +23,17 @@ export interface T3App {
     version: string | null;
     linux?: T3LinuxApp;
 }
+/** Whether an installed T3 runs the Shardflux provider: its server has the ACP Registry driver (t3-asar.ts, t3-linux.ts). */
+export declare const t3AppSupportsAcp: (app: T3App) => boolean;
+/**
+ * The T3 every command uses when several are installed (channels, or a .deb and an AppImage): the newest build with the
+ * Shardflux provider, else the newest build, whatever order the folders were scanned in, so its version (prewarm, the
+ * VM's T3 server) matches the T3 that opens. Ties keep scan order.
+ */
+export declare function preferredT3(apps: readonly T3App[]): {
+    app: T3App;
+    acp: boolean;
+} | undefined;
 /** The installed T3 Code apps (any channel), with their path and version, in the given app folders (applicationDirs). */
 export declare function t3Apps(dirs: string[], platform?: NodeJS.Platform, env?: Record<string, string | undefined>): T3App[];
 /**

package/dist/agent-targets.js

@@ -7,7 +7,9 @@ import { writePrivateFile } from "./credentials.js";
 import { UsageError } from "./errors.js";
 import { projectWorkspacePath } from "./agent-repository.js";
 import { withTargetLock } from "./target-lock.js";
-import { linuxApplicationDirs, linuxT3Apps } from "./t3-linux.js";
+import { linuxApplicationDirs, linuxSupportsAcp, linuxT3Apps } from "./t3-linux.js";
+import { t3ArchiveSupportsAcp } from "./t3-asar.js";
+import { compareT3Versions } from "./t3-version.js";
 const PERSISTED_TARGETS = ['claude-desktop', 'codex-app'];
 const BEGIN = '# BEGIN Shardflux managed targets';
 const END = '# END Shardflux managed targets';
@@ -37,6 +39,21 @@ export function managedBlock(text, body) {
     const stop = end + END.length + (text[end + END.length] === '\n' ? 1 : 0);
     return text.slice(0, start) + block + text.slice(stop);
 }
+/** Whether an installed T3 runs the Shardflux provider: its server has the ACP Registry driver (t3-asar.ts, t3-linux.ts). */
+export const t3AppSupportsAcp = (app) => app.linux
+    ? linuxSupportsAcp({ ...app, linux: app.linux }) : t3ArchiveSupportsAcp(join(app.path, 'Contents', 'Resources', 'app.asar'));
+/**
+ * The T3 every command uses when several are installed (channels, or a .deb and an AppImage): the newest build with the
+ * Shardflux provider, else the newest build, whatever order the folders were scanned in, so its version (prewarm, the
+ * VM's T3 server) matches the T3 that opens. Ties keep scan order.
+ */
+export function preferredT3(apps) {
+    if (apps.length <= 1)
+        return apps[0] && { app: apps[0], acp: t3AppSupportsAcp(apps[0]) };
+    const newest = (list) => list.reduce((best, app) => compareT3Versions(app.version, best.version) > 0 ? app : best);
+    const capable = apps.filter(t3AppSupportsAcp);
+    return capable.length ? { app: newest(capable), acp: true } : { app: newest(apps), acp: false };
+}
 /** The installed T3 Code apps (any channel), with their path and version, in the given app folders (applicationDirs). */
 export function t3Apps(dirs, platform = process.platform, env = process.env) {
     if (platform === 'linux')
@@ -101,9 +118,10 @@ export function installedTargets(env, platform = process.platform, appDirs) {
     const versions = {};
     const t3Bundles = t3Apps(dirs, platform, env);
     const t3 = t3Bundles.length > 0;
-    for (const app of t3Bundles)
-        if (app.version)
-            versions.t3 ??= app.version;
+    // The version of the T3 that opens (preferredT3, as t3Install picks it); one install costs no archive read.
+    const picked = t3Bundles.length > 1 ? preferredT3(t3Bundles)?.app : t3Bundles[0];
+    if (picked?.version)
+        versions.t3 = picked.version;
     const executable = (name) => (env.PATH ?? '').split(':').filter(Boolean).some(p => { try {
         accessSync(join(p, name), constants.X_OK);
         return true;

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.17.0";
+export declare const CLI_VERSION = "0.18.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;
@@ -34,6 +34,8 @@ export declare const GLOBAL_OPTIONS: Record<string, OptionSpec>;
 export declare const PROJECT_COMMAND: CommandSpec;
 export declare const ONBOARDING_COMMAND: CommandSpec;
 export declare const CENTER_COMMAND: CommandSpec;
+/** Bare `shard` without a terminal, or in a coding agent's shell (0.17.1+): the setup question and both paths' steps. */
+export declare const GUIDE_COMMAND: CommandSpec;
 export declare const COMMANDS: CommandSpec[];
 export declare function normalizeWords(words: string[]): string[];
 export declare function findCommand(words: string[]): CommandSpec | undefined;