chutes-build 1.7.1 → 2.0.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/CHANGELOG.md CHANGED
@@ -4,6 +4,204 @@ All notable changes to Chutes Build will be documented in this file. The format
4
4
  is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
5
5
  project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
+ ## [2.0.0] - 2026-10-22
8
+
9
+ ### Breaking
10
+
11
+ - **Chutes Build is the product all the way down.** Every retained upstream
12
+ crate, module, Rust identifier, environment variable and state path that
13
+ carried an `xai-*`/`grok` name now carries a Chutes name; the upstream
14
+ synchronization model that kept those names is frozen
15
+ (`docs/upstream-sync.md`). Legal attribution is unchanged in `NOTICE` and
16
+ `THIRD-PARTY-NOTICES`.
17
+ - **The local wire speaks Chutes.** ACP method namespace `x.ai/*` ->
18
+ `chutes.ai/*`, request headers `x-grok-*` -> `x-chutes-build-*`, token header
19
+ `X-XAI-Token-Auth` -> `X-Chutes-Token-Auth`, protobuf package
20
+ `xai.grok.tools.v1` -> `chutes.tools.v1`, ACP initialize meta `grokShell` ->
21
+ `chutesShell`. 2.0.0 does not interoperate with 1.7.2 or older peers
22
+ (spec §1.7). A user-configured xAI-compatible endpoint now receives the
23
+ Chutes token header (or bearer alone) rather than the upstream one; xAI-host
24
+ BYOK compatibility is dropped.
25
+ - **Local data keeps working.** Read compatibility is retained for data written
26
+ by 1.7.2 and older: `[grok_com_config]` parses as `[login_config]`,
27
+ `grok_ws_*`/`grok_version` fields resolve, legacy agent-type and client-type
28
+ spellings are accepted, `refs/grok/*` worktree pins are read (new pins are
29
+ `refs/chutes/*`), legacy `grok-*` downloads are pruned, and the `XAI_*`
30
+ orchestration environment names still resolve (spec §1.5).
31
+ - **Upstream-only surfaces removed.** `chat_modes`/`ChatModelsClient`, the
32
+ preview-proxy supervisor, the "official marketplace" auto-trust concept and
33
+ the xAI tier vocabulary are gone (spec §7). Tier names are the Chutes plans,
34
+ and a max-tier check that cannot recognise a tier resolves false.
35
+ - **Legacy endpoint configuration stays honored.** `CHUTES_BUILD_XAI_API_BASE_URL`
36
+ and the `xai_api_base_url` requirements key still select the endpoint when
37
+ the canonical names (`base_url`, `CHUTES_API_BASE_URL`, `chutes_api_base_url`)
38
+ are unset; the canonical names win when both are present.
39
+
40
+ ### Changed
41
+
42
+ - CLI help and errors, the TUI, crate documentation and npm metadata identify
43
+ Chutes Build only. `authors` metadata on inherited crates reads "Chutes Build
44
+ contributors" (upstream attribution remains in the notice files).
45
+ - Settings-cache HMAC read keys are versioned (`SETTINGS_CACHE_READ_HMAC_KEY_V1`
46
+ plus a key list) so rotating the key does not invalidate a valid cache.
47
+ - Computer-hub donated-metric names are `donated_*` (were `preview_proxy_*`).
48
+
49
+ ### Fixed
50
+
51
+ - Legacy `[grok_com_config]` configurations are honoured again through the
52
+ `login_config` normalisation path instead of being dropped.
53
+ - Pager snapshot files follow the renamed crate (`chutes_pager__*`), so the
54
+ snapshot suite no longer reports every diff as new.
55
+ - `known-failures` baselines name the real post-rebrand modules and tests.
56
+ - **The documented JSON contracts now hold.** `models --json` emits the model
57
+ report (`authenticated`, `auth`, `authDetail`, `defaultModel`, `models`) as
58
+ documented, and `setup --json` / `trace --json` emit a parseable JSON error
59
+ envelope on their failure paths instead of human text.
60
+ - **`update --check` fails honestly and quickly.** Release-channel failures are
61
+ reported as `HTTP <status>` without dumping the storage backend's XML/HTML
62
+ body, the channel-pointer deadline is 6s with retries only for transient
63
+ failures, and a definitive 4xx moves straight to the fallback base.
64
+ - **`du` names the directory it measured.** With `CHUTES_BUILD_HOME` set, the
65
+ report header shows the resolved path instead of the literal
66
+ `$CHUTES_BUILD_HOME` shorthand.
67
+ - **CLI help and docs describe shipped behavior.** `update`, `setup`, `trace`,
68
+ and `models` no longer promise a closed-loopback no-op or a remote trace
69
+ upload that the build does not perform; `setup`'s missing-key guidance drops
70
+ the impossible "team sign-in" step.
71
+ - **Key-save failures are English and actionable on any OS locale.** The
72
+ welcome screen and `chutes-build login` no longer embed the localized system
73
+ message ("Accesso negato." on an Italian Windows): the error names the path,
74
+ the English cause and the OS code, and on Windows points at Controlled folder
75
+ access, which blocks unsigned builds from writing under the user profile.
76
+ - **Session list/search/delete are local-only again.** The CLI no longer sends a
77
+ credentialed request to a remote session registry that answers 404 on Chutes,
78
+ so a search no longer waits on it or prints a warning for every query.
79
+ - **Documentation matches the shipped update and session behavior.** README,
80
+ privacy, cli-reference, getting-started, the embedded user guide and the
81
+ upstream-sync record now distinguish the compiled-out automatic update checks
82
+ from the explicit `update` command, describe the `k`-then-paste key flow, and
83
+ note the Windows Controlled folder access workaround.
84
+
85
+ ### Internal
86
+
87
+ - `scripts/rebrand.py` is now a check-only brand guard over
88
+ `scripts/rebrand_files.json`; `--apply`/`--reclassify` were removed because an
89
+ upstream tree no longer exists to re-brand. The guard runs in CI and in the
90
+ local gate.
91
+ - `docs/product-spec.md` §1.4/§1.5/§1.7 define the identity and compatibility
92
+ boundary; `docs/upstream-sync.md` records the freeze and the rebrand audit.
93
+ - The upstream watcher is manual-dispatch only and `.github/upstream.json` is
94
+ marked frozen.
95
+ - Gitleaks history fingerprints keep the path each finding had in its own commit;
96
+ the rebrand pass had renamed them and un-suppressed six reviewed synthetic
97
+ fixtures. The web-search fixture whose fake prefix the rebrand rewrote is now
98
+ allowlisted by exact literal in `.gitleaks.toml`.
99
+ - The pre-existing red CI checks that blocked the release are green again:
100
+ three panicking slice/index sites in `chutes-tools` were made fallible,
101
+ `doctor`'s fix-request guard accepts Windows 8.3 short names (`RUNNER~1`)
102
+ while still rejecting `~`-prefixed components (plus a canonically-pathed
103
+ fixture), the dashboard footer tests derive the multiline submit chord from
104
+ the terminal context (macOS paints `Opt+Enter`), and `rustls-webpki` /
105
+ `webpki-roots` were updated for RUSTSEC-2026-0381 and RUSTSEC-2026-0382.
106
+ - The last X Corp tier vocabulary left plan gating: `is_restricted_tier_name`
107
+ classifies only an absent/empty plan or an explicit "Free" (Chutes has no free
108
+ subscription tier), the surrounding comments speak the Chutes plans, the spec
109
+ names the shipped `PlanUpsell*`/`CreditLimitUpsell*` events instead of the
110
+ removed `SuperGrokUpsell*`, and the vendored mermaid manifest comments name the
111
+ crate they actually target. The spec also records the checked-in generated
112
+ bot-relay clients as upstream artifacts pending external regeneration.
113
+
114
+ ## [1.7.2] - 2026-10-19
115
+
116
+ ### Fixed
117
+
118
+ - **Chutes tools work right after welcome-screen login.** The agent held
119
+ the mid-session key only in its runtime slot while media, vision,
120
+ account, document, embedding, and speech tools read plain env, so they
121
+ failed until restart. Tool dispatch now publishes the resolved
122
+ credentials on the call context and the tools resolve them from there,
123
+ with env as fallback.
124
+ - **`login` no longer echoes the key on a terminal.** Terminal echo is
125
+ disabled while the TTY prompt reads, and restored afterwards; piped
126
+ input is unchanged.
127
+ - **Re-saving the API key tightens loose permissions.** Overwriting a
128
+ pre-existing world-readable `api_key` file now resets it to owner-only
129
+ (`0600` on Unix) instead of inheriting the old mode.
130
+ - **Docs no longer describe flows that cannot run.** Removed the OAuth/IdP
131
+ rows (the auth code flow is unreachable without account login), marked
132
+ the OAuth2/OIDC settings dormant, fixed the key-precedence and
133
+ credential-storage claims, dropped the dead ZDR docs link, and reduced
134
+ the external-OTEL chapter to an honest deadened notice (telemetry is
135
+ withheld, the OTEL `init` is a no-op).
136
+ - **User-visible strings name this product.** CLI errors, retry commands,
137
+ settings descriptions, sample configs, and the Linux inhibit identity
138
+ no longer say `grok`; guide samples spawn `chutes-build`, and the
139
+ README names the real binary and canonical key-management link.
140
+ - Windows binaries link with an 8 MiB main-thread stack reserve
141
+ again (a per-target `rustflags` reserve, so it covers every profile),
142
+ fixing the dev-profile `STATUS_STACK_OVERFLOW` on startup
143
+ (`--version` included).
144
+ - **Per-model context windows from the live catalog.** The model parser
145
+ now reads the Chutes-native `context_length` field, so models that
146
+ declare it size from their real window (40k–1M); the hardcoded 256k
147
+ default remains as the fallback for models that do not.
148
+ - **Model fallback keeps tool support.** Unless the failed model is
149
+ positively known to lack tools (cataloged with a non-empty feature
150
+ list without `tools`), the sampler fallback only considers
151
+ replacements declaring `tools`, instead of potentially stranding an
152
+ agentic turn on a text-only model. An absent or feature-less failed
153
+ model keeps the requirement on, and feature-less candidates never
154
+ satisfy it, so such a fallback now honestly reports no candidate.
155
+ - **Malformed deny/ask rules fail closed.** A rule entry that does not
156
+ parse no longer silently drops to no-rule for an identifiable tool;
157
+ it keeps a tool-wide rule with the same action (plus a warning), so
158
+ a typo cannot quietly permit what it meant to restrict.
159
+ - **Blank JSON prompts are refused.** `--prompt-json`/`--prompt-file`
160
+ with only whitespace text blocks now errors like an empty `-p`
161
+ prompt; image-only prompts still work.
162
+ - **Compaction threshold is a `u8`.** The percent field was the only
163
+ `u32` in an otherwise all-`u8` chain, forcing a lossy `as u8` cast
164
+ at the check; the cast (and its silent truncation) is gone.
165
+ - **Session notifications match both wire namespaces.** The pager now
166
+ matches `x.ai/session_notification` / `x.ai/session/update` next to
167
+ the `chutes.ai/*` arms (retained wire compat per spec §1.5), so
168
+ session updates from shell emitters that still send `x.ai/*` are no
169
+ longer silently dropped; session-list metadata prefers
170
+ `chutes.ai/*` with `x.ai/*` fallback.
171
+ - **`account` and `apikey` are reserved skill-collision keys.** Adding
172
+ them to `PAGER_COMMAND_KEYS` keeps user skills from shadowing the
173
+ account slash commands.
174
+ - **Windows paste/render path fixes.** Dropped `file://` URIs without
175
+ a drive letter now paste instead of vanishing (percent-decoded path
176
+ fallback for local hosts), OSC-8 links render Unix-style file URLs,
177
+ tool paths use display separators, and managed-text identity on
178
+ Windows keys on creation time instead of mtime.
179
+
180
+ ### Security
181
+
182
+ - Patched the TLS stack: `rustls` 0.23.37 → 0.23.46
183
+ (RUSTSEC-2026-0285, -0346, -0348, -0349) and `git2` 0.20.2 →
184
+ 0.20.4 (RUSTSEC-2026-0008). The `zip` SUID/symlink trio and the
185
+ `unsafe-libyaml`/`zbus` unmaintained notices are allowlisted in
186
+ `deny.toml` with reachability-checked reasons (affected APIs
187
+ unused or migrations out of scope).
188
+
189
+ ### Tests
190
+
191
+ - New pins: runtime-key dispatch follow-through, `0600` tighten on
192
+ key overwrite, catalog `context_length` parsing (plain + meta,
193
+ configured-wins) and tool-aware fallback, fail-closed malformed
194
+ rules, blank-JSON prompt refusal, `u8` compaction threshold, and
195
+ the Gitleaks allowlist for the four pre-existing history findings.
196
+ - Suites green: render crate (1181), pager `--lib` (10191), pager
197
+ `settings_e2e` (279), chutes tools filter (54), binary (35), core
198
+ (93).
199
+ - Known pre-existing (verified by stash comparison, unrelated to this
200
+ release): `xai-grok-tools`/`xai-grok-workspace` carry Windows-only
201
+ failures, `xai-grok-login` machinery tests fail for the
202
+ intentionally absent login store, and the Unix-only cross-checks
203
+ run on CI Linux.
204
+
7
205
  ## [1.7.1] - 2026-10-17
