@shardflux/cli 0.15.2 → 0.17.0

package/dist/cli-proxy-hub.js

@@ -0,0 +1,749 @@
+/**
+ * The account's hosted CLIProxyAPI ("hub"): one copy of router-for-me/CLIProxyAPI per account, in a small workspace
+ * (`shardflux/cli-proxy`) that sleeps between requests and wakes on a request to its port. Every device reaches it
+ * through a forwarder on 127.0.0.1:8317 (cli-proxy-forward.ts here, `sf-agent cli-proxy-forward` in VMs) that sends
+ * each request to the port's callback URL.
+ *
+ * Exactly one copy may run per account: CLIProxyAPI rotates the subscription refresh tokens in its auth files and never
+ * re-reads them, so two copies of one login sign each other out. Ensuring the hub is therefore idempotent and
+ * serialized in the hub itself (flock), and auth files already on the hub are never overwritten.
+ *
+ * Hub info (`cli-proxy.json`, 0600, in the config directory, in the hub and in the machine template so every VM has
+ * it): { version, api_url, workspace_id, callback_url, callback_created_at, management_key }. Never printed or logged.
+ */
+import { randomBytes } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Document, isMap, parseDocument } from 'yaml';
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { writePrivateFile } from "./credentials.js";
+import { CodedError, UsageError } from "./errors.js";
+/** The pinned CLIProxyAPI release and the SHA-256 of its Linux assets (verified in the hub before install). */
+export const CLI_PROXY_VERSION = '8.0.23';
+export const CLI_PROXY_ASSETS = {
+    x86_64: { asset: 'linux_amd64', sha256: '744000a1a4f9ce19f5964774f853d029797b87ef53796d054389258c66cb1224' },
+    aarch64: { asset: 'linux_aarch64', sha256: '7c54c9306167b3e252090924c39a9b9dd5c09dffd376551271d8902f391f0246' },
+};
+export const CLI_PROXY_PORT = 8317;
+/**
+ * The hub's VM port: `sf-agent cli-proxy-filter` in front of 8317 without the management API. VMs receive only this
+ * port's callback URL; 8317's (the management port) stays with the computers that imported the hub.
+ */
+export const CLI_PROXY_VM_PORT = 8318;
+/** The hub's workspace key in the API key's project, and its labels. */
+export const HUB_KEY = 'shardflux/cli-proxy';
+export const HUB_LABELS = { shard_role: 'cli_proxy' };
+/**
+ * `codex-connector`: the smallest fleet template (256 MiB fixed, 1 vCPU, 2 GiB disk) with curl, coreutils, util-linux
+ * and CA roots, which is all a single Go binary needs; `coding` would hold 2 GiB and start Docker, SSH and the agent
+ * services for nothing.
+ */
+export 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.
+ */
+export const HUB_TEMPLATE_VERSION = 4;
+export const HUB_CAPS = { cpu_millis: 1000, memory_mib: 256, disk_gib: 2, allocation_mode: 'fixed' };
+export const HUB_INFO_FILE = 'cli-proxy.json';
+/** Paths in the hub workspace. */
+export const HUB_DIR = '/home/user/.cli-proxy-hub';
+export const HUB_AUTH_DIR = '/home/user/.cli-proxy-api';
+const CALLBACK_PATH = /^\/__shardflux\/callback\/sfcb_[A-Za-z0-9_-]+\/$/;
+function callbackUrlOk(cb) {
+    try {
+        const u = new URL(cb);
+        const loopback = ['127.0.0.1', 'localhost', '[::1]'].includes(u.hostname);
+        return (u.protocol === 'https:' || (u.protocol === 'http:' && loopback)) && CALLBACK_PATH.test(u.pathname) && !u.search && !u.hash;
+    }
+    catch {
+        return false;
+    }
+}
+/** The hub info in `text`, or null when it is not a valid one (an unreadable file is treated as absent). */
+export function parseHubInfo(text) {
+    let v;
+    try {
+        v = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!v || typeof v !== 'object')
+        return null;
+    const o = v;
+    const str = (k) => { const v = o[k]; return typeof v === 'string' && v.length > 0 ? v : null; };
+    const [api, id, cb, at, mk] = [str('api_url'), str('workspace_id'), str('callback_url'), str('callback_created_at'), str('management_key')];
+    if (o.version !== 1 || !api || !id || !cb || !at || !mk || !callbackUrlOk(cb))
+        return null;
+    const [vcb, vat] = [str('vm_callback_url'), str('vm_callback_created_at')];
+    const vm = vcb && vat && callbackUrlOk(vcb) ? { vm_callback_url: vcb, vm_callback_created_at: vat } : {};
+    return { version: 1, api_url: api, workspace_id: id, callback_url: cb, callback_created_at: at, management_key: mk, ...vm };
+}
+export function hubInfoPath(dir) {
+    return join(dir, HUB_INFO_FILE);
+}
+/** The saved hub info for `apiUrl` (any API URL when omitted), or null. */
+export function readHubInfo(dir, apiUrl) {
+    let text;
+    try {
+        text = readFileSync(hubInfoPath(dir), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const info = parseHubInfo(text);
+    return info && (apiUrl === undefined || info.api_url === apiUrl) ? info : null;
+}
+export function hubInfoText(info) {
+    return `${JSON.stringify(info, null, 2)}\n`;
+}
+/**
+ * What every VM receives (in the machine template): the VM port's (8318) callback URL, which serves CLIProxyAPI
+ * without its management API, and nothing else secret. The management key and the management port's URL stay on the
+ * computers that imported the hub, so no agent in a VM reaches the hub's auth files, whatever key it finds. Null
+ * while the hub does not serve the VM port.
+ */
+export function vmHubInfoText(info) {
+    // The VM port's URL only: the management port's (8317) never leaves the computers that imported the hub.
+    if (!info.vm_callback_url || !info.vm_callback_created_at)
+        return null;
+    const { version, api_url, workspace_id } = info;
+    return `${JSON.stringify({ version, api_url, workspace_id, callback_url: info.vm_callback_url, callback_created_at: info.vm_callback_created_at }, null, 2)}\n`;
+}
+export function writeHubInfo(dir, info) {
+    writePrivateFile(dir, hubInfoPath(dir), hubInfoText(info));
+}
+/** Top-level sections only the v8 (nested) layout has (`routing`, `models` and `plugins` are in both). */
+const V8_SECTIONS = ['server', 'management', 'access', 'oauth', 'requests', 'observability', 'upstream', 'multimedia', 'credentials', 'client'];
+/** Each setting the hub sets (`value`) or leaves out: its path in the legacy (flat) layout and in the v8 layout. */
+const HUB_SETTINGS = [
+    { legacy: ['host'], v8: ['server', 'host'], value: '0.0.0.0' },
+    { legacy: ['port'], v8: ['server', 'port'], value: CLI_PROXY_PORT },
+    { legacy: ['tls'], v8: ['server', 'tls'] },
+    { legacy: ['trusted-proxies'], v8: ['server', 'trusted-proxies'] },
+    { legacy: ['discovery'], v8: ['server', 'discovery'] },
+    { legacy: ['pprof'], v8: ['observability', 'pprof'] },
+    { legacy: ['plugins'], v8: ['plugins'] },
+    { legacy: ['auth-dir'], v8: ['oauth', 'auth-dir'], value: HUB_AUTH_DIR },
+    { legacy: ['logging-to-file'], v8: ['observability', 'logs', 'logging-to-file'], value: true },
+    { legacy: ['logs-max-total-size-mb'], v8: ['observability', 'logs', 'logs-max-total-size-mb'], value: 100 },
+    { legacy: ['request-log'], v8: ['observability', 'logs', 'request-log'], value: false },
+    { legacy: ['debug'], v8: ['observability', 'logs', 'debug'], value: false },
+];
+function isLocalHost(host) {
+    const h = host.replace(/^\[|\]$/g, '').toLowerCase();
+    if (h === 'localhost' || h.endsWith('.local') || h.endsWith('.localhost') || h === '::1' || h === '0.0.0.0' || h.startsWith('fe80:') || /^f[cd][0-9a-f]{0,2}:/.test(h))
+        return true;
+    const m = /^(\d+)\.(\d+)\.\d+\.\d+$/.exec(h);
+    if (!m)
+        return false;
+    const [a, b] = [Number(m[1]), Number(m[2])];
+    return a === 127 || a === 10 || (a === 192 && b === 168) || (a === 172 && b >= 16 && b <= 31) || (a === 169 && b === 254) || (a === 100 && b >= 64 && b <= 127);
+}
+/** A proxy URL that points at the user's own computer or network (unreachable from the hub). */
+export function isLocalProxyUrl(value) {
+    if (typeof value !== 'string' || !value.trim())
+        return false;
+    try {
+        return isLocalHost(new URL(value.trim()).hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The hub's config: the user's own CLIProxyAPI config (routing, retries, client API keys, model aliases, upstream keys,
+ * payload rules…), so the hosted copy answers exactly like the local one, with what only works on their computer
+ * replaced: listen address, TLS, auth directory, management (remote, the hub key in MANAGEMENT_PASSWORD, the user's own
+ * key kept, control panel off), plugins, pprof, a proxy-url on their network, and logging (rotating files in the hub,
+ * 100 MB at most, no request bodies). The file keeps its layout: the legacy flat one or `config-version: 8`.
+ */
+export function hubConfig(userText) {
+    const dropped = [];
+    let doc = new Document({});
+    if (userText && userText.trim()) {
+        doc = parseDocument(userText);
+        if (doc.errors.length > 0)
+            throw new UsageError(`Your CLIProxyAPI config is not valid YAML: ${doc.errors[0].message.split('\n')[0]}`);
+        if (!isMap(doc.contents))
+            doc = new Document({});
+    }
+    const at = (path) => doc.getIn(path);
+    const del = (path) => { if (doc.hasIn(path))
+        doc.deleteIn(path); };
+    const v8 = doc.hasIn(['config-version']) || V8_SECTIONS.some((k) => isMap(at([k])));
+    // The user's own management key (a bcrypt hash once CLIProxyAPI has started) keeps working against the hub.
+    const userKey = [at(['management', 'secret-key']), at(['remote-management', 'secret-key'])].find((k) => typeof k === 'string' && k.trim() !== '');
+    if (at(['tls', 'enable']) === true || at(['server', 'tls', 'enable']) === true)
+        dropped.push('tls (the Shardflux edge serves HTTPS)');
+    if (at(['plugins', 'enabled']) === true)
+        dropped.push('plugins (they live on this computer)');
+    for (const path of [['proxy-url'], ['requests', 'proxy-url']]) {
+        if (isLocalProxyUrl(at(path))) {
+            del(path);
+            dropped.push('proxy-url (a proxy on this computer’s network)');
+        }
+    }
+    // Every replaced setting goes in both layouts, then is set in the layout the file uses.
+    for (const s of HUB_SETTINGS) {
+        del(s.legacy);
+        del(s.v8);
+    }
+    del(['remote-management']);
+    del(['management']);
+    if (v8 && !doc.hasIn(['config-version']))
+        doc.setIn(['config-version'], 8);
+    doc.setIn(v8 ? ['management'] : ['remote-management'], doc.createNode({ 'allow-remote': true, 'secret-key': userKey ?? '', 'disable-control-panel': true }));
+    for (const s of HUB_SETTINGS)
+        if (s.value !== undefined)
+            doc.setIn(v8 ? s.v8 : s.legacy, s.value);
+    return { text: doc.toString(), dropped: [...new Set(dropped)], keepsUserManagementKey: userKey !== undefined };
+}
+const missing = (e) => e instanceof ShardfluxApiError && e.status === 404;
+/** The hub through the SDK and the project API key. */
+/**
+ * Runs `script` in the hub with standard input open: the first stdout line goes to `answer`, whose reply is sent as
+ * the command's input (then closed), and the command's exit and output are returned. A failing `answer` still sends
+ * `ABORT` so the hub releases what it holds, then rethrows.
+ */
+async function converse(cell, script, args, signal, answer) {
+    const session = await cell.exec.start({ argv: ['bash', '-c', script, 'cli-proxy-hub', ...args], stdin_open: true, timeout_ms: 900_000 }, signal);
+    const events = await cell.exec.output(session.session_id, { follow: true, ...(signal ? { signal } : {}) });
+    const text = { stdout: '', stderr: '' };
+    const offsets = { stdout: 0, stderr: 0 };
+    let answered = false, failure = null, exit = null;
+    for await (const event of events) {
+        if (event.type === 'error')
+            throw new HubError(`The hub command failed: ${event.error?.error.message ?? 'stream error'}`);
+        if (event.type === 'exit') {
+            exit = event.session?.exit_code ?? 1;
+            break;
+        }
+        if (event.type !== 'output' || !event.stream || event.offset === undefined || event.data === undefined)
+            continue;
+        const bytes = Buffer.from(event.data, 'base64');
+        const fresh = bytes.subarray(Math.max(0, offsets[event.stream] - event.offset));
+        offsets[event.stream] = Math.max(offsets[event.stream], event.offset + bytes.length);
+        text[event.stream] += fresh.toString('utf8');
+        const nl = text.stdout.indexOf('\n');
+        if (answered || nl < 0)
+            continue;
+        answered = true;
+        let reply = 'ABORT\n';
+        try {
+            reply = await answer(text.stdout.slice(0, nl));
+        }
+        catch (err) {
+            failure = err instanceof Error ? err : new Error(String(err));
+        }
+        await cell.exec.input(session.session_id, reply, { offset: 0, close: true, ...(signal ? { signal } : {}) });
+    }
+    if (failure)
+        throw failure;
+    return { exit, stdout: text.stdout, stderr: text.stderr };
+}
+/**
+ * Where a new hub may be created: only in the organization's first project (its oldest), so every project's key finds
+ * the same one hub. `home` is null without a session to list the projects with.
+ */
+export function hubPlacement(keyProjectId, home) {
+    if (!home)
+        throw new HubError('Shard needs your account session to find your account’s CLIProxyAPI hub.', 'sign in: shard auth login, then run: shard cli-proxy import');
+    if (home.id !== keyProjectId) {
+        throw new HubError(`Your account’s CLIProxyAPI hub lives in project ${home.slug} (the organization’s first project), and this API key belongs to another project.`, `use a key of ${home.slug}: shard setup --project ${home.slug} --new-key, then run: shard cli-proxy import`);
+    }
+}
+export function sdkHubCloud(cloud, opts = {}) {
+    const signal = opts.signal;
+    return {
+        async open(create) {
+            const existing = await cloud.workspaces.findByKey(HUB_KEY, { includeDeleted: false, ...(signal ? { signal } : {}) });
+            if (!existing && !create)
+                return null;
+            if (!existing) {
+                // One hub per account: a key of another project must not create a second one.
+                const me = await cloud.me();
+                if (me.type !== 'api_key' || !me.api_key)
+                    throw new HubError('The hub needs a project API key.', 'save one: shard setup');
+                hubPlacement(me.api_key.project_id, (await opts.homeProject?.(me.api_key.organization_id)) ?? null);
+            }
+            const ws = await cloud.workspaces.open({
+                key: HUB_KEY,
+                ...(existing ? {} : { template: `${HUB_TEMPLATE}@${HUB_TEMPLATE_VERSION}`, caps: HUB_CAPS, lifetime: 'persistent' }),
+                labels: { ...existing?.labels, ...HUB_LABELS },
+                wait: { ...(opts.wakeTimeoutMs ? { timeoutMs: Math.max(opts.wakeTimeoutMs, 180_000) } : {}), ...(signal ? { signal } : {}) },
+            });
+            const cell = ws.cell({ ...(opts.agentLabel ? { agentLabel: opts.agentLabel } : {}), ...(opts.wakeTimeoutMs ? { transitionTimeoutMs: opts.wakeTimeoutMs } : {}) });
+            const hub = {
+                id: ws.id,
+                async sh(script, args = [], o = {}) {
+                    const r = await cell.exec.run(['bash', '-c', script, 'cli-proxy-hub', ...args], {
+                        timeoutMs: o.timeoutMs ?? 120_000, maxOutputBytes: 64 * 1024, ...(o.stdin !== undefined ? { stdin: o.stdin } : {}), ...(signal ? { signal } : {}),
+                    });
+                    return { code: r.exitCode, stdout: r.stdout, stderr: r.stderr };
+                },
+                async read(path) {
+                    try {
+                        return await cell.files.readText(path);
+                    }
+                    catch (e) {
+                        if (missing(e))
+                            return null;
+                        throw e;
+                    }
+                },
+                async write(path, data, mode) {
+                    await cell.files.write(path, data, { mode, createParents: true });
+                },
+                async list(dir) {
+                    try {
+                        return (await cell.files.list(dir)).entries.map((e) => e.name);
+                    }
+                    catch (e) {
+                        if (missing(e))
+                            return null;
+                        throw e;
+                    }
+                },
+                async authFiles() {
+                    const r = await hub.sh(`[ -d ${HUB_AUTH_DIR} ] || exit 0; cd ${HUB_AUTH_DIR} && find . -type f -name '*.json' -printf '%P\\n'`);
+                    if (r.code !== 0)
+                        throw new HubError(`Could not list the hub’s logins: ${r.stderr.trim() || `exit ${r.code}`}`);
+                    return r.stdout.split('\n').filter(Boolean);
+                },
+                async exposePort(port) {
+                    const p = await ws.ports.expose(port);
+                    return { callbackCreatedAt: p.callback?.createdAt ?? null };
+                },
+                async createCallbackUrl(port) {
+                    return ws.ports.createCallbackUrl(port);
+                },
+                async withCallbackLock(decide, file = 'callback.json') {
+                    let result = null, wrote = false;
+                    const r = await converse(cell, CALLBACK_SCRIPT, [file], signal, async (line) => {
+                        const m = /^STORED (\S+)$/.exec(line);
+                        if (!m)
+                            return 'ABORT\n';
+                        const stored = m[1] === '-' ? null : parseStoredCallback(Buffer.from(m[1], 'base64').toString('utf8'));
+                        result = await decide(stored);
+                        wrote = result !== stored;
+                        return wrote ? `NEW ${Buffer.from(JSON.stringify(result)).toString('base64')}\n` : 'KEEP\n';
+                    });
+                    if (r.exit !== 0 || !result || (wrote && !r.stdout.includes('SAVED'))) {
+                        throw new HubError(`The hub did not store its callback URL: ${r.stderr.trim().split('\n').at(-1) || `exit ${r.exit}`}`);
+                    }
+                    return result;
+                },
+                async withLock(name, fn) {
+                    let value;
+                    let ran = false;
+                    const r = await converse(cell, LOCK_SCRIPT, [name], signal, async (line) => {
+                        if (line !== 'LOCKED')
+                            return '\n';
+                        value = await fn();
+                        ran = true;
+                        return 'DONE\n';
+                    });
+                    if (r.exit !== 0 || !ran)
+                        throw new HubError(`The hub’s ${name} lock failed: ${r.stderr.trim().split('\n').at(-1) || `exit ${r.exit}`}`);
+                    return value;
+                },
+            };
+            return { ws: hub, created: !existing, template: { version: ws.template?.version ?? null, upgradeTo: ws.upgradeAvailable?.template_version ?? null } };
+        },
+        async upgrade(id) {
+            await cloud.workspaces.upgrade(id, { at: 'now', wait: { ...(opts.wakeTimeoutMs ? { timeoutMs: Math.max(opts.wakeTimeoutMs, 300_000) } : { timeoutMs: 300_000 }), ...(signal ? { signal } : {}) } });
+        },
+        async state(id) {
+            try {
+                const w = await cloud.workspaces.get(id);
+                return w.data.deleted_at ? null : w.data.observed_state;
+            }
+            catch (e) {
+                if (missing(e))
+                    return null;
+                throw e;
+            }
+        },
+        async suspend(id) {
+            await (await cloud.workspaces.get(id)).suspend({ wait: { ...(signal ? { signal } : {}) } });
+        },
+        probe: (url) => probeCallback(url),
+    };
+}
+/** Installs the pinned release once: download, verify its SHA-256, then move the binary into place. */
+export const INSTALL_SCRIPT = `set -euo pipefail
+v=${CLI_PROXY_VERSION}; dir=${HUB_DIR}; bin="$dir/bin/cli-proxy-api-$v"
+if [ -x "$bin" ]; then echo present; exit 0; fi
+case "$(uname -m)" in
+  x86_64|amd64) asset=${CLI_PROXY_ASSETS.x86_64.asset}; sum=${CLI_PROXY_ASSETS.x86_64.sha256} ;;
+  aarch64|arm64) asset=${CLI_PROXY_ASSETS.aarch64.asset}; sum=${CLI_PROXY_ASSETS.aarch64.sha256} ;;
+  *) echo "unsupported architecture $(uname -m)" >&2; exit 3 ;;
+esac
+mkdir -p "$dir/bin"
+tmp=$(mktemp -d "$dir/.install.XXXXXX"); trap 'rm -rf "$tmp"' EXIT
+curl -fsSL --retry 3 --connect-timeout 10 -o "$tmp/release.tar.gz" "https://github.com/router-for-me/CLIProxyAPI/releases/download/v$v/CLIProxyAPI_\${v}_\${asset}.tar.gz"
+echo "$sum  $tmp/release.tar.gz" | sha256sum -c --quiet - >&2 || { echo "the CLIProxyAPI $v download does not match its pinned SHA-256" >&2; exit 4; }
+tar -xzf "$tmp/release.tar.gz" -C "$tmp" cli-proxy-api
+chmod 0755 "$tmp/cli-proxy-api"
+mv "$tmp/cli-proxy-api" "$bin"
+echo installed
+`;
+/**
+ * Ends what an earlier supervisor of this hub left running (shared by run.sh and the stop script): its CLIProxyAPI
+ * (8317), its VM port (sf-agent cli-proxy-filter, 8318), and the supervisor and its loop. Matched by the argv of
+ * processes of this user, never by text in a command line (an exec'd script contains these words), never this shell.
+ * TERM, up to 5 s, then KILL.
+ */
+const CLEAR_STALE = `clear_stale() {
+  local p i a found=() left=()
+  for p in /proc/[0-9]*; do
+    p=\${p#/proc/}
+    [ "$p" != "$$" ] && [ -O "/proc/$p" ] || continue
+    a=(); mapfile -d '' -t a 2>/dev/null < "/proc/$p/cmdline" || continue
+    [ "\${#a[@]}" -gt 0 ] || continue
+    if [[ "\${a[0]}" == "$dir/bin/cli-proxy-api"* ]] || { [[ "\${a[0]}" == */bash || "\${a[0]}" == bash ]] && [ "\${a[1]-}" = "$dir/run.sh" ]; }; then
+      found+=("$p"); continue
+    fi
+    if [[ "\${a[0]}" == *sf-agent ]]; then
+      for ((i = 1; i + 1 < \${#a[@]}; i++)); do
+        if [ "\${a[i]}" = cli-proxy-filter ] && [ "\${a[i+1]}" = --listen ]; then found+=("$p"); break; fi
+      done
+    fi
+  done
+  [ "\${#found[@]}" -gt 0 ] || return 0
+  kill -TERM "\${found[@]}" 2>/dev/null || true
+  for ((i = 0; i < 50; i++)); do
+    left=()
+    for p in "\${found[@]}"; do
+      a=(); mapfile -d '' -t a 2>/dev/null < "/proc/$p/cmdline" || continue
+      [ "\${#a[@]}" -gt 0 ] && left+=("$p")
+    done
+    [ "\${#left[@]}" -gt 0 ] || return 0
+    sleep 0.1
+  done
+  kill -KILL "\${left[@]}" 2>/dev/null || true
+  return 0
+}`;
+/**
+ * The supervisor (setsid, its own process group): runs CLIProxyAPI in the foreground and starts it again 2 s after it
+ * exits. The management key is read from its 0600 file into MANAGEMENT_PASSWORD (never in the config or argv); logs go
+ * to rotating files under the hub directory (WRITABLE_PATH). First it ends whatever an earlier supervisor that died
+ * alone left running, which would hold 8317 and 8318.
+ */
+export const RUN_SCRIPT = `#!/bin/bash
+set -u
+dir=\${CLI_PROXY_HUB_DIR:-${HUB_DIR}}
+${CLEAR_STALE}
+clear_stale
+echo $$ > "$dir/run.pid"
+cd "$dir"
+# Its own session: stopping it ends the whole group (CLIProxyAPI and the VM port).
+trap 'trap - TERM INT; kill -TERM 0 2>/dev/null; exit 0' TERM INT
+# The VM port (0.0.0.0:${CLI_PROXY_VM_PORT}): CLIProxyAPI without its management API, served by sf-agent (the
+# template's, else one placed in the hub's bin).
+(
+  while :; do
+    filter=
+    for b in /usr/local/bin/sf-agent "$dir/bin/sf-agent"; do
+      if [ -x "$b" ] && "$b" cli-proxy-filter --probe >/dev/null 2>&1; then filter=$b; break; fi
+    done
+    if [ -z "$filter" ]; then sleep 300; continue; fi
+    "$filter" cli-proxy-filter --listen 0.0.0.0:${CLI_PROXY_VM_PORT} --upstream 127.0.0.1:${CLI_PROXY_PORT}
+    echo "$(date -u +%FT%TZ) the VM port exited with status $?; starting it again in 2 s"
+    sleep 2
+  done
+) &
+while :; do
+  MANAGEMENT_PASSWORD="$(cat "$dir/management.key")" WRITABLE_PATH="$dir" "$dir/bin/cli-proxy-api-${CLI_PROXY_VERSION}" -config "$dir/config.yaml" &
+  child=$!
+  wait "$child"; code=$?
+  echo "$(date -u +%FT%TZ) cli-proxy-api exited with status $code; starting it again in 2 s"
+  sleep 2
+done
+`;
+/**
+ * Starts the supervisor unless it runs and the hub answers /healthz (serialized by a lock in the hub, so two devices
+ * ensuring at once never start two copies). $1=1 restarts it (a new binary, run script or management key).
+ * Prints `running`, `started` or `restarted`.
+ *
+ * The codex-connector template's `cli-proxy-hub` service (images/templates/codex-connector/start-cli-proxy-hub) starts
+ * the same run.sh at boot under the same lock and run.pid rules; a template without it (version 3 and earlier) relies
+ * on this script alone. run.pid counts only while that pid's command line is run.sh: after a cold boot the old pid
+ * may belong to any process, which must be neither waited for nor signalled.
+ */
+export const START_SCRIPT = `set -euo pipefail
+dir=${HUB_DIR}; restart=\${1:-0}
+exec 9>"$dir/start.lock"; flock -w 90 9 || { echo "another start of CLIProxyAPI is still running in the hub" >&2; exit 6; }
+healthy() { curl -fsS -m 2 -o /dev/null http://127.0.0.1:${CLI_PROXY_PORT}/healthz 2>/dev/null; }
+# The second line says whether the VM port answers (it starts a moment after CLIProxyAPI).
+vmport() { for _ in $(seq 25); do if curl -fsS -m 1 -o /dev/null http://127.0.0.1:${CLI_PROXY_VM_PORT}/healthz 2>/dev/null; then echo "vm-port yes"; return; fi; sleep 0.2; done; echo "vm-port no"; }
+alive() {
+  [ -s "$dir/run.pid" ] || return 1
+  pid=$(cat "$dir/run.pid")
+  [[ "$pid" =~ ^[0-9]+$ ]] || return 1
+  cmd=$(tr '\\0' ' ' 2>/dev/null < "/proc/$pid/cmdline") || return 1
+  [[ "$cmd" == *"$dir/run.sh"* ]]
+}
+stop() {
+  if alive; then
+    pid=$(cat "$dir/run.pid"); kill -TERM -- "-$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null || true
+    for _ in $(seq 50); do alive || break; sleep 0.1; done
+    if alive; then kill -KILL -- "-$pid" 2>/dev/null || true; fi
+  fi
+  rm -f "$dir/run.pid"
+}
+state=started
+if [ "$restart" = 1 ] && alive; then stop; state=restarted; fi
+if alive; then
+  for _ in $(seq 100); do if healthy; then echo running; vmport; exit 0; fi; sleep 0.2; done
+  stop; state=restarted
+fi
+if [ -f "$dir/supervisor.log" ] && [ "$(stat -c %s "$dir/supervisor.log")" -gt 1048576 ]; then : > "$dir/supervisor.log"; fi
+# The supervisor must not inherit the lock (fd 9), or the next start would wait for it forever.
+setsid "$dir/run.sh" 9>&- >>"$dir/supervisor.log" 2>&1 </dev/null &
+for _ in $(seq 150); do if healthy; then echo "$state"; vmport; exit 0; fi; sleep 0.2; done
+echo "CLIProxyAPI did not answer on port ${CLI_PROXY_PORT} within 30 s" >&2
+tail -n 5 "$dir/supervisor.log" >&2 2>/dev/null || true
+exit 5
+`;
+/**
+ * Stops CLIProxyAPI in the hub for `shard cli-proxy export` (under the start lock): the supervisor and anything it
+ * started end (CLIProxyAPI and the VM port, also when an earlier supervisor left them running), run.sh is set aside
+ * (the boot service stays idle) and `exported` marks the hub, so no forwarder starts it again until the next import.
+ * Prints `stopped`.
+ */
+export const STOP_SCRIPT = `set -euo pipefail
+dir=\${CLI_PROXY_HUB_DIR:-${HUB_DIR}}
+${CLEAR_STALE}
+exec 9>"$dir/start.lock"; flock -w 90 9 || { echo "a start of CLIProxyAPI is still running in the hub" >&2; exit 6; }
+alive() {
+  [ -s "$dir/run.pid" ] || return 1
+  pid=$(cat "$dir/run.pid")
+  [[ "$pid" =~ ^[0-9]+$ ]] || return 1
+  cmd=$(tr '\\0' ' ' 2>/dev/null < "/proc/$pid/cmdline") || return 1
+  [[ "$cmd" == *"$dir/run.sh"* ]]
+}
+date -u +%FT%TZ > "$dir/exported"
+if [ -f "$dir/run.sh" ]; then mv "$dir/run.sh" "$dir/run.sh.exported"; fi
+if alive; then
+  kill -TERM -- "-$pid" 2>/dev/null || true
+  for _ in $(seq 50); do alive || break; sleep 0.1; done
+  if alive; then kill -KILL -- "-$pid" 2>/dev/null || true; fi
+fi
+rm -f "$dir/run.pid"
+clear_stale
+for _ in $(seq 50); do
+  if ! curl -fsS -m 1 -o /dev/null http://127.0.0.1:${CLI_PROXY_PORT}/healthz 2>/dev/null && ! curl -fsS -m 1 -o /dev/null http://127.0.0.1:${CLI_PROXY_VM_PORT}/healthz 2>/dev/null; then echo stopped; exit 0; fi
+  sleep 0.1
+done
+echo "CLIProxyAPI still answers in the hub" >&2
+exit 5
+`;
+/**
+ * The hub's management key, created once: under key.lock, a missing or malformed management.key becomes the key on
+ * standard input (0600, atomic). Prints `created` when it wrote one, then the key in use.
+ */
+export const KEY_SCRIPT = `set -euo pipefail
+dir=${HUB_DIR}; mkdir -p "$dir"
+exec 7>"$dir/key.lock"; flock -w 60 7 || { echo "another device is setting up the hub's key" >&2; exit 6; }
+IFS= read -r proposed || true
+if ! grep -qxE '[0-9a-f]{64}' "$dir/management.key" 2>/dev/null; then
+  [[ "$proposed" =~ ^[0-9a-f]{64}$ ]] || { echo "no valid key was proposed" >&2; exit 7; }
+  umask 077; printf '%s\\n' "$proposed" > "$dir/management.key.tmp"; mv "$dir/management.key.tmp" "$dir/management.key"
+  echo created
+fi
+cat "$dir/management.key"
+`;
+/**
+ * Adds one auth file to the hub only when that path is free (a hard link cannot replace a file), so two devices
+ * importing at once never overwrite each other's login or the hub's newer tokens. $1 is the path relative to the auth
+ * directory, the content comes on standard input. Prints `added` or `exists`.
+ */
+export const ADD_AUTH_SCRIPT = `set -euo pipefail
+a=${HUB_AUTH_DIR}; rel=$1
+case "$rel" in ''|/*|*..*) echo "not a path inside the auth folder" >&2; exit 2 ;; esac
+mkdir -p -m 0700 "$(dirname "$a/$rel")"
+tmp=$(mktemp "$a/.adding.XXXXXX"); chmod 0600 "$tmp"; cat > "$tmp"
+if ln "$tmp" "$a/$rel" 2>/dev/null; then echo added; else echo exists; fi
+rm -f "$tmp"
+`;
+/** Sets the hub's logins aside after an export copied them out (the hub holds none until the next import). */
+export const SET_ASIDE_SCRIPT = `set -euo pipefail
+a=${HUB_AUTH_DIR}; [ -d "$a" ] || exit 0
+to="$a.exported-$(date -u +%Y%m%dT%H%M%SZ)"
+mv "$a" "$to"; mkdir -m 0700 "$a"; chmod 0700 "$to"
+echo "$to"
+`;
+/** The hub could not be made ready (exit 1, code `cli_proxy_hub`). */
+export class HubError extends CodedError {
+    name = 'HubError';
+    constructor(message, hint) {
+        super('cli_proxy_hub', message, hint);
+    }
+}
+/**
+ * Makes sure the account's hub exists, runs the pinned CLIProxyAPI on port 8317 and has a callback URL, and saves the
+ * hub info locally (0600) and in the hub. Idempotent: a running, healthy hub with a valid callback URL is left as it is.
+ */
+export async function ensureCliProxyHub(cloud, opts) {
+    const hubCloud = 'workspaces' in cloud ? sdkHubCloud(cloud) : cloud;
+    const progress = opts.progress ?? (() => { });
+    const local = readHubInfo(opts.dir, opts.apiUrl);
+    progress('Opening the CLIProxyAPI hub…');
+    let opened = await hubCloud.open(!opts.repairOnly);
+    if (!opened)
+        throw new HubError('This account has no hosted CLIProxyAPI yet.', 'move yours: shard cli-proxy import');
+    // A hub on an older template is upgraded before VMs get its address (a plain repair only starts it again).
+    const template = opened.template;
+    if (!opened.created && (!opts.repairOnly || opts.renewInvalid) && hubCloud.upgrade && template?.version != null && template.version < HUB_TEMPLATE_VERSION && (template.upgradeTo ?? 0) >= HUB_TEMPLATE_VERSION) {
+        progress('Updating the CLIProxyAPI hub…');
+        await hubCloud.upgrade(opened.ws.id);
+        opened = await hubCloud.open(false);
+        if (!opened)
+            throw new HubError('The hub was deleted during its update.', 'run: shard cli-proxy import');
+    }
+    const { ws, created } = opened;
+    // After `shard cli-proxy export` the logins live on a computer again: only an import brings the hub back.
+    if ((await ws.read(`${HUB_DIR}/exported`)) !== null) {
+        if (opts.repairOnly)
+            throw new HubError('Your logins were moved back to a computer (shard cli-proxy export), so the hosted CLIProxyAPI stays stopped.', 'move them to the hub again: shard cli-proxy import');
+        await ws.sh(`rm -f ${HUB_DIR}/exported ${HUB_DIR}/run.sh.exported`);
+    }
+    const installed = await ws.sh(INSTALL_SCRIPT, [], { timeoutMs: 300_000 });
+    if (installed.code !== 0)
+        throw new HubError(`Could not install CLIProxyAPI ${CLI_PROXY_VERSION} in the hub: ${installed.stderr.trim().split('\n').at(-1) || `exit ${installed.code}`}`);
+    let restart = installed.stdout.trim() === 'installed' && !created;
+    // The management key: the hub's own file is the source of truth, created once under a hub-side lock (two devices
+    // ensuring a new hub at once must not each write their own).
+    const proposed = local?.workspace_id === ws.id && /^[0-9a-f]{64}$/.test(local.management_key) ? local.management_key : (opts.randomKey ?? (() => randomBytes(32).toString('hex')))();
+    const keyed = await ws.sh(KEY_SCRIPT, [], { stdin: `${proposed}\n` });
+    const keyLines = keyed.stdout.trim().split('\n');
+    const managementKey = keyLines.at(-1)?.trim() ?? '';
+    if (keyed.code !== 0 || !/^[0-9a-f]{64}$/.test(managementKey))
+        throw new HubError(`The hub did not keep its management key: ${keyed.stderr.trim().split('\n').at(-1) || `exit ${keyed.code}`}`);
+    if (keyLines[0] === 'created')
+        restart = true;
+    if ((await ws.read(`${HUB_DIR}/run.sh`)) !== RUN_SCRIPT) {
+        await ws.write(`${HUB_DIR}/run.sh`, RUN_SCRIPT, '0700');
+        restart = true;
+    }
+    // The hub's config is made once, from the first user config it gets: a second computer's import never replaces it
+    // (its client keys, routing and upstream keys stay the hub's). config.source says where it came from.
+    let config = null;
+    const configPath = `${HUB_DIR}/config.yaml`, sourcePath = `${HUB_DIR}/config.source`;
+    const hasConfig = (await ws.read(configPath)) !== null;
+    const source = hasConfig ? ((await ws.read(sourcePath))?.trim() ?? 'user') : null;
+    const fromUser = opts.userConfig !== undefined && opts.userConfig !== null;
+    if (!hasConfig || (source === 'default' && fromUser)) {
+        config = hubConfig(opts.userConfig ?? null);
+        // A running hub reloads its config by itself.
+        await ws.write(configPath, config.text, '0600');
+        await ws.write(sourcePath, fromUser ? 'user\n' : 'default\n', '0600');
+    }
+    if ((await ws.list(HUB_AUTH_DIR)) === null)
+        await ws.sh(`mkdir -p -m 0700 ${HUB_AUTH_DIR}`);
+    const started = await ws.sh(START_SCRIPT, [restart ? '1' : '0'], { timeoutMs: 180_000 });
+    const startLines = started.stdout.trim().split('\n');
+    const state = startLines.find((l) => ['running', 'started', 'restarted'].includes(l));
+    if (started.code !== 0 || !state) {
+        throw new HubError(`CLIProxyAPI did not start in the hub: ${started.stderr.trim().split('\n').at(0) || `exit ${started.code}`}`);
+    }
+    if (state !== 'running')
+        progress(state === 'started' ? 'CLIProxyAPI is running in the hub' : 'CLIProxyAPI started again in the hub');
+    // The management port's callback URL (this computer only) and, when the hub serves it, the VM port's (for VMs).
+    const probe = !opts.repairOnly || opts.renewInvalid ? (opts.probe ?? hubCloud.probe) : undefined;
+    const repairOnly = !!opts.repairOnly && !opts.renewInvalid;
+    const { callback, replaced: callbackReplaced } = await hubCallback(ws, repairOnly, CLI_PROXY_PORT, probe);
+    const vmPort = startLines.includes('vm-port yes') ? (await hubCallback(ws, repairOnly, CLI_PROXY_VM_PORT, probe)).callback : null;
+    const info = {
+        version: 1, api_url: opts.apiUrl, workspace_id: ws.id, callback_url: callback.callback_url, callback_created_at: callback.callback_created_at, management_key: managementKey,
+        ...(vmPort ? { vm_callback_url: vmPort.callback_url, vm_callback_created_at: vmPort.callback_created_at } : {}),
+    };
+    if (!local || hubInfoText(local) !== hubInfoText(info))
+        writeHubInfo(opts.dir, info);
+    return { info, created, process: state, callbackReplaced, config };
+}
+/**
+ * The hub's one callback URL. Under the hub's callback lock: the stored one is kept while the port's callback still
+ * has its creation time; otherwise one is created and stored before the lock is released. Every device and every
+ * import reads the stored one, so concurrent imports never replace each other's URL (and the VMs' copy).
+ */
+export async function hubCallback(ws, repairOnly = false, portNumber = CLI_PROXY_PORT, probe) {
+    let replaced = false;
+    const callback = await ws.withCallbackLock(async (stored) => {
+        const port = await ws.exposePort(portNumber);
+        const current = stored !== null && port.callbackCreatedAt !== null && stored.callback_created_at === port.callbackCreatedAt;
+        // The port still lists it, but the edge may refuse it (its API key was revoked): a probe tells.
+        if (current && stored && (!probe || (await probe(stored.callback_url)) !== 'invalid'))
+            return stored;
+        if (repairOnly)
+            throw new HubError('The hub’s callback URL changed.', 'connect this computer again: shard cli-proxy import');
+        const fresh = await ws.createCallbackUrl(portNumber);
+        replaced = port.callbackCreatedAt !== null;
+        return { callback_url: fresh.url, callback_created_at: fresh.createdAt };
+    }, callbackFile(portNumber));
+    return { callback, replaced };
+}
+/**
+ * Whether the edge still accepts a callback URL: `invalid` only for its own 401 `callback_invalid` refusal; any other
+ * answer (CLIProxyAPI's, a waking or starting hub) means the URL itself works. `unknown` when nothing answered.
+ */
+export async function probeCallback(url, timeoutMs = 45_000) {
+    try {
+        const res = await fetch(new URL('healthz', url), { signal: AbortSignal.timeout(timeoutMs) });
+        await res.arrayBuffer().catch(() => undefined);
+        return res.status === 401 && res.headers.get('x-shardflux-reason') === 'callback_invalid' ? 'invalid' : 'ok';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Where the hub stores a port's callback URL: callback.json (8317, management), callback-vm.json (8318, VMs). */
+export function callbackFile(port) {
+    return port === CLI_PROXY_VM_PORT ? 'callback-vm.json' : 'callback.json';
+}
+/**
+ * Holds the hub's callback lock (flock on callback.lock, in the hub) while the client decides: prints the stored
+ * callback (base64 JSON, or -), then reads one line: KEEP, ABORT, or NEW <base64 JSON>, which it stores atomically.
+ */
+export const CALLBACK_SCRIPT = `set -euo pipefail
+dir=${HUB_DIR}; mkdir -p "$dir"; f=\${1:-callback.json}
+case "$f" in callback.json|callback-vm.json) ;; *) echo "unknown callback file" >&2; exit 2 ;; esac
+exec 8>"$dir/callback.lock"
+flock -w 120 8 || { echo "another device is setting up the hub's callback URL" >&2; exit 6; }
+if [ -s "$dir/$f" ]; then printf 'STORED %s\\n' "$(base64 -w0 < "$dir/$f")"; else echo 'STORED -'; fi
+IFS= read -r -t 150 reply || { echo "no answer from the device" >&2; exit 7; }
+case "$reply" in
+  KEEP|ABORT) exit 0 ;;
+  NEW\\ *) umask 077; printf '%s' "\${reply#NEW }" | base64 -d > "$dir/$f.tmp"; mv "$dir/$f.tmp" "$dir/$f"; echo SAVED ;;
+  *) echo "unexpected answer" >&2; exit 8 ;;
+esac
+`;
+/**
+ * Holds a hub-side lock (flock on <name>.lock) while the device works: prints LOCKED, then waits for a line (or the
+ * end of standard input) and releases it.
+ */
+export const LOCK_SCRIPT = `set -euo pipefail
+dir=${HUB_DIR}; mkdir -p "$dir"; name=\${1:?}
+[[ "$name" =~ ^[a-z-]+$ ]] || { echo "bad lock name" >&2; exit 2; }
+exec 8>"$dir/$name.lock"
+flock -w 120 8 || { echo "another device holds the hub's $name lock" >&2; exit 6; }
+echo LOCKED
+IFS= read -r -t 600 _ || true
+echo RELEASED
+`;
+export function parseStoredCallback(text) {
+    let v;
+    try {
+        v = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const o = (v && typeof v === 'object' ? v : {});
+    return typeof o.callback_url === 'string' && typeof o.callback_created_at === 'string' && o.callback_url && o.callback_created_at
+        ? { callback_url: o.callback_url, callback_created_at: o.callback_created_at } : null;
+}