@fugood/buttress-server 2.25.0-beta.9 → 2.25.1-beta.0

package/README.md

@@ -20,73 +20,400 @@ npx bricks-buttress --config ./config.toml
 npx bricks-buttress
 ```
 
+## 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.
+
+The `bricks` CLI is the tool that performs the binding and writes the local state file. Install it first — see the [bricks-cli docs](https://docs.bricks.tools/cli) — then `bricks auth login` with the workspace owner's account before running the commands below.
+
+### Bind a server to a workspace
+
+```bash
+# Pair the local machine's buttress-server with the workspace of the current bricks-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
+```
+
+The state file (`~/.bricks-cli/buttress/state.json` by default, or `$BRICKS_BUTTRESS_STATE_DIR`) stores:
+
+- `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
+
+**Restart `bricks-buttress` after binding** for the change to take effect — the state file is read once at startup.
+
+### Inspect bindings
+
+```bash
+# Show local state.json + the workspace-side bound list
+bricks buttress status
+
+# Same, JSON-formatted
+bricks buttress status --json
+```
+
+### Discover servers on the LAN
+
+```bash
+# UDP scan + HTTP /buttress/info verification (3s timeout by default)
+bricks buttress scan
+
+# UDP only (skip the /buttress/info round-trip)
+bricks buttress scan --udp-only
+
+# Machine-readable
+bricks buttress scan --json
+```
+
+`scan` lists every buttress-server visible on the LAN, including unbound (public) ones, with their version, auth state (`open` vs `JWT required` + kid), bound workspace, and per-generator hardware caps (`score`, GPU, usable memory). Servers whose workspace matches your current `bricks-cli` profile are highlighted; this is purely a discovery command and does not mint any tokens.
+
+### Unbind
+
+```bash
+# Remove the binding from the workspace and delete the local state.json
+bricks buttress unbind
+
+# Keep the local state file (useful if you only want to revoke server-side)
+bricks buttress unbind --keep-local
+```
+
+After unbinding, restart the server to return it to public mode.
+
+### Issue a long-lived access token
+
+For headless callers (CI, ctor agents) that already hold a workspace token, mint a long-lived buttress access token instead of relying on a per-launcher session token:
+
+```bash
+# Default 30-day TTL
+bricks buttress issue-token
+
+# Custom TTL (seconds), JSON output for scripting
+bricks buttress issue-token --ttl 3600 --json
+```
+
+The token claims `{ k: 'ba', w_id, st: 'ws', sid, jti, exp }` and any buttress-server bound to the same workspace will accept it.
+
 ## Configuration
 
-Configuration can be provided via:
-- `--config` / `-c` flag with TOML file path
+Configuration is loaded from a TOML file passed via `--config` / `-c`. Every top-level table is optional — missing sections fall back to defaults. See `config/sample.toml` for an end-to-end example.
 
