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

package/lib/types.d.ts

@@ -0,0 +1,181 @@
+import type { Elysia, SingletonBase } from 'elysia';
+import type { ReadableStream } from 'node:stream/web';
+import type { Backend } from './index';
+export type HumanReadableUnit = number | string;
+type NormalizeKeys = 'max_body_size' | 'session_timeout' | 'max_size_bytes';
+export type DeepNormalize<T> = T extends object ? {
+    [K in keyof T]: K extends NormalizeKeys ? number : DeepNormalize<T[K]>;
+} : T;
+export type HumanReadableServerConfig = {
+    id?: string;
+    name?: string;
+    port?: number;
+    log_level?: 'debug' | 'info' | 'warn' | 'error';
+    max_body_size?: HumanReadableUnit;
+    session_timeout?: HumanReadableUnit;
+    temp_file_dir?: string;
+};
+export type SessionCacheConfig = {
+    enabled?: boolean;
+    max_size_bytes?: HumanReadableUnit;
+    max_entries?: number;
+};
+export type RuntimeConfig = {
+    cache_dir?: string;
+    huggingface_token?: string;
+    session_cache?: SessionCacheConfig;
+} & Record<string, any>;
+export type GeneratorType = 'ggml-llm' | 'ggml-stt' | 'mlx-llm' | 'onnx-stt' | 'onnx-tts';
+export type GeneratorConfig = {
+    type: GeneratorType;
+} & Record<string, any>;
+export type GlobalConfig = {
+    runtime?: RuntimeConfig;
+    openai_compat?: {
+        enabled?: boolean;
+        cors_allowed_origins?: string | string[];
+    };
+    anthropic_messages?: {
+        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: {
+        port?: number;
+        announcements: {
+            enabled: boolean;
+            interval?: number;
+        };
+        requests: {
+            enabled: boolean;
+            responseDelay?: number;
+        };
+    };
+    http: {
+        enabled: boolean;
+        path?: string;
+        cors?: boolean;
+    };
+    mdns?: {
+        enabled: boolean;
+    };
+};
+export type HumanReadableConfig = {
+    autodiscover?: AutodiscoverConfig | boolean;
+    server?: HumanReadableServerConfig;
+    generators?: GeneratorConfig[];
+} & GlobalConfig;
+export type ServerConfig = {
+    id: string;
+    name: string;
+    port: number;
+    log_level?: 'debug' | 'info' | 'warn' | 'error';
+    max_body_size: number;
+    session_timeout: number;
+    temp_file_dir: string;
+};
+export type Config = {
+    autodiscover: AutodiscoverConfig | null;
+    server: ServerConfig;
+    global: GlobalConfig;
+    generators: GeneratorConfig[];
+};
+export type GeneratorInfo = {
+    type: GeneratorType;
+    /** Performance score 0–100 from buttress-hardware-guardrails. */
+    score?: number;
+    /** Whether the host has an accelerator (GPU/Metal/etc) for this backend. */
+    hasGpu?: boolean;
+    /** Usable memory in bytes for this backend (GPU when present, else CPU). */
+    usableBytes?: number;
+} & Record<string, any>;
+export type ServerInfo = {
+    id: string;
+    name: string;
+    version: string;
+    address: string;
+    addresses?: string[];
+    port: number;
+    url: string;
+    generators: GeneratorInfo[];
+    authentication: {
+        required: boolean;
+        type: string;
+        /** Issuer key id (when type === 'workspace-jwt'). */
+        kid?: string;
+        /** True when buttress is paired with a workspace. */
+        bound?: boolean;
+    };
+    /** Workspace identity (only present when paired). */
+    workspace?: {
+        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;
+    data: any;
+};
+export type StreamReaderEntry = {
+    reader: ReadableStreamDefaultReader<EventStream>;
+    peerId: string;
+};
+export type Session = {
+    streams: Map<string, ReadableStream<EventStream>>;
+    streamReaders: Map<string, StreamReaderEntry>;
+    generators: Set<string>;
+    fileManager: import('./utils/SessionFileManager').SessionFileManager;
+    initializedContexts: Set<string>;
+    timeout: ReturnType<typeof setTimeout> | null;
+    identity?: import('./utils/buttressAuth').VerifiedIdentity | null;
+    ready?: Promise<boolean>;
+    currentPeerId?: string | null;
+};
+export type State = {
+    serverInfo: ServerInfo;
+    backend: Backend;
+    config: Config;
+    sessions: Map<string, Session>;
+    workspaceState: import('./utils/workspaceState').WorkspaceState;
+};
+type ButtressSingleton = SingletonBase & {
+    store: State;
+};
+export type ButtressApp = Elysia<any, ButtressSingleton, any, any, any, any, any>;
+export type MethodReturnType = string | object | number | boolean | null | ReadableStream<EventStream>;
+export type ServiceContext = State & {
+    peerId: string;
+    session: Session;
+};
+export type ServiceMethodHandler<InputType = any, OutputType = any> = (ctx: ServiceContext, property: InputType) => OutputType | Promise<OutputType>;
+export interface ServiceHandler {
+    [method: string]: ServiceMethodHandler;
+}
+export type Expand<T> = T extends object ? {
+    [K in keyof T]: Expand<T[K]>;
+} : T;
+export {};

package/lib/utils/SessionFileManager.d.ts

@@ -0,0 +1,16 @@
+import type { ReadableStream as NodeReadableStream } from 'node:stream/web';
+type UploadData = Buffer | ArrayBuffer | ReadableStream | NodeReadableStream;
+export declare class SessionFileManager {
+    sessionId: string;
+    private sessionDir;
+    private registry;
+    constructor(sessionId: string, tempDir: string);
+    register(filename: string, realPath: string, opts?: {
+        owned?: boolean;
+        ttl?: number;
+    }): void;
+    resolve(filename: string): string | null;
+    storeUpload(originalName: string, data: UploadData): Promise<string>;
+    destroy(): Promise<void>;
+}
+export {};

package/lib/utils/buttressAuth.d.ts

@@ -0,0 +1,25 @@
+import type { WorkspaceBinding } from './workspaceState';
+export declare const ACCESS_TOKEN_KIND = "ba";
+export interface AccessTokenClaims {
+    k: typeof ACCESS_TOKEN_KIND;
+    w_id: string;
+    st: 'ws' | 'dev';
+    sid: string;
+    jti?: string;
+    iat?: number;
+    exp: number;
+}
+export interface VerifiedIdentity {
+    workspaceId: string;
+    subjectType: 'ws' | 'dev';
+    subjectId: string;
+    jti?: string;
+    exp: number;
+}
+/**
+ * Extract a buttress access token from a request. Prefers the Authorization
+ * Bearer header; falls back to ?access_token / ?token query params for clients
+ * (browser WebSocket, RN file transfer) that can't set headers.
+ */
+export declare const extractAccessTokenFromRequest: (headers: Record<string, string | undefined> | undefined, query: Record<string, unknown> | undefined) => string | null;
+export declare const verifyAccessToken: (token: string | null, binding: WorkspaceBinding | null) => Promise<VerifiedIdentity | null>;

package/lib/utils/config.d.ts

@@ -0,0 +1,21 @@
+import type { Config, AutodiscoverConfig, HumanReadableConfig } from '../types';
+import type { Backend } from '../index';
+export declare const deepMerge: (target?: Record<string, any>, source?: Record<string, any>) => Record<string, any>;
+export declare const normalizeConfigInput: (input: any) => null | Record<string, any>;
+export declare const mergeGeneratorConfig: (base: any, override: any) => Record<string, any>;
+export declare const resolveDefaultConfig: (defaultConfigs: Config, backend: Backend, type: string, modelId: string | null) => Record<string, any> | null;
+/**
+ * Normalize autodiscover config input.
+ * - undefined/false → null (disabled)
+ * - true → default config
+ * - object → merge with defaults
+ */
+export declare const normalizeAutodiscoverConfig: (input: AutodiscoverConfig | boolean | undefined) => AutodiscoverConfig | null;
+export declare const resolveSupportedGenerators: (config: Config, defaultTypes: string[]) => {
+    type: string;
+}[];
+/**
+ * Process raw user config (HumanReadableConfig) into Config.
+ * Handles: device defaults, value normalization (bytes/ms), structure splitting.
+ */
+export declare const processConfig: (input: HumanReadableConfig | null) => Config;

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/httpAuthGuard.d.ts

@@ -0,0 +1 @@
+export declare const buttressAuthGuard: any;

package/lib/utils/net.d.ts

@@ -0,0 +1,6 @@
+export declare const getLocalIpAddress: () => string | null;
+export interface BroadcastInterface {
+    address: string;
+    broadcast: string;
+}
+export declare const getBroadcastInterfaces: () => BroadcastInterface[];

package/lib/utils/router.d.ts

@@ -0,0 +1,2 @@
+import type { ButtressApp } from '../types';
+export declare const createRouter: (options?: any) => ButtressApp;

package/lib/utils/serialize.d.ts

@@ -0,0 +1,2 @@
+export declare const deserialize: (input: string) => any;
+export declare const serialize: (output: any) => string;

package/lib/utils/serverCaps.d.ts

@@ -0,0 +1,4 @@
+import type { GeneratorInfo, GeneratorType } from '../types';
+export declare const enrichGeneratorsWithCaps: (generators: {
+    type: GeneratorType;
+}[]) => Promise<GeneratorInfo[]>;

package/lib/utils/sessionGuard.d.ts

@@ -0,0 +1,33 @@
+import type { Session } from '../types';
+type AnyRecord = Record<string, unknown>;
+/**
+ * Extract a session id from the `X-Buttress-Sess-Id` request header.
+ * Query-param fallback is intentionally not supported: session ids would
+ * otherwise show up in proxy access logs and browser history, and there is
+ * no transport in our supported clients that can't set custom headers.
+ */
+export declare const extractSessionIdFromRequest: (headers: Record<string, string | undefined> | undefined) => string | null;
+/**
+ * Elysia `beforeHandle` guard for HTTP routes that operate on a buttress
+ * session (file upload/download). Verifies:
+ *
+ *   1. A session id is supplied via the `X-Buttress-Sess-Id` header.
+ *   2. The session exists in the in-memory map (i.e. `init` has been issued
+ *      over WS for this client).
+ *   3. When the server is bound to a workspace, the request's access token
+ *      identity matches the identity recorded on the session — preventing
+ *      one device in a workspace from acting on another device's session.
+ *
+ * Handlers can re-extract the resolved session via `resolveGuardedSession`.
+ */
+export declare const buttressSessionGuard: any;
+/**
+ * Re-resolve the session that `buttressSessionGuard` validated. Returns null
+ * only if called outside the guard's protection (programming error). Handlers
+ * should treat null as 500 / unreachable.
+ */
+export declare const resolveGuardedSession: (store: AnyRecord, headers: Record<string, string | undefined>) => {
+    sessionId: string;
+    session: Session;
+} | null;
+export {};

package/lib/utils/test-caps.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Display model capabilities in a Markdown table format
+ * @param {Object} options - Display options
+ * @param {Array<string>} options.modelIds - Array of model repository IDs
+ * @param {Object|null} options.defaultConfig - Default configuration from TOML
+ * @returns {Promise<void>}
+ */
+export declare function showModelsTable({ modelIds, defaultConfig, }?: {
+    modelIds?: string[];
+    defaultConfig?: any;
+}): Promise<void>;
+/**
+ * Test ggml-llm capabilities for a backend type with optional model configuration
+ * @param {Object} options - Test options
+ * @param {string|null} options.modelId - Model repository ID
+ * @param {Object|null} options.defaultConfig - Default configuration from TOML
+ * @returns {Promise<void>}
+ */
+export declare function testGgmlLlmCapabilities({ modelId, defaultConfig, }?: {
+    modelId?: string | null;
+    defaultConfig?: any;
+}): Promise<void>;
+/**
+ * Display STT model capabilities in a Markdown table format
+ * @param {Object} options - Display options
+ * @param {Array<string>} options.modelIds - Array of model IDs (format: repo_id:filename)
+ * @param {Object|null} options.defaultConfig - Default configuration from TOML
+ * @returns {Promise<void>}
+ */
+export declare function showSttModelsTable({ modelIds, defaultConfig, }?: {
+    modelIds?: string[];
+    defaultConfig?: any;
+}): Promise<void>;
+/**
+ * Test ggml-stt capabilities for a backend type with optional model configuration
+ * @param {Object} options - Test options
+ * @param {string|null} options.modelId - Model ID (format: repo_id:filename)
+ * @param {Object|null} options.defaultConfig - Default configuration from TOML
+ * @returns {Promise<void>}
+ */
+/**
+ * Display MLX model capabilities in a Markdown table format.
+ *
+ * MLX getCapabilities is a platform/python check (no per-model GGUF metadata),
+ * so the table shows hardware fit based on unified memory and model repo IDs.
+ */
+export declare function showMlxModelsTable({ modelIds, defaultConfig, }?: {
+    modelIds?: string[];
+    defaultConfig?: any;
+}): Promise<void>;
+/**
+ * Test MLX LLM capabilities for a single model with detailed output
+ */
+export declare function testMlxLlmCapabilities({ modelId, defaultConfig, }?: {
+    modelId?: string | null;
+    defaultConfig?: any;
+}): Promise<void>;
+export declare function testGgmlSttCapabilities({ modelId, defaultConfig, }?: {
+    modelId?: string | null;
+    defaultConfig?: any;
+}): Promise<void>;

package/lib/utils/workspaceState.d.ts

@@ -0,0 +1,21 @@
+export interface WorkspaceBinding {
+    id: string;
+    name?: string;
+    serverId: string;
+    issuerPublicKey: string;
+    kid: string;
+    boundAt: string;
+}
+export interface ServerKeyPair {
+    publicKeySpki: string;
+    privateKeyPkcs8: string;
+    kid: string;
+}
+export interface WorkspaceState {
+    workspace: WorkspaceBinding | null;
+    serverKeyPair: ServerKeyPair | null;
+}
+export declare const resolveStateDir: () => string;
+export declare const resolveStatePath: () => string;
+export declare const loadWorkspaceState: () => WorkspaceState;
+export declare const saveWorkspaceState: (state: WorkspaceState) => Promise<void>;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@fugood/buttress-server",
-  "version": "2.25.0-beta.9",
+  "version": "2.25.1-beta.0",
   "main": "lib/index.mjs",
-  "types": "lib/index.d.mts",
+  "types": "lib/index.d.ts",
   "type": "module",
   "bin": {
     "bricks-buttress": "./bin/bricks-buttress"
@@ -15,7 +15,7 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "build": "tsdown -c rolldown.config.js",
+    "build": "tsdown -c rolldown.config.js --config-loader native && tsc --noCheck --emitDeclarationOnly",
     "prepublish": "bun run build",
     "dev": "bun src/index.ts",
     "start": "bun lib/index.mjs",
@@ -30,20 +30,33 @@
   "dependencies": {
     "@elysiajs/cors": "^1.1.1",
     "@elysiajs/node": "^1.4.2",
-    "@fugood/llama.node": "^1.7.0-rc.11",
-    "@fugood/whisper.node": "^1.0.18",
+    "@fugood/llama.node": "1.7.11",
+    "@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.20.1",
-    "typescript": "^5.9.3"
+    "tsdown": "^0.22.4",
+    "typescript": "^7.0.2"
   },
-  "gitHead": "9274cc21f1e882d26f80e45a972d814d648c861a"
+  "gitHead": "95e3bdbcf4d433d89c5ef7ddc67f046458bfc240"
 }