super-dsh 0.1.6 → 0.1.10-e

package/superd-hub/dist/client/agent-settings.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Runtime settings panels for the Hub's Agent Runtimes rows (P3, 2026-10-02
+ * user ruling).
+ *
+ * Interaction contract the UI follows (ruling, verbatim intent):
+ *   - clicking the ROW BODY expands that runtime's OWN settings inline
+ *     (accordion: at most one row open at a time);
+ *   - the row's existing right-hand `switch` affordance is the ONLY switch —
+ *     the panel never carries a second one.
+ *
+ * Config belongs to the adapter (agent-adapter-dev-rules §12), so this module
+ * owns only the presentation-side logic: which runtimes have a panel, the
+ * accordion transition, and a defensive parse of whatever the adapter's
+ * `*Auth/get` RPC returns. The adapter decides which auth methods exist, which
+ * are available on this machine, and which one is in force.
+ *
+ * Node-safe by construction (no DOM, no React, no fetch) — the host tsconfig
+ * dual-emits this file to `dist/client/agent-settings.js` so
+ * test/client-agent-settings.test.mjs can pin the parse and accordion rules
+ * under `node --test` (the roster.ts / mesh-api.ts precedent).
+ *
+ * @module superd-hub/client/agent-settings
+ */
+/** One selectable auth method as the adapter describes it. */
+export interface AuthMethodOption {
+    /** Stable id the RPC round-trips (`apiKey` | `oauth` | `adc`). */
+    readonly key: string;
+    /** Human label rendered on the option. */
+    readonly label: string;
+    /** Detected on THIS machine. Drives the availability annotation. */
+    readonly available: boolean;
+    /**
+     * Rendered but not selectable this round (the OAuth placeholder): the UI
+     * shows the shape and says why it is inert, instead of hiding it.
+     */
+    readonly placeholder: boolean;
+    /** One short line explaining the option (or why it is inert). */
+    readonly hint: string;
+}
+/** The adapter's answer to `<runtime>Auth/get`. */
+export interface RuntimeAuthView {
+    readonly methods: readonly AuthMethodOption[];
+    /** The user's explicit persisted choice; `null` when they have not made one. */
+    readonly selected: string | null;
+    /** What a new session would ACTUALLY use right now (ladder fallback applied). */
+    readonly effective: string | null;
+    /** Native file the adapter maintains for this runtime, when it owns one. */
+    readonly settingsPath?: string;
+    /** Free-form note from the adapter (e.g. why a mode is unavailable). */
+    readonly note?: string;
+}
+/**
+ * A runtime's settings panel: which adapter Remote answers for it.
+ *
+ * The namespace is the adapter's own service key — the hub forwards
+ * `envelope.method` verbatim, so the client needs only the name. A runtime absent
+ * from this table has no panel yet: its row still expands, to an explicit empty
+ * state rather than a dead control (the interaction stays uniform, and a runtime
+ * with nothing to configure SAYS so).
+ */
+export interface SettingsPanelSpec {
+    /** The adapter's Remote namespace (`agyAuth`). */
+    readonly namespace: string;
+    /**
+     * Which body the expanded row mounts. A runtime's config is not always a
+     * choice among a fixed set: Antigravity picks one sign-in form from a ladder,
+     * while Codex carries a LIST of providers the user adds, edits and removes
+     * (2026-10-03 ruling; the former active/select toggle is gone — which provider
+     * a Codex session runs on is DSH's own per-session model selection, not a
+     * hub-side switch). One namespace, two shapes — the kind discriminates.
+     */
+    readonly kind: 'auth' | 'providers';
+}
+/** The panel spec for a runtime, or `undefined` when it has none yet. */
+export declare function settingsPanelFor(agentKey: string): SettingsPanelSpec | undefined;
+/** Whether this runtime's row body expands into a real settings panel. */
+export declare function hasSettingsPanel(agentKey: string): boolean;
+/**
+ * Accordion transition: at most one row open. Clicking the open row closes it;
+ * clicking another moves the panel there in one click.
+ */
+export declare function toggleExpanded(current: string | null, key: string): string | null;
+/**
+ * Defensive parse of the RPC answer. Returns `undefined` for anything that is
+ * not a usable view (no methods, wrong shape, adapter absent) so the panel can
+ * render an explicit failure instead of an empty list that looks like success.
+ */
+export declare function parseAuthView(raw: unknown): RuntimeAuthView | undefined;
+/**
+ * The option the panel marks as in force: the effective one when the adapter
+ * named it, else the explicit selection. `undefined` when neither is known —
+ * the panel then marks nothing rather than guessing.
+ */
+export declare function activeMethod(view: RuntimeAuthView): AuthMethodOption | undefined;
+/** Whether an option may be picked (placeholders are rendered, never selected). */
+export declare function selectable(option: AuthMethodOption): boolean;
+/** One model behind a provider, as the panel lists it. */
+export interface ProviderModelOption {
+    readonly id: string;
+    /** Human label; the adapter sends one, else the id stands in. */
+    readonly label: string;
+    readonly contextWindow?: number;
+}
+/**
+ * The auth shapes the provider faces use between them: `apiKey` is shared,
+ * codex adds `env` (the key lives in a named variable), claude adds
+ * `authToken` (a Bearer token). Each face's adapter rejects the other's
+ * addition on save, which is why the form offers kinds per view
+ * (`authKindOptions`) instead of one fixed list.
+ */
+export type ProviderAuthKind = 'apiKey' | 'env' | 'authToken';
+/** One configured provider, listed but never carrying its key. */
+export interface ProviderOption {
+    readonly id: string;
+    readonly label: string;
+    readonly baseUrl: string;
+    readonly protocol: string;
+    readonly models: readonly ProviderModelOption[];
+    /** Which key shape the entry stores — see `ProviderAuthKind`. */
+    readonly authKind: ProviderAuthKind;
+    /** The variable an env-shaped provider expects. */
+    readonly envName?: string;
+    /** Whether a key is available — the ONLY thing the wire says about it. */
+    readonly hasKey: boolean;
+}
+/** One wire protocol the adapter offers, and whether it may be picked. */
+export interface ProviderProtocolOption {
+    readonly value: string;
+    readonly label: string;
+    readonly available: boolean;
+    readonly hint: string;
+}
+/**
+ * The files this surface reads and writes, shown so where an edit lands is
+ * never a surprise. Only `store` is common: each face names its own native
+ * files (codex: config/auth/catalogs; claude: settings), and a face that
+ * lacks a slot simply omits it — the footer renders what is there.
+ */
+export interface ProviderPaths {
+    readonly store: string;
+    readonly config?: string;
+    readonly auth?: string;
+    readonly catalogs?: string;
+    readonly settings?: string;
+}
+/** The adapter's answer to `codexProviders/get` / `claudeProviders/get` (and to every mutation). */
+export interface RuntimeProvidersView {
+    readonly providers: readonly ProviderOption[];
+    /**
+     * What the user's OWN native config currently names (codex: the provider
+     * `~/.codex/config.toml` selects; claude: the endpoint the `settings.json`
+     * env pins). Informational only — there is no action attached to it, and
+     * DSH's per-session model selection (not this list) decides what a session
+     * runs.
+     */
+    readonly native: {
+        readonly providerId?: string;
+        readonly baseUrl?: string;
+        readonly model?: string;
+    } | null;
+    /**
+     * The wire protocols the adapter offers, in the order it offers them. Empty
+     * for a face with no protocol choice (claude) — the panel then omits the
+     * dropdown instead of inventing options the runtime cannot run.
+     */
+    readonly protocols: readonly ProviderProtocolOption[];
+    readonly paths: ProviderPaths;
+    /** Epoch ms of the last reconcile against the native config, when one has happened. */
+    readonly syncedAt?: number;
+    readonly note?: string;
+}
+/**
+ * Defensive parse of the adapter's providers answer.
+ *
+ * `undefined` for anything that is not a usable view — but an empty `providers`
+ * array is valid (a fresh install), and so is a provider whose `models` array
+ * is empty. `protocols` is the codex face's field: an ABSENT field (the claude
+ * face) reads as "no protocol choice" and never fails the parse, while a
+ * present-but-unusable list is a malformed codex answer and rejects as before.
+ */
+export declare function parseProvidersView(raw: unknown): RuntimeProvidersView | undefined;
+/** One selectable auth shape for the add/edit form (`authKindOptions`). */
+export interface ProviderAuthKindOption {
+    readonly value: ProviderAuthKind;
+    readonly label: string;
+    readonly hint: string;
+}
+/**
+ * The auth shapes the add/edit form may pick for a provider, in display order.
+ *
+ * The view carries no explicit vocabulary field, so the panel reads it off the
+ * one field that distinguishes the faces today: `protocols`. The codex face
+ * advertises wire protocols and offers key-or-env-var; the claude face carries
+ * neither and offers its two header shapes instead. The list is per-view,
+ * never a fixed union — each adapter rejects the other's kinds on save, so a
+ * union dropdown would miscode silently. A third face extends the table.
+ */
+export declare function authKindOptions(view: RuntimeProvidersView): readonly ProviderAuthKindOption[];
+/**
+ * `provider / model` (codex) or `endpoint / model` (claude) — whichever halves
+ * the user's own native config names, joined for the one-line fact the panel
+ * states and never acts on.
+ */
+export declare function nativeDescription(native: RuntimeProvidersView['native']): string;
+/**
+ * The non-store paths joined for the panel's second footer line, in a fixed
+ * slot order. `undefined` when the face named none — the line is omitted
+ * entirely rather than rendered with blank slots.
+ */
+export declare function nativePathsLine(paths: ProviderPaths): string | undefined;

