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

package/lib/functions/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Local function system: user-authored `.ts`/`.js` files in a configured
+ * directory, exposed as MCP tools and HTTP endpoints.
+ *
+ * `createFunctionsService` is the single entry point the server wires up; it
+ * owns discovery/reload (registry) and execution (executor), and prepares the
+ * directory for authoring on startup.
+ */
+import type { FunctionEmit, FunctionRuntime, FunctionSummary, FunctionsConfig, LoadedAuthFunction } from './types';
+export { resolveFunctionsConfig } from './config';
+export { FunctionNotFoundError } from './registry';
+export { FunctionAbortError, FunctionTimeoutError } from './executor';
+export { FunctionImportError } from './loader';
+export { AUTH_BASENAME } from './auth';
+export type * from './types';
+export type CallOptions = {
+    runtime: FunctionRuntime;
+    emit?: FunctionEmit;
+    signal?: AbortSignal;
+    callId?: string;
+    /** Which API carried the call — recorded in the status history. */
+    surface?: 'http' | 'sse' | 'mcp';
+};
+export type FunctionsService = {
+    config: FunctionsConfig;
+    dir: string;
+    list: () => Promise<FunctionSummary[]>;
+    call: (name: string, input: any, options: CallOptions) => Promise<any>;
+    /**
+     * The operator's `_auth` function, or null when none exists. Rejects while
+     * an `_auth` file is present but broken — callers treat that as deny-all.
+     */
+    getCustomAuth: () => Promise<LoadedAuthFunction | null>;
+    /**
+     * Live capability summary for `serverInfo`. Mutated in place on every
+     * `list()` so the announced count follows the directory instead of freezing
+     * at whatever was on disk during startup.
+     */
+    stats: {
+        enabled: true;
+        count: number;
+    };
+    /** Stop the hot-reload watcher, when one is running. Safe to call always. */
+    dispose: () => void;
+};
+export type CreateFunctionsServiceOptions = {
+    /** `server.temp_file_dir`; per-call scratch space lives under it. */
+    tempFileDir: string;
+};
+export declare const createFunctionsService: (config: FunctionsConfig, { tempFileDir }: CreateFunctionsServiceOptions) => Promise<FunctionsService>;

package/lib/functions/libs.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Helper libraries handed to every local function as `context.libs`.
+ *
+ * These are the node-safe members of the BRICKS data-calculation sandbox bag,
+ * so a script author moving between device-side calc scripts and server-side
+ * local functions finds the same names. They are stateless singletons — the
+ * same instances are shared by every call.
+ */
+export declare const libs: Record<string, any>;
+export declare const LIB_NAMES: string[];