8
206
 
9
207
  ### Fixed
package/NOTICE CHANGED
@@ -1,5 +1,5 @@
1
1
  Chutes Build
2
- Copyright 2026 Michael Gasperini (Mikesoft)
2
+ Copyright (c) 2026 Michael Gasperini (Mikesoft)
3
3
 
4
4
  This product is derived from xai-org/grok-build, originally distributed under
5
5
  the Apache License, Version 2.0, and includes substantial modifications for the
@@ -13,6 +13,6 @@ THIRD-PARTY-NOTICES. Files changed from the upstream work carry their changes
13
13
  through this repository's version-control history and this notice.
14
14
 
15
15
  The native Chutes media subsystem incorporates the workflow and project-owned
16
- implementation concepts from chutes-media-mcp, Copyright 2026 Michael Gasperini
16
+ implementation concepts from chutes-media-mcp, Copyright (c) 2026 Michael Gasperini
17
17
  (Mikesoft), originally available under the MIT License. The applicable MIT
18
18
  license notice is preserved in this repository's third-party notices.
package/PRIVACY.md CHANGED
@@ -11,8 +11,9 @@ environment variable or remote setting.
11
11
 
12
12
  ## Local data
13
13
 
14
- The CLI may store configuration, an encrypted or OS-protected credential entry
15
- where supported, sessions, logs, local exports, and user memory under
14
+ The CLI may store configuration, the saved API key (`api_key`) and MCP
15
+ credentials (`mcp_credentials.json`) — both plaintext owner-only files —
16
+ sessions, logs, local exports, and user memory under
16
17
  `~/.chutes-build` (or `CHUTES_BUILD_HOME`). Plugins, user roles/personas, and
