super-dsh 0.1.6 → 0.1.10-e

package/superd-hub/dist/client/mesh-api.js

@@ -0,0 +1,219 @@
+/**
+ * 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
+ */
+/**
+ * Base path of the mesh machines API — the client-side spelling of the
+ * host's `MESH_API_BASE` (mesh-rpc.ts). Duplicated deliberately: importing
+ * the host module would drag its node:fs-backed dependencies into the
+ * browser bundle; a path literal cannot drift silently because the mesh-rpc
+ * route registration and this file are reviewed together.
+ */
+const MESH_API_BASE = '/api/superd/machines';
+/** The statuses the wire may carry; anything else coerces to `'pending'`. */
+const STATUSES = ['pending', 'reachable', 'unreachable', 'auth-expired'];
+/** Coerce the self block; a shape without a non-empty string id + string label is simply absent. */
+function coerceSelf(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return undefined;
+    const { id, label } = raw;
+    if (typeof id !== 'string' || id === '' || typeof label !== 'string')
+        return undefined;
+    return { id, label };
+}
+/**
+ * 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 function coerceMachineList(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return { machines: [] };
+    const record = raw;
+    const self = coerceSelf(record.self);
+    const machines = [];
+    if (Array.isArray(record.machines)) {
+        for (const entry of record.machines) {
+            if (typeof entry !== 'object' || entry === null || Array.isArray(entry))
+                continue;
+            const row = entry;
+            if (typeof row.id !== 'string' || row.id === '')
+                continue;
+            if (typeof row.name !== 'string' || row.name === '')
+                continue;
+            if (typeof row.origin !== 'string' || row.origin === '')
+                continue;
+            const status = typeof row.status === 'string' && STATUSES.includes(row.status)
+                ? row.status
+                : 'pending';
+            const base = {
+                id: row.id,
+                name: row.name,
+                label: typeof row.label === 'string' && row.label !== '' ? row.label : row.name,
+                origin: row.origin,
+                status,
+                self: self !== undefined && row.id === self.id,
+            };
+            const withProbe = typeof row.lastProbeAt === 'number' ? { ...base, lastProbeAt: row.lastProbeAt } : base;
+            machines.push(typeof row.versionWarning === 'string' && row.versionWarning !== ''
+                ? { ...withProbe, versionWarning: row.versionWarning }
+                : withProbe);
+        }
+    }
+    return self === undefined ? { machines } : { self, machines };
+}
+/**
+ * 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 function machineVersionChip(machine) {
+    return machine.versionWarning === undefined ? undefined : { text: machine.versionWarning };
+}
+/** Read a non-2xx body's `{error}` message; degrade to the bare status line. */
+async function errorText(response) {
+    try {
+        const body = await response.json();
+        if (typeof body?.error === 'string' && body.error !== '')
+            return body.error;
+    }
+    catch {
+        /* not JSON — the status line below is the message */
+    }
+    return `HTTP ${response.status}`;
+}
+/**
+ * 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 async function fetchMachines() {
+    const response = await fetch(MESH_API_BASE, { credentials: 'same-origin' });
+    if (!response.ok)
+        throw new Error(await errorText(response));
+    return coerceMachineList(await response.json().catch(() => undefined));
+}
+/**
+ * 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 async function addMachine(input) {
+    const body = { name: input.name, tokenUrl: input.tokenUrl };
+    if (typeof input.label === 'string' && input.label !== '')
+        body.label = input.label;
+    const response = await fetch(MESH_API_BASE, {
+        credentials: 'same-origin',
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok)
+        throw new Error(await errorText(response));
+}
+/**
+ * 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 async function removeMachine(id) {
+    const response = await fetch(`${MESH_API_BASE}?id=${encodeURIComponent(id)}`, {
+        credentials: 'same-origin',
+        method: 'DELETE',
+    });
+    if (!response.ok)
+        throw new Error(await errorText(response));
+}
+/**
+ * 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 async function reprobeMachine(id) {
+    const response = await fetch(MESH_API_BASE, {
+        credentials: 'same-origin',
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ op: 'reprobe', id }),
+    });
+    if (!response.ok)
+        throw new Error(await errorText(response));
+}
+/**
+ * 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 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 function lastFetchLabel(lastProbeAt, now) {
+    if (typeof lastProbeAt !== 'number' || !Number.isFinite(lastProbeAt))
+        return undefined;
+    const seconds = Math.max(0, Math.floor((now - lastProbeAt) / 1000));
+    if (seconds < 60)
+        return 'Updated just now';
+    if (seconds < 3600)
+        return `Updated ${Math.floor(seconds / 60)}m ago`;
+    if (seconds < 86_400)
+        return `Updated ${Math.floor(seconds / 3600)}h ago`;
+    return `Updated ${Math.floor(seconds / 86_400)}d ago`;
+}
+/**
+ * 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 function validTokenUrl(input) {
+    if (typeof input !== 'string' || input === '')
+        return false;
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return false;
+    const token = url.searchParams.get('token');
+    return token !== null && token !== '';
+}

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

@@ -0,0 +1,63 @@
+/**
+ * Machine-section grouping for the Hub switch surfaces (mesh P2, Task 4):
+ * the pure core that turns a roster plus the machines API's label map into
+ * the menu/row sections — the LOCAL group first under the fixed
+ * {@link LOCAL_MACHINE_LABEL} heading, then one section per remote machine
+ * sorted by display label (key as the tiebreak). This is the client-half
+ * mirror of the host's wire ordering (agent-roster.ts sorts federated rows
+ * by machine label server-side); the client re-derives it so the sections
+ * stay correct even when the wire order changes or the roster is seeded
+ * from a stale baked global.
+ *
+ * The label map comes from `fetchMachines()` (mesh-api.ts): machine label,
+ * falling back to the name, falling back to the raw m4 —
+ * {@link machineLabelsFrom} builds it, and a machine the registry no longer
+ * knows simply keeps its raw m4 as the section label (never a crash).
+ *
+ * Node-safe by construction — no DOM, no react, no @deepseek-ai imports —
+ * so the host tsc emits it to `dist/client/mesh-groups.js` and
+ * test/client-mesh-groups.test.mjs runs the pure halves under `node --test`
+ * without jsdom: the mesh-api precedent. No fetch happens at import time.
+ *
+ * @module superd-hub/client/mesh-groups
+ */
+import type { MeshList } from './mesh-api.js';
+import type { AgentLink } from './roster.js';
+/** The machine key every LOCAL roster row carries (older host shapes may omit the field — grouping treats absent as local). */
+export declare const LOCAL_MACHINE_KEY = "local";
+/** The LOCAL section's fixed display label — this machine needs no registry row to be named. */
+export declare const LOCAL_MACHINE_LABEL = "This machine";
+/** One machine's section: its grouping key, its display label, and its rows in roster order. */
+export interface MachineAgentGroup {
+    /** The grouping key: {@link LOCAL_MACHINE_KEY} or the owning machine's m4. */
+    readonly key: string;
+    /** The section heading: the machine's display label ({@link LOCAL_MACHINE_LABEL} for local, the raw key when no label is known). */
+    readonly label: string;
+    /** This machine's roster rows, keeping the roster's own order. */
+    readonly agents: readonly AgentLink[];
+}
+/**
+ * Group a roster into machine sections for the switch menu and the Hub
+ * roster rows: the LOCAL group first (label {@link LOCAL_MACHINE_LABEL};
+ * rows whose `machine` is `'local'` or absent), then one group per remote
+ * machine sorted by display label (code-unit order) with the machine key as
+ * the tiebreak. Members keep the roster's given order inside their group;
+ * groups only exist for machines actually present in the roster (no empty
+ * local section when every row is federated). An unknown label map entry —
+ * missing, or an empty string — falls back to the raw machine key.
+ *
+ * @param links - the roster rows (any order; the section order is derived, not inherited).
+ * @param machineLabels - machine key (m4) → display label; the machines API answer via {@link machineLabelsFrom}.
+ * @returns the sections, local first.
+ */
+export declare function groupByMachine(links: readonly AgentLink[], machineLabels: Readonly<Record<string, string>>): MachineAgentGroup[];
+/**
+ * The machines API answer → the grouping label map: every remote row's
+ * `id → label` (mesh-api's coercion already collapsed an empty label to the
+ * machine name) plus the self block's own `m4 → label`. An absent list is
+ * the empty map — the caller's degrade-to-flat trigger, never a throw.
+ *
+ * @param list - the coerced `fetchMachines()` answer, when it succeeded.
+ * @returns machine key → display label (the raw key stays absent, not mapped).
+ */
+export declare function machineLabelsFrom(list: MeshList | undefined): Record<string, string>;

