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

package/lib/functions/types.d.ts

@@ -0,0 +1,196 @@
+import type { Backend } from '../index';
+import type { Config } from '../types';
+import type { VerifiedIdentity } from '../utils/buttressAuth';
+/**
+ * Declarative metadata a local function file exports alongside its handler.
+ *
+ * `parameters` is a raw JSON Schema object: it is handed to MCP `tools/list`
+ * verbatim, so authors describe their input once and every surface agrees.
+ */
+export type FunctionMeta = {
+    description?: string;
+    parameters?: Record<string, any>;
+    /** Per-function deadline. Number of ms, or an `ms()` string like "10m". */
+    timeout?: number | string;
+};
+export type FunctionEmit = (event: string, data?: unknown) => void;
+export type SpawnOptions = {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    /** Written to the child's stdin, which is then closed. */
+    input?: string | Uint8Array;
+    /** 'utf8' (default) resolves stdout/stderr as strings, 'buffer' as Buffer. */
+    encoding?: 'utf8' | 'buffer';
+    /** Cap on captured stdout/stderr per stream (default 8MB). */
+    maxBuffer?: number;
+    onStdout?: (chunk: Buffer) => void;
+    onStderr?: (chunk: Buffer) => void;
+};
+export type SpawnResult = {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string | Buffer;
+    stderr: string | Buffer;
+    /** True when either stream hit `maxBuffer` and capture stopped early. */
+    truncated: boolean;
+};
+/**
+ * `messages` are rendered with the model's own chat template and thinking is
+ * off by default (see `CHAT_COMPLETION_DEFAULTS`); anything passed explicitly
+ * overrides that. Unlisted keys reach the backend verbatim.
+ */
+export type CompletionOptions = {
+    model?: string;
+    messages?: any[];
+    prompt?: string;
+    /** Cap on generated tokens; mapped onto the backend's `n_predict`. */
+    max_tokens?: number;
+    /** Emit reasoning into `reasoning_content` instead of suppressing it. */
+    enable_thinking?: boolean;
+    onToken?: (token: Record<string, any>) => void;
+} & Record<string, any>;
+export type CompletionResult = {
+    content: string;
+    reasoning_content?: string;
+    tool_calls?: any[];
+    interrupted?: boolean;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+};
+export type TranscribeOptions = {
+    model?: string;
+    /** Absolute (or functions-dir relative) path to an audio file. */
+    filePath?: string;
+    /** Raw audio bytes; mutually exclusive with `filePath`. */
+    audioData?: Uint8Array | Buffer;
+    options?: Record<string, any>;
+};
+export type SynthesizeOptions = {
+    model?: string;
+    text: string;
+    /** Passed to the TTS backend verbatim; `options.speaker` picks a voice. */
+    options?: Record<string, any>;
+};
+export type SynthesizeResult = {
+    /** WAV file inside the call's `tempDir` — pair with `context.fileUrl`. */
+    path: string;
+    sampling_rate: number;
+    channels: number;
+};
+/** The second argument every local function handler receives. */
+export type FunctionContext = {
+    spawn: (command: string, args?: string[], options?: SpawnOptions) => Promise<SpawnResult>;
+    buttress: {
+        completion: (options: CompletionOptions) => Promise<CompletionResult>;
+        transcribe: (options: TranscribeOptions) => Promise<any>;
+        synthesize: (options: SynthesizeOptions) => Promise<SynthesizeResult>;
+    };
+    fetch: typeof fetch;
+    log: (...args: unknown[]) => void;
+    emit: FunctionEmit;
+    signal: AbortSignal;
+    env: Record<string, string | undefined>;
+    config: Record<string, any>;
+    /** Per-call scratch directory, created on first access. */
+    tempDir: string;
+    /**
+     * Download URL path for a file inside `tempDir` (relative input resolves
+     * against it). Callers fetch it with the same auth as any function call.
+     */
+    fileUrl: (target: string) => string;
+    dir: string;
+    libs: Record<string, any>;
+};
+export type FunctionHandler = (input: any, context: FunctionContext) => any;
+export type LoadedFunction = {
+    name: string;
+    file: string;
+    meta: FunctionMeta;
+    handler: FunctionHandler;
+    timeoutMs: number;
+    /** Every file in this function's module graph → mtimeMs when it was loaded. */
+    files: Map<string, number>;
+};
+export type FunctionSummary = {
+    name: string;
+    description: string;
+    parameters: Record<string, any>;
+};
+export type FunctionsConfig = {
+    enabled: boolean;
+    dir: string;
+    allowUnauthenticated: boolean;
+    defaultTimeoutMs: number;
+    /**
+     * Watch the functions directory and reload eagerly on change (off by
+     * default). Lazy mtime reload stays active either way.
+     */
+    hotReload: boolean;
+    /** Free-form `[functions.config]` table, surfaced as `context.config`. */
+    userConfig: Record<string, any>;
+};
+/** Per-call dependencies the executor needs from the Elysia store. */
+export type FunctionRuntime = {
+    backend: Backend;
+    config: Config;
+};
+/** Metadata an `_auth` file exports alongside its authorize handler. */
+export type AuthMeta = {
+    /**
+     * How the custom function composes with the built-in workspace auth.
+     * 'both' (default): runs after workspace auth passes, as an extra gate.
+     * 'override': replaces workspace auth — the function is the only authority
+     * (a presented workspace token is still verified into `workspaceAuth`).
+     */
+    mode?: 'override' | 'both';
+};
+/** Workspace-auth outcome handed to a custom auth function. */
+export type WorkspaceAuthInfo = {
+    /** Whether this server is bound to a workspace. */
+    bound: boolean;
+    /** Whether the caller presented a valid workspace access token. */
+    authenticated: boolean;
+    identity: VerifiedIdentity | null;
+};
+/** The first argument the authorize handler receives. */
+export type AuthRequestInfo = {
+    method: string;
+    path: string;
+    /** Function name for `GET`/`POST /functions/<name>`; undefined for list and MCP. */
+    name?: string;
+    headers: Record<string, string | undefined>;
+    query: Record<string, any>;
+    /** Raw bearer token (Authorization header or `?token=`), if any. */
+    token: string | null;
+    workspaceAuth: WorkspaceAuthInfo;
+};
+/** The second argument the authorize handler receives. */
+export type AuthFunctionContext = {
+    log: (...args: unknown[]) => void;
+    fetch: typeof fetch;
+    env: Record<string, string | undefined>;
+    /** The `[functions.config]` table, same as `context.config` in functions. */
+    config: Record<string, any>;
+    dir: string;
+    libs: Record<string, any>;
+};
+/** Only `true` (or `{ ok: true }`) allows the request; anything else denies. */
+export type AuthDecision = boolean | {
+    ok: boolean;
+    /** Response status for a denial, 400–499 (default 403). */
+    status?: number;
+    /** Message returned to the caller on denial. */
+    error?: string;
+};
+export type AuthHandler = (request: AuthRequestInfo, context: AuthFunctionContext) => AuthDecision | Promise<AuthDecision>;
+export type LoadedAuthFunction = {
+    file: string;
+    mode: 'override' | 'both';
+    /** Invoke the operator's authorize handler with its baked-in context. */
+    run: (request: AuthRequestInfo) => Promise<AuthDecision>;
+    /** Every file in the auth module graph → mtimeMs when it was loaded. */
+    files: Map<string, number>;
+};

