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

package/README.md

@@ -113,6 +113,7 @@ 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)|
+| `[functions]`             | Enable local functions — see [Local Functions](#local-functions-experimental)                      |
 | `[[generators]]`          | Array of generator instances — one entry per loaded model                                          |
 
 ### `[env]`
@@ -387,25 +388,32 @@ 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}`)
@@ -413,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:
@@ -495,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.)

package/config/function-samples/_auth.ts

@@ -0,0 +1,48 @@
+// Custom auth for the /functions endpoints.
+//
+// Unlike other "_"-prefixed files, "_auth" is special: dropping it into the
+// functions directory activates it. `meta.mode` picks how it composes with
+// the built-in workspace auth:
+//
+//   - 'both' (default): runs after workspace auth passes — an extra gate that
+//     can only narrow access (e.g. per-function allow-lists).
+//   - 'override': fully replaces workspace auth — this function alone decides.
+//     A presented workspace token is still verified into
+//     `request.workspaceAuth` so the function can choose to honor it.
+//
+// This sample uses 'override' to keep workspace tokens working while ALSO
+// accepting static API keys for callers that have none. Configure the keys in
+// the server TOML:
+//
+//   [functions.config]
+//   api_keys = ["replace-with-a-long-random-string"]
+//
+// Callers then send `X-Api-Key: <key>` (or `Authorization: Bearer <key>`).
+// With no api_keys configured it denies everything except valid workspace
+// tokens — it never fails open.
+
+export const meta: ButtressAuthMeta = {
+  mode: 'override',
+}
+
+export default async function authorize(
+  request: ButtressAuthRequest,
+  context: ButtressAuthContext,
+): Promise<ButtressAuthResult> {
+  // A valid workspace access token keeps working like before.
+  if (request.workspaceAuth.authenticated) return true
+
+  const keys = context.config.api_keys
+  if (!Array.isArray(keys) || keys.length === 0) {
+    return {
+      ok: false,
+      error: 'No workspace token and no [functions.config] api_keys configured',
+    }
+  }
+
+  // Headers reach this function lower-cased.
+  const presented = request.headers['x-api-key'] || request.token
+  if (typeof presented === 'string' && keys.includes(presented)) return true
+
+  return { ok: false, status: 401, error: 'Invalid or missing API key' }
+}

package/config/function-samples/host-info.ts

@@ -0,0 +1,25 @@
+// Report facts about the machine this server runs on.
+//
+// A good first function to try: it needs no external tools, no configured
+// generators and no input.
+//
+//   curl -X POST http://<host>:<port>/functions/host-info
+
+import os from 'node:os'
+
+export const meta: ButtressFunctionMeta = {
+  description: 'Report hostname, OS, CPU, memory and uptime of the Buttress host',
+}
+
+export default async function (_input: unknown, context: ButtressFunctionContext) {
+  const { bytes, ms } = context.libs
+
+  return {
+    hostname: os.hostname(),
+    platform: `${os.platform()} ${os.release()} (${os.arch()})`,
+    cpus: os.cpus().length,
+    memory: { total: bytes(os.totalmem()), free: bytes(os.freemem()) },
+    uptime: ms(Math.round(os.uptime()) * 1000, { long: true }),
+    load: os.loadavg().map((value) => Number(value.toFixed(2))),
+  }
+}

package/config/function-samples/summarize-text.ts

@@ -0,0 +1,55 @@
+// Summarize text with this server's own LLM generator — no API keys, the
+// model already configured under [[generators]] does the work in-process.
+//
+// Needs at least one LLM generator (e.g. ggml-llm) in the server config.
+//
+//   curl -X POST http://<host>:<port>/functions/summarize-text \
+//     -H 'Content-Type: application/json' \
+//     -d '{"text": "…", "style": "bullets"}'
+
+export const meta: ButtressFunctionMeta = {
+  description: 'Summarize a piece of text with the local LLM',
+  parameters: {
+    type: 'object',
+    properties: {
+      text: { type: 'string', description: 'The text to summarize' },
+      style: {
+        type: 'string',
+        enum: ['bullets', 'paragraph'],
+        default: 'bullets',
+        description: 'Shape of the summary',
+      },
+      model: {
+        type: 'string',
+        description: 'Optional model override (repo_id of a configured generator)',
+      },
+    },
+    required: ['text'],
+  },
+  timeout: '5m',
+}
+
+type Input = { text: string; style?: 'bullets' | 'paragraph'; model?: string }
+
+export default async function (
+  { text, style = 'bullets', model }: Input,
+  context: ButtressFunctionContext,
+) {
+  const target = style === 'paragraph' ? 'one short paragraph' : '3-5 concise bullet points'
+
+  const { content, usage } = await context.buttress.completion({
+    model,
+    // A summary is bounded work; without a cap a model that starts repeating
+    // itself runs to the context limit before the call's deadline stops it.
+    max_tokens: 512,
+    messages: [
+      {
+        role: 'system',
+        content: `Summarize the user's text as ${target}. Reply with the summary only.`,
+      },
+      { role: 'user', content: text },
+    ],
+  })
+
+  return { summary: content.trim(), usage }
+}