17
18
  managed bundled-agent definitions use that same root; setting
18
19
  `CHUTES_BUILD_HOME` does not fall back to those resources in the default home.
@@ -23,10 +24,12 @@ files are created owner-only (mode 0600 where the platform has POSIX
23
24
  permissions), including the bootstrap templates written on first run.
24
25
 
25
26
  `chutes-build trace` always creates a local archive. Remote session sharing and
26
- search, remote workspace exposure, upstream managed configuration commands, and
27
- automatic update checks are disabled — compiled out through
28
- `chutes-build-core::product`, with their endpoints pointed at a closed loopback
29
- port rather than left resolvable.
27
+ search, remote workspace exposure, and upstream managed configuration commands
28
+ are disabled — compiled out through `chutes-build-core::product`, with their
29
+ endpoints pointed at a closed loopback port rather than left resolvable.
30
+ Automatic update checks are compiled out as well; the `chutes-build update`
31
+ command contacts the Chutes release channel only when you run it, and installs
32
+ only a version you explicitly request.
30
33
 
31
34
  There is no coding-data retention opt-in. Upstream offers one, both as a settings
32
35
  row and as a startup banner; here the setting is locked with the reason shown
@@ -63,17 +66,17 @@ explicit hosted feature:
63
66
  | --- | --- | --- |
64
67
  | `llm.chutes.ai` | Chutes inference (including native model routing via the `model` field), model catalog, semantic memory, voice transcription, OCR, and vision | model requests and the selected inputs: prompts/context, memory chunks, audio, images, PDF pages, or sampled video frames; Chutes API credential |
65
68
  | `api.chutes.ai` | Chutes account and media APIs | account requests, media parameters and user-selected media assets; Chutes API credential |
66
- | `api.chutes.ai/idp` | OAuth sign-in and refresh | authorization code or refresh token, PKCE verifier, registered client ID, and a client secret only when configured |
67
69
  | `chutes.ai/docs`, `chutes.ai/news` | mandatory primary-source verification for Chutes topics | requested official page URLs; no Chutes API credential |
68
70
  | `context7.com` | current library documentation | library names and documentation queries; known secrets are rejected and an optional Context7 key is sent only to the official HTTPS service |
69
71
  | DuckDuckGo or Brave Search | web search | search query; Brave receives only its dedicated key |
70
72
  | User-selected web pages | web fetch/browser automation | normal HTTP/browser traffic required by the requested action |
71
73
  | User-configured MCP servers/plugins | external tools | data required by the selected tool and its own configuration |
72
74
 
