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

package/README.md

@@ -8,6 +8,46 @@ A high-performance RPC server for managing GGML LLM generators with configurable
 npm install -g @fugood/buttress-server
 ```
 
+### Standalone binary (no Node.js required)
+
+A self-contained executable built with `bun build --compile`:
+
+```bash
+curl -fsSL https://cdn.bricks.tools/bricks-buttress/release/install.sh | sh
+# beta channel
+curl -fsSL https://cdn.bricks.tools/bricks-buttress/beta/install.sh | sh -s -- --beta
+```
+
+Windows (PowerShell):
+
+```powershell
+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
+`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
+`--ggml-variant=default|cuda|vulkan|snapdragon|all`.
+
+Installs and upgrades are transactional: the executable, the loose assets and
+every native package are downloaded into a staging directory and validated
+before any live path is replaced, and a failure part-way (or during the
+replacement itself) leaves the previously installed version runnable.
+
+Build the distribution locally from this package:
+
+```bash
+bun run build:dist -- --target=darwin-arm64   # or --platform=linux, etc.
+```
+
+See `scripts/build-distribution.js` for how native modules are swapped to
+sidecar loaders at bundle time, and `scripts/unix/install.sh` /
+`scripts/windows/install.ps1` for the host detection.
+
 ## Quick Start
 
 ### Using CLI
@@ -160,6 +200,8 @@ Most ggml-llm `[generators.model]` keys can also live in `[runtime]` as defaults
 | `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                                |
+| `state_cache_budget_mb`      | number                        | Memory budget of the cross-turn KV prefix cache for recurrent / hybrid models (default `160`, `0` disables) |
+| `state_cache_max_checkpoints` | number                       | Snapshot count cap for that cache (default `8`, `0` = unlimited); the memory budget takes precedence |
 | `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)                                                |
@@ -241,8 +283,10 @@ 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"`)                           |
 | `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`                   |
 | `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 |
+| `flash_attn_type`, `cache_type_k`, `cache_type_v`, `kv_unified`, `swa_full`, `ctx_shift`, `state_cache_budget_mb`, `state_cache_max_checkpoints`, `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`:
 
@@ -459,6 +503,14 @@ Buttress server for remote inference with GGML backends.
 
 Usage:
   bricks-buttress [options]
+  bricks-buttress update [--check] [-y] [--channel <release|beta>]
+
+Commands:
+  update                        Update bricks-buttress to the latest version.
+                                Standalone binary installs re-run the CDN
+                                installer (refreshing the native-module
+                                sidecar); npm/bun installs update the package.
+                                `--check` only reports whether an update exists.
 
 Options:
   -h, --help                    Show this help message
@@ -527,7 +579,7 @@ dir = "./functions"           # relative paths resolve against this config file
 
 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/).
+Ready-to-copy examples — a no-prerequisite starter, LLM summarization, sqlite-vec RAG, ffmpeg + STT transcription, TTS with a downloadable result, and a custom auth gate — live in [`config/function-samples/`](config/function-samples/).
 
 ### Writing a function
 
@@ -560,6 +612,9 @@ export default async function ({ path }: { path: string }, context: ButtressFunc
 | -------------- | ------------ |
 | `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.embedding({ model?, text, embd_normalize? })` | Embed text with a configured `ggml-llm` generator whose model has `embedding = true`; returns `{ embedding: number[] }`. |
+| `buttress.tokenize({ model?, text, params? })` | Tokenize with a configured GGML or MLX LLM → `{ tokens: number[], … }`. |
+| `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`); the WAV lands in `tempDir` → `{ path, sampling_rate, channels }`. |
 | `emit(event, data)` | Progress event; delivered to SSE callers, ignored otherwise. |
@@ -569,7 +624,7 @@ export default async function ({ path }: { path: string }, context: ButtressFunc
 | `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.
+Functions may `import` Node builtins (`node:fs/promises`, …), sibling files inside the functions directory, and the two provided database packages `sqlite3` and `sqlite-vec`. Other package imports are rejected. `sqlite-vec` supports macOS and Linux on x64/arm64, plus Windows x64; its upstream package does not ship a Windows arm64 extension, so the standalone Windows arm64 build does not provide either SQLite import.
 
 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.
 
@@ -581,13 +636,35 @@ For faster authoring feedback, opt into eager reloading with `[functions] hot_re
 | -------- | ------- |
 | `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` |
+| `GET /functions/<name>?…` | Run one with the query string as its input (see below) |
+| `POST /functions/<name>?stream=1` | Same, as SSE: `progress` events (from `context.emit`) then `result` or `error`. `GET` streams too |
 | `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).
 
+#### Calling with GET
+
+`GET /functions/<name>` runs the same call with no body at all — the query string is the input, which is what a browser address bar, a webhook, an `EventSource` (it cannot set headers, hence `?token=…`) or a bare `curl` can produce without ceremony:
+
+```bash
+curl '<base>/functions/weather?city=Taipei&days=3&units=metric'
+```
+
+Query values are strings, so the function's declared `meta.parameters` schema doubles as the coercion table: declared `number`/`integer`, `boolean`, `array` and `object` properties are converted, everything else stays a string. A value that does not fit its declared type is passed through verbatim rather than turned into `NaN` — the handler still owns validation.
+
+| Declared type | Query form |
+| ------------- | ---------- |
+| `number` / `integer` | `?n=3` |
+| `boolean` | `?verbose=true`, `?verbose=1`, or a bare `?verbose`; `false`/`0` for the other side |
+| `array` | `?tag=a&tag=b`, `?tag=a,b`, or `?tag=["a","b"]` (items coerce by `items`) |
+| `object` | `?filter={"lang":"en"}` |
+
+For exact types regardless of the schema, pass the whole object as JSON in `input` — plain parameters overlay it, exactly like a multipart call: `?input={"n":3}&note=hi`. `stream`, `token` and `access_token` steer the request and never reach the handler.
+
+GET is offered for every function; HTTP asks that a GET be safe to repeat and only you know whether yours is, so pick the method that matches what the function does. Responses are `no-store`.
+
 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:
