usegrunt 0.0.0-stage → 0.5.0
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 +463 -2
- package/dist/agent.js +292 -0
- package/dist/chat.html +39 -0
- package/dist/config.js +29 -0
- package/dist/dots-events.js +141 -0
- package/dist/dots-oauth.js +179 -0
- package/dist/dots-relay.js +143 -0
- package/dist/dots-store.js +70 -0
- package/dist/index.js +64 -0
- package/dist/local/api.js +196 -0
- package/dist/local/approval-proxy.js +71 -0
- package/dist/local/codex.js +115 -0
- package/dist/local/dots-link.js +110 -0
- package/dist/local/dots.js +87 -0
- package/dist/local/fallback-setup.js +191 -0
- package/dist/local/fixtures/ownership-mux.js +42 -0
- package/dist/local/freebuff.js +300 -0
- package/dist/local/freellmapi.js +77 -0
- package/dist/local/harness.js +25 -0
- package/dist/local/main.js +107 -0
- package/dist/local/multiplexer.js +62 -0
- package/dist/local/native-router.js +56 -0
- package/dist/local/opencode.js +143 -0
- package/dist/local/registry.js +81 -0
- package/dist/local/routing.js +138 -0
- package/dist/local/setup.js +523 -0
- package/dist/local/source.js +105 -0
- package/dist/local/wizard.js +258 -0
- package/dist/openrouter.js +15 -0
- package/dist/registry/adapters.json +10 -0
- package/dist/registry-routes.js +25 -0
- package/dist/registry.js +54 -0
- package/dist/router.js +37 -0
- package/dist/server.js +30 -0
- package/dist/store.js +56 -0
- package/dist/types.js +1 -0
- package/package.json +50 -4
package/README.md
CHANGED
|
@@ -1,3 +1,464 @@
|
|
|
1
|
-
#
|
|
1
|
+
# grunt
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Get started with `npx usegrunt setup`. Website: https://grunt.run.
|
|
4
|
+
|
|
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.
|
|
8
|
+
|
|
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
|
+
Freebuff acts as a delegate: it runs its own tools and can edit files in the
|
|
143
|
+
working directory. Your harness receives final text; its own tool loop does not
|
|
144
|
+
run for that turn. grunt extracts cwd from harness context (including environment
|
|
145
|
+
blocks), accepts an explicit absolute `cwd`, and otherwise uses the daemon's
|
|
146
|
+
working directory. It logs the chosen directory. Check it before asking for edits.
|
|
147
|
+
Text and function-tool turns are translated across APIs. Native Responses tools
|
|
148
|
+
are accepted by the app delegate; the Chat Completions gateway cannot forward
|
|
149
|
+
those tools and fails over to the app source. Unsupported media blocks return an
|
|
150
|
+
error rather than silently losing context.
|
|
151
|
+
|
|
152
|
+
### Free API and account setup
|
|
153
|
+
|
|
154
|
+
`npx usegrunt` (or `npx usegrunt setup`) starts the terminal wizard. It installs
|
|
155
|
+
and connects the local Trusty Squire broker; one Google sign-in establishes the
|
|
156
|
+
browser session used for free-service signups. Setup reads the adapter registry,
|
|
157
|
+
installs Freebuff and OpenCode, checks sign-in, installs the grunt background
|
|
158
|
+
service, and adds the **grunt** provider to Pi at `http://127.0.0.1:8788/v1`.
|
|
159
|
+
Each adapter gets a verification task and a PASS/FAIL line. Incomplete setup
|
|
160
|
+
exits unsuccessfully with a repair step; rerun it to resume. Run `pi`, open
|
|
161
|
+
`/model`, and choose **grunt**. For a foreground daemon, run `usegrunt serve`.
|
|
162
|
+
|
|
163
|
+
Freebuff pairs its CLI through Squire's browser. Setup installs tmux when
|
|
164
|
+
needed. OpenCode first tries its free model without an account and requests
|
|
165
|
+
sign-in only if that model requires it. Captcha, passkey and email verification
|
|
166
|
+
show a browser handoff and wait for the user to resume. Existing accounts are
|
|
167
|
+
reused; no extra Google accounts are created.
|
|
168
|
+
|
|
169
|
+
Before making changes, setup checks Node, npm, Pi, tar and the user service
|
|
170
|
+
manager. A missing prerequisite prints its install or repair step and stops.
|
|
171
|
+
|
|
172
|
+
Existing vault API keys are reused. Missing keys are created through Squire's
|
|
173
|
+
browser and captured directly into its vault. Human verification opens a browser
|
|
174
|
+
handoff, including email confirmation, and signup resumes in that same session.
|
|
175
|
+
Provider refusals stop setup. grunt calls `grant_app_access` and sends only
|
|
176
|
+
the grant's base URL and bearer token to FreeLLMAPI's custom-provider endpoint.
|
|
177
|
+
Provider keys stay in Squire; no provider reveal approval is requested. Groq
|
|
178
|
+
uses its `/openai/v1` API path beneath the Squire grant root. Setup discovers
|
|
179
|
+
currently available chat models through that grant before registering one.
|
|
180
|
+
`usegrunt add groq` or `usegrunt add cerebras` connects another provider through the same flow.
|
|
181
|
+
|
|
182
|
+
When no Squire session exists, the wizard runs Squire's own connect installer
|
|
183
|
+
with the OpenCode target. Squire manages login and its broker service. An existing
|
|
184
|
+
session with an unavailable broker reports the connection error for repair.
|
|
185
|
+
Setup does not pair with Beeline or create agents or Rooms.
|
|
186
|
+
|
|
187
|
+
grunt state lives under `$MILO_CONFIG_DIR`, otherwise `$XDG_CONFIG_HOME/milo` or
|
|
188
|
+
`~/.config/milo`. Keep this directory across service restarts. Local router login
|
|
189
|
+
and encryption material are generated once and stored with mode `0600`.
|
|
190
|
+
FreeLLMAPI encrypts the grant tokens in its backend database. Neither tokens nor
|
|
191
|
+
provider keys appear in Pi's config or terminal output. Never share backend state.
|
|
192
|
+
Existing routers with keys are preserved if their local admin state is missing.
|
|
193
|
+
|
|
194
|
+
The service uses FreeLLMAPI first and OpenCode free models as fallback. It loads
|
|
195
|
+
the saved router login itself at startup and retries if the router is temporarily
|
|
196
|
+
unavailable. Setup keeps a runtime outside the npx cache, so cache cleanup does
|
|
197
|
+
not remove the service. Pi's other providers are preserved. `PI_CODING_AGENT_DIR`
|
|
198
|
+
selects a nondefault Pi agent directory.
|
|
199
|
+
|
|
200
|
+
Setup installs the pinned FreeLLMAPI Node server as a separate background service;
|
|
201
|
+
Docker is not required. Linux uses systemd user units; macOS uses launchd
|
|
202
|
+
(macOS remains untested). The router data and private login live under grunt's
|
|
203
|
+
config directory. `MILO_FREELLMAPI_URL` chooses its numeric loopback address and
|
|
204
|
+
is saved in grunt's service configuration. The router's database is created under
|
|
205
|
+
umask `0077`. `MILO_ROUTER_RUNTIME=docker` retains the older Docker installer for
|
|
206
|
+
existing installations and offline regression checks.
|
|
207
|
+
|
|
208
|
+
`MILO_SQUIRE_HOME` and `MILO_SQUIRE_XDG_CONFIG_HOME` select an existing Squire
|
|
209
|
+
home without relocating grunt state. `MILO_SETUP_NO_HUMAN=1` stops before Squire
|
|
210
|
+
onboarding or browser handoff if human verification would be needed.
|
|
211
|
+
|
|
212
|
+
The package is `usegrunt` (version `0.5.0`); the installed command is `usegrunt`.
|
|
213
|
+
This change prepares the package for publication after merge; it does not publish.
|
|
214
|
+
|
|
215
|
+
Explicit legacy FreeLLMAPI installations send calls to `http://127.0.0.1:3001/v1`, including
|
|
216
|
+
provider failover. There is no direct OpenRouter free API route. An already
|
|
217
|
+
configured install can provide `MILO_FREELLMAPI_KEY` in its process environment;
|
|
218
|
+
`MILO_FREELLMAPI_URL` accepts numeric HTTP loopback addresses only. The completion
|
|
219
|
+
cap is (4096) tokens. Select `freellmapi` for the free chain or `kilo` for the
|
|
220
|
+
anonymous `kilo-auto/free` model through that same router. Kilo needs no account.
|
|
221
|
+
The separate Freebuff bridge listens only on `127.0.0.1:8789` and contains only
|
|
222
|
+
the Freebuff source, preventing a routing loop. FreeLLMAPI supports priority
|
|
223
|
+
ordering: keyed providers come first, Kilo next, Freebuff last. Setup enables
|
|
224
|
+
only those providers in the chain, excluding Google, OpenRouter and unvetted
|
|
225
|
+
aggregators.
|
|
226
|
+
|
|
227
|
+
FreeLLMAPI's signed catalog handles model and quota updates. Free installations
|
|
228
|
+
receive its delayed monthly snapshot; live catalog access is a separate upstream
|
|
229
|
+
premium option. Check the local dashboard when provider availability changes.
|
|
230
|
+
FreeLLMAPI is single-user software for personal experimentation; keep it bound
|
|
231
|
+
to loopback. See its [installation guide](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/install/01-install.md).
|
|
232
|
+
|
|
233
|
+
### OpenCode app driver
|
|
234
|
+
|
|
235
|
+
Select `opencode` as the grunt model. grunt starts `opencode serve` on a loopback
|
|
236
|
+
port, using your normal OS home and existing OpenCode login. It sends only the
|
|
237
|
+
latest user message, word for word, through the session API, with no caller
|
|
238
|
+
system prompt or tool definitions. Follow-ups with their user-message history
|
|
239
|
+
reuse the same session; the mapping lasts until grunt exits. OpenCode runs its
|
|
240
|
+
own tools and returns final text, as Freebuff does. It uses no tmux.
|
|
241
|
+
|
|
242
|
+
`MILO_OPENCODE_MODEL` selects the OpenCode free model (default `big-pickle`).
|
|
243
|
+
Use a currently free model from your OpenCode catalog; grunt does not buy credits
|
|
244
|
+
or switch to paid models. `MILO_OPENCODE_URL` optionally connects an existing
|
|
245
|
+
numeric loopback server. If it uses HTTP Basic auth, set
|
|
246
|
+
`OPENCODE_SERVER_USERNAME` and `OPENCODE_SERVER_PASSWORD` in grunt's environment.
|
|
247
|
+
Avoid configuring that OpenCode server to call grunt, which would create a loop.
|
|
248
|
+
See the [server API](https://opencode.ai/v1/docs/server/).
|
|
249
|
+
|
|
250
|
+
[OpenCode's free models](https://opencode.ai/docs/zen) may be free only for a
|
|
251
|
+
limited time, and some retain prompts for training. [Kilo Auto Free](https://kilo.ai/docs/getting-started/using-kilo-for-free)
|
|
252
|
+
may route to providers that log prompts and outputs and use them to improve
|
|
253
|
+
their services. Do not send confidential data through these free routes.
|
|
254
|
+
|
|
255
|
+
### opencode
|
|
256
|
+
|
|
257
|
+
For opencode 1.18.31, save this as `opencode.json` in your project:
|
|
258
|
+
|
|
259
|
+
```json
|
|
260
|
+
{
|
|
261
|
+
"$schema": "https://opencode.ai/config.json",
|
|
262
|
+
"model": "milo/milo",
|
|
263
|
+
"provider": {
|
|
264
|
+
"milo": {
|
|
265
|
+
"name": "grunt",
|
|
266
|
+
"npm": "@ai-sdk/openai-compatible",
|
|
267
|
+
"options": { "baseURL": "http://127.0.0.1:8788/v1", "apiKey": "local" },
|
|
268
|
+
"models": { "milo": { "name": "grunt" } }
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
}
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
Then run `opencode -m milo/milo`. The [provider docs for this config format](https://docs.dev.opencode.ai/docs/providers/)
|
|
275
|
+
use `provider`, `npm`, and `options`. Newer native configs in the
|
|
276
|
+
[current docs](https://opencode.ai/docs/providers/) use `providers`,
|
|
277
|
+
`package: "@opencode/ai/providers/openai-compatible"`, and `settings` instead.
|
|
278
|
+
|
|
279
|
+
### pi
|
|
280
|
+
|
|
281
|
+
Add this provider to `~/.pi/agent/models.json` (tested with pi 0.99.1):
|
|
282
|
+
|
|
283
|
+
```json
|
|
284
|
+
{
|
|
285
|
+
"providers": {
|
|
286
|
+
"milo": {
|
|
287
|
+
"baseUrl": "http://127.0.0.1:8788/v1",
|
|
288
|
+
"api": "openai-completions",
|
|
289
|
+
"apiKey": "local",
|
|
290
|
+
"models": [{
|
|
291
|
+
"id": "milo", "name": "grunt", "reasoning": false, "input": ["text"],
|
|
292
|
+
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
|
|
293
|
+
"contextWindow": 128000, "maxTokens": 8192
|
|
294
|
+
}]
|
|
295
|
+
}
|
|
296
|
+
}
|
|
297
|
+
}
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
Run `pi --provider milo --model milo`. See [pi's model configuration](https://pi.dev/docs/latest/models-configuration).
|
|
301
|
+
|
|
302
|
+
### Claude Code
|
|
303
|
+
|
|
304
|
+
Claude Code 2.1.319 uses the Anthropic endpoint:
|
|
305
|
+
|
|
306
|
+
```sh
|
|
307
|
+
ANTHROPIC_BASE_URL=http://127.0.0.1:8788 \
|
|
308
|
+
ANTHROPIC_AUTH_TOKEN=local \
|
|
309
|
+
claude --model milo
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
See [Claude Code gateway configuration](https://code.claude.com/docs/en/llm-gateway).
|
|
313
|
+
The placeholder token satisfies the client; the loopback daemon does not require
|
|
314
|
+
a provider credential. Custom model metadata may produce a context-window warning.
|
|
315
|
+
|
|
316
|
+
### Codex
|
|
317
|
+
|
|
318
|
+
Add to your user `config.toml` (Responses API; tested with Codex 0.167.0):
|
|
319
|
+
|
|
320
|
+
```toml
|
|
321
|
+
model = "milo"
|
|
322
|
+
model_provider = "milo"
|
|
323
|
+
|
|
324
|
+
[model_providers.milo]
|
|
325
|
+
name = "grunt"
|
|
326
|
+
base_url = "http://127.0.0.1:8788/v1"
|
|
327
|
+
wire_api = "responses"
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
Run `codex`. See the [official configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference).
|
|
331
|
+
|
|
332
|
+
### Codex source
|
|
333
|
+
|
|
334
|
+
Codex is opt-in. With the official `codex` CLI already signed in using ChatGPT,
|
|
335
|
+
set `MILO_SOURCES=codex,freellmapi,opencode,kilo` to enable it first. Enabling it
|
|
336
|
+
spends your Codex plan allowance, including the weekly limit. Without
|
|
337
|
+
`MILO_SOURCES`, grunt uses only Freebuff and OpenCode and never launches Codex.
|
|
338
|
+
With Codex enabled, select model `codex` to use only Codex.
|
|
339
|
+
API-key logins do not enable this source. Missing or signed-out Codex is omitted
|
|
340
|
+
from `/v1/models`; grunt continues through the free chain on usage limits.
|
|
341
|
+
|
|
342
|
+
grunt spawns `codex exec --json --sandbox workspace-write` in the request's working
|
|
343
|
+
directory. Codex can use its tools and edit files there. grunt never reads or
|
|
344
|
+
copies Codex login files, changes its config, or signs you in. Set
|
|
345
|
+
`MILO_CODEX_MODEL` to override your Codex default. Only the latest user text is
|
|
346
|
+
sent; follow-ups resume the saved thread, keyed by working directory and user
|
|
347
|
+
history. Session mappings last until grunt exits. Avoid pointing the delegated
|
|
348
|
+
Codex default back at grunt, which would create a routing loop.
|
|
349
|
+
|
|
350
|
+
### Sources and app sessions
|
|
351
|
+
|
|
352
|
+
The launch registry contains Freebuff and OpenCode with equal selection
|
|
353
|
+
probability after renormalization. Both adapters currently support text only.
|
|
354
|
+
Pi remains the harness. Each new user turn starts a task keyed by the canonical
|
|
355
|
+
working directory and user history. Tool results and retries keep the same
|
|
356
|
+
adapter. No usage counters switch it ahead of quota exhaustion.
|
|
357
|
+
|
|
358
|
+
A quota error switches immediately and bars that adapter until Retry-After,
|
|
359
|
+
or one hour. Three consecutive upstream failures or timeouts in a task bar it
|
|
360
|
+
for fifteen minutes. A missing installation or expired login bars it until a
|
|
361
|
+
successful health check. Cancellation and provider refusal do not switch.
|
|
362
|
+
When no eligible adapter remains, the API returns HTTP 429 and, when known,
|
|
363
|
+
the earliest Retry-After. Agent adapters return final text, so streaming headers
|
|
364
|
+
are sent after completion; quota failures retain their HTTP status.
|
|
365
|
+
|
|
366
|
+
On handoff, the next adapter receives the original task, working-tree status,
|
|
367
|
+
the diff against a task-start `git stash create` checkpoint, the previous
|
|
368
|
+
adapter's last four KB of output, and an instruction to continue without
|
|
369
|
+
restarting. The checkpoint creates no branch commit or stash entry. Outside a
|
|
370
|
+
git repository, only task text and output are sent.
|
|
371
|
+
|
|
372
|
+
The owner curates `registry/adapters.json`. The **Publish adapter registry**
|
|
373
|
+
workflow accepts manual dispatch only by `lunchboxfortwo` on `main`, validates
|
|
374
|
+
the registry, uploads it atomically to the Fly gateway volume, and checks
|
|
375
|
+
`GET /v1/registry`. Ordinary code deployments do not publish registry edits.
|
|
376
|
+
Before the first dispatch the endpoint returns HTTP 503. Published data
|
|
377
|
+
survives deploys and has an ETag. Stable weights total (0.8) and experimental
|
|
378
|
+
weights total (0.2) when both tiers are present. Unknown adapter identifiers
|
|
379
|
+
are ignored locally and cannot install new code.
|
|
380
|
+
|
|
381
|
+
The daemon synchronizes on startup and every twenty-four hours with
|
|
382
|
+
If-None-Match. It writes the valid registry and ETag atomically in a private
|
|
383
|
+
`registry.json` in its existing config directory. A gateway or cache failure
|
|
384
|
+
keeps the last good list, falling back to the packaged list on a fresh install.
|
|
385
|
+
Known adapters are installed and checked during sync; removing a registry entry
|
|
386
|
+
disables it without uninstalling its files. The legacy `MILO_CONFIG_DIR` and
|
|
387
|
+
`MILO_PORT` settings remain supported. `GRUNT_REGISTRY_URL` overrides the sync
|
|
388
|
+
endpoint for local development.
|
|
389
|
+
|
|
390
|
+
Explicit `MILO_SOURCES` configurations containing legacy sources such as Dots,
|
|
391
|
+
Codex or FreeLLMAPI retain their existing ordered behavior. They are outside the
|
|
392
|
+
launch registry. Codex still requires explicit opt-in. The Fly personal-agent
|
|
393
|
+
API remains separate from this local daemon.
|
|
394
|
+
|
|
395
|
+
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.
|
|
396
|
+
|
|
397
|
+
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
|
|
398
|
+
per canonical working directory; `MILO_APP_POOL` defaults to (2) active sessions
|
|
399
|
+
per directory. New-chat creation and association are serialized per shared on-disk project
|
|
400
|
+
directory, including different working folders with the same basename. Once a
|
|
401
|
+
chat is associated with its originating process, its response runs concurrently
|
|
402
|
+
with other associated turns; replies and startup logs are read only from that chat. SIGINT/SIGTERM
|
|
403
|
+
cancel work and close only grunt's own sessions and server on its private tmux socket.
|
|
404
|
+
The private server stays alive between turns so ending the last session cannot
|
|
405
|
+
race with launching the next; daemon shutdown waits for launches and closes it explicitly.
|
|
406
|
+
`MILO_APP_TIMEOUT_MS` defaults to (600000), including queue time. More sessions
|
|
407
|
+
consume your account's free hours faster. Freebuff automation may conflict with
|
|
408
|
+
its terms; using your account this way is your choice.
|
|
409
|
+
|
|
410
|
+
Errors carry `not_installed`, `logged_out`, `quota`, `timeout`, `refused`, or `upstream` in
|
|
411
|
+
the harness's error envelope. Missing executables are detected immediately.
|
|
412
|
+
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.
|
|
413
|
+
|
|
414
|
+
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.
|
|
415
|
+
Unrecognized startup failures return a clear upstream error; they do not wait
|
|
416
|
+
for the full model-turn timeout. Stable malformed chat data returns an explicit format error.
|
|
417
|
+
Authentication, quota, missing-app and upstream availability failures can try the
|
|
418
|
+
next configured source. Timeouts stop instead of replaying potentially unfinished
|
|
419
|
+
filesystem work. Use `MILO_SOURCES=freebuff` to keep requests on the app path.
|
|
420
|
+
|
|
421
|
+
The source interface is in `src/local/source.ts`; `Multiplexer` is in
|
|
422
|
+
`src/local/multiplexer.ts`. Register another app in local configuration without
|
|
423
|
+
changing API handlers. Offline tests replay recorded harness request shapes and
|
|
424
|
+
run a fake Freebuff TUI through real tmux; they require tmux but no credentials.
|
|
425
|
+
|
|
426
|
+
To demonstrate the built daemon offline, run `pnpm build && node src/local/proof.mjs`.
|
|
427
|
+
It starts the real local entry point with a temporary fake Freebuff on PATH,
|
|
428
|
+
exercises all three APIs with and without SSE, and removes its temporary chats.
|
|
429
|
+
|
|
430
|
+
To replay chat-ownership races through the built HTTP API, run
|
|
431
|
+
`pnpm build && node src/local/ownership-proof.mjs`. This uses a filesystem-writing
|
|
432
|
+
multiplexer that delays send completion until both processes have persisted their
|
|
433
|
+
chat. It verifies exact cwd/chat ownership, follow-up continuation, and a quota-only
|
|
434
|
+
startup log alongside a successful request from another folder named `project`.
|
|
435
|
+
|
|
436
|
+
### Dots through the grunt connector (optional)
|
|
437
|
+
|
|
438
|
+
With grunt running on your computer, tell your dot:
|
|
439
|
+
|
|
440
|
+
> Join grunt: api.grunt.run/join
|
|
441
|
+
|
|
442
|
+
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`.
|
|
443
|
+
|
|
444
|
+
Dots is off by default. Start grunt with an explicit source order that includes it:
|
|
445
|
+
|
|
446
|
+
```sh
|
|
447
|
+
MILO_SOURCES=dots,freellmapi,opencode,kilo usegrunt serve
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
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.
|
|
451
|
+
|
|
452
|
+
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.
|
|
453
|
+
|
|
454
|
+
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.
|
|
455
|
+
|
|
456
|
+
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.
|
|
457
|
+
|
|
458
|
+
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.
|
|
459
|
+
|
|
460
|
+
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.
|
|
461
|
+
|
|
462
|
+
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.
|
|
463
|
+
|
|
464
|
+
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).
|