@atomic-chat/core 0.5.1 → 0.13.2

package/dist/backend/select/turboquant-tiers.js

@@ -0,0 +1,114 @@
+/**
+ * Ideal-backend detection and update check for the TurboQuant fork (`llamacpp` provider). Port of
+ * the decision half of `detectIdealBackendType` in `extensions/llamacpp-extension/src/index.ts` and
+ * of `find_latest_version_for_backend` / `check_backend_for_updates` in
+ * `src-tauri/plugins/tauri-plugin-llamacpp/src/backend.rs`.
+ *
+ * Why it cannot share `tiers.ts`: the fork names its builds differently, publishes Linux CUDA and
+ * ROCm builds upstream does not, keeps a 6 GiB VRAM floor where upstream went to 2 GiB, and runs no
+ * `--list-devices` tier probe. Nothing here reads hardware, disk or network: the facts and the
+ * catalog are parameters.
+ */
+import { AtomicCoreError } from '../../contracts/index.js';
+import { compareTurboquantBackendsForSort, getTurboquantSupportedFeatures, mapOldTurboquantBackendToNew, TURBOQUANT_GPU_MIN_VRAM_MIB, } from '../turboquant.js';
+import { stripBom } from '../version.js';
+import { normalizeFeatures } from './features.js';
+import { integratedGpuOnly } from './tiers.js';
+/** The fork's "any GPU backend in the catalog" test — broader than upstream's, it matches every id. */
+export function isTurboquantGpuBackendId(backend) {
+    return /(cuda-\d|vulkan|rocm)/.test(stripBom(backend));
+}
+/**
+ * Which fork build this host should ideally run. Windows: CUDA 13 → CUDA 12 → Vulkan (6 GiB, not
+ * integrated-only). Linux x64: CUDA 13 → CUDA 12 → ROCm → Vulkan (ROCm and Vulkan share the VRAM
+ * and integrated guards). Every pick is a catalog entry, so the id is one the release stream carries.
+ * A GPU-capable host whose catalog has no GPU build is `detection-failed` (the release index was
+ * unreachable); macOS, arm64 and hosts without a usable tier are `cpu-optimal`. Any thrown error is
+ * `detection-failed`. The caller wraps this in its 20 s timeout.
+ */
+export async function detectIdealTurboquantBackendType(input) {
+    const warn = input.onWarn ?? (() => { });
+    try {
+        const { osType, gpus } = input;
+        const features = normalizeFeatures(getTurboquantSupportedFeatures(osType, input.cpuExtensions, gpus, input.rocm));
+        const hasEnoughVram = gpus.some((gpu) => (gpu.total_memory ?? 0) >= TURBOQUANT_GPU_MIN_VRAM_MIB);
+        const integratedOnly = integratedGpuOnly(gpus);
+        const archSuffix = input.arch.includes('aarch64') || input.arch.includes('arm64') ? 'arm64' : 'x64';
+        if (osType !== 'windows' && osType !== 'linux')
+            return { kind: 'cpu-optimal' };
+        const catalog = await input.listAvailableBackends();
+        const pick = (pattern) => {
+            const hit = catalog.find((b) => pattern.test(stripBom(b.backend)));
+            return hit ? stripBom(hit.backend) : null;
+        };
+        const anyGpuBackendAvailable = catalog.some((b) => isTurboquantGpuBackendId(b.backend));
+        if (osType === 'windows') {
+            const cuda13 = pick(new RegExp(`^windows-${archSuffix}-cuda-13(\\.\\d+)?$`));
+            const cuda12 = pick(new RegExp(`^windows-${archSuffix}-cuda-12(\\.\\d+)?$`));
+            const vulkan = pick(new RegExp(`^windows-${archSuffix}-vulkan$`));
+            if (features.cuda13 && cuda13)
+                return { kind: 'gpu', backend: cuda13 };
+            if (features.cuda12 && cuda12)
+                return { kind: 'gpu', backend: cuda12 };
+            if (features.vulkan && hasEnoughVram && vulkan && !integratedOnly)
+                return { kind: 'gpu', backend: vulkan };
+            const gpuCapable = features.cuda13 || features.cuda12 || (features.vulkan && hasEnoughVram && !integratedOnly);
+            if (gpuCapable && !anyGpuBackendAvailable) {
+                warn('detectIdealBackendType: GPU-capable Windows host but no turboquant GPU backend in catalog — treating as detection failure (manifest likely unreachable)');
+                return { kind: 'detection-failed' };
+            }
+            return { kind: 'cpu-optimal' };
+        }
+        if (archSuffix === 'x64') {
+            const cuda13 = pick(/^linux-x64-cuda-13(\.\d+)?$/);
+            const cuda12 = pick(/^linux-x64-cuda-12(\.\d+)?$/);
+            const rocm = pick(/^linux-x64-rocm$/);
+            const vulkan = pick(/^linux-x64-vulkan$/);
+            const gpuWorthIt = hasEnoughVram && !integratedOnly;
+            if (features.cuda13 && cuda13)
+                return { kind: 'gpu', backend: cuda13 };
+            if (features.cuda12 && cuda12)
+                return { kind: 'gpu', backend: cuda12 };
+            if (features.rocm && gpuWorthIt && rocm)
+                return { kind: 'gpu', backend: rocm };
+            if (features.vulkan && gpuWorthIt && vulkan)
+                return { kind: 'gpu', backend: vulkan };
+            const gpuCapable = features.cuda13 || features.cuda12 || ((features.rocm || features.vulkan) && gpuWorthIt);
+            if (gpuCapable && !anyGpuBackendAvailable) {
+                warn('detectIdealBackendType: GPU-capable Linux host but no turboquant GPU backend in catalog — treating as detection failure (manifest likely unreachable)');
+                return { kind: 'detection-failed' };
+            }
+        }
+        return { kind: 'cpu-optimal' };
+    }
+    catch (err) {
+        warn(`detectIdealBackendType failed: ${err instanceof Error ? err.message : String(err)}`);
+        return { kind: 'detection-failed' };
+    }
+}
+/**
+ * Newest `<version>/<backend>` whose normalised fork id equals `backendType`, or `null`. The
+ * original backend spelling is kept in the result (Rust `find_latest_version_for_backend`).
+ */
+export function findLatestTurboquantVersionForBackend(versionBackends, backendType) {
+    const matching = versionBackends.filter((vb) => mapOldTurboquantBackendToNew(vb.backend) === backendType);
+    const best = [...matching].sort(compareTurboquantBackendsForSort)[0];
+    return best ? `${best.version}/${best.backend}` : null;
+}
+/**
+ * Whether a newer build of the current backend's (normalised) fork type exists. `new_version` is
+ * `"0"` and `target_backend` `null` when nothing newer or nothing at all is listed.
+ */
+export function checkTurboquantBackendForUpdates(currentBackendString, versionBackends) {
+    const parts = currentBackendString.split('/');
+    if (parts.length !== 2) {
+        throw new AtomicCoreError('INVALID_ARGUMENT', `Invalid current backend format: ${currentBackendString}`);
+    }
+    const effectiveType = mapOldTurboquantBackendToNew(parts[1] ?? '');
+    const target = findLatestTurboquantVersionForBackend(versionBackends, effectiveType);
+    if (target === null || target === currentBackendString) {
+        return { update_needed: false, new_version: '0', target_backend: null };
+    }
+    return { update_needed: true, new_version: target.split('/')[0] ?? '', target_backend: target };
+}
+//# sourceMappingURL=turboquant-tiers.js.map

