usegrunt 0.5.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,464 +1,27 @@
1
- # grunt
1
+ <h1 align="center">grunt</h1>
2
2
 
3
- Get started with `npx usegrunt setup`. Website: https://grunt.run.
3
+ <p align="center">
4
+ <a href="https://www.npmjs.com/package/usegrunt"><img alt="npm version" src="https://img.shields.io/npm/v/usegrunt"></a>
5
+ <a href="https://www.npmjs.com/package/usegrunt"><img alt="node" src="https://img.shields.io/node/v/usegrunt"></a>
6
+ <a href="https://www.npmjs.com/package/usegrunt"><img alt="downloads" src="https://img.shields.io/npm/dm/usegrunt"></a>
7
+ </p>
4
8
 
5
- Compatibility: the `milo` and `milo-local` commands remain aliases for this release.
6
- Existing `MILO_*` variables, `milo` model/provider IDs, config paths, MCP names,
7
- and infrastructure names remain supported.
9
+ <p align="center"><strong>Free AI inference, pooled on your machine.</strong></p>
8
10
 
9
- Chat with grunt. Hand it a bigger job, keep talking while it works, and get the
10
- result back in the same conversation.
11
-
12
- One Node process, one SQLite file, a front agent, and a small background pool.
13
- There are no accounts: paste your OpenRouter key at `/chat`. Jobs spend your
14
- OpenRouter credits. The key is saved in your browser; use a trusted device.
15
-
16
- ## Run
17
-
18
- Requires Node 22 and pnpm.
19
-
20
- ```sh
21
- pnpm install --frozen-lockfile
22
- pnpm build
23
- MILO_DB=file:./milo.db pnpm start
24
- ```
25
-
26
- Open http://localhost:8787/chat. `pnpm dev` runs the TypeScript source.
27
- `pnpm lint` checks ESLint and TypeScript; `pnpm test` runs the offline suite.
28
-
29
- Environment:
30
-
31
- | Variable | Default | Purpose |
32
- | --- | --- | --- |
33
- | `PORT` | `8787` | HTTP port |
34
- | `MILO_DB` | `file:/data/milo.db` | Local SQLite file |
35
- | `MILO_CONFIG` | unset | Optional JSON file with `agent.whitelist` |
36
-
37
- ## Behavior
38
-
39
- grunt answers quick questions and uses `dispatch`, `status`, `cancel`, and
40
- `remember` for longer work and durable preferences. Each message uses one front
41
- model turn, with a retry on a second model only for transient failure. A worker
42
- receives a self-contained brief and saved notes, never the raw conversation.
43
- Workers have no tools or live web access. There are at most three active workers,
44
- with at most two per person. Jobs are capped at 4,096 output tokens; front replies
45
- at 1,024. Cancel aborts a request. Queued or running jobs fail after a restart.
46
-
47
- On completion or failure, grunt makes a front-model call for a short proactive
48
- update. The full result lives on the job. If that summary call fails, a plain
49
- grunt update still tells you the job's outcome. SSE streams carry assistant
50
- messages and job status changes, with keepalives every fifteen seconds.
51
-
52
- The whitelist defaults to DeepSeek v4.1 Flash, GLM 5.3 Flash, GLM 5.3, GPT 5.6
53
- Luna and Claude Opus 5. The front prefers DeepSeek Flash, then GLM Flash. No
54
- `google/` model is permitted, even if configured. Model access and credits must
55
- be available on your OpenRouter key; there is no substitute outside the whitelist.
56
-
57
- `pick()` filters context size, whitelist membership and recent rate limits,
58
- then scores `reliability × quality − a × latency − b × expected token cost`.
59
- Chat weights favor speed; code, research and writing favor quality. Price and
60
- quality estimates start as explicit priors; reliability and latency learn from
61
- call history. After a 429, 5xx or timeout, a worker retries once on the next model.
62
- A 429 excludes that model for sixty seconds. Jobs show the chosen model and reason.
63
-
64
- To override priors, set `MILO_CONFIG` to a JSON file shaped like:
65
-
66
- ```json
67
- {
68
- "agent": {
69
- "whitelist": [{
70
- "model": "deepseek/deepseek-v4.1-flash",
71
- "quality": { "chat": 0.85, "code": 0.85, "research": 0.85, "writing": 0.85 },
72
- "inputUsdPerM": 0.14, "outputUsdPerM": 0.28,
73
- "contextLength": 128000, "reliability": 0.98, "latencyMs": 1500
74
- }]
75
- }
76
- }
77
- ```
78
-
79
- Priors are estimates, not a live pricing feed. Use the provider's current prices
80
- when configuring cost weights.
81
-
82
- ## API
83
-
84
- All `/agent/*` routes require `Authorization: Bearer <OpenRouter key>`.
85
- The person's identity is the SHA-256 of the key. The server retains the raw key
86
- only for active chat requests and unfinished jobs; it never stores or logs it.
87
- Chat content, briefs, results and notes persist locally in SQLite.
88
-
89
- | Method | Route | Result |
90
- | --- | --- | --- |
91
- | GET | `/` | Redirect to `/chat` |
92
- | GET | `/chat` | Chat page |
93
- | GET | `/health` | Health status |
94
- | POST | `/agent/messages` | `{text}` → `{reply, dispatched}` |
95
- | GET | `/agent/state` | Recent messages, jobs and notes |
96
- | GET | `/agent/events` | Authenticated fetch-streaming SSE: `message`, `task` |
97
- | POST | `/agent/tasks/:id/cancel` | Cancel a job belonging to the caller |
98
-
99
- ## Offline demonstration
100
-
101
- ```sh
102
- pnpm build
103
- MILO_DB=file:/tmp/milo-proof.db PORT=8788 node --import ./proof/fake.mjs dist/server.js
104
- ```
105
-
106
- Open `/chat` on that port and enter any synthetic key. Send “hello”, “remember I
107
- write TypeScript; keep answers short”, “write a one-page launch plan”, then “what
108
- is the capital of France?”. The job stays running while Paris appears. Release
109
- it with `curl -X POST http://127.0.0.1:18789/release`; grunt proactively posts its
110
- summary and attaches the full plan. This adapter never calls OpenRouter.
111
-
112
- ## Deploy
113
-
114
- The Docker image contains only the compiled app, page and production dependencies.
115
- On pushes to main, GitHub builds and smoke-tests the exact image, then deploys
116
- it to Fly app `milo-gateway` in `iad` using the existing `FLY_API_TOKEN` secret.
117
- The `milo_data` volume mounts at `/data`. Keep a single Fly machine for SQLite.
118
-
119
- This replaces the former OpenAI-compatible gateway. The old `/v1/*` routes are
120
- removed. There is no Jev, billing, roster service, worker tooling or monorepo.
121
-
122
- ## Use grunt as your harness's model
123
-
124
- Run the separate local daemon on your own machine (Node 22+, Linux or macOS,
125
- `opencode` on PATH, and `tmux` with an existing logged-in `freebuff` for the last fallback):
126
-
127
- ```sh
128
- pnpm install --frozen-lockfile
129
- pnpm build
130
- node dist/local/main.js setup
131
- # Published package: npx usegrunt setup; installed bin: usegrunt.
132
- # Freebuff alone, without API setup: MILO_SOURCES=freebuff node dist/local/main.js
11
+ ```bash
12
+ npx usegrunt
133
13
  ```
134
14
 
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.
15
+ usegrunt installs grunt on this machine. It pools free AI quota and serves one local agent.
453
16
 
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.
17
+ https://grunt.run. `milo` and `milo-local` remain aliases.
455
18
 
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.
19
+ Setup is Trusty Squire, the free-service list, sign-in, then your coding tools.
457
20
 
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.
21
+ [Reference](https://github.com/bananaman614305/milo/blob/main/docs/reference.md).
459
22
 
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.
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.
461
24
 
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.
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.
463
26
 
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).
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/api.js CHANGED
@@ -1,10 +1,12 @@
1
1
  import { pairDots } from './dots-link.js';
2
2
  import { Hono } from 'hono';
3
3
  import { streamSSE } from 'hono/streaming';
4
- import { randomUUID } from 'node:crypto';
5
- import { isAbsolute } from 'node:path';
4
+ import { createHash, randomUUID } from 'node:crypto';
5
+ import { mkdir } from 'node:fs/promises';
6
+ import { homedir } from 'node:os';
7
+ import { isAbsolute, join } from 'node:path';
6
8
  import { housekeeping, userText } from './harness.js';
7
- import { SourceError } from './source.js';
9
+ import { SourceError, answeredBy } from './source.js';
8
10
  const object = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
9
11
  const array = (v) => Array.isArray(v) ? v : [];
10
12
  function text(v) {
@@ -63,14 +65,16 @@ export function decode(body, api, fallback) {
63
65
  const matches = [...context.matchAll(/(?:<cwd>\s*([^<\n]+)\s*<\/cwd>|(?:Working directory|Current working directory|Primary working directory|cwd):\s*([^\n<]+))/gi)];
64
66
  const absolute = matches.filter(m => isAbsolute((m[1] ?? m[2] ?? '').trim()));
65
67
  const inferred = absolute.find(m => /^Primary working directory:/i.test(m[0])) ?? absolute[0];
66
- const cwd = typeof body.cwd === 'string' ? body.cwd : (inferred?.[1] ?? inferred?.[2])?.trim() ?? fallback;
67
- if (!isAbsolute(cwd))
68
- throw new Error('Working directory must be an absolute path');
68
+ const namedCwd = typeof body.cwd === 'string' ? body.cwd : (inferred?.[1] ?? inferred?.[2])?.trim();
69
69
  const rawTurns = api === 'responses' ? (typeof body.input === 'string' ? [{ role: 'user', content: body.input }] : array(body.input)) : array(body.messages);
70
70
  const userMessages = rawTurns.map(object).filter(m => (m.role === 'user' || (api === 'responses' && !m.role && !m.type))).map(m => typeof m.content === 'string' ? userText(m.content) : array(m.content).map(object).filter(b => b.type === 'text' || b.type === 'input_text').map(b => userText(String(b.text ?? ''))).filter(t => t.length > 0).join('\n')).filter(t => t.length > 0);
71
+ const cwdSource = namedCwd !== undefined ? 'request' : fallback !== undefined ? 'fallback' : 'scratch';
72
+ const cwd = namedCwd ?? fallback ?? join(process.env.XDG_STATE_HOME || join(homedir(), '.local/state'), 'grunt/scratch', createHash('sha256').update(userMessages[0] ?? '').digest('hex').slice(0, 24));
73
+ if (!isAbsolute(cwd))
74
+ throw new Error('Working directory must be an absolute path');
71
75
  const tokens = body.max_tokens ?? body.max_output_tokens ?? body.max_completion_tokens;
72
76
  const imageInput = /"type"\s*:\s*"(?:image|input_image|image_url)"/.test(JSON.stringify(body.input ?? body.messages));
73
- return { model: String(body.model ?? 'milo'), messages, userMessages, tools, cwd, stream: body.stream === true, ...(imageInput ? { imageInput: true } : {}), ...(typeof tokens === 'number' ? { maxTokens: tokens } : {}) };
77
+ return { model: String(body.model ?? 'milo'), messages, userMessages, tools, cwd, cwdSource, stream: body.stream === true, ...(imageInput ? { imageInput: true } : {}), ...(typeof tokens === 'number' ? { maxTokens: tokens } : {}) };
74
78
  }
75
79
  function toolInput(arguments_) {
76
80
  try {
@@ -154,13 +158,13 @@ export function createLocalApp(sources, options = {}) {
154
158
  app.post(`/v1/${path}`, async (c) => {
155
159
  let request;
156
160
  try {
157
- request = decode(object(await c.req.json()), api, options.cwd ?? process.cwd());
161
+ request = decode(object(await c.req.json()), api, options.cwd);
158
162
  }
159
163
  catch (e) {
160
164
  return c.json({ ...(api === 'messages' ? { type: 'error' } : {}), error: { type: 'invalid_request_error', message: e instanceof Error ? e.message : 'Invalid request' } }, 400);
161
165
  }
162
166
  const local = housekeeping(request);
163
- options.log?.(`${request.cwd}; cwd=${request.cwd === (options.cwd ?? process.cwd()) ? 'fallback-or-explicit' : 'request'}; classification=${local === undefined ? 'user' : 'housekeeping'}`);
167
+ options.log?.(`${request.cwd}; cwd=${request.cwdSource}; classification=${local === undefined ? 'user' : 'housekeeping'}`);
164
168
  const complete = (signal) => local === undefined ? sources.complete(request, signal) : Promise.resolve({ text: local });
165
169
  const controller = new AbortController();
166
170
  const abort = () => controller.abort();
@@ -172,7 +176,15 @@ export function createLocalApp(sources, options = {}) {
172
176
  try {
173
177
  // Agent adapters return final text, not incremental tokens. Resolve routing
174
178
  // before committing SSE headers so exhausted routes still return HTTP 429.
175
- const result = encode(await complete(controller.signal), request.model, api);
179
+ if (request.cwdSource === 'scratch')
180
+ await mkdir(request.cwd, { recursive: true });
181
+ const completion = await complete(controller.signal);
182
+ const source = answeredBy.get(completion);
183
+ if (source)
184
+ c.header('X-Grunt-Source', source);
185
+ if (sources.preparing.size)
186
+ c.header('X-Grunt-Preparing', [...sources.preparing].join(','));
187
+ const result = encode(completion, request.model, api);
176
188
  if (request.stream)
177
189
  return streamSSE(c, async (stream) => {
178
190
  stream.onAbort(abort);
@@ -183,6 +195,8 @@ export function createLocalApp(sources, options = {}) {
183
195
  }
184
196
  catch (e) {
185
197
  const { err, body } = failure(e);
198
+ if (sources.preparing.size)
199
+ c.header('X-Grunt-Preparing', [...sources.preparing].join(','));
186
200
  if (err.retryAfter !== undefined)
187
201
  c.header('Retry-After', String(Math.max(1, Math.ceil(err.retryAfter))));
188
202
  return c.json(body, err.code === 'quota' ? 429 : err.code === 'timeout' ? 504 : 503);