package/superd-hub/dist/client/mesh-groups.js

@@ -0,0 +1,66 @@
+/** The machine key every LOCAL roster row carries (older host shapes may omit the field — grouping treats absent as local). */
+export const LOCAL_MACHINE_KEY = 'local';
+/** The LOCAL section's fixed display label — this machine needs no registry row to be named. */
+export const LOCAL_MACHINE_LABEL = 'This machine';
+/** Whether a row's machine field parks it in the local section: `'local'` or absent (the coercion drops unknown values). */
+function isLocalMachine(machine) {
+    return machine === undefined || machine === LOCAL_MACHINE_KEY;
+}
+/**
+ * Group a roster into machine sections for the switch menu and the Hub
+ * roster rows: the LOCAL group first (label {@link LOCAL_MACHINE_LABEL};
+ * rows whose `machine` is `'local'` or absent), then one group per remote
+ * machine sorted by display label (code-unit order) with the machine key as
+ * the tiebreak. Members keep the roster's given order inside their group;
+ * groups only exist for machines actually present in the roster (no empty
+ * local section when every row is federated). An unknown label map entry —
+ * missing, or an empty string — falls back to the raw machine key.
+ *
+ * @param links - the roster rows (any order; the section order is derived, not inherited).
+ * @param machineLabels - machine key (m4) → display label; the machines API answer via {@link machineLabelsFrom}.
+ * @returns the sections, local first.
+ */
+export function groupByMachine(links, machineLabels) {
+    const local = [];
+    const byKey = new Map();
+    for (const link of links) {
+        if (isLocalMachine(link.machine)) {
+            local.push(link);
+            continue;
+        }
+        const machine = link.machine;
+        const bucket = byKey.get(machine);
+        if (bucket === undefined)
+            byKey.set(machine, [link]);
+        else
+            bucket.push(link);
+    }
+    const labelOf = (key) => {
+        const label = machineLabels[key];
+        return typeof label === 'string' && label !== '' ? label : key;
+    };
+    const remote = [...byKey.entries()]
+        .map(([key, agents]) => ({ key, label: labelOf(key), agents }))
+        .sort((a, b) => (a.label !== b.label ? (a.label < b.label ? -1 : 1) : (a.key < b.key ? -1 : a.key > b.key ? 1 : 0)));
+    return local.length > 0 ? [{ key: LOCAL_MACHINE_KEY, label: LOCAL_MACHINE_LABEL, agents: local }, ...remote] : remote;
+}
+/**
+ * The machines API answer → the grouping label map: every remote row's
+ * `id → label` (mesh-api's coercion already collapsed an empty label to the
+ * machine name) plus the self block's own `m4 → label`. An absent list is
+ * the empty map — the caller's degrade-to-flat trigger, never a throw.
+ *
+ * @param list - the coerced `fetchMachines()` answer, when it succeeded.
+ * @returns machine key → display label (the raw key stays absent, not mapped).
+ */
+export function machineLabelsFrom(list) {
+    const labels = {};
+    if (list === undefined)
+        return labels;
+    for (const machine of list.machines) {
+        labels[machine.id] = machine.label !== '' ? machine.label : machine.name;
+    }
+    if (list.self !== undefined)
+        labels[list.self.id] = list.self.label;
+    return labels;
+}

