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 +16 -511
- package/dist/local/fixtures/opencode-events.js +4 -0
- package/dist/local/harnesses.js +1 -1
- package/dist/local/native-router.js +1 -0
- package/dist/local/opencode.js +100 -8
- package/dist/local/routing.js +5 -10
- package/dist/local/setup.js +39 -12
- package/dist/local/wizard.js +16 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,522 +1,27 @@
|
|
|
1
|
-
|
|
1
|
+
<h1 align="center">grunt</h1>
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
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
|
-
|
|
10
|
-
|
|
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
|
-
|
|
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
|
|
17
|
+
https://grunt.run. `milo` and `milo-local` remain aliases.
|
|
513
18
|
|
|
514
|
-
|
|
19
|
+
Setup is Trusty Squire, the free-service list, sign-in, then your coding tools.
|
|
515
20
|
|
|
516
|
-
|
|
21
|
+
[Reference](https://github.com/bananaman614305/milo/blob/main/docs/reference.md).
|
|
517
22
|
|
|
518
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
package/dist/local/harnesses.js
CHANGED
|
@@ -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
|
|
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
|
}
|
package/dist/local/opencode.js
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
}
|
package/dist/local/routing.js
CHANGED
|
@@ -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 = {
|
|
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 = {
|
|
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'
|
|
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
|
-
|
|
118
|
-
|
|
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
|
}
|
package/dist/local/setup.js
CHANGED
|
@@ -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) =>
|
|
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
|
-
|
|
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
|
|
302
|
-
|
|
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:
|
|
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
|
}
|
package/dist/local/wizard.js
CHANGED
|
@@ -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('&', '&').replaceAll('<', '<').replaceAll('>', '>').replaceAll('"', '"');
|
|
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:
|
|
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
|
}
|