package/config/function-samples/text-to-speech.ts

@@ -0,0 +1,51 @@
+// Synthesize speech with this server's own TTS generator and hand back a
+// download URL — the caller never needs filesystem access to the server.
+//
+// Needs an onnx-tts generator in the server config, e.g.:
+//
+//   [[generators]]
+//   type = "onnx-tts"
+//   [generators.model]
+//   repo_id = "Xenova/speecht5_tts"
+//
+//   curl -X POST http://<host>:<port>/functions/text-to-speech \
+//     -H 'Content-Type: application/json' \
+//     -d '{"text": "Hello from Buttress"}'
+//   # → { "result": { "url": "/functions/files/…", … } }
+//   curl -OJ "http://<host>:<port>$url"   # same auth headers as the call
+
+export const meta: ButtressFunctionMeta = {
+  description: 'Synthesize speech from text with the local TTS model; returns a download URL',
+  parameters: {
+    type: 'object',
+    properties: {
+      text: { type: 'string', description: 'Text to speak' },
+      speaker: { type: 'string', description: 'Optional registered speaker id' },
+      model: { type: 'string', description: 'Optional TTS model override' },
+    },
+    required: ['text'],
+  },
+  timeout: '5m',
+}
+
+type Input = { text: string; speaker?: string; model?: string }
+
+export default async function ({ text, speaker, model }: Input, context: ButtressFunctionContext) {
+  const {
+    path: audioPath,
+    sampling_rate,
+    channels,
+  } = await context.buttress.synthesize({
+    text,
+    model,
+    options: speaker ? { speaker } : {},
+  })
+
+  return {
+    // Download with the same Authorization the function call used; the file
+    // stays available until the scratch-dir sweep (~24h).
+    url: context.fileUrl(audioPath),
+    sampling_rate,
+    channels,
+  }
+}

package/config/function-samples/transcribe-media.ts

@@ -0,0 +1,65 @@
+// Transcribe any audio or video file: ffmpeg extracts 16 kHz mono WAV audio
+// into the per-call scratch directory, then this server's STT generator
+// transcribes it. Progress reaches SSE callers (`?stream=1`) via context.emit.
+//
+// Needs `ffmpeg` on the server's PATH and an STT generator (ggml-stt or
+// onnx-stt) in the server config.
+//
+// Remote callers send the media inline — a multipart body stages every file
+// field and injects its server-local path into the input, so one request
+// does the whole job (bump [server] max_body_size for large files):
+//
+//   curl -X POST 'http://<host>:<port>/functions/transcribe-media?stream=1' \
+//     -F file=@interview.mp4
+//
+// To reuse one file across several calls, stage it once instead and pass the
+// returned path as {"file": "<path>"}:
+//
+//   curl -F file=@interview.mp4 http://<host>:<port>/functions/upload
+
+import path from 'node:path'
+
+export const meta: ButtressFunctionMeta = {
+  description: 'Transcribe an audio/video file using ffmpeg and the local STT model',
+  parameters: {
+    type: 'object',
+    properties: {
+      file: { type: 'string', description: 'Absolute path to a media file on the server' },
+      model: { type: 'string', description: 'Optional STT model override' },
+    },
+    required: ['file'],
+  },
+  timeout: '15m',
+}
+
+type Input = { file: string; model?: string }
+
+export default async function ({ file, model }: Input, context: ButtressFunctionContext) {
+  const wavPath = path.join(context.tempDir, 'audio.wav')
+
+  context.emit('stage', 'extract-audio')
+  // -hide_banner/-loglevel error keep stderr to the actual failure, so a
+  // thrown error reaches the caller instead of ffmpeg's build configuration.
+  const { code, stderr } = await context.spawn('ffmpeg', [
+    '-hide_banner',
+    '-loglevel',
+    'error',
+    '-y',
+    '-i',
+    file,
+    '-vn',
+    '-ac',
+    '1',
+    '-ar',
+    '16000',
+    wavPath,
+  ])
+  if (code !== 0) {
+    throw new Error(`ffmpeg failed (${code}): ${String(stderr).slice(-2000)}`)
+  }
+
+  context.emit('stage', 'transcribe')
+  const transcription = await context.buttress.transcribe({ model, filePath: wavPath })
+
+  return { transcription }
+}