package/superd-hub/dist/client/roster.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared roster projection for the client half: the runtime list every Hub
+ * switch surface (the HubPanelIcon chevron menu, the HubPage Agent Runtimes
+ * rows — the sole agent-switch surface since the T-B RuntimeSeat retirement)
+ * renders. Source of truth = the hub's read-only `/api/agent-runtime` face;
+ * the baked `window.__DSH_AGENT_ROSTER__` global only seeds the first paint
+ * (a world page's baked copy can be stale, so the wire answer is
+ * authoritative).
+ *
+ * Node-safe by construction (no DOM globals, fetch only inside functions) —
+ * the host tsc dual-emits this file to `dist/client/roster.js` so
+ * test/client-mesh-groups.test.mjs can pin the coercion under `node --test`
+ * (the mesh-api/mesh-groups precedent).
+ *
+ * @module superd-hub/client/roster
+ */
+/** One runtime as the roster hands it over: key, display label, mount path, machine. */
+export interface AgentLink {
+    readonly key: string;
+    readonly label: string;
+    readonly path: string;
+    /**
+     * Machine the runtime comes from (mesh P2): `'local'` for this machine's
+     * rows, the owning machine's m4 id for federated rows. Optional and
+     * additive: the coercion drops unknown values to `undefined` and the
+     * grouping (mesh-groups.ts) treats absent as local — no parse-boundary
+     * default anymore, the wire's machine ids pass through verbatim.
+     */
+    readonly machine?: string;
+    /** Whether the world's data plane is up. Optional: older hosts omit it (parse boundary default). */
+    readonly ready?: boolean;
+    /** Whether the world's spawn REJECTED. Optional: older hosts omit it. */
+    readonly failed?: boolean;
+}
+/** The native runtime every composition can fall back to. */
+export declare const NATIVE_LINK: AgentLink;
+/** Seed from the index-baked roster global, when the page carries one. */
+export declare function rosterFromGlobal(): AgentLink[] | undefined;
+/** Normalize the current mount root: `/omp` and `/omp/` are the same page. */
+export declare function currentMountPath(): string;
+/**
+ * Ask the hub for the live roster (preferred `agents` shape with paths; the
+ * bare `available` key list falls back to `/<key>/` paths).
+ *
+ * @returns the runtime links, keyed by runtime.
+ * @throws when the face is unreachable or returns no usable roster.
+ */
+export declare function fetchRoster(): Promise<AgentLink[]>;

