@shardflux/cli 0.20.0 → 0.22.0

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

@@ -1,5 +1,7 @@
 import type { AgentCredentialMetadata, CellClient, Workspace } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
+/** Someone types into this terminal: not --json, a TTY with raw mode, and not a coding agent's shell. */
+export declare function claudeTerminal(ctx: Ctx): boolean;
 export declare function requireClaudeTerminal(ctx: Ctx): void;
 export declare function cloudClaudeLogin(ctx: Ctx): Promise<AgentCredentialMetadata | undefined>;
 /** Parse only complete provider authorize links, including the native OSC-8 link. */
@@ -21,6 +23,26 @@ export declare function runWorkspaceLogin(ctx: Ctx, ws: Workspace, cell: CellCli
     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>;
+/**
+ * The same sign-in without an attached terminal (0.20.1+: a coding agent's shell, --json, no TTY). The workspace PTY
+ * runs the login exactly as runWorkspaceLogin does; shard reads its output, opens the claude.ai link it prints, and
+ * opens a page on this computer where the person pastes the code claude.ai shows (the agent never sees it). The code
+ * and Enter go into the PTY; the page says "Signed in" once the login exited 0. True when it did.
+ */
+export declare function runWorkspaceLoginHeadless(ctx: Ctx, cell: CellClient, login: {
+    session: string;
+    argv: string[];
+    env: Record<string, string>;
+    cwd: string;
+    urls: (output: string) => string[];
+}, timeoutMs: number): Promise<boolean>;
+/**
+ * A transient Linux profile holds the initial pair; it is removed before an agent starts. `headless` (0.20.1+): the
+ * sign-in runs through the pages shard opens (runWorkspaceLoginHeadless) instead of an attached terminal.
+ */
+export declare function loginClaudeInWorkspace(ctx: Ctx, ws: Workspace, opts?: {
+    headless?: {
+        timeoutMs: number;
+    };
+}): Promise<AgentCredentialMetadata>;
 export declare function ensureCloudClaude(ctx: Ctx, ws: Workspace): Promise<void>;

package/dist/claude-cloud-login.js

@@ -1,15 +1,21 @@
+import { StringDecoder } from 'node:string_decoder';
 import { isDeepStrictEqual } from 'node:util';
 import { ShardfluxApiError } from '@shardflux/sdk';
-import { UsageError } from "./errors.js";
+import { CodedError, UsageError } from "./errors.js";
 import { openUrl } from "./browser.js";
-import { attachTerminal, cellConnector, PtyOutputCursor, workspaceAsleep } from "./agent-terminal.js";
+import { attachTerminal, cellConnector, PtyOutputCursor, reattachDelayMs, retryableAttach, workspaceAsleep } from "./agent-terminal.js";
 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';
+import { announce, askInBrowser, openInBrowser } from "./secret-ask.js";
+const NEED_TERMINAL = 'Claude sign-in needed: run shard agents credentials login claude, once for the account (it opens the claude.ai sign-in and a page for its code).';
+const NEED_TERMINAL_HINT = 'a coding agent runs shard agents credentials login claude --json itself; its user signs in and pastes the code into the page it opens';
 const VERSION = '2.1.289';
-export function requireClaudeTerminal(ctx) {
+/** Someone types into this terminal: not --json, a TTY with raw mode, and not a coding agent's shell. */
+export function claudeTerminal(ctx) {
     // 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))
+    return !ctx.json && ctx.io.stdin.isTTY === true && typeof ctx.io.stdin.setRawMode === 'function' && typeof ctx.io.stdin.on === 'function' && !codingAgentShell(ctx.io.env);
+}
+export function requireClaudeTerminal(ctx) {
+    if (!claudeTerminal(ctx))
         throw new UsageError(NEED_TERMINAL, NEED_TERMINAL_HINT);
 }
 export async function cloudClaudeLogin(ctx) {
@@ -109,7 +115,7 @@ export async function runWorkspaceLogin(ctx, ws, cell, login) {
                             for (const url of login.urls(output))
                                 if (!opened.has(url)) {
                                     opened.add(url);
-                                    openUrl(url, ctx.io.env);
+                                    void openUrl(url, ctx.io.env);
                                 }
                         }
                         yield message;
@@ -121,9 +127,141 @@ export async function runWorkspaceLogin(ctx, ws, cell, login) {
     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);
+/** How long Claude may take to exchange the pasted code and exit. */
+const CODE_EXCHANGE_MS = 60_000;
+/**
+ * The same sign-in without an attached terminal (0.20.1+: a coding agent's shell, --json, no TTY). The workspace PTY
+ * runs the login exactly as runWorkspaceLogin does; shard reads its output, opens the claude.ai link it prints, and
+ * opens a page on this computer where the person pastes the code claude.ai shows (the agent never sees it). The code
+ * and Enter go into the PTY; the page says "Signed in" once the login exited 0. True when it did.
+ */
+export async function runWorkspaceLoginHeadless(ctx, cell, login, timeoutMs) {
+    await cell.pty.open({ session_id: login.session, argv: login.argv, env: login.env, cwd: login.cwd, rows: 24, cols: 100 });
+    const deadline = Date.now() + timeoutMs;
+    const stop = new AbortController();
+    const signal = AbortSignal.any([ctx.signal, stop.signal]);
+    // The PTY ended (or could not be read) before the code went in: the page closes with that.
+    const ended = new AbortController();
+    const connect = cellConnector(cell, login.session);
+    const cursor = new PtyOutputCursor();
+    const decoder = new StringDecoder('utf8');
+    const waiters = new Set();
+    const notify = () => { for (const wake of waiters)
+        wake(); waiters.clear(); };
+    let output = '';
+    let exit;
+    let failure;
+    let reading = true;
+    let codeSent = false;
+    const early = () => new CodedError('claude_sign_in_ended', 'The Claude sign-in ended before its code arrived.', 'run shard agents credentials login claude again');
+    const reader = (async () => {
+        let failures = 0;
+        while (!signal.aborted && exit === undefined) {
+            let connection;
+            try {
+                connection = await connect(cursor.offset, signal);
+                for await (const message of connection.messages()) {
+                    failures = 0;
+                    const bytes = cursor.consume(message);
+                    if (bytes?.length)
+                        output = (output + decoder.write(bytes)).slice(-16384);
+                    if (message.type === 'exit') {
+                        exit = message.session?.exit_code ?? null;
+                        if (!codeSent)
+                            ended.abort(early());
+                    }
+                    notify();
+                    if (exit !== undefined || signal.aborted)
+                        return;
+                }
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return;
+                if (!retryableAttach(error))
+                    throw error;
+                failures += 1;
+                await new Promise((resolve) => {
+                    const done = () => { clearTimeout(timer); signal.removeEventListener('abort', done); resolve(); };
+                    const timer = setTimeout(done, reattachDelayMs(error, failures));
+                    signal.addEventListener('abort', done, { once: true });
+                });
+            }
+            finally {
+                await connection?.close().catch(() => undefined);
+            }
+        }
+    })().catch((error) => {
+        failure = error;
+        if (!codeSent)
+            ended.abort(error instanceof Error ? error : early());
+    }).finally(() => { reading = false; notify(); });
+    /** Until `ready()`, at most `ms`: false when it did not happen (time out, or the reader stopped). */
+    const until = async (ready, ms) => {
+        const end = Date.now() + ms;
+        for (;;) {
+            if (ready())
+                return true;
+            if (failure !== undefined)
+                throw failure instanceof Error ? failure : new Error('The Claude sign-in terminal failed.');
+            if (!reading || Date.now() >= end)
+                return false;
+            await new Promise((resolve) => {
+                const timer = setTimeout(wake, end - Date.now());
+                function wake() { clearTimeout(timer); waiters.delete(wake); resolve(); }
+                waiters.add(wake);
+            });
+        }
+    };
+    try {
+        await until(() => login.urls(output).length > 0 || exit !== undefined, deadline - Date.now());
+        const url = login.urls(output)[0];
+        if (url === undefined)
+            return false;
+        const opened = await openInBrowser(ctx, url);
+        announce(ctx, { event: 'open', url, opened }, opened ? `Opened the Claude sign-in in your browser (or open: ${url})` : `Open the Claude sign-in: ${url}`);
+        await askInBrowser(ctx, {
+            kind: 'code',
+            title: 'Sign in to Claude',
+            purpose: 'Paste the code claude.ai shows after you sign in. Your coding agent never sees it.',
+            label: 'Code',
+            submit: 'Sign in',
+            done: 'Signed in to Claude',
+            failed: 'Not signed in',
+            link: { href: url, text: 'Open the Claude sign-in again' },
+            doing: 'to paste the Claude code',
+            event: 'ask',
+            maxBytes: 4096,
+            timeoutMs: Math.max(1_000, deadline - Date.now()),
+            signal: ended.signal,
+            // Once the code went in, the login either finishes or ends: there is nothing to retry on the page.
+            retry: () => false,
+            use: async (code) => {
+                if (exit !== undefined)
+                    throw early();
+                codeSent = true;
+                await cell.pty.input(login.session, `${code}\r`);
+                if (!await until(() => exit !== undefined, CODE_EXCHANGE_MS))
+                    throw new CodedError('claude_sign_in_timeout', 'Claude did not finish the sign-in within a minute of the code.', 'run shard agents credentials login claude again');
+                if (exit !== 0)
+                    throw new CodedError('claude_code_refused', `Claude did not accept the code (exit ${exit ?? 'by signal'}).`, 'run shard agents credentials login claude again for a new code');
+            },
+        });
+    }
+    finally {
+        stop.abort();
+        await reader;
+    }
+    const session = await cell.pty.get(login.session);
+    return session.state === 'exited' && session.exit_code === 0;
+}
+/**
+ * A transient Linux profile holds the initial pair; it is removed before an agent starts. `headless` (0.20.1+): the
+ * sign-in runs through the pages shard opens (runWorkspaceLoginHeadless) instead of an attached terminal.
+ */
+export async function loginClaudeInWorkspace(ctx, ws, opts = {}) {
+    if (!opts.headless)
+        requireClaudeTerminal(ctx);
     const api = ctx.cloud().agentCredentials;
     let claim;
     try {
@@ -147,7 +285,9 @@ 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.`);
-        if (!await runWorkspaceLogin(ctx, ws, cell, { session, argv: ['claude', 'auth', 'login', '--claudeai'], env, cwd: root, urls: claudeLoginUrls }))
+        const login = { session, argv: ['claude', 'auth', 'login', '--claudeai'], env, cwd: root, urls: claudeLoginUrls };
+        const signedIn = opts.headless ? await runWorkspaceLoginHeadless(ctx, cell, login, opts.headless.timeoutMs) : await runWorkspaceLogin(ctx, ws, cell, login);
+        if (!signedIn)
             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-forward.d.ts

@@ -13,6 +13,8 @@ export interface ForwarderOptions {
      * for once, so a URL that stays invalid is answered as is.
      */
     renew?: () => Promise<void>;
+    /** Called as each request (or upgrade) arrives, before it is forwarded: the hub is about to be awake. */
+    onRequest?: () => void;
     host?: string;
     port?: number;
     /** How long one request may be retried for (default 60 s, plus the time a repair takes). */

package/dist/cli-proxy-forward.js

@@ -97,8 +97,8 @@ export class CliProxyForwarder {
                 this.dropIdleConnections();
             tick = now;
         }, 5_000).unref();
-        this.#server = createServer((req, res) => void this.#handle(req, res));
-        this.#server.on('upgrade', (req, socket, head) => void this.#upgrade(req, socket, head));
+        this.#server = createServer((req, res) => { this.#arrived(); void this.#handle(req, res); });
+        this.#server.on('upgrade', (req, socket, head) => { this.#arrived(); void this.#upgrade(req, socket, head); });
         // Long streams (SSE, Responses) must not be cut by the server's own timeouts.
         this.#server.requestTimeout = 0;
         this.#server.headersTimeout = 60_000;
@@ -327,6 +327,13 @@ export class CliProxyForwarder {
             delay = Math.min(delay * 2, 8000);
         }
     }
+    /** onRequest never fails or delays a request. */
+    #arrived() {
+        try {
+            this.#o.onRequest?.();
+        }
+        catch { /* the hook is advisory */ }
+    }
     async #handle(req, res) {
         if (pathOnly(req.url) === IDENTITY_PATH) {
             const info = this.#o.hub();

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

@@ -32,24 +32,20 @@ export declare const HUB_TEMPLATE = "codex-connector";
 /**
  * The codex-connector version a hub runs at least: the first with the hub's boot service and an sf-agent that serves
  * the VM port (cli-proxy-filter). New hubs are created on it; an older hub is upgraded in place (its home, and so its
- * logins and settings, stay) before VMs get the hub's address.
+ * logins and settings, stay) before VMs get the hub's address. A hub on a newer version keeps it (never downgraded).
  */
 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";
-};
+/**
+ * Each provider's active login: `{ "<provider type>": "<auth file, relative to the auth directory>" }` (0600). The one
+ * login of each provider that stays enabled in the hub; every other login of that provider is kept there with
+ * `"disabled": true`. Written by the CLI and by the hub's sf-agent, both under the hub's `logins.lock`.
+ */
+export declare const HUB_ACTIVE_FILE = "/home/user/.cli-proxy-hub/active.json";
 export interface HubInfo {
     version: 1;
     api_url: string;
@@ -112,7 +108,10 @@ export interface HubWorkspace {
     write(path: string, data: string, mode: '0600' | '0700'): Promise<void>;
     /** Names in a directory, or null when it does not exist. */
     list(dir: string): Promise<string[] | null>;
-    /** The hub's auth files, as paths relative to its auth directory (subdirectories included, as CLIProxyAPI reads them). */
+    /**
+     * The hub's auth files, as paths relative to its auth directory (subdirectories included, as CLIProxyAPI reads them),
+     * oldest first: by modification time, then by path.
+     */
     authFiles(): Promise<string[]>;
     /** Exposes the port (idempotent): when its callback URL was created, null without one. */
     exposePort(port: number): Promise<{
@@ -167,6 +166,8 @@ export declare function sdkHubCloud(cloud: Shardflux, opts?: {
     agentLabel?: string;
     homeProject?: (organizationId: string) => Promise<HomeProject | null>;
 }): HubCloud;
+/** The hub's auth files, oldest first (modification time, then path in byte order), one relative path per line. */
+export declare const AUTH_FILES_SCRIPT = "set -euo pipefail\n[ -d /home/user/.cli-proxy-api ] || exit 0; cd /home/user/.cli-proxy-api\nfind . -type f -name '*.json' -printf '%T@ %P\\n' | LC_ALL=C sort -t ' ' -k1,1n -k2 | cut -d ' ' -f 2-\n";
 /** Installs the pinned release once: download, verify its SHA-256, then move the binary into place. */
 export declare const INSTALL_SCRIPT: string;
 /**
@@ -228,15 +229,6 @@ 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;
@@ -246,6 +238,8 @@ export interface EnsureResult {
     callbackReplaced: boolean;
     /** The config written now; null when the hub kept its own. */
     config: HubConfig | null;
+    /** The hub's logins, one active per provider (the others kept disabled). */
+    logins: HubLogin[];
 }
 /** The hub could not be made ready (exit 1, code `cli_proxy_hub`). */
 export declare class HubError extends CodedError {
@@ -258,11 +252,61 @@ export declare class HubError extends CodedError {
  */
 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.
+ * A login in the hub: one auth file. Only its provider, email and state are ever shown, never its tokens.
+ *
+ * CLIProxyAPI spreads requests across every enabled login of a provider (round-robin, fill-first) and moves to another
+ * one on a 429, so the hub keeps exactly one enabled per provider: the user's active login. Every other login of that
+ * provider stays in the hub with `"disabled": true` (CLIProxyAPI 8.0.23 never uses a disabled auth file) until the
+ * user makes it active (`shard cli-proxy use`).
+ */
+export interface HubLogin {
+    /** Path relative to the auth directory. */
+    file: string;
+    /** The auth file's `type` (claude, codex, gemini…), lowercase; null when it has none. */
+    provider: string | null;
+    email: string | null;
+    /** The file carries `"disabled": true`. */
+    disabled: boolean;
+    /** The one login of its provider that serves requests. */
+    active: boolean;
+}
+/** Parses active.json: provider type → auth file. Anything else (missing, not JSON, other values) counts as empty. */
+export declare function parseActive(text: string | null): Record<string, string>;
+/**
+ * The hub's logins, oldest first, as they are (nothing changes): `active` marks the one active.json names while it is
+ * enabled. Files the retired account pool router left are not listed (they stay disabled).
+ */
+export declare function listHubLogins(ws: HubWorkspace): Promise<HubLogin[]>;
+/** The auth file's text with `disabled` set (true) or removed (false), every other field kept; null when unchanged. */
+export declare function withDisabled(text: string, disabled: boolean): string | null;
+/**
+ * Replaces one auth file atomically (0600, a temporary file in its folder then rename), only while it still holds what
+ * the device read ($2, its SHA-256): CLIProxyAPI rewrites a file when it refreshes the login, and a newer token must
+ * never be overwritten. The modification time stays, so the order of the hub's logins (oldest first) does not change.
+ * $1 is the path relative to the auth directory, the new content comes on standard input. Prints `written`, `changed`
+ * or `gone`.
+ */
+export declare const SET_AUTH_SCRIPT = "set -euo pipefail\na=/home/user/.cli-proxy-api; rel=$1; want=$2\ncase \"$rel\" in ''|/*|*..*) echo \"not a path inside the auth folder\" >&2; exit 2 ;; esac\nf=\"$a/$rel\"\n[ -f \"$f\" ] || { echo gone; exit 0; }\ntmp=$(mktemp \"$(dirname \"$f\")/.writing.XXXXXX\"); trap 'rm -f \"$tmp\"' EXIT\nchmod 0600 \"$tmp\"; cat > \"$tmp\"; touch -r \"$f\" \"$tmp\"\nif [ \"$(sha256sum < \"$f\" | cut -d' ' -f1)\" != \"$want\" ]; then echo changed; exit 0; fi\nmv -f \"$tmp\" \"$f\"; trap - EXIT\necho written\n";
+/** Writes active.json atomically (0600) from standard input. */
+export declare const ACTIVE_SCRIPT = "set -euo pipefail\ndir=/home/user/.cli-proxy-hub; mkdir -p \"$dir\"; umask 077\ntmp=$(mktemp \"$dir/.active.XXXXXX\"); trap 'rm -f \"$tmp\"' EXIT\ncat > \"$tmp\"; mv -f \"$tmp\" \"$dir/active.json\"; trap - EXIT\necho written\n";
+/**
+ * Keeps exactly one login enabled per provider (call it under the hub's `logins` lock, so two computers do not race):
+ * `prefer[provider]` when given, else the one active.json names while it is present and enabled, else the oldest.
+ * active.json records the choice first, then every other login of that provider is disabled (all other fields kept), then
+ * the chosen one is enabled. Files without a `type` are left alone; the retired pool router's files are
+ * disabled and never chosen. Returns the logins as they are now, oldest first (without the pool router's).
+ */
+export declare function enforceActiveLogins(ws: HubWorkspace, prefer?: Record<string, string>): Promise<HubLogin[]>;
+/**
+ * One login per provider on a hub that may predate it, without waking the hub: a hub that is not running is left
+ * alone (it is checked again later). The forwarder on every connected computer runs this at start and every 15
+ * minutes, so a hub set up before this rule stops spreading requests across logins without anyone running a command.
  */
-export declare function poolHubConfig(text: string): string;
+export declare function enforceHubLoginsIfRunning(hub: HubCloud, workspaceId: string): Promise<'enforced' | 'asleep' | 'missing'>;
+/** Removes the router's files; prints `retired` when its hub token was there (its sf-agent then starts again without it). */
+export declare const RETIRE_POOL_SCRIPT: string;
+/** The config without the router's own client key (`api-keys`, or v8 `access.api-keys`); the text itself when absent. */
+export declare function withoutClientKey(text: string, key: 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;