usegrunt 0.6.0 → 0.6.1

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
@@ -1,522 +1,27 @@
1
- # grunt
1
+ <h1 align="center">grunt</h1>
2
2
 
3
- Get started with `npx usegrunt setup`. Website: https://grunt.run.
3
+ <p align="center">
4
+ <a href="https://www.npmjs.com/package/usegrunt"><img alt="npm version" src="https://img.shields.io/npm/v/usegrunt"></a>
5
+ <a href="https://www.npmjs.com/package/usegrunt"><img alt="node" src="https://img.shields.io/node/v/usegrunt"></a>
6
+ <a href="https://www.npmjs.com/package/usegrunt"><img alt="downloads" src="https://img.shields.io/npm/dm/usegrunt"></a>
7
+ </p>
4
8
 
5
- Compatibility: the `milo` and `milo-local` commands remain aliases for this release.
6
- Existing `MILO_*` variables, `milo` model/provider IDs, config paths, MCP names,
7
- and infrastructure names remain supported.
9
+ <p align="center"><strong>Free AI inference, pooled on your machine.</strong></p>
8
10
 
9
- Chat with grunt. Hand it a bigger job, keep talking while it works, and get the
10
- result back in the same conversation.
11
-
12
- One Node process, one SQLite file, a front agent, and a small background pool.
13
- There are no accounts: paste your OpenRouter key at `/chat`. Jobs spend your
14
- OpenRouter credits. The key is saved in your browser; use a trusted device.
15
-
16
- ## Run
17
-
18
- Requires Node 22 and pnpm.
19
-
20
- ```sh
21
- pnpm install --frozen-lockfile
22
- pnpm build
23
- MILO_DB=file:./milo.db pnpm start
24
- ```
25
-
26
- Open http://localhost:8787/chat. `pnpm dev` runs the TypeScript source.
27
- `pnpm lint` checks ESLint and TypeScript; `pnpm test` runs the offline suite.
28
-
29
- Environment:
30
-
31
- | Variable | Default | Purpose |
32
- | --- | --- | --- |
33
- | `PORT` | `8787` | HTTP port |
34
- | `MILO_DB` | `file:/data/milo.db` | Local SQLite file |
35
- | `MILO_CONFIG` | unset | Optional JSON file with `agent.whitelist` |
36
-
37
- ## Behavior
38
-
39
- grunt answers quick questions and uses `dispatch`, `status`, `cancel`, and
40
- `remember` for longer work and durable preferences. Each message uses one front
41
- model turn, with a retry on a second model only for transient failure. A worker
42
- receives a self-contained brief and saved notes, never the raw conversation.
43
- Workers have no tools or live web access. There are at most three active workers,
44
- with at most two per person. Jobs are capped at 4,096 output tokens; front replies
45
- at 1,024. Cancel aborts a request. Queued or running jobs fail after a restart.
46
-
47
- On completion or failure, grunt makes a front-model call for a short proactive
48
- update. The full result lives on the job. If that summary call fails, a plain
49
- grunt update still tells you the job's outcome. SSE streams carry assistant
50
- messages and job status changes, with keepalives every fifteen seconds.
51
-
52
- The whitelist defaults to DeepSeek v4.1 Flash, GLM 5.3 Flash, GLM 5.3, GPT 5.6
53
- Luna and Claude Opus 5. The front prefers DeepSeek Flash, then GLM Flash. No
54
- `google/` model is permitted, even if configured. Model access and credits must
55
- be available on your OpenRouter key; there is no substitute outside the whitelist.
56
-
57
- `pick()` filters context size, whitelist membership and recent rate limits,
58
- then scores `reliability × quality − a × latency − b × expected token cost`.
59
- Chat weights favor speed; code, research and writing favor quality. Price and
60
- quality estimates start as explicit priors; reliability and latency learn from
61
- call history. After a 429, 5xx or timeout, a worker retries once on the next model.
62
- A 429 excludes that model for sixty seconds. Jobs show the chosen model and reason.
63
-
64
- To override priors, set `MILO_CONFIG` to a JSON file shaped like:
65
-
66
- ```json
67
- {
68
- "agent": {
69
- "whitelist": [{
70
- "model": "deepseek/deepseek-v4.1-flash",
71
- "quality": { "chat": 0.85, "code": 0.85, "research": 0.85, "writing": 0.85 },
72
- "inputUsdPerM": 0.14, "outputUsdPerM": 0.28,
73
- "contextLength": 128000, "reliability": 0.98, "latencyMs": 1500
74
- }]
75
- }
76
- }
77
- ```
78
-
79
- Priors are estimates, not a live pricing feed. Use the provider's current prices
80
- when configuring cost weights.
81
-
82
- ## API
83
-
84
- All `/agent/*` routes require `Authorization: Bearer <OpenRouter key>`.
85
- The person's identity is the SHA-256 of the key. The server retains the raw key
86
- only for active chat requests and unfinished jobs; it never stores or logs it.
87
- Chat content, briefs, results and notes persist locally in SQLite.
88
-
89
- | Method | Route | Result |
90
- | --- | --- | --- |
91
- | GET | `/` | Redirect to `/chat` |
92
- | GET | `/chat` | Chat page |
93
- | GET | `/health` | Health status |
94
- | POST | `/agent/messages` | `{text}` → `{reply, dispatched}` |
95
- | GET | `/agent/state` | Recent messages, jobs and notes |
96
- | GET | `/agent/events` | Authenticated fetch-streaming SSE: `message`, `task` |
97
- | POST | `/agent/tasks/:id/cancel` | Cancel a job belonging to the caller |
98
-
99
- ## Offline demonstration
100
-
101
- ```sh
102
- pnpm build
103
- MILO_DB=file:/tmp/milo-proof.db PORT=8788 node --import ./proof/fake.mjs dist/server.js
104
- ```
105
-
106
- Open `/chat` on that port and enter any synthetic key. Send “hello”, “remember I
107
- write TypeScript; keep answers short”, “write a one-page launch plan”, then “what
108
- is the capital of France?”. The job stays running while Paris appears. Release
109
- it with `curl -X POST http://127.0.0.1:18789/release`; grunt proactively posts its
110
- summary and attaches the full plan. This adapter never calls OpenRouter.
111
-
112
- ## Deploy
113
-
114
- The Docker image contains only the compiled app, page and production dependencies.
115
- On pushes to main, GitHub builds and smoke-tests the exact image, then deploys
116
- it to Fly app `milo-gateway` in `iad` using the existing `FLY_API_TOKEN` secret.
117
- The `milo_data` volume mounts at `/data`. Keep a single Fly machine for SQLite.
118
-
119
- This replaces the former OpenAI-compatible gateway. The old `/v1/*` routes are
120
- removed. There is no Jev, billing, roster service, worker tooling or monorepo.
121
-
122
- ## Use grunt as your harness's model
123
-
124
- Run the separate local daemon on your own machine (Node 22+, Linux or macOS,
125
- `opencode` on PATH, and `tmux` with an existing logged-in `freebuff` for the last fallback):
126
-
127
- ```sh
128
- pnpm install --frozen-lockfile
129
- pnpm build
130
- node dist/local/main.js setup
131
- # Published package: npx usegrunt setup; installed bin: usegrunt.
132
- # Freebuff alone, without API setup: MILO_SOURCES=freebuff node dist/local/main.js
133
- ```
134
-
135
- It binds only `127.0.0.1:8788`. `MILO_PORT` changes the port. It provides
136
- `GET /v1/models`, Chat Completions, Anthropic Messages, and OpenAI Responses,
137
- including SSE. Choose model `milo` for automatic source selection, or a source
138
- id such as `freebuff`. This process is separate from the Fly server and Docker
139
- entry point. Local callers can invoke Freebuff with your filesystem permissions;
140
- keep this endpoint on your own machine.
141
-
142
- Requests containing function tools follow the same source selection and fallback
143
- rules as other requests. Selecting `freebuff` keeps Freebuff eligible even when
144
- Pi attaches tool definitions, including on the separate fallback listener.
145
- FreeLLMAPI and Gateway forward tool definitions to their upstream APIs. Without
146
- the JSON bridge, Freebuff remains a delegate returning final text; routing a
147
- request to it does not enable Pi's own tool loop.
148
-
149
- Freebuff returns only text after the last non-text block in its completed reply.
150
- Earlier deliberation and tool activity are omitted.
151
-
152
- Freebuff acts as a delegate: it runs its own tools and can edit files in the
153
- working directory. Your harness receives final text; its own tool loop does not
154
- run for that turn. grunt extracts cwd from harness context (including environment
155
- blocks), accepts an explicit absolute `cwd`, and otherwise uses the daemon's
156
- working directory. It logs the chosen directory. Check it before asking for edits.
157
- Text and function-tool turns are translated across APIs. Native Responses tools
158
- are accepted by the app delegate; the Chat Completions gateway cannot forward
159
- those tools and fails over to the app source. Unsupported media blocks return an
160
- error rather than silently losing context.
161
-
162
- ### Free API and account setup
163
-
164
- `npx usegrunt` (or `npx usegrunt setup`) starts the terminal wizard. In a wide
165
- interactive terminal it opens with a short animation (any key skips it; CI,
166
- pipes and narrow terminals get a one-line title). It explains what grunt does,
167
- then says that Trusty Squire needs one Google sign-in before it installs and
168
- connects the local broker. Setup pulls the free service list from the grunt
169
- registry (falling back to the saved or bundled list, and saying so), signs in
170
- to each service, installs the grunt background service, and sends each service
171
- a test request through grunt. Each service gets a PASS/FAIL line and a summary
172
- row. Incomplete setup exits unsuccessfully with a repair step; rerun it to
173
- resume. For a foreground daemon, run `usegrunt serve`.
174
-
175
- Setup ends by offering to connect grunt to the coding tools it finds on PATH
176
- (Pi is preselected; non-interactive runs connect Pi only). Each choice adds a
177
- named **grunt** option and keeps your default model and provider:
178
- Pi gets a `grunt` provider in `models.json`; Codex gets its own
179
- `$CODEX_HOME/grunt.config.toml` for `codex --profile grunt` (`config.toml` is
180
- not edited); OpenCode gets a `grunt` provider in `opencode.json` (pick it with
181
- `/models`; an `opencode.jsonc` file is left alone); Claude Code needs no file
182
- and is started with the printed `ANTHROPIC_BASE_URL` command. A changed file is
183
- first copied to `<file>.grunt-backup-<time>`. Each tool is reported connected
184
- only after it answers one real request through grunt.
185
-
186
- Freebuff pairs its CLI through Squire's browser. Setup installs tmux when
187
- needed. OpenCode first tries its free model without an account and requests
188
- sign-in only if that model requires it. Captcha, passkey and email verification
189
- show a browser handoff and wait for the user to resume. Existing accounts are
190
- reused; no extra Google accounts are created.
191
-
192
- Before making changes, setup checks Node, npm, Pi, tar and the user service
193
- manager. A missing prerequisite prints its install or repair step and stops.
194
-
195
- Existing vault API keys are reused. Missing keys are created through Squire's
196
- browser and captured directly into its vault. Human verification opens a browser
197
- handoff, including email confirmation, and signup resumes in that same session.
198
- Provider refusals stop setup. grunt calls `grant_app_access` and sends only
199
- the grant's base URL and bearer token to FreeLLMAPI's custom-provider endpoint.
200
- Provider keys stay in Squire; no provider reveal approval is requested. Groq
201
- uses its `/openai/v1` API path beneath the Squire grant root. Setup discovers
202
- currently available chat models through that grant before registering one.
203
- `usegrunt add groq` or `usegrunt add cerebras` connects another provider through the same flow.
204
-
205
- When no Squire session exists, the wizard runs Squire's own connect installer
206
- with the OpenCode target. Squire manages login and its broker service. An existing
207
- session with an unavailable broker reports the connection error for repair.
208
- Setup does not pair with Beeline or create agents or Rooms.
209
-
210
- grunt state lives under `$MILO_CONFIG_DIR`, otherwise `$XDG_CONFIG_HOME/milo` or
211
- `~/.config/milo`. Keep this directory across service restarts. Local router login
212
- and encryption material are generated once and stored with mode `0600`.
213
- FreeLLMAPI encrypts the grant tokens in its backend database. Neither tokens nor
214
- provider keys appear in Pi's config or terminal output. Never share backend state.
215
- Existing routers with keys are preserved if their local admin state is missing.
216
-
217
- The service uses FreeLLMAPI first and OpenCode free models as fallback. It loads
218
- the saved router login itself at startup and retries if the router is temporarily
219
- unavailable. Setup keeps a runtime outside the npx cache, so cache cleanup does
220
- not remove the service. Pi's other providers are preserved. `PI_CODING_AGENT_DIR`
221
- selects a nondefault Pi agent directory.
222
-
223
- Setup installs the pinned FreeLLMAPI Node server as a separate background service;
224
- Docker is not required. Linux uses systemd user units; macOS uses launchd
225
- (macOS remains untested). The router data and private login live under grunt's
226
- config directory. `MILO_FREELLMAPI_URL` chooses its numeric loopback address and
227
- is saved in grunt's service configuration. The router's database is created under
228
- umask `0077`. `MILO_ROUTER_RUNTIME=docker` retains the older Docker installer for
229
- existing installations and offline regression checks.
230
-
231
- `MILO_SQUIRE_HOME` and `MILO_SQUIRE_XDG_CONFIG_HOME` select an existing Squire
232
- home without relocating grunt state. `MILO_SETUP_NO_HUMAN=1` stops before Squire
233
- onboarding or browser handoff if human verification would be needed.
234
-
235
- The package is `usegrunt` (version `0.6.0`); the installed command is `usegrunt`.
236
- This change prepares the package for publication after merge; it does not publish.
237
-
238
- Explicit legacy FreeLLMAPI installations send calls to `http://127.0.0.1:3001/v1`, including
239
- provider failover. There is no direct OpenRouter free API route. An already
240
- configured install can provide `MILO_FREELLMAPI_KEY` in its process environment;
241
- `MILO_FREELLMAPI_URL` accepts numeric HTTP loopback addresses only. The completion
242
- cap is (4096) tokens. Select `freellmapi` for the free chain or `kilo` for the
243
- anonymous `kilo-auto/free` model through that same router. Kilo needs no account.
244
- The separate Freebuff bridge listens only on `127.0.0.1:8789` and contains only
245
- the Freebuff source, preventing a routing loop. FreeLLMAPI supports priority
246
- ordering: keyed providers come first, Kilo next, Freebuff last. Setup enables
247
- only those providers in the chain, excluding Google, OpenRouter and unvetted
248
- aggregators.
249
-
250
- FreeLLMAPI's signed catalog handles model and quota updates. Free installations
251
- receive its delayed monthly snapshot; live catalog access is a separate upstream
252
- premium option. Check the local dashboard when provider availability changes.
253
- FreeLLMAPI is single-user software for personal experimentation; keep it bound
254
- to loopback. See its [installation guide](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/install/01-install.md).
255
-
256
- ### OpenCode app driver
257
-
258
- Select `opencode` as the grunt model. grunt starts `opencode serve` on a loopback
259
- port, using your normal OS home and existing OpenCode login. It sends only the
260
- latest user message, word for word, through the session API, with no caller
261
- system prompt or tool definitions. Follow-ups with their user-message history
262
- reuse the same session; the mapping lasts until grunt exits. OpenCode runs its
263
- own tools and returns final text, as Freebuff does. It uses no tmux.
264
-
265
- `MILO_OPENCODE_MODEL` selects the OpenCode free model (default `big-pickle`).
266
- Use a currently free model from your OpenCode catalog; grunt does not buy credits
267
- or switch to paid models. `MILO_OPENCODE_URL` optionally connects an existing
268
- numeric loopback server. If it uses HTTP Basic auth, set
269
- `OPENCODE_SERVER_USERNAME` and `OPENCODE_SERVER_PASSWORD` in grunt's environment.
270
- Avoid configuring that OpenCode server to call grunt, which would create a loop.
271
- See the [server API](https://opencode.ai/v1/docs/server/).
272
-
273
- [OpenCode's free models](https://opencode.ai/docs/zen) may be free only for a
274
- limited time, and some retain prompts for training. [Kilo Auto Free](https://kilo.ai/docs/getting-started/using-kilo-for-free)
275
- may route to providers that log prompts and outputs and use them to improve
276
- their services. Do not send confidential data through these free routes.
277
-
278
- ### opencode
279
-
280
- For opencode 1.18.31, save this as `opencode.json` in your project:
281
-
282
- ```json
283
- {
284
- "$schema": "https://opencode.ai/config.json",
285
- "model": "milo/milo",
286
- "provider": {
287
- "milo": {
288
- "name": "grunt",
289
- "npm": "@ai-sdk/openai-compatible",
290
- "options": { "baseURL": "http://127.0.0.1:8788/v1", "apiKey": "local" },
291
- "models": { "milo": { "name": "grunt" } }
292
- }
293
- }
294
- }
295
- ```
296
-
297
- Then run `opencode -m milo/milo`. The [provider docs for this config format](https://docs.dev.opencode.ai/docs/providers/)
298
- use `provider`, `npm`, and `options`. Newer native configs in the
299
- [current docs](https://opencode.ai/docs/providers/) use `providers`,
300
- `package: "@opencode/ai/providers/openai-compatible"`, and `settings` instead.
301
-
302
- ### pi
303
-
304
- Add this provider to `~/.pi/agent/models.json` (tested with pi 0.99.1):
305
-
306
- ```json
307
- {
308
- "providers": {
309
- "milo": {
310
- "baseUrl": "http://127.0.0.1:8788/v1",
311
- "api": "openai-completions",
312
- "apiKey": "local",
313
- "models": [{
314
- "id": "milo", "name": "grunt", "reasoning": false, "input": ["text"],
315
- "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
316
- "contextWindow": 128000, "maxTokens": 8192
317
- }]
318
- }
319
- }
320
- }
321
- ```
322
-
323
- Run `pi --provider milo --model milo`. See [pi's model configuration](https://pi.dev/docs/latest/models-configuration).
324
-
325
- ### Claude Code
326
-
327
- Claude Code 2.1.319 uses the Anthropic endpoint:
328
-
329
- ```sh
330
- ANTHROPIC_BASE_URL=http://127.0.0.1:8788 \
331
- ANTHROPIC_AUTH_TOKEN=local \
332
- claude --model milo
11
+ ```bash
12
+ npx usegrunt
333
13
  ```
334
14
 
335
- See [Claude Code gateway configuration](https://code.claude.com/docs/en/llm-gateway).
336
- The placeholder token satisfies the client; the loopback daemon does not require
337
- a provider credential. Custom model metadata may produce a context-window warning.
338
-
339
- ### Codex
340
-
341
- Add to your user `config.toml` (Responses API; tested with Codex 0.167.0):
342
-
343
- ```toml
344
- model = "milo"
345
- model_provider = "milo"
346
-
347
- [model_providers.milo]
348
- name = "grunt"
349
- base_url = "http://127.0.0.1:8788/v1"
350
- wire_api = "responses"
351
- ```
352
-
353
- Run `codex`. See the [official configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference).
354
-
355
- ### Codex source
356
-
357
- Codex is opt-in. With the official `codex` CLI already signed in using ChatGPT,
358
- set `MILO_SOURCES=codex,freellmapi,opencode,kilo` to enable it first. Enabling it
359
- spends your Codex plan allowance, including the weekly limit. Without
360
- `MILO_SOURCES`, grunt uses only Freebuff and OpenCode and never launches Codex.
361
- With Codex enabled, select model `codex` to use only Codex.
362
- API-key logins do not enable this source. Missing or signed-out Codex is omitted
363
- from `/v1/models`; grunt continues through the free chain on usage limits.
364
-
365
- grunt spawns `codex exec --json --sandbox workspace-write` in the request's working
366
- directory. Codex can use its tools and edit files there. grunt never reads or
367
- copies Codex login files, changes its config, or signs you in. Set
368
- `MILO_CODEX_MODEL` to override your Codex default. Only the latest user text is
369
- sent; follow-ups resume the saved thread, keyed by working directory and user
370
- history. Session mappings last until grunt exits. Avoid pointing the delegated
371
- Codex default back at grunt, which would create a routing loop.
372
-
373
- ### Sources and app sessions
374
-
375
- The launch registry contains Freebuff and OpenCode with equal selection
376
- probability after renormalization. Both adapters currently support text only.
377
- Pi remains the harness. Each new user turn starts a task keyed by the canonical
378
- working directory and user history. Tool results and retries keep the same
379
- adapter. No usage counters switch it ahead of quota exhaustion.
380
-
381
- A quota error switches immediately and bars that adapter until Retry-After,
382
- or one hour. Three consecutive upstream failures or timeouts in a task bar it
383
- for fifteen minutes. A missing installation or expired login bars it until a
384
- successful health check. Cancellation and provider refusal do not switch.
385
- When no eligible adapter remains, the API returns HTTP 429 and, when known,
386
- the earliest Retry-After. Agent adapters return final text, so streaming headers
387
- are sent after completion; quota failures retain their HTTP status.
388
-
389
- On handoff, the next adapter receives the original task, working-tree status,
390
- the diff against a task-start `git stash create` checkpoint, the previous
391
- adapter's last four KB of output, and an instruction to continue without
392
- restarting. The checkpoint creates no branch commit or stash entry. Outside a
393
- git repository, only task text and output are sent.
394
-
395
- The owner curates `registry/adapters.json`. The **Publish adapter registry**
396
- workflow accepts manual dispatch only by `lunchboxfortwo` on `main`, validates
397
- the registry, uploads it atomically to the Fly gateway volume, and checks
398
- `GET /v1/registry`. Ordinary code deployments do not publish registry edits.
399
- Before the first dispatch the endpoint returns HTTP 503. Published data
400
- survives deploys and has an ETag. Stable weights total (0.8) and experimental
401
- weights total (0.2) when both tiers are present. Unknown adapter identifiers
402
- are ignored locally and cannot install new code.
403
-
404
- The daemon synchronizes on startup and every twenty-four hours with
405
- If-None-Match. It writes the valid registry and ETag atomically in a private
406
- `registry.json` in its existing config directory. A gateway or cache failure
407
- keeps the last good list, falling back to the packaged list on a fresh install.
408
- Known adapters are installed and checked during sync; removing a registry entry
409
- disables it without uninstalling its files. The legacy `MILO_CONFIG_DIR` and
410
- `MILO_PORT` settings remain supported. `GRUNT_REGISTRY_URL` overrides the sync
411
- endpoint for local development.
412
-
413
- Explicit `MILO_SOURCES` configurations containing legacy sources such as Dots,
414
- Codex or FreeLLMAPI retain their existing ordered behavior. They are outside the
415
- launch registry. Codex still requires explicit opt-in. The Fly personal-agent
416
- API remains separate from this local daemon.
417
-
418
- Outside provider handoffs, only the latest user text is pasted into Freebuff, without system/developer prompts, tools, results, or known harness context envelopes. Title, summary, topic and warm-up requests are answered locally; classification and the selected working directory are logged. Side-call detection uses system/developer instructions, including Claude Code's recorded session-naming prompt; an ordinary user request for a summary still reaches the source. Detection remains heuristic.
419
-
420
- An experimental Freebuff JSON tool bridge is available with
421
- `MILO_FREEBUFF_JSON_BRIDGE=1`. It is **off by default and not live validated**.
422
- When enabled, Freebuff translates function-tool requests into the JSON protocol,
423
- including on the separate fallback listener. Existing source order still applies. Every bridge
424
- request sends the full system/developer, skill and conversation context, tool
425
- definitions, assistant calls and correlated Pi tool results in a fresh CLI
426
- session. Treat this as disclosure of that context to Freebuff.
427
-
428
- The bridge accepts a whole JSON final-answer or tool-call envelope, validates
429
- names and arguments against JSON Schema draft 7 with Ajv, and returns tool calls
430
- for Pi to execute with its existing permissions. Unsupported schemas fail closed;
431
- arguments are never coerced or supplied with defaults. IDs are deterministic for
432
- the same complete request and call. A changed context gets different IDs. There
433
- is no execution ledger: Pi owns execution and retry deduplication; IDs alone do
434
- not provide exactly-once execution across client retries. The adapter rejects
435
- unmatched, duplicate and missing tool results and duplicate calls within one
436
- envelope. It allows one repair in another fresh session, then fails/falls back.
437
- Rejected protocol text and partial deliberation are not returned as answers or
438
- fallback context. Cancellation stops the bridge rather than repairing it.
439
-
440
- This is not a sandbox. Freebuff CLI (tested help: version 0.2.36) exposes no
441
- documented option to disable its native tools. Instructions ask it to use only
442
- the JSON protocol, but cannot enforce that. Observed native-tool blocks reject
443
- the completion without repair; rejection cannot undo actions already executed.
444
- Use a separately restricted host environment for any authorized live trial.
445
- Fresh sessions prevent persisted chat reuse, but do not isolate Freebuff's file
446
- access or other ambient account state.
447
-
448
- Freebuff's [published terms](https://freebuff.com/terms-of-service), effective
449
- November 12, 2026, restrict relaying access to other applications and automated
450
- operation without written permission. No supported authorization for this
451
- integration has been established. Do not treat a CLI login or the opt-in flag as
452
- that permission. Live tool and skill support remains unproven; see
453
- [the recorded proof and limitations](proof/freebuff-json-bridge.md).
454
-
455
- A conversation is keyed by canonical working directory and a hash of its first user text. Follow-ups resume its saved Freebuff chat using `--continue`; concurrent requests use separate chats. The in-memory mapping lasts until the daemon exits. Each turn runs in a dedicated tmux session. Requests queue
456
- per canonical working directory; `MILO_APP_POOL` defaults to (2) active sessions
457
- per directory. New-chat creation and association are serialized per shared on-disk project
458
- directory, including different working folders with the same basename. Once a
459
- chat is associated with its originating process, its response runs concurrently
460
- with other associated turns; replies and startup logs are read only from that chat. SIGINT/SIGTERM
461
- cancel work and close only grunt's own sessions and server on its private tmux socket.
462
- The private server stays alive between turns so ending the last session cannot
463
- race with launching the next; daemon shutdown waits for launches and closes it explicitly.
464
- `MILO_APP_TIMEOUT_MS` defaults to (600000), including queue time. More sessions
465
- consume your account's free hours faster. Freebuff automation may conflict with
466
- its terms; using your account this way is your choice.
467
-
468
- Errors carry `not_installed`, `logged_out`, `quota`, `timeout`, `refused`, or `upstream` in
469
- the harness's error envelope. Missing executables are detected immediately.
470
- Freebuff refusals (`prompt_policy_refused`) in the chat log return a typed `refused` error immediately and permit source failover. Long pastes stored in text attachments are supported.
471
-
472
- The driver runs a bounded `freebuff doctor` preflight and reads startup log errors before waiting for a saved user message. A turn that is never persisted fails with a startup error after (10 seconds). Recognized login and exhausted-hours diagnostics return typed errors immediately.
473
- Unrecognized startup failures return a clear upstream error; they do not wait
474
- for the full model-turn timeout. Stable malformed chat data returns an explicit format error.
475
- Authentication, quota, missing-app and upstream availability failures can try the
476
- next configured source. Timeouts stop instead of replaying potentially unfinished
477
- filesystem work. Use `MILO_SOURCES=freebuff` to keep requests on the app path.
478
-
479
- The source interface is in `src/local/source.ts`; `Multiplexer` is in
480
- `src/local/multiplexer.ts`. Register another app in local configuration without
481
- changing API handlers. Offline tests replay recorded harness request shapes and
482
- run a fake Freebuff TUI through real tmux; they require tmux but no credentials.
483
-
484
- To demonstrate the built daemon offline, run `pnpm build && node src/local/proof.mjs`.
485
- It starts the real local entry point with a temporary fake Freebuff on PATH,
486
- exercises all three APIs with and without SSE, and removes its temporary chats.
487
-
488
- To replay chat-ownership races through the built HTTP API, run
489
- `pnpm build && node src/local/ownership-proof.mjs`. This uses a filesystem-writing
490
- multiplexer that delays send completion until both processes have persisted their
491
- chat. It verifies exact cwd/chat ownership, follow-up continuation, and a quota-only
492
- startup log alongside a successful request from another folder named `project`.
493
-
494
- ### Dots through the grunt connector (optional)
495
-
496
- With grunt running on your computer, tell your dot:
497
-
498
- > Join grunt: api.grunt.run/join
499
-
500
- Choose **Allow** when ChatGPT opens grunt's connection page. It sends your browser to the local daemon, redeems a single-use ticket, and returns to ChatGPT. No command or typed code is needed. The dot receives server instructions to subscribe to `milo.request` automatically and return answers with `milo_submit_reply`.
501
-
502
- Dots is off by default. Start grunt with an explicit source order that includes it:
503
-
504
- ```sh
505
- MILO_SOURCES=dots,freellmapi,opencode,kilo usegrunt serve
506
- ```
507
-
508
- The normal join flow targets the default daemon port (`8788`). The OAuth authorize URL can specify `milo_port` when the daemon runs on another port. If grunt cannot be reached, or you approve on a phone, return to the Allow page and choose **Connect another computer**. Run the displayed fallback command, `usegrunt dots link <code>`, on the computer running grunt, then choose **Continue to ChatGPT** on that page. Codes and tickets are private, single-use, and expire within ten minutes. The fallback command reuses the same device secret as automatic pairing.
509
-
510
- Select model `dots` for the dot only. Model `milo` moves to the next source when the device is not paired, no live subscription exists, the dot reports an actual quota refusal, or no reply arrives before `MILO_DOTS_TIMEOUT_MS` (default `300000`, five minutes). Caller cancellation stops the chain. Without pairing, dots is absent from `/v1/models`. Without `dots` in `MILO_SOURCES`, normal requests and the local pairing route make no gateway calls. Replies that merely discuss usage limits are returned normally.
15
+ usegrunt installs grunt on this machine. It pools free AI quota and serves one local agent.
511
16
 
512
- grunt stores its generated device secret in `dots.json` under `MILO_CONFIG_DIR`, otherwise `$XDG_CONFIG_HOME/milo` or `~/.config/milo`, with mode `0600`, and reuses it for later authorizations. It is a grunt relay secret, never an OpenAI token; do not share that file. Local pairing requires a navigation from the configured gateway and a ticket that gateway confirms was approved. It refuses arbitrary origins, return URLs, unapproved tickets, reused tickets and expired tickets.
17
+ https://grunt.run. `milo` and `milo-local` remain aliases.
513
18
 
514
- The public relay runs on `milo-gateway` at api.grunt.run. `/join` is the canonical OAuth MCP endpoint; `/mcp` is an alias. `MILO_DOTS_URL` overrides the relay origin for tests (HTTP only on loopback). Pair using that override: grunt will not forward an existing device secret to another origin. The gateway's `MILO_PUBLIC_URL` defaults to `https://api.grunt.run` and controls OAuth metadata. Deployment uses the existing merge-to-main workflow.
19
+ Setup is Trusty Squire, the free-service list, sign-in, then your coding tools.
515
20
 
516
- The relay sends a signed event containing only a request ID and fixed summary. The dot reads the conversation with `milo_get_request`, then calls `milo_submit_reply(requestId, text)` or `milo_fail_request(requestId, reason)` (`quota` or `upstream`). Follow-ups carry earlier user and assistant turns. Prompt text is removed from SQLite when answered or expired; replies remain only until local acknowledgment or expiry. Text is never written to application logs. The relay temporarily stores conversation text and the dot receives it, so send only content you intend to share.
21
+ [Reference](https://github.com/bananaman614305/milo/blob/main/docs/reference.md).
517
22
 
518
- MCP Events is experimental. The live test checks whether the dot follows the server instructions and subscribes by itself. If it does not, say: “Subscribe to grunt's milo.request event, answer each request in chat, and send the answer back with milo_submit_reply.” Record the exact error if ChatGPT rejects a subscription. You can ask the dot manually to read a queued request while its subscription remains live. Whether event-triggered dot work counts against plan limits must be checked live; do not assume it is free. Every prompt asks for a chat answer without starting Codex or Work tasks, but this cannot guarantee the dot's behavior or usage accounting. Replies are text only; they cannot edit the local working directory or return local tool calls.
23
+ Run `usegrunt add kilo` to connect Kilo and restart grunt with its API sources enabled. This reuses saved Squire access or opens Kilo's free signup flow. Requests using model `grunt`, `milo`, or `freellmapi` try free Nemotron 3 Ultra before `kilo-auto/free`; model `kilo` selects Auto explicitly. Freebuff and OpenCode remain available. Repeat setup preserves the API sources. If Nemotron disappears from Kilo's catalog, setup uses Auto.
519
24
 
520
- Disconnecting the connector revokes the grant and stops subscriptions when ChatGPT invokes the revocation endpoint. Otherwise subscriptions expire within a day; grunt cannot detect ChatGPT-only removal immediately.
25
+ Kilo free models may log prompts or use them for training; avoid sensitive prompts. Their free limits are unknown. Kilo quota errors fall through FreeLLMAPI's fallback chain. Requests allow a long timeout for Nemotron reasoning.
521
26
 
522
- References: [OpenAI MCP Events](https://developers.openai.com/plugins/build/mcp-events), [ChatGPT plugin connections](https://developers.openai.com/plugins/deploy/connect-chatgpt), and [dots availability and delegated tasks](https://learn.chatgpt.com/docs/dots).
27
+ Squire egress grants use the first allowed host and the stored authentication shape. Kilo setup uses `api.kilo.ai` first, bearer authentication, and `/api/gateway` beneath the grant. Provider keys stay in Squire.
@@ -0,0 +1,4 @@
1
+ // An idle SSE subscription for tests that exercise other OpenCode behavior.
2
+ export function idleEvents() {
3
+ return new Response(new ReadableStream(), { headers: { 'Content-Type': 'text/event-stream' } });
4
+ }
@@ -82,7 +82,7 @@ export async function configureOpenCode(port = 8788) {
82
82
  catch {
83
83
  try {
84
84
  await access(join(directory, 'opencode.jsonc'));
85
- throw new Error(`OpenCode uses ${join(directory, 'opencode.jsonc')}, which setup does not edit. Add the grunt provider by hand: see the README`);
85
+ throw new Error(`OpenCode uses ${join(directory, 'opencode.jsonc')}, which setup does not edit. Add the grunt provider by hand: see docs/reference.md`);
86
86
  }
87
87
  catch (error) {
88
88
  if (error.code !== 'ENOENT')
@@ -51,6 +51,7 @@ await import(pathToFileURL(process.env.MILO_ROUTER_ENTRY).href);
51
51
  MILO_CONFIG_DIR: configDir(), MILO_ROUTER_ENTRY: entry,
52
52
  HOST: '127.0.0.1', PORT: url.port || '80', NODE_ENV: 'production',
53
53
  FREEAPI_DB_PATH: join(directory, 'router.db'),
54
+ PROVIDER_TIMEOUT_CUSTOM: '600000',
54
55
  PATH: process.env.PATH || '/usr/local/bin:/usr/bin:/bin'
55
56
  });
56
57
  }
@@ -12,6 +12,7 @@ export class OpenCode {
12
12
  child;
13
13
  starting;
14
14
  sessions = new Map();
15
+ prepared = new Map();
15
16
  busy = new Set();
16
17
  shutdown = new AbortController();
17
18
  constructor(options = {}) {
@@ -46,7 +47,12 @@ export class OpenCode {
46
47
  const binary = await executable('opencode');
47
48
  this.starting = new Promise((resolve, reject) => {
48
49
  // Keep the normal OS home and the user's existing OpenCode login.
49
- const child = spawn(binary, ['serve', '--hostname', '127.0.0.1', '--port', '0'], { stdio: ['ignore', 'pipe', 'ignore'] });
50
+ const config = JSON.parse(process.env.OPENCODE_CONFIG_CONTENT || '{}');
51
+ const permission = typeof config.permission === 'string' ? { '*': config.permission } : config.permission;
52
+ const env = { ...process.env, OPENCODE_CONFIG_CONTENT: JSON.stringify({
53
+ ...config, permission: { ...permission, external_directory: 'deny' }
54
+ }) };
55
+ const child = spawn(binary, ['serve', '--hostname', '127.0.0.1', '--port', '0'], { stdio: ['ignore', 'pipe', 'ignore'], env });
50
56
  this.child = child;
51
57
  const timer = setTimeout(() => { child.kill(); reject(new SourceError('timeout', 'OpenCode server startup timed out')); }, 30000);
52
58
  let output = '';
@@ -58,7 +64,7 @@ export class OpenCode {
58
64
  resolve(address);
59
65
  }
60
66
  });
61
- const failed = () => { clearTimeout(timer); this.starting = undefined; this.sessions.clear(); reject(new SourceError('upstream', 'OpenCode server stopped; run opencode serve to check installation')); };
67
+ const failed = () => { clearTimeout(timer); this.starting = undefined; this.sessions.clear(); this.prepared.clear(); reject(new SourceError('upstream', 'OpenCode server stopped; run opencode serve to check installation')); };
62
68
  child.once('error', failed);
63
69
  child.once('exit', failed);
64
70
  });
@@ -72,28 +78,111 @@ export class OpenCode {
72
78
  const key = (history) => createHash('sha256').update(JSON.stringify([cwd, history])).digest('hex');
73
79
  const prior = this.sessions.get(key(turns)) ?? (turns.length > 1 ? this.sessions.get(key(turns.slice(0, -1))) : undefined);
74
80
  const continuation = prior && !this.busy.has(prior) ? prior : undefined;
75
- const signal = AbortSignal.any([caller, this.shutdown.signal, AbortSignal.timeout(this.options.timeout ?? 90000)]);
81
+ const signal = AbortSignal.any([caller, this.shutdown.signal, ...(this.options.timeout ? [AbortSignal.timeout(this.options.timeout)] : [])]);
76
82
  let session, base;
83
+ const events = new AbortController();
84
+ let reader;
85
+ let watching;
86
+ let guardFailed = false;
87
+ const turnSignal = AbortSignal.any([signal, events.signal]);
77
88
  const headers = { 'Content-Type': 'application/json', 'x-opencode-directory': cwd,
78
89
  ...(process.env.OPENCODE_SERVER_PASSWORD ? { Authorization: `Basic ${Buffer.from(`${process.env.OPENCODE_SERVER_USERNAME ?? 'opencode'}:${process.env.OPENCODE_SERVER_PASSWORD}`).toString('base64')}` } : {}) };
79
- const call = async (path, body) => {
80
- const res = await this.fetcher(`${base}${path}`, { method: 'POST', headers, redirect: 'error', signal, body: JSON.stringify(body) });
90
+ const check = (res) => {
81
91
  if (!res.ok) {
82
92
  const header = res.headers.get('Retry-After');
83
93
  const seconds = header === null ? NaN : /^\d+(?:\.\d+)?$/.test(header) ? Number(header) : (Date.parse(header) - Date.now()) / 1000;
84
94
  throw new SourceError(res.status === 403 ? 'refused' : res.status === 401 ? 'logged_out' : res.status === 429 ? 'quota' : 'upstream', `OpenCode returned HTTP ${res.status}`, Number.isFinite(seconds) ? Math.max(1, seconds) : undefined);
85
95
  }
96
+ };
97
+ const call = async (path, body) => {
98
+ const res = await this.fetcher(`${base}${path}`, { method: 'POST', headers, redirect: 'error', signal: turnSignal, body: JSON.stringify(body) });
99
+ check(res);
86
100
  return await res.json();
87
101
  };
88
102
  try {
89
103
  base = await this.server();
90
104
  signal.throwIfAborted();
105
+ if (!this.options.url) {
106
+ // Personal MCP catalogs can fill the model context before a task starts.
107
+ // Disconnect them only in our own worker instance, once per directory.
108
+ // OpenCode's coding tools, saved login and config files stay available.
109
+ let prepared = this.prepared.get(cwd);
110
+ if (!prepared) {
111
+ prepared = (async () => {
112
+ const preparationSignal = AbortSignal.any([this.shutdown.signal, AbortSignal.timeout(30000)]);
113
+ const prepare = async (path, method = 'GET') => {
114
+ const response = await this.fetcher(`${base}${path}`, { method, headers, redirect: 'error', signal: preparationSignal });
115
+ check(response);
116
+ return await response.json();
117
+ };
118
+ const peers = await prepare('/mcp');
119
+ if (!peers || typeof peers !== 'object' || Array.isArray(peers))
120
+ throw new SourceError('upstream', 'OpenCode returned invalid MCP status');
121
+ await Promise.all(Object.entries(peers).filter(([, peer]) => peer?.status === 'connected').map(async ([name]) => {
122
+ if (await prepare(`/mcp/${encodeURIComponent(name)}/disconnect`, 'POST') !== true)
123
+ throw new SourceError('upstream', 'OpenCode could not prepare its worker tools');
124
+ }));
125
+ })();
126
+ this.prepared.set(cwd, prepared);
127
+ const pending = prepared;
128
+ void pending.catch(() => { if (this.prepared.get(cwd) === pending)
129
+ this.prepared.delete(cwd); });
130
+ }
131
+ let cancel;
132
+ const cancellation = new Promise((_, reject) => { cancel = () => reject(turnSignal.reason); });
133
+ turnSignal.addEventListener('abort', cancel, { once: true });
134
+ try {
135
+ turnSignal.throwIfAborted();
136
+ await Promise.race([prepared, cancellation]);
137
+ }
138
+ finally {
139
+ turnSignal.removeEventListener('abort', cancel);
140
+ }
141
+ }
91
142
  session = continuation ?? (await call('/session', { title: 'grunt' })).id;
92
143
  if (!session || !/^[a-zA-Z0-9_-]+$/.test(session))
93
144
  throw new SourceError('upstream', 'OpenCode returned an invalid session');
94
145
  this.busy.add(session);
146
+ // OpenCode 1.18.31: subscribe before sending the message so a fast
147
+ // permission request cannot be missed, including on an existing server.
148
+ const stream = await this.fetcher(`${base}/event`, { headers, redirect: 'error', signal: turnSignal });
149
+ check(stream);
150
+ if (!stream.headers.get('content-type')?.includes('text/event-stream') || !stream.body) {
151
+ throw new SourceError('upstream', 'OpenCode permission event stream unavailable');
152
+ }
153
+ reader = stream.body.getReader();
154
+ watching = (async () => {
155
+ const decoder = new TextDecoder();
156
+ let buffer = '';
157
+ while (true) {
158
+ const chunk = await reader.read();
159
+ if (chunk.done)
160
+ throw new SourceError('upstream', 'OpenCode permission event stream closed');
161
+ buffer += decoder.decode(chunk.value, { stream: true });
162
+ let boundary;
163
+ while ((boundary = /\r?\n\r?\n/.exec(buffer))) {
164
+ const frame = buffer.slice(0, boundary.index);
165
+ buffer = buffer.slice(boundary.index + boundary[0].length);
166
+ const data = frame.split(/\r?\n/).filter(line => line.startsWith('data:')).map(line => line.slice(5).trimStart()).join('\n');
167
+ if (!data)
168
+ continue;
169
+ const event = JSON.parse(data);
170
+ if (event.type !== 'permission.asked')
171
+ continue;
172
+ const permission = event.properties;
173
+ if (typeof permission?.sessionID !== 'string')
174
+ throw new SourceError('upstream', 'OpenCode returned an invalid permission request');
175
+ if (permission.sessionID !== session)
176
+ continue;
177
+ if (typeof permission.id !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(permission.id)) {
178
+ throw new SourceError('upstream', 'OpenCode returned an invalid permission request');
179
+ }
180
+ await call(`/permission/${permission.id}/reply`, { reply: 'reject' });
181
+ }
182
+ }
183
+ })().catch(error => { guardFailed = true; throw error; });
95
184
  const modelID = typeof this.options.model === 'function' ? this.options.model() : this.options.model ?? 'big-pickle';
96
- const reply = await call(`/session/${session}/message`, { model: { providerID: 'opencode', modelID }, parts: [{ type: 'text', text: prompt }] });
185
+ const reply = await Promise.race([watching, call(`/session/${session}/message`, { model: { providerID: 'opencode', modelID }, parts: [{ type: 'text', text: prompt }] })]);
97
186
  const parts = reply.parts ?? [];
98
187
  const text = parts.filter(p => p.type === 'text' && typeof p.text === 'string').map(p => p.text).join('\n');
99
188
  if (reply.info?.error) {
@@ -110,9 +199,9 @@ export class OpenCode {
110
199
  return { text };
111
200
  }
112
201
  catch (error) {
202
+ if ((signal.aborted || guardFailed) && session && base)
203
+ await this.fetcher(`${base}/session/${session}/abort`, { method: 'POST', headers, redirect: 'error', signal: AbortSignal.timeout(2000) }).catch(() => { });
113
204
  if (signal.aborted) {
114
- if (session && base)
115
- await this.fetcher(`${base}/session/${session}/abort`, { method: 'POST', headers, redirect: 'error', signal: AbortSignal.timeout(2000) }).catch(() => { });
116
205
  caller.throwIfAborted();
117
206
  if (this.shutdown.signal.aborted)
118
207
  throw new SourceError('cancelled', 'OpenCode request cancelled during shutdown');
@@ -123,6 +212,9 @@ export class OpenCode {
123
212
  throw new SourceError('upstream', 'OpenCode request failed');
124
213
  }
125
214
  finally {
215
+ events.abort();
216
+ await reader?.cancel().catch(() => { });
217
+ await watching?.catch(() => { });
126
218
  if (session)
127
219
  this.busy.delete(session);
128
220
  }
@@ -24,7 +24,7 @@ export class StickyRouter {
24
24
  return (await exec('git', ['-C', cwd, ...args], { timeout: 10000, maxBuffer: 1024 * 1024 })).stdout.trim();
25
25
  }
26
26
  async createTask(request) {
27
- const task = { failures: 0, original: userTurns(request).at(-1) ?? '', output: '', switched: false, busy: false };
27
+ const task = { original: userTurns(request).at(-1) ?? '', output: '', switched: false, busy: false };
28
28
  try {
29
29
  task.checkpoint = await this.git(request.cwd, ['stash', 'create']) || await this.git(request.cwd, ['rev-parse', 'HEAD']);
30
30
  }
@@ -58,7 +58,7 @@ export class StickyRouter {
58
58
  let task = this.tasks.get(key);
59
59
  if (!task) {
60
60
  // Reserve the task before asynchronous checkpoint creation to avoid two bindings.
61
- task = { failures: 0, original: '', output: '', switched: false, busy: true };
61
+ task = { original: '', output: '', switched: false, busy: true };
62
62
  this.tasks.set(key, task);
63
63
  Object.assign(task, await this.createTask({ ...request, cwd }), { busy: true });
64
64
  }
@@ -91,12 +91,10 @@ export class StickyRouter {
91
91
  if (task.source)
92
92
  task.switched = true;
93
93
  task.source = selected.source.id;
94
- task.failures = 0;
95
94
  }
96
95
  try {
97
96
  const input = task.switched ? await this.handoff({ ...request, cwd }, task) : { ...request, cwd };
98
97
  const result = await selected.source.complete(input, signal);
99
- task.failures = 0;
100
98
  task.output = Buffer.from(result.text).subarray(-4096).toString('utf8');
101
99
  task.switched = false;
102
100
  answeredBy.set(result, selected.source.id);
@@ -107,19 +105,16 @@ export class StickyRouter {
107
105
  const failure = error instanceof SourceError ? error : new SourceError('upstream', 'Adapter request failed');
108
106
  if (failure.output)
109
107
  task.output = failure.output;
110
- if (failure.code === 'cancelled' || failure.code === 'refused')
108
+ if (failure.code === 'cancelled')
111
109
  throw failure;
112
110
  let until;
113
111
  if (failure.code === 'quota')
114
112
  until = this.now() + (failure.retryAfter ?? 3600) * 1000;
115
113
  else if (failure.code === 'logged_out' || failure.code === 'not_installed')
116
114
  until = Infinity;
117
- else {
118
- task.failures++;
119
- if (task.failures < 3)
120
- throw failure;
115
+ // Any other failure moves this task to the next source now, so the request still gets an answer.
116
+ else
121
117
  until = this.now() + 15 * 60 * 1000;
122
- }
123
118
  this.bars.set(selected.source.id, until);
124
119
  task.switched = true;
125
120
  }
@@ -15,7 +15,10 @@ import { freeConfig, loopback } from './freellmapi.js';
15
15
  import { proxyApproval } from './approval-proxy.js';
16
16
  const exec = promisify(execFile);
17
17
  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' };
18
+ export const PROVIDERS = { groq: 'https://console.groq.com/keys', cerebras: 'https://cloud.cerebras.ai/platform/api-keys', kilo: 'https://app.kilo.ai/profile' };
19
+ export const KILO_NEMOTRON = 'nvidia/nemotron-3-ultra-550b-a55b:free';
20
+ const savedProviders = ['kilo'];
21
+ const providerModels = { kilo: [KILO_NEMOTRON, 'kilo-auto/free'] };
19
22
  const sameService = (credential, service) => credential.service?.trim().toLowerCase() === service.trim().toLowerCase();
20
23
  function apiKeyField(credential, provider) {
21
24
  return credential.field_names.find(field => {
@@ -104,6 +107,22 @@ export async function setupProviders(squire, router, options) {
104
107
  await router.addGrant(provider, grant);
105
108
  options.notify(`${provider}: connected through Squire grant`);
106
109
  }
110
+ // These sources reuse existing vault access only; missing keys never start signup.
111
+ for (const provider of savedProviders) {
112
+ if (options.providers?.includes(provider))
113
+ continue;
114
+ if (await router.hasKey?.(provider)) {
115
+ options.notify(`${provider}: connected`);
116
+ continue;
117
+ }
118
+ const credential = (await squire.credentials.list()).find(c => sameService(c, provider) && c.auth_strategy !== 'username_password' && apiKeyField(c, provider));
119
+ if (!credential) {
120
+ options.notify(`${provider}: skipped; no saved API access`);
121
+ continue;
122
+ }
123
+ await router.addGrant(provider, await squire.credentials.grant(credential.reference));
124
+ options.notify(`${provider}: connected through Squire grant`);
125
+ }
107
126
  return { pending, dropped };
108
127
  }
109
128
  const object = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
@@ -218,7 +237,7 @@ export class BrowserSquire {
218
237
  const session = this.sessions.get(provider);
219
238
  const result = await this.call('operate_drive', {
220
239
  ...(session ? { session_id: session } : { url }),
221
- 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. 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.`,
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.`,
222
241
  facts: { plan: 'free', project_name: 'grunt' }, max_seconds: 45, max_steps: 60
223
242
  });
224
243
  if (typeof result.session_id === 'string')
@@ -272,7 +291,7 @@ export class BrowserSquire {
272
291
  async close() { for (const handoff of this.handoffs)
273
292
  handoff.close(); await this.client.close(); }
274
293
  }
275
- const providerPath = (provider) => provider === 'groq' ? '/openai/v1' : '/v1';
294
+ const providerPath = (provider) => ({ groq: '/openai/v1', kilo: '/api/gateway' })[provider] ?? '/v1';
276
295
  export class FreeLLMAdmin {
277
296
  token = '';
278
297
  url;
@@ -290,7 +309,13 @@ export class FreeLLMAdmin {
290
309
  if (!key || !key.models?.length)
291
310
  return false;
292
311
  const discovery = await this.call('/keys/custom/discover-models', { keyId: key.id });
293
- return key.models.some(model => discovery.models.some(available => available.id === model.modelId));
312
+ const available = new Set(discovery.models.map(model => model.id));
313
+ const wanted = providerModels[platform]?.filter(id => available.has(id));
314
+ if (wanted) {
315
+ const required = platform === 'kilo' ? wanted : wanted.slice(0, 1);
316
+ return required.length > 0 && required.every(id => key.models.some(model => model.modelId === id));
317
+ }
318
+ return key.models.some(model => available.has(model.modelId));
294
319
  }
295
320
  async addGrant(platform, grant) {
296
321
  // Custom endpoints bind the grant URL and token to their own model rows.
@@ -298,12 +323,13 @@ export class FreeLLMAdmin {
298
323
  const label = `Milo ${platform} (Squire)`;
299
324
  const discovery = await this.call('/keys/custom/discover-models', { baseUrl, apiKey: grant.token });
300
325
  const available = new Set(discovery.models.map(model => model.id));
301
- const model = ['openai/gpt-oss-120b', 'gpt-oss-120b', 'llama-3.3-70b-versatile', 'openai/gpt-oss-20b'].find(id => available.has(id));
302
- if (!model)
326
+ const candidates = providerModels[platform] ?? ['openai/gpt-oss-120b', 'gpt-oss-120b', 'llama-3.3-70b-versatile', 'openai/gpt-oss-20b'];
327
+ const models = platform === 'kilo' ? candidates.filter(id => available.has(id)) : candidates.filter(id => available.has(id)).slice(0, 1);
328
+ if (!models.length)
303
329
  throw new Error(`No supported chat model is currently available from ${platform}`);
304
330
  const previous = await this.call('/keys', undefined, 'GET');
305
331
  await this.call('/keys/custom', { baseUrl, apiKey: grant.token,
306
- label, models: [{ model, supportsTools: true }] });
332
+ label, models: models.map(model => ({ model, supportsTools: true })) });
307
333
  for (const key of previous) {
308
334
  if (Number.isInteger(key.id) && key.platform === 'custom' && key.label === label && key.baseUrl !== baseUrl)
309
335
  await this.call(`/keys/${key.id}`, undefined, 'DELETE');
@@ -320,11 +346,12 @@ export class FreeLLMAdmin {
320
346
  async configureChain(excluded = []) {
321
347
  const chain = await this.call('/fallback', undefined, 'GET');
322
348
  const rows = chain.map(row => {
323
- const provider = Object.keys(PROVIDERS).find(provider => row.keyLabel === `Milo ${provider} (Squire)`);
324
- const fallback = row.modelId === 'freebuff' || row.modelId === 'kilo-auto/free';
349
+ 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');
351
+ const vetted = !provider || !providerModels[provider] || providerModels[provider].includes(row.modelId);
325
352
  return { modelDbId: row.modelDbId,
326
- enabled: fallback || (provider ? row.platform === 'custom' && !excluded.includes(provider) : row.enabled === true),
327
- priority: row.modelId === 'freebuff' ? 1000000 : row.modelId === 'kilo-auto/free' ? 999999 : row.priority };
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 };
328
355
  });
329
356
  await this.call('/fallback', rows, 'PUT');
330
357
  await this.call('/fallback/routing', { strategy: 'priority' }, 'PUT');
@@ -392,7 +419,7 @@ export async function ensureRouter(password, encryption, run = argsWithEnv, recr
392
419
  await run(['volume', 'rm', 'milo-freellmapi-data']);
393
420
  }
394
421
  // Docker copies named variables from env, keeping secrets out of argv.
395
- await run(['run', '-d', '--name', 'milo-freellmapi', '--label', 'io.milo.router=1', ...(process.platform === 'linux' ? ['--network', 'host'] : ['-p', '127.0.0.1:3001:3001']), '--restart', 'unless-stopped', '-v', 'milo-freellmapi-data:/app/server/data', '-e', process.platform === 'linux' ? 'HOST=127.0.0.1' : 'HOST=0.0.0.0', '-e', 'PORT=3001', '-e', 'ENCRYPTION_KEY', '-e', 'FREEAPI_CONFIG_JSON', FREELLMAPI_IMAGE], {
422
+ await run(['run', '-d', '--name', 'milo-freellmapi', '--label', 'io.milo.router=1', ...(process.platform === 'linux' ? ['--network', 'host'] : ['-p', '127.0.0.1:3001:3001']), '--restart', 'unless-stopped', '-v', 'milo-freellmapi-data:/app/server/data', '-e', process.platform === 'linux' ? 'HOST=127.0.0.1' : 'HOST=0.0.0.0', '-e', 'PORT=3001', '-e', 'PROVIDER_TIMEOUT_CUSTOM=600000', '-e', 'ENCRYPTION_KEY', '-e', 'FREEAPI_CONFIG_JSON', FREELLMAPI_IMAGE], {
396
423
  ...process.env, ENCRYPTION_KEY: encryption, FREEAPI_CONFIG_JSON: JSON.stringify({ admin: { email: 'milo@localhost.local', password }, ...freeConfig() })
397
424
  });
398
425
  }
@@ -127,6 +127,17 @@ export async function preflight(run = command) {
127
127
  }
128
128
  const systemdQuote = (value) => '"' + value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%').replaceAll('$', '$$').replaceAll('\n', '\\n') + '"';
129
129
  const xml = (value) => value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
130
+ export async function installedSources(directory = configDir()) {
131
+ try {
132
+ await access(join(directory, 'router-admin.json'));
133
+ }
134
+ catch (error) {
135
+ if (error.code !== 'ENOENT')
136
+ throw error;
137
+ return 'freebuff,opencode';
138
+ }
139
+ return 'freellmapi,kilo,freebuff,opencode';
140
+ }
130
141
  export async function installService() {
131
142
  if (!['linux', 'darwin'].includes(process.platform))
132
143
  throw new Error('grunt background service requires systemd or launchd');
@@ -142,7 +153,9 @@ export async function installService() {
142
153
  const port = process.env.MILO_PORT || '8788';
143
154
  if (!/^\d+$/.test(port) || Number(port) < 1 || Number(port) > 65535)
144
155
  throw new Error('Invalid grunt service port');
145
- const env = { GRUNT_DAEMON: '1', MILO_CONFIG_DIR: directory, MILO_PORT: port, MILO_SOURCES: 'freebuff,opencode', PATH: process.env.PATH || '/usr/local/bin:/usr/bin:/bin' };
156
+ const env = { GRUNT_DAEMON: '1', MILO_CONFIG_DIR: directory, MILO_PORT: port, MILO_SOURCES: await installedSources(directory), PATH: process.env.PATH || '/usr/local/bin:/usr/bin:/bin' };
157
+ if (process.env.MILO_FREELLMAPI_URL)
158
+ env.MILO_FREELLMAPI_URL = process.env.MILO_FREELLMAPI_URL;
146
159
  const opencodeConfig = join(directory, 'opencode-free.json');
147
160
  try {
148
161
  await readFile(opencodeConfig);
@@ -379,6 +392,8 @@ export async function wizard(add, actions = wizardActions) {
379
392
  await step('Connecting Trusty Squire', () => actions.connectSquire());
380
393
  if (add) {
381
394
  await step('FreeLLMAPI and provider grants', () => actions.setup(line => log.info(line), [add]));
395
+ await step('Starting the grunt background service', actions.installService);
396
+ await step('Waiting for grunt to answer', () => actions.checkService(Number(process.env.MILO_PORT || '8788')));
382
397
  outro(`${add} connected`);
383
398
  return;
384
399
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "usegrunt",
3
- "version": "0.6.0",
3
+ "version": "0.6.1",
4
4
  "type": "module",
5
5
  "engines": {
6
6
  "node": ">=22"