package/superd-hub/dist/client/roster.js

@@ -0,0 +1,102 @@
+/**
+ * Shared roster projection for the client half: the runtime list every Hub
+ * switch surface (the HubPanelIcon chevron menu, the HubPage Agent Runtimes
+ * rows — the sole agent-switch surface since the T-B RuntimeSeat retirement)
+ * renders. Source of truth = the hub's read-only `/api/agent-runtime` face;
+ * the baked `window.__DSH_AGENT_ROSTER__` global only seeds the first paint
+ * (a world page's baked copy can be stale, so the wire answer is
+ * authoritative).
+ *
+ * Node-safe by construction (no DOM globals, fetch only inside functions) —
+ * the host tsc dual-emits this file to `dist/client/roster.js` so
+ * test/client-mesh-groups.test.mjs can pin the coercion under `node --test`
+ * (the mesh-api/mesh-groups precedent).
+ *
+ * @module superd-hub/client/roster
+ */
+/** The native runtime every composition can fall back to. */
+export const NATIVE_LINK = { key: 'native', label: 'DSH', path: '/', machine: 'local', ready: true, failed: false };
+/** Labels for the read-only face's bare keys (it reports keys, not labels). */
+const FALLBACK_LABELS = {
+    native: 'DSH',
+    omp: 'OMP',
+    codex: 'Codex',
+    claude: 'Claude',
+    pi: 'Pi',
+    hermes: 'Hermes',
+    agy: 'Antigravity',
+    // The opt-in SDK halves carry their own keys so a host that reports only keys
+    // still renders a distinguishable label (the composite rows are `disabled: true`
+    // by default, so these appear only once an operator turns one on).
+    'omp-sdk': 'OMP (SDK)',
+    'agy-sdk': 'Antigravity (SDK)',
+    'codex-sdk': 'Codex (SDK)',
+};
+/** Coerce a wire `agents` array into links; undefined when unusable/empty. */
+function coerceAgents(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const links = [];
+    for (const entry of raw) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const { key, label, path, machine } = entry;
+        if (typeof key !== 'string' || typeof path !== 'string')
+            continue;
+        links.push({
+            key,
+            label: typeof label === 'string' ? label : (FALLBACK_LABELS[key] ?? key),
+            path,
+            // Passthrough (mesh P2 Task 4): a string machine id rides verbatim
+            // ('local' for this machine's rows, the m4 for federated rows);
+            // anything else is dropped to undefined — the grouping treats absent
+            // as local, so an older host shape needs no default here.
+            machine: typeof machine === 'string' && machine !== '' ? machine : undefined,
+            ready: entry.ready === true,
+            failed: entry.failed === true,
+        });
+    }
+    return links.length > 0 ? links : undefined;
+}
+/** Seed from the index-baked roster global, when the page carries one. */
+export function rosterFromGlobal() {
+    const raw = globalThis.__DSH_AGENT_ROSTER__;
+    return coerceAgents(raw?.agents);
+}
+/** Normalize the current mount root: `/omp` and `/omp/` are the same page. */
+export function currentMountPath() {
+    const location = globalThis.location;
+    const pathname = location === undefined ? '/' : location.pathname;
+    if (pathname === '' || pathname === '/')
+        return '/';
+    return pathname.endsWith('/') ? pathname : `${pathname}/`;
+}
+/**
+ * Ask the hub for the live roster (preferred `agents` shape with paths; the
+ * bare `available` key list falls back to `/<key>/` paths).
+ *
+ * @returns the runtime links, keyed by runtime.
+ * @throws when the face is unreachable or returns no usable roster.
+ */
+export async function fetchRoster() {
+    const response = await fetch('/api/agent-runtime', { credentials: 'same-origin' });
+    if (!response.ok)
+        throw new Error(`HTTP ${response.status}`);
+    const json = (await response.json());
+    const agents = coerceAgents(json.agents);
+    if (agents !== undefined)
+        return agents;
+    if (Array.isArray(json.available)) {
+        const links = [];
+        for (const key of json.available) {
+            if (typeof key !== 'string')
+                continue;
+            links.push(key === 'native'
+                ? NATIVE_LINK
+                : { key, label: FALLBACK_LABELS[key] ?? key, path: `/${key}/`, machine: 'local', ready: key === 'native' });
+        }
+        if (links.length > 0)
+            return links;
+    }
+    throw new Error('agent-runtime face returned no roster');
+}