package/lib/functions/loader.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Evaluates transpiled local function modules inside a `node:vm` context.
+ *
+ * Each function gets its own vm context, so its module-level state is private
+ * and a reload simply throws the whole context away. The context is a *clean*
+ * global: no `process`, no `require`, no ambient host globals beyond the
+ * curated set in `createSandboxGlobals`. That is a clarity boundary, not a
+ * security boundary — function files are trusted (an operator puts them on the
+ * server's disk, like the TOML config), and they are handed `spawn` anyway.
+ *
+ * Values crossing back from the vm belong to another realm: `Array.isArray`
+ * and `JSON.stringify` work, but `instanceof` against host constructors does
+ * not. Never `instanceof`-check a function's return value.
+ */
+export declare class FunctionImportError extends Error {
+    constructor(message: string);
+}
+/**
+ * Globals visible to function code. Everything here is a host object, so
+ * `Buffer.isBuffer` and friends still work on values a function creates.
+ */
+export declare const createSandboxGlobals: (extra?: Record<string, any>) => Record<string, any>;
+export type ResolvedSpecifier = {
+    kind: 'builtin';
+    id: string;
+} | {
+    kind: 'file';
+    path: string;
+};
+export declare const resolveSpecifier: (specifier: string, fromFile: string, rootDir: string) => Promise<ResolvedSpecifier>;
+export type ModuleGraph = {
+    exports: Record<string, any>;
+    /** Every source file in the graph → its mtimeMs at load time. */
+    files: Map<string, number>;
+};
+export type LoadOptions = {
+    rootDir: string;
+    globals?: Record<string, any>;
+};
+/**
+ * Transpile and evaluate `entryFile` plus everything it imports, returning the
+ * entry's export namespace.
+ *
+ * Note: a module body that blocks synchronously (e.g. `while (true) {}` at the
+ * top level) wedges the event loop — vm has no way to interrupt it. Callers
+ * run this inside the per-call deadline so an *async* hang is still bounded.
+ */
+export declare const loadModuleGraph: (entryFile: string, { rootDir, globals }: LoadOptions) => Promise<ModuleGraph>;

package/lib/functions/mcp.d.ts

@@ -0,0 +1,35 @@
+/**
+ * MCP surface for local functions.
+ *
+ * Served from the same Elysia app (and therefore the same port and auth guard)
+ * as the HTTP endpoints. The SDK's own Streamable HTTP transport needs Node
+ * `IncomingMessage`/`ServerResponse` objects, which Elysia does not expose and
+ * which do not exist under Bun at all — so this module pairs the SDK's protocol
+ * implementation with a minimal stateless transport that just moves one
+ * JSON-RPC message in and its response out.
+ *
+ * Stateless means a fresh `Server` per POST: no `mcp-session-id` handshake, and
+ * `tools/list` always reflects the functions on disk right now. Clients that
+ * try to open the optional GET event stream get a 405, which the spec (and the
+ * SDK's client transport) treat as "this server has no server-initiated
+ * stream".
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { FunctionRuntime } from './types';
+import type { FunctionsService } from './index';
+export declare const serializeToolResult: (result: unknown) => string;
+export type McpServerOptions = {
+    functions: FunctionsService;
+    runtime: FunctionRuntime;
+    version: string;
+    signal?: AbortSignal;
+};
+export declare const createFunctionsMcpServer: ({ functions, runtime, version, signal, }: McpServerOptions) => Server;
+type JsonRpcMessage = Record<string, any>;
+/**
+ * Run one JSON-RPC payload (single message or batch) against a fresh server.
+ *
+ * Returns null when nothing needs to be sent back — the caller answers 202.
+ */
+export declare const handleMcpPayload: (options: McpServerOptions, payload: JsonRpcMessage | JsonRpcMessage[]) => Promise<JsonRpcMessage | JsonRpcMessage[] | null>;
+export {};

package/lib/functions/registry.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Discovers local function files and keeps their loaded modules fresh.
+ *
+ * Discovery is a flat scan of the functions directory: every supported
+ * top-level file is one function, named after the file. Subdirectories hold
+ * helper modules — importable by functions, never exposed as tools.
+ *
+ * Reload is lazy and mtime-driven. Before handing back a loaded function we
+ * stat every file in its module graph; if any changed, the module is
+ * re-transpiled into a fresh vm context. No watchers, identical behavior on
+ * every platform, and an edit is picked up by the very next call.
+ */
+import type { FunctionSummary, FunctionsConfig, LoadedFunction } from './types';
+type Entry = {
+    name: string;
+    file: string;
+    loaded: LoadedFunction | null;
+    loading: Promise<LoadedFunction> | null;
+    /** Signature of the last failure we logged, so a broken file logs once. */
+    reportedError: string | null;
+};
+export declare class FunctionNotFoundError extends Error {
+    constructor(name: string);
+}
+export type FunctionsRegistry = ReturnType<typeof createFunctionsRegistry>;
+export declare const createFunctionsRegistry: (config: FunctionsConfig) => {
+    dir: string;
+    config: FunctionsConfig;
+    scan: () => Promise<void>;
+    get: (name: string) => Promise<LoadedFunction>;
+    list: () => Promise<FunctionSummary[]>;
+    entries: Map<string, Entry>;
+};
+export {};

package/lib/functions/scaffold.d.ts

@@ -0,0 +1,18 @@
+/** One day; function scratch dirs older than this are swept at startup. */
+export declare const TEMP_DIR_MAX_AGE_MS: number;
+/**
+ * Ensure the functions directory exists and carries current editor support.
+ *
+ * The ambient types are always refreshed; the tsconfig and example are only
+ * seeded into a directory that has no functions yet.
+ */
+export declare const scaffoldFunctionsDir: (dir: string) => Promise<{
+    seeded: boolean;
+}>;
+/**
+ * Remove stale per-call scratch directories.
+ *
+ * A call's `tempDir` outlives the request on purpose (a co-located agent may
+ * read the file the function produced), so cleanup is time-based instead.
+ */
+export declare const sweepFunctionTempDirs: (tempRoot: string, maxAgeMs?: number) => Promise<number>;

package/lib/functions/status.d.ts

@@ -0,0 +1,119 @@
+/**
+ * In-memory activity log for the functions surface, shown on `/status`.
+ *
+ * Counterpart to the backend-core status trackers (model loads, completions):
+ * counters since startup plus a bounded newest-first history per category.
+ * Everything here is observable metadata — names, paths, sizes, outcome codes.
+ * Credentials (tokens, API keys) are never recorded.
+ *
+ * A module-scoped singleton, like the backend trackers: the guard, the routes
+ * and the service all record into the same instance, and the status route
+ * snapshots it.
+ */
+export type FunctionCallRecord = {
+    timestamp: string;
+    name: string;
+    surface: 'http' | 'sse' | 'mcp';
+    durationMs: number;
+    success: boolean;
+    error?: string;
+};
+export type FunctionUploadRecord = {
+    timestamp: string;
+    /** 'upload' = POST /functions/upload, 'call' = multipart function call. */
+    source: 'upload' | 'call';
+    name: string;
+    size: number;
+    success: boolean;
+    error?: string;
+};
+export type FunctionDownloadRecord = {
+    timestamp: string;
+    path: string;
+    size?: number;
+    success: boolean;
+};
+export type FunctionAuthRecord = {
+    timestamp: string;
+    method: string;
+    path: string;
+    /**
+     * 'workspace' when no custom auth is active, else the `_auth` mode. Absent
+     * for decisions made before any auth regime applied (origin block, broken
+     * `_auth` file).
+     */
+    mode?: 'workspace' | 'both' | 'override';
+    /** 'allowed', or the denial error code. */
+    outcome: string;
+    subject?: string;
+};
+export declare const createFunctionsStatusTracker: (maxHistory?: number) => {
+    recordCall(record: Omit<FunctionCallRecord, 'timestamp'>): void;
+    recordUpload(record: Omit<FunctionUploadRecord, 'timestamp'>): void;
+    recordDownload(record: Omit<FunctionDownloadRecord, 'timestamp'>): void;
+    recordAuth(record: Omit<FunctionAuthRecord, 'timestamp'>): void;
+    snapshot(): {
+        counters: {
+            calls: {
+                total: number;
+                failed: number;
+            };
+            uploads: {
+                total: number;
+                failed: number;
+                bytes: number;
+            };
+            downloads: {
+                total: number;
+                missed: number;
+                bytes: number;
+            };
+            auth: {
+                total: number;
+                denied: number;
+            };
+        };
+        history: {
+            calls: FunctionCallRecord[];
+            uploads: FunctionUploadRecord[];
+            downloads: FunctionDownloadRecord[];
+            auth: FunctionAuthRecord[];
+        };
+    };
+};
+export type FunctionsStatusTracker = ReturnType<typeof createFunctionsStatusTracker>;
+/** The shared instance every functions surface records into. */
+export declare const functionsStatusTracker: {
+    recordCall(record: Omit<FunctionCallRecord, 'timestamp'>): void;
+    recordUpload(record: Omit<FunctionUploadRecord, 'timestamp'>): void;
+    recordDownload(record: Omit<FunctionDownloadRecord, 'timestamp'>): void;
+    recordAuth(record: Omit<FunctionAuthRecord, 'timestamp'>): void;
+    snapshot(): {
+        counters: {
+            calls: {
+                total: number;
+                failed: number;
+            };
+            uploads: {
+                total: number;
+                failed: number;
+                bytes: number;
+            };
+            downloads: {
+                total: number;
+                missed: number;
+                bytes: number;
+            };
+            auth: {
+                total: number;
+                denied: number;
+            };
+        };
+        history: {
+            calls: FunctionCallRecord[];
+            uploads: FunctionUploadRecord[];
+            downloads: FunctionDownloadRecord[];
+            auth: FunctionAuthRecord[];
+        };
+    };
+};

package/lib/functions/templates.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Files scaffolded into the functions directory.
+ *
+ * `buttress-functions.d.ts` is managed: it is rewritten on every start so the
+ * ambient types always match the running server. The tsconfig and the example
+ * are written only into a directory that holds no functions yet, so a deleted
+ * example never comes back.
+ */
+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 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";

package/lib/functions/transpile.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Runtime transpilation of user-authored local function files.
+ *
+ * Two passes, both synchronous native (napi) calls:
+ *   1. `transformSync` strips TypeScript types (no-op for plain JS).
+ *   2. `moduleRunnerTransformSync` rewrites ESM into a flat body that reads and
+ *      writes `__vite_ssr_*` bindings, which `vm.runInContext` can evaluate on
+ *      plain Node. `vm.SourceTextModule` (real ESM in a vm) is unavailable on
+ *      Node without `--experimental-vm-modules`, and `bin/bricks-buttress` runs
+ *      `node lib/index.mjs` whenever Bun is absent — so this form is the only
+ *      one that behaves identically on both runtimes.
+ *
+ * The `moduleRunnerTransformSync` output contract (Vite's module runner) is
+ * implemented by `loader.ts`. Keep both files in sync; this module is the only
+ * place that touches oxc so swapping transpilers stays a one-file change.
+ */
+export type TranspileResult = {
+    code: string;
+    /** Static import specifiers, as written in the source. */
+    deps: string[];
+    dynamicDeps: string[];
+};
+export declare const transpileModule: (file: string, source: string) => TranspileResult;

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 `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;