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

package/lib/routes/functions.check.d.ts

@@ -0,0 +1,13 @@
+/**
+ * End-to-end check for the local function endpoints.
+ *
+ * Boots a real server on an ephemeral port against a temporary functions
+ * directory, then exercises the HTTP list/call/SSE paths and a full MCP
+ * initialize → tools/list → tools/call round trip.
+ *
+ *   bun src/routes/functions.check.ts
+ *
+ * Not a jest test: it needs a real Elysia listener and the native transpiler,
+ * neither of which fits the root jest (jsdom + React Native preset) project.
+ */
+export {};

package/lib/routes/functions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Local function endpoints (EXPERIMENTAL).
+ *
+ *   GET  /functions            list callable functions
+ *   POST /functions/:name      run one; add ?stream=1 for SSE progress.
+ *                              multipart bodies stage file fields inline and
+ *                              inject their server paths into the input
+ *   GET  /functions/:name      run one with the query string as its input
+ *   POST /functions/mcp        MCP (Streamable HTTP, stateless)
+ *   GET  /functions/files/*    download a file a function wrote (context.fileUrl)
+ *   POST /functions/upload     stage an input file for a function call
+ *
+ * Enable via TOML config: [functions] enabled = true, dir = "./functions"
+ */
+import type { FunctionsService } from '../functions';
+import type { Config } from '../types';
+export default function factory(config: Config, functions: FunctionsService): import("../types").ButtressApp;

package/lib/routes/generator-cache.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Warm-generator cache shared by the sessionless HTTP surfaces (compatibility
+ * routes and local functions).
+ *
+ * Generators are expensive to start (model load + context alloc), so entries
+ * are kept warm and reference-counted by in-flight requests: only idle entries
+ * (`activeRequests === 0`) are ever evicted, and the map doubles as an LRU
+ * because re-inserting on use moves a key to the end.
+ *
+ * Each caller creates its own cache instance (one per backend family) but the
+ * bookkeeping — in-flight de-duplication, retain/release, eviction — lives here.
+ */
+export type GeneratorCacheEntry = {
+    id: string;
+    type: string;
+    config: any;
+    repoId: string;
+    initialized: boolean;
+    activeRequests: number;
+};
+export type ResolvedGeneratorRequest = {
+    type: string;
+    /** Cache key and model identity for this request. */
+    repoId: string;
+    mergedConfig: any;
+};
+export type GeneratorCacheOptions = {
+    /** Warm entries kept alive; the oldest idle entries are finalized beyond it. */
+    max: number;
+    /** Pick the configured generator that serves `requestedModel`. */
+    resolve: (config: any, requestedModel?: string) => ResolvedGeneratorRequest;
+    /** Post-start preparation (typically `initContext`). */
+    prepare: (backend: any, entry: GeneratorCacheEntry) => Promise<void>;
+};
+type ConfiguredGeneratorResolverOptions = {
+    family: string;
+    types: readonly string[];
+};
+/**
+ * Model identity shared by local generators whose repository can contain
+ * several weight files.
+ */
+export declare const configuredGeneratorModelId: (generatorConfig: any) => string;
+/**
+ * Build a resolver for generator families that must use an explicitly
+ * configured model. STT and TTS intentionally reject unknown models instead
+ * of silently loading different weights or voices.
+ */
+export declare const createConfiguredGeneratorResolver: ({ family, types }: ConfiguredGeneratorResolverOptions) => (config: any, requestedModel?: string) => ResolvedGeneratorRequest;
+export declare const createGeneratorCache: ({ max, resolve, prepare }: GeneratorCacheOptions) => {
+    getOrCreate: (backend: any, config: any, requestedModel: string | undefined, logPrefix: string) => Promise<GeneratorCacheEntry>;
+    release: (backend: any, entry: GeneratorCacheEntry | null | undefined, logPrefix: string) => Promise<void>;
+};
+/** Best-effort reader teardown: sources may already be closed or errored. */
+export declare function cancelReaderBestEffort(reader: {
+    cancel: () => Promise<unknown>;
+}): void;
+export {};