package/superd-hub/dist/client/runtime-settings-api.d.ts

@@ -0,0 +1,76 @@
+/**
+ * runtime-settings-api.ts — the browser half of a runtime's settings panel.
+ *
+ * The panel's config belongs to the ADAPTER, so nothing here knows what an auth
+ * method is: it posts a `client-request` envelope at the runtime's own world and
+ * hands the adapter's answer to `parseAuthView` (agent-settings.ts).
+ *
+ *    POST /hub/api?agent=agy
+ *    { type:'client-request', rpcId, method:'agyAuth/get'|'agyAuth/set',
+ *      payload:{ args: {} | { request: { mode } } } }
+ *
+ * `/hub/api` is the hub family's prefix mount (`hub-route.ts`), which forwards
+ * `method` verbatim to the addressed world's `typertGateway`. The path needs no
+ * `CONTROL` exemption in fusion-transport.ts: the rewrite only touches same-origin
+ * `/api/...` paths, and `/hub/...` is never one of them.
+ *
+ * Node-safe: no DOM reach at module scope and `fetch` is injectable, so
+ * test/client-runtime-settings.test.mjs pins the envelope and every failure
+ * branch under `node --test` (the mesh-api.ts precedent).
+ *
+ * @module superd-hub/client/runtime-settings-api
+ */
+import { type RuntimeAuthView, type RuntimeProvidersView } from './agent-settings.js';
+/** Structural slice of `fetch` — the bundle uses the global, tests inject a stub. */
+export type FetchLike = (input: string, init: RequestInit) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+/** One rpcId for request/response correlation. `randomUUID` needs a secure context. */
+export declare function mintRpcId(): string;
+/** The wire body of one unary call. */
+export interface ClientRequestEnvelope {
+    type: 'client-request';
+    rpcId: string;
+    method: string;
+    payload: {
+        args: Record<string, unknown>;
+    };
+}
+/** Build the envelope for one panel call (exported so tests pin the exact wire shape). */
+/** The operation names the adapter Remotes accept (auth ladder + providers). */
+export type RuntimeSettingsOp = 'get' | 'set' | 'save' | 'remove';
+export declare function settingsEnvelope(namespace: string, op: RuntimeSettingsOp, args: Record<string, unknown>): ClientRequestEnvelope;
+/** What a caller can do with a failed panel call — kept structural for the tests. */
+declare function messageOf(error: unknown): string;
+/**
+ * One unary call at a runtime's world, unwrapped to the RPC's value.
+ *
+ * Every failure mode is reported as a thrown `Error` carrying the adapter's own
+ * message where one exists: a transport failure, a malformed answer, and the
+ * gateway's business error (`{ok:false,error}`) must not look alike to the panel.
+ *
+ * @param agentKey - roster key addressing the world (`?agent=`).
+ * @param namespace - the adapter's Remote namespace (`agyAuth`).
+ * @param op - the Remote method.
+ * @param args - exact named wire arguments.
+ * @param doFetch - fetch implementation (tests inject).
+ * @returns the raw RPC value.
+ * @throws {Error} on transport, framing, or gateway failure.
+ */
+export declare function callRuntimeSettings(agentKey: string, namespace: string, op: RuntimeSettingsOp, args: Record<string, unknown>, doFetch?: FetchLike): Promise<unknown>;
+/** Read one runtime's panel state, parsed. */
+export declare function fetchAuthView(agentKey: string, namespace: string, doFetch?: FetchLike): Promise<RuntimeAuthView>;
+/** Adopt one auth form (`null` clears the explicit choice). */
+export declare function setAuthMode(agentKey: string, namespace: string, mode: string | null, doFetch?: FetchLike): Promise<RuntimeAuthView>;
+/** Read the multi-provider state of one runtime. */
+export declare function fetchProvidersView(agentKey: string, namespace: string, doFetch?: FetchLike): Promise<RuntimeProvidersView>;
+/**
+ * Add or edit one provider in the adapter's list. Which provider a session runs
+ * on is DSH's own per-session model selection, so this touches no active half.
+ */
+export declare function saveProvider(agentKey: string, namespace: string, provider: unknown, doFetch?: FetchLike): Promise<RuntimeProvidersView>;
+/** Drop one provider from the list. Does not rewrite the runtime's own config. */
+export declare function removeProvider(agentKey: string, namespace: string, id: string, doFetch?: FetchLike): Promise<RuntimeProvidersView>;
+export { messageOf as settingsErrorText };