@@ -618,13 +695,15 @@ 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:
+Browser-initiated cross-site requests are rejected regardless of the above, so a web page you happen to visit cannot reach this surface — that covers both requests carrying an `Origin` header and no-CORS loads that send none (`<img src>`, `<script src>`, a prefetch of a `GET` call), which browsers mark with `Sec-Fetch-Site`. To allow a browser client, list its origin explicitly:
 
 ```toml
 [functions]
 cors_allowed_origins = ["http://localhost:3000"]   # or "*" to allow any origin
 ```
 
+A listed origin only helps requests that carry one; a no-CORS load has no origin to match, so only `"*"` lets those through.
+
 #### 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:

package/config/function-samples/README.md

@@ -11,6 +11,7 @@ needed. On first start the server scaffolds `buttress-functions.d.ts` and a
 |------|-------|-------|
 | `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 |
+| `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 |
 | `_auth.ts` | Custom auth: keep workspace tokens working, add static API keys | see the file header |
@@ -18,6 +19,38 @@ needed. On first start the server scaffolds `buttress-functions.d.ts` and a
 `_auth.ts` is not a function: copying it changes how every `/functions` endpoint
 authenticates callers. Read its header before copying it.
 
+`simple-rag.ts` needs a dedicated embedding model. Keep your chat generator as
+the first LLM (or pass its `repo_id` as `chatModel`) and add, for example:
+
+```toml
+[[generators]]
+type = "ggml-llm"
+[generators.model]
+repo_id = "nomic-ai/nomic-embed-text-v1.5-GGUF"
+filename = "nomic-embed-text-v1.5.Q8_0.gguf"
+embedding = true
+pooling_type = "mean"
+n_ctx = 2048
+```
+
+Then call it with `question`, `documents`, and
+`embeddingModel: "nomic-ai/nomic-embed-text-v1.5-GGUF"`. SQLite defaults to an
+in-memory index:
+
+```json
+{ "databasePath": ":memory:" }
+```
+
+For a file-backed database, pass an absolute path or one relative to the
+configured functions directory (missing parent directories are created):
+
+```json
+{ "databasePath": "./data/simple-rag.sqlite" }
+```
+
+The sample rebuilds `chunks` on each call so both modes behave identically; a
+file retains the latest index after the database closes.
+
 Quick test after copying (on a bound server pass a workspace token, or run
 unbound with `allow_unauthenticated = true`):
 

package/config/function-samples/simple-rag.ts