-### Configuration Format (TOML)
+### Top-level sections
+
+| Section                   | Purpose                                                                                            |
+| ------------------------- | -------------------------------------------------------------------------------------------------- |
+| `[env]`                   | Environment variables exported into the process **only if not already set**                        |
+| `[server]`                | HTTP/RPC listener (port, log level, body limits)                                                   |
+| `[runtime]`               | Global defaults shared by every generator (most `[generators.model]` keys may live here too)       |
+| `[runtime.session_cache]` | KV-cache reuse store — see [Session State Cache](#session-state-cache)                             |
+| `[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)|
+| `[functions]`             | Enable local functions — see [Local Functions](#local-functions-experimental)                      |
+| `[[generators]]`          | Array of generator instances — one entry per loaded model                                          |
+
+### `[env]`
 
 ```toml
-# Environment variables (only set if not already defined in system)
 [env]
-HF_TOKEN = "your_huggingface_token_here"
+HUGGINGFACE_TOKEN = "hf_xxx"   # ggml backends read this; HF_TOKEN is not picked up automatically
 CUDA_VISIBLE_DEVICES = "0"
+```
 
-[server]
-port = 2080
-log_level = "info"
+Values here are exported only when the variable isn't already set in the process — see [Environment Variable Priority](#environment-variable-priority). For HuggingFace auth across all backends, `[runtime] huggingface_token = "hf_xxx"` works regardless of variable name.
+
+### `[server]`
+
+| Key               | Type           | Default                                                                |
+| ----------------- | -------------- | ---------------------------------------------------------------------- |
+| `id`              | string         | `buttress-<machineId>` — stable id used for autodiscover / binding     |
+| `name`            | string         | `Buttress Server (<short id>)` — display name                          |
+| `port`            | number         | `2080` (overridden by `--port`)                                        |
+| `log_level`       | `"debug"`/`"info"`/`"warn"`/`"error"` | unset                                          |
+| `max_body_size`   | string\|number | `"50MB"` — e.g. `"100MB"`, `"1GB"`, or raw bytes                       |
+| `session_timeout` | string\|number | `60000` ms — accepts ms numbers or duration strings (`"30s"`)          |
+| `temp_file_dir`   | string         | `$TMPDIR/.buttress`                                                    |
+
+### `[runtime]` — global generator defaults
+
+Most ggml-llm `[generators.model]` keys can also live in `[runtime]` as defaults. Per-generator values win; otherwise the runtime default applies.
+
+| Key                          | Type                          | Notes                                                                  |
+| ---------------------------- | ----------------------------- | ---------------------------------------------------------------------- |
+| `cache_dir`                  | string                        | Model + metadata cache root (default `~/.buttress/models`)             |
+| `huggingface_token`          | string                        | Falls back to `$HUGGINGFACE_TOKEN`                                     |
+| `http_headers`               | table                         | Extra headers attached to HF / HTTP downloads                          |
+| `context_release_delay_ms`   | number                        | Idle time before unloading a context (default `10000`; `0` = immediate)|
+| `prefer_variants`            | string[]                      | Override variant probe order (ggml backends)                           |
+| `n_threads`                  | number                        | CPU thread count                                                       |
+| `n_ctx`                      | number                        | Context window (per-model value wins; auto-capped at training context) |
+| `n_gpu_layers`               | number\|`"auto"`              | Layers offloaded to GPU (default `"auto"`)                             |
+| `n_batch` / `n_ubatch`       | number                        | Prompt batch / micro-batch size. **Note:** `n_batch` has a model-level default of `512` that shadows the runtime value unless `[generators.model] n_batch` is set explicitly. |
+| `n_parallel`                 | number                        | Parallel sequences (default `4`)                                       |
+| `n_cpu_moe`                  | number                        | MoE expert layers offloaded to CPU                                     |
+| `flash_attn_type`            | `"on"` / `"off"` / `"auto"`   | When a GPU backend is selected, defaults to `"auto"`; on CPU, defaults to `"off"`. Explicit `"on"` / `"off"` / `"auto"` overrides. |
+| `cache_type_k`, `cache_type_v` | string                      | KV-cache dtype (`f16`, `f32`, `q8_0`, `q4_0`, …)                       |
+| `kv_unified`                 | boolean                       | Use a unified KV cache across sequences                                |
+| `swa_full`                   | boolean                       | Materialize full attention even for sliding-window layers              |
+| `ctx_shift`                  | boolean                       | Allow llama.cpp's rolling context shift                                |
+| `use_mmap`, `use_mlock`      | boolean                       | Memory-mapping / locking                                               |
+| `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                                      |
+| Speculative keys             | various                       | `speculative`, `spec_type`, `spec_draft_n_max/n_min/p_min/p_split`, plus draft-model GPU/cache settings |
+
+### `[autodiscover]`
+
+Set `autodiscover = true` for defaults, `false` (or omit) to disable, or a table for fine control:
 
-[runtime]
-cache_dir = "~/.buttress/models"
+```toml
+[autodiscover]
+udp.port = 8089
+udp.announcements = { enabled = true, interval = 5000 }
+udp.requests       = { enabled = true, responseDelay = 100 }
+http.enabled = true
+http.path    = "/buttress/info"
+http.cors    = true
+# mdns.enabled = false   # Bonjour/Avahi advertisement (optional)
+```
 
-# Session state cache for ggml-llm (saves KV cache to disk for prompt reuse)
-[runtime.session_cache]
-enabled = true
-max_size_bytes = "10GB"  # Supports string (e.g., "10GB", "500MB") or number
-max_entries = 1000
+### `[[generators]]`
+
+Every generator entry has a `type`, an optional `[generators.backend]` table, and a `[generators.model]` table:
+
+```toml
+[[generators]]
+type = "ggml-llm"        # or "ggml-stt" / "mlx-llm"
 
-# GGML LLM generator
+[generators.backend]
+# (see per-type sections below)
+
+[generators.model]
+repo_id = "..."
+# (see per-type sections below)
+```
+
+#### Common `[generators.model]` keys
+
+Shared by **all** generator types:
+
+| Key                       | Type      | Notes                                                                            |
+| ------------------------- | --------- | -------------------------------------------------------------------------------- |
+| `repo_id` *(required)*    | string    | HuggingFace repo (`org/repo`)                                                    |
+| `revision`                | string    | Default `"main"`                                                                 |
+| `download`                | boolean   | Pre-download at server startup (default `false`)                                 |
+
+Additional keys honored by **ggml-llm** and **ggml-stt** (mlx-llm gets quantization from the repo itself and does not use these):
+
+| Key                       | Type      | Notes                                                                            |
+| ------------------------- | --------- | -------------------------------------------------------------------------------- |
+| `filename`                | string    | Pin a specific artifact in the repo                                              |
+| `url`                     | string    | Direct download URL (skips manifest lookup)                                      |
+| `quantization`            | string    | Preferred quant tag — e.g. `q4_0`, `q8_0`, `mxfp4`                               |
+| `preferred_quantizations` | string[]  | Ordered fallback list when `quantization` doesn't match (alias: `quantizations`) |
+| `allow_local_file`        | boolean   | Required to use `local_path` / `mmproj_local_path`                               |
+| `local_path`              | string    | Use a local file as the load path. Repo metadata is still resolved from HF, so `repo_id` is still required. |
+| `api_base`, `base_url`    | string    | Override HF API / blob hosts (mirrors / proxies)                                 |
+
+---
+
+### `ggml-llm` (llama.cpp via `@fugood/llama.node`)
+
+Loads a GGUF LLM. Runtime keys above can be overridden per-generator under `[generators.model]`; `[generators.backend]` only controls backend selection and resource planning.
+
+**`[generators.backend]`**
+
+| Key                   | Type     | Default                                       | Notes                                                            |
+| --------------------- | -------- | --------------------------------------------- | ---------------------------------------------------------------- |
+| `variant`             | string   | auto                                          | Force `cuda` / `vulkan` / `snapdragon` / `default`               |
+| `variant_preference`  | string[] | `["cuda","vulkan","snapdragon","default"]`    | Probe order when `variant` is unset                              |
+| `gpu_memory_fraction` | number   | `0.85`                                        | Max GPU fraction the hardware guardrails may plan against        |
+| `cpu_memory_fraction` | number   | `0.5`                                         | Max RAM fraction for CPU-side buffers                            |
+
+**`[generators.model]`** — in addition to the common keys above:
+
+| Key                                                                           | Type             | Notes                                                                |
+| ----------------------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------- |
+| `n_ctx`                                                                       | number           | Context window. Auto-capped at the model's training context.         |
+| `n_gpu_layers`                                                                | number\|`"auto"` | Layers offloaded to GPU (default `"auto"`)                           |
+| `n_batch`                                                                     | number           | Prompt batch size (default `512`)                                    |
+| `n_ubatch`, `n_threads`, `n_parallel`, `n_cpu_moe`                            | number           | Same semantics as the `[runtime]` defaults                           |
+| `flash_attn_type`, `cache_type_k`, `cache_type_v`, `kv_unified`, `swa_full`, `ctx_shift`, `use_mmap`, `use_mlock`, `no_extra_bufts`, `cpu_mask`, `cpu_strict`, `devices` | various | Per-model overrides for the `[runtime]` defaults |
+
+**Multimodal (mtmd)** — auto-downloads the matching `mmproj-*.gguf` from the same repo and calls `initMultimodal`:
+
+| Key                       | Type    | Notes                                                              |
+| ------------------------- | ------- | ------------------------------------------------------------------ |
+| `enable_mtmd`             | boolean | Default `false`                                                    |
+| `mmproj_filename`         | string  | Pin a specific projector file                                      |
+| `mmproj_url`              | string  | Direct URL override                                                |
+| `mmproj_local_path`       | string  | Local projector (requires `allow_local_file = true`)               |
+| `mmproj_use_gpu`          | boolean | `null` = auto (true when `n_gpu_layers > 0`)                       |
+| `mmproj_image_min_tokens` | number  | Min visual tokens (dynamic-resolution models; `-1` = unset)        |
+| `mmproj_image_max_tokens` | number  | Max visual tokens (`-1` = unset)                                   |
+
+**Speculative decoding**
+
+`model_draft` may be a direct URL/path string or a table with the same
+`repo_id`/`filename`/`url`/`local_path` model keys described above. Local draft paths require
+`allow_local_file = true`. When `download = true`, Buttress pre-downloads both target and draft
+models and includes both in its memory plan.
+
+| Key                        | Type            | Notes                                                        |
+| -------------------------- | --------------- | ------------------------------------------------------------ |
+| `model_draft`              | string \| table | Optional separate GGUF draft model                           |
+| `speculative`              | bool \| string \| table | Enable speculative decoding and optionally select a strategy |
+| `spec_type`                | string          | Strategy, such as `"draft-mtp"`                              |
+| `spec_draft_n_max`         | int             | Max drafted tokens per step                                  |
+| `spec_draft_n_min`         | int             | Min drafted tokens                                           |
+| `spec_draft_p_min`         | number          | Min acceptance probability                                   |
+| `spec_draft_p_split`       | number          | Split threshold                                              |
+| `spec_draft_n_gpu_layers`  | int             | Draft-model layers offloaded to GPU (`-1` auto, `-2` all)    |
+| `spec_draft_cache_type_k`  | string          | Draft-model K-cache dtype                                    |
+| `spec_draft_cache_type_v`  | string          | Draft-model V-cache dtype                                    |
+
+**Example**
+
+```toml
 [[generators]]
 type = "ggml-llm"
 [generators.backend]
 variant_preference = ["cuda", "vulkan", "default"]
+gpu_memory_fraction = 0.95
 [generators.model]
 repo_id = "ggml-org/gpt-oss-20b-GGUF"
 quantization = "mxfp4"
 n_ctx = 12800
+download = true
+```
+
+A separate draft model can be configured inline:
+
+```toml
+[generators.model]
+repo_id = "org/target-model-GGUF"
+model_draft = { repo_id = "org/draft-model-GGUF", filename = "draft-q8_0.gguf" }
+speculative = { type = "draft-mtp" }
+spec_draft_n_max = 4
+spec_draft_n_gpu_layers = -1
+spec_draft_cache_type_k = "f16"
+spec_draft_cache_type_v = "f16"
+```
+
+---
+
+### `ggml-stt` (whisper.cpp via `@fugood/whisper.node`)
+
+Loads a Whisper GGML model for speech-to-text.
 
-# GGML STT (Speech-to-Text) generator
+**`[generators.backend]`**
+
+| Key                   | Type     | Default                       | Notes                              |
+| --------------------- | -------- | ----------------------------- | ---------------------------------- |
+| `variant`             | string   | auto                          | `cuda` / `vulkan` / `default`      |
+| `variant_preference`  | string[] | `["cuda","vulkan","default"]` | Probe order                        |
+| `gpu_memory_fraction` | number   | `0.85`                        |                                    |
+| `cpu_memory_fraction` | number   | `0.5`                         |                                    |
+
+**`[generators.model]`** — common keys plus:
+
+| Key                       | Type                          | Default                          | Notes                                                |
+| ------------------------- | ----------------------------- | -------------------------------- | ---------------------------------------------------- |
+| `repo_id`                 | string                        | `"BricksDisplay/whisper-ggml"`   | Defaulted (unlike ggml-llm)                          |
+| `preferred_quantizations` | string[]                      | `["q8_0", <no-quant>, "q5_1"]`   | Default fallback chain                               |
+| `use_gpu`                 | boolean                       | `true`                           | Force-disable GPU even when available                |
+| `use_flash_attn`          | `"on"` / `"off"` / `"auto"` / boolean | `"auto"`                 | `"auto"` enables flash-attn when GPU is in use. `true`/`false` are accepted as shortcuts for `"on"`/`"off"`. |
+
+**Runtime extras** — under `[runtime]` for ggml-stt only:
+
+| Key           | Type   | Notes                                       |
+| ------------- | ------ | ------------------------------------------- |
+| `max_threads` | number | Caps the whisper.cpp thread count           |
+
+**Example**
+
+```toml
 [[generators]]
 type = "ggml-stt"
 [generators.backend]
-variant_preference = ["coreml", "default"]
+variant_preference = ["cuda", "vulkan", "default"]
 [generators.model]
 repo_id = "BricksDisplay/whisper-ggml"
-filename = "ggml-small.bin"
+filename = "ggml-large-v3-turbo-q8_0.bin"
+use_gpu = true
+use_flash_attn = "on"
+download = true
+```
+
+---
+
+### `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.
+
+**`[generators.model]`** — common `repo_id` / `revision` / `download` plus:
+
+| Key                | Type                | Default   | Notes                                                                         |
+| ------------------ | ------------------- | --------- | ----------------------------------------------------------------------------- |
+| `adapter_path`     | string              | —         | Local LoRA adapter directory                                                  |
+| `vlm`              | `"auto"` / boolean  | `"auto"`  | Force VLM (`true`) vs text-only (`false`); `"auto"` infers from the repo      |
+| `tokenizer_config` | table               | —         | Forwarded to `mlx_lm.load(..., tokenizer_config=...)`                         |
+| `model_config`     | table               | —         | Forwarded to `mlx_lm.load(..., model_config=...)`                             |
+
+`quantization`, `filename`, and `preferred_quantizations` are **not** used — the MLX repo itself determines the quantization.
+
+**Runtime extras** — under `[runtime]` for mlx-llm:
+
+| Key                 | Type   | Default                       | Notes                                                                |
+| ------------------- | ------ | ----------------------------- | -------------------------------------------------------------------- |
+| `mlx_env_dir`       | string | `{cache_dir}/mlx-env`         | Location of the auto-managed Python venv                             |
+| `mlx_lm_package`    | string | `"mlx-lm==0.31.1"`            | pip spec used when provisioning the venv                             |
+| `mlx_vlm_package`   | string | `"mlx-vlm==0.4.0"`            | pip spec used when provisioning the venv                             |
+| `session_cache.*`   | table  | enabled, `5GB`, 100 entries   | Separate cache from ggml-llm (lives in `{cache_dir}/mlx-session-cache`) |
+
+**Example**
+
+```toml
+[[generators]]
+type = "mlx-llm"
+[generators.model]
+repo_id = "mlx-community/Qwen2.5-VL-3B-Instruct-4bit"
+vlm = true
+download = true
 ```
 
 ### Programmatic Usage
 
+`startServer` takes a processed config — run raw (TOML-shaped) input through `processConfig` first. Optional endpoint families are enabled with explicit flags, mirroring what the CLI resolves from the TOML and environment.
+
 ```javascript
-import { startServer } from '@fugood/buttress-server'
+import { startServer, processConfig } from '@fugood/buttress-server'
+import { resolveFunctionsConfig } from '@fugood/buttress-server'
+
+const config = processConfig({
+  server: { port: 3000 },
+  runtime: { cache_dir: './.buttress-cache' },
+  generators: [
+    {
+      type: 'ggml-llm',
+      model: {
+        repo_id: 'ggml-org/gemma-3-270m-qat-GGUF',
+        quantization: 'mxfp4',
+      },
+    },
+  ],
+})
 
 startServer({
-  port: 3000,
-  defaultConfig: {
-    runtime: {
-      cache_dir: './.buttress-cache'
-    },
-    generators: [
-      {
-        type: 'ggml-llm',
-        model: {
-          repo_id: 'ggml-org/gemma-3-270m-qat-GGUF',
-          quantization: 'mxfp4',
-        }
-      }
-    ]
-  }
+  config,
+  enableOpenAICompat: false,
+  enableAnthropicMessages: false,
+  // Omit (or pass null) to leave local functions off.
+  functions: resolveFunctionsConfig(config.global, { configDir: process.cwd() }),
 })
   .then(({ port }) => {
     console.log(`Server running on port ${port}`)
@@ -94,6 +421,8 @@ startServer({
   .catch(console.error)
 ```
 
+Note that the `[env]` table is applied by the CLI entrypoint only — a programmatic caller sets `process.env` itself.
+
 ### Environment Variable Priority
 
 Environment variables can be set in the `[env]` section of the TOML config. These values will **only be applied if the environment variable is not already set** in the system. This allows:
@@ -176,6 +505,148 @@ enabled = true
 | `/oai-compat/v1/*`    | `[openai_compat] enabled = true`     |
 | `/anthropic-messages` | `[anthropic_messages] enabled = true` |
 
+## Local Functions (Experimental)
+
+Local functions are `.ts`/`.js` files you drop into a directory on the server. Each one becomes an MCP tool **and** an HTTP endpoint, so an agent (or any HTTP client) can run server-side work — shelling out to `ffmpeg`, calling this server's own LLM/STT generators — without you writing a service.
+
+> **Experimental.** This entire surface — the endpoints, the function file contract, the `context` API, custom `_auth`, and the `[functions]` config keys — may change between releases without a deprecation window. The server says so at startup. Pin your `@fugood/bricks-buttress` version if you build on it, and re-check this section after upgrades.
+
+```toml
+[functions]
+enabled = true
+dir = "./functions"           # relative paths resolve against this config file
+# allow_unauthenticated = false   # see Security below
+# default_timeout = "5m"          # per-call deadline; override per function via meta.timeout
+# hot_reload = false              # watch the dir and reload eagerly on change (see below)
+
+[functions.config]            # optional; handed to functions as `context.config`
+# api_base = "https://example.internal"
+```
+
+`ENABLE_FUNCTIONS_ENDPOINT=1` and `BUTTRESS_FUNCTIONS_DIR=<dir>` are equivalent to the first two keys.
+
+On startup the server creates the directory if needed and writes `buttress-functions.d.ts` (ambient types, refreshed every start), plus a `tsconfig.json` and a commented `_example.ts` when the directory holds no functions yet.
+
+Ready-to-copy examples — a no-prerequisite starter, LLM summarization, ffmpeg + STT transcription, TTS with a downloadable result, and a custom auth gate — live in [`config/function-samples/`](config/function-samples/).
+
+### Writing a function
+
+The file name is the tool name — `video-duration.ts` becomes `video-duration`. Files beginning with `_`, `.d.ts` files, and `*.test.*` / `*.spec.*` files are ignored, as are subdirectories (which are for helper modules).
+
+```ts
+export const meta: ButtressFunctionMeta = {
+  description: 'Transcribe the audio track of a video file',
+  parameters: {
+    type: 'object',
+    properties: { path: { type: 'string' } },
+    required: ['path'],
+  },
+  timeout: '10m',
+}
+
+export default async function ({ path }: { path: string }, context: ButtressFunctionContext) {
+  const wav = `${context.tempDir}/audio.wav`
+  const { code, stderr } = await context.spawn('ffmpeg', ['-i', path, '-ar', '16000', wav])
+  if (code !== 0) throw new Error(`ffmpeg failed: ${stderr}`)
+
+  context.emit('progress', { stage: 'transcribing' })
+  return context.buttress.transcribe({ filePath: wav })
+}
+```
+
+`meta.parameters` is plain JSON Schema and is handed to MCP clients verbatim. The default export receives the parsed input object and a context:
+
+| Context member | What it does |
+| -------------- | ------------ |
+| `spawn(cmd, args?, opts?)` | Run a child process; resolves `{ code, signal, stdout, stderr, truncated }`. A non-zero exit resolves — check `code`. Every child is killed when the call ends. |
+| `buttress.completion({ model?, messages, max_tokens?, onToken?, … })` | Run a chat completion on this server's LLM generator. `messages` go through the model's chat template; thinking is off unless you pass `enable_thinking: true` (which fills `reasoning_content`). Other keys reach the backend verbatim. |
+| `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`); the WAV lands in `tempDir` → `{ path, sampling_rate, channels }`. |
+| `emit(event, data)` | Progress event; delivered to SSE callers, ignored otherwise. |
+| `signal` | `AbortSignal`, aborted on timeout or caller disconnect. |
+| `tempDir` | Per-call scratch directory, created on first access. |
+| `fileUrl(path)` | Download URL (`/functions/files/…`) for a file inside `tempDir`, so callers can fetch outputs without filesystem access. |
+| `log`, `fetch`, `env`, `config`, `dir` | Prefixed logging, host `fetch`, `process.env`, the `[functions.config]` table, the functions directory. |
+| `libs` | `_`/`lodash`, `moment`, `math`/`mathjs`, `voca`, `chroma`, `json5`, `qs`, `bytes`, `ms`, `nanoid`, `md5`. |
+
+Functions may `import` Node builtins (`node:fs/promises`, …) and sibling files inside the functions directory. Package imports are not supported.
+
+Edits are picked up on the next call — the server re-transpiles when a file in the function's module graph changes, so no restart is needed. A file that fails to load is logged and skipped; the rest keep working.
+
+For faster authoring feedback, opt into eager reloading with `[functions] hot_reload = true` (or `BUTTRESS_FUNCTIONS_HOT_RELOAD=1`): the server watches the directory and reloads on save, so a broken file is logged the moment you save it, and the function count in `/status` and discovery announcements moves without waiting for a call. The lazy mtime check keeps running either way — hot reload only adds immediacy, so a missed watch event costs nothing. On platforms without recursive `fs.watch` the server logs a warning and stays lazy.
+
+### Endpoints
+
+| Endpoint | Purpose |
+| -------- | ------- |
+| `GET /functions` | List callable functions with their JSON Schemas |
+| `POST /functions/<name>` | Run one; JSON body = input object, response is `{ "result": … }`. A multipart body stages its file fields inline (see below) |
+| `POST /functions/<name>?stream=1` | Same, as SSE: `progress` events (from `context.emit`) then `result` or `error` |
+| `POST /functions/mcp` | MCP over Streamable HTTP (stateless; `GET`/`DELETE` return 405) |
+| `GET /functions/files/<path>` | Download a file a function wrote to its `tempDir` — functions hand out these URLs via `context.fileUrl` |
+| `POST /functions/upload` | Stage an input file on the server (multipart, `file` field) → `{ "path", "url", "name", "size" }` |
+
+Errors come back as `{ "error": { "code", "message" } }` with `FUNCTION_NOT_FOUND` (404), `FUNCTION_TIMEOUT` (504), `FUNCTION_FAILED` (500) or `FUNCTION_FILE_NOT_FOUND` (404).
+
+Downloads carry the same auth as function calls, only ever serve files under the functions scratch root (anything else — traversal, directories — is a 404), and stay available until the ~24h scratch sweep. Typical flow: a function returns `{ url: context.fileUrl(outPath) }` and the caller (or MCP agent) fetches `<base><url>` with its existing `Authorization` header — see `config/function-samples/text-to-speech.ts` for the end-to-end shape.
+
+Uploads are the same idea in the other direction, for functions whose input is a media file (`transcribe-media` and friends). The direct route is a multipart **call**: post `multipart/form-data` to `POST /functions/<name>` and every file field is staged into the call's scratch directory with its server-local path injected into the input under the field's name — one request uploads and runs:
+
+```bash
+curl -X POST <base>/functions/transcribe-media -F file=@interview.mp4
+# optional: -F input='{"model": "..."}' for typed values; other plain fields arrive as strings
+```
+
+To stage a file once and reuse it across calls, `curl -F file=@interview.mp4 <base>/functions/upload` stores it in its own scratch directory and returns `{ "path", "url", "name", "size" }` — pass `path` as the function's input. Either way the client file name is sanitized to a bare name, and staged files share the auth guard and the ~24h sweep. Requests are capped by `[server] max_body_size` (default 50MB) — raise it for large media.
+
+All of this activity is observable: the `/status` dashboard (and the `/buttress/status` JSON it polls) carries a **Local Functions** card with counters since startup and recent history for calls (per surface: HTTP/SSE/MCP, with durations and failure reasons), uploads, downloads, and auth decisions (allowed/denied with mode and subject — never credentials).
+
+To point an agent at the MCP endpoint:
+
+```bash
+bricks buttress mcp-config --write        # discovers the server, mints a token, updates .mcp.json
+```
+
+### Security
+
+Functions execute code and spawn processes on the host, so this surface is **fail-closed**: on a server with no workspace binding every call is rejected with `403 FUNCTIONS_UNAUTHENTICATED_DISABLED`. Either bind the server (`bricks buttress bind`) so calls require a workspace access token like every other data path, or opt in explicitly:
+
+```toml
+[functions]
+allow_unauthenticated = true    # or BUTTRESS_FUNCTIONS_ALLOW_UNAUTHENTICATED=1
+```
+
+Only do that on a trusted network — it lets anyone who can reach the port run every function.
+
+Requests carrying a browser `Origin` header are rejected regardless of the above, so a web page you happen to visit cannot reach this surface. To allow a browser client, list its origin explicitly:
+
+```toml
+[functions]
+cors_allowed_origins = ["http://localhost:3000"]   # or "*" to allow any origin
+```
+
+#### Custom auth (`_auth.ts`)
+
+Dropping an `_auth.ts` (or `.js`) into the functions directory puts your own logic in front of every `/functions` endpoint. The file has the same shape as a function file — `meta` plus a default-exported handler — and `meta.mode` picks how it composes with the workspace auth above:
+
+- **`both`** (default): workspace auth runs first, unchanged; your function runs after it as an extra gate. It can only narrow access — use it for per-function allow-lists, subject checks, audit logging.
+- **`override`**: your function alone decides. A presented workspace token is still verified into `request.workspaceAuth`, so you can keep honoring workspace tokens while also accepting other credentials — e.g. static API keys on a server that is not bound to any workspace (`allow_unauthenticated` stops mattering in this mode).
+
+```ts
+export const meta: ButtressAuthMeta = { mode: 'override' }
+
+export default async function (request: ButtressAuthRequest, context: ButtressAuthContext) {
+  if (request.workspaceAuth.authenticated) return true       // workspace tokens keep working
+  const keys = context.config.api_keys                       // [functions.config] api_keys = [...]
+  if (Array.isArray(keys) && keys.includes(request.headers['x-api-key'])) return true
+  return { ok: false, status: 401, error: 'Invalid or missing API key' }
+}
+```
+
+The handler receives `{ method, path, name?, headers, query, token, workspaceAuth }` (`name` is only set for `POST /functions/<name>` — MCP `tools/call` targets live in the JSON-RPC body, which the guard does not parse) and a trimmed context (`log`, `fetch`, `env`, `config`, `dir`, `libs`). Only a returned `true` or `{ ok: true }` allows the request; anything else denies with `403 FUNCTIONS_AUTH_REJECTED` (or the `status`/`error` you return). Denials never fail open: while an `_auth` file exists but does not load, every call is rejected with `500 FUNCTIONS_AUTH_UNAVAILABLE`, and a handler that throws denies with `500 FUNCTIONS_AUTH_ERROR`. The browser-`Origin` block above always runs first — a permissive `_auth` cannot re-open it. Edits follow the same lazy reload as function files, and deleting the file reverts to plain workspace auth. See [`config/function-samples/_auth.ts`](config/function-samples/_auth.ts) for a commented version, and the scaffolded `buttress-functions.d.ts` for the full `ButtressAuth*` types.
+
+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.
+
 ## 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