package/lib/routes/index.d.ts

@@ -3,3 +3,4 @@ export { default as file } from './file';
 export { default as status } from './status';
 export { default as openaiCompatFactory } from './openai-compat';
 export { default as anthropicMessagesFactory } from './anthropic-messages';
+export { default as functionsFactory } from './functions';

package/lib/routes/llm-shared.d.ts

@@ -1,33 +1,36 @@
 /**
- * Shared helpers for LLM-backed compatibility routes (OpenAI / Anthropic).
+ * Shared helpers for LLM-backed sessionless routes (OpenAI / Anthropic
+ * compatibility endpoints and local functions).
  *
- * The generator cache is module-scoped so different compatibility routes
- * (e.g. /oai-compat and /anthropic-messages) reuse the same warm generator
- * for a given model instead of duplicating contexts.
+ * The generator cache is module-scoped so every caller reuses the same warm
+ * generator for a given model instead of duplicating contexts.
  */
+import type { GeneratorCacheEntry } from './generator-cache';
+export type { GeneratorCacheEntry };
+export { cancelReaderBestEffort } from './generator-cache';
 export declare const LLM_TYPES: string[];
-export type GeneratorCacheEntry = {
-    id: string;
-    type: string;
-    config: any;
-    repoId: string;
-    initialized: boolean;
-    activeRequests: number;
+/**
+ * Backend options every `messages`-shaped completion needs.
+ *
+ * Without `jinja` the backend never applies the model's own chat template and
+ * the reply degrades into raw-continuation output (`assistant\nassistant\n…`).
+ * `reasoning_format` splits a thinking model's `<think>` block out of `content`
+ * into `reasoning_content` instead of leaving it inline, and thinking stays off
+ * unless the caller asks for it.
+ */
+export declare const CHAT_COMPLETION_DEFAULTS: {
+    readonly jinja: true;
+    readonly add_generation_prompt: true;
+    readonly reasoning_format: 'auto';
+    readonly enable_thinking: false;
 };
-export declare function cancelReaderBestEffort(reader: {
-    cancel: () => Promise<unknown>;
-}): void;
-export declare function releaseGenerator(backend: any, entry: GeneratorCacheEntry | null | undefined, logPrefix?: string): Promise<void>;
 /**
  * Get the LLM backend API for a generator type.
  */
 export declare function getLlmBackend(backend: any, type: string): any;
+export declare function releaseGenerator(backend: any, entry: GeneratorCacheEntry | null | undefined, logPrefix?: string): Promise<void>;
 /**
  * Get or create a cached generator for the requested model.
- *
- * If `requestedModel` matches a configured generator's `model.repo_id`,
- * that config is used; otherwise the first LLM generator is selected and
- * its repo_id is overridden with the requested model.
  */
 export declare function getOrCreateGenerator(backend: any, config: any, requestedModel?: string, logPrefix?: string): Promise<GeneratorCacheEntry>;
 /**

package/lib/routes/stt-shared.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared helpers for speech-to-text on the sessionless paths.
+ *
+ * Mirrors llm-shared: a module-scoped warm-generator cache, reference-counted
+ * by in-flight requests. Unlike the LLM path, an unmatched model is an error
+ * rather than a repo_id override — STT models are identified by repo *and*
+ * filename (several whisper builds live in one repo), so silently substituting
+ * one would load the wrong weights.
+ */
+import type { GeneratorCacheEntry } from './generator-cache';
+export declare const STT_TYPES: string[];
+/** Get the STT backend API for a generator type. */
+export declare function getSttBackend(backend: any, type: string): any;
+export declare function getOrCreateSttGenerator(backend: any, config: any, requestedModel?: string, logPrefix?: string): Promise<GeneratorCacheEntry>;
+export declare function releaseSttGenerator(backend: any, entry: GeneratorCacheEntry | null | undefined, logPrefix?: string): Promise<void>;
+/**
+ * Normalize a transcription call result.
+ *
+ * `ggmlStt.transcribe` resolves a plain object while `onnxStt.transcribe`
+ * returns a ReadableStream of progress events — duck-typed here (never
+ * `instanceof`, which fails across vm realms) so both shapes collapse to the
+ * final result payload.
+ */
+export declare function resolveTranscription(value: any): Promise<any>;
+export type TranscribeRequest = {
+    model?: string;
+    audioPath?: string;
+    audioData?: Uint8Array | Buffer;
+    options?: Record<string, any>;
+};
+/**
+ * Run a transcription against a warm STT generator, releasing it afterwards.
+ */
+export declare function transcribeWith(backend: any, config: any, { model, audioPath, audioData, options }: TranscribeRequest, logPrefix?: string): Promise<any>;

package/lib/routes/tts-shared.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared helpers for text-to-speech on the sessionless paths.
+ *
+ * Mirrors stt-shared: a module-scoped warm-generator cache, reference-counted
+ * by in-flight requests. Like the STT path, an unmatched model is an error
+ * rather than a substitution — synthesizing with the wrong voice is a silent
+ * failure the caller cannot detect.
+ */
+import type { GeneratorCacheEntry } from './generator-cache';
+export declare const TTS_TYPES: string[];
+/** Get the TTS backend API for a generator type (only onnx-tts today). */
+export declare function getTtsBackend(backend: any, _type: string): any;
+export declare function getOrCreateTtsGenerator(backend: any, config: any, requestedModel?: string, logPrefix?: string): Promise<GeneratorCacheEntry>;
+export declare function releaseTtsGenerator(backend: any, entry: GeneratorCacheEntry | null | undefined, logPrefix?: string): Promise<void>;
+export type SynthesizeRequest = {
+    model?: string;
+    text: string;
+    /** Passed to the backend verbatim; `options.speaker` picks a registered voice. */
+    options?: Record<string, any>;
+};
+export type SynthesizeBackendResult = {
+    cachedId: string;
+    /**
+     * Path into the TTS output cache. The cache owns this file and may evict it
+     * — callers that need the audio beyond the immediate request must copy it.
+     */
+    cachedFile: string;
+    sampling_rate: number;
+    channels: number;
+};
+/**
+ * Run a synthesis against a warm TTS generator, releasing it afterwards.
+ */
+export declare function synthesizeWith(backend: any, config: any, { model, text, options }: SynthesizeRequest, logPrefix?: string): Promise<SynthesizeBackendResult>;

package/lib/services/create-onnx-init-context.d.ts

@@ -0,0 +1,10 @@
+import { ReadableStream } from 'node:stream/web';
+import type { EventStream, ServiceContext } from '../types';
+type InitContextBackend = {
+    initContext: (id: string, property: Record<string, unknown> & {
+        onProgress: (progress: number) => void;
+    }) => Promise<unknown>;
+};
+type GetBackend = (backend: ServiceContext['backend']) => InitContextBackend;
+export default function createOnnxInitContext(getBackend: GetBackend): ({ backend }: ServiceContext, id: string, property: Record<string, unknown> | undefined) => ReadableStream<EventStream>;
+export {};

package/lib/services/onnx-stt.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { ReadableStream } from 'node:stream/web';
+import type { ReadableStream } from 'node:stream/web';
 import type { ServiceContext, EventStream, Expand } from '../types';
 export declare const schemas: {
     initContext: z.ZodTuple<[z.ZodString, z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>], null>;

package/lib/services/onnx-tts.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { ReadableStream } from 'node:stream/web';
+import type { ReadableStream } from 'node:stream/web';
 import type { ServiceContext, EventStream, Expand } from '../types';
 export declare const schemas: {
     initContext: z.ZodTuple<[z.ZodString, z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>], null>;

package/lib/types.d.ts

@@ -39,6 +39,20 @@ export type GlobalConfig = {
         enabled?: boolean;
         cors_allowed_origins?: string | string[];
     };
+    functions?: {
+        enabled?: boolean;
+        /** Directory holding local function files, relative to the config file. */
+        dir?: string;
+        /** Allow calls on a server with no workspace binding (off by default). */
+        allow_unauthenticated?: boolean;
+        /** Default per-call deadline; ms number or duration string like "5m". */
+        default_timeout?: HumanReadableUnit;
+        /** Watch the functions dir and reload eagerly on change (off by default). */
+        hot_reload?: boolean;
+        /** Free-form table handed to functions as `context.config`. */
+        config?: Record<string, any>;
+        cors_allowed_origins?: string | string[];
+    };
 } & Record<string, any>;
 export type AutodiscoverConfig = {
     udp: {
@@ -112,6 +126,15 @@ export type ServerInfo = {
         id: string;
         name?: string;
     };
+    /**
+     * Local function surface. Only a flag and a count: the whole ServerInfo is
+     * serialized into every UDP ANNOUNCE datagram, so the tool list itself must
+     * never go in here.
+     */
+    functions?: {
+        enabled: boolean;
+        count: number;
+    };
 };
 export type EventStream = {
     event: string;

package/lib/utils/functionsAuthGuard.d.ts

@@ -0,0 +1,12 @@
+import type { LoadedAuthFunction } from '../functions/types';
+export type FunctionsAuthGuardOptions = {
+    allowUnauthenticated: boolean;
+    allowedOrigins?: string | string[];
+    /**
+     * Resolve the operator's `_auth` function; null when none exists. A
+     * rejection (present-but-broken auth file) fails closed: every call is
+     * rejected until the file loads again.
+     */
+    getCustomAuth?: () => Promise<LoadedAuthFunction | null>;
+};
+export declare const createFunctionsAuthGuard: ({ allowUnauthenticated, allowedOrigins, getCustomAuth, }: FunctionsAuthGuardOptions) => any;

package/lib/utils/update.d.ts

@@ -0,0 +1,38 @@
+export declare const isWindows: boolean;
+export type InstallMethod = 'binary' | 'npm' | 'bun' | 'pnpm' | 'yarn' | 'unknown';
+export interface DetectedInstall {
+    method: InstallMethod;
+    execPath?: string;
+    installDir?: string;
+    installRoot?: string;
+    scriptPath?: string;
+}
+export declare const compareVersions: (current: string, latest: string) => boolean;
+export declare const detectChannel: ({ version }?: {
+    version?: string;
+}) => "beta" | "release";
+export declare const detectInstallMethod: ({ execPath, scriptPath, homeDir, realpath, }?: {
+    execPath?: string;
+    scriptPath?: string;
+    homeDir?: string;
+    realpath?: (p?: string) => string | undefined;
+}) => DetectedInstall;
+export declare const fetchVersionInfo: (channel: string) => Promise<{
+    version: string;
+}>;
+export declare const fetchNpmVersionInfo: (channel: string) => Promise<{
+    version: string;
+}>;
+export declare const fetchLatestVersionInfo: (channel: string, method: InstallMethod) => Promise<{
+    version: string;
+}>;
+export declare const updateNpm: (channel: string) => void;
+export declare const updateBun: (channel: string) => void;
+export interface BinaryUpdateOptions {
+    installDir?: string;
+    ggmlVariant?: string;
+}
+export declare const updateBinary: (channel: string, { installDir, ggmlVariant }?: BinaryUpdateOptions) => Promise<void>;
+export declare const runUpdateForMethod: (method: InstallMethod, channel: string, detected?: DetectedInstall, options?: {
+    ggmlVariant?: string;
+}) => Promise<void>;

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@fugood/buttress-server",
-  "version": "2.25.0",
+  "version": "2.25.1-beta.1",
   "main": "lib/index.mjs",
   "types": "lib/index.d.ts",
   "type": "module",
   "bin": {
     "bricks-buttress": "./bin/bricks-buttress"
   },
+  "s3url": {
+    "release": "https://cdn.bricks.tools/bricks-buttress/release",
+    "beta": "https://cdn.bricks.tools/bricks-buttress/beta"
+  },
   "files": [
     "lib",
     "bin",
@@ -16,6 +20,11 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "tsdown -c rolldown.config.js --config-loader native && tsc --noCheck --emitDeclarationOnly",
+    "build:dist": "bun scripts/build-distribution.js",
+    "release": "bun scripts/build-distribution.js",
+    "release-beta": "bun scripts/build-distribution.js --beta",
+    "upload-release": "node scripts/upload-release.js",
+    "upload-beta": "node scripts/upload-release.js --beta",
     "prepublish": "bun run build",
     "dev": "bun src/index.ts",
     "start": "bun lib/index.mjs",
@@ -30,22 +39,33 @@
   "dependencies": {
     "@elysiajs/cors": "^1.1.1",
     "@elysiajs/node": "^1.4.2",
-    "@fugood/llama.node": "1.7.11",
+    "@fugood/llama.node": "1.7.14",
     "@fugood/whisper.node": "^1.1.1",
     "@huggingface/gguf": "^0.3.2",
     "@iarna/toml": "^3.0.0",
+    "@modelcontextprotocol/sdk": "^1.15.0",
     "bytes": "^3.1.0",
+    "chroma-js": "^2.1.2",
     "elysia": "^1.4.19",
     "jose": "^5.9.6",
+    "json5": "^2.0.1",
+    "lodash": "^4.17.4",
+    "mathjs": "^12.2.0",
+    "md5": "^2.2.1",
+    "moment": "^2.22.2",
     "ms": "^2.1.1",
+    "nanoid": "^3.1.4",
     "node-machine-id": "^1.1.12",
     "onnxruntime-node": "1.24.3",
+    "oxc-transform": "^0.105.0",
+    "qs": "^6.15.0",
     "sharp": "^0.34.1",
+    "voca": "^1.4.1",
     "zod": "^3.25.76"
   },
   "devDependencies": {
     "tsdown": "^0.22.4",
     "typescript": "^7.0.2"
   },
-  "gitHead": "a2690b315c7043b65d71f21609b65358cd50d9a4"
+  "gitHead": "bc61ad0f7d649c7d30674a78d5cfbe22591564e5"
 }

package/public/status.html

@@ -581,6 +581,39 @@
           </div>
         </div>
       </div>
+
+      <!-- Local Functions (hidden unless enabled) -->
+      <div class="card" id="functionsCard" style="display:none">
+        <div class="card-header">
+          <span class="card-title">Local Functions <span class="badge badge-warning">experimental</span></span>
+          <span class="badge badge-info" id="functionsCount">0 functions</span>
+        </div>
+        <div id="functionsSummary"></div>
+        <div class="section">
+          <div class="section-title collapsible" onclick="toggleSection(this)">Call History</div>
+          <div class="collapsible-content" id="functionsCallHistory">
+            <div class="empty-state">No function calls</div>
+          </div>
+        </div>
+        <div class="section">
+          <div class="section-title collapsible" onclick="toggleSection(this)">Upload History</div>
+          <div class="collapsible-content" id="functionsUploadHistory">
+            <div class="empty-state">No uploads</div>
+          </div>
+        </div>
+        <div class="section">
+          <div class="section-title collapsible" onclick="toggleSection(this)">Download History</div>
+          <div class="collapsible-content" id="functionsDownloadHistory">
+            <div class="empty-state">No downloads</div>
+          </div>
+        </div>
+        <div class="section">
+          <div class="section-title collapsible" onclick="toggleSection(this)">Auth History</div>
+          <div class="collapsible-content" id="functionsAuthHistory">
+            <div class="empty-state">No auth activity</div>
+          </div>
+        </div>
+      </div>
     </div>
   </div>
 
@@ -1144,6 +1177,89 @@
           `<span class="badge badge-error">Failed</span>`
         },
       ])
+
+      renderFunctionsStatus(status.functions || {})
+    }
+
+    // Local Functions activity (calls, uploads, downloads, auth)
+    function renderFunctionsStatus(fns) {
+      document.getElementById('functionsCard').style.display = fns.enabled ? '' : 'none'
+      if (!fns.enabled) return
+
+      const count = fns.count ?? 0
+      document.getElementById('functionsCount').textContent =
+        `${count} function${count !== 1 ? 's' : ''}`
+
+      const c = fns.counters || {}
+      const summary = document.getElementById('functionsSummary')
+      const stat = (label, value, bad) => `
+        <tr>
+          <td>${label}</td>
+          <td>${value}</td>
+          <td>${bad ? `<span class="badge badge-error">${bad}</span>` : '-'}</td>
+        </tr>
+      `
+      withScrollPreserve(summary, () => {
+        summary.innerHTML = `
+          <div class="table-wrapper">
+            <div class="table-inner">
+              <table>
+                <thead>
+                  <tr><th>Activity</th><th>Total</th><th>Problems</th></tr>
+                </thead>
+                <tbody>
+                  ${stat('Calls', c.calls?.total ?? 0, c.calls?.failed ? `${c.calls.failed} failed` : '')}
+                  ${stat('Uploads', `${c.uploads?.total ?? 0} (${formatBytes(c.uploads?.bytes ?? 0)})`, c.uploads?.failed ? `${c.uploads.failed} failed` : '')}
+                  ${stat('Downloads', `${c.downloads?.total ?? 0} (${formatBytes(c.downloads?.bytes ?? 0)})`, c.downloads?.missed ? `${c.downloads.missed} missed` : '')}
+                  ${stat('Auth checks', c.auth?.total ?? 0, c.auth?.denied ? `${c.auth.denied} denied` : '')}
+                </tbody>
+              </table>
+            </div>
+          </div>
+        `
+      })
+
+      const history = fns.history || {}
+      const statusBadge = i => i.success ?
+        '<span class="badge badge-success">Success</span>' :
+        `<span class="badge badge-error">Failed: ${escapeHtml(i.error || 'Unknown')}</span>`
+
+      renderHistory('functionsCallHistory', history.calls || [], [
+        { label: 'Time', render: i => `<span class="timestamp">${formatRelativeTime(i.timestamp)}</span>` },
+        { label: 'Function', render: i => escapeHtml(i.name) },
+        { label: 'Surface', render: i => `<span class="badge badge-info">${escapeHtml(i.surface || '-')}</span>` },
+        { label: 'Duration', render: i => `${(i.durationMs / 1000).toFixed(2)}s` },
+        { label: 'Status', render: statusBadge },
+      ])
+
+      renderHistory('functionsUploadHistory', history.uploads || [], [
+        { label: 'Time', render: i => `<span class="timestamp">${formatRelativeTime(i.timestamp)}</span>` },
+        { label: 'Name', render: i => escapeHtml(i.name) },
+        { label: 'Via', render: i => `<span class="badge badge-info">${i.source === 'call' ? 'multipart call' : 'upload'}</span>` },
+        { label: 'Size', render: i => formatBytes(i.size ?? 0) },
+        { label: 'Status', render: statusBadge },
+      ])
+
+      renderHistory('functionsDownloadHistory', history.downloads || [], [
+        { label: 'Time', render: i => `<span class="timestamp">${formatRelativeTime(i.timestamp)}</span>` },
+        { label: 'Path', render: i => escapeHtml(i.path) },
+        { label: 'Size', render: i => i.success ? formatBytes(i.size ?? 0) : '-' },
+        { label: 'Status', render: i => i.success ?
+          '<span class="badge badge-success">Served</span>' :
+          '<span class="badge badge-error">Not found</span>'
+        },
+      ])
+
+      renderHistory('functionsAuthHistory', history.auth || [], [
+        { label: 'Time', render: i => `<span class="timestamp">${formatRelativeTime(i.timestamp)}</span>` },
+        { label: 'Request', render: i => escapeHtml(`${i.method || ''} ${i.path || ''}`.trim()) },
+        { label: 'Mode', render: i => escapeHtml(i.mode || '-') },
+        { label: 'Subject', render: i => escapeHtml(i.subject || '-') },
+        { label: 'Outcome', render: i => i.outcome === 'allowed' ?
+          '<span class="badge badge-success">Allowed</span>' :
+          `<span class="badge badge-error">${escapeHtml(i.outcome || 'denied')}</span>`
+        },
+      ])
     }
 
     // Fallback: Fetch status via HTTP polling