package/config/sample.toml

@@ -29,6 +29,22 @@ enabled = true
 # cors_allowed_origins = ["http://localhost:3000", "https://example.com"]
 # cors_allowed_origins = "*"
 
+# Local functions (EXPERIMENTAL): .ts/.js files exposed as MCP tools and HTTP
+# endpoints. Interfaces may change between releases.
+# See the "Local Functions" section of README.md; ready-to-copy examples live
+# in config/function-samples/. An optional _auth.ts in the functions directory
+# customizes auth (extra gate, or full replacement of workspace auth).
+# [functions]
+# enabled = true
+# dir = "./functions"                # relative to this config file
+# default_timeout = "5m"             # per-call deadline; meta.timeout overrides it
+# hot_reload = false                 # watch the dir and reload eagerly on change
+# allow_unauthenticated = false      # UNBOUND servers reject calls unless this is true
+# cors_allowed_origins = ["http://localhost:3000"]  # browsers are blocked unless listed
+# [functions.config]                 # free-form; reaches functions as context.config
+# api_base = "https://example.internal"
+# api_keys = ["a-long-random-string"]  # e.g. consumed by function-samples/_auth.ts
+
 [runtime]
 cache_dir = "./.buttress-cache"
 # huggingface_token = "hf_xx"

package/lib/functions/auth.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Optional operator-supplied auth for the `/functions` surface.
+ *
+ * Dropping `_auth.ts` (or `.js`) into the functions directory activates it —
+ * the underscore keeps it out of tool discovery like any other helper file.
+ * `meta.mode` decides how it composes with the built-in workspace auth:
+ *
+ *   - 'both' (default): workspace auth runs first, unchanged; the custom
+ *     function is an additional gate, so it can only narrow access.
+ *   - 'override': the custom function is the only authority. A presented
+ *     workspace token is still verified so the function can honor it via
+ *     `request.workspaceAuth` (e.g. accept workspace tokens OR an API key).
+ *
+ * Failure never widens access: while an `_auth` file exists but does not
+ * load, every call is rejected until it is fixed. Reload follows the same
+ * mtime-driven lazy scheme as function files, and deleting the file reverts
+ * the server to plain workspace auth on the next request.
+ */
+import type { FunctionsConfig, LoadedAuthFunction } from './types';
+export declare const AUTH_BASENAME = "_auth";
+export type AuthLoader = {
+    /**
+     * Current auth function, or null when no `_auth` file exists. Throws when
+     * the file is present but unloadable — callers must treat that as deny-all.
+     */
+    get: () => Promise<LoadedAuthFunction | null>;
+};
+export declare const createAuthLoader: (config: FunctionsConfig) => AuthLoader;

package/lib/functions/config.d.ts