package/lib/functions/uploads.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Staging of uploaded files for the functions surface.
+ *
+ * Two callers share this: `POST /functions/upload` (standalone staging, one
+ * fresh directory per request) and multipart `POST /functions/<name>` (inline
+ * staging into the call's own scratch directory, so an input file lives and
+ * dies with the call that consumed it).
+ */
+/** Multipart field values that carry a file, duck-typed — never `instanceof`. */
+export declare const isUploadFile: (value: unknown) => value is File;
+export type WrittenUpload = {
+    path: string;
+    name: string;
+    size: number;
+};
+/**
+ * Stream one uploaded file into `targetDir` under its sanitized client name.
+ * Same-named siblings (two multipart files sharing a name) get a numeric
+ * prefix instead of clobbering each other.
+ */
+export declare const writeUploadFile: (targetDir: string, file: File) => Promise<WrittenUpload>;
+/** A caller mistake in the multipart shape — reported as 400, not 500. */
+export declare class MultipartInputError extends Error {
+    constructor(message: string);
+}
+export type StagedUpload = WrittenUpload & {
+    field: string;
+};
+export type MultipartInput = {
+    input: Record<string, any>;
+    staged: StagedUpload[];
+};
+/**
+ * Turn a parsed multipart body into a function input object.
+ *
+ * The optional `input` field carries a JSON object for typed values; every
+ * other string field overlays it as a string, and every file field is staged
+ * into `uploadsDir` with the resulting server-local path injected under the
+ * field's name (an array of paths when the field repeats). Precedence when a
+ * key appears more than once: file path > plain field > `input` JSON.
+ */
+export declare const stageMultipartInput: (body: Record<string, unknown>, uploadsDir: string) => Promise<MultipartInput>;

