@fugood/buttress-server 2.26.0-beta.2 → 2.26.0-beta.21

package/README.md

@@ -27,7 +27,8 @@ irm https://cdn.bricks.tools/bricks-buttress/release/install.ps1 | iex
 The installer detects the host's supported GGML accelerator (CUDA > Vulkan >
 Snapdragon, falling back to the default CPU/Metal build) and downloads only
 the native modules the binary needs — the ggml llama.node / whisper.node
-variant packages plus onnxruntime, sharp, and oxc-transform prebuilds — into a
+variant packages plus onnxruntime, sharp, oxc-transform and (where gpuix
+publishes one) the settings window's gpuix prebuilds — into a
 `node_modules` sidecar next to the executable. It installs to
 `~/.bricks-cli/bin` (shared with the BRICKS CLI, so one PATH entry covers
 both). Override detection with
@@ -60,6 +61,67 @@ npx bricks-buttress --config ./config.toml
 npx bricks-buttress
 ```
 
+## Settings, status and chat window (`bricks-buttress ui`)
+
+`bricks-buttress ui` opens a native desktop window for one config file:
+
+```bash
+bricks-buttress ui -c ./config.toml   # or: bricks-buttress ui ./config.toml
+bricks-buttress ui -c ./config.toml --tab chat   # open on a given tab: chat, status or settings
+```
+
+- **Settings** edits the TOML through a form: server, runtime defaults, discovery and endpoints, and generators (a HuggingFace search adds models, and each model shows whether it fits the memory budget). `[functions]`, `[[agents]]`, `[agents_options]` and `[env]` are edited as raw TOML. HuggingFace requests use `[runtime] huggingface_token`, else `$HUGGINGFACE_TOKEN`, else `$HF_TOKEN`.
+- **Status** is a live dashboard of the server started with this config: identity, hardware, pre-downloads, the generators and requests of each backend, and local functions.
+- **Chat** talks to the `[[agents]]` of that server (see [Chat tab](#chat-tab) below).
+
+Saving shows a diff of the file first, and an invalid value blocks it. The write is atomic (temporary file + rename), and the previous content is kept as `<config>.bak` next to the file (one backup, replaced on each save). The form rewrites the sections it owns, so comments inside them are lost; the raw sections are written back verbatim, comments included. When the file changes on disk while the window is open, the window offers to reload it or to keep your edits; it never merges them. A missing file opens as a new config from defaults, and nothing is written until you confirm **Create file**.
+
+The window never starts, stops or restarts the server, and the server reads its config only at startup: restart it to apply saved changes (the window shows the start command). The settings stay editable while the server runs.
+
+**Server detection.** The window reads `[server] port` (default `2080`) and `id` (default `buttress-<machineId>`) from the config, then asks `http://127.0.0.1:<port>` for the server id every 3 seconds:
+
+- the same `id` answers: the server runs, and the window opens on Chat when the server reports agents, else on Status;
+- another `id` answers: the port is used by another buttress server;
+- something answers HTTP without a buttress id: the port is used by another program;
+- no answer: the server is not running. The window opens on Settings, and its Status tab turns live by itself when the server appears.
+
+The id comes from `/buttress/info` when the server serves it, else from `server.id` in `/buttress/status`. The server serves `/buttress/info` only while autodiscover HTTP is on (`autodiscover = true`, or an `[autodiscover]` table without `http.enabled = false`), and the window asks for it at the default path only: with a custom `http.path` it identifies the server from `/buttress/status`. `/buttress/status` is always served, so detection works with autodiscover off too. Without `/buttress/info` the window shows no addresses or workspace binding for the server.
+
+When you save a new `[server] port` or `id` while the server runs, the window keeps showing the running server (with a "restart required" banner) until it stops, then looks for the new port and id.
+
+`--tab chat|status|settings` opens the window on that tab instead of the one detection picks.
+
+**Platform support.** The window uses gpuix (a React renderer for GPUI) and runs under Bun on `darwin-arm64`, `linux-x64` and `win32-x64`, the platforms with gpuix prebuilt modules. Under Node.js or on another platform the command stops with a message; open `http://<host>:<port>/status` in a browser instead. The standalone binary includes the window (its installer adds gpuix's native module to the sidecar on those platforms); the npm package does not include `@fugood/buttress-ui`, and the command says so. Light or dark follows the macOS appearance; other platforms use light.
+
+### Chat tab
+
+The Chat tab is a client of the [agent endpoints](#agents-experimental), like `bricks-buttress agent`: it calls `http://127.0.0.1:<port>` of the config with the runtime token the server writes at startup, so it works on an unbound server without `allow_unauthenticated`. The sidebar groups the sessions by agent, newest first, with the first prompt as the title and a badge on forked sessions; it refreshes every 10 seconds and after each run. A run streams into the chat: the thinking (collapsed), the answer as markdown, each tool call with its arguments and result, and a footer with the stop reason, turns and tokens. Enter sends and Shift+Enter starts a new line. Stop aborts the run and the session stays continuable; Fork sends the next prompt to a copy of the session; New session (or `/new` in the composer) starts a fresh one. The window runs one prompt at a time. The server keeps no turn of a stopped or failed run in the session, so a session opened later shows such a prompt with a "No saved answer" note. The tab needs the running server: without it the tab shows the start command, and a config without `[[agents]]` shows where to add them (Settings › Advanced). When the server starts again, the tab reads the new runtime token and reloads the agents by itself. A saved file with `[[agents]]` that the running server does not have (it was started before they were saved, or from another file) shows the restart command instead of an error; agents the server would refuse to start with show that refusal, and the Advanced section warns about it before you save. An agent on a `buttress/…` model needs `[openai_compat] enabled = true` (see [Agents](#agents-experimental), Models).
+
+### Status page and `/buttress/status`
+
+The server still serves the dashboard at `/status` for any browser (phone width included). It is built from the same view model as the Status tab (see DEVELOPMENT.md) and polls `/buttress/status` every 3 seconds, and `/buttress/info` while the server serves it (the page footer names the path, or says there is none).
+
+Next to the per-backend status (`ggmlLlm`, `ggmlStt`, `ggmlTts`, `ggmlDecision`, `mlxLlm`, `onnxStt`, `onnxTts`) and `functions`, `/buttress/status` returns:
+
+| Field                  | Content                                                                                                  |
+| ---------------------- | -------------------------------------------------------------------------------------------------------- |
+| `server.id`, `server.name`, `server.version`, `server.port` | The identity `/buttress/info` reports, here also when autodiscover HTTP is off |
+| `server.startedAt`     | ISO time the server started                                                                              |
+| `server.uptimeMs`      | Milliseconds since `startedAt`                                                                           |
+| `server.sessions.open` | RPC sessions in memory: connected clients, plus disconnected ones inside their `session_timeout` window  |
+| `server.generatorTypes` | The generator types this server loaded from the config (entries with `enabled = false` excluded), each once |
+| `server.generators`    | The generators this server loaded from the config, in file order: `type`, `repoId` and `quantization` (`null` when the entry sets none). The status page lists the ones no client has loaded yet |
+| `server.features.openaiCompat`, `.anthropicMessages`, `.typesafeCompat` | `true` when that compatibility endpoint is served (env var or config flag) |
+| `server.features.autodiscover` | `{ udpPort, udpAnnouncing, httpPath }` as configured (`null` for a transport that is off), or `null` when autodiscover is off. `udpAnnouncing` is `false` when UDP is configured but does not run: it needs a server bound to a workspace with an announce key |
+| `server.features.functions` | `{ enabled, count, daemons, hotReload }`: the local functions loaded now, and the daemon functions configured (`meta.daemon`), including ones that failed to start |
+| `server.features.agents` | `{ enabled, count, names }` of the configured agents, or `null` when none run |
+| `server.host`          | This machine, read at startup: `cpuModel`, `cpuCores`, `totalMemoryBytes`, `appleSilicon`, and `gpuName` on Apple Silicon (the chip name) |
+| `server.caps`          | The hardware probe of each configured generator type, run at startup: `type`, `score`, `hasGpu`, `usableBytes` (the `generators` list of `/buttress/info`, here also when that route is off) |
+| `downloads.active`     | Pre-downloads in progress: `type`, `repoId`, `filename`, `startedAt`, `progress` (0–1), `receivedBytes`, `totalBytes`, `bytesPerSecond` |
+| `downloads.recent`     | The last 20 finished pre-downloads, newest first: `type`, `repoId`, `filename`, `totalBytes`, `durationMs`, `finishedAt`, `success`, `error` |
+
+`downloads` covers the startup pre-downloads (`download = true`) only; a download that starts when a client loads a model that is not cached yet is not listed. The backends report download progress as a fraction, so `receivedBytes` is `0` and `totalBytes` / `bytesPerSecond` are `null`: use `progress`.
+
 ## Workspace Binding (`bricks buttress`)
 
 By default, a buttress-server runs in **public mode**: any client on the LAN can connect, no auth required. To restrict access to a single BRICKS workspace and enable workspace-scoped JWT auth, **bind** the server with the `bricks buttress` CLI commands. Once bound, the server only accepts WebSocket / file-transfer requests carrying a valid access token signed by that workspace's issuer.
@@ -69,14 +131,14 @@ The `bricks` CLI is the tool that performs the binding and writes the local stat
 ### Bind a server to a workspace
 
 ```bash
-# Pair the local machine's buttress-server with the workspace of the current bricks-cli profile
+# Pair the local server and provision a workspace DevTools token using the current CLI profile
 bricks buttress bind
 
 # Override the auto-detected server id, give it a friendly name, or write to a custom state dir
 bricks buttress bind --server-id buttress-mac-studio --name "Studio LLM" --state-dir /etc/buttress
 
 # For headless/remote setups: emit state.json to stdout instead of writing to disk
-bricks buttress bind --print > /etc/buttress/state.json
+(umask 077; bricks buttress bind --print > /etc/buttress/state.json)
 ```
 
 The state file (`~/.bricks-cli/buttress/state.json` by default, or `$BRICKS_BUTTRESS_STATE_DIR`) stores:
@@ -84,6 +146,15 @@ The state file (`~/.bricks-cli/buttress/state.json` by default, or `$BRICKS_BUTT
 - `workspace.id` / `workspace.name` — which workspace this server belongs to
 - `workspace.serverId` — the server's stable id (defaults to `buttress-<machineId>`)
 - `workspace.issuerPublicKey` + `workspace.kid` — Ed25519 SPKI used to verify access tokens
+- `devtools` — workspace-scoped DevTools JWT (`k: "da"`), workspace id and expiry,
+  provisioned automatically by `bind` for agent device tools
+
+Normal bind/status output reports only token expiry, never the token. The CLI writes
+state with mode `0600`; `--print` includes credentials and must be treated as a secret.
+Rebinding provisions a fresh token (default lifetime: 30 days) and rotates the announce
+key. Issuance failure stops binding before changing the remote announce key. Rebinding
+or unbinding does not revoke previously issued DevTools JWTs; they remain valid until
+expiry or issuer-key rotation.
 
 **Restart `bricks-buttress` after binding** for the change to take effect — the state file is read once at startup.
 
@@ -153,7 +224,9 @@ Configuration is loaded from a TOML file passed via `--config` / `-c`. Every top
 | `[autodiscover]`          | LAN UDP / HTTP / mDNS discovery toggles                                                            |
 | `[openai_compat]`         | Enable `/oai-compat/v1/*` — see [Compatibility Endpoints](#compatibility-endpoints-experimental)   |
 | `[anthropic_messages]`    | Enable `/anthropic-messages` — see [Compatibility Endpoints](#compatibility-endpoints-experimental)|
+| `[typesafe_compat]`       | Enable `/typesafe-compat/v1/*` — see [Compatibility Endpoints](#compatibility-endpoints-experimental) |
 | `[functions]`             | Enable local functions — see [Local Functions](#local-functions-experimental)                      |
+| `[[agents]]`              | Config-defined agents — see [Agents](#agents-experimental)                                         |
 | `[[generators]]`          | Array of generator instances — one entry per loaded model                                          |
 
 ### `[env]`
@@ -206,6 +279,8 @@ Most ggml-llm `[generators.model]` keys can also live in `[runtime]` as defaults
 | `no_extra_bufts`             | boolean                       | Disable extra compute buffer types                                     |
 | `cpu_mask`, `cpu_strict`     | string / boolean              | CPU affinity (advanced)                                                |
 | `devices`                    | string[]                      | Restrict to specific GGML devices                                      |
+| `split_mode`                 | `"none"` / `"layer"` / `"row"` / `"tensor"` | ggml-llm GPU splitting: single GPU, layers + KV (default), weight rows, or weights + KV (experimental tensor parallelism) |
+| `tensor_split`               | number[]\|string              | ggml-llm per-GPU proportions, e.g. `[3, 1]` or `"3,1"`; unset uses the native automatic split |
 | Speculative keys             | various                       | `speculative`, `spec_type`, `spec_draft_n_max/n_min/p_min/p_split`, plus draft-model GPU/cache settings |
 
 ### `[autodiscover]`
@@ -229,7 +304,8 @@ Every generator entry has a `type`, an optional `[generators.backend]` table, an
 
 ```toml
 [[generators]]
-type = "ggml-llm"        # or "ggml-stt" / "ggml-tts" / "mlx-llm"
+type = "ggml-llm"        # or "ggml-stt" / "ggml-tts" / "ggml-decision" / "mlx-llm"
+# enabled = false        # keep the entry but skip it at startup
 
 [generators.backend]
 # (see per-type sections below)
@@ -239,6 +315,11 @@ repo_id = "..."
 # (see per-type sections below)
 ```
 
+| Key                  | Type    | Notes                                                                                     |
+| -------------------- | ------- | ----------------------------------------------------------------------------------------- |
+| `type` *(required)*  | string  | `ggml-llm`, `ggml-stt`, `ggml-tts`, `ggml-decision`, `mlx-llm`, `onnx-stt` or `onnx-tts`   |
+| `enabled`            | boolean | Default `true`. With `false` the server skips the entry at startup: it is not served, announced or pre-downloaded, but stays in the file (the settings window uses this to switch a model off) |
+
 #### Common `[generators.model]` keys
 
 Shared by **all** generator types:
@@ -249,7 +330,7 @@ Shared by **all** generator types:
 | `revision`                | string    | Default `"main"`                                                                 |
 | `download`                | boolean   | Pre-download at server startup (default `false`)                                 |
 
-Additional keys honored by **ggml-llm**, **ggml-stt** and **ggml-tts** (mlx-llm gets quantization from the repo itself and does not use these):
+Additional keys honored by **ggml-llm**, **ggml-stt**, **ggml-tts** and **ggml-decision** (mlx-llm gets quantization from the repo itself and does not use these):
 
 | Key                       | Type      | Notes                                                                            |
 | ------------------------- | --------- | -------------------------------------------------------------------------------- |
@@ -267,6 +348,10 @@ Additional keys honored by **ggml-llm**, **ggml-stt** and **ggml-tts** (mlx-llm
 
 Loads a GGUF LLM. Runtime keys above can be overridden per-generator under `[generators.model]`; `[generators.backend]` only controls backend selection and resource planning.
 
+GPU splitting (`split_mode`, `tensor_split`) is currently configurable only in Buttress.
+TODO: Expose these options in the LLM (GGML) generator. The experimental `tensor` mode
+requires a compatible GPU backend and model architecture.
+
 **`[generators.backend]`**
 
 | Key                   | Type     | Default                                       | Notes                                                            |
@@ -282,6 +367,7 @@ Loads a GGUF LLM. Runtime keys above can be overridden per-generator under `[gen
 | ----------------------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------- |
 | `n_ctx`                                                                       | number           | Context window. Auto-capped at the model's training context.         |
 | `n_gpu_layers`                                                                | number\|`"auto"` | Layers offloaded to GPU (default `"auto"`)                           |
+| `split_mode`, `tensor_split`                                                   | string / number[]\|string | Per-model overrides for the GPU split defaults in `[runtime]`       |
 | `n_batch`                                                                     | number           | Prompt batch size (default `512`)                                    |
 | `embedding`                                                                   | boolean          | Enable llama.cpp embedding mode for a dedicated embedding model (default `false`) |
 | `pooling_type`                                                                | string           | Optional embedding pooling override such as `mean`                   |
@@ -354,12 +440,21 @@ spec_draft_cache_type_v = "f16"
 
 Loads a Whisper GGML model for speech-to-text.
 
+With `@fugood/whisper.node` 1.2.0-rc.0, `snapdragon` enables experimental
+Whisper Hexagon NPU acceleration on Linux arm64 with a working Qualcomm
+HTP/FastRPC runtime. This variant does not include OpenCL. Install it with
+`--ggml-variant=snapdragon` (the default CPU package remains available for fallback).
+The platform package includes the HTP libraries; the loader defaults
+`ADSP_LIBRARY_PATH` to that package directory and `GGML_HEXAGON_NDEV` to `16`,
+without overriding explicit environment values. Hexagon always enables flash
+attention, even when `use_flash_attn` is off.
+
 **`[generators.backend]`**
 
 | Key                   | Type     | Default                       | Notes                              |
 | --------------------- | -------- | ----------------------------- | ---------------------------------- |
-| `variant`             | string   | auto                          | `cuda` / `vulkan` / `default`      |
-| `variant_preference`  | string[] | `["cuda","vulkan","default"]` | Probe order                        |
+| `variant`             | string   | auto                          | `cuda` / `vulkan` / `snapdragon` / `default` |
+| `variant_preference`  | string[] | `["cuda","vulkan","snapdragon","default"]` | Probe order                  |
 | `gpu_memory_fraction` | number   | `0.85`                        |                                    |
 | `cpu_memory_fraction` | number   | `0.5`                         |                                    |
 
@@ -384,7 +479,7 @@ Loads a Whisper GGML model for speech-to-text.
 [[generators]]
 type = "ggml-stt"
 [generators.backend]
-variant_preference = ["cuda", "vulkan", "default"]
+variant_preference = ["cuda", "vulkan", "snapdragon", "default"]
 [generators.model]
 repo_id = "BricksDisplay/whisper-ggml"
 filename = "ggml-large-v3-turbo-q8_0.bin"
@@ -467,6 +562,105 @@ vocoder_batch_size = 4096
 
 ---
 
+### `ggml-decision` (typed decisions via `@fugood/llama.node`)
+
+Loads a typed decision model (System One — Julia-1, Laya, Kev, Jevling, lev,
+...) and answers `choice` / `score` / `noul` questions about a state with
+calibrated probabilities: one forward pass per answer, no generated tokens.
+Clients reach it through the Typed Decision (GGML) generator; local
+functions through `context.buttress.decide`.
+
+The model is checked when its context loads: a GGUF with no decision metadata
+(`<arch>.decision.type`) and no `system_one` template, or one whose decision
+type this build cannot serve, fails the load with the reason. Requests on one
+generator run one at a time.
+
+**Sharing a model with `ggml-llm`** — a model that both generates and decides
+(Jevling, for one) can be configured as both a `ggml-llm` and a
+`ggml-decision`. By default each loads its own context. Set
+`[generators.backend] share_llm_context = true` on the decision entry to run
+its decisions on the LLM's context instead, when the two entries name the same
+weights (same `repo_id`, `revision`, `filename`, `quantization`, `url` and
+`local_path`): the model is then loaded once, with the LLM's config. This
+applies to local functions, the TypeSafe-compatible endpoint and client
+sessions (whose decision runtime options then do not apply).
+
+Sharing trades throughput for memory. A decision takes one of the LLM's
+`n_parallel` slots, and its forward passes run between the LLM's batches, so
+concurrent completions stop generating while it runs (in a CPU test, a
+128-token completion took twice as long beside six decisions; with a separate
+decision context it did not slow down). Results are not affected: the slot's
+sequence and prompt cache are cleared after each decision. Without
+`kv_unified = true` on the LLM a slot holds `n_ctx / n_parallel` tokens, which
+must fit the state plus the questions. The decision loads its own context
+anyway when it sets `rank_pooling` (it needs an embedding context), when its
+projector differs from the LLM's, or when the LLM is embedding or vocab-only.
+The server logs at startup which decision models share.
+
+```toml
+[[generators]]
+type = "ggml-llm"
+[generators.model]
+repo_id = "BricksDisplay/jevling-0.8b-v1-GGUF"
+filename = "jevling-0.8b-v1-q8_0-embf16.gguf"
+[generators.runtime]
+n_ctx = 16384
+
+[[generators]]
+type = "ggml-decision"
+[generators.backend]
+share_llm_context = true
+[generators.model]
+repo_id = "BricksDisplay/jevling-0.8b-v1-GGUF"
+filename = "jevling-0.8b-v1-q8_0-embf16.gguf"
+```
+
+**`[generators.backend]`** — same keys as `ggml-tts` (`variant`,
+`variant_preference`, `gpu_memory_fraction`, `cpu_memory_fraction`).
+
+**`[generators.model]`** — common keys plus:
+
+| Key                       | Type     | Default                          | Notes                                                              |
+| ------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------ |
+| `preferred_quantizations` | string[] | `["q8_0", "q4_k_m", <no-quant>]` | Default fallback chain                                             |
+| `mmproj_repo_id`          | string   | falls back to `repo_id`          | Vision projector repo, for models whose prompt takes images        |
+| `mmproj_filename`         | string   | auto (`*mmproj*`)                | Pin a specific projector artifact                                  |
+| `mmproj_url`              | string   | —                                | Direct projector URL (skips manifest lookup)                       |
+| `mmproj_revision`         | string   | falls back to `revision`         |                                                                    |
+| `mmproj_local_path`       | string   | —                                | Requires `allow_local_file`                                        |
+| `rank_pooling`            | boolean  | `false`                          | `system_one` models with a classification head (`rank_head` readout) |
+| `use_gpu`                 | boolean  | `true`                           | Force-disable GPU even when available                              |
+| `n_gpu_layers`            | number   | `99`                             | Forced to `0` when the GPU is unused                               |
+
+Setting any `mmproj_*` key loads a projector; requests can then pass `images`
+(file paths or data URLs). The projector is ignored, with a warning, when the
+model's prompt has no place for images.
+
+**Runtime extras** — under `[runtime]` for ggml-decision:
+
+| Key                        | Type   | Default         | Notes                                    |
+| -------------------------- | ------ | --------------- | ---------------------------------------- |
+| `n_ctx`                    | number | `4096`          | Must hold the state plus every question  |
+| `n_batch` / `n_ubatch`     | number | `2048` / `512`  |                                          |
+| `max_threads`              | number | auto            | Caps the llama.cpp thread count          |
+| `flash_attn_type`          | string | `auto`          | `auto` / `on` / `off`                    |
+| `context_release_delay_ms` | number | `10000`         | `0` releases the context right away      |
+
+**Example**
+
+```toml
+[[generators]]
+type = "ggml-decision"
+[generators.model]
+repo_id = "ggml-org/Julia-1-GGUF"
+filename = "Julia-1-Q8_0.gguf"
+download = true
+[generators.runtime]
+n_ctx = 4096
+```
+
+---
+
 ### `mlx-llm` (Apple Silicon, Python `mlx-lm` / `mlx-vlm` bridge)
 
 Loads an MLX-format model on Apple Silicon. On first use, the backend creates a virtualenv at `{cache_dir}/mlx-env` and installs `mlx_lm_package`, `mlx_vlm_package`, plus `torch` and `torchvision` (required by some VLM processors). If an existing venv already has `mlx_vlm` and `torch` importable, the install step is skipped. There is no `[generators.backend]` section.
@@ -575,9 +769,12 @@ Buttress server for remote inference with GGML backends.
 
 Usage:
   bricks-buttress [options]
+  bricks-buttress ui [-c] <config.toml>
   bricks-buttress update [--check] [-y] [--channel <release|beta>]
 
 Commands:
+  ui                            Open the settings, status and chat window for a
+                                config file (see `bricks-buttress ui --help`)
   update                        Update bricks-buttress to the latest version.
                                 Standalone binary installs re-run the CDN
                                 installer (refreshing the native-module
@@ -612,7 +809,7 @@ Examples:
 
 ## Compatibility Endpoints (Experimental)
 
-The server can expose OpenAI- and Anthropic-compatible HTTP endpoints in addition to the native RPC. Each endpoint is opt-in via the TOML config:
+The server can expose OpenAI-, Anthropic- and TypeSafe-compatible HTTP endpoints in addition to the native RPC. Each endpoint is opt-in via the TOML config:
 
 ```toml
 [openai_compat]
@@ -622,14 +819,19 @@ enabled = true
 [anthropic_messages]
 enabled = true
 # cors_allowed_origins = ["http://localhost:3000"]
+
+[typesafe_compat]
+enabled = true
 ```
 
 | Endpoint              | Config flag                          |
 | --------------------- | ------------------------------------ |
 | `/oai-compat/v1/*`    | `[openai_compat] enabled = true`     |
 | `/anthropic-messages` | `[anthropic_messages] enabled = true` |
+| `/typesafe-compat/v1/*` | `[typesafe_compat] enabled = true` |
 
-Completion requests may select only LLM models declared in `[[generators]]`. Use each
+Completion requests may select only LLM models declared in `[[generators]]`, and decision
+requests only `ggml-decision` generators. Use each
 endpoint's `GET /v1/models` response for valid model IDs; unknown IDs are rejected before the
 server starts or downloads a generator.
 
@@ -693,6 +895,7 @@ export default async function ({ path }: { path: string }, context: ButtressFunc
 | `buttress.detokenize({ model?, tokens })` | Convert token ids back into text with the same model. |
 | `buttress.transcribe({ model?, filePath \| audioData, options? })` | Transcribe audio with this server's STT generator. |
 | `buttress.synthesize({ model?, text, options? })` | Synthesize speech with this server's TTS generator (`onnx-tts` or `ggml-tts`); the WAV lands in `tempDir` → `{ path, sampling_rate, channels }`. |
+| `buttress.decide({ model?, state, questions, images? })` | Answer typed `choice` / `score` / `noul` questions about `state` with this server's `ggml-decision` generator → `{ model, answers, usage }`. `answers[id]` is typed from its question. `images` are local paths or data URLs. |
 | `bank.list({ keyword?, meta?, ids? })` / `bank.get(id)` / `bank.update(properties, { dontNotify? })` / `bank.remove(id)` | Read/write the bound workspace's remote **Data Bank** (see below). To listen for changes, use `bank.subscribe` inside a daemon function. |
 | `daemons.emit(name, event, data?)` / `daemons.list()` | Signal a running **daemon function**'s `onEvent` handlers (see below) / list running daemon names. |
 | `emit(event, data)` | Progress event; delivered to SSE callers, ignored otherwise. |
@@ -850,6 +1053,208 @@ The handler receives `{ method, path, name?, headers, query, token, workspaceAut
 
 Function files themselves are trusted input, exactly like this config file. They run in a `node:vm` context with a clean global (no ambient `process` or `require`), but that is for clarity, not isolation — a function that is handed `spawn` can do anything the server process can. Only put code you wrote (or reviewed) in the functions directory.
 
+## Agents (Experimental)
+
+Buttress can host **agents**: pi-based LLM loops that run inside the server
+process, use **local functions** (and MCP servers) as their tools, and keep
+**config-scoped sessions** on disk. The primary consumer is automation — a
+local function or daemon calls `context.agents.run(...)` to add multi-step
+reasoning to a server-side workflow; an interactive CLI exists for driving and
+inspecting the same agents.
+
+```toml
+[[agents]]
+name = "ops-assistant"                        # unique; the session scope key
+model = "buttress/ggml-org/gpt-oss-20b-GGUF"  # split on the FIRST slash: provider/model-id
+# model = "anthropic/claude-sonnet-5"         # any pi-supported provider; API key from env
+system_prompt_file = "./prompts/ops.md"       # or inline: system_prompt = "..."
+tools = ["get_server_status", "restart_service"]  # local function names (explicit; no wildcard)
+local_devices = false                        # opt in to LAN scan + device DevTools tools
+max_turns = 30                                 # assistant↔tool round-trips per run (default 30)
+# codemode = true                             # opt in: a sandboxed JS tool that calls the other tools
+# max_tokens_per_run = 200000                 # per-run token budget; unset = unlimited
+# temperature = 0.2                           # unrecognized keys pass through to generation
+
+[agents.mcp_servers.github]                   # optional MCP servers (StreamableHTTP or stdio)
+url = "https://api.githubcopilot.com/mcp/"
+# headers = { Authorization = "Bearer ..." }
+# optional = true                             # continue without this server if it won't connect
+# timeout = 60                                # per-request seconds (progress renews it)
+# exposure = "direct"                         # "hidden": unreachable; "codemode": scripts only (needs codemode = true)
+# tool_exposure = { "delete_*" = "hidden" }   # per tool, by exact name or * pattern
+
+[agents_options]                              # optional; defaults shown
+# sessions_dir = "./.buttress-agent/sessions" # relative to this config file
+# session_max_age = "30d"                     # retention sweep; 0 disables
+# session_max_count = 500                     # per agent; 0 disables
+# max_depth = 2                               # function → agent → function → agent chain cap
+# allow_unauthenticated = false               # serve /agents on an UNBOUND server (see below)
+```
+
+**Models.** `buttress/<repo_id>` targets a configured `[[generators]]` LLM
+(ggml/mlx) and is validated at startup; traffic flows through an in-process
+OpenAI-compat loopback (no socket). The loopback calls the server's own
+`/oai-compat/v1` routes, which exist only with `[openai_compat] enabled = true`
+(or `ENABLE_OPENAI_COMPAT_ENDPOINT=1`): an agent with a `buttress/…` model
+needs it, or every run fails with `404 NOT_FOUND`. Any other provider prefix is a pi
+built-in provider (`anthropic/…`, `openai/…`, `google/…`, …) authenticated by
+its usual environment variable (`ANTHROPIC_API_KEY`, …) — set it via `[env]`
+or the process environment. OAuth-based logins are not supported headless.
+
+**Tools.** `tools` lists local function names explicitly. Each tool call runs
+through the normal functions executor (same lazy reload, scratch dir, spawn
+tracking, and the function's own `meta.timeout` deadline), and aborting the
+run aborts in-flight tool calls and their spawned processes. A listed function
+that is missing fails the run loudly rather than letting a headless automation
+improvise around it. MCP tools get server-qualified names
+(`mcp__github__create_issue`; characters outside `[A-Za-z0-9_]` become `_`);
+MCP servers connect lazily on the first run and fail closed unless marked
+`optional = true`.
+
+**Codemode.** `codemode = true` on an `[[agents]]` entry (default `false`) adds a
+`codemode` tool: the model writes JavaScript that runs in a QuickJS sandbox and
+calls the agent's other tools (`await tools.<name>(args)`), so it can batch calls
+and filter large results before they reach the context. MCP servers of such an
+agent may use `exposure = "codemode"` (or `"deferred"`) to keep their tools out
+of the model's tool list; scripts find them with `searchTools()`.
+`models.classify()` runs pi-ai classifier models with the agent's credentials,
+including this server's decision generators (`buttress/<ggml-decision id>`).
+Small local models may write poor scripts — prefer it with capable models.
+
+**Decisions (System One).** `decision_model` gives an agent a typed-decision
+model: `buttress/<ggml-decision id>` (as `GET /typesafe-compat/v1/models` lists
+it), or a hosted classifier such as `typesafe/jev-latest` (`TYPESAFE_API_KEY`;
+the questions and the state are then sent to TypeSafe). Unset means no
+decisions; it never falls back to the chat model.
+
+```toml
+[[agents]]
+name = "ops-assistant"
+model = "buttress/unsloth/Qwen3.5-4B-GGUF"
+tools = ["host-info"]
+decision_model = "buttress/BricksDisplay/jevling-e2b-v1-GGUF:jevling-e2b-v1-q8_0-embf16.gguf"
+decision_assistance = true   # opt-in tool prefilter (default false)
+# decision_timeout_ms = 500  # prefilter deadline; past it the run keeps every tool
+```
+
+- With a `decision_model`, the agent gets a `decision_evaluate` tool. The model
+  calls it itself with a `state` and `choice` / `score` / `bool` questions, and
+  gets calibrated probabilities back. The tool sees only that state, not the
+  conversation. Its answers are evidence for the model, not permission.
+- With `decision_assistance = true` too, a tool prefilter runs before each run.
+  It asks three yes/no questions about the request: does it need live facts
+  about the system, does it ask for an action (or approve/retry one), and does
+  it point at something not in the conversation. Only when all three are
+  clearly no (each probability < 0.35) does the run go out **without tool
+  definitions**: a shorter prompt for greetings, thanks, explanations or
+  translations. Anything else, including a timeout or an error, keeps every
+  tool. It sends the request, the nearest user/assistant text (≤ 6,000
+  characters) and the tool names; never tool arguments, results or reasoning.
+  The server logs each outcome (`tool prefilter pruned|kept …`).
+- The prefilter never adds or allows a tool; it only withholds them for one
+  run. Small decision models judge it less reliably: jevling-0.8b pruned some
+  live-fact questions that need a tool, jevling-e2b kept them (about 170 ms per
+  run on a GPU). The first run after start may time out while the model loads.
+
+**Local devices.** Set `local_devices = true` on an individual `[[agents]]` entry
+(default `false`) to add just two built-in tools, independently of local functions/MCP:
+
+- `devices_scan`: the same UDP + HTTP LAN discovery as `bricks devtools scan`,
+  including project previews found relative to the Buttress config directory.
+- `devtools`: one action-based tool for screenshots (inline images), brick tree/query,
+  tap/key/text input, console capture, JavaScript evaluation, storage overview, and
+  raw CDP requests for other supported operations. Reuses the CLI CDP transport and
+  shared DevTools operations; no CLI subprocess or separate tool per device/action.
+
+For example, scan with `{}` then call `devtools` with
+`{ "action": "tree", "address": "192.168.1.42", "port": 19851 }`.
+After `bricks buttress bind` and a restart, the workspace credential is injected
+server-side automatically when the device advertises the same workspace and issuer.
+The token is validated for signature, kind and expiry before use; inbound Buttress
+JWTs (`k: "ba"`) are never forwarded. Older bindings without the credential, or expired
+credentials, require rebinding and a restart. The server does not read the CLI login
+or renew tokens itself. Local previews can still use advertised inspect credentials;
+explicit `passcode` / `accessToken` arguments remain optional overrides. Calls open/close their own connection;
+avoid parallel calls or other inspectors on the same device (one CDP client at a time).
+
+**Security:** enabling this option grants network discovery and device control,
+including arbitrary JavaScript evaluation on reachable authenticated devices. It is
+not read-only or a network sandbox. Automatic authentication requires a **trusted LAN**:
+workspace/issuer hints from device info are not cryptographic peer authentication.
+The stored token is never inserted into model arguments and is redacted from text
+results/errors before truncation. Explicit credentials supplied in arguments still
+enter session transcripts, as do console output and device data; prefer automatic
+authentication and only grant this to trusted agents/callers. Disable with `local_devices = false` and
+restart Buttress. Aborting closes active CDP connections; discovery completes its
+bounded scan before returning the abort result.
+
+**Sessions.** Each run returns a `sessionId`; pass it back to continue the
+conversation, or add `fork: true` to branch it into a fresh session. Sessions
+are JSONL files under `sessions_dir`, scoped by agent name (renaming an agent
+orphans its sessions), written as the run streams — an aborted or timed-out
+run still leaves a continuable transcript. Same-session runs queue; different
+sessions run in parallel. A retention sweep prunes by age and count.
+
+**From a local function** (the primary surface):
+
+```ts
+export default async ({ service }, context) => {
+  const result = await context.agents.run('ops-assistant', {
+    prompt: `Investigate the '${service}' service and fix it if needed.`,
+    // sessionId, fork, onEvent are also accepted
+  })
+  return { conclusion: result.content, sessionId: result.sessionId }
+}
+```
+
+`context.agents.run` resolves within the caller's lifetime and deadline
+(`context.signal` aborts it); long-running agent work belongs in a **daemon**
+(no deadline) or a function with a raised `meta.timeout`. `context.agents.list()`
+and `context.agents.sessions(name)` round out the surface. Chained invocations
+(a tool function calling another agent) are capped by `agents_options.max_depth`.
+
+**HTTP endpoints** (also what the CLI uses):
+
+```
+GET  /agents                           { agents: names, details: [{ name, model, tools,
+                                       mcpServers, maxTurns, localDevices, codemode,
+                                       decisionModel }] }
+POST /agents/:name/run                 { prompt, sessionId?, fork? }; ?stream=1 for SSE
+                                       (a `session` event with the id arrives first,
+                                       then `agent` events, then `result`/`error`)
+GET  /agents/:name/sessions            newest-first summaries (id, timestamps, preview)
+GET  /agents/:name/sessions/:id        full transcript
+POST /agents/:name/sessions/:id/abort  abort the active run
+```
+
+`details` has, per agent, its `model` reference (`provider/model-id`), its local function `tools`, the names of its `mcpServers` (never their urls, commands, headers or env), `maxTurns`, `localDevices`, `codemode` and `decisionModel` (`null` when unset).
+
+The `agent` events are pi agent events made small for the wire. `message_update` carries only the delta (`event: { type, contentIndex, delta }`), `message_start` / `message_end` only the `role`, and `tool_execution_end` carries `toolCallId`, `toolName`, `isError` and `result: { text, images, truncated }`: the text blocks of the tool result joined by newlines (`null` when there are none), cut after 4,000 characters with a trailing `…` (then `truncated` is `true`), and the number of images. Image data is never streamed; the transcript has the full result. `tool_emit` (a local function's `context.emit` progress) carries `toolCallId`, `toolName`, `event` and `data`: the calls of one turn run in parallel, so the call id tells two calls of the same tool apart.
+
+Auth mirrors the functions surface, not the open inference endpoints: a bound
+server requires a workspace JWT; an **unbound server rejects remote calls**
+unless `allow_unauthenticated = true`. The server also writes an ephemeral
+internal token to `<sessions_dir>/../runtime-token` (mode 0600) at startup —
+same-host CLIs authenticate with it automatically, bound or not.
+
+**Interactive CLI**:
+
+```sh
+bricks-buttress agent -c config.toml                 # list agents
+bricks-buttress agent ops-assistant -c config.toml   # chat (streams text, thinking, tool calls)
+bricks-buttress agent ops-assistant --sessions -c config.toml
+bricks-buttress agent ops-assistant --session <id> -c config.toml   # continue
+bricks-buttress agent ops-assistant --fork <id> -c config.toml      # fork, then continue the fork
+```
+
+On a real terminal the chat runs a pi-tui interface (markdown answers, dim
+thinking, tool-call lines, Ctrl+C aborts the running turn); pipes/scripts —
+or `--plain` — get a line-based renderer with identical semantics.
+
+Like function files, agent definitions are trusted input: an agent is only as
+safe as the functions and MCP servers you hand it.
+
+
 ## Session State Cache
 
 The server supports session state caching for ggml-llm generators, which saves KV cache state to disk after completions. This enables:

package/config/function-samples/README.md

@@ -14,6 +14,7 @@ needed. On first start the server scaffolds `buttress-functions.d.ts` and a
 | `simple-rag.ts` | Token chunking, embeddings, `sqlite3` + `sqlite-vec` retrieval, then completion | a chat LLM + a GGML embedding `[[generators]]` entry (below) |
 | `transcribe-media.ts` | `context.spawn` (ffmpeg), the scratch dir, SSE progress, STT | `ffmpeg` on PATH + an STT `[[generators]]` entry |
 | `text-to-speech.ts` | TTS (`context.buttress.synthesize`) + downloadable output (`context.fileUrl`) | an `onnx-tts` `[[generators]]` entry |
+| `classify-ticket.ts` | Typed decisions (`context.buttress.decide`): a choice, a score and yes/no flags with calibrated probabilities | a `ggml-decision` `[[generators]]` entry |
 | `bank-note.ts` | Reading/writing the workspace's remote Data Bank (`context.bank`) | `bricks buttress bank-key` run on this host |
 | `bank-watch-daemon.ts` | A daemon (`meta.daemon = true`): `context.bank.subscribe`, `context.setInterval`, `context.onEvent` | `bricks buttress bank-key` run on this host |
 | `_auth.ts` | Custom auth: keep workspace tokens working, add static API keys | see the file header |