@@ -0,0 +1,20 @@
+import type { GlobalConfig } from '../types';
+import type { FunctionsConfig } from './types';
+export declare const DEFAULT_TIMEOUT_MS: number;
+export type ResolveFunctionsOptions = {
+    /**
+     * Directory a relative `dir` is resolved against — the directory holding the
+     * `--config` file. Inline-TOML configs have no such directory, so callers
+     * pass `process.cwd()`.
+     */
+    configDir?: string;
+    env?: Record<string, string | undefined>;
+};
+/**
+ * Resolve the `[functions]` TOML table (plus env overrides) into the shape the
+ * runtime uses. Returns null when the feature is not enabled.
+ *
+ * Enablement follows the same env-or-config idiom as the compatibility
+ * endpoints: `ENABLE_FUNCTIONS_ENDPOINT=1` or `[functions] enabled = true`.
+ */
+export declare const resolveFunctionsConfig: (globalConfig: GlobalConfig | undefined, { configDir, env }?: ResolveFunctionsOptions) => FunctionsConfig | null;

package/lib/functions/constants.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared constants for the local function system.
+ *
+ * Kept apart from `transpile.ts` so discovery and scaffolding can import them
+ * without pulling in the native transpiler.
+ */
+/** File extensions a local function (or one of its helper modules) may use. */
+export declare const SUPPORTED_EXTENSIONS: string[];
+/** What a function (file) may be called. Doubles as a path-safety guarantee. */
+export declare const FUNCTION_NAME_PATTERN: RegExp;
+/**
+ * Static segments of the functions API a function may not be named after:
+ * `POST /functions/mcp` (MCP), `GET /functions/files/*` (downloads) and
+ * `POST /functions/upload` (uploads) would shadow — or be shadowed by — a
+ * function of the same name.
+ */
+export declare const RESERVED_FUNCTION_NAMES: Set<string>;

package/lib/functions/executor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Runs a loaded local function with a deadline, a scratch directory, and the
+ * capabilities it is allowed to reach (spawn, buttress inference, helper libs).
+ *
+ * Cancellation is cooperative *plus* forceful: the call's AbortSignal is
+ * surfaced to the function (so `fetch` and the inference helpers unwind), and
+ * every process the call spawned is terminated. Code that blocks the event loop
+ * synchronously cannot be interrupted — function files are trusted, and vm has
+ * no way to preempt a running script.
+ */
+import type { FunctionEmit, FunctionRuntime, FunctionsConfig, LoadedFunction } from './types';
+export declare class FunctionTimeoutError extends Error {
+    constructor(name: string, timeoutMs: number);
+}
+export declare class FunctionAbortError extends Error {
+    constructor(name: string);
+}
+export type ExecuteOptions = {
+    runtime: FunctionRuntime;
+    functionsConfig: FunctionsConfig;
+    /** Streams progress to the caller; ignored on non-streaming surfaces. */
+    emit?: FunctionEmit;
+    /** Aborts the call early (e.g. the HTTP client disconnected). */
+    signal?: AbortSignal;
+    callId?: string;
+};
+export declare const executeFunction: (fn: LoadedFunction, input: any, { runtime, functionsConfig, emit, signal, callId }: ExecuteOptions) => Promise<any>;

package/lib/functions/files.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Path mapping for the function file-download surface.
+ *
+ * A call's scratch directory lives at `<temp_file_dir>/functions/<name>-<id>/`;
+ * `GET /functions/files/<name>-<id>/<file>` serves what a function wrote there.
+ * Both directions of the mapping live here, pure and unit-testable: URL →
+ * filesystem path (with strict containment, for the route) and filesystem
+ * path → URL (for `context.fileUrl`).
+ */
+export declare const FUNCTIONS_FILES_PREFIX = "/functions/files";
+/**
+ * Resolve a raw wildcard path from `GET /functions/files/*` to an absolute
+ * path inside `tempRoot`. Null when the path is empty, escapes the root, or
+ * cannot be decoded — the route treats all of those as 404.
+ */
+export declare const resolveFunctionsFile: (tempRoot: string, rawPath: string) => string | null;
+/**
+ * Build the download URL path for an absolute file inside `tempRoot`.
+ * Null when the file is outside it.
+ */
+export declare const functionsFileUrl: (tempRoot: string, absolutePath: string) => string | null;
+/**
+ * Tame a client-supplied upload file name into something safe to place on
+ * disk. Every upload gets its own directory, so only the name itself needs
+ * care: no path segments, no control characters, no dot-prefixed (hidden /
+ * traversal-looking) names. The extension survives — ffmpeg and friends use
+ * it for format detection.
+ */
+export declare const sanitizeUploadFilename: (original: string) => string;