package/lib/functions/watcher.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Optional eager reload for the functions directory.
+ *
+ * The default reload strategy is lazy (every call stats its module graph), so
+ * a change is only *noticed* on the next call. With `[functions] hot_reload`
+ * an fs.watch keeps the loaded state warm instead: bursts of change events
+ * are debounced and handed to the service, which re-lists functions and
+ * re-loads `_auth` — so a broken save is logged at save time, and the
+ * function count on `/status` and in ANNOUNCE moves without any traffic.
+ *
+ * This is an additive optimization, not a correctness mechanism: the lazy
+ * mtime check keeps running either way, so a missed watch event costs
+ * nothing but immediacy. Watchers are created non-persistent — they never
+ * hold the process open.
+ */
+import fs from 'node:fs';
+export type FunctionsWatcher = {
+    close: () => void;
+};
+export type WatchFn = (target: string, options: {
+    recursive: boolean;
+    persistent: boolean;
+}, listener: (eventType: string, filename: string | Buffer | null) => void) => fs.FSWatcher;
+export type CreateWatcherOptions = {
+    debounceMs?: number;
+    /** Injectable for tests; defaults to `fs.watch`. */
+    watchFn?: WatchFn;
+};
+/**
+ * Watch `dir` recursively and report debounced bursts of changed file names.
+ * Returns null (with a warning) where recursive watching is unavailable —
+ * callers fall back to lazy reload alone.
+ */
+export declare const createFunctionsWatcher: (dir: string, onBurst: (changed: Set<string>) => void, { debounceMs, watchFn }?: CreateWatcherOptions) => FunctionsWatcher | null;

package/lib/index.d.ts

@@ -2,10 +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;
@@ -15,15 +19,19 @@ export interface StartServerOptions {
     config: Config;
     enableOpenAICompat?: boolean;
     enableAnthropicMessages?: boolean;
+    /** Resolved `[functions]` config; null/omitted leaves the feature off. */
+    functions?: FunctionsConfig | null;
 }
-export declare const createServer: ({ backend, router, config, enableOpenAICompat, enableAnthropicMessages, }: StartServerOptions) => Promise<{
+export declare const createServer: ({ backend, router, config, enableOpenAICompat, enableAnthropicMessages, functions: functionsConfig, }: StartServerOptions) => Promise<{
     app: AnyElysia;
     config: Config;
+    functions: FunctionsService | null;
 }>;
-export declare const startServer: ({ backend, router, config, enableOpenAICompat, enableAnthropicMessages, }: StartServerOptions) => Promise<{
+export declare const startServer: ({ backend, router, config, enableOpenAICompat, enableAnthropicMessages, functions: functionsConfig, }: StartServerOptions) => Promise<{
     app: AnyElysia;
     port: number;
     openaiEnabled: boolean;
     anthropicMessagesEnabled: boolean;
+    functions: FunctionsService | null;
     autoDiscover: AutodiscoverService | null;
 }>;