package/dist/backend/select/turboquant-tiers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turboquant-tiers.js","sourceRoot":"","sources":["../../../src/backend/select/turboquant-tiers.ts"],"names":[],"mappings":"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"}

package/dist/backend/types.d.ts

@@ -9,16 +9,7 @@
  * Field names are snake_case where the app serialises them (Rust structs, the cache record) so a
  * value produced here can be handed to the app unchanged.
  */
-import type { DeviceInfo } from '../contracts/index.js';
-/**
- * One backend build. Rust `BackendInfo { version, backend, #[serde(default)] order: u32 }`: `order`
- * is the directory mtime in seconds for a build found on disk and 0 (or absent) for a manifest entry.
- */
-export interface BackendVersion {
-    version: string;
-    backend: string;
-    order?: number;
-}
+import type { BackendVersion, DeviceInfo } from '../contracts/index.js';
 /** `os_type` as the hardware probe reports it (`tauri-plugin-hardware`). */
 export type BackendOsType = 'windows' | 'linux' | 'macos';
 /** Architecture suffix used in backend ids (`win-cpu-x64`, `macos-arm64`). */
@@ -54,37 +45,19 @@ export interface BackendArchiveSource {
     sha256?: string;
     size?: number;
 }
-/**
- * Rust `SystemFeatures` (input of `determine_supported_backends`) and the guest-js
- * `BackendFeatures`. `cuda11` is accepted for wire compatibility but never expands into a backend.
- */
-export interface BackendFeatures {
-    cuda11: boolean;
-    cuda12: boolean;
-    cuda13: boolean;
-    vulkan: boolean;
-    rocm: boolean;
-}
-/** Rust `SupportedFeatures` (output of `get_supported_features`). */
-export interface SupportedFeatures extends BackendFeatures {
-    avx: boolean;
-    avx2: boolean;
-    avx512: boolean;
-}
 /** Lives in `contracts/hardware.ts` now (every host injects it); re-exported so nothing here moves. */
 export type { GpuProbeInfo } from '../contracts/index.js';
+/**
+ * Live in `contracts/backend-advisor.ts` now (the advisor routes carry them to the app, and `client/`
+ * must import them without `node:*`); re-exported so nothing here moves.
+ */
+export type { BackendFeatures, BackendRecommendation, BackendVersion, IdealBackendResult, OptimalBackendCacheBase, OptimalBackendCacheRecord, SupportedFeatures, UpdateCheckResult, } from '../contracts/index.js';
 /** Rust `BestBackendResult`. */
 export interface BestBackendResult {
     backend_string: string;
     version: string;
     backend_type: string;
 }
