usegrunt 0.6.6 → 0.6.7

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.
package/README.md CHANGED
@@ -14,12 +14,18 @@ npx usegrunt
14
14
 
15
15
  usegrunt installs grunt on this machine. It pools free AI quota and serves one local agent.
16
16
 
17
- Restarts reuse saved connections. Background verification preserves them on
17
+ Use Node 22 or 24 LTS on Linux with systemd or macOS with launchd. Setup needs npm and tar; browser sign-in also needs a working browser/display path, especially on a headless server. Mistral Vibe needs `uv` or Python 3.12 or later.
18
+
19
+ Daemon restarts reuse saved connections. Background verification preserves them on
18
20
  temporary failures and asks for foreground setup when human verification is needed.
19
21
 
20
22
  https://grunt.run. `milo` and `milo-local` remain aliases.
21
23
 
22
- The 0.6.6 pool has eleven sources: OpenCode, Kilo, Zro, Token Harbor, Runcrate, Mistral Vibe Free, LiveKit, Pollinations, BeatAPI, Clixad and Perch. Setup connects Trusty Squire once, connects up to six services at once with up to three browser operations, tests each, then connects your coding tools. Provider-specific human verification is grouped or queued when needed. Pi is optional.
24
+ The curated pool has eleven sources: OpenCode, Kilo, Zro, Token Harbor, Runcrate, Mistral Vibe Free, LiveKit, Pollinations, BeatAPI, Clixad and Perch. Pi is optional.
25
+
26
+ In 0.6.7, setup starts the persistent daemon before provider jobs and checks each provider as it finishes. The first verified reply makes grunt ready; setup then applies your coding-tool choices while the remaining jobs continue. Eligible anonymous Kilo and OpenCode routes can work while account-dependent providers wait for Squire sign-in. Up to six provider jobs, three browser operations and three reply checks can run concurrently; readiness does not wait for the whole pool.
27
+
28
+ The original `npx usegrunt` terminal stays open as the approval console until the remaining jobs finish. Use a connected coding tool in another terminal while it works. Closing the console pauses unfinished signups; verified daemon routes keep running, and rerunning setup resumes the rest. Partial provider failures are reported without failing an installation that has at least one verified route. Perch remains in the default pool, but its human verification does not have to finish before another route becomes usable. Setup duration depends on downloads, prerequisites and verification; no cold-start time is promised.
23
29
 
