usegrunt 0.6.1 → 0.6.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -13,10 +13,17 @@ import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
13
13
  import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
14
14
  import { freeConfig, loopback } from './freellmapi.js';
15
15
  import { proxyApproval } from './approval-proxy.js';
16
+ import { VerificationQueue } from './verification-queue.js';
17
+ import { withTerminal } from './terminal.js';
18
+ import { Nvidia, writeNvidiaGrant } from './nvidia.js';
19
+ import { Zro, writeZroGrant } from './zro.js';
20
+ import { TokenHarbor, writeTokenHarborGrant } from './tokenharbor.js';
21
+ import { DATA_SHARING_POLICIES, dataSharingPolicies, readDataSharingConsent } from './data-sharing.js';
16
22
  const exec = promisify(execFile);
17
23
  export const FREELLMAPI_IMAGE = 'ghcr.io/tashfeenahmed/freellmapi@sha256:845a4b568a20fffd5112e1b9c0258e7782d9eabbba2430612d2f7c811eee267e';
18
- export const PROVIDERS = { groq: 'https://console.groq.com/keys', cerebras: 'https://cloud.cerebras.ai/platform/api-keys', kilo: 'https://app.kilo.ai/profile' };
24
+ export const PROVIDERS = { groq: 'https://console.groq.com/keys', cerebras: 'https://cloud.cerebras.ai/platform/api-keys', kilo: 'https://app.kilo.ai/profile', nvidia: 'https://build.nvidia.com/settings/api-keys', zro: 'https://zro.moonmath.ai/overview', tokenharbor: 'https://tokenharbor.ai/dashboard' };
19
25
  export const KILO_NEMOTRON = 'nvidia/nemotron-3-ultra-550b-a55b:free';
26
+ export { NVIDIA_DEEPSEEK } from './nvidia.js';
20
27
  const savedProviders = ['kilo'];
21
28
  const providerModels = { kilo: [KILO_NEMOTRON, 'kilo-auto/free'] };
22
29
  const sameService = (credential, service) => credential.service?.trim().toLowerCase() === service.trim().toLowerCase();
@@ -69,7 +76,7 @@ export async function setupProviders(squire, router, options) {
69
76
  }
70
77
  const find = async () => (await squire.credentials.list()).find(c => sameService(c, provider) && c.auth_strategy !== 'username_password' && apiKeyField(c, provider));
71
78
  let credential = await find();