@@ -0,0 +1,231 @@
+import { mkdir } from 'node:fs/promises'
+import path from 'node:path'
+
+import sqlite3 from 'sqlite3'
+import * as sqliteVec from 'sqlite-vec'
+
+type Input = {
+  question: string
+  documents: string[]
+  embeddingModel: string
+  chatModel?: string
+  databasePath?: string
+  chunkTokens?: number
+  topK?: number
+}
+
+type Database = InstanceType<typeof sqlite3.Database>
+type Match = { text: string; distance: number }
+
+export const meta: ButtressFunctionMeta = {
+  description: 'Answer a question from supplied documents with sqlite-vec retrieval',
+  parameters: {
+    type: 'object',
+    properties: {
+      question: { type: 'string', description: 'Question to answer' },
+      documents: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Source texts to chunk and search',
+      },
+      embeddingModel: {
+        type: 'string',
+        description: 'repo_id of a configured GGML generator with embedding = true',
+      },
+      chatModel: {
+        type: 'string',
+        description: 'Optional repo_id of the generator that writes the answer',
+      },
+      databasePath: {
+        type: 'string',
+        default: ':memory:',
+        description:
+          'Use :memory: for an ephemeral index or a SQLite file path; relative paths resolve from the functions directory',
+      },
+      chunkTokens: { type: 'integer', default: 256, minimum: 32, maximum: 1024 },
+      topK: { type: 'integer', default: 3, minimum: 1, maximum: 10 },
+    },
+    required: ['question', 'documents', 'embeddingModel'],
+  },
+  timeout: '10m',
+}
+
+const resolveDatabasePath = async (
+  requestedPath: string | undefined,
+  functionsDirectory: string,
+): Promise<string> => {
+  const databasePath = requestedPath?.trim() || ':memory:'
+  if (databasePath === ':memory:') return databasePath
+
+  const resolvedPath = path.isAbsolute(databasePath)
+    ? databasePath
+    : path.resolve(functionsDirectory, databasePath)
+  await mkdir(path.dirname(resolvedPath), { recursive: true })
+  return resolvedPath
+}
+
+const openDatabase = (databasePath: string): Promise<Database> =>
+  new Promise((resolve, reject) => {
+    const database = new sqlite3.Database(databasePath, (error) => {
+      if (error) reject(error)
+      else resolve(database)
+    })
+  })
+
+const loadExtension = (database: Database, extension: string): Promise<void> =>
+  new Promise((resolve, reject) => {
+    database.loadExtension(extension, (error) => {
+      if (error) reject(error)
+      else resolve()
+    })
+  })
+
+const run = (database: Database, sql: string, ...params: unknown[]): Promise<void> =>
+  new Promise((resolve, reject) => {
+    database.run(sql, ...params, (error: Error | null) => {
+      if (error) reject(error)
+      else resolve()
+    })
+  })
+
+const all = <T>(database: Database, sql: string, ...params: unknown[]): Promise<T[]> =>
+  new Promise((resolve, reject) => {
+    database.all<T>(sql, ...params, (error: Error | null, rows: T[]) => {
+      if (error) reject(error)
+      else resolve(rows)
+    })
+  })
+
+const close = (database: Database): Promise<void> =>
+  new Promise((resolve, reject) => {
+    database.close((error) => {
+      if (error) reject(error)
+      else resolve()
+    })
+  })
+
+const vectorBlob = (values: number[]): Buffer => {
+  const vector = Float32Array.from(values)
+  return Buffer.from(vector.buffer, vector.byteOffset, vector.byteLength)
+}
+
+const clampInteger = (value: unknown, fallback: number, min: number, max: number): number => {
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? Math.min(max, Math.max(min, Math.floor(parsed))) : fallback
+}
+
+export default async function (
+  {
+    question,
+    documents,
+    embeddingModel,
+    chatModel,
+    databasePath,
+    chunkTokens = 256,
+    topK = 3,
+  }: Input,
+  context: ButtressFunctionContext,
+) {
+  if (!question?.trim()) throw new Error('question is required')
+  if (!Array.isArray(documents) || documents.length === 0) {
+    throw new Error('documents must contain at least one source text')
+  }
+
+  const chunkSize = clampInteger(chunkTokens, 256, 32, 1024)
+  const limit = clampInteger(topK, 3, 1, 10)
+  const chunks: string[] = []
+
+  context.emit('progress', { stage: 'chunking', documents: documents.length })
+  for (const document of documents) {
+    const { tokens } = await context.buttress.tokenize({
+      model: embeddingModel,
+      text: String(document),
+    })
+    for (let offset = 0; offset < tokens.length; offset += chunkSize) {
+      const text = await context.buttress.detokenize({
+        model: embeddingModel,
+        tokens: tokens.slice(offset, offset + chunkSize),
+      })
+      if (text.trim()) chunks.push(text)
+    }
+  }
+  if (chunks.length === 0) throw new Error('documents produced no searchable text')
+
+  context.emit('progress', { stage: 'embedding', chunks: chunks.length })
+  const embedded: { text: string; embedding: number[] }[] = []
+  for (const text of chunks) {
+    const { embedding } = await context.buttress.embedding({ model: embeddingModel, text })
+    if (embedding.length === 0) throw new Error('embedding model returned an empty vector')
+    if (embedded.length > 0 && embedding.length !== embedded[0].embedding.length) {
+      throw new Error('embedding model returned vectors with inconsistent dimensions')
+    }
+    embedded.push({ text, embedding })
+  }
+
+  const { embedding: questionEmbedding } = await context.buttress.embedding({
+    model: embeddingModel,
+    text: question,
+  })
+  const dimensions = embedded[0].embedding.length
+  if (questionEmbedding.length !== dimensions) {
+    throw new Error('question embedding dimension does not match the document vectors')
+  }
+
+  const resolvedDatabasePath = await resolveDatabasePath(databasePath, context.dir)
+  const database = await openDatabase(resolvedDatabasePath)
+  let matches: Match[]
+  try {
+    // sqlite-vec's convenience `load()` is synchronous, while node-sqlite3's
+    // loadExtension is callback-based. Awaiting the path explicitly avoids a
+    // race with the first vec0 statement.
+    await loadExtension(database, sqliteVec.getLoadablePath())
+    // Rebuild on every call so memory and file-backed usage have identical,
+    // deterministic behavior. The file retains the latest index after close.
+    await run(database, 'DROP TABLE IF EXISTS chunks')
+    await run(
+      database,
+      `CREATE VIRTUAL TABLE chunks USING vec0(embedding float[${dimensions}], text TEXT)`,
+    )
+    for (const chunk of embedded) {
+      await run(
+        database,
+        'INSERT INTO chunks(embedding, text) VALUES (?, ?)',
+        vectorBlob(chunk.embedding),
+        chunk.text,
+      )
+    }
+    matches = await all<Match>(
+      database,
+      `SELECT text, distance
+         FROM chunks
+        WHERE embedding MATCH ?
+        ORDER BY distance
+        LIMIT ${limit}`,
+      vectorBlob(questionEmbedding),
+    )
+  } finally {
+    await close(database)
+  }
+
+  context.emit('progress', { stage: 'answering', matches: matches.length })
+  const sources = matches.map((match, index) => `[${index + 1}] ${match.text}`).join('\n\n')
+  const answer = await context.buttress.completion({
+    model: chatModel,
+    messages: [
+      {
+        role: 'system',
+        content:
+          'Answer only from the supplied sources. If they do not contain the answer, say so.',
+      },
+      { role: 'user', content: `Sources:\n${sources}\n\nQuestion: ${question}` },
+    ],
+    max_tokens: 512,
+  })
+
+  return {
+    answer: answer.content,
+    matches,
+    chunks: chunks.length,
+    usage: answer.usage,
+  }
+}