-/** Rust `UpdateCheckResult`; `target_backend` serialises as `null` when no update is offered. */
-export interface UpdateCheckResult {
-    update_needed: boolean;
-    new_version: string;
-    target_backend: string | null;
-}
 /** Rust `SettingUpdateResult`. */
 export interface SettingUpdateResult {
     backend_type_updated: boolean;
@@ -95,42 +68,6 @@ export interface SettingUpdateResult {
 }
 /** Verdict of the `--list-devices` health probe for one GPU tier (`tierEnumeratesDevices`). */
 export type TierHealth = 'works' | 'unverified' | 'broken';
-/**
- * Outcome of `detectIdealBackendType` (ATO-161): a better GPU backend exists, CPU genuinely is the
- * best this hardware can do, or detection could not complete and the current backend must stay.
- */
-export type IdealBackendResult = {
-    kind: 'gpu';
-    backend: string;
-} | {
-    kind: 'cpu-optimal';
-} | {
-    kind: 'detection-failed';
-};
-interface OptimalBackendCacheBase {
-    schemaVersion: 1;
-    provider: 'llamacpp-upstream' | 'llamacpp';
-    detectedAt: number;
-    currentBackend: string;
-    recommendedCategory: string;
-}
-/** Persisted under `OPTIMAL_BACKEND_CACHE_KEY` (app: `localStorage`; core: `<data>/atomic-core/`). */
-export type OptimalBackendCacheRecord = (OptimalBackendCacheBase & {
-    detectionKind: 'gpu';
-    idealBackendId: string;
-    recommendedBackend?: string;
-}) | (OptimalBackendCacheBase & {
-    detectionKind: 'cpu-optimal';
-});
-/** Payload of `AppEvent.onBetterBackendDetected` and of `llama_cpp_better_backend_recommendation`. */
-export interface BackendRecommendation {
-    currentBackend: string;
-    recommendedBackend: string;
-    recommendedCategory: string;
-    provider: string;
-    version: string;
-    backendId: string;
-}
 /** What a tier probe needs from its caller: the installed builds and a way to run `--list-devices`. */
 export interface TierProbeDeps {
     listInstalled: () => Promise<BackendVersion[]>;

package/dist/cli/commands/backends.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `backends list|recommend|updates` — the advisor's three answers for a llama.cpp provider, so what
+ * the desktop app shows can be seen (and scripted) without it.
+ */
+import type { BackendCatalogResponse, BackendRecommendationResponse, BackendUpdateCheckResponse } from '../../contracts/index.js';
+import type { CliIo } from '../io.js';
+export declare function backendsCommand(argv: string[], io: CliIo): Promise<number>;
+export declare function formatCatalog(catalog: BackendCatalogResponse, current?: string): string;
+export declare function formatRecommendation(result: BackendRecommendationResponse): string;
+export declare function formatUpdates(result: BackendUpdateCheckResponse): string;

package/dist/cli/commands/backends.js

@@ -0,0 +1,142 @@
+/**
+ * `backends list|recommend|updates` — the advisor's three answers for a llama.cpp provider, so what
+ * the desktop app shows can be seen (and scripted) without it.
+ */
+import { parseArgs } from 'node:util';
+import { isLlamacppProviderId } from '../../backend/index.js';
+import { withAttachedOwner } from '../owner.js';
+import { attachOptions } from './hardware.js';
+import { layoutFor } from './shared.js';
+const SUBCOMMANDS = ['list', 'recommend', 'updates'];
+export async function backendsCommand(argv, io) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: {
+            'json': { type: 'boolean' },
+            'provider': { type: 'string' },
+            'current': { type: 'string' },
+            'force': { type: 'boolean' },
+            'mode': { type: 'string' },
+            'app-version': { type: 'string' },
+            'data-folder': { type: 'string' },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+    const sub = positionals[0] ?? 'list';
+    if (!SUBCOMMANDS.includes(sub)) {
+        io.stderr(`Unknown backends subcommand: ${sub} (use ${SUBCOMMANDS.join(', ')})\n`);
+        return 2;
+    }
+    const provider = values.provider ?? 'llamacpp-upstream';
+    if (!isLlamacppProviderId(provider)) {
+        io.stderr(`--provider must be llamacpp-upstream, llamacpp or atomic-prism, not ${provider}\n`);
+        return 2;
+    }
+    const mode = values.mode ?? 'recheck';
+    if (sub === 'recommend' && mode !== 'refresh' && mode !== 'recheck') {
+        io.stderr(`--mode must be refresh or recheck, not ${mode}\n`);
+        return 2;
+    }
+    const common = {
+        ...(values.force ? { force: true } : {}),
+        ...(values['app-version'] ? { app_version: values['app-version'] } : {}),
+    };
+    const layout = layoutFor(values, io);
+    const result = await withAttachedOwner(attachOptions(layout, `backends ${sub}`, io), async ({ client }) => {
+        if (sub === 'list')
+            return client.backendCatalog(provider, {
+                ...common,
+                ...(values.current ? { current_backend: values.current } : {}),
+            });
+        if (sub === 'recommend')
+            return client.recommendBackend(provider, {
+                mode: mode,
+                ...common,
+                ...(values.current ? { current_backend: values.current } : {}),
+            });
+        return client.checkBackendUpdates(provider, {
+            ...common,
+            ...(values.current ? { current: values.current } : {}),
+        });
+    });
+    if (values.json) {
+        io.stdout(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    if (sub === 'list')
+        io.stdout(formatCatalog(result, values.current));
+    else if (sub === 'recommend')
+        io.stdout(formatRecommendation(result));
+    else
+        io.stdout(formatUpdates(result));
+    return 0;
+}
+export function formatCatalog(catalog, current) {
+    const lines = [''];
+    const installed = new Set(catalog.installed.map((entry) => `${entry.version}/${entry.backend}`));
+    if (catalog.available.length === 0) {
+        lines.push(`  No backend of ${catalog.provider} fits this machine (source: ${catalog.source}).`);
+    }
+    else {
+        const width = Math.max(7, ...catalog.available.map((entry) => entry.version.length));
+        lines.push(`  ${'VERSION'.padEnd(width)}  ${'BACKEND'.padEnd(24)}  INSTALLED  MARKS`);
+        for (const entry of catalog.available) {
+            const id = `${entry.version}/${entry.backend}`;
+            const marks = [];
+            if (id === catalog.recommended)
+                marks.push('recommended');
+            if (current && id === current)
+                marks.push('current');
+            lines.push(`  ${entry.version.padEnd(width)}  ${entry.backend.padEnd(24)}  ${(installed.has(id) ? 'yes' : '-').padEnd(9)}  ${marks.join(', ')}`);
+        }
+    }
+    lines.push('');
+    lines.push(`  Supported   ${catalog.supported_backends.join(', ') || 'none'}`);
+    lines.push(`  Recommended ${catalog.recommended ?? 'none'}`);
+    lines.push(`  Source      ${catalog.source} (hardware: ${catalog.hardware_source})`);
+    lines.push('');
+    return `${lines.join('\n')}\n`;
+}
+export function formatRecommendation(result) {
+    const lines = [''];
+    switch (result.outcome) {
+        case 'mac':
+            lines.push('  macOS runs its single Metal build; nothing to recommend.');
+            break;
+        case 'detection_failed':
+            lines.push('  Detection could not complete; keeping the current backend.');
+            break;
+        case 'cpu_optimal':
+            lines.push('  The CPU build is the best this machine can run.');
+            break;
+        case 'already_optimal':
+            lines.push(`  Already on the recommended backend${result.record ? ` (${result.record.currentBackend})` : ''}.`);
+            break;
+        case 'no_catalog_entry':
+            lines.push('  A better backend type exists but no release of it is published; keeping the current one.');
+            break;
+        case 'recommend':
+            lines.push(`  Recommended ${result.recommendation?.recommendedBackend ?? '?'} (${result.recommendation?.recommendedCategory ?? '?'})`);
+            lines.push(`  Current     ${result.recommendation?.currentBackend || 'none'}`);
+            break;
+    }
+    lines.push(`  Detection   ${result.detection ? result.detection.kind : 'skipped'}, ${result.mode}, ${result.elapsed_ms} ms`);
+    lines.push(`  Record      revision ${result.revision}`);
+    lines.push('');
+    return `${lines.join('\n')}\n`;
+}
+export function formatUpdates(result) {
+    const lines = [''];
+    if (result.current_kind === 'missing')
+        lines.push('  No backend is configured for this provider.');
+    else if (!result.update_needed)
+        lines.push(`  Up to date: ${result.current}`);
+    else if (result.same_family)
+        lines.push(`  Update: ${result.current} -> ${result.target_backend ?? '?'} (same family)`);
+    else
+        lines.push(`  Newer build ${result.target_backend ?? '?'} is a different family than ${result.current}; not offered automatically.`);
+    lines.push('');
+    return `${lines.join('\n')}\n`;
+}
+//# sourceMappingURL=backends.js.map

package/dist/cli/commands/backends.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backends.js","sourceRoot":"","sources":["../../../src/cli/commands/backends.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAOrC,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAE/C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEvC,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,CAAU,CAAA;AAE7D,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAc,EAAE,EAAS;IAC7D,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC;QACxC,IAAI,EAAE,IAAI;QACV,OAAO,EAAE;YACP,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;YAC3B,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC9B,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC7B,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;YAC5B,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC1B,aAAa,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YACjC,aAAa,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SAClC;QACD,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE,IAAI;KACb,CAAC,CAAA;IACF,MAAM,GAAG,GAAG,WAAW,CAAC,CAAC,CAAC,IAAI,MAAM,CAAA;IACpC,IAAI,CAAE,WAAiC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACtD,EAAE,CAAC,MAAM,CAAC,gCAAgC,GAAG,SAAS,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAClF,OAAO,CAAC,CAAA;IACV,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,mBAAmB,CAAA;IACvD,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpC,EAAE,CAAC,MAAM,CAAC,uEAAuE,QAAQ,IAAI,CAAC,CAAA;QAC9F,OAAO,CAAC,CAAA;IACV,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,SAAS,CAAA;IACrC,IAAI,GAAG,KAAK,WAAW,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACpE,EAAE,CAAC,MAAM,CAAC,0CAA0C,IAAI,IAAI,CAAC,CAAA;QAC7D,OAAO,CAAC,CAAA;IACV,CAAC;IACD,MAAM,MAAM,GAAG;QACb,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxC,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACzE,CAAA;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IACpC,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;QACxG,IAAI,GAAG,KAAK,MAAM;YAChB,OAAO,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE;gBACrC,GAAG,MAAM;gBACT,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC/D,CAAC,CAAA;QACJ,IAAI,GAAG,KAAK,WAAW;YACrB,OAAO,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE;gBACvC,IAAI,EAAE,IAA6B;gBACnC,GAAG,MAAM;gBACT,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC/D,CAAC,CAAA;QACJ,OAAO,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE;YAC1C,GAAG,MAAM;YACT,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACvD,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IACF,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,EAAE,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAA;QACjD,OAAO,CAAC,CAAA;IACV,CAAC;IACD,IAAI,GAAG,KAAK,MAAM;QAAE,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,MAAgC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAA;SACzF,IAAI,GAAG,KAAK,WAAW;QAAE,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,MAAuC,CAAC,CAAC,CAAA;;QACjG,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,MAAoC,CAAC,CAAC,CAAA;IACnE,OAAO,CAAC,CAAA;AACV,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAA+B,EAAE,OAAgB;IAC7E,MAAM,KAAK,GAAa,CAAC,EAAE,CAAC,CAAA;IAC5B,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;IAChG,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,KAAK,CAAC,IAAI,CACR,mBAAmB,OAAO,CAAC,QAA8B,+BAA+B,OAAO,CAAC,MAAM,IAAI,CAC3G,CAAA;IACH,CAAC;SAAM,CAAC;QACN,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAA;QACpF,KAAK,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,oBAAoB,CAAC,CAAA;QACrF,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACtC,MAAM,EAAE,GAAG,GAAG,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE,CAAA;YAC9C,MAAM,KAAK,GAAa,EAAE,CAAA;YAC1B,IAAI,EAAE,KAAK,OAAO,CAAC,WAAW;gBAAE,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAA;YACzD,IAAI,OAAO,IAAI,EAAE,KAAK,OAAO;gBAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;YACpD,KAAK,CAAC,IAAI,CACR,KAAK,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACrI,CAAA;QACH,CAAC;IACH,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACd,KAAK,CAAC,IAAI,CAAC,iBAAiB,OAAO,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,EAAE,CAAC,CAAA;IAC9E,KAAK,CAAC,IAAI,CAAC,iBAAiB,OAAO,CAAC,WAAW,IAAI,MAAM,EAAE,CAAC,CAAA;IAC5D,KAAK,CAAC,IAAI,CAAC,iBAAiB,OAAO,CAAC,MAAM,eAAe,OAAO,CAAC,eAAe,GAAG,CAAC,CAAA;IACpF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACd,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAA;AAChC,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAAqC;IACxE,MAAM,KAAK,GAAa,CAAC,EAAE,CAAC,CAAA;IAC5B,QAAQ,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,KAAK,KAAK;YACR,KAAK,CAAC,IAAI,CAAC,4DAA4D,CAAC,CAAA;YACxE,MAAK;QACP,KAAK,kBAAkB;YACrB,KAAK,CAAC,IAAI,CAAC,8DAA8D,CAAC,CAAA;YAC1E,MAAK;QACP,KAAK,aAAa;YAChB,KAAK,CAAC,IAAI,CAAC,mDAAmD,CAAC,CAAA;YAC/D,MAAK;QACP,KAAK,iBAAiB;YACpB,KAAK,CAAC,IAAI,CACR,uCAAuC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,CACpG,CAAA;YACD,MAAK;QACP,KAAK,kBAAkB;YACrB,KAAK,CAAC,IAAI,CAAC,4FAA4F,CAAC,CAAA;YACxG,MAAK;QACP,KAAK,WAAW;YACd,KAAK,CAAC,IAAI,CACR,iBAAiB,MAAM,CAAC,cAAc,EAAE,kBAAkB,IAAI,GAAG,KAAK,MAAM,CAAC,cAAc,EAAE,mBAAmB,IAAI,GAAG,GAAG,CAC3H,CAAA;YACD,KAAK,CAAC,IAAI,CAAC,iBAAiB,MAAM,CAAC,cAAc,EAAE,cAAc,IAAI,MAAM,EAAE,CAAC,CAAA;YAC9E,MAAK;IACT,CAAC;IACD,KAAK,CAAC,IAAI,CACR,iBAAiB,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,KAAK,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,UAAU,KAAK,CACjH,CAAA;IACD,KAAK,CAAC,IAAI,CAAC,0BAA0B,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAA;IACvD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACd,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAA;AAChC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAkC;IAC9D,MAAM,KAAK,GAAa,CAAC,EAAE,CAAC,CAAA;IAC5B,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAA;SAC7F,IAAI,CAAC,MAAM,CAAC,aAAa;QAAE,KAAK,CAAC,IAAI,CAAC,iBAAiB,MAAM,CAAC,OAAO,EAAE,CAAC,CAAA;SACxE,IAAI,MAAM,CAAC,WAAW;QACzB,KAAK,CAAC,IAAI,CAAC,aAAa,MAAM,CAAC,OAAO,OAAO,MAAM,CAAC,cAAc,IAAI,GAAG,gBAAgB,CAAC,CAAA;;QAE1F,KAAK,CAAC,IAAI,CACR,iBAAiB,MAAM,CAAC,cAAc,IAAI,GAAG,+BAA+B,MAAM,CAAC,OAAO,8BAA8B,CACzH,CAAA;IACH,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACd,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAA;AAChC,CAAC"}

package/dist/cli/commands/hardware.d.ts

@@ -0,0 +1,13 @@
+/** `hardware info` — the machine as the core sees it, which is what backend selection runs on. */
+import type { HardwareInfoResponse } from '../../contracts/index.js';
+import type { DataLayout } from '../../config/index.js';
+import type { CliIo } from '../io.js';
+export declare function hardwareCommand(argv: string[], io: CliIo): Promise<number>;
+/** The owner to ask: start one when none runs — the answer is the core's own probe. */
+export declare function attachOptions(layout: DataLayout, command: string, io: CliIo): {
+    layout: DataLayout;
+    clientName: string;
+    launch: boolean;
+    log: (message: string) => void;
+};
+export declare function formatHardwareInfo(response: HardwareInfoResponse): string;

package/dist/cli/commands/hardware.js

@@ -0,0 +1,71 @@
+/** `hardware info` — the machine as the core sees it, which is what backend selection runs on. */
+import { parseArgs } from 'node:util';
+import { withAttachedOwner } from '../owner.js';
+import { layoutFor } from './shared.js';
+export async function hardwareCommand(argv, io) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: {
+            'json': { type: 'boolean' },
+            'refresh': { type: 'boolean' },
+            'data-folder': { type: 'string' },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+    const sub = positionals[0] ?? 'info';
+    if (sub !== 'info') {
+        io.stderr(`Unknown hardware subcommand: ${sub}\n`);
+        return 2;
+    }
+    const layout = layoutFor(values, io);
+    const info = await withAttachedOwner(attachOptions(layout, 'hardware info', io), ({ client }) => values.refresh ? client.refreshHardware() : client.hardwareInfo());
+    if (values.json) {
+        io.stdout(`${JSON.stringify(info, null, 2)}\n`);
+        return 0;
+    }
+    io.stdout(formatHardwareInfo(info));
+    return 0;
+}
+/** The owner to ask: start one when none runs — the answer is the core's own probe. */
+export function attachOptions(layout, command, io) {
+    return {
+        layout,
+        clientName: `atomic-chat-core ${command}`,
+        launch: true,
+        log: (message) => io.stderr(`${message}\n`),
+    };
+}
+export function formatHardwareInfo(response) {
+    const { info } = response;
+    const lines = [];
+    lines.push('');
+    lines.push(`  OS        ${info.os_name || info.os_type} (${info.os_type})`);
+    lines.push(`  CPU       ${info.cpu.name}, ${info.cpu.core_count} cores, ${info.cpu.arch}`);
+    const flags = info.cpu.extensions_known
+        ? info.cpu.extensions.filter((flag) => /^avx/.test(flag)).join(', ') || 'no AVX'
+        : 'unknown';
+    lines.push(`  Flags     ${flags}`);
+    lines.push(`  Memory    ${formatMiB(info.total_memory)}`);
+    if (info.gpus.length === 0)
+        lines.push('  GPU       none detected');
+    for (const gpu of info.gpus) {
+        const parts = [gpu.vendor, gpu.name, formatMiB(gpu.total_memory)];
+        if (gpu.driver_version)
+            parts.push(`driver ${gpu.driver_version}`);
+        if (gpu.nvidia_info?.compute_capability)
+            parts.push(`cc ${gpu.nvidia_info.compute_capability}`);
+        if (gpu.vulkan_info)
+            parts.push(`vulkan ${gpu.vulkan_info.device_type}`);
+        lines.push(`  GPU       ${parts.join(', ')}`);
+    }
+    lines.push(`  Source    ${response.source} at ${new Date(response.probed_at).toISOString()}`);
+    for (const warning of response.warnings)
+        lines.push(`  Warning   ${warning}`);
+    lines.push('');
+    return `${lines.join('\n')}\n`;
+}
+function formatMiB(mib) {
+    return mib >= 1024 ? `${(mib / 1024).toFixed(1)} GiB` : `${mib} MiB`;
+}
+//# sourceMappingURL=hardware.js.map

package/dist/cli/commands/hardware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hardware.js","sourceRoot":"","sources":["../../../src/cli/commands/hardware.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/host-step.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `host-step exec <request-file>` — the privileged helper (design D3). The app copies this binary
+ * to a private folder and runs it under `pkexec`; a person without a polkit agent runs the same
+ * command with `sudo`. It reads the request, runs the recipe, writes `<step>.result.json` beside
+ * the request and exits. It never talks to a core.
+ *
+ * On Windows (change `add-tensorrt-llm-windows`, task 2.4) the app runs it through UAC for the one
+ * Windows recipe, `windows.enable-wsl`, and the request folder is trusted by its owner and ACL
+ * (`executor-io-windows.ts`) instead of uid and mode.
+ *
+ * Exit codes:
+ * - 0 — the recipe completed; the result file says `completed`, or `reboot-required` (it succeeded
+ *   and takes effect after Windows restarts).
+ * - 1 — a result file was written and says `failed` (a refused request or a failed step).
+ * - 2 — no result file was written: a usage error, a path not named `<step_id>.request.json`, a
+ *   folder the executor does not trust (not a real directory, writable by others, or not owned by
+ *   the invoking user — or, run as root with neither `PKEXEC_UID` nor `SUDO_UID`, not owned by
+ *   root), or a result write that failed for any other reason (full disk, read-only file system,
+ *   the folder gone). The reason is printed on stderr; the client must treat a missing result file
+ *   as failed.
+ *
+ * Deliberately not in `USAGE`: nobody runs it by choice, and `atc host-step` is hidden the same way.
+ */
+import type { HostStepExecutorDeps } from '../../host/recipes/index.js';
+import type { CliIo } from '../io.js';
+/** The executor's I/O for the platform this binary runs on. */
+export declare function hostStepDepsFor(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): HostStepExecutorDeps;
+export declare function hostStepCommand(argv: string[], io: CliIo, deps?: HostStepExecutorDeps): Promise<number>;

package/dist/cli/commands/host-step.js

@@ -0,0 +1,67 @@
+/**
+ * `host-step exec <request-file>` — the privileged helper (design D3). The app copies this binary
+ * to a private folder and runs it under `pkexec`; a person without a polkit agent runs the same
+ * command with `sudo`. It reads the request, runs the recipe, writes `<step>.result.json` beside
+ * the request and exits. It never talks to a core.
+ *
+ * On Windows (change `add-tensorrt-llm-windows`, task 2.4) the app runs it through UAC for the one
+ * Windows recipe, `windows.enable-wsl`, and the request folder is trusted by its owner and ACL
+ * (`executor-io-windows.ts`) instead of uid and mode.
+ *
+ * Exit codes:
+ * - 0 — the recipe completed; the result file says `completed`, or `reboot-required` (it succeeded
+ *   and takes effect after Windows restarts).
+ * - 1 — a result file was written and says `failed` (a refused request or a failed step).
+ * - 2 — no result file was written: a usage error, a path not named `<step_id>.request.json`, a
+ *   folder the executor does not trust (not a real directory, writable by others, or not owned by
+ *   the invoking user — or, run as root with neither `PKEXEC_UID` nor `SUDO_UID`, not owned by
+ *   root), or a result write that failed for any other reason (full disk, read-only file system,
+ *   the folder gone). The reason is printed on stderr; the client must treat a missing result file
+ *   as failed.
+ *
+ * Deliberately not in `USAGE`: nobody runs it by choice, and `atc host-step` is hidden the same way.
+ */
+import { parseArgs } from 'node:util';
+import { AtomicCoreError } from '../../contracts/index.js';
+import { executeHostStep, nodeHostStepDeps, windowsHostStepDeps } from '../../host/recipes/index.js';
+const HOST_STEP_USAGE = 'Usage: atomic-chat-core host-step exec <step_id.request.json> [--json]\n' +
+    'Exit: 0 completed or reboot-required, 1 failed (see the result file), 2 no result file was written (see stderr).\n';
+/** The executor's I/O for the platform this binary runs on. */
+export function hostStepDepsFor(platform, env) {
+    return platform === 'win32' ? windowsHostStepDeps(env) : nodeHostStepDeps(env);
+}
+export async function hostStepCommand(argv, io, deps = hostStepDepsFor(process.platform, io.env)) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: { json: { type: 'boolean' } },
+        allowPositionals: true,
+        strict: true,
+    });
+    const [sub, requestPath] = positionals;
+    if (sub !== undefined && sub !== 'exec') {
+        io.stderr(`Unknown host-step subcommand: ${sub}\n${HOST_STEP_USAGE}`);
+        return 2;
+    }
+    if (sub === undefined || requestPath === undefined || positionals.length > 2) {
+        io.stderr(HOST_STEP_USAGE);
+        return 2;
+    }
+    let result;
+    try {
+        result = await executeHostStep(requestPath, deps);
+    }
+    catch (error) {
+        // `executeHostStep` throws only when it could not write a result file: a refused path or folder
+        // (`MANAGED_HOST_STEP_INVALID`) or a failed write (ENOSPC, EROFS, ENOENT, ...). Either way the
+        // caller finds no result, and exit 2 is what tells it so.
+        const why = error instanceof AtomicCoreError ? error.message : error.message;
+        io.stderr(`host-step: no result file was written: ${why}\n`);
+        return 2;
+    }
+    if (values.json)
+        io.stdout(`${JSON.stringify(result, null, 2)}\n`);
+    else
+        io.stdout(`${result.step_id || '(unknown step)'}: ${result.outcome} — ${result.log_tail}\n`);
+    return result.outcome === 'failed' ? 1 : 0;
+}
+//# sourceMappingURL=host-step.js.map

package/dist/cli/commands/host-step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-step.js","sourceRoot":"","sources":["../../../src/cli/commands/host-step.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAC1D,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAIpG,MAAM,eAAe,GACnB,0EAA0E;IAC1E,oHAAoH,CAAA;AAEtH,+DAA+D;AAC/D,MAAM,UAAU,eAAe,CAAC,QAAyB,EAAE,GAAsB;IAC/E,OAAO,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAA;AAChF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAc,EACd,EAAS,EACT,OAA6B,eAAe,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,GAAG,CAAC;IAEtE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC;QACxC,IAAI,EAAE,IAAI;QACV,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE;QACtC,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE,IAAI;KACb,CAAC,CAAA;IACF,MAAM,CAAC,GAAG,EAAE,WAAW,CAAC,GAAG,WAAW,CAAA;IACtC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;QACxC,EAAE,CAAC,MAAM,CAAC,iCAAiC,GAAG,KAAK,eAAe,EAAE,CAAC,CAAA;QACrE,OAAO,CAAC,CAAA;IACV,CAAC;IACD,IAAI,GAAG,KAAK,SAAS,IAAI,WAAW,KAAK,SAAS,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7E,EAAE,CAAC,MAAM,CAAC,eAAe,CAAC,CAAA;QAC1B,OAAO,CAAC,CAAA;IACV,CAAC;IACD,IAAI,MAAM,CAAA;IACV,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,eAAe,CAAC,WAAW,EAAE,IAAI,CAAC,CAAA;IACnD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,gGAAgG;QAChG,+FAA+F;QAC/F,0DAA0D;QAC1D,MAAM,GAAG,GAAG,KAAK,YAAY,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAE,KAAe,CAAC,OAAO,CAAA;QACvF,EAAE,CAAC,MAAM,CAAC,0CAA0C,GAAG,IAAI,CAAC,CAAA;QAC5D,OAAO,CAAC,CAAA;IACV,CAAC;IACD,IAAI,MAAM,CAAC,IAAI;QAAE,EAAE,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAA;;QAC7D,EAAE,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,IAAI,gBAAgB,KAAK,MAAM,CAAC,OAAO,MAAM,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAA;IACjG,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAC5C,CAAC"}

package/dist/cli/commands/index.d.ts

@@ -7,8 +7,11 @@
  * migration. The deliberate difference is ownership: `serve` attaches to a core that keeps running
  * after Ctrl+C instead of owning the model itself, which the help text states outright.
  */
-export { apiUrl, baseUrl, formatBytes, layoutFor } from './shared.js';
+export { apiUrl, baseUrl, formatBytes, layoutFor, sessionProcess } from './shared.js';
 export { modelsCommand } from './models.js';
+export { backendsCommand } from './backends.js';
+export { hardwareCommand } from './hardware.js';
+export { hostStepCommand } from './host-step.js';
 export { daemonCommand } from './daemon.js';
 export { DEFAULT_SERVE_CTX_SIZE, DEFAULT_SERVE_GPU_LAYERS, DEFAULT_SERVE_PORT, DEFAULT_SERVE_TIMEOUT_SECS, serveAttachOptions, serveCommand, } from './serve.js';
 export { serverCommand } from './server.js';

package/dist/cli/commands/index.js

@@ -7,8 +7,11 @@
  * migration. The deliberate difference is ownership: `serve` attaches to a core that keeps running
  * after Ctrl+C instead of owning the model itself, which the help text states outright.
  */
-export { apiUrl, baseUrl, formatBytes, layoutFor } from './shared.js';
+export { apiUrl, baseUrl, formatBytes, layoutFor, sessionProcess } from './shared.js';
 export { modelsCommand } from './models.js';
+export { backendsCommand } from './backends.js';
+export { hardwareCommand } from './hardware.js';
+export { hostStepCommand } from './host-step.js';
 export { daemonCommand } from './daemon.js';
 export { DEFAULT_SERVE_CTX_SIZE, DEFAULT_SERVE_GPU_LAYERS, DEFAULT_SERVE_PORT, DEFAULT_SERVE_TIMEOUT_SECS, serveAttachOptions, serveCommand, } from './serve.js';
 export { serverCommand } from './server.js';

package/dist/cli/commands/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/commands/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,kBAAkB,EAClB,0BAA0B,EAC1B,kBAAkB,EAClB,YAAY,GACb,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/commands/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACrF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,kBAAkB,EAClB,0BAA0B,EAC1B,kBAAkB,EAClB,YAAY,GACb,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA"}