24
30
  [Reference](https://github.com/bananaman614305/milo/blob/main/docs/reference.md) · [Vision](https://github.com/bananaman614305/milo/blob/main/VISION.md) · [Changelog](https://github.com/bananaman614305/milo/blob/main/CHANGELOG.md) · [Project instructions](https://github.com/bananaman614305/milo/blob/main/CLAUDE.md).
25
31
 
@@ -27,7 +33,7 @@ In 0.6.6, one grouped data-sharing approval covers nine active providers. Setup
27
33
 
28
34
  LiveKit adds DeepSeek V4.1 Flash through its free Build plan, using one free project and the official CLI's browser login. The documented included inference allowance is $2.50 per calendar month with a hard stop and no card. Keep the account on Build. LiveKit documents [zero data retention and no training for inference](https://docs.livekit.io/agents/models/inference/), so it needs no sharing approval. The route passed short-prompt, tool-call and 210,077-token context checks through Grunt.
29
35
 
30
- The four additions are BeatAPI, Pollinations, Clixad and Perch. BeatAPI's ongoing free DeepSeek route permits one successful request per minute and leaves its separate $2 welcome credit untouched. Pollinations' fixed community GLM route needs a numeric zero-budget, Quest-only key and a positive unused Quest balance; the zero-priced route does not spend its one-time first-key reward. Clixad uses its native free GLM route with a zero wallet balance. Perch uses active Starter access with 20,000 Perch Tokens per month, the optional Data Program off, and both memory switches off. Native CLI output limits are local checks and cannot hard-cap upstream generation; keep Clixad's wallet at zero and Perch on Starter. See the reference for model-attestation and billing limits.
36
+ The four additions in 0.6.6 are BeatAPI, Pollinations, Clixad and Perch. BeatAPI's ongoing free DeepSeek route permits one successful request per minute and leaves its separate $2 welcome credit untouched. Pollinations' fixed community GLM route needs a numeric zero-budget, Quest-only key and a positive unused Quest balance; the zero-priced route does not spend its one-time first-key reward. Clixad uses its native free GLM route with a zero wallet balance. Perch uses active Starter access with 20,000 Perch Tokens per month, the optional Data Program off, and both memory switches off. Native CLI output limits are local checks and cannot hard-cap upstream generation; keep Clixad's wallet at zero and Perch on Starter. See the reference for model-attestation and billing limits.
31
37
 
32
38
  Within OpenCode, new conversations rotate across DeepSeek V4.1 Flash Free,
33
39
  GLM 5.3 Flash Free and Big Pickle. Follow-ups keep their model, and quota errors
@@ -67,9 +67,12 @@ export async function verifyOpenCode(source = new OpenCode(), signal = AbortSign
67
67
  export async function setupFallbacks(options) {
68
68
  const squire = options.squire ?? new BrowserSquire({ dataSharingApproved: options.dataSharingApproved ?? [] });
69
69
  const owned = squire instanceof BrowserSquire && !options.squire;
70
- const requested = options.adapters ?? ['opencode'];
70
+ const requested = [...new Set(options.adapters ?? ['opencode'])];
71
+ // A registry may list account-based providers first. Keep their shared
72
+ // browser login from occupying every worker before anonymous routes start.
73
+ const anonymous = ['kilo', 'opencode'];
74
+ const execution = [...anonymous.filter(id => requested.includes(id)), ...requested.filter(id => !anonymous.includes(id))];
71
75
  const unavailable = requested.filter(id => disabledAdapters.has(id));
72
- const adapters = requested.filter(id => !disabledAdapters.has(id));
73
76
  for (const id of unavailable)
74
77
  options.notify(`${id}: routing is disabled; other free services continue`);
75
78
  const approved = [...new Set([...(options.dataSharingApproved ?? []), ...await readDataSharingConsent(options.directory, DATA_SHARING_POLICIES.map(policy => policy.provider))])];
@@ -98,6 +101,16 @@ export async function setupFallbacks(options) {
98
101
  await options.run('npm', ['install', '--global', pkg]);
99
102
  }
100
103
  };
104
+ const settled = new Set(), callbacks = [], callbackFailures = [];
105
+ const onSettled = (id, available) => {
106
+ if (!options.onSettled || settled.has(id))
107
+ return;
108
+ settled.add(id);
109
+ // Observers may verify the daemon or configure coding tools. Start that
110
+ // work immediately without holding a provider worker or rejecting early.
111
+ callbacks.push(Promise.resolve().then(() => options.onSettled(id, available && !options.signal?.aborted))
112
+ .catch(error => { callbackFailures.push(error); }));
113
+ };
101
114
  options.notify('Free routes run their own tools with your filesystem permissions in the working directory. Free model providers may retain prompts.');
102
115
  try {
103
116
  const tasks = {
@@ -335,18 +348,44 @@ export async function setupFallbacks(options) {
335
348
  }
336
349
  }
337
350
  };
338
- await parallelMap(adapters, async (id) => {
339
- if (requiresDataSharing(id) && !approved.includes(id)) {
340
- unavailable.push(id);
341
- options.notify(`${id}: skipped until the grouped data-sharing approval is granted`);
342
- return;
343
- }
344
- const task = tasks[id];
345
- if (!task)
346
- throw new Error('Unsupported vetted adapter');
347
- await task();
348
- }, SETUP_CONCURRENCY, options.signal);
351
+ let failure;
352
+ try {
353
+ await parallelMap(execution, async (id) => {
354
+ let available = false;
355
+ try {
356
+ if (disabledAdapters.has(id))
357
+ return;
358
+ if (requiresDataSharing(id) && !approved.includes(id)) {
359
+ unavailable.push(id);
360
+ options.notify(`${id}: skipped until the grouped data-sharing approval is granted`);
361
+ return;
362
+ }
363
+ const task = tasks[id];
364
+ if (!task)
365
+ throw new Error('Unsupported vetted adapter');
366
+ await task();
367
+ available = !unavailable.includes(id);
368
+ }
369
+ finally {
370
+ onSettled(id, available);
371
+ }
372
+ }, SETUP_CONCURRENCY, options.signal);
373
+ }
374
+ catch (error) {
375
+ failure = { error };
376
+ }
377
+ finally {
378
+ // Cancellation can leave queued providers unstarted. Settle those as
379
+ // unavailable and keep the shared client alive until observers finish.
380
+ for (const id of requested)
381
+ onSettled(id, false);
382
+ await Promise.all(callbacks);
383
+ }
384
+ if (failure)
385
+ throw failure.error;
349
386
  options.signal?.throwIfAborted();
387
+ if (callbackFailures.length)
388
+ throw callbackFailures[0];
350
389
  return { unavailable: requested.filter(id => unavailable.includes(id)) };
351
390
  }
352
391
  finally {
@@ -2,7 +2,7 @@
2
2
  import { disabledAdapters, knownAdapters } from '../registry.js';
3
3
  import { realpathSync } from 'node:fs';
4
4
  import { pathToFileURL } from 'node:url';
5
- import { basename } from 'node:path';
5
+ import { basename, join } from 'node:path';
6
6
  import { serve } from '@hono/node-server';
7
7
  import { createLocalApp } from './api.js';
8
8
  import { positive } from './freebuff.js';
@@ -31,6 +31,7 @@ import { RegistrySync } from './registry.js';
31
31
  import { configDir, command } from './wizard.js';
32
32
  import { setupFallbacks } from './fallback-setup.js';
33
33
  import { BrowserSquire } from './setup.js';
34
+ import { readSetupSession } from './setup-session.js';
34
35
  export const HOST = '127.0.0.1';
35
36
  export function configure(env = process.env, registry = () => bundledRegistry) {
36
37
  const url = env.MILO_FREELLMAPI_URL ?? 'http://127.0.0.1:3001/v1';
@@ -55,7 +56,7 @@ export function configure(env = process.env, registry = () => bundledRegistry) {
55
56
  // default while retaining explicit environment and custom-model overrides.
56
57
  return adapter?.models ?? (adapter?.model && adapter.model !== 'big-pickle' ? [adapter.model] : DEFAULT_OPENCODE_MODELS);
57
58
  };
58
- const registered = [dots, new Codex(env.MILO_CODEX_MODEL ? { model: env.MILO_CODEX_MODEL } : {}), new ManagedRouter(new FreeLLMAPI(connection), url, configDir(env)), new Kilo({ directory: configDir(env) }), new Nvidia({ directory: configDir(env) }), new Zro({ directory: configDir(env) }), new TokenHarbor({ directory: configDir(env) }), new Runcrate({ directory: configDir(env) }), new MistralVibe({ directory: configDir(env) }), new LiveKit({ directory: configDir(env) }), new Pollinations({ directory: configDir(env) }), new BeatAPI({ directory: configDir(env) }), new Clixad({ directory: configDir(env) }), new Perch({ directory: configDir(env) }), new OpenCode({ models: opencodeModels, ...(env.MILO_OPENCODE_URL ? { url: env.MILO_OPENCODE_URL } : {}) })];
59
+ const registered = [dots, new Codex(env.MILO_CODEX_MODEL ? { model: env.MILO_CODEX_MODEL } : {}), new ManagedRouter(new FreeLLMAPI(connection), url, configDir(env)), new Kilo({ directory: configDir(env) }), new Nvidia({ directory: configDir(env) }), new Zro({ directory: configDir(env) }), new TokenHarbor({ directory: configDir(env) }), new Runcrate({ directory: configDir(env) }), new MistralVibe({ directory: configDir(env) }), new LiveKit({ directory: configDir(env) }), new Pollinations({ directory: configDir(env) }), new BeatAPI({ directory: configDir(env) }), new Clixad({ directory: configDir(env) }), new Perch({ directory: configDir(env) }), new OpenCode({ models: opencodeModels, configFile: join(configDir(env), 'opencode-free.json'), ...(env.MILO_OPENCODE_URL ? { url: env.MILO_OPENCODE_URL } : {}) })];
59
60
  const ids = (env.MILO_SOURCES?.split(',').map(id => id.trim()) ?? registry().adapters.filter(adapter => knownAdapters.has(adapter.id)).map(adapter => adapter.id)).filter(id => id && !disabledAdapters.has(id));
60
61
  const routing = ids.every(id => knownAdapters.has(id)) ? { registry } : undefined;
61
62
  return new Sources(ids.map(id => {
@@ -71,16 +72,51 @@ export function start(env = process.env) {
71
72
  const sources = configure(env, () => registry);
72
73
  const directory = configDir(env);
73
74
  let squire;
75
+ const backgroundPreparing = new Set();
76
+ const reconcile = () => {
77
+ sources.preparing.clear();
78
+ for (const id of backgroundPreparing)
79
+ sources.preparing.add(id);
80
+ for (const id of sources.pending)
81
+ sources.preparing.add(id);
82
+ };
83
+ // Serialize snapshots so an older filesystem read cannot overwrite a newer
84
+ // provider release while requests and registry checks run concurrently.
85
+ let sessionRead = Promise.resolve();
86
+ const refreshSession = () => {
87
+ const result = sessionRead.then(async () => {
88
+ const session = await readSetupSession(directory);
89
+ sources.pending.clear();
90
+ for (const id of session?.pending ?? [])
91
+ if (sources.sources.some(source => source.id === id))
92
+ sources.pending.add(id);
93
+ sources.verifying.clear();
94
+ for (const id of session?.verifying ?? [])
95
+ if (sources.pending.has(id))
96
+ sources.verifying.add(id);
97
+ reconcile();
98
+ return session;
99
+ });
100
+ sessionRead = result.catch(() => { });
101
+ return result;
102
+ };
74
103
  const sync = new RegistrySync({ directory, ...(env.GRUNT_REGISTRY_URL ? { url: env.GRUNT_REGISTRY_URL } : {}),
75
104
  afterEnsure: async () => { await squire?.close(); squire = undefined; },
76
105
  changed: current => { registry = current; }, notify: console.error,
77
106
  ensure: async (adapter, signal) => {
78
107
  if (!sources.sources.some(source => source.id === adapter.id))
79
108
  return;
109
+ const session = await refreshSession();
110
+ if (session?.owned.has(adapter.id)) {
111
+ backgroundPreparing.delete(adapter.id);
112
+ reconcile();
113
+ return;
114
+ }
80
115
  const approved = await readDataSharingConsent(directory, [adapter.id]);
81
116
  if (requiresDataSharing(adapter.id) && !approved.includes(adapter.id))
82
117
  return;
83
- sources.preparing.add(adapter.id);
118
+ backgroundPreparing.add(adapter.id);
119
+ reconcile();
84
120
  const client = squire ??= new BrowserSquire({ background: true, signal, dataSharingApproved: approved });
85
121
  client.approveDataSharing([...new Set([...(await readDataSharingConsent(directory, [...knownAdapters])), ...approved])]);
86
122
  try {
@@ -91,23 +127,28 @@ export function start(env = process.env) {
91
127
  sources.healthy(adapter.id);
92
128
  }
93
129
  finally {
94
- sources.preparing.delete(adapter.id);
130
+ backgroundPreparing.delete(adapter.id);
131
+ reconcile();
95
132
  }
96
133
  }
97
134
  });
98
135
  // Load the private cache before accepting tasks, without waiting for the network.
99
136
  // Mark adapters as preparing until their first background setup finishes.
100
- const ready = sync.load().then(() => { for (const adapter of sync.enabled)
101
- if (sources.sources.some(source => source.id === adapter.id))
102
- sources.preparing.add(adapter.id); });
103
- void ready.then(() => sync.start()).catch(() => console.error('Registry sync could not start; using the bundled list')).finally(() => sources.preparing.clear());
137
+ const ready = sync.load().then(async () => {
138
+ const session = await refreshSession();
139
+ for (const adapter of sync.enabled)
140
+ if (!session?.owned.has(adapter.id) && sources.sources.some(source => source.id === adapter.id))
141
+ backgroundPreparing.add(adapter.id);
142
+ reconcile();
143
+ });
144
+ void ready.then(() => sync.start()).catch(() => console.error('Registry sync could not start; using the bundled list')).finally(() => { backgroundPreparing.clear(); reconcile(); });
104
145
  // Warm the saved login without delaying the server; failed loads retry lazily.
105
- void sources.sources.find(source => ['freellmapi', 'kilo'].includes(source.id))?.available();
146
+ void ready.then(() => sources.sources.find(source => !sources.pending.has(source.id) && ['freellmapi', 'kilo'].includes(source.id))?.available()).catch(() => { });
106
147
  const port = positive(env.MILO_PORT, 8788);
107
148
  if (port > 65535)
108
149
  throw new Error('MILO_PORT must be at most 65535');
109
150
  const app = createLocalApp(sources, { port, dotsEnv: env, log: cwd => console.error(`grunt working directory: ${cwd}`) });
110
- const server = serve({ fetch: async (request) => { await ready; return app.fetch(request); }, hostname: HOST, port }, () => console.error(`grunt model API: http://${HOST}:${port}/v1`));
151
+ const server = serve({ fetch: async (request) => { await ready; await refreshSession(); return app.fetch(request); }, hostname: HOST, port }, () => console.error(`grunt model API: http://${HOST}:${port}/v1`));
111
152
  let closing = false;
112
153
  const close = async () => { if (closing)
113
154
  return; closing = true; await sync.close(); await sources.close(); server.close(); };
@@ -1,4 +1,4 @@
1
- import { guardRouterSharing } from './setup.js';
1
+ import { guardRouterSharing, RouterSetupPending } from './setup.js';
2
2
  import { SourceError } from './source.js';
3
3
  // The legacy backend can contain Grunt-created sharing providers alongside the
4
4
  // user's custom rows. Enforce current consent without disabling custom sources.
@@ -22,7 +22,9 @@ export class ManagedRouter {
22
22
  try {
23
23
  await guardRouterSharing(this.url, this.directory);
24
24
  }
25
- catch {
25
+ catch (error) {
26
+ if (error instanceof RouterSetupPending)
27
+ throw new SourceError('not_installed', 'A managed provider is still being verified; other ready sources remain available');
26
28
  throw new SourceError('refused', 'Cannot enforce saved router data-sharing choices; rerun usegrunt setup');
27
29
  }
28
30
  signal.throwIfAborted();
@@ -1,7 +1,7 @@
1
1
  import { spawn } from 'node:child_process';
2
2
  import { createHash } from 'node:crypto';
3
3
  import { tmpdir } from 'node:os';
4
- import { realpath } from 'node:fs/promises';
4
+ import { lstat, realpath } from 'node:fs/promises';
5
5
  import { userTurns } from './harness.js';
6
6
  import { executable } from './multiplexer.js';
7
7
  import { loopback } from './freellmapi.js';
@@ -53,31 +53,51 @@ export class OpenCode {
53
53
  return this.options.url.replace(/\/$/, '');
54
54
  if (this.starting)
55
55
  return this.starting;
56
- const binary = await executable('opencode');
57
- this.starting = new Promise((resolve, reject) => {
56
+ const starting = (async () => {
57
+ const binary = await executable('opencode');
58
58
  // Keep the normal OS home and the user's existing OpenCode login.
59
59
  const config = JSON.parse(process.env.OPENCODE_CONFIG_CONTENT || '{}');
60
60
  const permission = typeof config.permission === 'string' ? { '*': config.permission } : config.permission;
61
61
  const env = { ...process.env, OPENCODE_CONFIG_CONTENT: JSON.stringify({
62
62
  ...config, permission: { ...permission, external_directory: 'deny' }
63
63
  }) };
64
- const child = spawn(binary, ['serve', '--hostname', '127.0.0.1', '--port', '0'], { stdio: ['ignore', 'pipe', 'ignore'], env });
65
- this.child = child;
66
- const timer = setTimeout(() => { child.kill(); reject(new SourceError('timeout', 'OpenCode server startup timed out')); }, 30000);
67
- let output = '';
68
- child.stdout.on('data', (chunk) => {
69
- output = (output + chunk.toString()).slice(-8192);
70
- const address = output.match(/http:\/\/127\.0\.0\.1:\d+/)?.[0];
71
- if (address) {
72
- clearTimeout(timer);
73
- resolve(address);
64
+ if (this.options.configFile) {
65
+ try {
66
+ const stat = await lstat(this.options.configFile);
67
+ if (!stat.isFile() || stat.isSymbolicLink() || stat.uid !== process.getuid?.() || (stat.mode & 0o777) !== 0o600)
68
+ throw new Error('Invalid private config');
69
+ // Signup may create this private grant after the daemon was started.
70
+ // Let the CLI read it; provider values never enter this process.
71
+ env.OPENCODE_CONFIG = this.options.configFile;
72
+ }
73
+ catch (error) {
74
+ if (error.code !== 'ENOENT')
75
+ throw new SourceError('logged_out', 'OpenCode private configuration is unavailable; rerun usegrunt setup');
74
76
  }
77
+ }
78
+ this.shutdown.signal.throwIfAborted();
79
+ return new Promise((resolve, reject) => {
80
+ const child = spawn(binary, ['serve', '--hostname', '127.0.0.1', '--port', '0'], { stdio: ['ignore', 'pipe', 'ignore'], env });
81
+ this.child = child;
82
+ const timer = setTimeout(() => { child.kill(); reject(new SourceError('timeout', 'OpenCode server startup timed out')); }, 30000);
83
+ let output = '';
84
+ child.stdout.on('data', (chunk) => {
85
+ output = (output + chunk.toString()).slice(-8192);
86
+ const address = output.match(/http:\/\/127\.0\.0\.1:\d+/)?.[0];
87
+ if (address) {
88
+ clearTimeout(timer);
89
+ resolve(address);
90
+ }
91
+ });
92
+ const failed = () => { clearTimeout(timer); this.starting = undefined; this.sessions.clear(); this.sessionModels.clear(); this.sessionParents.clear(); this.prepared.clear(); reject(new SourceError('upstream', 'OpenCode server stopped; run opencode serve to check installation')); };
93
+ child.once('error', failed);
94
+ child.once('exit', failed);
75
95
  });
76
- const failed = () => { clearTimeout(timer); this.starting = undefined; this.sessions.clear(); this.sessionModels.clear(); this.sessionParents.clear(); this.prepared.clear(); reject(new SourceError('upstream', 'OpenCode server stopped; run opencode serve to check installation')); };
77
- child.once('error', failed);
78
- child.once('exit', failed);
79
- });
80
- return this.starting;
96
+ })();
97
+ this.starting = starting;
98
+ void starting.catch(() => { if (this.starting === starting)
99
+ this.starting = undefined; });
100
+ return starting;
81
101
  }
82
102
  async complete(request, caller) {
83
103
  const signal = AbortSignal.any([caller, this.shutdown.signal, ...(this.options.timeout ? [AbortSignal.timeout(this.options.timeout)] : [])]);
@@ -19,7 +19,11 @@ export class StickyRouter {
19
19
  needsHealthCheck(id) { return this.bars.get(id) === Infinity; }
20
20
  healthy(id) { if (this.bars.get(id) === Infinity)
21
21
  this.bars.delete(id); }
22
+ verified(id) { this.bars.delete(id); }
22
23
  listed(id) { return knownAdapters.has(id) && this.options.registry().adapters.some(a => a.id === id); }
24
+ supportsInput(id, imageInput = false) {
25
+ return knownAdapters.has(id) && this.options.registry().adapters.some(adapter => adapter.id === id && adapter.modalities.includes('text') && (!imageInput || adapter.modalities.includes('image')));
26
+ }
23
27
  async git(cwd, args) {
24
28
  return (await exec('git', ['-C', cwd, ...args], { timeout: 10000, maxBuffer: 1024 * 1024 })).stdout.trim();
25
29
  }
@@ -76,7 +80,7 @@ export class StickyRouter {
76
80
  const adapter = adapters.find(a => a.id === source.id);
77
81
  if (!task.source && this.sources.some(s => s.id === request.model) && source.id !== request.model)
78
82
  continue;
79
- if (!adapter || (this.bars.get(source.id) ?? 0) > this.now())
83
+ if (!adapter || this.options.pending?.has(source.id) || (this.bars.get(source.id) ?? 0) > this.now())
80
84
  continue;
81
85
  if (source.id === task.source || await source.available().catch(() => false))
82
86
  eligible.push({ source, weight: adapter.weight });
@@ -0,0 +1,232 @@
1
+ import { constants } from 'node:fs';
2
+ import { mkdir, lstat, readdir, open, rename, rm, writeFile } from 'node:fs/promises';
3
+ import { randomUUID } from 'node:crypto';
4
+ import { join } from 'node:path';
5
+ import { knownAdapters } from '../registry.js';
6
+ const prefix = '.setup-session-';
7
+ const ttl = 90000;
8
+ const heartbeat = 15000;
9
+ const claimName = /^\.setup-session-(\d+)-([a-f0-9-]{36})$/;
10
+ const sourceId = /^[a-z][a-z0-9-]{0,63}$/;
11
+ const unavailable = () => new Error('Cannot coordinate provider setup safely; finish the existing setup or rerun usegrunt setup');
12
+ function alive(pid) { try {
13
+ process.kill(pid, 0);
14
+ return true;
15
+ }
16
+ catch (error) {
17
+ return error.code === 'EPERM';
18
+ } }
19
+ async function privateDirectory(path) {
20
+ const stat = await lstat(path);
21
+ return stat.isDirectory() && !stat.isSymbolicLink() && stat.uid === process.getuid?.() && (stat.mode & 0o777) === 0o700;
22
+ }
23
+ async function claims(directory) {
24
+ if (!await privateDirectory(directory))
25
+ throw unavailable();
26
+ const result = [];
27
+ for (const name of await readdir(directory)) {
28
+ const match = claimName.exec(name);
29
+ if (!match)
30
+ continue;
31
+ const pid = Number(match[1]), path = join(directory, name);
32
+ if (!Number.isSafeInteger(pid) || pid < 1 || !alive(pid))
33
+ continue;
34
+ try {
35
+ if (await privateDirectory(path))
36
+ result.push({ path, id: match[2], pid });
37
+ }
38
+ catch { /* A completed setup may remove its own directory concurrently. */ }
39
+ }
40
+ return result;
41
+ }
42
+ async function readState(claim, allowExpired = false) {
43
+ let file;
44
+ try {
45
+ file = await open(join(claim.path, 'state.json'), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
46
+ const stat = await file.stat();
47
+ if (!stat.isFile() || stat.uid !== process.getuid?.() || (stat.mode & 0o777) !== 0o600 || stat.size > 32768)
48
+ return;
49
+ const state = JSON.parse(await file.readFile('utf8'));
50
+ if (state.version !== 1 || state.id !== claim.id || state.pid !== claim.pid || typeof state.expires !== 'number'
51
+ || !Number.isFinite(state.expires) || (!allowExpired && state.expires <= Date.now()) || state.expires > Date.now() + ttl + 60000
52
+ || !Array.isArray(state.owned) || state.owned.length > 100 || state.owned.some(id => typeof id !== 'string' || !sourceId.test(id))
53
+ || new Set(state.owned).size !== state.owned.length || !Array.isArray(state.pending)
54
+ || state.pending.some(id => typeof id !== 'string' || !state.owned.includes(id)) || new Set(state.pending).size !== state.pending.length
55
+ || !Array.isArray(state.verifying) || state.verifying.some(id => typeof id !== 'string' || !state.pending.includes(id))
56
+ || new Set(state.verifying).size !== state.verifying.length)
57
+ return;
58
+ return state;
59
+ }
60
+ catch {
61
+ return;
62
+ }
63
+ finally {
64
+ await file?.close();
65
+ }
66
+ }
67
+ async function blockingClaim(claim) {
68
+ const state = await readState(claim, true);
69
+ if (state)
70
+ return state.expires > Date.now();
71
+ // Protect the atomic mkdir -> initial snapshot handshake. Old partial claims
72
+ // cannot block a new installer indefinitely, including after PID reuse.
73
+ try {
74
+ return Date.now() - (await lstat(claim.path)).mtimeMs < ttl;
75
+ }
76
+ catch {
77
+ return false;
78
+ }
79
+ }
80
+ /** No credentials are stored here. Dead or expired owners never block routing. */
81
+ export async function readSetupSession(directory) {
82
+ try {
83
+ const active = await claims(directory);
84
+ const states = await Promise.all(active.map(claim => readState(claim, true)));
85
+ // An active initializing/corrupt claim has no trustworthy provider subset.
86
+ // Hold provisioning and dispatch conservatively until its owner repairs or
87
+ // aborts, rather than treating unsafe IO as permission to duplicate signup.
88
+ for (let i = 0; i < active.length; i++)
89
+ if (!states[i] && await blockingClaim(active[i])) {
90
+ const all = new Set([...knownAdapters, 'freellmapi']);
91
+ return { owned: all, pending: all, verifying: new Set() };
92
+ }
93
+ const valid = states.filter((state) => state !== undefined && state.expires > Date.now());
94
+ if (!valid.length)
95
+ return;
96
+ return {
97
+ owned: new Set(valid.flatMap(state => state.owned)), pending: new Set(valid.flatMap(state => state.pending)),
98
+ verifying: new Set(valid.flatMap(state => state.verifying))
99
+ };
100
+ }
101
+ catch {
102
+ return;
103
+ }
104
+ }
105
+ /** Claim before starting the daemon. Keep this owner alive while later approvals run. */
106
+ export async function beginSetupSession(directory, ids) {
107
+ if (ids.length > 100 || ids.some(id => !sourceId.test(id)) || new Set(ids).size !== ids.length)
108
+ throw unavailable();
109
+ await mkdir(directory, { recursive: true, mode: 0o700 });
110
+ if (!await privateDirectory(directory))
111
+ throw unavailable();
112
+ const id = randomUUID(), pid = process.pid, path = join(directory, `${prefix}${pid}-${id}`), claim = { id, pid, path };
113
+ await mkdir(path, { mode: 0o700 });
114
+ // Every contender creates its unique claim before scanning. At most one can
115
+ // observe no other live claim; rejected contenders remove only their own.
116
+ try {
117
+ for (const peer of await claims(directory))
118
+ if (peer.id !== id && await blockingClaim(peer))
119
+ throw unavailable();
120
+ }
121
+ catch (error) {
122
+ await rm(path, { recursive: true, force: true });
123
+ throw error;
124
+ }
125
+ const pending = new Set(ids), verifying = new Set(), controller = new AbortController();
126
+ let closed = false, initialized = false, failure, tail = Promise.resolve();
127
+ let expires = Date.now() + ttl;
128
+ let timer, expiryTimer;
129
+ const fail = () => {
130
+ failure ??= unavailable();
131
+ controller.abort(failure);
132
+ if (timer)
133
+ clearInterval(timer);
134
+ timer = undefined;
135
+ if (expiryTimer)
136
+ clearTimeout(expiryTimer);
137
+ };
138
+ const armExpiry = () => {
139
+ if (expiryTimer)
140
+ clearTimeout(expiryTimer);
141
+ expiryTimer = setTimeout(fail, Math.max(0, expires - Date.now()));
142
+ expiryTimer.unref();
143
+ };
144
+ armExpiry();
145
+ const assertOwner = async () => {
146
+ if (closed || controller.signal.aborted || expires <= Date.now() || !await privateDirectory(path))
147
+ throw unavailable();
148
+ if (initialized) {
149
+ const state = await readState(claim, true);
150
+ if (!state || state.expires !== expires)
151
+ throw unavailable();
152
+ }
153
+ // A committed newer owner means this one has lost authority. Initializing
154
+ // peers will reject our current valid claim, so they cannot evict us.
155
+ for (const peer of await claims(directory))
156
+ if (peer.id !== id && await readState(peer))
157
+ throw unavailable();
158
+ if (controller.signal.aborted || expires <= Date.now())
159
+ throw unavailable();
160
+ };
161
+ const persist = () => {
162
+ const work = tail.then(async () => {
163
+ if (closed)
164
+ return;
165
+ await assertOwner();
166
+ const temporary = join(path, `state.${randomUUID()}.tmp`), nextExpiry = Date.now() + ttl;
167
+ try {
168
+ const state = { version: 1, id, pid, expires: nextExpiry, owned: [...ids], pending: [...pending], verifying: [...verifying] };
169
+ await writeFile(temporary, JSON.stringify(state), { flag: 'wx', mode: 0o600 });
170
+ // Slow IO must not resurrect a lease after its TTL or watchdog abort.
171
+ await assertOwner();
172
+ await rename(temporary, join(path, 'state.json'));
173
+ if (controller.signal.aborted || expires <= Date.now())
174
+ throw unavailable();
175
+ expires = nextExpiry;
176
+ initialized = true;
177
+ armExpiry();
178
+ }
179
+ finally {
180
+ await rm(temporary, { force: true });
181
+ }
182
+ }).catch(() => { fail(); throw failure; });
183
+ tail = work.catch(() => { });
184
+ return work;
185
+ };
186
+ try {
187
+ await persist();
188
+ }
189
+ catch (error) {
190
+ closed = true;
191
+ fail();
192
+ await rm(path, { recursive: true, force: true });
193
+ throw error;
194
+ }
195
+ timer = setInterval(() => { void persist().catch(() => { }); }, heartbeat);
196
+ timer.unref();
197
+ const update = async (source, state) => {
198
+ if (closed || controller.signal.aborted || !ids.includes(source))
199
+ throw unavailable();
200
+ if (state === 'release') {
201
+ pending.delete(source);
202
+ verifying.delete(source);
203
+ }
204
+ else {
205
+ pending.add(source);
206
+ if (state === 'verify')
207
+ verifying.add(source);
208
+ else
209
+ verifying.delete(source);
210
+ }
211
+ await persist();
212
+ };
213
+ return {
214
+ signal: controller.signal,
215
+ verify: source => update(source, 'verify'),
216
+ hold: source => update(source, 'hold'),
217
+ release: source => update(source, 'release'),
218
+ async close() {
219
+ if (closed)
220
+ return;
221
+ closed = true;
222
+ if (timer)
223
+ clearInterval(timer);
224
+ timer = undefined;
225
+ if (expiryTimer)
226
+ clearTimeout(expiryTimer);
227
+ controller.abort(new Error('Provider setup session ended'));
228
+ await tail;
229
+ await rm(path, { recursive: true, force: true });
230
+ }
231
+ };
232
+ }
@@ -30,6 +30,7 @@ import { setupPerch } from './perch-setup.js';
30
30
  import { disabledAdapters } from '../registry.js';
31
31
  import { KILO_PARTICLE, verifyKiloAccess } from './kilo.js';
32
32
  import { DATA_SHARING_POLICIES, dataSharingPolicies, readDataSharingConsent } from './data-sharing.js';
33
+ import { readSetupSession } from './setup-session.js';
33
34
  const exec = promisify(execFile);
34
35
  export const FREELLMAPI_IMAGE = 'ghcr.io/tashfeenahmed/freellmapi@sha256:845a4b568a20fffd5112e1b9c0258e7782d9eabbba2430612d2f7c811eee267e';
35
36
  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', runcrate: 'https://www.runcrate.ai/auth/signup', apinex: 'https://apinex.bond/register', 'mistral-vibe': 'https://console.mistral.ai', livekit: 'https://cloud.livekit.io', pollinations: 'https://enter.pollinations.ai', beatapi: 'https://beatapi.io', clixad: 'https://app.clixad.io', perch: 'https://www.perchai.app' };
@@ -837,6 +838,8 @@ const retiredManagedAdapter = (row) => {
837
838
  };
838
839
  // Reconcile only Grunt-owned sharing rows before a legacy backend request. This
839
840
  // never provisions a router, changes custom rows, or enables a disabled row.
841
+ export class RouterSetupPending extends Error {
842
+ }
840
843
  export async function guardRouterSharing(url, directory) {
841
844
  const approved = await readDataSharingConsent(directory, ['kilo']);
842
845
  const admin = await readLocalAdmin(join(directory, 'router-admin.json'));
@@ -850,7 +853,15 @@ export async function guardRouterSharing(url, directory) {
850
853
  if (updates.length)
851
854
  await router.call('/fallback', updates, 'PUT');
852
855
  const patched = chain.map(row => ({ ...row, ...updates.find(update => update.modelDbId === row.modelDbId) }));
853
- await router.migrateKiloModels(approved, patched);
856
+ const pending = (await readSetupSession(directory))?.pending;
857
+ if (patched.some(row => {
858
+ const provider = managedSharingProvider(row);
859
+ return provider && row.enabled !== false && pending?.has(provider);
860
+ }))
861
+ throw new RouterSetupPending('A managed provider is still being verified');
862
+ // An old aggregate backend must not create a new owned route before the
863
+ // corresponding direct source has passed its foreground verification.
864
+ await router.migrateKiloModels(approved.filter(provider => !pending?.has(provider)), patched);
854
865
  }
855
866
  // Read the login already created by setup; never provision or change router state.
856
867
  export async function loadRouterKey(url) {
@@ -17,18 +17,23 @@ export class Sources {
17
17
  router;
18
18
  // Adapters whose background setup has not finished yet.
19
19
  preparing = new Set();
20
+ // Foreground signups must not probe or dispatch incomplete sources. Routine
21
+ // background checks remain metadata and do not interrupt already-bound work.
22
+ pending = new Set();
23
+ // An exact-ID setup probe may run without admitting that source to the pool.
24
+ verifying = new Set();
20
25
  constructor(sources, routing, disabledModels = new Set()) {
21
26
  this.sources = sources;
22
27
  this.disabledModels = disabledModels;
23
28
  if ((!sources.length && !disabledModels.size) || new Set(sources.map(s => s.id)).size !== sources.length)
24
29
  throw new Error('Configure distinct grunt sources');
25
30
  if (routing)
26
- this.router = new StickyRouter(sources, routing);
31
+ this.router = new StickyRouter(sources, { ...routing, pending: this.pending });
27
32
  }
28
33
  healthy(id) { this.router?.healthy(id); }
29
34
  async models() {
30
35
  const available = await Promise.all(this.sources.map(async (s) => {
31
- if (this.router && !this.router.listed(s.id) || !await s.available())
36
+ if (this.pending.has(s.id) || this.router && !this.router.listed(s.id) || !await s.available())
32
37
  return null;
33
38
  if (this.router?.needsHealthCheck(s.id) && await s.healthCheck?.().catch(() => false))
34
39
  this.healthy(s.id);
@@ -40,6 +45,24 @@ export class Sources {
40
45
  signal.throwIfAborted();
41
46
  if (this.disabledModels.has(request.model))
42
47
  throw new SourceError('refused', `${request.model} routing is disabled`);
48
+ if (this.pending.has(request.model)) {
49
+ if (!this.verifying.has(request.model))
50
+ throw new SourceError('not_installed', `${request.model} setup is still in progress`);
51
+ const source = this.sources.find(source => source.id === request.model);
52
+ if (!source)
53
+ throw new SourceError('not_installed', `No source for model ${request.model}`);
54
+ if (this.router && !this.router.listed(source.id))
55
+ throw new SourceError('not_installed', `${request.model} is not in the current provider registry`);
56
+ if (this.router && !this.router.supportsInput(source.id, request.imageInput))
57
+ throw new SourceError('refused', `${request.model} does not support this input modality`);
58
+ // A setup probe is one exact-source call, never sticky failover or a
59
+ // retry of a provider refusal. The source retains every normal guard.
60
+ const completion = await source.complete(request, signal);
61
+ signal.throwIfAborted();
62
+ this.router?.verified(source.id);
63
+ answeredBy.set(completion, source.id);
64
+ return completion;
65
+ }
43
66
  if (this.router)
44
67
  return this.router.complete(request, signal);
45
68
  const known = this.sources.some(s => s.id === request.model);
@@ -49,6 +72,8 @@ export class Sources {
49
72
  let last = new SourceError('not_installed', `No source for model ${request.model}`);
50
73
  for (const source of candidates) {
51
74
  signal.throwIfAborted();
75
+ if (this.pending.has(source.id))
76
+ continue;
52
77
  let completion;
53
78
  try {
54
79
  completion = await source.complete(request, signal);
@@ -1,6 +1,7 @@
1
1
  import { promisify } from 'node:util';
2
2
  import { spawn, execFile } from 'node:child_process';
3
- import { mkdir, readFile, writeFile, cp, mkdtemp, rm, access } from 'node:fs/promises';
3
+ import { constants } from 'node:fs';
4
+ import { mkdir, readFile, writeFile, cp, mkdtemp, rm, access, lstat, open } from 'node:fs/promises';
4
5
  import { homedir, tmpdir } from 'node:os';
5
6
  import { dirname, join } from 'node:path';
6
7
  import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -16,11 +17,14 @@ import { RegistrySync } from './registry.js';
16
17
  import { bundledRegistry, disabledAdapters, knownAdapters } from '../registry.js';
17
18
  import { banner } from './banner.js';
18
19
  import { approveDataSharing, requiresDataSharing } from './data-sharing.js';
19
- import { HARNESSES, configurePi, connectHarness, detectHarnesses } from './harnesses.js';
20
+ import { configurePi, connectHarness, detectHarnesses } from './harnesses.js';
21
+ import { beginSetupSession } from './setup-session.js';
20
22
  export const configDir = (env = process.env) => env.MILO_CONFIG_DIR || join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'milo');
21
- export async function command(binary, args, interactive = false, signal) {
23
+ export async function command(binary, args, interactive = false, signal, env) {
24
+ signal?.throwIfAborted();
22
25
  const run = () => new Promise((resolve, reject) => {
23
- const child = spawn(binary, args, { stdio: interactive ? 'inherit' : 'ignore', ...(signal ? { signal } : {}) });
26
+ signal?.throwIfAborted();
27
+ const child = spawn(binary, args, { stdio: interactive ? 'inherit' : 'ignore', ...(signal ? { signal } : {}), ...(env ? { env } : {}) });
24
28
  child.once('error', () => reject(new Error(`Could not run ${binary}`)));
25
29
  child.once('exit', code => code === 0 ? resolve() : reject(new Error(`${binary} failed; inspect its service status before retrying`)));
26
30
  });
@@ -70,20 +74,56 @@ export async function squireBrokerExists() {
70
74
  const result = await promisify(execFile)(process.execPath, ['--input-type=module', '-e', program], { env: squireEnvironment(), timeout: 10000 });
71
75
  return result.stdout === 'present';
72
76
  }
73
- export async function connectSquire(options = {}) {
74
- const probe = async () => { const squire = options.squire ?? new BrowserSquire(); try {
75
- await squire.connect();
77
+ async function squireBootstrapEnvironment(signal) {
78
+ signal?.throwIfAborted();
79
+ const directory = configDir();
80
+ await mkdir(directory, { recursive: true, mode: 0o700 });
81
+ signal?.throwIfAborted();
82
+ const parent = await lstat(directory);
83
+ if (!parent.isDirectory() || parent.isSymbolicLink() || parent.uid !== process.getuid?.() || (parent.mode & 0o777) !== 0o700) {
84
+ throw new Error('Squire setup requires a private grunt configuration directory');
85
+ }
86
+ const path = join(directory, 'squire-opencode.json');
87
+ const file = await open(path, constants.O_RDWR | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
88
+ try {
89
+ const stat = await file.stat();
90
+ if (!stat.isFile() || stat.uid !== process.getuid?.() || (stat.mode & 0o777) !== 0o600 || stat.size > 262144) {
91
+ throw new Error('Squire setup requires a private grunt-owned client configuration file');
92
+ }
93
+ signal?.throwIfAborted();
94
+ if (!stat.size)
95
+ await file.writeFile('{}\n');
76
96
  }
77
97
  finally {
78
- if (!options.squire)
79
- await squire.close();
80
- } };
98
+ await file.close();
99
+ }
100
+ signal?.throwIfAborted();
101
+ // The supported Squire override applies only to this installer child. It
102
+ // must never rewrite the user's OpenCode config or a provider grant config.
103
+ return { ...process.env, OPENCODE_CONFIG: path };
104
+ }
105
+ export async function connectSquire(options = {}) {
106
+ const probe = async () => {
107
+ options.signal?.throwIfAborted();
108
+ const squire = options.squire ?? new BrowserSquire(options.signal ? { signal: options.signal } : {});
109
+ try {
110
+ await squire.connect();
111
+ options.signal?.throwIfAborted();
112
+ }
113
+ finally {
114
+ if (!options.squire)
115
+ await squire.close();
116
+ }
117
+ };
81
118
  try {
82
119
  await probe();
83
120
  return;
84
121
  }
85
122
  catch (error) {
86
- if (await (options.hasBroker || squireBrokerExists)()) {
123
+ options.signal?.throwIfAborted();
124
+ const exists = await (options.hasBroker || squireBrokerExists)();
125
+ options.signal?.throwIfAborted();
126
+ if (exists) {
87
127
  throw new Error(`Existing trusty-squire-broker failed its connection probe: ${error instanceof Error ? error.message : String(error)}. Repair the broker, then rerun usegrunt setup.`, { cause: error });
88
128
  }
89
129
  }
@@ -91,7 +131,9 @@ export async function connectSquire(options = {}) {
91
131
  throw new Error('Squire login needs human verification; stopped before onboarding');
92
132
  // Only a machine without a broker may enter the installer.
93
133
  const bin = options.installer || join(dirname(fileURLToPath(import.meta.resolve('@trusty-squire/mcp'))), 'bin.js');
94
- await (options.run || command)(process.execPath, [bin, 'connect', '--target=opencode', '--json'], true);
134
+ const env = await squireBootstrapEnvironment(options.signal);
135
+ options.signal?.throwIfAborted();
136
+ await (options.run || command)(process.execPath, [bin, 'connect', '--target=opencode', '--json'], true, options.signal, env);
95
137
  await probe();
96
138
  }
97
139
  export async function preflight(run = command) {
@@ -152,20 +194,27 @@ export async function installedSources(directory = configDir()) {
152
194
  }
153
195
  return 'freellmapi,kilo,opencode,zro';
154
196
  }
155
- export async function installService(adapters) {
197
+ export async function installService(adapters, options = {}) {
198
+ const stage = async (operation) => {
199
+ options.signal?.throwIfAborted();
200
+ const result = await operation();
201
+ options.signal?.throwIfAborted();
202
+ return result;
203
+ };
204
+ options.signal?.throwIfAborted();
156
205
  if (!['linux', 'darwin'].includes(process.platform))
157
206
  throw new Error('grunt background service requires systemd or launchd');
158
- const selected = [...new Set(adapters ?? (await installedSources()).split(','))].filter(id => id && !disabledAdapters.has(id));
207
+ const selected = [...new Set(adapters ?? (await stage(() => installedSources())).split(','))].filter(id => id && !disabledAdapters.has(id));
159
208
  if (selected.some(id => !knownAdapters.has(id) && id !== 'freellmapi'))
160
209
  throw new Error('Invalid grunt service selection');
161
210
  const directory = configDir(), runtime = join(directory, 'runtime');
162
211
  // npx cache entries can disappear. Keep a backend runtime outside that cache.
163
212
  const root = fileURLToPath(new URL('../../', import.meta.url));
164
- await mkdir(runtime, { recursive: true, mode: 0o700 });
165
- await cp(join(root, 'dist'), join(runtime, 'dist'), { recursive: true });
166
- const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
167
- await writeFile(join(runtime, 'package.json'), JSON.stringify({ name: 'milo-runtime', private: true, type: 'module', dependencies: pkg.dependencies }), { mode: 0o600 });
168
- await command('npm', ['install', '--prefix', runtime, '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund']);
213
+ await stage(() => mkdir(runtime, { recursive: true, mode: 0o700 }));
214
+ await stage(() => cp(join(root, 'dist'), join(runtime, 'dist'), { recursive: true }));
215
+ const pkg = JSON.parse(await stage(() => readFile(join(root, 'package.json'), 'utf8')));
216
+ await stage(() => writeFile(join(runtime, 'package.json'), JSON.stringify({ name: 'milo-runtime', private: true, type: 'module', dependencies: pkg.dependencies }), { mode: 0o600 }));
217
+ await stage(() => command('npm', ['install', '--prefix', runtime, '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund'], false, options.signal));
169
218
  const entry = join(runtime, 'dist', 'local', 'main.js');
170
219
  const port = process.env.MILO_PORT || '8788';
171
220
  if (!/^\d+$/.test(port) || Number(port) < 1 || Number(port) > 65535)
@@ -175,34 +224,42 @@ export async function installService(adapters) {
175
224
  env.MILO_FREELLMAPI_URL = process.env.MILO_FREELLMAPI_URL;
176
225
  const opencodeConfig = join(directory, 'opencode-free.json');
177
226
  try {
178
- await readFile(opencodeConfig);
227
+ await stage(() => readFile(opencodeConfig));
179
228
  env.OPENCODE_CONFIG = opencodeConfig;
180
229
  }
181
230
  catch (error) {
182
231
  if (error.code !== 'ENOENT')
183
232
  throw error;
184
233
  }
185
- await installBackgroundService('milo', entry, env);
186
- await writeFile(join(directory, 'installed-sources.json'), JSON.stringify(selected), { mode: 0o600 });
234
+ await stage(() => installBackgroundService('milo', entry, env, options));
235
+ await stage(() => writeFile(join(directory, 'installed-sources.json'), JSON.stringify(selected), { mode: 0o600 }));
187
236
  }
188
- export async function installBackgroundService(name, entry, env) {
237
+ export async function installBackgroundService(name, entry, env, options = {}) {
238
+ const stage = async (operation) => {
239
+ options.signal?.throwIfAborted();
240
+ const result = await operation();
241
+ options.signal?.throwIfAborted();
242
+ return result;
243
+ };
244
+ const run = (binary, args) => stage(() => command(binary, args, false, options.signal));
245
+ options.signal?.throwIfAborted();
189
246
  if (!/^[a-z][a-z0-9-]*$/.test(name))
190
247
  throw new Error('Invalid service name');
191
248
  if (process.platform === 'linux') {
192
249
  const units = join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'systemd', 'user');
193
- await mkdir(units, { recursive: true });
194
- await writeFile(join(units, `${name}.service`), `[Unit]\nDescription=grunt model service\nAfter=network-online.target\n\n[Service]\nExecStart=${systemdQuote(process.execPath)} ${systemdQuote(entry)}\n${Object.entries(env).map(([key, value]) => `Environment=${systemdQuote(`${key}=${value}`)}`).join('\n')}\nRestart=on-failure\nUMask=0077\n\n[Install]\nWantedBy=default.target\n`, { mode: 0o600 });
195
- await command('systemctl', ['--user', 'daemon-reload']);
196
- await command('systemctl', ['--user', 'enable', `${name}.service`]);
197
- await command('systemctl', ['--user', 'restart', `${name}.service`]);
250
+ await stage(() => mkdir(units, { recursive: true }));
251
+ await stage(() => writeFile(join(units, `${name}.service`), `[Unit]\nDescription=grunt model service\nAfter=network-online.target\n\n[Service]\nExecStart=${systemdQuote(process.execPath)} ${systemdQuote(entry)}\n${Object.entries(env).map(([key, value]) => `Environment=${systemdQuote(`${key}=${value}`)}`).join('\n')}\nRestart=on-failure\nUMask=0077\n\n[Install]\nWantedBy=default.target\n`, { mode: 0o600 }));
252
+ await run('systemctl', ['--user', 'daemon-reload']);
253
+ await run('systemctl', ['--user', 'enable', `${name}.service`]);
254
+ await run('systemctl', ['--user', 'restart', `${name}.service`]);
198
255
  }
199
256
  else {
200
257
  const agents = join(homedir(), 'Library', 'LaunchAgents');
201
- await mkdir(agents, { recursive: true });
258
+ await stage(() => mkdir(agents, { recursive: true }));
202
259
  const plist = join(agents, `ai.${name}.service.plist`), domain = `gui/${process.getuid()}`;
203
- await writeFile(plist, `<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict><key>Label</key><string>ai.${name}.service</string><key>ProgramArguments</key><array><string>${xml(process.execPath)}</string><string>${xml(entry)}</string></array><key>EnvironmentVariables</key><dict>${Object.entries(env).map(([key, value]) => `<key>${xml(key)}</key><string>${xml(value)}</string>`).join('')}</dict><key>RunAtLoad</key><true/><key>KeepAlive</key><true/><key>Umask</key><integer>63</integer></dict></plist>`, { mode: 0o600 });
204
- await command('launchctl', ['bootout', `${domain}/ai.${name}.service`]).catch(() => { });
205
- await command('launchctl', ['bootstrap', domain, plist]);
260
+ await stage(() => writeFile(plist, `<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict><key>Label</key><string>ai.${name}.service</string><key>ProgramArguments</key><array><string>${xml(process.execPath)}</string><string>${xml(entry)}</string></array><key>EnvironmentVariables</key><dict>${Object.entries(env).map(([key, value]) => `<key>${xml(key)}</key><string>${xml(value)}</string>`).join('')}</dict><key>RunAtLoad</key><true/><key>KeepAlive</key><true/><key>Umask</key><integer>63</integer></dict></plist>`, { mode: 0o600 }));
261
+ await run('launchctl', ['bootout', `${domain}/ai.${name}.service`]).catch(() => { });
262
+ await run('launchctl', ['bootstrap', domain, plist]);
206
263
  }
207
264
  }
208
265
  // /v1/models asks every source whether it is available. Bound the combined probe
@@ -262,6 +319,7 @@ export async function checkFallbackServices(unavailable, port = 8788, notify = c
262
319
  const directory = await mkdtemp(join(tmpdir(), 'milo-free-check-'));
263
320
  try {
264
321
  for (const source of adapters) {
322
+ wait.signal?.throwIfAborted();
265
323
  if (unavailable.includes(source)) {
266
324
  notify(`${source}: FAIL — setup incomplete`);
267
325
  continue;
@@ -269,12 +327,13 @@ export async function checkFallbackServices(unavailable, port = 8788, notify = c
269
327
  const deadline = Date.now() + wait.limit;
270
328
  let failure, waiting = false;
271
329
  for (let attempt = 1;; attempt++) {
330
+ wait.signal?.throwIfAborted();
272
331
  let preparing = false;
273
332
  try {
274
333
  const response = await fetch(`http://127.0.0.1:${port}/v1/chat/completions`, {
275
334
  method: 'POST', headers: { 'Content-Type': 'application/json' },
276
335
  body: JSON.stringify({ model: source, cwd: directory, messages: [{ role: 'user', content: `Reply only: grunt is ready (${source}). Do not use tools or change files. Check ${attempt}.` }], stream: false, max_tokens: 256 }),
277
- signal: AbortSignal.timeout(120000)
336
+ signal: AbortSignal.any([AbortSignal.timeout(120000), ...(wait.signal ? [wait.signal] : [])])
278
337
  });
279
338
  preparing = response.headers.get('x-grunt-preparing')?.split(',').includes(source) ?? false;
280
339
  const answered = response.headers.get('x-grunt-source');
@@ -293,13 +352,13 @@ export async function checkFallbackServices(unavailable, port = 8788, notify = c
293
352
  }
294
353
  // Retry only while grunt still runs this adapter's background setup. Each attempt
295
354
  // is a new prompt, so the router does not keep a fallback source from an earlier try.
296
- if (!failure || !preparing || Date.now() + wait.interval > deadline)
355
+ if (!failure || wait.retryPreparing === false || !preparing || Date.now() + wait.interval > deadline)
297
356
  break;
298
357
  if (!waiting) {
299
358
  waiting = true;
300
359
  notify(`${source}: grunt is still preparing this adapter; waiting`);
301
360
  }
302
- await delay(wait.interval);
361
+ await delay(wait.interval, undefined, wait.signal ? { signal: wait.signal } : {});
303
362
  }
304
363
  if (failure) {
305
364
  unavailable.push(source);
@@ -335,19 +394,19 @@ const PREAMBLE = [
335
394
  'sends each request to a free service that can answer it.',
336
395
  '',
337
396
  'Setup will:',
338
- ' 1. Connect Trusty Squire (one Google sign-in)',
339
- ' 2. Pull the current list of free services from the grunt registry',
340
- ' 3. Sign up for each service, connect it to grunt and test it',
341
- ' 4. Connect grunt to the coding tools installed here'
397
+ ' 1. Pull the free service list and ask for grouped sharing approval',
398
+ ' 2. Start grunt and connect your coding tools when a source answers',
399
+ ' 3. Connect Trusty Squire when an account-based source needs it',
400
+ ' 4. Continue remaining signups and browser confirmations alongside use'
342
401
  ].join('\n');
343
402
  const SQUIRE_NOTICE = [
344
403
  'Some free services only work with an account. Trusty Squire is a local',
345
404
  'browser helper that signs up for them using their supported sign-in.',
346
405
  'Most use Google; Runcrate’s card-free access needs GitHub sign-in.',
347
406
  '',
348
- 'Next, a browser may open and ask you to sign in to Google once. If Trusty',
349
- 'Squire is already connected on this machine, setup reuses it. A captcha or',
350
- 'email check pauses setup until you finish it in the browser.'
407
+ 'Account-based setup may open a browser for Google sign-in. An existing',
408
+ 'Squire connection is reused. Anonymous sources can start first. A captcha',
409
+ 'or email check pauses only its source while other setup jobs continue.'
351
410
  ].join('\n');
352
411
  const mark = (status) => status === 'pass' ? chalk.green('✔') : status === 'fail' ? chalk.red('✘') : chalk.dim('–');
353
412
  const describe = (adapter) => [adapter.kind === 'agent' ? 'coding agent' : 'model API', adapter.model ? `free model ${adapter.model}` : undefined,
@@ -364,12 +423,12 @@ const report = (shown = new Set()) => (line) => {
364
423
  else
365
424
  log.info(line);
366
425
  };
367
- export async function connectHarnesses(port, options = {}) {
426
+ export async function prepareHarnesses(port, options = {}) {
368
427
  log.step('Connect grunt to your coding tools');
369
428
  const found = await detectHarnesses(options.harnesses);
370
429
  if (!found.length) {
371
- log.warn(`No supported coding tool found on PATH (${HARNESSES.map(h => h.binary).join(', ')}). Install one, then rerun usegrunt setup.`);
372
- return [];
430
+ log.info('No supported coding tool is currently installed. Grunt will become usable through its local API.');
431
+ return Object.assign(async () => [], { discoverLater: true });
373
432
  }
374
433
  log.info(`Found: ${found.map(h => h.name).join(', ')}. grunt is added as an extra, named option; your default model and provider stay as they are.`);
375
434
  const interactive = process.stdin.isTTY && process.stdout.isTTY && process.env.MILO_SETUP_NO_HUMAN !== '1';
@@ -380,42 +439,56 @@ export async function connectHarnesses(port, options = {}) {
380
439
  options: list.map(h => ({ value: h.id, label: h.name, hint: h.launch(port) })), initialValues: list.filter(h => h.id === 'pi').map(h => h.id) });
381
440
  return isCancel(picked) ? [] : list.filter(h => picked.includes(h.id));
382
441
  });
383
- const connected = [];
384
- for (const harness of await choose(found)) {
385
- const progress = spinner();
386
- progress.start(`${harness.name}: adding grunt and sending a test request through it`);
387
- try {
388
- const { change } = await connectHarness(harness, port, options.run);
389
- progress.stop(`${harness.name}: PASS — answered through grunt`);
390
- if (change?.backup)
391
- log.info(`${harness.name}: previous config saved as ${change.backup}`);
392
- connected.push(harness);
393
- }
394
- catch (error) {
395
- progress.error(`${harness.name}: FAIL — ${error instanceof Error ? error.message : String(error)}`);
442
+ // Choose once before provider jobs can request browser confirmations. Applying
443
+ // the saved choices later never reads stdin or waits for a Squire prompt.
444
+ const selected = await withTerminal(() => choose(found));
445
+ return async () => {
446
+ const connected = [];
447
+ for (const harness of selected) {
448
+ const progress = spinner();
449
+ progress.start(`${harness.name}: adding grunt and sending a test request through it`);
450
+ try {
451
+ const { change } = await connectHarness(harness, port, options.run);
452
+ progress.stop(`${harness.name}: PASS — answered through grunt`);
453
+ if (change?.backup)
454
+ log.info(`${harness.name}: previous config saved as ${change.backup}`);
455
+ connected.push(harness);
456
+ }
457
+ catch (error) {
458
+ progress.error(`${harness.name}: FAIL — ${error instanceof Error ? error.message : String(error)}`);
459
+ }
396
460
  }
397
- }
398
- if (connected.length)
399
- note(connected.map(h => `${chalk.bold(h.name)}\n ${h.launch(port)}`).join('\n'), 'Start coding with grunt');
400
- return connected;
461
+ if (connected.length)
462
+ note(connected.map(h => `${chalk.bold(h.name)}\n ${h.launch(port)}`).join('\n'), 'Start coding with grunt');
463
+ return connected;
464
+ };
401
465
  }
402
- const wizardActions = { installedSources, createSquire: () => new BrowserSquire(), banner, preflight, connectSquire, setup, setupFallbacks, installService, configurePi, checkService, checkFallbackServices, loadRegistry, checkServiceSources, connectHarnesses, approveDataSharing };
466
+ export async function connectHarnesses(port, options = {}) {
467
+ return (await prepareHarnesses(port, options))();
468
+ }
469
+ const wizardActions = { installedSources, createSquire: () => new BrowserSquire(), banner, preflight, connectSquire, setup, setupFallbacks, installService, configurePi, checkService, checkFallbackServices, loadRegistry, checkServiceSources, connectHarnesses, prepareHarnesses, approveDataSharing };
403
470
  export async function wizard(add, actions = wizardActions) {
404
471
  if (add && disabledAdapters.has(add))
405
472
  throw new Error(`${add} routing is disabled`);
406
473
  if (add && !Object.hasOwn(PROVIDERS, add))
407
474
  throw new Error(`Choose a supported provider: ${Object.keys(PROVIDERS).join(', ')}`);
408
475
  const squire = actions.createSquire?.();
476
+ let session;
477
+ let connection;
478
+ let closing;
479
+ let abortSetup;
480
+ const closeSquire = () => closing ??= (async () => { await squire?.close(); })();
481
+ const connect = () => connection ??= step('Connecting Trusty Squire', () => actions.connectSquire({ ...(squire ? { squire } : {}), ...(session ? { signal: session.signal } : {}) }));
409
482
  try {
410
483
  await actions.banner?.();
411
484
  intro(chalk.hex('#f4b41a').bold('grunt') + chalk.dim(' — npx usegrunt setup'));
412
485
  note(PREAMBLE, 'What grunt does');
413
486
  await step('Checking prerequisites', () => actions.preflight());
414
487
  note(SQUIRE_NOTICE, 'Google sign-in for Trusty Squire');
415
- await step('Connecting Trusty Squire', () => actions.connectSquire(squire ? { squire } : {}));
416
488
  // Capture legacy API routing before default Kilo setup creates its admin file.
417
489
  const previous = ((await actions.installedSources?.())?.split(',') ?? []).filter(id => id && !disabledAdapters.has(id));
418
490
  if (add) {
491
+ await connect();
419
492
  const defaults = bundledRegistry.adapters.filter(adapter => knownAdapters.has(adapter.id) && !disabledAdapters.has(adapter.id)).map(adapter => adapter.id);
420
493
  const sources = ['kilo', 'nvidia', 'zro', 'tokenharbor', 'runcrate', 'apinex', 'mistral-vibe', 'livekit', 'pollinations', 'beatapi', 'clixad', 'perch'].includes(add)
421
494
  ? [...new Set([...(previous.length ? previous : defaults), add])]
@@ -471,42 +544,140 @@ export async function wizard(add, actions = wizardActions) {
471
544
  outro('No approved free services are available; the background service now enforces your data-sharing choices');
472
545
  return;
473
546
  }
474
- log.step(`Installing and connecting ${ids.length} vetted free services (up to ${SETUP_CONCURRENCY} at once)`);
475
- log.info('Trusty Squire reuses existing accounts and grants. Only free access is requested. Provider verification may still need your browser; verification prompts are queued.');
476
- const outcome = await actions.setupFallbacks({ directory: configDir(), run: command, adapters: ids, notify,
477
- ...(consent.approved.length ? { dataSharingApproved: consent.approved } : {}),
478
- ...(squire ? { squire, connect: () => squire.connect() } : {}) });
479
- unavailable.push(...outcome.unavailable);
480
- for (const id of ids)
481
- results.get(id).signup = unavailable.includes(id) ? 'fail' : 'pass';
482
- log.step('Connecting the services to the grunt daemon');
483
- await step('Starting the grunt background service', () => actions.installService([...new Set([...previous.filter(id => id === 'freellmapi'), ...ids])]));
484
547
  const port = Number(process.env.MILO_PORT || '8788');
485
- await step(`Waiting for grunt to answer at http://127.0.0.1:${port}`, () => actions.checkService(port));
486
- const beforeSources = new Set(unavailable);
487
- if (actions.checkServiceSources)
488
- await step('Checking which services the daemon runs', () => actions.checkServiceSources(unavailable, notify, ids));
489
- for (const id of ids)
490
- results.get(id).daemon = beforeSources.has(id) ? 'skip' : unavailable.includes(id) ? 'fail' : 'pass';
491
- log.step('Testing each service with a real request through grunt');
492
- await parallelMap(ids, async (id) => {
493
- const before = unavailable.includes(id);
494
- await actions.checkFallbackServices(unavailable, port, notify, [id]);
495
- results.get(id).check = before ? 'skip' : unavailable.includes(id) ? 'fail' : 'pass';
548
+ const harnessPlan = actions.prepareHarnesses ? await actions.prepareHarnesses(port) : undefined;
549
+ if (harnessPlan?.discoverLater)
550
+ log.info('Setup will check again for coding tools after provider installations finish.');
551
+ const applyHarnesses = harnessPlan ?? (async () => {
552
+ if (actions.connectHarnesses)
553
+ await actions.connectHarnesses(port);
554
+ else if (actions.configurePi)
555
+ await step('Pi provider', () => actions.configurePi(port));
496
556
  });
557
+ session = await beginSetupSession(configDir(), ids);
558
+ abortSetup = () => { void closeSquire().catch(() => { }); };
559
+ session.signal.addEventListener('abort', abortSetup, { once: true });
560
+ session.signal.throwIfAborted();
561
+ await step('Starting the grunt background service', () => actions.installService([...new Set([...previous.filter(id => id === 'freellmapi'), ...ids])], { signal: session.signal }));
562
+ await step(`Waiting for grunt to answer at http://127.0.0.1:${port}`, () => actions.checkService(port));
563
+ // Keep at most three real verification requests in flight without holding a
564
+ // provider-install worker. A queued check receives the released slot directly.
565
+ let activeChecks = 0;
566
+ const queuedChecks = [];
567
+ const check = async (task) => {
568
+ if (activeChecks < 3)
569
+ activeChecks++;
570
+ else
571
+ await new Promise(resolve => queuedChecks.push(resolve));
572
+ try {
573
+ return await task();
574
+ }
575
+ finally {
576
+ const next = queuedChecks.shift();
577
+ if (next)
578
+ next();
579
+ else
580
+ activeChecks--;
581
+ }
582
+ };
583
+ const settled = new Map();
584
+ let firstReady;
585
+ let readyCount = 0;
586
+ const firstAnswer = () => firstReady ??= (async () => {
587
+ log.success(`grunt is ready at http://127.0.0.1:${port}; a free provider answered`);
588
+ log.info('Start using grunt now. Keep this setup terminal open for remaining signups and browser confirmations; working requests do not wait for them.');
589
+ try {
590
+ await applyHarnesses();
591
+ }
592
+ catch {
593
+ log.warn('grunt is ready; coding-tool configuration needs attention. Rerun setup to finish connecting your tool.');
594
+ }
595
+ })();
596
+ const onSettled = (id, available) => {
597
+ if (!ids.includes(id))
598
+ return Promise.reject(new Error('Unexpected provider setup result'));
599
+ const previousResult = settled.get(id);
600
+ if (previousResult)
601
+ return previousResult;
602
+ const task = (async () => {
603
+ const result = results.get(id);
604
+ result.signup = available ? 'pass' : 'fail';
605
+ if (!available) {
606
+ if (!unavailable.includes(id))
607
+ unavailable.push(id);
608
+ result.daemon = result.check = 'skip';
609
+ notify(`${id}: FAIL — setup incomplete`);
610
+ return;
611
+ }
612
+ const passed = await check(async () => {
613
+ try {
614
+ session.signal.throwIfAborted();
615
+ await session.verify(id);
616
+ if (actions.checkServiceSources)
617
+ await actions.checkServiceSources(unavailable, notify, [id]);
618
+ result.daemon = unavailable.includes(id) ? 'fail' : 'pass';
619
+ if (result.daemon === 'fail') {
620
+ result.check = 'skip';
621
+ await session.hold(id);
622
+ return false;
623
+ }
624
+ await actions.checkFallbackServices(unavailable, port, notify, [id], { limit: 180000, interval: 2000, signal: session.signal, retryPreparing: false });
625
+ session.signal.throwIfAborted();
626
+ result.check = unavailable.includes(id) ? 'fail' : 'pass';
627
+ if (result.check === 'pass')
628
+ await session.release(id);
629
+ else
630
+ await session.hold(id);
631
+ session.signal.throwIfAborted();
632
+ return result.check === 'pass';
633
+ }
634
+ catch {
635
+ await session.hold(id).catch(() => { });
636
+ if (!unavailable.includes(id))
637
+ unavailable.push(id);
638
+ result.check = 'fail';
639
+ result.daemon ??= 'fail';
640
+ notify(`${id}: FAIL — verification incomplete; other ready sources continue`);
641
+ return false;
642
+ }
643
+ });
644
+ if (passed) {
645
+ readyCount++;
646
+ await firstAnswer();
647
+ }
648
+ })();
649
+ settled.set(id, task);
650
+ return task;
651
+ };
652
+ log.step(`Installing and connecting ${ids.length} vetted free services (up to ${SETUP_CONCURRENCY} at once)`);
653
+ log.info('Trusty Squire reuses existing accounts and grants. Only free access is requested. Sources become usable independently; verification prompts are queued.');
654
+ const outcome = await actions.setupFallbacks({ directory: configDir(), run: command, adapters: ids, notify, onSettled, connect,
655
+ signal: session.signal, ...(consent.approved.length ? { dataSharingApproved: consent.approved } : {}), ...(squire ? { squire } : {}) });
656
+ // Compatibility for injected setup implementations that return only a final
657
+ // result. Production emits settlement events as soon as each source finishes.
658
+ await parallelMap(ids, id => onSettled(id, !outcome.unavailable.includes(id)));
659
+ await Promise.all(settled.values());
660
+ session.signal.throwIfAborted();
497
661
  note([`${'service'.padEnd(10)} sign-in daemon test`, ...requested.map(id => {
498
662
  const r = results.get(id);
499
663
  return `${id.padEnd(10)} ${mark(r.signup)} ${mark(r.daemon)} ${mark(r.check)}`;
500
664
  })].join('\n'), 'Free services');
501
- if (actions.connectHarnesses)
665
+ if (!readyCount)
666
+ throw new Error('No adapters passed verification. Run usegrunt setup to resume.');
667
+ // OpenCode may have been installed by its provider job. Only rediscover
668
+ // when no tool existed initially, never after the user selected none.
669
+ if (harnessPlan?.discoverLater && actions.connectHarnesses)
502
670
  await actions.connectHarnesses(port);
503
- else if (actions.configurePi)
504
- await step('Pi provider', () => actions.configurePi(port));
505
671
  outro(unavailable.length ? `grunt is ready; incomplete fallbacks: ${unavailable.join(', ')}. Rerun setup to finish them.` : 'grunt is ready');
506
- if (unavailable.length)
507
- throw new Error('Some adapters failed verification. Run usegrunt setup to resume.');
508
672
  }
509
673
  finally {
510
- await squire?.close();
674
+ if (session && abortSetup)
675
+ session.signal.removeEventListener('abort', abortSetup);
676
+ try {
677
+ await closeSquire();
678
+ }
679
+ finally {
680
+ await session?.close();
681
+ }
511
682
  }
512
683
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "usegrunt",
3
- "version": "0.6.6",
3
+ "version": "0.6.7",
4
4
  "type": "module",
5
5
  "engines": {
6
6
  "node": ">=22"