Internal desktop bridge

Scope

This is the internal native IPC contract used by the owned RegesARC renderer. It is not an installable browser SDK, an HTTP API or a stable external automation surface. The declarations live in desktop/src/shared/contracts.ts; runtime validation remains in the host.

Every promise returns an explicit result shape:

interface Result<T> {
  ok: boolean;
  value?: T;
  error?: string;
}
interface LoadOptions {
  context: number;
  gpuLayers: number;
  backend: 'cuda' | 'cpu';
  placement?: 'layers' | 'cpu-experts';
  cpuThreads?: number;
  engine?: 'lemonade' | 'strata';
  expertCacheMiB?: number;
}

Check ok before reading value. A failed method is not a successful empty response.

Legacy omissions normalize to Lemonade, ordinary layers placement, zero explicit CPU threads and a 2,048 MiB expert-cache default. The installed CPU-expert placement path has completed functional qualification; it requires CUDA/All layers and role-aware admission. The experimental Strata adapter is a separately qualified installed path for one exact artifact/profile, with fixed CUDA/All policy, 256–8,192 context, 512–4,096 MiB cache in 256 MiB steps and at least two total CPU participants. Strata chat accepts a maximum output limit of 1–4,096 tokens, while Lemonade retains the general 1–32,768 range. The active host adapter revalidates a request independently from the selected UI draft. The host validates and resolves options; TypeScript declarations alone do not admit a request.

Actual methods

Method	Purpose
bootstrap()	Initialize and obtain version/settings/hardware/artifacts/runtime/logs
refresh()	Refresh actual inventory/hardware under the mutation guard
addFolder() / importFile()	Native user selection; inspect local files
saveSettings(settings)	Validate and persist current supported settings
plan(artifactId, options)	Coarse memory admission for an inspected artifact
installBackend(backend)	Explicit Lemonade backend installation; not a Strata installer
load(artifactId, options) / unload()	Owned model lifecycle
chat(request) / cancelChat(requestId)	Correlated generation and cancellation
getConversations() / saveConversation(value)	Local chat persistence
exportDiagnostics()	Native destination selection and diagnostic export
openExternal(url)	HTTPS destination allowlist enforced in main
onEvent(callback)	Runtime, log and chat events; returns an unsubscribe function

Streaming

ChatRequest contains requestId, text messages, temperature and maxTokens. A ChatChunk carries the matching ID and may contain text, reasoning, done, error and reported response stats. A usage-only progress chunk is valid. Terminal errors must be observed rather than treated as a finished answer.

interface ResponseTimings {
  promptMs?: number;
  decodeMs?: number;
  timeToFirstTokenMs?: number;
  tokensPerSecond?: number;
}
interface ResponseStats {
  usage?: Record<string, number>;
  elapsedMs?: number;
  timings?: ResponseTimings;
  finishReason?: string;
}
interface ConversationMessage extends Message {
  stats?: ResponseStats;
}

Progress counts are cumulative engine measurements: prompt_tokens, completion_tokens and cached_tokens when available. timings.tokensPerSecond defines the live observed interval, avoiding an off-by-one first-token assumption in the renderer. Native final decode timings take precedence at completion. Missing fields do not erase preceding measurements; unavailable values are not estimated from displayed text.

Conversation storage retains validated assistant stats, including a canceled reasoning-only response when metrics exist. Runtime request serialization sends only nonempty roles/text, never stats. These additive fields completed actual installed live/persisted-metrics qualification on the exact Strata reference profile. Their presence does not prove that every other runtime reports all measurements.

Runtime snapshots expose phase, actual engine/model identity, ownership, backend readiness and an endpoint where applicable. Strata uses private JSONL pipes rather than a renderer-facing HTTP endpoint. Snapshot.strata.available reports bundle presence, with full integrity checks deferred to load; Snapshot.lemonade independently reports Lemonade backend readiness even while Strata is active. FitPlan.gpuOverheadBytes separates the Strata state/workspace reserve from its weight/cache estimate. Renderer code does not receive a reusable service credential. The bridge does not expose an arbitrary filesystem, shell command or secret-store method.

Contract changes

Additive TypeScript fields are not enough to ship a feature. New options require host validation, runtime mapping, visible effective settings, serialization compatibility and negative tests. Future API/SDK clients need their own versioned public contract; they must not reach into the application’s private preload or copy its runtime key.