73
- The ambient Chutes API credential and cached Chutes session token are accepted
74
- only for allowlisted HTTPS Chutes and router hosts. They are never reused for a
75
- custom endpoint, web search, Context7, arbitrary websites, MCP servers, or
76
- browser automation. Custom inference models must declare a dedicated
75
+ The ambient Chutes API credential — the only credential this build holds;
76
+ there is no login session and no session token — is accepted only for
77
+ allowlisted HTTPS Chutes and router hosts. It is never reused for a custom
78
+ endpoint, web search, Context7, arbitrary websites, MCP servers, or browser
79
+ automation. Custom inference models must declare a dedicated
77
80
  `api_key`/`env_key`; a custom model-catalog endpoint uses
78
81
  `CHUTES_MODELS_API_KEY`.
79
82
 
package/README.md CHANGED
@@ -1,215 +1,196 @@
1
- <div align="center">
1
+ # Chutes Build
2
2
 
3
- <h1>Chutes Build (<code>chutes-build</code>)</h1>
3
+ A Chutes-native terminal coding agent
4
4
 
5
5
  [![CI](https://github.com/TheStreamCode/chutes-build/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/TheStreamCode/chutes-build/actions/workflows/ci.yml)
6
6
  [![npm](https://img.shields.io/npm/v/chutes-build?logo=npm&color=cb3837)](https://www.npmjs.com/package/chutes-build)
7
7
  [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
8
8
 
9
- **Chutes Build** is a terminal-based AI coding agent for the
10
- [Chutes](https://chutes.ai) ecosystem. It runs as a full-screen TUI that
11
- understands your codebase, edits files, executes shell commands, searches the web,
12
- and manages long-running tasks — interactively, headlessly for scripting/CI, or
13
- embedded in editors via the Agent Client Protocol (ACP).
14
-
15
- [Installing](#installing) ·
16
- [Building from source](#building-from-source) ·
17
- [Documentation](#documentation) ·
18
- [Repository layout](#repository-layout) ·
19
- [Development](#development) ·
20
- [Troubleshooting](#troubleshooting) ·
21
- [Contributing](#contributing) ·
22
- [License](#license)
23
-
24
9
  ![Chutes Build TUI](assets/chutes/screenshot/chutes-build.png)
25
10
 
26
- </div>
27
-
28
- ## What this is, and what it is built on
29
-
30
- Chutes Build started from [`xai-org/grok-build`](https://github.com/xai-org/grok-build)
31
- (re-based onto upstream 1.0.45) and is developed independently, for the Chutes
32
- ecosystem only: it talks to Chutes services and nothing else. Upstream code in
33
- this tree is used under Apache-2.0 (see [`NOTICE`](NOTICE)); the project is not
34
- affiliated with or endorsed by xAI.
35
-
36
- What the fork changes:
37
-
38
- - **Chutes, not xAI.** Inference goes to `llm.chutes.ai`, the model catalog is
39
- Chutes', the default route is Chutes' native model routing (the saved
40
- `default` pool, or an inline pool via `CHUTES_ROUTING_POOL`), and media
41
- generation, OCR, usage and quota all go through Chutes APIs.
42
- - **Nothing phones home.** Telemetry, remote error reporting, upload, session
43
- sharing, remote workspace exposure and self-update are off at compile time and
44
- their endpoints are deadened, not merely unused. See
45
- [`PRIVACY.md`](PRIVACY.md).
46
- - **A few exclusive features**: native Chutes ecosystem tools the agent calls
47
- by itself — image generation and editing, video and music generation,
48
- speech-to-text and text-to-speech, PDF/document extraction, OCR, text
49
- embeddings, and Context7 documentation lookup — plus an isolated browser
50
- tool, automatic vision delegation for text-only models, and automatic
51
- equivalent-model fallback when a chute is unavailable.
52
-
53
- Everything else is meant to track upstream closely, so their fixes arrive by
54
- merge rather than by hand. [`docs/upstream-sync.md`](docs/upstream-sync.md)
55
- documents that procedure and records each sync;
56
- [`.github/upstream.json`](.github/upstream.json) records the commit this tree is
57
- level with. `SOURCE_REV` is inherited from upstream's published tree and refers to
58
- their monorepo, not to anything in this repository.
11
+ Chutes Build is a terminal-based AI coding agent for the [Chutes](https://chutes.ai) ecosystem. It runs as a full-screen TUI (terminal user interface) that understands a codebase, edits files, executes shell commands, searches the web, and manages long-running tasks, interactively, headlessly for scripts and CI, or embedded in editors through the Agent Client Protocol (ACP). It is an independent, unofficial fork of [xai-org/grok-build](https://github.com/xai-org/grok-build) with Chutes-native inference, model routing, media and account endpoints, and it is not affiliated with or endorsed by xAI.
59
12
 
60
- ---
13
+ ## Contents
14
+
15
+ - [Install](#install)
16
+ - [Quick start](#quick-start)
17
+ - [Features](#features)
18
+ - [Requirements](#requirements)
19
+ - [Configuration](#configuration)
20
+ - [Privacy and security](#privacy-and-security)
21
+ - [Troubleshooting](#troubleshooting)
22
+ - [Development](#development)
23
+ - [Support](#support)
24
+ - [Contributing](#contributing)
25
+ - [License](#license)
61
26
 
62
- ## Installing
27
+ ## Install
63
28
 
64
- Via npm, which fetches the binary for your platform:
29
+ Install the npm launcher, which resolves the native binary for the current platform:
65
30
 
66
31
  ```sh
67
- npm i -g chutes-build
32
+ npm install -g chutes-build
68
33
  chutes-build --version
69
34
  ```
70
35
 
71
- Or build from source below.
36
+ Run it once without installing:
72
37
 
73
- From 1.0.0 on, each
74
- [release](https://github.com/TheStreamCode/chutes-build/releases) also carries the
75
- six platform executables as downloadable assets. Earlier releases (0.4.x) carry
76
- release notes only — npm is the way to install those.
38
+ ```sh
39
+ npx chutes-build
40
+ ```
77
41
 
78
- There is no self-update: `chutes-build` never contacts an update server, and the
79
- `update` subcommand reports where to get a newer version rather than fetching one.
80
- [`CHANGELOG.md`](CHANGELOG.md) records what changed in each release.
42
+ Each release also publishes the six platform executables (macOS, Linux and Windows, x64 and arm64) as downloadable assets on the [releases page](https://github.com/TheStreamCode/chutes-build/releases). Older releases carry release notes only, so use npm for those.
81
43
 
82
- ## Building from source
44
+ There is no automatic self-update: `chutes-build` never checks for updates on its own. `chutes-build update` contacts the Chutes release channel only when you run it (`--check` reads just the channel pointer) and installs nothing unless you ask for a specific version. [`CHANGELOG.md`](CHANGELOG.md) records what changed in each release.
83
45
 
84
- Requirements:
46
+ ## Quick start
85
47
 
86
- - **Rust** — the toolchain is pinned by [`rust-toolchain.toml`](rust-toolchain.toml);
87
- `rustup` installs it automatically on first build.
88
- - **[DotSlash](https://dotslash-cli.com)** — required so hermetic tools under
89
- [`bin/`](bin/) (notably [`bin/protoc`](bin/protoc)) can download and run.
90
- Install it and ensure `dotslash` is on your `PATH` **before** building:
48
+ 1. Create a Chutes API key at [chutes.ai/app/settings/api-keys](https://chutes.ai/app/settings/api-keys).
49
+ 2. Provide the key once with `chutes-build login`, paste it on the welcome screen, or export `CHUTES_API_KEY` for the current process. An explicit environment key wins over a saved one.
50
+ 3. Run `chutes-build` from the repository you want the agent to inspect. Start with `/help`, `/model` and `/docs`.
91
51
 
92
- ```sh
93
- cargo install dotslash
94
- # or: prebuilt packages — https://dotslash-cli.com/docs/installation/
95
- /usr/bin/env dotslash --help # sanity check
96
- ```
52
+ ```sh
53
+ chutes-build login
54
+ cd path/to/your/repository
55
+ chutes-build
56
+ ```
97
57
 
98
- - **protoc** — proto codegen resolves [`bin/protoc`](bin/protoc) via DotSlash,
99
- or falls back to a `protoc` on `PATH` / `$PROTOC`.
100
- - Windows, macOS and Linux all build. Windows is where this tree is developed and
101
- gated, and it needs the vendored `protoc` fallback carried here — upstream
102
- does not build on Windows at all, because `bin/protoc` is a DotSlash wrapper the
103
- platform cannot execute from a build script.
58
+ Headless runs use the same binary:
104
59
 
105
60
  ```sh
106
- cargo run -p chutes-build # build + launch the TUI
107
- cargo build -p chutes-build --release # release binary: target/release/chutes-build
108
- cargo check --workspace # fast validation
61
+ chutes-build -p "Summarize this repository" --output-format plain
62
+ chutes-build -p "Return the package list" --output-format json
109
63
  ```
110
64
 
111
- The binary artifact is named `xai-grok-pager`; official installs ship it as
112
- `chutes-build`. The only credential is a Chutes API key, created at
113
- [chutes.ai/app/settings/api-keys](https://chutes.ai/app/settings/api-keys)
114
- and provided via `chutes-build login`, the welcome screen, or
115
- `CHUTES_API_KEY`. There is no browser login; see the
116
- [authentication guide](crates/codegen/xai-grok-pager/docs/user-guide/02-authentication.md).
65
+ Headless-only controls such as `--max-turns`, `--tools`, `--disallowed-tools` and `--json-schema` require a headless prompt.
117
66
 
118
- ## Documentation
67
+ Full documentation lives in the repository: the [documentation hub](docs/README.md) links the [getting started guide](docs/getting-started.md), [configuration reference](docs/configuration.md), CLI reference and slash-command reference. The in-binary user guide at [`crates/codegen/chutes-pager/docs/user-guide/`](crates/codegen/chutes-pager/docs/user-guide/README.md) covers keyboard shortcuts, theming, MCP servers, skills, plugins, hooks, sessions, sandboxing, headless mode and more. There is no separate documentation site.
119
68
 
120
- The documentation lives in this repository. There is no separate site: an earlier
121
- link to `docs.chutes.ai/build/overview` was a 404 dressed as a promise.
69
+ ## Features
122
70
 
123
- The user guide ships with the pager crate:
124
- [`crates/codegen/xai-grok-pager/docs/user-guide/`](crates/codegen/xai-grok-pager/docs/user-guide/)
125
- — getting started, keyboard shortcuts, slash commands, configuration, theming,
126
- MCP servers, skills, plugins, hooks, headless mode, sandboxing, and more.
71
+ - Chutes-native inference and routing: requests go to Chutes, the model catalog is Chutes', and the default route is Chutes' native routing, either the saved `default` pool or an inline pool set with `CHUTES_ROUTING_POOL`.
72
+ - Automatic equivalent-model fallback when a chute is unavailable, with an ordered `CHUTES_FALLBACK_MODELS` chain and `CHUTES_STRICT_MODEL=1` to disable it.
73
+ - Full-screen TUI with file edits, shell commands, code search, plan mode, rewind and undo, sessions, and long-running background tasks.
74
+ - Headless mode for scripts and CI, plus the Agent Client Protocol (ACP) for editor integrations.
75
+ - Chutes ecosystem tools the agent calls on its own: image generation and editing, video and music generation, speech-to-text and text-to-speech, PDF and document extraction, OCR, text embeddings, and Context7 documentation lookup.
76
+ - Isolated browser automation over the DevTools protocol, with a temporary profile and loopback-only DevTools, plus automatic vision delegation for text-only models.
77
+ - Privacy boundaries compiled in rather than configured out: telemetry, remote error reporting, upload, session sharing, remote workspace exposure and self-update are disabled at build time and their endpoints are deadened. See [`PRIVACY.md`](PRIVACY.md).
78
+ - Permission prompts, a sandbox, local memory, MCP servers, skills, plugins and hooks, documented in the user guide.
127
79
 
128
- ## Repository layout
80
+ ## Requirements
129
81
 
130
- | Path | Contents |
131
- |------|----------|
132
- | `crates/codegen/xai-grok-pager-bin` | Composition-root package `chutes-build`; builds the `chutes-build` binary |
133
- | `crates/codegen/xai-grok-pager` | The TUI: scrollback, prompt, modals, rendering |
134
- | `crates/codegen/xai-grok-shell` | Agent runtime + leader/stdio/headless entry points |
135
- | `crates/codegen/xai-grok-tools` | Tool implementations (terminal, file edit, search, ...) |
136
- | `crates/codegen/xai-grok-workspace` | Host filesystem, VCS, execution, checkpoints |
137
- | `crates/codegen/...` | The rest of the CLI crate closure (config, MCP, markdown, sandbox, ...) |
138
- | `crates/common/`, `crates/build/`, `prod/mc/` | Small shared leaf crates pulled in by the closure |
139
- | `third_party/` | Vendored upstream source (Mermaid diagram stack) — see below |
140
-
141
- > [!IMPORTANT]
142
- > The root `Cargo.toml` (workspace members, dependency versions, lints,
143
- > profiles) is **generated** — treat it as read-only. Prefer editing per-crate
144
- > `Cargo.toml` files.
82
+ - Windows, macOS or Linux, on x64 or arm64.
83
+ - Node.js 18 or newer for the npm launcher.
84
+ - A Chutes API key. It is the only credential; there is no browser login.
85
+ - For a source build: Git, a Rust toolchain (pinned in [`rust-toolchain.toml`](rust-toolchain.toml), installed automatically by `rustup`), and the platform C/C++ toolchain used by Rust.
86
+ - [DotSlash](https://dotslash-cli.com) on `PATH` before building, so hermetic tools under [`bin/`](bin/) such as [`bin/protoc`](bin/protoc) can run.
87
+ - `protoc` for proto code generation, resolved through DotSlash or a `protoc` on `PATH` or in `$PROTOC`. On Windows use the vendored `protoc` fallback, because the DotSlash wrapper in `bin/protoc` is not executable from a build script there.
145
88
 
146
- ## Development
89
+ ## Configuration
147
90
 
148
- ```sh
149
- cargo check -p <crate> # always target specific crates; full-workspace builds are slow
150
- cargo test -p xai-grok-config # per-crate tests
151
- cargo clippy -p <crate> # lint config: clippy.toml at the repo root
152
- ```
91
+ Configuration layers command-line arguments, environment variables, user configuration, project configuration and project instructions. `chutes-build inspect --json` shows the effective non-secret structure, and [`docs/configuration.md`](docs/configuration.md) is the full reference.
92
+
93
+ | Setting | Purpose | Default |
94
+ | --- | --- | --- |
95
+ | `CHUTES_API_KEY` | Ambient Chutes API credential, sent only to allowlisted official HTTPS endpoints | Unset; prompted or saved by `chutes-build login` |
96
+ | `CHUTES_BUILD_HOME` | Relocates the complete user state tree, including credentials, sessions, logs and plugins | `~/.chutes-build` |
97
+ | `CHUTES_BUILD_DEFAULT_MODEL` | Default model id, or a native routing string such as `default` or an inline pool | Chutes native routing (`default`) |
98
+ | `CHUTES_ROUTING_POOL` | Inline routing pool of comma-separated catalogue ids | Unset |
99
+ | `CHUTES_ROUTING_STRATEGY` | Routing strategy for a pool: `sequential`, `latency` or `throughput` | `sequential` |
100
+ | `CHUTES_FALLBACK_MODELS` | Ordered comma-separated fallback chain | Unset |
101
+ | `CHUTES_STRICT_MODEL` | Set to `1` to disable automatic fallback | Disabled |
102
+ | `CHUTES_EXTRA_CA_BUNDLE` | PEM bundle of extra TLS roots for networks that intercept TLS | Unset; no file is read |
103
+
104
+ Environment variables are read from the process environment; `.env` files are not loaded automatically. Endpoint overrides fail closed unless they use an allowlisted Chutes HTTPS host with no URL credentials and the default port, and ambient credentials are never inherited by arbitrary custom endpoints.
105
+
106
+ ## Privacy and security
107
+
108
+ Sessions, memory, configuration, logs, traces and generated artifacts stay local unless a documented feature needs a provider request. Telemetry, remote error reporting, trace upload, session sharing, remote workspace exposure, managed remote configuration and automatic updates stay off regardless of inherited configuration values. [`PRIVACY.md`](PRIVACY.md) is the authoritative statement of the data boundaries.
109
+
110
+ Report vulnerabilities privately through [`SECURITY.md`](SECURITY.md), never in a public issue.
153
111
 
154
112
  ## Troubleshooting
155
113
 
156
114
  ### Missing `CHUTES_API_KEY`
157
115
 
158
- On first launch `chutes-build` asks for a Chutes API key (created at
159
- [chutes.ai/app/api](https://chutes.ai/app/api)); it is also readable from the
160
- `CHUTES_API_KEY` environment variable. If requests fail with authentication
161
- errors, check that the variable is exported in the launching shell — Chutes
162
- Build reads the process environment and does not load `.env` files
163
- automatically (see [`docs/configuration.md`](docs/configuration.md)).
164
- Never commit a real key; use your shell, CI platform, or secret manager to
165
- provide it, and run `chutes-build inspect --json` to verify the effective
166
- non-secret configuration.
116
+ On first launch Chutes Build asks for a key created at [chutes.ai/app/settings/api-keys](https://chutes.ai/app/settings/api-keys); it also reads `CHUTES_API_KEY` from the process environment. If requests fail with authentication errors, check that the variable is exported in the launching shell: `.env` files are not loaded automatically. Never commit a real key; use your shell, your CI platform or a secret manager, and run `chutes-build inspect --json` to verify the effective non-secret configuration.
167
117
 
168
118
  ### Model-pool routing errors
169
119
 
170
- The default model route is Chutes' native routing: the saved `default` pool
171
- (managed at chutes.ai/app → Model Routing), or an inline pool via
172
- `CHUTES_ROUTING_POOL` (comma-separated catalogue ids sent as one `model`
173
- value, e.g. `modelA,modelB,modelC`). If the `default` alias cannot resolve
174
- and no dashboard pool is saved, the built-in fallback chain steps down to a
175
- live inline pool from the current catalogue; a saved dashboard pool, once
176
- configured, takes priority. Common fixes: save a pool on the dashboard, set
177
- `CHUTES_ROUTING_POOL` explicitly, check `CHUTES_FALLBACK_MODELS` ordering (or
178
- `CHUTES_STRICT_MODEL=1`, which disables automatic fallback), and pick a
179
- strategy with `CHUTES_ROUTING_STRATEGY` (`sequential` default, `latency`, or
180
- `throughput`). Full reference: [`docs/configuration.md`](docs/configuration.md)
181
- ("Native model routing").
120
+ The default route is Chutes' native routing: the saved `default` pool (managed at chutes.ai/app, Model Routing) or an inline pool from `CHUTES_ROUTING_POOL`. When the `default` alias cannot resolve and no dashboard pool is saved, the built-in fallback chain steps down to a live inline pool from the current catalogue; a saved dashboard pool takes priority once configured. Check the saved pool, set `CHUTES_ROUTING_POOL` explicitly, review `CHUTES_FALLBACK_MODELS` ordering, and pick a strategy with `CHUTES_ROUTING_STRATEGY`.
121
+
122
+ ### Windows blocks saving the API key
123
+
124
+ If the welcome screen or `chutes-build login` reports `permission denied (os error 5)` for
125
+ `C:\Users\<you>\.chutes-build\api_key`, Windows Controlled folder access is blocking the
126
+ unsigned binary; the directory itself is writable. Allow `chutes-build.exe` through
127
+ **Windows Security → Virus & threat protection → Ransomware protection → Allow an app through
128
+ Controlled folder access**, or point `CHUTES_BUILD_HOME` at a folder the protection does not
129
+ cover.
182
130
 
183
131
  ### Windows console shows wrong glyphs
184
132
 
185
- The TUI degrades decorative glyphs on the legacy Windows console (ConHost
186
- `cmd.exe` / `powershell.exe`, Consolas/Lucida Console raster font, no font
187
- fallback): arrows, checkmarks, diamonds, and spinners fall back to ASCII or
188
- CP437-safe stand-ins (see
189
- [`crates/codegen/xai-grok-pager-render/src/glyphs.rs`](crates/codegen/xai-grok-pager-render/src/glyphs.rs)).
190
- This is expected on legacy ConHost — for the full rendering use Windows
191
- Terminal, VS Code's terminal, or another modern emulator. Note that CI forces
192
- the modern-glyph path with `CHUTES_BUILD_FORCE_LEGACY_CONSOLE=0` (see
193
- [`.github/workflows/ci.yml`](.github/workflows/ci.yml)), so screenshots and
194
- test rendering may look richer than a legacy local console.
133
+ The TUI degrades decorative glyphs on the legacy Windows console: arrows, checkmarks, diamonds and spinners fall back to ASCII or CP437-safe stand-ins. This is expected on legacy ConHost; for full rendering use Windows Terminal, the VS Code terminal or another modern emulator.
195
134
 
135
+ ### Browser or media tools unavailable
136
+
137
+ Browser automation needs Chrome or Edge, or an explicit `CHUTES_BROWSER_EXECUTABLE`. Video inspection needs FFmpeg, or an explicit `CHUTES_FFMPEG_EXECUTABLE`; install it and restart the process.
138
+
139
+ ## Development
140
+
141
+ Clone the repository and build with the pinned toolchain:
142
+
143
+ ```sh
144
+ git clone https://github.com/TheStreamCode/chutes-build.git
145
+ cd chutes-build
146
+ cargo run -p chutes-build # build and launch the TUI
147
+ cargo build -p chutes-build --release # release binary: target/release/chutes-build
148
+ cargo check --workspace # fast validation
149
+ ```
150
+
151
+ Run checks on the crates you touched instead of the whole workspace:
152
+
153
+ ```sh
154
+ cargo test -p chutes-config # per-crate tests
155
+ cargo clippy -p <crate> # lint configuration: clippy.toml at the repository root
156
+ ```
157
+
158
+ The binary artifact is named `chutes-build`. The root `Cargo.toml` is generated and read-only: change the owning crate manifest or the generator source, and prefer per-crate `Cargo.toml` files. `Cargo.lock` is committed, and the npm launcher is a thin resolver for prebuilt native binaries: it never compiles Rust and has no install lifecycle script.
159
+
160
+ Upstream synchronization from `xai-org/grok-build` is frozen at 2.0.0. The total rebrand renamed every crate, module and the local wire, so an upstream diff no longer applies mechanically; ports are manual and recorded in [`docs/upstream-sync.md`](docs/upstream-sync.md), and the crate and module names stay `chutes-*`.
161
+
162
+ ### Repository layout
163
+
164
+ | Path | Contents |
165
+ | --- | --- |
166
+ | `crates/chutes-build-core` | Chutes-owned product policy and integrations |
167
+ | `crates/codegen/chutes-build` | Composition-root package `chutes-build`; builds the binary |
168
+ | `crates/codegen/chutes-pager` | The TUI: scrollback, prompt, modals, rendering |
169
+ | `crates/codegen/chutes-shell` | Agent runtime and leader, stdio and headless entry points |
170
+ | `crates/codegen/chutes-tools` | Tool implementations (terminal, file edit, search, media, browser) |
171
+ | `crates/codegen/chutes-workspace` | Host filesystem, VCS, execution and checkpoints |
172
+ | `crates/codegen/...` | The rest of the CLI crate closure (config, MCP, markdown, sandbox) |
173
+ | `third_party/` | Vendored upstream source, including the Mermaid diagram stack |
174
+
175
+ ## Support
176
+
177
+ See [`SUPPORT.md`](SUPPORT.md) and GitHub Discussions for usage questions. Bug reports belong in GitHub Issues; security problems follow [`SECURITY.md`](SECURITY.md) and never a public issue.
196
178
 
197
179
  ## Contributing
198
180
 
199
- > [!NOTE]
200
- > External contributions are not accepted. See [`CONTRIBUTING.md`](CONTRIBUTING.md).
181
+ External contributions are not accepted. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the licensing terms that apply to this source.
201
182
 
202
183
  ## License
203
184
 
204
- First-party code in this repository is licensed under the **Apache License,
205
- Version 2.0** — see [`LICENSE`](LICENSE).
185
+ First-party code in this repository is licensed under the **Apache License, Version 2.0**; see [`LICENSE`](LICENSE). The project is derived from `xai-org/grok-build`, used under Apache-2.0; the upstream attribution is preserved in [`NOTICE`](NOTICE).
186
+
187
+ Third-party and vendored code remains under its original licenses:
206
188
 
207
- Third-party and vendored code remains under its original licenses. See:
189
+ - [`THIRD-PARTY-NOTICES`](THIRD-PARTY-NOTICES) lists crates.io and git dependencies, bundled UI themes, and in-tree source ports, including the openai/codex and sst/opencode tool implementations.
190
+ - [`crates/codegen/chutes-tools/THIRD_PARTY_NOTICES.md`](crates/codegen/chutes-tools/THIRD_PARTY_NOTICES.md) is the crate-local notice for the codex and opencode ports, with license texts and the Apache section 4(b) change notice.
191
+ - [`third_party/NOTICE`](third_party/NOTICE) is the vendored Mermaid-stack index.
192
+
193
+ ---
208
194
 
209
- - [`THIRD-PARTY-NOTICES`](THIRD-PARTY-NOTICES) — crates.io / git dependencies,
210
- bundled UI themes, and **in-tree source ports** (including openai/codex and
211
- sst/opencode tool implementations)
212
- - [`crates/codegen/xai-grok-tools/THIRD_PARTY_NOTICES.md`](crates/codegen/xai-grok-tools/THIRD_PARTY_NOTICES.md)
213
- — crate-local notice for the codex and opencode ports (license texts +
214
- Apache §4(b) change notice)
215
- - [`third_party/NOTICE`](third_party/NOTICE) — vendored Mermaid-stack index
195
+ Maintained by [Michael Gasperini (Mikesoft)](https://mikesoft.it).
196
+ If this project is useful to you, consider [sponsoring its maintenance](https://github.com/sponsors/TheStreamCode).
package/SECURITY.md CHANGED
@@ -4,6 +4,15 @@ Chutes Build is a fork of
4
4
  [`xai-org/grok-build`](https://github.com/xai-org/grok-build). Where to report
5
5
  depends on which part is affected, and if you are not sure, report it here first.
6
6
 
7
+ ## Supported versions
8
+
9
+ Security fixes are shipped for the latest release only.
10
+
11
+ | Version | Supported |
12
+ | --- | --- |
13
+ | Latest release | Yes |
14
+ | Older releases | No |
15
+
7
16
  ## Report it here
8
17
 
9
18
  Use GitHub's private vulnerability reporting on this repository:
@@ -11,10 +20,16 @@ Use GitHub's private vulnerability reporting on this repository:
11
20
 
12
21
  Please do not open a public issue for a vulnerability.
13
22
 
23
+ Include the affected version and platform, a description of the issue and its
24
+ impact, reproduction steps or a proof of concept, and any mitigation you already
25
+ know about. You can expect an initial acknowledgement within 7 days and a status
26
+ update within 30 days. If the report is valid, a fix is prepared privately and
27
+ disclosed in the release notes once a patched version is available. Credit is
28
+ given in the advisory unless you ask otherwise.
29
+
14
30
  Anything in the fork's own surface belongs here:
15
31
 
16
- - credential resolution and storage (`CHUTES_API_KEY`, `auth.json`, the OAuth
17
- flow against the Chutes IdP);
32
+ - credential resolution and storage (`CHUTES_API_KEY`, `~/.chutes-build/api_key`);
18
33
  - which endpoints may receive a credential (`chutes-build-core::endpoint_policy`);
19
34
  - the plugin trust boundary, permission rules, and the sandbox;
20
35
  - the Chutes tools — media generation, OCR, the isolated browser, Context7;
package/package.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "chutes-build",
3
- "version": "1.7.1",
3
+ "version": "2.0.0",
4
4
  "description": "Privacy-first, open-source coding agent for the Chutes ecosystem",
5
5
  "license": "Apache-2.0",
6
- "author": "Michael Gasperini (Mikesoft)",
6
+ "author": { "name": "Michael Gasperini", "email": "michael@mikesoft.it", "url": "https://mikesoft.it" },
7
7
  "homepage": "https://github.com/TheStreamCode/chutes-build#readme",
8
8
  "repository": {
9
9
  "type": "git",
@@ -37,12 +37,12 @@
37
37
  "check": "npm test && npm run verify:release && npm pack --dry-run"
38
38
  },
39
39
  "optionalDependencies": {
40
- "chutes-build-darwin-arm64": "1.7.1",
41
- "chutes-build-darwin-x64": "1.7.1",
42
- "chutes-build-linux-arm64-gnu": "1.7.1",
43
- "chutes-build-linux-x64-gnu": "1.7.1",
44
- "chutes-build-win32-arm64": "1.7.1",
45
- "chutes-build-win32-x64": "1.7.1"
40
+ "chutes-build-darwin-arm64": "2.0.0",
41
+ "chutes-build-darwin-x64": "2.0.0",
42
+ "chutes-build-linux-arm64-gnu": "2.0.0",
43
+ "chutes-build-linux-x64-gnu": "2.0.0",
44
+ "chutes-build-win32-arm64": "2.0.0",
45
+ "chutes-build-win32-x64": "2.0.0"
46
46
  },
47
47
  "keywords": [
48
48
  "ai",