Skip to content

Commit ffe31a7

Browse files
authored
Add opt-in desktop model chooser bridge with durable switch claims (#142)
1 parent 644b400 commit ffe31a7

5 files changed

Lines changed: 412 additions & 4 deletions

File tree

‎packages/user-intent-kit/bin/uik-daemon.js‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,15 @@
5757
* writers race and the row flickers, which is how
5858
* the MacBook "disappeared" (2026-08-29).
5959
* POLL_INTERVAL_MS default: 30000
60+
* INTENT_CHOOSER_URL optional local chooser base URL. OFF when unset.
61+
* Publishes its catalog/state each device beat and polls
62+
* owner-filed switch requests every 15s. POST selection
63+
* happens only after a fresh local catalog check.
64+
* INTENT_DEVICE_BRAIN_OF optional agent name for the reload warning.
65+
* INTENT_SWITCH_STATE_FILE optional persistent claim/report file path.
66+
* Defaults under ~/.local/state/user-intent-kit per
67+
* user/device. Preserve it across restarts. Run exactly
68+
* ONE chooser-enabled device publisher per device.
6069
*/
6170

6271
import { hostname } from 'node:os';

‎packages/user-intent-kit/src/adapters/desktop.js‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import { collectHostTelemetry } from '../host-telemetry.js';
99
import { ServedModelProbe } from '../served-model.js';
1010
import { ModelAvailabilityProbe } from '../model-availability.js';
1111
import { StatePublisher } from '../state-publisher.js';
12+
import { ModelSwitcher } from '../model-switcher.js';
1213

1314
/**
1415
* Desktop Adapter - detects active window and context on macOS.
@@ -28,6 +29,7 @@ export class DesktopAdapter {
2829
#availabilityProbe;
2930
#pollIntervalMs;
3031
#publisher;
32+
#switcher;
3133

3234
/**
3335
* @param {import('../client.js').IntentClient} client
@@ -44,9 +46,10 @@ export class DesktopAdapter {
4446
*/
4547
constructor(client, {
4648
pollIntervalMs = 30000, machine, kind, model, modelProbe, availabilityProbe,
47-
hostSources,
49+
hostSources, modelSwitcher, chooserUrl,
4850
} = {}) {
4951
this.#client = client;
52+
this.#switcher = modelSwitcher ?? new ModelSwitcher(client, { chooserUrl });
5053
this.#machine = machine ?? client?.deviceId ?? undefined;
5154
this.#kind = kind;
5255
this.#model = model;
@@ -126,7 +129,8 @@ export class DesktopAdapter {
126129
*/
127130
async publishState() {
128131
const state = this.#detectState();
129-
await this.#publisher.publish({ ...state, ttl_sec: 90 });
132+
const chooser = await this.#switcher.refresh();
133+
await this.#publisher.publish({ ...state, ...chooser, ttl_sec: 90 });
130134
}
131135

132136
/**
@@ -139,10 +143,13 @@ export class DesktopAdapter {
139143
// Started AFTER the first publish and never awaited, so the machine
140144
// appears on the dashboard at once with whatever vitals it has, label or
141145
// no label. The first probe fills the label in for the next beat.
142-
this.#modelProbe?.start();
146+
// Chooser mode has one model authority. Do not run the legacy generation
147+
// probe alongside it: a load-on-demand probe can itself load a model.
148+
if (!this.#switcher.enabled) this.#modelProbe?.start();
143149
// Same contract, slower timer: the scan is disk-bound, so it never runs on
144150
// the heartbeat's path and the first beat goes out without waiting for it.
145-
this.#availabilityProbe?.start();
151+
if (!this.#switcher.enabled) this.#availabilityProbe?.start();
152+
this.#switcher.start();
146153
// this.#client.startHeartbeat() removed: the StatePublisher's own
147154
// refreshMs timer now re-sends the last state as the liveness beat, so a
148155
// second heartbeat mechanism only doubled the writes (c0ed66d, 18 Sep 2026).
@@ -159,6 +166,7 @@ export class DesktopAdapter {
159166
}
160167
this.#modelProbe?.stop();
161168
this.#availabilityProbe?.stop();
169+
this.#switcher?.stop();
162170
}
163171

164172
/**

‎packages/user-intent-kit/src/client.js‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,16 @@ export class IntentClient {
5858
return this.#request('PATCH', `/intent/${this.#userId}/${this.#deviceId}`, fields);
5959
}
6060

61+
async getModelSwitch() {
62+
if (!this.#deviceId) throw new Error('No deviceId configured');
63+
return this.#request('GET', `/intent/${encodeURIComponent(this.#userId)}/${encodeURIComponent(this.#deviceId)}/switch`);
64+
}
65+
66+
async reportModelSwitch(report) {
67+
if (!this.#deviceId) throw new Error('No deviceId configured');
68+
return this.#request('PATCH', `/intent/${encodeURIComponent(this.#userId)}/${encodeURIComponent(this.#deviceId)}/switch`, report);
69+
}
70+
6171
async setDevice(fields) {
6272
if (!this.#deviceId) throw new Error('No deviceId configured');
6373
return this.#request('PUT', `/intent/${this.#userId}/${this.#deviceId}`, fields);
Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
// SPDX-License-Identifier: AGPL-3.0
2+
import { mkdir, readFile, open, rename } from 'node:fs/promises';
3+
import { dirname, join } from 'node:path';
4+
import { homedir } from 'node:os';
5+
6+
export const normalizeModelName = name => typeof name === 'string'
7+
? name.trim().split('/').pop().replace(/\.gguf$/i, '').replace(/-\d{5}-of-\d{5}$/, '') : '';
8+
9+
/** Optional local chooser bridge. Never sends the intent key to the chooser.
10+
* Claims are durable BEFORE dispatch. An uncertain dispatch is reconciled,
11+
* never replayed: exactly-once side effects cannot be promised by HTTP.
12+
*/
13+
export class ModelSwitcher {
14+
#client; #url; #file; #brain; #fetch; #now; #timeout; #busy = false;
15+
#records; #timer; #fields; #warn; #lastWarning = -Infinity;
16+
constructor(client, {
17+
chooserUrl = process.env.INTENT_CHOOSER_URL,
18+
brainOf = process.env.INTENT_DEVICE_BRAIN_OF || '',
19+
stateFile = process.env.INTENT_SWITCH_STATE_FILE || join(homedir(), '.local', 'state', 'user-intent-kit',
20+
`switch-${encodeURIComponent(client.userId)}-${encodeURIComponent(client.deviceId)}.json`),
21+
fetchImpl = fetch, now = Date.now, timeoutMs = 15 * 60 * 1000, warn = console.warn,
22+
} = {}) {
23+
this.#client = client; this.#brain = brainOf; this.#file = stateFile;
24+
this.#fetch = fetchImpl; this.#now = now; this.#timeout = timeoutMs;
25+
this.#warn = warn;
26+
if (chooserUrl) {
27+
const u = new URL(chooserUrl);
28+
if (!['http:', 'https:'].includes(u.protocol) || u.username || u.password || u.search || u.hash)
29+
throw new Error('Invalid INTENT_CHOOSER_URL');
30+
this.#url = u.href.replace(/\/+$/, '');
31+
}
32+
this.#fields = this.#down();
33+
}
34+
get enabled() { return !!this.#url; }
35+
#down() { return { model_catalog: [], model: null, model_state: 'down', brain_of: this.#brain }; }
36+
fields() { return this.enabled ? structuredClone(this.#fields) : {}; }
37+
#warning(reason) {
38+
const now = this.#now();
39+
if (now >= this.#lastWarning && now - this.#lastWarning < 300000) return;
40+
this.#lastWarning = now;
41+
// Fixed diagnostics only: never log URLs, keys, response bodies or model paths.
42+
this.#warn(`uik model switcher: ${reason}`);
43+
}
44+
async #registry() {
45+
try { return await this.#readRegistry(); }
46+
catch (error) { this.#warning('local chooser unavailable or invalid; no new switch dispatched'); throw error; }
47+
}
48+
async #readRegistry() {
49+
const response = await this.#fetch(`${this.#url}/api/models`, { signal: AbortSignal.timeout(10000) });
50+
if (!response.ok) throw new Error('Chooser unavailable');
51+
const r = await response.json();
52+
if (!Array.isArray(r.models) || !['ready', 'loading', 'down'].includes(r.state))
53+
throw new Error('Invalid chooser registry');
54+
this.#fields = {
55+
model_catalog: r.models.filter(m => m && typeof m.name === 'string' && m.name.trim()).map(m => ({
56+
name: m.name, size_gb: Number.isFinite(m.size_gb) ? m.size_gb : null,
57+
params_label: typeof m.params_label === 'string' ? m.params_label : null, fits: m.fits === true,
58+
})),
59+
model: typeof r.running === 'string' ? r.running : null,
60+
model_state: r.state, brain_of: this.#brain,
61+
};
62+
return r;
63+
}
64+
async refresh() {
65+
if (!this.enabled) return {};
66+
try { await this.#registry(); } catch { this.#fields = this.#down(); }
67+
return this.fields();
68+
}
69+
async #load() {
70+
if (this.#records) return;
71+
try {
72+
const data = JSON.parse(await readFile(this.#file, 'utf8'));
73+
if (data.version !== 1 || !data.records || typeof data.records !== 'object' || Array.isArray(data.records))
74+
throw new Error('Invalid switch state');
75+
const records = new Map(Object.entries(data.records));
76+
for (const record of records.values()) {
77+
if (!record || typeof record.model !== 'string' || !Number.isFinite(record.started) ||
78+
!['claimed', 'dispatched', 'done', 'failed', 'expired'].includes(record.status))
79+
throw new Error('Invalid switch state record');
80+
}
81+
this.#records = records;
82+
} catch (error) {
83+
if (error.code !== 'ENOENT') {
84+
this.#warning('state file unreadable or corrupt; switching paused (preserve the file for inspection)');
85+
throw error; // corrupt/unreadable state fails closed
86+
}
87+
this.#records = new Map();
88+
}
89+
}
90+
async #save(id, record) {
91+
// Do not update the in-memory claim until persistence succeeds.
92+
const next = new Map(this.#records); next.set(id, record);
93+
await mkdir(dirname(this.#file), { recursive: true, mode: 0o700 });
94+
const tmp = `${this.#file}.${process.pid}.tmp`;
95+
const file = await open(tmp, 'w', 0o600);
96+
try {
97+
await file.writeFile(JSON.stringify({ version: 1, records: Object.fromEntries(next) }));
98+
await file.sync();
99+
} finally { await file.close(); }
100+
await rename(tmp, this.#file);
101+
const directory = await open(dirname(this.#file), 'r');
102+
try { await directory.sync(); } finally { await directory.close(); }
103+
this.#records = next;
104+
}
105+
async #finish(id, record, status, detail) {
106+
const terminal = { ...record, status, detail };
107+
await this.#save(id, terminal); // retain report even if PATCH is unavailable
108+
await this.#client.reportModelSwitch({ id, status, ...(detail === undefined ? {} : { detail }) });
109+
}
110+
async poll() {
111+
if (!this.enabled || this.#busy) return;
112+
this.#busy = true;
113+
try {
114+
await this.#load();
115+
const { request: req } = await this.#client.getModelSwitch();
116+
if (!req || typeof req.id !== 'string' || !req.id || typeof req.model !== 'string') return;
117+
let record = this.#records.get(req.id);
118+
if (['done', 'failed'].includes(req.status) || (req.status === 'expired' && record?.status === 'expired')) return;
119+
if (record && ['done', 'failed', 'expired'].includes(record.status)) {
120+
await this.#client.reportModelSwitch({ id: req.id, status: record.status, detail: record.detail });
121+
return;
122+
}
123+
if (!record) {
124+
if (!['pending', 'expired'].includes(req.status)) return; // never adopt an unknown running command
125+
const filed = Date.parse(req.requested_at);
126+
record = { model: req.model, started: this.#now(), status: 'claimed' };
127+
if (req.status === 'expired' || !Number.isFinite(filed) || this.#now() - filed > 600000 || filed > this.#now() + 60000)
128+
return await this.#finish(req.id, record, 'expired', 'Request expired');
129+
const registry = await this.#registry(); // current LOCAL catalog, not the server's list
130+
const matches = registry.models.filter(m => normalizeModelName(m?.name) === normalizeModelName(req.model));
131+
const pick = matches.length === 1 ? matches[0] : null;
132+
if (!pick || pick.fits !== true)
133+
return await this.#finish(req.id, record, 'failed', 'Model is not in the local fitting catalog');
134+
if (registry.state === 'ready' && normalizeModelName(registry.running) === normalizeModelName(pick.name))
135+
return await this.#finish(req.id, record, 'done', 'already running');
136+
await this.#save(req.id, record);
137+
// If this PATCH fails/has an uncertain result, no local POST is made.
138+
await this.#client.reportModelSwitch({ id: req.id, status: 'running' });
139+
await this.#save(req.id, { ...record, status: 'dispatched' });
140+
let response;
141+
try {
142+
response = await this.#fetch(`${this.#url}/api/model`, {
143+
method: 'POST', headers: { 'Content-Type': 'application/json' },
144+
body: JSON.stringify({ name: pick.name }), signal: AbortSignal.timeout(70000),
145+
});
146+
} catch {
147+
this.#warning('chooser dispatch response uncertain; reconciling without replay');
148+
return; // reconcile later; NEVER retry an uncertain POST
149+
}
150+
const body = await response.text();
151+
if (!response.ok) return await this.#finish(req.id, record, 'failed', body);
152+
let result;
153+
try { result = JSON.parse(body); } catch { return; }
154+
if (result.ok !== true) return await this.#finish(req.id, record, 'failed', body);
155+
return; // readiness checked on the independent next 15s poll
156+
}
157+
if (req.status === 'pending')
158+
return await this.#finish(req.id, record, 'failed', 'Interrupted before dispatch; not replayed');
159+
if (req.status !== 'running') return;
160+
let registry;
161+
try { registry = await this.#registry(); } catch { /* transient outage until deadline */ }
162+
if (registry?.state === 'ready' && normalizeModelName(registry.running) === normalizeModelName(record.model))
163+
return await this.#finish(req.id, record, 'done');
164+
if (this.#now() - record.started >= this.#timeout)
165+
await this.#finish(req.id, record, 'failed', 'Timed out waiting for the requested model to be ready; not replayed');
166+
} catch (error) {
167+
this.#warning('poll/report or state persistence failed; switching fails closed without dispatch replay');
168+
throw error;
169+
} finally { this.#busy = false; }
170+
}
171+
start() {
172+
this.stop();
173+
if (!this.enabled) return;
174+
this.poll().catch(() => {});
175+
this.#timer = setInterval(() => this.poll().catch(() => {}), 15000);
176+
this.#timer.unref?.();
177+
}
178+
stop() { if (this.#timer) clearInterval(this.#timer); this.#timer = null; }
179+
}

0 commit comments

Comments
 (0)