package/superd-hub/dist/client/agent-settings.js

@@ -0,0 +1,300 @@
+/**
+ * Runtime settings panels for the Hub's Agent Runtimes rows (P3, 2026-10-02
+ * user ruling).
+ *
+ * Interaction contract the UI follows (ruling, verbatim intent):
+ *   - clicking the ROW BODY expands that runtime's OWN settings inline
+ *     (accordion: at most one row open at a time);
+ *   - the row's existing right-hand `switch` affordance is the ONLY switch —
+ *     the panel never carries a second one.
+ *
+ * Config belongs to the adapter (agent-adapter-dev-rules §12), so this module
+ * owns only the presentation-side logic: which runtimes have a panel, the
+ * accordion transition, and a defensive parse of whatever the adapter's
+ * `*Auth/get` RPC returns. The adapter decides which auth methods exist, which
+ * are available on this machine, and which one is in force.
+ *
+ * Node-safe by construction (no DOM, no React, no fetch) — the host tsconfig
+ * dual-emits this file to `dist/client/agent-settings.js` so
+ * test/client-agent-settings.test.mjs can pin the parse and accordion rules
+ * under `node --test` (the roster.ts / mesh-api.ts precedent).
+ *
+ * @module superd-hub/client/agent-settings
+ */
+const SETTINGS_PANELS = {
+    // The one runtime with a settings surface this round: the CLI adapter owns the
+    // auth ladder and is the configuration surface for the user's local Antigravity.
+    agy: { namespace: 'agyAuth', kind: 'auth' },
+    // Codex's own config.toml names exactly one `model_provider`, but that file
+    // is the USER's and no longer the hub's toggle: Super D hosts the list
+    // cc-switch otherwise holds (add / edit / remove) and the adapter owns both
+    // the list and whatever it does with the native file.
+    codex: { namespace: 'codexProviders', kind: 'providers' },
+    // Both Codex lines host the SAME provider list (2026-10-04): the SDK half is
+    // the same agent through a different transport, so it carries the same panel
+    // and the same Remote namespace. The two worlds keep separate stores under
+    // their own `agents/<key>/`, so neither sees the other's list.
+    'codex-sdk': { namespace: 'codexProviders', kind: 'providers' },
+    // Claude serves the same providers view shape as Codex with no protocol
+    // dropdown: its adapter's view carries no `protocols` field (claude has no
+    // wire-protocol choice to make), so the body degrades to what the view does
+    // carry — two header auth kinds and its own native fact (2026-10-04).
+    claude: { namespace: 'claudeProviders', kind: 'providers' },
+};
+/** The panel spec for a runtime, or `undefined` when it has none yet. */
+export function settingsPanelFor(agentKey) {
+    return SETTINGS_PANELS[agentKey];
+}
+/** Whether this runtime's row body expands into a real settings panel. */
+export function hasSettingsPanel(agentKey) {
+    return settingsPanelFor(agentKey) !== undefined;
+}
+/**
+ * Accordion transition: at most one row open. Clicking the open row closes it;
+ * clicking another moves the panel there in one click.
+ */
+export function toggleExpanded(current, key) {
+    return current === key ? null : key;
+}
+function str(value) {
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+function methodOption(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const record = raw;
+    const key = str(record.key);
+    const label = str(record.label);
+    if (key === undefined || label === undefined)
+        return undefined;
+    return {
+        key,
+        label,
+        // Absent flags read as the conservative value: an older adapter that omits
+        // `available` must not render an option as usable when we cannot tell.
+        available: record.available === true,
+        placeholder: record.placeholder === true,
+        hint: str(record.hint) ?? '',
+    };
+}
+/**
+ * Defensive parse of the RPC answer. Returns `undefined` for anything that is
+ * not a usable view (no methods, wrong shape, adapter absent) so the panel can
+ * render an explicit failure instead of an empty list that looks like success.
+ */
+export function parseAuthView(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const record = raw;
+    if (!Array.isArray(record.methods))
+        return undefined;
+    const methods = record.methods.map(methodOption).filter((m) => m !== undefined);
+    if (methods.length === 0)
+        return undefined;
+    const settingsPath = str(record.settingsPath);
+    const note = str(record.note);
+    return {
+        methods,
+        selected: str(record.selected) ?? null,
+        effective: str(record.effective) ?? null,
+        ...(settingsPath === undefined ? {} : { settingsPath }),
+        ...(note === undefined ? {} : { note }),
+    };
+}
+/**
+ * The option the panel marks as in force: the effective one when the adapter
+ * named it, else the explicit selection. `undefined` when neither is known —
+ * the panel then marks nothing rather than guessing.
+ */
+export function activeMethod(view) {
+    const wanted = view.effective ?? view.selected;
+    if (wanted === null)
+        return undefined;
+    return view.methods.find((method) => method.key === wanted);
+}
+/** Whether an option may be picked (placeholders are rendered, never selected). */
+export function selectable(option) {
+    return !option.placeholder;
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+function modelOption(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const record = raw;
+    const id = nonEmpty(record.id);
+    if (id === undefined)
+        return undefined;
+    const contextWindow = record.contextWindow;
+    return {
+        id,
+        label: nonEmpty(record.displayName) ?? id,
+        ...(typeof contextWindow === 'number' && Number.isSafeInteger(contextWindow) && contextWindow > 0
+            ? { contextWindow }
+            : {}),
+    };
+}
+function providerAuthKind(raw) {
+    // An unstated or unknown kind reads as the shared conservative default,
+    // never as the other face's shape.
+    return raw === 'env' ? 'env' : raw === 'authToken' ? 'authToken' : 'apiKey';
+}
+function providerOption(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const record = raw;
+    const id = nonEmpty(record.id);
+    const label = nonEmpty(record.label);
+    const baseUrl = nonEmpty(record.baseUrl);
+    if (id === undefined || label === undefined || baseUrl === undefined)
+        return undefined;
+    const models = Array.isArray(record.models)
+        ? record.models.map(modelOption).filter((entry) => entry !== undefined)
+        : [];
+    const envName = nonEmpty(record.envName);
+    return {
+        id,
+        label,
+        baseUrl,
+        // An unknown protocol is never echoed into a control; the only value this
+        // harness can actually run is the safe default.
+        protocol: record.protocol === 'chat' ? 'chat' : 'responses',
+        models,
+        authKind: providerAuthKind(record.authKind),
+        ...(envName === undefined ? {} : { envName }),
+        hasKey: record.hasKey === true,
+    };
+}
+function protocolOption(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const record = raw;
+    const value = nonEmpty(record.value);
+    const label = nonEmpty(record.label);
+    if (value === undefined || label === undefined)
+        return undefined;
+    return { value, label, available: record.available === true, hint: nonEmpty(record.hint) ?? '' };
+}
+function providerPaths(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const record = raw;
+    const store = nonEmpty(record.store);
+    // The store is the only slot every face promises; the native files are the
+    // face's own, and an absent one stays absent rather than blank.
+    if (store === undefined)
+        return undefined;
+    const config = nonEmpty(record.config);
+    const auth = nonEmpty(record.auth);
+    const catalogs = nonEmpty(record.catalogs);
+    const settings = nonEmpty(record.settings);
+    return {
+        store,
+        ...(config === undefined ? {} : { config }),
+        ...(auth === undefined ? {} : { auth }),
+        ...(catalogs === undefined ? {} : { catalogs }),
+        ...(settings === undefined ? {} : { settings }),
+    };
+}
+/**
+ * Defensive parse of the adapter's providers answer.
+ *
+ * `undefined` for anything that is not a usable view — but an empty `providers`
+ * array is valid (a fresh install), and so is a provider whose `models` array
+ * is empty. `protocols` is the codex face's field: an ABSENT field (the claude
+ * face) reads as "no protocol choice" and never fails the parse, while a
+ * present-but-unusable list is a malformed codex answer and rejects as before.
+ */
+export function parseProvidersView(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const record = raw;
+    if (!Array.isArray(record.providers))
+        return undefined;
+    // Absent `protocols` (the claude face) → nothing to offer, the panel omits
+    // the dropdown. Present (the codex face) → must parse to at least one
+    // option, exactly as before.
+    let protocols = [];
+    if (record.protocols !== undefined) {
+        if (!Array.isArray(record.protocols))
+            return undefined;
+        protocols = record.protocols.map(protocolOption).filter((entry) => entry !== undefined);
+        if (protocols.length === 0)
+            return undefined;
+    }
+    const paths = providerPaths(record.paths);
+    if (paths === undefined)
+        return undefined;
+    const providers = record.providers.map(providerOption).filter((entry) => entry !== undefined);
+    const syncedAt = record.syncedAt;
+    const note = nonEmpty(record.note);
+    return {
+        providers,
+        native: nativeConfig(record.native),
+        protocols,
+        paths,
+        ...(typeof syncedAt === 'number' && Number.isFinite(syncedAt) ? { syncedAt } : {}),
+        ...(note === undefined ? {} : { note }),
+    };
+}
+/**
+ * The user's own native config as the adapter last read it. `null` when the
+ * adapter said nothing; otherwise an object carrying whichever halves were
+ * named — codex names a provider id, claude an endpoint URL — and an empty
+ * one is still news (the panel says the file names nothing).
+ */
+function nativeConfig(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const record = raw;
+    const providerId = nonEmpty(record.providerId);
+    const baseUrl = nonEmpty(record.baseUrl);
+    const model = nonEmpty(record.model);
+    return {
+        ...(providerId === undefined ? {} : { providerId }),
+        ...(baseUrl === undefined ? {} : { baseUrl }),
+        ...(model === undefined ? {} : { model }),
+    };
+}
+/** The codex face: a stored key, or the name of a variable holding it. */
+const KEY_OR_ENV = [
+    { value: 'apiKey', label: 'API key', hint: 'Stored with the provider; injected at launch.' },
+    { value: 'env', label: 'Environment variable', hint: 'The child reads the key from a named variable.' },
+];
+/** The claude face: both kinds are literal keys, differing only in the header. */
+const TWO_HEADER_SHAPES = [
+    { value: 'apiKey', label: 'API key (x-api-key)', hint: 'Sent as the x-api-key header.' },
+    { value: 'authToken', label: 'Bearer token', hint: 'Sent as the Authorization header.' },
+];
+/**
+ * The auth shapes the add/edit form may pick for a provider, in display order.
+ *
+ * The view carries no explicit vocabulary field, so the panel reads it off the
+ * one field that distinguishes the faces today: `protocols`. The codex face
+ * advertises wire protocols and offers key-or-env-var; the claude face carries
+ * neither and offers its two header shapes instead. The list is per-view,
+ * never a fixed union — each adapter rejects the other's kinds on save, so a
+ * union dropdown would miscode silently. A third face extends the table.
+ */
+export function authKindOptions(view) {
+    return view.protocols.length > 0 ? KEY_OR_ENV : TWO_HEADER_SHAPES;
+}
+/**
+ * `provider / model` (codex) or `endpoint / model` (claude) — whichever halves
+ * the user's own native config names, joined for the one-line fact the panel
+ * states and never acts on.
+ */
+export function nativeDescription(native) {
+    const parts = [native?.providerId ?? native?.baseUrl, native?.model].filter((part) => part !== undefined);
+    return parts.length === 0 ? 'no provider' : parts.join(' / ');
+}
+/**
+ * The non-store paths joined for the panel's second footer line, in a fixed
+ * slot order. `undefined` when the face named none — the line is omitted
+ * entirely rather than rendered with blank slots.
+ */
+export function nativePathsLine(paths) {
+    const parts = [paths.config, paths.auth, paths.catalogs, paths.settings].filter((part) => part !== undefined);
+    return parts.length === 0 ? undefined : parts.join(' · ');
+}

package/superd-hub/dist/client/mesh-api.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Machine-mesh data access for the Hub machines panel (mesh P1, Task 5):
+ * the client half of `/api/superd/machines` (host side: mesh-rpc.ts) —
+ * same-origin fetch behind the standard browser-trust + cookie fence, the
+ * roster face's house style (`credentials: 'same-origin'`). The localStorage
+ * ledger era (machines-store.ts, retired with this module) ended: the hub's
+ * registry is the single source of truth, this file only fetches it and
+ * coerces the wire answer into row views.
+ *
+ * Node-safe by construction — no DOM, no react, no @deepseek-ai imports —
+ * so the host tsc emits it to `dist/client/mesh-api.js` and
+ * test/client-mesh-view.test.mjs runs the pure halves (coercion, token-URL
+ * pre-check) under `node --test` without jsdom: the switch-core/toast-core
+ * precedent in reverse (pure logic kept beside the fetch wrappers, all under
+ * src/client). No fetch happens at import time.
+ *
+ * @module superd-hub/client/mesh-api
+ */
+/** Machine health as the hub reports it (mesh-rpc joins `'pending'` when the mesh-link status table has no entry for the row). */
+export type MeshMachineStatus = 'pending' | 'reachable' | 'unreachable' | 'auth-expired';
+/**
+ * One machine row for the panel: the wire's public projection (never token,
+ * never cookie) with `self` DERIVED from the response's self block — never
+ * stored per-row (the server's machines array carries remotes only; the
+ * flag exists so a self row surfacing in it still renders as self). Since
+ * I2 (mesh P3 5a) a reachable row may also carry `versionWarning` — the
+ * host's version-mismatch computation, coerced additively (absent stays
+ * absent; a non-string is dropped).
+ */
+export interface MeshMachineView {
+    readonly id: string;
+    readonly name: string;
+    readonly label: string;
+    readonly origin: string;
+    readonly status: MeshMachineStatus;
+    readonly lastProbeAt?: number;
+    /** I2: present exactly when the hub's probe found the peer's superd
+     *  version incompatible with ours (diff major/minor, or unparsable). */
+    readonly versionWarning?: string;
+    readonly self: boolean;
+}
+/** The response's self block: this machine's minted m4 id + label. */
+export interface MeshSelfView {
+    readonly id: string;
+    readonly label: string;
+}
+/** The coerced GET answer: self (when the wire carried a usable one) + the remote rows. */
+export interface MeshList {
+    readonly self?: MeshSelfView;
+    readonly machines: readonly MeshMachineView[];
+}
+/** The pairing input — origin is parsed out of the token URL SERVER-side (mesh-link), never a separate field. */
+export interface AddMachineInput {
+    readonly name: string;
+    readonly label?: string;
+    readonly tokenUrl: string;
+}
+/**
+ * Coerce a raw GET body into the panel's view list. Any bad shape degrades
+ * to the empty list (rows dropped individually, self dropped as a block) —
+ * the UI never crashes on a malformed answer.
+ *
+ * @param raw - the parsed JSON body (or anything else the wire produced).
+ * @returns self (when usable) + the coerced remote rows.
+ */
+export declare function coerceMachineList(raw: unknown): MeshList;
+/**
+ * The version-warning chip for one machine row (I2): present EXACTLY when the
+ * coerced row carries a `versionWarning` — the Hub machines panel renders
+ * the chip iff this returns a value. Kept here beside the coercion so the
+ * presence contract stays unit-testable without jsdom (the HubPage seat is
+ * a one-line consumer following the existing chip patterns).
+ */
+export declare function machineVersionChip(machine: Pick<MeshMachineView, 'versionWarning'>): {
+    text: string;
+} | undefined;
+/**
+ * GET the machine list (self + remotes).
+ *
+ * @returns the coerced list — a malformed body degrades to the empty list, never a throw.
+ * @throws when the request fails or the face answers non-2xx.
+ */
+export declare function fetchMachines(): Promise<MeshList>;
+/**
+ * POST a pairing `{name, label?, tokenUrl}` (label omitted → the server
+ * collapses it to the name).
+ *
+ * @throws Error(body.error) when the face answers non-2xx — the message is
+ * mesh-link's own, already token-redacted.
+ */
+export declare function addMachine(input: AddMachineInput): Promise<void>;
+/**
+ * DELETE one remote row by id (`{removed: boolean}` answers even for
+ * unknown ids — a false removal is a reload, not an error).
+ *
+ * @throws Error(body.error) on a non-2xx answer.
+ */
+export declare function removeMachine(id: string): Promise<void>;
+/**
+ * POST `{op: 'reprobe', id}` — a fresh probe of one remote; the outcome
+ * (even unreachable/auth-expired) lands in the status table server-side, so
+ * the caller reloads rather than interpreting the probe body.
+ *
+ * @throws Error(body.error) on a non-2xx answer (the op itself failed).
+ */
+export declare function reprobeMachine(id: string): Promise<void>;
+/**
+ * The standing cadence note (D18): machine status refresh rides the hub's
+ * 5-minute sweep — the panel renders this verbatim beside its live-fetch
+ * control. English copy to match the DSH UI.
+ */
+export declare const AUTO_REFRESH_NOTE = "auto-refreshes every 5 min";
+/**
+ * The per-machine last-fetch line, shaped from the row's `lastProbeAt`
+ * (the hub's status table stamp — mesh-rpc joins it on every GET).
+ * Pure by design (the UI passes its own `now`): headless-testable without
+ * jsdom, same presence contract as {@link machineVersionChip} — absent or
+ * non-finite stamp means "never probed" and the panel omits the line.
+ *
+ * @param lastProbeAt - epoch ms of the machine's last recorded probe.
+ * @param now - epoch ms the panel renders at.
+ * @returns "Updated 2m ago" / "Updated just now" / … , or undefined.
+ */
+export declare function lastFetchLabel(lastProbeAt: number | undefined, now: number): string | undefined;
+/**
+ * Client-side pre-check before a pairing submit: a parseable absolute
+ * http(s) URL carrying a non-empty `token` query param. The server re-parses
+ * authoritatively (mesh-link's parseTokenUrl); this only keeps obviously
+ * dead drafts off the wire.
+ *
+ * @param input - the raw token-URL draft (trim before calling).
+ * @returns whether the draft is submit-shaped.
+ */
+export declare function validTokenUrl(input: string): boolean;