package/lib/cli-update.d.ts

@@ -0,0 +1 @@
+export declare const runUpdateCommand: (args: string[]) => Promise<never>;

package/lib/functions/index.d.ts

@@ -25,6 +25,8 @@ export type FunctionsService = {
     config: FunctionsConfig;
     dir: string;
     list: () => Promise<FunctionSummary[]>;
+    /** One function's summary; rejects when it is unknown or fails to load. */
+    describe: (name: string) => Promise<FunctionSummary>;
     call: (name: string, input: any, options: CallOptions) => Promise<any>;
     /**
      * The operator's `_auth` function, or null when none exists. Rejects while

package/lib/functions/input.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The shared record contract behind the transport input parsers.
+ *
+ * `parseQueryInput` and `stageMultipartInput` both fill an input object with
+ * externally chosen field names, so plain `input[field] = value` is wrong: a
+ * field literally named `__proto__` would hit `Object.prototype`'s legacy
+ * setter instead of becoming an input value — silently dropped for strings,
+ * and a swapped prototype for object-like values.
+ */
+/** Set an externally named field as a plain own data property. */
+export declare const setInputField: (input: Record<string, any>, field: string, value: any) => void;

package/lib/functions/loader.d.ts

@@ -12,6 +12,8 @@
  * and `JSON.stringify` work, but `instanceof` against host constructors does
  * not. Never `instanceof`-check a function's return value.
  */
+/** The deliberately small package surface local functions may import. */
+export declare const SUPPORTED_PACKAGE_IMPORTS: readonly ['sqlite3', 'sqlite-vec'];
 export declare class FunctionImportError extends Error {
     constructor(message: string);
 }
@@ -23,6 +25,9 @@ export declare const createSandboxGlobals: (extra?: Record<string, any>) => Reco
 export type ResolvedSpecifier = {
     kind: 'builtin';
     id: string;
+} | {
+    kind: 'package';
+    id: string;
 } | {
     kind: 'file';
     path: string;

package/lib/functions/query.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Query-string input for `GET /functions/<name>`.
+ *
+ * The sibling of `stageMultipartInput`: same idea, other transport. An optional
+ * `input` parameter carries a JSON object for exact types, and every other
+ * parameter overlays it — so `?input={"n":3}&note=hi` and a multipart body with
+ * the same two fields produce the same input object.
+ *
+ * Query values are always strings, so a bare `?n=3` would hand a handler `"3"`.
+ * The function's declared `meta.parameters` schema is the only thing that says
+ * otherwise, so it doubles as the coercion table: declared numbers, booleans,
+ * arrays and objects are converted, and anything undeclared stays a string.
+ * Coercion never rejects — a value that does not fit its declared type is
+ * passed through verbatim rather than turned into `NaN` (the handler, which
+ * owns validation, sees what the caller actually sent).
+ */
+/** A caller mistake in the query shape — reported as 400, not 500. */
+export declare class QueryInputError extends Error {
+    constructor(message: string);
+}
+/**
+ * Turn a query string into a function input object.
+ *
+ * `parameters` is the function's declared JSON Schema, when it has one; without
+ * it every value stays a string.
+ */
+export declare const parseQueryInput: (search: URLSearchParams, parameters?: Record<string, any>) => Record<string, any>;

package/lib/functions/registry.d.ts

@@ -28,6 +28,7 @@ export declare const createFunctionsRegistry: (config: FunctionsConfig) => {
     config: FunctionsConfig;
     scan: () => Promise<void>;
     get: (name: string) => Promise<LoadedFunction>;
+    describe: (name: string) => Promise<FunctionSummary>;
     list: () => Promise<FunctionSummary[]>;
     entries: Map<string, Entry>;
 };

package/lib/functions/templates.d.ts

@@ -9,6 +9,6 @@
 export declare const TYPES_FILE_NAME = "buttress-functions.d.ts";
 export declare const TSCONFIG_FILE_NAME = "tsconfig.json";
 export declare const EXAMPLE_FILE_NAME = "_example.ts";
-export declare const TYPES_TEMPLATE = "// Generated by @fugood/buttress-server \u2014 do not edit.\n// Rewritten on every server start to match the running version.\n//\n// Local functions are EXPERIMENTAL: this contract may change between\n// releases \u2014 after a server upgrade, re-read this file for the current shape.\n\n/** Result of `context.spawn(...)`. */\ntype ButtressSpawnResult = {\n  /** Exit code, or null when the process was killed by a signal. */\n  code: number | null\n  signal: NodeJS.Signals | null\n  stdout: string | Buffer\n  stderr: string | Buffer\n  /** True when output hit `maxBuffer` and capture stopped early. */\n  truncated: boolean\n}\n\ntype ButtressSpawnOptions = {\n  cwd?: string\n  /** Merged over the server's own environment. */\n  env?: Record<string, string | undefined>\n  /** Written to stdin, which is then closed. */\n  input?: string | Uint8Array\n  /** 'utf8' (default) yields strings; 'buffer' yields Buffers. */\n  encoding?: 'utf8' | 'buffer'\n  /** Per-stream capture cap in bytes (default 8MB). */\n  maxBuffer?: number\n  onStdout?: (chunk: Buffer) => void\n  onStderr?: (chunk: Buffer) => void\n}\n\ntype ButtressCompletionResult = {\n  content: string\n  reasoning_content?: string\n  tool_calls?: any[]\n  interrupted?: boolean\n  usage: { prompt_tokens: number; completion_tokens: number; total_tokens: number }\n}\n\ntype ButtressFunctionContext = {\n  /**\n   * Run a child process. Resolves once it exits \u2014 a non-zero `code` is a\n   * normal resolution, so check it yourself. Rejects only when the process\n   * cannot be started. Every process a call spawns is killed when the call\n   * ends or times out.\n   */\n  spawn: (\n    command: string,\n    args?: string[],\n    options?: ButtressSpawnOptions,\n  ) => Promise<ButtressSpawnResult>\n\n  buttress: {\n    /**\n     * Run a chat completion on this server's LLM generator. `messages` are\n     * rendered with the model's own chat template, and thinking is off unless\n     * you pass `enable_thinking: true` (which fills `reasoning_content`).\n     */\n    completion: (options: {\n      /** Configured `[[generators]]` model; defaults to the first one. */\n      model?: string\n      messages?: { role: string; content: any }[]\n      prompt?: string\n      /** Cap on generated tokens. Unbounded when omitted. */\n      max_tokens?: number\n      temperature?: number\n      /** Emit the model's reasoning into `reasoning_content` (default false). */\n      enable_thinking?: boolean\n      /** Called for every streamed token event. */\n      onToken?: (event: { token?: string; content?: string; [key: string]: any }) => void\n      /** Any other backend sampling option (`top_p`, `stop`, `tools`, \u2026). */\n      [param: string]: any\n    }) => Promise<ButtressCompletionResult>\n\n    /** Transcribe audio with this server's STT generator. */\n    transcribe: (options: {\n      /** Must match a configured STT model (`repo_id` or `repo_id:filename`). */\n      model?: string\n      filePath?: string\n      audioData?: Uint8Array | Buffer\n      options?: Record<string, any>\n    }) => Promise<any>\n\n    /**\n     * Synthesize speech with this server's TTS generator (onnx-tts). The WAV\n     * is written into `tempDir`; return `fileUrl(path)` to let callers\n     * download it.\n     */\n    synthesize: (options: {\n      /** Must match a configured TTS model when given. */\n      model?: string\n      text: string\n      /** Backend options; `options.speaker` picks a registered voice. */\n      options?: Record<string, any>\n    }) => Promise<{ path: string; sampling_rate: number; channels: number }>\n  }\n\n  fetch: typeof fetch\n  /** Server-side log, prefixed with the function name. */\n  log: (...args: unknown[]) => void\n  /** Emit a progress event. Delivered only to SSE callers; a no-op otherwise. */\n  emit: (event: string, data?: unknown) => void\n  /** Aborted when the call times out or the caller disconnects. */\n  signal: AbortSignal\n  env: Record<string, string | undefined>\n  /** The `[functions.config]` table from the server config. */\n  config: Record<string, any>\n  /** Per-call scratch directory, created on first access. */\n  tempDir: string\n  /**\n   * Download URL path (`/functions/files/...`) for a file inside `tempDir`;\n   * relative input resolves against it. Callers fetch the URL with the same\n   * auth as any function call. Scratch dirs are swept after ~24h.\n   */\n  fileUrl: (target: string) => string\n  /** Absolute path of this functions directory. */\n  dir: string\n  /** Helper libraries: _, lodash, moment, math, mathjs, voca, chroma, json5, qs, bytes, ms, nanoid, md5. */\n  libs: Record<string, any>\n}\n\ntype ButtressFunctionMeta = {\n  /** Shown to MCP clients in `tools/list`. */\n  description?: string\n  /** JSON Schema for the input object, passed to MCP verbatim. */\n  parameters?: Record<string, any>\n  /** Deadline for this function: ms, or a duration string like \"10m\". */\n  timeout?: number | string\n}\n\n// --- Custom auth ------------------------------------------------------------\n// Drop an `_auth.ts` into this directory to gate the /functions endpoints\n// with your own logic. It exports the same shape as a function file:\n//\n//   export const meta: ButtressAuthMeta = { mode: 'both' }\n//   export default async function (\n//     request: ButtressAuthRequest,\n//     context: ButtressAuthContext,\n//   ): Promise<ButtressAuthResult> { ... }\n//\n// While an `_auth` file exists but fails to load, every call is rejected.\n\ntype ButtressAuthMeta = {\n  /**\n   * 'both' (default): runs after the built-in workspace auth passes, as an\n   * extra gate. 'override': replaces workspace auth \u2014 this function is the\n   * only authority (a presented workspace token is still verified into\n   * `request.workspaceAuth` so you can choose to honor it).\n   */\n  mode?: 'override' | 'both'\n}\n\ntype ButtressAuthRequest = {\n  method: string\n  path: string\n  /** Function name for `POST /functions/<name>`; undefined for list and MCP. */\n  name?: string\n  headers: Record<string, string | undefined>\n  query: Record<string, string | undefined>\n  /** Raw bearer token (Authorization header or `?token=`), if any. */\n  token: string | null\n  workspaceAuth: {\n    /** Whether this server is bound to a workspace. */\n    bound: boolean\n    /** Whether the caller presented a valid workspace access token. */\n    authenticated: boolean\n    identity: {\n      workspaceId: string\n      subjectType: 'ws' | 'dev'\n      subjectId: string\n      jti?: string\n      exp: number\n    } | null\n  }\n}\n\ntype ButtressAuthContext = {\n  /** Server-side log, prefixed with \"_auth\". */\n  log: (...args: unknown[]) => void\n  fetch: typeof fetch\n  env: Record<string, string | undefined>\n  /** The `[functions.config]` table, same as `context.config` in functions. */\n  config: Record<string, any>\n  /** Absolute path of this functions directory. */\n  dir: string\n  /** Same helper libraries functions get. */\n  libs: Record<string, any>\n}\n\n/** Only `true` (or `{ ok: true }`) allows the request; anything else denies. */\ntype ButtressAuthResult =\n  | boolean\n  | {\n      ok: boolean\n      /** Response status for a denial, 400-499 (default 403). */\n      status?: number\n      /** Message returned to the caller on denial. */\n      error?: string\n    }\n";
+export declare const TYPES_TEMPLATE = "// Generated by @fugood/buttress-server \u2014 do not edit.\n// Rewritten on every server start to match the running version.\n//\n// Local functions are EXPERIMENTAL: this contract may change between\n// releases \u2014 after a server upgrade, re-read this file for the current shape.\n\n/** Result of `context.spawn(...)`. */\ntype ButtressSpawnResult = {\n  /** Exit code, or null when the process was killed by a signal. */\n  code: number | null\n  signal: NodeJS.Signals | null\n  stdout: string | Buffer\n  stderr: string | Buffer\n  /** True when output hit `maxBuffer` and capture stopped early. */\n  truncated: boolean\n}\n\ntype ButtressSpawnOptions = {\n  cwd?: string\n  /** Merged over the server's own environment. */\n  env?: Record<string, string | undefined>\n  /** Written to stdin, which is then closed. */\n  input?: string | Uint8Array\n  /** 'utf8' (default) yields strings; 'buffer' yields Buffers. */\n  encoding?: 'utf8' | 'buffer'\n  /** Per-stream capture cap in bytes (default 8MB). */\n  maxBuffer?: number\n  onStdout?: (chunk: Buffer) => void\n  onStderr?: (chunk: Buffer) => void\n}\n\ntype ButtressCompletionResult = {\n  content: string\n  reasoning_content?: string\n  tool_calls?: any[]\n  interrupted?: boolean\n  usage: { prompt_tokens: number; completion_tokens: number; total_tokens: number }\n}\n\ntype ButtressEmbeddingResult = {\n  /** Plain numbers, ready for JSON or conversion into a sqlite-vec float32 BLOB. */\n  embedding: number[]\n}\n\ntype ButtressFunctionContext = {\n  /**\n   * Run a child process. Resolves once it exits \u2014 a non-zero `code` is a\n   * normal resolution, so check it yourself. Rejects only when the process\n   * cannot be started. Every process a call spawns is killed when the call\n   * ends or times out.\n   */\n  spawn: (\n    command: string,\n    args?: string[],\n    options?: ButtressSpawnOptions,\n  ) => Promise<ButtressSpawnResult>\n\n  buttress: {\n    /**\n     * Run a chat completion on this server's LLM generator. `messages` are\n     * rendered with the model's own chat template, and thinking is off unless\n     * you pass `enable_thinking: true` (which fills `reasoning_content`).\n     */\n    completion: (options: {\n      /** Configured `[[generators]]` model; defaults to the first one. */\n      model?: string\n      messages?: { role: string; content: any }[]\n      prompt?: string\n      /** Cap on generated tokens. Unbounded when omitted. */\n      max_tokens?: number\n      temperature?: number\n      /** Emit the model's reasoning into `reasoning_content` (default false). */\n      enable_thinking?: boolean\n      /** Called for every streamed token event. */\n      onToken?: (event: { token?: string; content?: string; [key: string]: any }) => void\n      /** Any other backend sampling option (`top_p`, `stop`, `tools`, \u2026). */\n      [param: string]: any\n    }) => Promise<ButtressCompletionResult>\n\n    /**\n     * Embed text with a GGML generator whose `[generators.model]` table sets\n     * `embedding = true`. The vector is returned as plain numbers.\n     */\n    embedding: (options: {\n      model?: string\n      text: string\n      /** llama.cpp normalization mode; 2 (L2) is the native default. */\n      embd_normalize?: number\n    }) => Promise<ButtressEmbeddingResult>\n\n    /** Tokenize text with a configured GGML or MLX generator. */\n    tokenize: (options: {\n      model?: string\n      text: string\n      params?: Record<string, any>\n    }) => Promise<Record<string, any> & { tokens: number[] }>\n\n    /** Turn model token ids back into text. */\n    detokenize: (options: { model?: string; tokens: number[] }) => Promise<string>\n\n    /** Transcribe audio with this server's STT generator. */\n    transcribe: (options: {\n      /** Must match a configured STT model (`repo_id` or `repo_id:filename`). */\n      model?: string\n      filePath?: string\n      audioData?: Uint8Array | Buffer\n      options?: Record<string, any>\n    }) => Promise<any>\n\n    /**\n     * Synthesize speech with this server's TTS generator (onnx-tts). The WAV\n     * is written into `tempDir`; return `fileUrl(path)` to let callers\n     * download it.\n     */\n    synthesize: (options: {\n      /** Must match a configured TTS model when given. */\n      model?: string\n      text: string\n      /** Backend options; `options.speaker` picks a registered voice. */\n      options?: Record<string, any>\n    }) => Promise<{ path: string; sampling_rate: number; channels: number }>\n  }\n\n  fetch: typeof fetch\n  /** Server-side log, prefixed with the function name. */\n  log: (...args: unknown[]) => void\n  /** Emit a progress event. Delivered only to SSE callers; a no-op otherwise. */\n  emit: (event: string, data?: unknown) => void\n  /** Aborted when the call times out or the caller disconnects. */\n  signal: AbortSignal\n  env: Record<string, string | undefined>\n  /** The `[functions.config]` table from the server config. */\n  config: Record<string, any>\n  /** Per-call scratch directory, created on first access. */\n  tempDir: string\n  /**\n   * Download URL path (`/functions/files/...`) for a file inside `tempDir`;\n   * relative input resolves against it. Callers fetch the URL with the same\n   * auth as any function call. Scratch dirs are swept after ~24h.\n   */\n  fileUrl: (target: string) => string\n  /** Absolute path of this functions directory. */\n  dir: string\n  /** Helper libraries: _, lodash, moment, math, mathjs, voca, chroma, json5, qs, bytes, ms, nanoid, md5. */\n  libs: Record<string, any>\n}\n\ntype ButtressFunctionMeta = {\n  /** Shown to MCP clients in `tools/list`. */\n  description?: string\n  /** JSON Schema for the input object, passed to MCP verbatim. */\n  parameters?: Record<string, any>\n  /** Deadline for this function: ms, or a duration string like \"10m\". */\n  timeout?: number | string\n}\n\n// --- Custom auth ------------------------------------------------------------\n// Drop an `_auth.ts` into this directory to gate the /functions endpoints\n// with your own logic. It exports the same shape as a function file:\n//\n//   export const meta: ButtressAuthMeta = { mode: 'both' }\n//   export default async function (\n//     request: ButtressAuthRequest,\n//     context: ButtressAuthContext,\n//   ): Promise<ButtressAuthResult> { ... }\n//\n// While an `_auth` file exists but fails to load, every call is rejected.\n\ntype ButtressAuthMeta = {\n  /**\n   * 'both' (default): runs after the built-in workspace auth passes, as an\n   * extra gate. 'override': replaces workspace auth \u2014 this function is the\n   * only authority (a presented workspace token is still verified into\n   * `request.workspaceAuth` so you can choose to honor it).\n   */\n  mode?: 'override' | 'both'\n}\n\ntype ButtressAuthRequest = {\n  method: string\n  path: string\n  /** Function name for `GET`/`POST /functions/<name>`; undefined for list and MCP. */\n  name?: string\n  headers: Record<string, string | undefined>\n  query: Record<string, string | undefined>\n  /** Raw bearer token (Authorization header or `?token=`), if any. */\n  token: string | null\n  workspaceAuth: {\n    /** Whether this server is bound to a workspace. */\n    bound: boolean\n    /** Whether the caller presented a valid workspace access token. */\n    authenticated: boolean\n    identity: {\n      workspaceId: string\n      subjectType: 'ws' | 'dev'\n      subjectId: string\n      jti?: string\n      exp: number\n    } | null\n  }\n}\n\ntype ButtressAuthContext = {\n  /** Server-side log, prefixed with \"_auth\". */\n  log: (...args: unknown[]) => void\n  fetch: typeof fetch\n  env: Record<string, string | undefined>\n  /** The `[functions.config]` table, same as `context.config` in functions. */\n  config: Record<string, any>\n  /** Absolute path of this functions directory. */\n  dir: string\n  /** Same helper libraries functions get. */\n  libs: Record<string, any>\n}\n\n/** Only `true` (or `{ ok: true }`) allows the request; anything else denies. */\ntype ButtressAuthResult =\n  | boolean\n  | {\n      ok: boolean\n      /** Response status for a denial, 400-499 (default 403). */\n      status?: number\n      /** Message returned to the caller on denial. */\n      error?: string\n    }\n\n// The only non-builtin packages the local-function loader accepts. These\n// declarations keep editor support working when this directory is outside the\n// server package's own node_modules resolution tree.\ndeclare module 'sqlite3' {\n  type SqliteCallback = (error: Error | null) => void\n\n  class Database {\n    constructor(filename: string, callback?: SqliteCallback)\n    run(sql: string, ...params: any[]): this\n    all<T = Record<string, any>>(\n      sql: string,\n      ...params: [...any[], (error: Error | null, rows: T[]) => void]\n    ): this\n    exec(sql: string, callback?: SqliteCallback): this\n    loadExtension(filename: string, callback?: SqliteCallback): this\n    close(callback?: SqliteCallback): void\n  }\n\n  const sqlite3: { Database: typeof Database }\n  export { Database }\n  export default sqlite3\n}\n\ndeclare module 'sqlite-vec' {\n  export function getLoadablePath(): string\n  export function load(database: { loadExtension(path: string): unknown }): void\n}\n";
 export declare const TSCONFIG_TEMPLATE = "{\n  // Editor support for Buttress local functions.\n  // Install @types/node here for typings on \"node:*\" imports.\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"Bundler\",\n    \"lib\": [\"ES2023\"],\n    \"strict\": true,\n    \"noEmit\": true,\n    \"allowJs\": true,\n    \"skipLibCheck\": true\n  },\n  \"include\": [\"**/*.ts\", \"**/*.js\"]\n}\n";
-export declare const EXAMPLE_TEMPLATE = "// Example Buttress local function.\n//\n// Rename (or copy) this file to expose it: files starting with \"_\" are\n// ignored. The tool name is the file name \u2014 \"video-duration.ts\" becomes the\n// tool \"video-duration\", callable over MCP and at\n// POST /functions/video-duration.\n\nexport const meta: ButtressFunctionMeta = {\n  description: 'Report the duration of a video file using ffprobe',\n  parameters: {\n    type: 'object',\n    properties: {\n      path: { type: 'string', description: 'Absolute path to a video file' },\n    },\n    required: ['path'],\n  },\n  timeout: '2m',\n}\n\nexport default async function (\n  { path }: { path: string },\n  context: ButtressFunctionContext,\n): Promise<{ seconds: number }> {\n  const { code, stdout, stderr } = await context.spawn('ffprobe', [\n    '-v',\n    'error',\n    '-show_entries',\n    'format=duration',\n    '-of',\n    'default=noprint_wrappers=1:nokey=1',\n    path,\n  ])\n\n  if (code !== 0) throw new Error(`ffprobe failed (${code}): ${stderr}`)\n\n  return { seconds: Number(String(stdout).trim()) }\n}\n";
+export declare const EXAMPLE_TEMPLATE = "// Example Buttress local function.\n//\n// Rename (or copy) this file to expose it: files starting with \"_\" are\n// ignored. The tool name is the file name \u2014 \"video-duration.ts\" becomes the\n// tool \"video-duration\", callable over MCP, at POST /functions/video-duration\n// with a JSON body, and at GET /functions/video-duration?path=... with the\n// input in the query string.\n\nexport const meta: ButtressFunctionMeta = {\n  description: 'Report the duration of a video file using ffprobe',\n  parameters: {\n    type: 'object',\n    properties: {\n      path: { type: 'string', description: 'Absolute path to a video file' },\n    },\n    required: ['path'],\n  },\n  timeout: '2m',\n}\n\nexport default async function (\n  { path }: { path: string },\n  context: ButtressFunctionContext,\n): Promise<{ seconds: number }> {\n  const { code, stdout, stderr } = await context.spawn('ffprobe', [\n    '-v',\n    'error',\n    '-show_entries',\n    'format=duration',\n    '-of',\n    'default=noprint_wrappers=1:nokey=1',\n    path,\n  ])\n\n  if (code !== 0) throw new Error(`ffprobe failed (${code}): ${stderr}`)\n\n  return { seconds: Number(String(stdout).trim()) }\n}\n";

package/lib/functions/types.d.ts

@@ -60,6 +60,28 @@ export type CompletionResult = {
         total_tokens: number;
     };
 };
+export type EmbeddingOptions = {
+    model?: string;
+    text: string;
+    /** llama.cpp normalization mode; 2 (L2) is the native default. */
+    embd_normalize?: number;
+};
+export type EmbeddingResult = {
+    /** Plain numbers (not a cross-realm Float32Array), ready for JSON or sqlite-vec. */
+    embedding: number[];
+};
+export type TokenizeOptions = {
+    model?: string;
+    text: string;
+    params?: Record<string, any>;
+};
+export type TokenizeResult = Record<string, any> & {
+    tokens: number[];
+};
+export type DetokenizeOptions = {
+    model?: string;
+    tokens: number[];
+};
 export type TranscribeOptions = {
     model?: string;
     /** Absolute (or functions-dir relative) path to an audio file. */
@@ -85,6 +107,10 @@ export type FunctionContext = {
     spawn: (command: string, args?: string[], options?: SpawnOptions) => Promise<SpawnResult>;
     buttress: {
         completion: (options: CompletionOptions) => Promise<CompletionResult>;
+        /** GGML only; the selected generator must set `model.embedding = true`. */
+        embedding: (options: EmbeddingOptions) => Promise<EmbeddingResult>;
+        tokenize: (options: TokenizeOptions) => Promise<TokenizeResult>;
+        detokenize: (options: DetokenizeOptions) => Promise<string>;
         transcribe: (options: TranscribeOptions) => Promise<any>;
         synthesize: (options: SynthesizeOptions) => Promise<SynthesizeResult>;
     };
@@ -159,7 +185,7 @@ export type WorkspaceAuthInfo = {
 export type AuthRequestInfo = {
     method: string;
     path: string;
-    /** Function name for `POST /functions/<name>`; undefined for list and MCP. */
+    /** Function name for `GET`/`POST /functions/<name>`; undefined for list and MCP. */
     name?: string;
     headers: Record<string, string | undefined>;
     query: Record<string, any>;

package/lib/index.d.ts

@@ -2,13 +2,14 @@ import type { AnyElysia } from 'elysia';
 import * as backendCore from '@fugood/buttress-backend-core';
 import { AutodiscoverService } from './autodiscover';
 import type { Config } from './types';
+import { compareVersions } from './utils/update';
 import type { FunctionsConfig, FunctionsService } from './functions';
 export { startModelDownload } from '@fugood/buttress-backend-core';
 export { processConfig } from './utils/config';
 export { resolveFunctionsConfig } from './functions';
 export type { FunctionsConfig, FunctionsService } from './functions';
 export declare const checkForUpdates: () => Promise<string | null>;
-export declare const compareVersions: (current: string, latest: string) => boolean;
+export { compareVersions };
 export declare const logUpdateMessage: (latestVersion: string) => void;
 export declare const checkAndNotifyUpdates: () => Promise<void>;
 export type Backend = typeof backendCore;