72
- if (!credential) {
79
+ if (!credential || options.verifySaved?.includes(provider)) {
73
80
  const result = await squire.runs.start({ service: provider, plan: 'free', project_name: 'grunt', category: 'ai', cost_cents: 0, recurrence: 'none', idempotency_key: `milo-free-${provider}` });
74
81
  if (result.decision === 'reject')
75
82
  throw setupStopped(`Squire refused ${provider} signup; setup stopped`, result.reason);
@@ -108,7 +115,10 @@ export async function setupProviders(squire, router, options) {
108
115
  options.notify(`${provider}: connected through Squire grant`);
109
116
  }
110
117
  // These sources reuse existing vault access only; missing keys never start signup.
111
- for (const provider of savedProviders) {
118
+ const approved = options.dataSharingApproved ?? await readDataSharingConsent(dirname(localAdminPath()), savedProviders);
119
+ for (const provider of options.reuseSaved === false ? [] : savedProviders) {
120
+ if (dataSharingPolicies([provider]).length && !approved.includes(provider))
121
+ continue;
112
122
  if (options.providers?.includes(provider))
113
123
  continue;
114
124
  if (await router.hasKey?.(provider)) {
@@ -139,10 +149,32 @@ export class BrowserSquire {
139
149
  constructor(options = {}) {
140
150
  this.options = options;
141
151
  }
152
+ approveDataSharing(providers) { this.options.dataSharingApproved = [...new Set(providers)]; }
142
153
  client = new Client({ name: 'grunt setup', version: '0.1.0' });
143
154
  sessions = new Map();
155
+ recoveryChoices = new Map();
156
+ pending = new Set();
157
+ closed = false;
158
+ shutdown = new AbortController();
159
+ get signal() { return this.options.signal ? AbortSignal.any([this.options.signal, this.shutdown.signal]) : this.shutdown.signal; }
144
160
  handoffs = [];
145
- async connect() {
161
+ connection;
162
+ metadata;
163
+ grants = new Map();
164
+ verification = new VerificationQueue(items => withTerminal(async () => {
165
+ this.signal.throwIfAborted();
166
+ for (const item of items)
167
+ console.log(`Complete ${item.service} verification in this browser: ${item.url}`);
168
+ const { confirm, isCancel } = await import('@clack/prompts');
169
+ const done = await confirm({ message: `Finished verification for ${items.map(item => item.service).join(', ')}? Resume setup.`, initialValue: true, signal: this.signal });
170
+ if (isCancel(done) || !done)
171
+ throw new Error('Provider verification cancelled');
172
+ this.signal.throwIfAborted();
173
+ }));
174
+ connect() {
175
+ return this.connection ??= this.connectOnce().catch(error => { this.connection = undefined; throw error; });
176
+ }
177
+ async connectOnce() {
146
178
  const bin = join(dirname(fileURLToPath(import.meta.resolve('@trusty-squire/mcp'))), 'bin.js');
147
179
  const env = squireEnvironment();
148
180
  // Squire owns its account binding and vault. grunt never reads its files.
@@ -163,6 +195,7 @@ export class BrowserSquire {
163
195
  const result = await this.call('list_credentials', { fields: 'summary' }, true);
164
196
  if (!Array.isArray(result.credentials))
165
197
  throw new Error('Squire did not return vault metadata');
198
+ this.metadata = Promise.resolve(result.credentials);
166
199
  }
167
200
  catch (error) {
168
201
  await this.client.close().catch(() => { });
@@ -182,7 +215,7 @@ export class BrowserSquire {
182
215
  }
183
216
  }
184
217
  async call(name, args, connectionCheck = false) {
185
- const result = await this.client.callTool({ name, arguments: args }, undefined, { timeout: 60000, ...(this.options.signal ? { signal: this.options.signal } : {}) }).catch(error => {
218
+ const result = await this.client.callTool({ name, arguments: args }, undefined, { timeout: name === 'operate_finish' ? 10000 : 60000, ...(name === 'operate_finish' ? {} : { signal: this.signal }) }).catch(error => {
186
219
  if (connectionCheck)
187
220
  throw error;
188
221
  throw new Error(`Squire ${name} is unavailable; resume setup after reconnecting Squire`);
@@ -206,75 +239,142 @@ export class BrowserSquire {
206
239
  }
207
240
  credentials = {
208
241
  list: async () => {
209
- const result = await this.call('list_credentials', { fields: 'summary' });
210
- if (!Array.isArray(result.credentials))
211
- throw new Error('Squire did not return vault metadata');
212
- return result.credentials;
242
+ return structuredClone(await (this.metadata ??= this.call('list_credentials', { fields: 'summary' }).then(result => {
243
+ if (!Array.isArray(result.credentials))
244
+ throw new Error('Squire did not return vault metadata');
245
+ return result.credentials;
246
+ }).catch(error => { this.metadata = undefined; throw error; })));
213
247
  },
214
248
  grant: async (reference) => {
215
- const result = await this.call('grant_app_access', { reference });
216
- if (typeof result.base_url !== 'string' || typeof result.token !== 'string' || !result.token)
217
- throw new Error('Squire returned no app grant');
218
- const url = new URL(result.base_url);
219
- if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash)
220
- throw new Error('Squire returned an invalid grant endpoint');
221
- return { base_url: result.base_url, token: result.token };
249
+ let grant = this.grants.get(reference);
250
+ if (!grant) {
251
+ grant = this.grant(reference).catch(error => { this.grants.delete(reference); throw error; });
252
+ this.grants.set(reference, grant);
253
+ }
254
+ return grant;
222
255
  }
223
256
  };
257
+ async grant(reference) {
258
+ const result = await this.call('grant_app_access', { reference });
259
+ if (typeof result.base_url !== 'string' || typeof result.token !== 'string' || !result.token)
260
+ throw new Error('Squire returned no app grant');
261
+ const url = new URL(result.base_url);
262
+ if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash)
263
+ throw new Error('Squire returned an invalid grant endpoint');
264
+ return { base_url: result.base_url, token: result.token };
265
+ }
266
+ async finishSession(provider, completed = false) {
267
+ const id = this.sessions.get(provider);
268
+ if (!id)
269
+ return;
270
+ try {
271
+ await this.call('operate_finish', { session_id: id, outcome: completed ? 'result' : 'none',
272
+ ...(completed ? { summary: 'grunt provider key stored in user vault' } : {}) });
273
+ if (this.sessions.get(provider) === id)
274
+ this.sessions.delete(provider);
275
+ this.recoveryChoices.delete(provider);
276
+ }
277
+ catch { /* Preserve the original error; close retries a failed cleanup. */ }
278
+ }
224
279
  async signup(service, url, goal) {
225
280
  const deadline = Date.now() + 600000;
226
- while (Date.now() < deadline) {
227
- this.options.signal?.throwIfAborted();
228
- const result = await this.drive(service, url, goal);
229
- if (result.run.state === 'completed')
230
- return;
231
- if (result.run.state !== 'running')
232
- throw new Error(`${service}: signup could not be completed`);
281
+ try {
282
+ while (Date.now() < deadline) {
283
+ this.signal.throwIfAborted();
284
+ const result = await this.drive(service, url, goal);
285
+ if (result.run.state === 'completed')
286
+ return;
287
+ if (result.run.state !== 'running')
288
+ throw new Error(`${service}: signup could not be completed`);
289
+ }
290
+ throw new Error(`${service}: signup timed out; rerun setup to resume`);
291
+ }
292
+ finally {
293
+ await this.finishSession(service);
233
294
  }
234
- throw new Error(`${service}: signup timed out; rerun setup to resume`);
235
295
  }
236
296
  async drive(provider, url = PROVIDERS[provider], goal) {
237
- const session = this.sessions.get(provider);
238
- const result = await this.call('operate_drive', {
239
- ...(session ? { session_id: session } : { url }),
240
- goal: goal ?? `Use the user's existing ${provider} account or sign up for the free plan. Create one API key for grunt and store it in this user's Squire vault with service ${provider}. Use operate_extract to capture the key directly into the vault; never put its value in your answer.${provider === 'kilo' ? ' Reuse the existing profile API key without resetting it. Capture with api_hosts ["api.kilo.ai", "ai-gateway.kilo.ai"] in that order and auth_shape "bearer"; grunt uses /api/gateway beneath the grant.' : ''} No paid plan, payment method, extra account or account switching. If captcha, passkey or email confirmation needs a human, stop and report the required step so grunt can share this browser. Do not bypass verification. Stop on provider refusal.`,
241
- facts: { plan: 'free', project_name: 'grunt' }, max_seconds: 45, max_steps: 60
242
- });
243
- if (typeof result.session_id === 'string')
244
- this.sessions.set(provider, result.session_id);
245
- const reason = setupReason(result.reason, result.remaining);
246
- const classification = [result.reason, result.remaining].filter(value => typeof value === 'string').join(' ').replace(/[_-]/g, ' ');
247
- const refusal = ['refused', 'rejected', 'denied', 'forbidden'].includes(String(result.status)) || /\b(?:refus(?:al|ed|es|ing)?|denied|prohibit(?:ed|s)?|not allowed|not permitted|forbidden|disallowed)\b/i.test(classification);
248
- if (refusal)
249
- throw setupStopped(`Provider refused ${provider} signup; setup stopped`, reason);
250
- if (result.status === 'complete') {
251
- const id = this.sessions.get(provider);
252
- if (id) {
253
- await this.call('operate_finish', { session_id: id, outcome: 'result', summary: 'grunt provider key stored in user vault' });
254
- this.sessions.delete(provider);
255
- }
256
- return { run: { id: provider, state: 'completed' }, decision: 'silent' };
297
+ if (this.closed)
298
+ throw new Error('Squire setup is closed');
299
+ const pending = this.driveOnce(provider, url, goal);
300
+ this.pending.add(pending);
301
+ try {
302
+ return await pending;
303
+ }
304
+ catch (error) {
305
+ await this.finishSession(provider);
306
+ throw error;
307
+ }
308
+ finally {
309
+ this.pending.delete(pending);
257
310
  }
258
- const humanStep = /\b(?:sms|phone|captcha|passkey|email|e mail|verification|confirm(?:ation)?|human(?: only| input| assistance)?)\b/i.test(`${String(result.field)} ${classification}`);
259
- if (!humanStep && (result.status === 'budget' || result.status === 'evaluate_timeout'))
260
- return { run: { id: provider, state: 'running' }, decision: 'silent' };
261
- if (humanStep && process.env.MILO_SETUP_NO_HUMAN === '1')
262
- throw new Error('Provider signup needs human verification; stopped before handoff');
263
- if (humanStep && this.sessions.has(provider)) {
264
- const url = await this.humanHandoff(this.sessions.get(provider));
265
- console.log(`Complete ${provider} verification in this browser: ${url}`);
266
- if (this.options.background) {
267
- await delay(5000, undefined, this.options.signal ? { signal: this.options.signal } : {});
311
+ }
312
+ async driveOnce(provider, url, goal) {
313
+ const customGoal = goal === undefined ? undefined : `${goal}${this.options.dataSharingApproved?.includes(provider) ? ' The user approved data sharing for this provider during grouped setup consent. You may accept its required free-route data-sharing disclosure to enable free access.' : ' Do not opt in to optional prompt/response retention, staff review or model training; report any required consent for grouped setup approval.'}`;
314
+ const instruction = customGoal ?? `Use the user's existing ${provider} account or sign up for the free plan. Prefer Google OAuth using the user's Squire-connected identity. Reuse an existing key in this user's vault, or create one API key for grunt and store it in this user's Squire vault with service ${provider}. Use operate_extract to capture the key directly into the vault; never put its value in your answer.${provider === 'kilo' ? ' Reuse the existing profile API key without resetting it. Capture with api_hosts ["api.kilo.ai", "ai-gateway.kilo.ai"] in that order and auth_shape "bearer"; grunt uses /api/gateway beneath the grant.' : ''}${provider === 'nvidia' ? ' Complete free NVIDIA Build developer onboarding and enable its free inference endpoint. Capture the API key with api_hosts ["integrate.api.nvidia.com"] and auth_shape "bearer". Never reset or rotate an existing key. The requested free model is deepseek-ai/deepseek-v4.1-flash.' : ''}${provider === 'zro' ? ' Verify that this account is on the Free plan, has no paid subscription, no purchased usage-pack balance and no saved payment method before creating or reusing its key. If any paid balance, plan or payment method exists, stop and report it; do not cancel, downgrade, remove a payment method or create another account. Enable only its daily free DeepSeek V4.1 Flash access. Capture the API key with api_hosts ["zro.moonmath.ai"] and auth_shape "bearer". Store service zro, label grunt. Never reset or rotate an existing key. The requested model is deepseek-v4.1-flash.' : ''}${provider === 'tokenharbor' ? ' Enable the free model deepseek-v4.1-flash:free under the approved data-sharing policy; never select its paid sibling. Capture with api_hosts ["tokenharbor.ai"] and auth_shape "bearer", service tokenharbor, label grunt. Do not create a second key if an existing vaulted key is usable, and never reset or rotate an existing key.' : ''}${this.options.dataSharingApproved?.includes(provider) ? ' The user approved data sharing for this provider during grouped setup consent. You may accept its required free-route prompt/response retention, staff review and provider training disclosure to enable free access.' : ' Do not opt in to optional prompt/response retention, staff review or model training; if free access requires that consent, report it for the grouped setup approval.'} No paid plan, payment method, extra account or account switching. If captcha, passkey or email confirmation needs a human, stop and report the required step so grunt can share this browser. Do not bypass verification. Stop on provider refusal.`;
315
+ let answer;
316
+ while (true) {
317
+ this.signal.throwIfAborted();
318
+ const session = this.sessions.get(provider);
319
+ const result = await this.call('operate_drive', {
320
+ ...(session ? { session_id: session } : { url }), goal: instruction,
321
+ facts: { plan: 'free', project_name: 'grunt' }, max_seconds: 45, max_steps: 60,
322
+ ...(answer ? { answer } : {})
323
+ });
324
+ if (typeof result.session_id === 'string')
325
+ this.sessions.set(provider, result.session_id);
326
+ // The driver's remaining field can repeat our own goal, including refusal
327
+ // and human-verification instructions. That is not evidence from the site.
328
+ const normalize = (value) => value.replace(/\s+/g, ' ').trim().toLowerCase();
329
+ const remaining = typeof result.remaining === 'string' && result.remaining.trim()
330
+ && !normalize(instruction).includes(normalize(result.remaining))
331
+ && !normalize(result.remaining).includes(normalize(instruction)) ? result.remaining : undefined;
332
+ const reason = setupReason(result.reason, remaining);
333
+ const classification = [result.reason, remaining].filter(value => typeof value === 'string').join(' ').replace(/[_-]/g, ' ');
334
+ const refusal = ['refused', 'rejected', 'denied', 'forbidden'].includes(String(result.status)) || /\b(?:refus(?:al|ed|es|ing)?|denied|prohibit(?:ed|s)?|not allowed|not permitted|forbidden|disallowed)\b/i.test(classification);
335
+ if (refusal)
336
+ throw setupStopped(`Provider refused ${provider} signup; setup stopped`, reason);
337
+ if (result.status === 'complete') {
338
+ this.metadata = undefined; // A browser capture may have added a credential.
339
+ await this.finishSession(provider, true);
340
+ return { run: { id: provider, state: 'completed' }, decision: 'silent' };
341
+ }
342
+ const uncertain = result.status === 'low_confidence' || result.status === 'no_progress';
343
+ if (uncertain && this.sessions.has(provider)) {
344
+ const used = this.recoveryChoices.get(provider) ?? new Set();
345
+ this.recoveryChoices.set(provider, used);
346
+ // Only resume choices the browser actually offered. Never guess consent,
347
+ // payment, arbitrary Continue controls, or repeat a dispatched OAuth click.
348
+ const choice = Object.entries(object(result.options)).find(([, label]) => typeof label === 'string'
349
+ && /^(?:reject optional|reject all(?: cookies)?|only necessary(?: cookies)?|continue without accepting|more signup options)$/i.test(label.trim())
350
+ && !used.has(label.trim().toLowerCase()));
351
+ if (choice && used.size < 4) {
352
+ used.add(choice[1].trim().toLowerCase());
353
+ answer = choice[0];
354
+ continue;
355
+ }
356
+ }
357
+ const humanStep = /\b(?:sms|phone|captcha|passkey|email|e mail|verification|confirm(?:ation)?|human(?: only| input| assistance)?)\b/i.test(`${String(result.field)} ${classification}`);
358
+ if (!humanStep && (result.status === 'budget' || result.status === 'evaluate_timeout'))
359
+ return { run: { id: provider, state: 'running' }, decision: 'silent' };
360
+ // A driver that cannot choose the next action still owns a resumable tab.
361
+ // Share that exact browser instead of silently dropping the signup.
362
+ const handoff = humanStep || uncertain || result.status === 'stuck';
363
+ if (handoff && process.env.MILO_SETUP_NO_HUMAN === '1')
364
+ throw new Error('Provider signup needs human verification; stopped before handoff');
365
+ if (handoff && this.sessions.has(provider)) {
366
+ const url = await this.humanHandoff(this.sessions.get(provider));
367
+ if (this.options.background) {
368
+ console.log(`Complete ${provider} verification in this browser: ${url}`);
369
+ await delay(5000, undefined, { signal: this.signal });
370
+ return { run: { id: provider, state: 'running' }, decision: 'silent' };
371
+ }
372
+ await this.verification.wait({ service: provider, url });
268
373
  return { run: { id: provider, state: 'running' }, decision: 'silent' };
269
374
  }
270
- const { confirm, isCancel } = await import('@clack/prompts');
271
- const done = await confirm({ message: 'Verification complete? Resume signup.', initialValue: true });
272
- if (isCancel(done) || !done)
273
- throw new Error('Provider verification cancelled');
274
- return { run: { id: provider, state: 'running' }, decision: 'silent' };
375
+ await this.finishSession(provider);
376
+ return { run: { id: provider, state: 'dropped' }, decision: 'drop', reason: reason || 'Signup could not be completed' };
275
377
  }
276
- this.sessions.delete(provider);
277
- return { run: { id: provider, state: 'dropped' }, decision: 'drop', reason: reason || 'Signup could not be completed' };
278
378
  }
279
379
  async humanHandoff(session) {
280
380
  const share = await this.call('operate_share', { session_id: session });
@@ -288,8 +388,15 @@ export class BrowserSquire {
288
388
  start: async (input) => this.drive(input.service),
289
389
  get: async (id) => { const result = await this.drive(id); return { state: result.run.state, ...(result.approval_url ? { approval_url: result.approval_url } : {}), ...(result.reason ? { reason: result.reason } : {}) }; }
290
390
  };
291
- async close() { for (const handoff of this.handoffs)
292
- handoff.close(); await this.client.close(); }
391
+ async close() {
392
+ this.closed = true;
393
+ this.shutdown.abort();
394
+ await Promise.allSettled([...this.pending]);
395
+ await Promise.allSettled([...this.sessions.keys()].map(provider => this.finishSession(provider)));
396
+ for (const handoff of this.handoffs)
397
+ handoff.close();
398
+ await this.client.close();
399
+ }
293
400
  }
294
401
  const providerPath = (provider) => ({ groq: '/openai/v1', kilo: '/api/gateway' })[provider] ?? '/v1';
295
402
  export class FreeLLMAdmin {
@@ -343,15 +450,18 @@ export class FreeLLMAdmin {
343
450
  }
344
451
  }
345
452
  }
346
- async configureChain(excluded = []) {
453
+ async configureChain(excluded = [], dataSharingApproved) {
454
+ const approved = dataSharingApproved ?? await readDataSharingConsent(dirname(localAdminPath()), DATA_SHARING_POLICIES.map(policy => policy.provider));
347
455
  const chain = await this.call('/fallback', undefined, 'GET');
348
456
  const rows = chain.map(row => {
349
457
  const provider = [...Object.keys(PROVIDERS), ...savedProviders].find(provider => row.keyLabel === `Milo ${provider} (Squire)`);
350
- const fallback = !provider && (row.modelId === 'freebuff' || row.modelId === 'kilo-auto/free');
458
+ const owned = managedSharingProvider(row);
459
+ const fallback = !provider && owned !== undefined;
460
+ const sharingAllowed = !owned || approved.includes(owned);
351
461
  const vetted = !provider || !providerModels[provider] || providerModels[provider].includes(row.modelId);
352
462
  return { modelDbId: row.modelDbId,
353
- enabled: fallback || (provider ? row.platform === 'custom' && vetted && !excluded.includes(provider) : row.enabled === true),
354
- priority: provider === 'kilo' ? (row.modelId === KILO_NEMOTRON ? 999996 : 999997) : row.modelId === 'freebuff' ? 1000000 : row.modelId === 'kilo-auto/free' ? 999999 : row.priority };
463
+ enabled: sharingAllowed && (fallback || (provider ? row.platform === 'custom' && vetted && !excluded.includes(provider) : row.enabled === true)),
464
+ priority: provider === 'kilo' ? (row.modelId === KILO_NEMOTRON ? 999996 : 999997) : owned === 'freebuff' ? 1000000 : owned === 'kilo' ? 999999 : row.priority };
355
465
  });
356
466
  await this.call('/fallback', rows, 'PUT');
357
467
  await this.call('/fallback/routing', { strategy: 'priority' }, 'PUT');
@@ -429,10 +539,10 @@ async function argsWithEnv(args, env) {
429
539
  function localAdminPath() {
430
540
  return join(process.env.MILO_CONFIG_DIR || join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'milo'), 'router-admin.json');
431
541
  }
432
- async function readLocalAdmin() {
542
+ async function readLocalAdmin(path = localAdminPath()) {
433
543
  let handle;
434
544
  try {
435
- handle = await open(localAdminPath(), constants.O_RDONLY | constants.O_NOFOLLOW);
545
+ handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
436
546
  }
437
547
  catch (error) {
438
548
  if (error.code === 'ENOENT')
@@ -470,6 +580,32 @@ async function saveLocalAdmin(admin) {
470
580
  await rm(temporary, { force: true }).catch(() => { });
471
581
  }
472
582
  }
583
+ function managedSharingProvider(row) {
584
+ if (row.platform !== 'custom')
585
+ return;
586
+ if (row.keyLabel === 'Milo kilo (Squire)' || (row.keyLabel === 'Kilo Free' && row.modelId === 'kilo-auto/free'))
587
+ return 'kilo';
588
+ if (row.keyLabel === 'Freebuff' && row.modelId === 'freebuff')
589
+ return 'freebuff';
590
+ return;
591
+ }
592
+ // Reconcile only Grunt-owned sharing rows before a legacy backend request. This
593
+ // never provisions a router, changes custom rows, or enables a disabled row.
594
+ export async function guardRouterSharing(url, directory) {
595
+ const approved = await readDataSharingConsent(directory, ['kilo', 'freebuff']);
596
+ if (approved.includes('kilo') && approved.includes('freebuff'))
597
+ return;
598
+ const admin = await readLocalAdmin(join(directory, 'router-admin.json'));
599
+ if (!admin)
600
+ throw new Error('Local router admin state is required to enforce data-sharing choices; rerun usegrunt setup');
601
+ const router = new FreeLLMAdmin(url);
602
+ await router.login(admin.password);
603
+ const chain = await router.call('/fallback', undefined, 'GET');
604
+ const updates = chain.filter(row => { const provider = managedSharingProvider(row); return provider && !approved.includes(provider) && row.enabled !== false; })
605
+ .map(row => ({ modelDbId: row.modelDbId, enabled: false, priority: row.priority }));
606
+ if (updates.length)
607
+ await router.call('/fallback', updates, 'PUT');
608
+ }
473
609
  // Read the login already created by setup; never provision or change router state.
474
610
  export async function loadRouterKey(url) {
475
611
  const admin = await readLocalAdmin();
@@ -482,11 +618,17 @@ export async function loadRouterKey(url) {
482
618
  throw new Error('Local router returned an invalid API key');
483
619
  return key;
484
620
  }
485
- export async function setup(notify = console.log, providers = ['groq']) {
486
- const squire = new BrowserSquire();
487
- const router = new FreeLLMAdmin();
488
- try {
489
- await squire.connect();
621
+ const routerStarts = new Map();
622
+ // Provider signups overlap, but they must share one local router initialization.
623
+ // Otherwise two fresh jobs can generate different encryption keys for one DB.
624
+ function readyRouter(signal) {
625
+ const key = JSON.stringify([localAdminPath(), process.env.MILO_FREELLMAPI_URL, process.env.MILO_ROUTER_RUNTIME]);
626
+ const existing = routerStarts.get(key);
627
+ if (existing)
628
+ return existing;
629
+ const starting = (async () => {
630
+ const router = new FreeLLMAdmin();
631
+ signal?.throwIfAborted();
490
632
  const saved = await readLocalAdmin();
491
633
  if (!saved && process.env.MILO_ROUTER_RUNTIME !== 'docker') {
492
634
  const database = join(dirname(localAdminPath()), 'freellmapi', 'router.db');
@@ -512,28 +654,123 @@ export async function setup(notify = console.log, providers = ['groq']) {
512
654
  if (!saved)
513
655
  await saveLocalAdmin(admin);
514
656
  const { ensureNativeRouter } = await import('./native-router.js');
515
- await ensureNativeRouter();
657
+ let running = false;
658
+ if (saved) {
659
+ try {
660
+ await router.login(admin.password);
661
+ running = true;
662
+ }
663
+ catch { /* Repair an unavailable backend. */ }
664
+ }
665
+ if (!running)
666
+ await ensureNativeRouter(signal);
516
667
  }
517
668
  let ready = false;
518
669
  for (let attempt = 0; attempt < 60; attempt++) {
670
+ signal?.throwIfAborted();
519
671
  try {
520
672
  await router.login(admin.password);
521
673
  ready = true;
522
674
  break;
523
675
  }
524
676
  catch {
525
- await delay(1000);
677
+ await delay(1000, undefined, signal ? { signal } : {});
526
678
  }
527
679
  }
528
680
  if (!ready)
529
681
  throw new Error('Local FreeLLMAPI did not start; inspect its health before resuming setup');
530
682
  await router.ensureFreeFallbacks();
531
683
  await router.configureChain();
532
- const result = await setupProviders(squire, router, { providers, notify });
684
+ return router;
685
+ })();
686
+ routerStarts.set(key, starting);
687
+ void starting.finally(() => { if (routerStarts.get(key) === starting)
688
+ routerStarts.delete(key); }).catch(() => { });
689
+ return starting;
690
+ }
691
+ export async function setup(notify = console.log, providers = ['groq'], options = {}) {
692
+ const location = options.directory ?? process.env.MILO_CONFIG_DIR ?? join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'milo');
693
+ const approved = [...new Set([...(options.dataSharingApproved ?? []), ...await readDataSharingConsent(location, DATA_SHARING_POLICIES.map(policy => policy.provider))])];
694
+ const unapproved = dataSharingPolicies(providers).filter(policy => !approved.includes(policy.provider));
695
+ if (unapproved.length)
696
+ throw new Error(`${unapproved.map(policy => policy.name).join(', ')} data sharing requires the grouped setup approval`);
697
+ const owned = options.squire ? undefined : new BrowserSquire({ ...(options.signal ? { signal: options.signal } : {}), dataSharingApproved: approved });
698
+ if (options.squire instanceof BrowserSquire)
699
+ options.squire.approveDataSharing(approved);
700
+ const squire = options.squire ?? owned;
701
+ try {
702
+ await owned?.connect();
703
+ options.signal?.throwIfAborted();
704
+ if (providers.includes('zro')) {
705
+ const source = new Zro({ directory: location });
706
+ try {
707
+ const result = await setupProviders(squire, {
708
+ hasKey: async (provider) => provider === 'zro' && await source.available(),
709
+ addGrant: async (provider, grant) => {
710
+ if (provider !== 'zro')
711
+ throw new Error('Unexpected Zro credential');
712
+ await writeZroGrant(grant, location);
713
+ }
714
+ }, { providers: ['zro'], notify, reuseSaved: false, verifySaved: ['zro'] });
715
+ if (result.dropped.length)
716
+ throw new Error('Zro setup incomplete; rerun usegrunt setup');
717
+ }
718
+ finally {
719
+ await source.close();
720
+ }
721
+ providers = providers.filter(provider => provider !== 'zro');
722
+ if (!providers.length)
723
+ return {};
724
+ }
725
+ if (providers.includes('tokenharbor')) {
726
+ const source = new TokenHarbor({ directory: location });
727
+ try {
728
+ const result = await setupProviders(squire, {
729
+ hasKey: async (provider) => provider === 'tokenharbor' && await source.available(),
730
+ addGrant: async (provider, grant) => {
731
+ if (provider !== 'tokenharbor')
732
+ throw new Error('Unexpected Token Harbor credential');
733
+ await writeTokenHarborGrant(grant, location);
734
+ }
735
+ }, { providers: ['tokenharbor'], notify, reuseSaved: false, verifySaved: ['tokenharbor'] });
736
+ if (result.dropped.length)
737
+ throw new Error('Token Harbor setup incomplete; rerun usegrunt setup');
738
+ }
739
+ finally {
740
+ await source.close();
741
+ }
742
+ providers = providers.filter(provider => provider !== 'tokenharbor');
743
+ if (!providers.length)
744
+ return {};
745
+ }
746
+ if (providers.includes('nvidia')) {
747
+ const source = new Nvidia();
748
+ try {
749
+ const result = await setupProviders(squire, {
750
+ hasKey: async (provider) => provider === 'nvidia' && await source.available(),
751
+ addGrant: async (provider, grant) => {
752
+ if (provider !== 'nvidia')
753
+ throw new Error('Unexpected NVIDIA credential');
754
+ await writeNvidiaGrant(grant);
755
+ }
756
+ }, { providers: ['nvidia'], notify, reuseSaved: false });
757
+ if (result.dropped.length)
758
+ throw new Error('NVIDIA setup incomplete; rerun usegrunt setup');
759
+ }
760
+ finally {
761
+ await source.close();
762
+ }
763
+ providers = providers.filter(provider => provider !== 'nvidia');
764
+ if (!providers.length)
765
+ return {};
766
+ }
767
+ const router = await readyRouter(options.signal);
768
+ options.signal?.throwIfAborted();
769
+ const result = await setupProviders(squire, router, { providers, notify, dataSharingApproved: approved });
533
770
  const dropped = new Set(result.dropped);
534
771
  if (dropped.size)
535
772
  throw new Error(`Provider setup incomplete: ${[...dropped].join(', ')}`);
536
- await router.configureChain([...dropped]);
773
+ await router.configureChain([...dropped], approved);
537
774
  return { key: await router.key() };
538
775
  }
539
776
  catch (error) {
@@ -545,6 +782,6 @@ export async function setup(notify = console.log, providers = ['groq']) {
545
782
  throw new Error('FreeLLMAPI installation failed; check Node and npm availability and run npx usegrunt setup again');
546
783
  }
547
784
  finally {
548
- await squire.close();
785
+ await owned?.close();
549
786
  }
550
787
  }
@@ -0,0 +1,8 @@
1
+ // Interactive child processes (for example sudo) and browser confirmations
2
+ // must never read stdin at the same time. Noninteractive jobs stay concurrent.
3
+ let tail = Promise.resolve();
4
+ export function withTerminal(task) {
5
+ const result = tail.then(task);
6
+ tail = result.catch(() => { });
7
+ return result;
8
+ }
@@ -0,0 +1,64 @@
1
+ import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
2
+ import { homedir } from 'node:os';
3
+ import { join } from 'node:path';
4
+ import { randomUUID } from 'node:crypto';
5
+ import { FreeApi, readFreeApiGrant } from './free-api.js';
6
+ import { verifiedDeepSeekFetch } from './deepseek-response.js';
7
+ import { readDataSharingConsent } from './data-sharing.js';
8
+ import { SourceError } from './source.js';
9
+ export const TOKENHARBOR_DEEPSEEK = 'deepseek-v4.1-flash:free';
10
+ const directory = () => process.env.MILO_CONFIG_DIR || join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'milo');
11
+ export async function writeTokenHarborGrant(grant, location = directory()) {
12
+ const url = new URL(grant.base_url);
13
+ if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || typeof grant.token !== 'string' || !grant.token.trim())
14
+ throw new Error('Invalid Token Harbor grant');
15
+ const temporary = join(location, `tokenharbor.${randomUUID()}.tmp`);
16
+ await mkdir(location, { recursive: true, mode: 0o700 });
17
+ try {
18
+ await writeFile(temporary, JSON.stringify({ base_url: grant.base_url.replace(/\/$/, ''), token: grant.token }), { mode: 0o600, flag: 'wx' });
19
+ await rename(temporary, join(location, 'tokenharbor.json'));
20
+ }
21
+ finally {
22
+ await rm(temporary, { force: true });
23
+ }
24
+ }
25
+ export class TokenHarbor {
26
+ options;
27
+ id = 'tokenharbor';
28
+ supportsFunctionTools = true;
29
+ source;
30
+ location;
31
+ constructor(options = {}) {
32
+ this.options = options;
33
+ this.location = options.directory ?? directory();
34
+ this.source = new FreeApi('tokenharbor', { ...options, directory: this.location, fetcher: verifiedDeepSeekFetch(options.fetcher) });
35
+ }
36
+ async approved() { return (await readDataSharingConsent(this.location, ['tokenharbor'])).includes('tokenharbor'); }
37
+ grant() { return this.options.loadGrant?.() ?? readFreeApiGrant('tokenharbor', this.location); }
38
+ async available() {
39
+ if (!await this.approved())
40
+ return false;
41
+ try {
42
+ const grant = await this.grant();
43
+ const response = await (this.options.fetcher ?? fetch)(`${grant.base_url}/api/cli/free-tier`, {
44
+ headers: { Authorization: `Bearer ${grant.token}` }, redirect: 'error', signal: AbortSignal.timeout(5000)
45
+ });
46
+ if (!response.ok) {
47
+ await response.body?.cancel();
48
+ return false;
49
+ }
50
+ const result = await response.json();
51
+ return result.models_enabled === true && result.exhausted !== true;
52
+ }
53
+ catch {
54
+ return false;
55
+ }
56
+ }
57
+ async healthCheck() { return this.available(); }
58
+ async complete(request, signal) {
59
+ if (!await this.approved())
60
+ throw new SourceError('refused', 'Token Harbor data sharing is not approved; rerun usegrunt setup');
61
+ return this.source.complete({ ...request, model: this.id }, signal);
62
+ }
63
+ async close() { await this.source.close(); }
64
+ }
@@ -0,0 +1,31 @@
1
+ // Group handoffs arriving together; only one terminal prompt may own stdin.
2
+ // Other installation/browser jobs keep running while the user verifies.
3
+ export class VerificationQueue {
4
+ confirm;
5
+ pending = [];
6
+ running = false;
7
+ constructor(confirm) {
8
+ this.confirm = confirm;
9
+ }
10
+ wait(item) {
11
+ const result = new Promise((resolve, reject) => this.pending.push({ item, resolve, reject }));
12
+ if (!this.running) {
13
+ this.running = true;
14
+ setImmediate(() => { void this.drain(); });
15
+ }
16
+ return result;
17
+ }
18
+ async drain() {
19
+ while (this.pending.length) {
20
+ const batch = this.pending.splice(0);
21
+ try {
22
+ await this.confirm(batch.map(entry => entry.item));
23
+ batch.forEach(entry => entry.resolve());
24
+ }
25
+ catch (error) {
26
+ [...batch, ...this.pending.splice(0)].forEach(entry => entry.reject(error));
27
+ }
28
+ }
29
+ this.running = false;
30
+ }
31
+ }