@shardflux/cli 0.22.0 → 0.23.1

package/dist/cli-proxy.js

@@ -7,12 +7,12 @@
  * (only one copy may refresh a login), their auth files go to the hub (never printed), the forwarder takes 127.0.0.1:8317
  * and the machine template carries the hub info. Onboarding calls `detectLocalCliProxy()` and `importCliProxy(ctx)`.
  *
- * One login per provider serves requests (the user's active one, `shard cli-proxy use` switches it); the provider's
- * other logins stay in the hub, disabled, so CLIProxyAPI never moves a request to another account by itself.
+ * The hub is the user's own CLIProxyAPI: it routes requests across their logins as their config says, and each login
+ * stays enabled or disabled as they left it. `shard cli-proxy use` is their switch: one login for a provider, or all.
  */
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { connect } from 'node:net';
 import { homedir, userInfo } from 'node:os';
 import { basename, dirname, join } from 'node:path';
@@ -21,9 +21,9 @@ import { parse as parseYaml } from 'yaml';
 import { AgentStateStore } from "./agent-state.js";
 import { syncAgentConfig } from "./agent-config-sync.js";
 import { CliProxyForwarder, IDENTITY_PATH, hubInfoSource } from "./cli-proxy-forward.js";
-import { ADD_AUTH_SCRIPT, CLI_PROXY_PORT, CLI_PROXY_VM_PORT, HUB_ACTIVE_FILE, HUB_AUTH_DIR, HUB_KEY, HubError, SET_ASIDE_SCRIPT, STOP_SCRIPT, enforceActiveLogins, enforceHubLoginsIfRunning, ensureCliProxyHub, hubCallback, listHubLogins, parseActive, readHubInfo, sdkHubCloud, vmHubInfoText, withDisabled, writeHubInfo } from "./cli-proxy-hub.js";
+import { ADD_AUTH_SCRIPT, CLI_PROXY_PORT, CLI_PROXY_VM_PORT, HUB_AUTH_DIR, HUB_KEY, HubError, SET_ASIDE_SCRIPT, STOP_SCRIPT, ensureCliProxyHub, hubCallback, listHubLogins, readHubInfo, sdkHubCloud, useHubLogins, vmHubInfoText, writeHubInfo } from "./cli-proxy-hub.js";
 import { CLI_VERSION } from "./args.js";
-import { UsageError, describeError } from "./errors.js";
+import { UsageError } from "./errors.js";
 import { json } from "./format.js";
 import { progress } from "./progress.js";
 const execute = promisify(execFile);
@@ -634,14 +634,6 @@ function entryFile(f) {
         return f.path.slice(HUB_AUTH_DIR.length + 1);
     return [f.id, f.name].find((v) => typeof v === 'string' && v !== '') ?? null;
 }
-/**
- * Marks each provider's active login: an enabled login whose file is one of `activeFiles` (the hub's active.json).
- * Without them (unreadable), a provider's only enabled login is its active one.
- */
-export function markActive(accounts, activeFiles) {
-    const enabled = (p) => accounts.filter((a) => a.provider === p && !a.disabled).length;
-    return accounts.map((a) => ({ ...a, active: !a.disabled && (activeFiles ? a.file !== null && activeFiles.has(a.file) : enabled(a.provider) === 1) }));
-}
 /** The hub's logins from its management API (wakes the hub). */
 export async function hubAccounts(info, timeoutMs = 45_000) {
     const res = await fetch(new URL('v0/management/auth-files', info.callback_url), {
@@ -658,7 +650,7 @@ export async function hubAccounts(info, timeoutMs = 45_000) {
         status: typeof f.status === 'string' && f.status ? f.status : null,
         disabled: f.disabled === true,
         file: entryFile(f),
-        active: false,
+        active: f.disabled !== true,
     }));
 }
 /** Whether the hub answers /healthz through its callback URL, and the edge's reason when it does not. */
@@ -672,7 +664,7 @@ export async function hubHealth(info, timeoutMs = 45_000) {
         return { ok: false, reason: err.name === 'TimeoutError' ? 'timeout' : 'unreachable' };
     }
 }
