@shardflux/cli 0.16.0 → 0.17.0

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

@@ -0,0 +1,273 @@
+import type { Caps, Shardflux } from '@shardflux/sdk';
+import { CodedError } from './errors.js';
+/** The pinned CLIProxyAPI release and the SHA-256 of its Linux assets (verified in the hub before install). */
+export declare const CLI_PROXY_VERSION = "8.0.23";
+export declare const CLI_PROXY_ASSETS: {
+    readonly x86_64: {
+        readonly asset: "linux_amd64";
+        readonly sha256: "744000a1a4f9ce19f5964774f853d029797b87ef53796d054389258c66cb1224";
+    };
+    readonly aarch64: {
+        readonly asset: "linux_aarch64";
+        readonly sha256: "7c54c9306167b3e252090924c39a9b9dd5c09dffd376551271d8902f391f0246";
+    };
+};
+export declare 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 declare const CLI_PROXY_VM_PORT = 8318;
+/** The hub's workspace key in the API key's project, and its labels. */
+export declare const HUB_KEY = "shardflux/cli-proxy";
+export declare const HUB_LABELS: {
+    readonly 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 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.
+ */
+export declare const HUB_TEMPLATE_VERSION = 4;
+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";
+export interface HubInfo {
+    version: 1;
+    api_url: string;
+    workspace_id: string;
+    /** `https://8317-<handle>.<domain>/__shardflux/callback/sfcb_…/`: a request to `<callback_url><rest>` reaches `/<rest>`. */
+    callback_url: string;
+    /** When the port's callback URL was created: a different value on the port means this one was replaced. */
+    callback_created_at: string;
+    /** The hub's MANAGEMENT_PASSWORD (Authorization: Bearer on /v0/management/*). */
+    management_key: string;
+    /** The VM port's (8318) callback URL: what VMs receive. Absent while the hub does not serve that port. */
+    vm_callback_url?: string;
+    vm_callback_created_at?: string;
+}
+/** The hub info in `text`, or null when it is not a valid one (an unreadable file is treated as absent). */
+export declare function parseHubInfo(text: string): HubInfo | null;
+export declare function hubInfoPath(dir: string): string;
+/** The saved hub info for `apiUrl` (any API URL when omitted), or null. */
+export declare function readHubInfo(dir: string, apiUrl?: string): HubInfo | null;
+export declare function hubInfoText(info: HubInfo): string;
+/**
+ * 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 declare function vmHubInfoText(info: HubInfo): string | null;
+export declare function writeHubInfo(dir: string, info: HubInfo): void;
+export interface HubConfig {
+    text: string;
+    /** Settings of the user's config that only work on their own computer, left out of the hub's copy. */
+    dropped: string[];
+    /** The user's own management key (its bcrypt hash) is kept, so tools that use it keep working. */
+    keepsUserManagementKey: boolean;
+}
+/** A proxy URL that points at the user's own computer or network (unreachable from the hub). */
+export declare function isLocalProxyUrl(value: unknown): boolean;
+/**
+ * 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 declare function hubConfig(userText: string | null): HubConfig;
+/** What ensuring the hub needs from its workspace (the SDK in production, a stand-in in tests). */
+export interface HubWorkspace {
+    readonly id: string;
+    /** bash -c `script` as the workspace user; argv after the script are $1…. */
+    sh(script: string, args?: string[], opts?: {
+        stdin?: string;
+        timeoutMs?: number;
+    }): Promise<{
+        code: number | null;
+        stdout: string;
+        stderr: string;
+    }>;
+    /** File content, or null when it does not exist. */
+    read(path: string): Promise<string | null>;
+    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). */
+    authFiles(): Promise<string[]>;
+    /** Exposes the port (idempotent): when its callback URL was created, null without one. */
+    exposePort(port: number): Promise<{
+        callbackCreatedAt: string | null;
+    }>;
+    createCallbackUrl(port: number): Promise<{
+        url: string;
+        createdAt: string;
+    }>;
+    /**
+     * Runs `decide` while the hub's callback lock is held (one device at a time): it gets the stored callback, or null,
+     * and returns the one to keep; a different one is stored in the hub before the lock is released.
+     */
+    withCallbackLock(decide: (stored: StoredCallback | null) => Promise<StoredCallback>, file?: string): Promise<StoredCallback>;
+    /** Runs `fn` while the hub-side lock `name` is held (one device at a time). */
+    withLock<T>(name: string, fn: () => Promise<T>): Promise<T>;
+}
+export interface HubCloud {
+    /** The hub workspace, running (resumed or woken as needed); with `create`, created on first use. Null when missing. */
+    open(create: boolean): Promise<{
+        ws: HubWorkspace;
+        created: boolean;
+        template?: HubTemplate;
+    } | null>;
+    /** Upgrades the hub to its template's newest version now (files and home stay; processes start again). */
+    upgrade?: (id: string) => Promise<void>;
+    /** The workspace's observed state (`running`, `suspended`, …), or null when it no longer exists. Never wakes it. */
+    state(id: string): Promise<string | null>;
+    /** Suspends the hub workspace (it wakes on the next request or open). */
+    suspend(id: string): Promise<void>;
+    /** Whether the edge still accepts a stored callback URL (probeCallback); without it a stored URL counts as valid. */
+    probe?: (url: string) => Promise<CallbackProbe>;
+}
+/** The template version a hub runs, and the newer one it can be upgraded to (null when none). */
+export interface HubTemplate {
+    version: number | null;
+    upgradeTo: number | null;
+}
+/** A project of the account (the hub's home is the organization's first one). */
+export interface HomeProject {
+    id: string;
+    slug: string;
+}
+/**
+ * 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 declare function hubPlacement(keyProjectId: string, home: HomeProject | null): void;
+export declare function sdkHubCloud(cloud: Shardflux, opts?: {
+    signal?: AbortSignal;
+    wakeTimeoutMs?: number;
+    agentLabel?: string;
+    homeProject?: (organizationId: string) => Promise<HomeProject | null>;
+}): HubCloud;
+/** Installs the pinned release once: download, verify its SHA-256, then move the binary into place. */
+export declare const INSTALL_SCRIPT: string;
+/**
+ * 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 declare const RUN_SCRIPT = "#!/bin/bash\nset -u\ndir=${CLI_PROXY_HUB_DIR:-/home/user/.cli-proxy-hub}\nclear_stale() {\n  local p i a found=() left=()\n  for p in /proc/[0-9]*; do\n    p=${p#/proc/}\n    [ \"$p\" != \"$$\" ] && [ -O \"/proc/$p\" ] || continue\n    a=(); mapfile -d '' -t a 2>/dev/null < \"/proc/$p/cmdline\" || continue\n    [ \"${#a[@]}\" -gt 0 ] || continue\n    if [[ \"${a[0]}\" == \"$dir/bin/cli-proxy-api\"* ]] || { [[ \"${a[0]}\" == */bash || \"${a[0]}\" == bash ]] && [ \"${a[1]-}\" = \"$dir/run.sh\" ]; }; then\n      found+=(\"$p\"); continue\n    fi\n    if [[ \"${a[0]}\" == *sf-agent ]]; then\n      for ((i = 1; i + 1 < ${#a[@]}; i++)); do\n        if [ \"${a[i]}\" = cli-proxy-filter ] && [ \"${a[i+1]}\" = --listen ]; then found+=(\"$p\"); break; fi\n      done\n    fi\n  done\n  [ \"${#found[@]}\" -gt 0 ] || return 0\n  kill -TERM \"${found[@]}\" 2>/dev/null || true\n  for ((i = 0; i < 50; i++)); do\n    left=()\n    for p in \"${found[@]}\"; do\n      a=(); mapfile -d '' -t a 2>/dev/null < \"/proc/$p/cmdline\" || continue\n      [ \"${#a[@]}\" -gt 0 ] && left+=(\"$p\")\n    done\n    [ \"${#left[@]}\" -gt 0 ] || return 0\n    sleep 0.1\n  done\n  kill -KILL \"${left[@]}\" 2>/dev/null || true\n  return 0\n}\nclear_stale\necho $$ > \"$dir/run.pid\"\ncd \"$dir\"\n# Its own session: stopping it ends the whole group (CLIProxyAPI and the VM port).\ntrap 'trap - TERM INT; kill -TERM 0 2>/dev/null; exit 0' TERM INT\n# The VM port (0.0.0.0:8318): CLIProxyAPI without its management API, served by sf-agent (the\n# template's, else one placed in the hub's bin).\n(\n  while :; do\n    filter=\n    for b in /usr/local/bin/sf-agent \"$dir/bin/sf-agent\"; do\n      if [ -x \"$b\" ] && \"$b\" cli-proxy-filter --probe >/dev/null 2>&1; then filter=$b; break; fi\n    done\n    if [ -z \"$filter\" ]; then sleep 300; continue; fi\n    \"$filter\" cli-proxy-filter --listen 0.0.0.0:8318 --upstream 127.0.0.1:8317\n    echo \"$(date -u +%FT%TZ) the VM port exited with status $?; starting it again in 2 s\"\n    sleep 2\n  done\n) &\nwhile :; do\n  MANAGEMENT_PASSWORD=\"$(cat \"$dir/management.key\")\" WRITABLE_PATH=\"$dir\" \"$dir/bin/cli-proxy-api-8.0.23\" -config \"$dir/config.yaml\" &\n  child=$!\n  wait \"$child\"; code=$?\n  echo \"$(date -u +%FT%TZ) cli-proxy-api exited with status $code; starting it again in 2 s\"\n  sleep 2\ndone\n";
+/**
+ * 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 declare const START_SCRIPT = "set -euo pipefail\ndir=/home/user/.cli-proxy-hub; restart=${1:-0}\nexec 9>\"$dir/start.lock\"; flock -w 90 9 || { echo \"another start of CLIProxyAPI is still running in the hub\" >&2; exit 6; }\nhealthy() { curl -fsS -m 2 -o /dev/null http://127.0.0.1:8317/healthz 2>/dev/null; }\n# The second line says whether the VM port answers (it starts a moment after CLIProxyAPI).\nvmport() { for _ in $(seq 25); do if curl -fsS -m 1 -o /dev/null http://127.0.0.1:8318/healthz 2>/dev/null; then echo \"vm-port yes\"; return; fi; sleep 0.2; done; echo \"vm-port no\"; }\nalive() {\n  [ -s \"$dir/run.pid\" ] || return 1\n  pid=$(cat \"$dir/run.pid\")\n  [[ \"$pid\" =~ ^[0-9]+$ ]] || return 1\n  cmd=$(tr '\\0' ' ' 2>/dev/null < \"/proc/$pid/cmdline\") || return 1\n  [[ \"$cmd\" == *\"$dir/run.sh\"* ]]\n}\nstop() {\n  if alive; then\n    pid=$(cat \"$dir/run.pid\"); kill -TERM -- \"-$pid\" 2>/dev/null || kill -TERM \"$pid\" 2>/dev/null || true\n    for _ in $(seq 50); do alive || break; sleep 0.1; done\n    if alive; then kill -KILL -- \"-$pid\" 2>/dev/null || true; fi\n  fi\n  rm -f \"$dir/run.pid\"\n}\nstate=started\nif [ \"$restart\" = 1 ] && alive; then stop; state=restarted; fi\nif alive; then\n  for _ in $(seq 100); do if healthy; then echo running; vmport; exit 0; fi; sleep 0.2; done\n  stop; state=restarted\nfi\nif [ -f \"$dir/supervisor.log\" ] && [ \"$(stat -c %s \"$dir/supervisor.log\")\" -gt 1048576 ]; then : > \"$dir/supervisor.log\"; fi\n# The supervisor must not inherit the lock (fd 9), or the next start would wait for it forever.\nsetsid \"$dir/run.sh\" 9>&- >>\"$dir/supervisor.log\" 2>&1 </dev/null &\nfor _ in $(seq 150); do if healthy; then echo \"$state\"; vmport; exit 0; fi; sleep 0.2; done\necho \"CLIProxyAPI did not answer on port 8317 within 30 s\" >&2\ntail -n 5 \"$dir/supervisor.log\" >&2 2>/dev/null || true\nexit 5\n";
+/**
+ * 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 declare const STOP_SCRIPT = "set -euo pipefail\ndir=${CLI_PROXY_HUB_DIR:-/home/user/.cli-proxy-hub}\nclear_stale() {\n  local p i a found=() left=()\n  for p in /proc/[0-9]*; do\n    p=${p#/proc/}\n    [ \"$p\" != \"$$\" ] && [ -O \"/proc/$p\" ] || continue\n    a=(); mapfile -d '' -t a 2>/dev/null < \"/proc/$p/cmdline\" || continue\n    [ \"${#a[@]}\" -gt 0 ] || continue\n    if [[ \"${a[0]}\" == \"$dir/bin/cli-proxy-api\"* ]] || { [[ \"${a[0]}\" == */bash || \"${a[0]}\" == bash ]] && [ \"${a[1]-}\" = \"$dir/run.sh\" ]; }; then\n      found+=(\"$p\"); continue\n    fi\n    if [[ \"${a[0]}\" == *sf-agent ]]; then\n      for ((i = 1; i + 1 < ${#a[@]}; i++)); do\n        if [ \"${a[i]}\" = cli-proxy-filter ] && [ \"${a[i+1]}\" = --listen ]; then found+=(\"$p\"); break; fi\n      done\n    fi\n  done\n  [ \"${#found[@]}\" -gt 0 ] || return 0\n  kill -TERM \"${found[@]}\" 2>/dev/null || true\n  for ((i = 0; i < 50; i++)); do\n    left=()\n    for p in \"${found[@]}\"; do\n      a=(); mapfile -d '' -t a 2>/dev/null < \"/proc/$p/cmdline\" || continue\n      [ \"${#a[@]}\" -gt 0 ] && left+=(\"$p\")\n    done\n    [ \"${#left[@]}\" -gt 0 ] || return 0\n    sleep 0.1\n  done\n  kill -KILL \"${left[@]}\" 2>/dev/null || true\n  return 0\n}\nexec 9>\"$dir/start.lock\"; flock -w 90 9 || { echo \"a start of CLIProxyAPI is still running in the hub\" >&2; exit 6; }\nalive() {\n  [ -s \"$dir/run.pid\" ] || return 1\n  pid=$(cat \"$dir/run.pid\")\n  [[ \"$pid\" =~ ^[0-9]+$ ]] || return 1\n  cmd=$(tr '\\0' ' ' 2>/dev/null < \"/proc/$pid/cmdline\") || return 1\n  [[ \"$cmd\" == *\"$dir/run.sh\"* ]]\n}\ndate -u +%FT%TZ > \"$dir/exported\"\nif [ -f \"$dir/run.sh\" ]; then mv \"$dir/run.sh\" \"$dir/run.sh.exported\"; fi\nif alive; then\n  kill -TERM -- \"-$pid\" 2>/dev/null || true\n  for _ in $(seq 50); do alive || break; sleep 0.1; done\n  if alive; then kill -KILL -- \"-$pid\" 2>/dev/null || true; fi\nfi\nrm -f \"$dir/run.pid\"\nclear_stale\nfor _ in $(seq 50); do\n  if ! curl -fsS -m 1 -o /dev/null http://127.0.0.1:8317/healthz 2>/dev/null && ! curl -fsS -m 1 -o /dev/null http://127.0.0.1:8318/healthz 2>/dev/null; then echo stopped; exit 0; fi\n  sleep 0.1\ndone\necho \"CLIProxyAPI still answers in the hub\" >&2\nexit 5\n";
+/**
+ * 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 declare const KEY_SCRIPT = "set -euo pipefail\ndir=/home/user/.cli-proxy-hub; mkdir -p \"$dir\"\nexec 7>\"$dir/key.lock\"; flock -w 60 7 || { echo \"another device is setting up the hub's key\" >&2; exit 6; }\nIFS= read -r proposed || true\nif ! grep -qxE '[0-9a-f]{64}' \"$dir/management.key\" 2>/dev/null; then\n  [[ \"$proposed\" =~ ^[0-9a-f]{64}$ ]] || { echo \"no valid key was proposed\" >&2; exit 7; }\n  umask 077; printf '%s\\n' \"$proposed\" > \"$dir/management.key.tmp\"; mv \"$dir/management.key.tmp\" \"$dir/management.key\"\n  echo created\nfi\ncat \"$dir/management.key\"\n";
+/**
+ * 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 declare const ADD_AUTH_SCRIPT = "set -euo pipefail\na=/home/user/.cli-proxy-api; rel=$1\ncase \"$rel\" in ''|/*|*..*) echo \"not a path inside the auth folder\" >&2; exit 2 ;; esac\nmkdir -p -m 0700 \"$(dirname \"$a/$rel\")\"\ntmp=$(mktemp \"$a/.adding.XXXXXX\"); chmod 0600 \"$tmp\"; cat > \"$tmp\"\nif ln \"$tmp\" \"$a/$rel\" 2>/dev/null; then echo added; else echo exists; fi\nrm -f \"$tmp\"\n";
+/** Sets the hub's logins aside after an export copied them out (the hub holds none until the next import). */
+export declare const SET_ASIDE_SCRIPT = "set -euo pipefail\na=/home/user/.cli-proxy-api; [ -d \"$a\" ] || exit 0\nto=\"$a.exported-$(date -u +%Y%m%dT%H%M%SZ)\"\nmv \"$a\" \"$to\"; mkdir -m 0700 \"$a\"; chmod 0700 \"$to\"\necho \"$to\"\n";
+export interface EnsureOptions {
+    /** The local config directory (hub info file). */
+    dir: string;
+    apiUrl: string;
+    /**
+     * The user's own CLIProxyAPI config (import): the hub's config is made from it when the hub has none yet, or only
+     * the defaults. A hub already configured from a user config keeps it.
+     */
+    userConfig?: string | null;
+    /** Only start the existing hub again (the forwarder): never create a workspace or replace the callback URL. */
+    repairOnly?: boolean;
+    /**
+     * With repairOnly: replace a callback URL the edge no longer accepts (`callback_invalid`: the API key that created it
+     * was revoked), which a probe of the stored URL shows. An import always probes before it reuses a stored URL.
+     */
+    renewInvalid?: boolean;
+    /** The probe of a stored callback URL (the cloud's when omitted). */
+    probe?: (url: string) => Promise<CallbackProbe>;
+    progress?: (message: string) => void;
+    /** Random management key (tests). */
+    randomKey?: () => string;
+}
+export interface EnsureResult {
+    info: HubInfo;
+    created: boolean;
+    /** `running` (nothing to do), `started` or `restarted`. */
+    process: 'running' | 'started' | 'restarted';
+    callbackReplaced: boolean;
+    /** The config written now; null when the hub kept its own. */
+    config: HubConfig | null;
+}
+/** The hub could not be made ready (exit 1, code `cli_proxy_hub`). */
+export declare class HubError extends CodedError {
+    name: string;
+    constructor(message: string, hint?: string);
+}
+/**
+ * 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 declare function ensureCliProxyHub(cloud: Shardflux | HubCloud, opts: EnsureOptions): Promise<EnsureResult>;
+/** 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;
+    callback_created_at: string;
+}
+/**
+ * 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 declare function hubCallback(ws: HubWorkspace, repairOnly?: boolean, portNumber?: number, probe?: (url: string) => Promise<CallbackProbe>): Promise<{
+    callback: StoredCallback;
+    replaced: boolean;
+}>;
+export type CallbackProbe = 'ok' | 'invalid' | 'unknown';
+/**
+ * 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 declare function probeCallback(url: string, timeoutMs?: number): Promise<CallbackProbe>;
+/** Where the hub stores a port's callback URL: callback.json (8317, management), callback-vm.json (8318, VMs). */
+export declare function callbackFile(port: number): string;
+/**
+ * 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 declare const CALLBACK_SCRIPT = "set -euo pipefail\ndir=/home/user/.cli-proxy-hub; mkdir -p \"$dir\"; f=${1:-callback.json}\ncase \"$f\" in callback.json|callback-vm.json) ;; *) echo \"unknown callback file\" >&2; exit 2 ;; esac\nexec 8>\"$dir/callback.lock\"\nflock -w 120 8 || { echo \"another device is setting up the hub's callback URL\" >&2; exit 6; }\nif [ -s \"$dir/$f\" ]; then printf 'STORED %s\\n' \"$(base64 -w0 < \"$dir/$f\")\"; else echo 'STORED -'; fi\nIFS= read -r -t 150 reply || { echo \"no answer from the device\" >&2; exit 7; }\ncase \"$reply\" in\n  KEEP|ABORT) exit 0 ;;\n  NEW\\ *) umask 077; printf '%s' \"${reply#NEW }\" | base64 -d > \"$dir/$f.tmp\"; mv \"$dir/$f.tmp\" \"$dir/$f\"; echo SAVED ;;\n  *) echo \"unexpected answer\" >&2; exit 8 ;;\nesac\n";
+/**
+ * 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 declare const LOCK_SCRIPT = "set -euo pipefail\ndir=/home/user/.cli-proxy-hub; mkdir -p \"$dir\"; name=${1:?}\n[[ \"$name\" =~ ^[a-z-]+$ ]] || { echo \"bad lock name\" >&2; exit 2; }\nexec 8>\"$dir/$name.lock\"\nflock -w 120 8 || { echo \"another device holds the hub's $name lock\" >&2; exit 6; }\necho LOCKED\nIFS= read -r -t 600 _ || true\necho RELEASED\n";
+export declare function parseStoredCallback(text: string): StoredCallback | null;