@@ -0,0 +1,37 @@
+# Function Samples
+
+Ready-to-copy examples for the [Local Functions](../../README.md#local-functions-experimental)
+feature (experimental — interfaces may change between releases).
+Copy any of them into your configured functions directory (`[functions] dir`
+in the server TOML) — the server picks new files up on the next call, no restart
+needed. On first start the server scaffolds `buttress-functions.d.ts` and a
+`tsconfig.json` into that directory, which give these files full editor typings.
+
+| File | Shows | Needs |
+|------|-------|-------|
+| `host-info.ts` | The simplest possible function: a node builtin + `context.libs` | nothing |
+| `summarize-text.ts` | Calling this server's own LLM (`context.buttress.completion`) | an LLM `[[generators]]` entry |
+| `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 |
+| `_auth.ts` | Custom auth: keep workspace tokens working, add static API keys | see the file header |
+
+`_auth.ts` is not a function: copying it changes how every `/functions` endpoint
+authenticates callers. Read its header before copying it.
+
+Quick test after copying (on a bound server pass a workspace token, or run
+unbound with `allow_unauthenticated = true`):
+
+```bash
+curl -X POST http://localhost:2080/functions/host-info
+```
+
+The media samples take their input file inline — a multipart call stages the
+file and hands the function its server-local path in one request:
+
+```bash
+curl -X POST http://localhost:2080/functions/transcribe-media -F file=@interview.mp4
+```
+
+(To reuse a file across calls, stage it once with
+`curl -F file=@interview.mp4 http://localhost:2080/functions/upload` and pass
+the returned `path` as the `file` input.)