-const accountLine = (a) => `  ${a.provider.padEnd(8)} ${a.email ?? '(no email)'}${a.active ? '  active' : ''}${a.disabled ? '  disabled' : a.status && a.status !== 'active' ? `  ${a.status}` : ''}`;
+const accountLine = (a) => `  ${a.provider.padEnd(8)} ${a.email ?? '(no email)'}${a.disabled ? '  disabled' : a.status && a.status !== 'active' ? `  ${a.status}` : ''}`;
 /** The logins a `--use` or `shard cli-proxy use` value names: by email (any case), path in the auth folder, or file name. */
 export function matchLogins(spec, logins) {
     const want = spec.trim().toLowerCase();
@@ -681,7 +673,8 @@ export function matchLogins(spec, logins) {
 const loginName = (l) => l.email ?? l.file;
 const refs = (logins, active) => logins.filter((l) => l.provider !== null && l.active === active).map((l) => ({ provider: l.provider, email: l.email, file: l.file }));
 /**
- * Resolves `--use` (repeatable): each value names one login per provider, on this computer or already in the hub.
+ * Resolves `--use` (repeatable): each value names the one login that serves its provider, on this computer or already
+ * in the hub.
  * Checked before anything changes, so a typo stops the import with the logins to pick from.
  */
 function resolveUse(specs, local, hub) {
@@ -710,23 +703,13 @@ function resolveUse(specs, local, hub) {
             const choice = here[0] ? { local: here[0].file, identity: here[0].identity } : { hub: there[0].file };
             const earlier = by.get(provider);
             if (earlier !== undefined && earlier !== spec)
-                throw new UsageError(`--use ${earlier} and --use ${spec} both name a ${provider} login; one login per provider is active.`, 'keep one --use per provider');
+                throw new UsageError(`--use ${earlier} and --use ${spec} both name a ${provider} login; --use names one login per provider.`, 'keep one --use per provider');
             by.set(provider, spec);
             out.set(provider, choice);
         }
     }
     return out;
 }
-/** When a local login was added: its birth time where the file system keeps one, else its last change. */
-function addedAt(path) {
-    try {
-        const st = statSync(path);
-        return st.birthtimeMs > 0 ? st.birthtimeMs : st.mtimeMs;
-    }
-    catch {
-        return Number.MAX_SAFE_INTEGER;
-    }
-}
 const useSpecs = (v) => (Array.isArray(v) ? v : typeof v === 'string' ? [v] : []).filter((x) => x.trim() !== '');
 /**
  * Moves CLIProxyAPI from this computer into the account (or connects this computer to the account's hub): ensure the
@@ -734,9 +717,9 @@ const useSpecs = (v) => (Array.isArray(v) ? v : typeof v === 'string' ? [v] : []
  * one: the hub's copy may hold a newer refresh token), start the forwarder on 127.0.0.1:8317 and put the hub info into
  * the machine template.
  *
- * One login per provider serves requests. `--use <email|file>` (repeatable, one per provider) picks it; otherwise a
- * provider the hub already serves keeps its active login, and a provider new to the hub starts with this computer's
- * oldest login of it. Every other login is uploaded with `"disabled": true` and kept in the hub.
+ * Each login arrives as it is on this computer (enabled or disabled), and the hub routes across the enabled ones as
+ * the user's config says. `--use <email|file>` (repeatable, one per provider) makes that login the only one serving
+ * its provider (the provider's others are kept in the hub, disabled), as `shard cli-proxy use` does.
  */
 export async function importCliProxy(ctx, opts = {}) {
     if (cliProxyTools.inVm()) {
@@ -817,8 +800,7 @@ export async function importCliProxy(ctx, opts = {}) {
             machine = { error: err instanceof Error ? err.message : String(err) };
         }
     }
-    const activeFiles = new Set(hubLogins.filter((l) => l.active).map((l) => l.file));
-    const accounts = await hubAccounts(ensured.info).then((a) => markActive(a, activeFiles), () => null);
+    const accounts = await hubAccounts(ensured.info).catch(() => null);
     return {
         hub: { workspace_id: ensured.info.workspace_id, created: ensured.created, process: ensured.process },
         logins: { uploaded, kept, added, already, moved_aside: movedAside.map((m) => m.to), active: refs(hubLogins, true), disabled: refs(hubLogins, false) },
@@ -826,57 +808,23 @@ export async function importCliProxy(ctx, opts = {}) {
     };
 }
 /**
- * Under the hub's logins lock: uploads this computer's logins the hub lacks (a login that is not its provider's active
- * one arrives with `"disabled": true`), then keeps one login per provider enabled. Returns the hub's logins after.
+ * Under the hub's logins lock: uploads this computer's logins the hub lacks, each as it is (enabled or disabled), then
+ * applies --use. Returns the hub's logins after.
  */
 async function uploadLogins(ws, local, use, out) {
     const inHub = new Map();
-    const providersInHub = new Set();
     const present = await ws.authFiles();
     for (const rel of present) {
         const text = await ws.read(`${HUB_AUTH_DIR}/${rel}`);
         const id = text === null ? `file:${rel}` : loginIdentity(text, rel);
         if (!inHub.has(id))
             inHub.set(id, rel);
-        const type = (() => { try {
-            const t = JSON.parse(text ?? '').type;
-            return typeof t === 'string' && t.trim() ? t.trim().toLowerCase() : null;
-        }
-        catch {
-            return null;
-        } })();
-        if (type && !/^sfa-[^/]+\.json$/.test(rel))
-            providersInHub.add(type);
     }
     const names = new Set(present);
-    const logins = (local?.logins ?? []).map((login) => {
-        const path = join(local.authDir, login.file);
-        const text = readFileSync(path, 'utf8');
-        let disabled = false;
-        try {
-            disabled = JSON.parse(text).disabled === true;
-        }
-        catch { /* not JSON */ }
-        return { ...login, text, identity: loginIdentity(text, login.file), at: addedAt(path), disabled };
-    });
-    // The identity each provider's active login has after this import: --use, else (a provider new to the hub) this
-    // computer's oldest enabled login of it, else its oldest. A provider the hub serves keeps its active login.
-    const target = new Map();
-    for (const [provider, choice] of use)
-        if ('local' in choice)
-            target.set(provider, choice.identity);
-    for (const l of [...logins].sort((a, b) => Number(a.disabled) - Number(b.disabled) || a.at - b.at || (a.file < b.file ? -1 : 1))) {
-        const p = l.provider?.toLowerCase();
-        if (p && !use.has(p) && !providersInHub.has(p) && !target.has(p))
-            target.set(p, l.identity);
-    }
-    for (const login of logins) {
-        const p = login.provider?.toLowerCase() ?? null;
-        // Only a provider new to the hub gets its chosen login enabled on upload. Next to a login the hub already serves,
-        // every upload arrives disabled (two enabled logins would fail over between each other); enforceActiveLogins below
-        // then disables the old one before it enables the chosen one.
-        const content = p === null || (target.get(p) === login.identity && !providersInHub.has(p)) ? login.text : (withDisabled(login.text, true) ?? login.text);
-        const r = inHub.has(login.identity) || names.has(login.file) ? null : await ws.sh(ADD_AUTH_SCRIPT, [login.file], { stdin: content });
+    for (const login of local?.logins ?? []) {
+        const text = readFileSync(join(local.authDir, login.file), 'utf8');
+        const identity = loginIdentity(text, login.file);
+        const r = inHub.has(identity) || names.has(login.file) ? null : await ws.sh(ADD_AUTH_SCRIPT, [login.file], { stdin: text });
         if (r && r.code !== 0)
             throw new HubError(`Could not add ${login.file} to the hub: ${r.stderr.trim().split('\n').at(-1) || `exit ${r.code}`}`, `run: ${AGAIN}`);
         if (!r || r.stdout.trim() === 'exists') {
@@ -886,19 +834,18 @@ async function uploadLogins(ws, local, use, out) {
         }
         out.uploaded.push(login.file);
         out.added.push({ provider: login.provider, email: login.email });
-        inHub.set(login.identity, login.file);
+        inHub.set(identity, login.file);
         names.add(login.file);
     }
-    const prefer = {};
+    if (!use.size)
+        return listHubLogins(ws);
+    const only = {};
     for (const [provider, choice] of use) {
         const file = 'hub' in choice ? choice.hub : inHub.get(choice.identity);
         if (file !== undefined)
-            prefer[provider] = file;
+            only[provider] = file;
     }
-    for (const [provider, identity] of target)
-        if (prefer[provider] === undefined && inHub.has(identity))
-            prefer[provider] = inHub.get(identity);
-    return enforceActiveLogins(ws, prefer);
+    return useHubLogins(ws, { only });
 }
 /**
  * Brings the hub's logins back to this computer: the hub stops first (from then on only this computer refreshes
@@ -978,72 +925,68 @@ async function exportHandler(ctx, values) {
     return 0;
 }
 /**
- * `shard cli-proxy use <email|file>`: makes that login its provider's active one in the hub (an email with a Claude
- * and a Codex login sets both); the provider's other logins stay in the hub, disabled. Under the hub's logins lock.
+ * `shard cli-proxy use <email|file>`: that login alone serves its provider (an email with a Claude and a Codex login
+ * sets both); the provider's other logins stay in the hub, disabled. `--all`: every login serves again, and the hub
+ * routes across them as its config says. Under the hub's logins lock.
  */
 export async function useCliProxyLogin(ctx, spec, opts = {}) {
     if (cliProxyTools.inVm())
         throw new UsageError('shard cli-proxy use runs on a computer connected to your hosted CLIProxyAPI; this is a Shardflux VM.', 'run it on that computer: shard cli-proxy use <email>');
-    if (!spec.trim())
-        throw new UsageError('Name the login to make active.', 'run: shard cli-proxy use <email>');
+    if (!opts.all && !spec.trim())
+        throw new UsageError('Name the login to use, or --all for every login.', 'run: shard cli-proxy use <email>');
+    if (opts.all && spec.trim())
+        throw new UsageError('Name a login or use --all, not both.', 'run: shard cli-proxy use --all');
     const hub = opts.hub ?? sdkHubCloud(ctx.cloud(), { signal: ctx.signal, wakeTimeoutMs: ctx.wakeTimeoutMs, agentLabel: ctx.agentLabel });
     const opened = await hub.open(false);
     if (!opened)
         throw new UsageError('This account has no hosted CLIProxyAPI yet.', `move yours: ${AGAIN}`);
     return opened.ws.withLock('logins', async () => {
         const before = await listHubLogins(opened.ws);
+        if (opts.all) {
+            const after = await useHubLogins(opened.ws, { all: true });
+            return { switched: [], active: refs(after, true), disabled: refs(after, false) };
+        }
         const matches = matchLogins(spec, before);
         if (!matches.length) {
             const all = before.filter((l) => l.provider).map((l) => `${l.provider} ${loginName(l)}`);
             throw new UsageError(`No login in your hosted CLIProxyAPI matches ${spec}.`, all.length ? `pick one of: ${all.join(', ')}` : `add yours: ${AGAIN}`);
         }
-        const prefer = {};
+        const only = {};
         for (const provider of new Set(matches.map((l) => l.provider))) {
             const mine = matches.filter((l) => l.provider === provider);
             if (mine.length > 1)
                 throw new UsageError(`${spec} matches more than one ${provider} login (${mine.map((l) => l.file).join(', ')}).`, 'name one by its file name: shard cli-proxy use <file>');
-            prefer[provider] = mine[0].file;
+            only[provider] = mine[0].file;
         }
-        const after = await enforceActiveLogins(opened.ws, prefer);
+        const after = await useHubLogins(opened.ws, { only });
         const ref = (l) => ({ provider: l.provider, email: l.email, file: l.file });
-        const switched = Object.entries(prefer).map(([provider, file]) => {
-            const was = before.find((l) => l.provider === provider && l.active);
-            return { provider, from: was ? ref(was) : null, to: ref(after.find((l) => l.file === file)) };
+        const switched = Object.entries(only).map(([provider, file]) => {
+            const was = before.filter((l) => l.provider === provider && l.active);
+            return { provider, from: was.length === 1 ? ref(was[0]) : null, to: ref(after.find((l) => l.file === file)) };
         });
         return { switched, active: refs(after, true), disabled: refs(after, false) };
     });
 }
 async function useHandler(ctx, values, positionals) {
     const spec = positionals[0] ?? (typeof values.login === 'string' ? values.login : '');
-    const r = await useCliProxyLogin(ctx, spec);
+    const r = await useCliProxyLogin(ctx, spec, { all: values.all === true });
     if (ctx.json) {
         ctx.io.stdout.write(json(r));
         return 0;
     }
-    const lines = r.switched.map((s) => (s.from?.file === s.to.file
-        ? `${loginName(s.to)} is already your active ${s.provider} login.`
-        : `Active ${s.provider} login: ${loginName(s.to)}. Claude Code, Codex and T3 Code use it from their next request.`));
+    const lines = values.all === true
+        ? [`Every login serves requests, routed as your CLIProxyAPI config says: ${r.active.map((l) => `${l.provider} ${loginName(l)}`).join(', ') || 'none yet'}.`]
+        : r.switched.map((s) => (s.from?.file === s.to.file
+            ? `${loginName(s.to)} already serves your ${s.provider} requests.`
+            : `${loginName(s.to)} serves your ${s.provider} requests now. Claude Code, Codex and T3 Code use it from their next request.`));
     for (const provider of new Set(r.switched.map((s) => s.provider))) {
         const others = r.disabled.filter((l) => l.provider === provider);
         if (others.length)
-            lines.push(`Kept in the hub, disabled: ${others.map(loginName).join(', ')}.`);
+            lines.push(`Kept in the hub, disabled: ${others.map(loginName).join(', ')}. Use them all again: shard cli-proxy use --all`);
     }
     ctx.io.stdout.write(`${lines.join('\n')}\n`);
     return 0;
 }
-/** The hub's active.json as a set of files (null when it cannot be read: status then marks a provider's only enabled login). */
-async function activeFilesOf(hub) {
-    try {
-        const opened = await hub.open(false);
-        if (!opened)
-            return null;
-        const text = await opened.ws.read(HUB_ACTIVE_FILE);
-        return text === null ? null : new Set(Object.values(parseActive(text)));
-    }
-    catch {
-        return null;
-    }
-}
 // ---- handlers ------------------------------------------------------------------------------------------------------
 function statusLines(state, accounts, forwarding, launchd, machineVersion) {
     const hub = state === null ? 'missing (run shard cli-proxy import)' : state === 'running' ? 'running' : ['suspended', 'parked', 'stopped'].includes(state) ? 'sleeping (wakes on the next request)' : state;
@@ -1125,8 +1068,6 @@ async function status(ctx, values) {
         }
         if (health.ok)
             accounts = await hubAccounts(info).catch(() => null);
-        if (accounts)
-            accounts = markActive(accounts, await activeFilesOf(hub));
     }
     const identity = await cliProxyTools.identity();
     const launchd = existsSync(forwarderPlistPath(ctx.io.env.HOME || homedir()));
@@ -1154,8 +1095,7 @@ async function importHandler(ctx, values) {
         ...(r.config === 'kept' ? ['The hub keeps its settings (client keys, routing, upstream keys).'] : []),
         ...r.logins.moved_aside.map((dir) => `This computer’s auth files are in ${dir} now, where no CLIProxyAPI reads them.`),
         ...(r.port !== CLI_PROXY_PORT ? [`Point tools that used http://127.0.0.1:${r.port} at http://127.0.0.1:${CLI_PROXY_PORT}.`] : []),
-        ...(r.logins.active.length ? [`Active logins: ${r.logins.active.map((l) => `${l.provider} ${loginName(l)}`).join(', ')}.`] : []),
-        ...(r.logins.disabled.length ? [`Kept in the hub, disabled: ${r.logins.disabled.map((l) => `${l.provider} ${loginName(l)}`).join(', ')}. Switch any time: shard cli-proxy use <email>`] : []),
+        ...(r.logins.disabled.length ? [`Kept in the hub, disabled: ${r.logins.disabled.map((l) => `${l.provider} ${loginName(l)}`).join(', ')}. Use them too: shard cli-proxy use --all`] : []),
         ...(r.accounts ? [`Accounts: ${r.accounts.length}`, ...r.accounts.map(accountLine)] : []),
         r.forwarder.launchd ? `This computer: http://127.0.0.1:${CLI_PROXY_PORT} forwards to it (starts at login).` : `This computer: run shard cli-proxy forward to reach it at http://127.0.0.1:${CLI_PROXY_PORT}.`,
         r.machine && 'version' in r.machine ? `VMs: every new VM reaches it at http://127.0.0.1:${CLI_PROXY_PORT} (machine version ${r.machine.version}).` : '',
@@ -1169,12 +1109,9 @@ async function importHandler(ctx, values) {
 async function forwardHandler(ctx) {
     const source = hubInfoSource(ctx.store.dir);
     const log = (line) => void ctx.io.stderr.write(`${new Date().toISOString()} ${line}\n`);
-    let checks = null;
     const forwarder = new CliProxyForwarder({
         hub: source,
         log,
-        // The first request after the hub slept: check its logins as it wakes.
-        onRequest: () => checks?.nudge(),
         repair: async () => {
             const info = source();
             if (!info || info.api_url !== ctx.apiUrl)
@@ -1192,68 +1129,14 @@ async function forwardHandler(ctx) {
     if (!source())
         log('not connected to a hosted CLIProxyAPI yet; answering 503 until shard cli-proxy import connects this computer');
     await forwarder.listen();
-    checks = hubLoginChecks(ctx, source, log);
     await new Promise((resolve) => {
         if (ctx.signal.aborted)
             return resolve();
         ctx.signal.addEventListener('abort', () => resolve(), { once: true });
     });
-    checks.stop();
     await forwarder.close();
     return 0;
 }
-/** How often the forwarder checks that the hub serves one login per provider while it runs. */
-export const HUB_LOGIN_CHECK_MS = 15 * 60_000;
-/** How soon it looks again when the hub was asleep (a VM's request may wake it any moment; looking never wakes it). */
-export const HUB_LOGIN_ASLEEP_MS = 60_000;
-/** The least time between two checks a request asks for (requests come in bursts). */
-export const HUB_LOGIN_NUDGE_MS = 10_000;
-/**
- * The forwarder's check that the hub serves one login per provider (enforceHubLoginsIfRunning), never waking the hub:
- * at start; then every HUB_LOGIN_CHECK_MS while it runs and every HUB_LOGIN_ASLEEP_MS while it sleeps; and at the first
- * request after it slept (nudge), so a hub set up before one login per provider cannot fail over between logins for
- * long after it wakes. One check at a time.
- */
-export function hubLoginChecks(ctx, source, log, opts = {}) {
-    const everyMs = opts.everyMs ?? HUB_LOGIN_CHECK_MS, asleepMs = opts.asleepMs ?? HUB_LOGIN_ASLEEP_MS, nudgeMs = opts.nudgeMs ?? HUB_LOGIN_NUDGE_MS;
-    let running = false, stopped = false, last = null, lastAt = 0;
-    let timer;
-    const schedule = (ms) => { clearTimeout(timer); if (!stopped) {
-        timer = setTimeout(() => void check(), ms);
-        timer.unref?.();
-    } };
-    const check = async () => {
-        const info = source();
-        if (running || stopped)
-            return;
-        if (!info || info.api_url !== ctx.apiUrl) {
-            schedule(everyMs);
-            return;
-        }
-        running = true;
-        try {
-            const hub = opts.hub ?? sdkHubCloud(ctx.cloud(), { signal: ctx.signal, wakeTimeoutMs: ctx.wakeTimeoutMs, agentLabel: ctx.agentLabel });
-            last = await enforceHubLoginsIfRunning(hub, info.workspace_id);
-            if (last === 'enforced')
-                log('the hub serves one login per provider');
-        }
-        catch (err) {
-            last = 'failed';
-            log(`could not check the hub's logins (${describeError(err).message}); checking again soon`);
-        }
-        finally {
-            running = false;
-            lastAt = Date.now();
-            schedule(last === 'enforced' || last === 'missing' ? everyMs : asleepMs);
-        }
-    };
-    void check();
-    return {
-        nudge() { if (!running && !stopped && (last !== 'enforced' || Date.now() - lastAt >= everyMs) && Date.now() - lastAt >= nudgeMs)
-            void check(); },
-        stop() { stopped = true; clearTimeout(timer); },
-    };
-}
 /**
  * After the edge refused the hub's callback URL (`callback_invalid`: the API key that created it was revoked):
  * replaces the URLs the edge refuses (under the hub's lock), saves them locally and gives VMs the new VM address.

package/dist/codex-cloud.d.ts

@@ -5,11 +5,16 @@ import type { ModelChoice } from './agent-models.js';
 import type { Conversation } from './conversations.js';
 import type { LocalConversation } from './conversations.js';
 import type { InitialImage } from './initial-prompt.js';
-/** Only provider-returned task ids enter the registered Codex deep-link route. */
-export declare function openCodexThread(task: CodexCloudTask, env: Ctx['io']['env']): Promise<void>;
+/** Cloud threads open in the browser, preserving the durable provider destination on every OS. */
+export declare function openCodexThread(task: CodexCloudTask, env: Ctx['io']['env'], platform?: NodeJS.Platform): Promise<void>;
 export declare function submitCloudInitialPrompt(ctx: Ctx, c: Conversation, prompt: string, workspaceKey: string): Promise<void>;
-/** Prints the Cloud thread (and its link) and opens it in the Codex app; --json prints it instead. */
+/** Prints the Cloud thread (and its link) and opens it in your browser; --json prints it instead. */
 export declare function printCloudThread(ctx: Ctx, c: Conversation, task: CodexCloudTask, submitted?: boolean, choice?: ModelChoice): Promise<void>;
+/**
+ * A Cloud conversation where the Codex app cannot show it (0.23.0+): where its chat lives, whether it waits for an
+ * answer, and how to answer and follow it from here. Never a new start: the conversation exists.
+ */
+export declare function cloudChatElsewhere(c: Pick<Conversation, 'id' | 'key' | 'state'>, url: string): string;
 /** How long the account's Codex remote device may take to come up before it counts as stuck. */
 export declare const CODEX_STARTING_LIMIT_MS: number;
 export type CodexConnectorView = {
@@ -51,7 +56,7 @@ export declare function ensureCodexCloud(ctx: Ctx): Promise<{
 export declare function launchCodexCloud(ctx: Ctx, values: Values, path: string, images?: readonly InitialImage[]): Promise<number>;
 /** A start whose carrying process said so in the last 45 s. */
 export declare const startCarried: (start: NonNullable<LocalConversation["cloud_start"]>) => boolean;
-export declare function openCodexConversation(ctx: Ctx, c: Conversation): Promise<number>;
+export declare function openCodexConversation(ctx: Ctx, c: Conversation, history?: true | string): Promise<number>;
 /** Continues the same accepted identity, never creates a replacement VM/chat. */
 export declare function resumeCloudStartup(ctx: Ctx, c: Conversation): Promise<CodexCloudTask>;
 export declare const CODEX_CLOUD_HANDLERS: Record<string, Handler>;

package/dist/codex-cloud.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { CodedError, UsageError } from "./errors.js";
 import { json } from "./format.js";
@@ -5,25 +6,29 @@ import { syncAgentCredentials } from "./agent-credentials.js";
 import { createConversation, conversationWorkspace, getConversation, localConversations, recordedChoice, resumeConversation, seedConversation } from "./conversations.js";
 import { CHOICE_PENDING, choiceReport, hasChoice, modelChoice } from "./agent-models.js";
 import { AgentStateStore } from "./agent-state.js";
+import { installedTargets } from "./agent-targets.js";
 import { ensureProjectGit } from "./project-git.js";
 import { gitRunner } from "./agent-git.js";
 import { projectIdentity } from "./project-identity.js";
 import { uploadInitialImages } from "./initial-prompt.js";
-/** Only provider-returned task ids enter the registered Codex deep-link route. */
-export async function openCodexThread(task, env) {
+/** Cloud threads open in the browser, preserving the durable provider destination on every OS. */
+export async function openCodexThread(task, env, platform = process.platform) {
     const url = threadLink(task);
-    const program = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'rundll32' : 'xdg-open';
-    const args = process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url];
+    const program = platform === 'darwin' ? 'open' : platform === 'win32' ? 'rundll32' : 'xdg-open';
+    const args = platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url];
     const child = spawn(program, args, { env, stdio: 'ignore' });
-    await new Promise((resolve, reject) => { const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('Codex app did not open in time')); }, 10000); child.once('error', error => { clearTimeout(timer); reject(error); }); child.once('exit', code => { clearTimeout(timer); if (code === 0)
+    await new Promise((resolve, reject) => { const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('Cloud chat did not open in time')); }, 10000); child.once('error', error => { clearTimeout(timer); reject(error); }); child.once('exit', code => { clearTimeout(timer); if (code === 0)
         resolve();
     else
-        reject(new Error(`Open this Cloud thread in Codex: ${task.desktop_url}`)); }); });
+        reject(new Error(`Open this Cloud thread: ${url}`)); }); });
 }
 function threadLink(task) {
-    if (!task.thread_id || !/^[a-zA-Z0-9_-]{1,128}$/.test(task.thread_id) || task.desktop_url !== `codex://threads/${encodeURIComponent(task.thread_id)}?hostId=durable`)
+    if (!task.thread_id || !/^[a-zA-Z0-9_-]{1,128}$/.test(task.thread_id))
         throw new Error('Cloud returned an invalid Codex thread link');
-    return task.desktop_url;
+    const url = `https://chatgpt.com/local/${encodeURIComponent(task.thread_id)}`;
+    if (task.web_url != null && task.web_url !== url || task.desktop_url != null && task.desktop_url !== `codex://threads/${encodeURIComponent(task.thread_id)}?hostId=durable`)
+        throw new Error('Cloud returned an invalid Codex thread link');
+    return url;
 }
 export async function submitCloudInitialPrompt(ctx, c, prompt, workspaceKey) {
     try {
@@ -33,19 +38,32 @@ export async function submitCloudInitialPrompt(ctx, c, prompt, workspaceKey) {
         throw new CodedError('initial_prompt_failed', `Created ${workspaceKey}, but the initial prompt could not be confirmed. Open that conversation before starting another.`, undefined, { workspace_key: workspaceKey, conversation_id: c.id, submitted: null });
     }
 }
-/** Prints the Cloud thread (and its link) and opens it in the Codex app; --json prints it instead. */
+/** Prints the Cloud thread (and its link) and opens it in your browser; --json prints it instead. */
 export async function printCloudThread(ctx, c, task, submitted = false, choice) { return output(ctx, c, task, submitted, choice); }
+/** Whether this computer has the Codex app, which opens a Cloud thread's codex:// link (on Linux 0.23.0+). */
+const codexAppHere = (env) => installedTargets(env ?? {}).clients.includes('codex-app');
+/**
+ * A Cloud conversation where the Codex app cannot show it (0.23.0+): where its chat lives, whether it waits for an
+ * answer, and how to answer and follow it from here. Never a new start: the conversation exists.
+ */
+export function cloudChatElsewhere(c, url) {
+    return `${c.key} runs in Codex Cloud${c.state === 'needs_you' ? ' and is waiting for your answer' : ''}. Its chat opens in your browser: ${url}\n` +
+        `Answer it from here: shard conversations send ${c.id} "<your answer>"\nWhere it stands: shard conversations get ${c.id}\n`;
+}
 async function output(ctx, c, task, submitted = false, choice) {
-    const url = threadLink(task);
+    const url = threadLink(task), app = codexAppHere(ctx.io.env);
     // model_choice (0.17.0+): an admitted thread's record keeps the model and effort only when Cloud started it with them.
     const applied = hasChoice(choice) ? await cloudChoiceApplied(ctx, c, choice) : true;
+    // codex_app and reply_command (0.23.0+): without the Codex app, the conversation is answered with that command.
     if (ctx.json) {
-        ctx.io.stdout.write(json({ conversation: c, cloud: task, url, ...(submitted ? { initial_prompt: { submitted: true } } : {}), ...(hasChoice(choice) ? { model_choice: choiceReport(choice, applied) } : {}) }));
+        ctx.io.stdout.write(json({ conversation: c, cloud: task, url, previous_threads: (task.previous_thread_ids ?? []).map(id => ({ thread_id: id, url: threadLink({ thread_id: id }) })), codex_app: app, reply_command: ['shard', 'conversations', 'send', c.id, '<message>'], ...(submitted ? { initial_prompt: { submitted: true } } : {}), ...(hasChoice(choice) ? { model_choice: choiceReport(choice, applied) } : {}) }));
         return;
     }
     if (!applied)
         ctx.io.stderr.write(`${CHOICE_PENDING}\n`);
-    ctx.io.stdout.write(`${c.key}\n${task.desktop_url}\n`);
+    ctx.io.stdout.write(`${c.key}\n${url}\n`);
+    for (const id of task.previous_thread_ids ?? [])
+        ctx.io.stdout.write(`Earlier history: https://chatgpt.com/local/${encodeURIComponent(id)}\n`);
     await openCodexThread(task, ctx.io.env);
 }
 async function cloudChoiceApplied(ctx, c, choice) {
@@ -183,7 +201,14 @@ function carryStart(ctx, id) {
 }
 /** A start whose carrying process said so in the last 45 s. */
 export const startCarried = (start) => Date.now() - (start.heartbeat_at ?? 0) < 45_000;
-export async function openCodexConversation(ctx, c) {
+export async function openCodexConversation(ctx, c, history) {
+    if (history) {
+        const task = await ctx.cloud().codex.task(c.id), ids = task.previous_thread_ids ?? [];
+        const id = history === true ? ids[0] : history;
+        if (!id || !ids.includes(id))
+            throw new UsageError('This conversation has no matching earlier Cloud history.');
+        return output(ctx, c, { ...task, thread_id: id, desktop_url: null, web_url: null }, false).then(() => 0);
+    }
     const local = localConversations(ctx)[c.id];
     if (local?.cloud_start && local.cloud_start.state !== 'active' && !c.ended_at) {
         const task = await resumeCloudStartup(ctx, c);
@@ -197,7 +222,15 @@ export async function openCodexConversation(ctx, c) {
         await output(ctx, c, task);
         return 0;
     }
-    const task = await ctx.cloud().codex.task(c.id);
+    let task = await ctx.cloud().codex.task(c.id);
+    // A thread a connector change stopped (Codex Cloud turned off and on, or the active Codex account switched) continues
+    // in a new Cloud thread of this same conversation, on its VM and branch: an API that admits it again does so on
+    // request (0.23.0+); an older one answers with the stopped thread.
+    if (task.state === 'canceled') {
+        task = await ctx.cloud().codex.admit(c.id, { idempotencyKey: `codex-readmit-${c.id}-${randomUUID()}`, signal: ctx.signal });
+        if (task.state !== 'canceled')
+            task = await ctx.cloud().codex.waitTask(c.id, { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+    }
     if (task.state === 'canceled')
         throw new UsageError('This conversation’s Codex executor was removed. Start a new Cloud conversation; its saved branch and history remain available.');
     if (task.state !== 'active' || !task.thread_id)

package/dist/codex-linux.d.ts

@@ -0,0 +1,14 @@
+type Env = Record<string, string | undefined>;
+/** A Codex app install: its desktop entry and that entry's Exec as argv (field codes removed). */
+export interface LinuxCodexApp {
+    desktop_id: string;
+    exec: string[];
+}
+/** The installed Codex apps: entries that handle codex:// and whose program exists. The first entry with an id wins (XDG precedence). */
+export declare function linuxCodexApps(dirs: string[], env: Env): LinuxCodexApp[];
+/**
+ * Opens a codex:// link in that install, as the desktop does: its Exec with the link. Detached, so a cold start keeps
+ * running after `shard` exits; a running app takes the link in its window.
+ */
+export declare function openLinuxCodexLink(app: LinuxCodexApp, url: string, env: Env): Promise<void>;
+export {};

package/dist/codex-linux.js

@@ -0,0 +1,69 @@
+/**
+ * The Codex app on Linux (0.23.0+): OpenAI's ChatGPT app for Linux (package `chatgpt`: `chatgpt.desktop`,
+ * `Exec=chatgpt %U`) and community builds (`codex-desktop.desktop`) register the codex:// scheme, which opens a Codex
+ * thread (`codex://threads/<id>?hostId=durable` for a Cloud conversation). The app is the desktop entry in the XDG
+ * application folders (linuxApplicationDirs) that handles x-scheme-handler/codex.
+ */
+import { spawn } from 'node:child_process';
+import { accessSync, constants, readFileSync, readdirSync, statSync } from 'node:fs';
+import { delimiter, isAbsolute, join } from 'node:path';
+import { desktopEntry, desktopExec, t3OpenEnv } from "./t3-linux.js";
+/** Entry names worth reading (every entry in the folders would be hundreds of files on each `shard` run). */
+const MAYBE_ENTRY = /chatgpt|codex|openai/i;
+const executable = (path) => { try {
+    accessSync(path, constants.X_OK);
+    return statSync(path).isFile();
+}
+catch {
+    return false;
+} };
+const onPath = (name, env) => isAbsolute(name) ? executable(name) : (env.PATH ?? '').split(delimiter).filter(Boolean).some(dir => executable(join(dir, name)));
+/** The installed Codex apps: entries that handle codex:// and whose program exists. The first entry with an id wins (XDG precedence). */
+export function linuxCodexApps(dirs, env) {
+    const found = [], ids = new Set();
+    for (const dir of dirs) {
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (!name.endsWith('.desktop') || !MAYBE_ENTRY.test(name) || ids.has(name))
+                continue;
+            let text;
+            try {
+                text = readFileSync(join(dir, name), 'utf8');
+            }
+            catch {
+                continue;
+            }
+            ids.add(name);
+            const e = desktopEntry(text);
+            if (e.Hidden === 'true' || (e.Type ?? 'Application') !== 'Application' || !(e.MimeType ?? '').split(';').includes('x-scheme-handler/codex'))
+                continue;
+            if (e.TryExec && !onPath(e.TryExec, env))
+                continue;
+            const exec = desktopExec(e.Exec ?? '');
+            // `env VAR=value /usr/bin/codex-desktop %u` (a community entry): the program after the assignments must exist.
+            const program = exec?.[0] === 'env' ? exec.slice(1).find(a => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(a)) : exec?.[0];
+            if (!exec?.length || !program || !onPath(program, env))
+                continue;
+            found.push({ desktop_id: name, exec });
+        }
+    }
+    return found;
+}
+/**
+ * Opens a codex:// link in that install, as the desktop does: its Exec with the link. Detached, so a cold start keeps
+ * running after `shard` exits; a running app takes the link in its window.
+ */
+export async function openLinuxCodexLink(app, url, env) {
+    const [command, ...args] = app.exec;
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, [...args, url], { env: t3OpenEnv(env), stdio: 'ignore', detached: true });
+        child.once('spawn', () => { child.unref(); resolve(); });
+        child.once('error', reject);
+    });
+}