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

package/config/function-samples/_auth.ts

@@ -0,0 +1,48 @@
+// Custom auth for the /functions endpoints.
+//
+// Unlike other "_"-prefixed files, "_auth" is special: dropping it into the
+// functions directory activates it. `meta.mode` picks how it composes with
+// the built-in workspace auth:
+//
+//   - 'both' (default): runs after workspace auth passes — an extra gate that
+//     can only narrow access (e.g. per-function allow-lists).
+//   - 'override': fully replaces workspace auth — this function alone decides.
+//     A presented workspace token is still verified into
+//     `request.workspaceAuth` so the function can choose to honor it.
+//
+// This sample uses 'override' to keep workspace tokens working while ALSO
+// accepting static API keys for callers that have none. Configure the keys in
+// the server TOML:
+//
+//   [functions.config]
+//   api_keys = ["replace-with-a-long-random-string"]
+//
+// Callers then send `X-Api-Key: <key>` (or `Authorization: Bearer <key>`).
+// With no api_keys configured it denies everything except valid workspace
+// tokens — it never fails open.
+
+export const meta: ButtressAuthMeta = {
+  mode: 'override',
+}
+
+export default async function authorize(
+  request: ButtressAuthRequest,
+  context: ButtressAuthContext,
+): Promise<ButtressAuthResult> {
+  // A valid workspace access token keeps working like before.
+  if (request.workspaceAuth.authenticated) return true
+
+  const keys = context.config.api_keys
+  if (!Array.isArray(keys) || keys.length === 0) {
+    return {
+      ok: false,
+      error: 'No workspace token and no [functions.config] api_keys configured',
+    }
+  }
+
+  // Headers reach this function lower-cased.
+  const presented = request.headers['x-api-key'] || request.token
+  if (typeof presented === 'string' && keys.includes(presented)) return true
+
+  return { ok: false, status: 401, error: 'Invalid or missing API key' }
+}

package/config/function-samples/host-info.ts

@@ -0,0 +1,25 @@
+// Report facts about the machine this server runs on.
+//
+// A good first function to try: it needs no external tools, no configured
+// generators and no input.
+//
+//   curl -X POST http://<host>:<port>/functions/host-info
+
+import os from 'node:os'
+
+export const meta: ButtressFunctionMeta = {
+  description: 'Report hostname, OS, CPU, memory and uptime of the Buttress host',
+}
+
+export default async function (_input: unknown, context: ButtressFunctionContext) {
+  const { bytes, ms } = context.libs
+
+  return {
+    hostname: os.hostname(),
+    platform: `${os.platform()} ${os.release()} (${os.arch()})`,
+    cpus: os.cpus().length,
+    memory: { total: bytes(os.totalmem()), free: bytes(os.freemem()) },
+    uptime: ms(Math.round(os.uptime()) * 1000, { long: true }),
+    load: os.loadavg().map((value) => Number(value.toFixed(2))),
+  }
+}

package/config/function-samples/summarize-text.ts

@@ -0,0 +1,55 @@
+// Summarize text with this server's own LLM generator — no API keys, the
+// model already configured under [[generators]] does the work in-process.
+//
+// Needs at least one LLM generator (e.g. ggml-llm) in the server config.
+//
+//   curl -X POST http://<host>:<port>/functions/summarize-text \
+//     -H 'Content-Type: application/json' \
+//     -d '{"text": "…", "style": "bullets"}'
+
+export const meta: ButtressFunctionMeta = {
+  description: 'Summarize a piece of text with the local LLM',
+  parameters: {
+    type: 'object',
+    properties: {
+      text: { type: 'string', description: 'The text to summarize' },
+      style: {
+        type: 'string',
+        enum: ['bullets', 'paragraph'],
+        default: 'bullets',
+        description: 'Shape of the summary',
+      },
+      model: {
+        type: 'string',
+        description: 'Optional model override (repo_id of a configured generator)',
+      },
+    },
+    required: ['text'],
+  },
+  timeout: '5m',
+}
+
+type Input = { text: string; style?: 'bullets' | 'paragraph'; model?: string }
+
+export default async function (
+  { text, style = 'bullets', model }: Input,
+  context: ButtressFunctionContext,
+) {
+  const target = style === 'paragraph' ? 'one short paragraph' : '3-5 concise bullet points'
+
+  const { content, usage } = await context.buttress.completion({
+    model,
+    // A summary is bounded work; without a cap a model that starts repeating
+    // itself runs to the context limit before the call's deadline stops it.
+    max_tokens: 512,
+    messages: [
+      {
+        role: 'system',
+        content: `Summarize the user's text as ${target}. Reply with the summary only.`,
+      },
+      { role: 'user', content: text },
+    ],
+  })
+
+  return { summary: content.trim(), usage }
+}

package/config/function-samples/text-to-speech.ts

@@ -0,0 +1,51 @@
+// Synthesize speech with this server's own TTS generator and hand back a
+// download URL — the caller never needs filesystem access to the server.
+//
+// Needs an onnx-tts generator in the server config, e.g.:
+//
+//   [[generators]]
+//   type = "onnx-tts"
+//   [generators.model]
+//   repo_id = "Xenova/speecht5_tts"
+//
+//   curl -X POST http://<host>:<port>/functions/text-to-speech \
+//     -H 'Content-Type: application/json' \
+//     -d '{"text": "Hello from Buttress"}'
+//   # → { "result": { "url": "/functions/files/…", … } }
+//   curl -OJ "http://<host>:<port>$url"   # same auth headers as the call
+
+export const meta: ButtressFunctionMeta = {
+  description: 'Synthesize speech from text with the local TTS model; returns a download URL',
+  parameters: {
+    type: 'object',
+    properties: {
+      text: { type: 'string', description: 'Text to speak' },
+      speaker: { type: 'string', description: 'Optional registered speaker id' },
+      model: { type: 'string', description: 'Optional TTS model override' },
+    },
+    required: ['text'],
+  },
+  timeout: '5m',
+}
+
+type Input = { text: string; speaker?: string; model?: string }
+
+export default async function ({ text, speaker, model }: Input, context: ButtressFunctionContext) {
+  const {
+    path: audioPath,
+    sampling_rate,
+    channels,
+  } = await context.buttress.synthesize({
+    text,
+    model,
+    options: speaker ? { speaker } : {},
+  })
+
+  return {
+    // Download with the same Authorization the function call used; the file
+    // stays available until the scratch-dir sweep (~24h).
+    url: context.fileUrl(audioPath),
+    sampling_rate,
+    channels,
+  }
+}

package/config/function-samples/transcribe-media.ts

@@ -0,0 +1,65 @@
+// Transcribe any audio or video file: ffmpeg extracts 16 kHz mono WAV audio
+// into the per-call scratch directory, then this server's STT generator
+// transcribes it. Progress reaches SSE callers (`?stream=1`) via context.emit.
+//
+// Needs `ffmpeg` on the server's PATH and an STT generator (ggml-stt or
+// onnx-stt) in the server config.
+//
+// Remote callers send the media inline — a multipart body stages every file
+// field and injects its server-local path into the input, so one request
+// does the whole job (bump [server] max_body_size for large files):
+//
+//   curl -X POST 'http://<host>:<port>/functions/transcribe-media?stream=1' \
+//     -F file=@interview.mp4
+//
+// To reuse one file across several calls, stage it once instead and pass the
+// returned path as {"file": "<path>"}:
+//
+//   curl -F file=@interview.mp4 http://<host>:<port>/functions/upload
+
+import path from 'node:path'
+
+export const meta: ButtressFunctionMeta = {
+  description: 'Transcribe an audio/video file using ffmpeg and the local STT model',
+  parameters: {
+    type: 'object',
+    properties: {
+      file: { type: 'string', description: 'Absolute path to a media file on the server' },
+      model: { type: 'string', description: 'Optional STT model override' },
+    },
+    required: ['file'],
+  },
+  timeout: '15m',
+}
+
+type Input = { file: string; model?: string }
+
+export default async function ({ file, model }: Input, context: ButtressFunctionContext) {
+  const wavPath = path.join(context.tempDir, 'audio.wav')
+
+  context.emit('stage', 'extract-audio')
+  // -hide_banner/-loglevel error keep stderr to the actual failure, so a
+  // thrown error reaches the caller instead of ffmpeg's build configuration.
+  const { code, stderr } = await context.spawn('ffmpeg', [
+    '-hide_banner',
+    '-loglevel',
+    'error',
+    '-y',
+    '-i',
+    file,
+    '-vn',
+    '-ac',
+    '1',
+    '-ar',
+    '16000',
+    wavPath,
+  ])
+  if (code !== 0) {
+    throw new Error(`ffmpeg failed (${code}): ${String(stderr).slice(-2000)}`)
+  }
+
+  context.emit('stage', 'transcribe')
+  const transcription = await context.buttress.transcribe({ model, filePath: wavPath })
+
+  return { transcription }
+}

package/config/sample.toml

@@ -29,6 +29,22 @@ enabled = true
 # cors_allowed_origins = ["http://localhost:3000", "https://example.com"]
 # cors_allowed_origins = "*"
 
+# Local functions (EXPERIMENTAL): .ts/.js files exposed as MCP tools and HTTP
+# endpoints. Interfaces may change between releases.
+# See the "Local Functions" section of README.md; ready-to-copy examples live
+# in config/function-samples/. An optional _auth.ts in the functions directory
+# customizes auth (extra gate, or full replacement of workspace auth).
+# [functions]
+# enabled = true
+# dir = "./functions"                # relative to this config file
+# default_timeout = "5m"             # per-call deadline; meta.timeout overrides it
+# hot_reload = false                 # watch the dir and reload eagerly on change
+# allow_unauthenticated = false      # UNBOUND servers reject calls unless this is true
+# cors_allowed_origins = ["http://localhost:3000"]  # browsers are blocked unless listed
+# [functions.config]                 # free-form; reaches functions as context.config
+# api_base = "https://example.internal"
+# api_keys = ["a-long-random-string"]  # e.g. consumed by function-samples/_auth.ts
+
 [runtime]
 cache_dir = "./.buttress-cache"
 # huggingface_token = "hf_xx"
@@ -73,6 +89,15 @@ quantization = "mxfp4"
 download = true
 n_ctx = 12800 # Max: 131072
 
+# Optional separate draft model for speculative decoding. Buttress includes the
+# draft model in pre-downloads and memory planning.
+# model_draft = { repo_id = "org/draft-model-GGUF", filename = "draft-q8_0.gguf" }
+# speculative = { type = "draft-mtp" }
+# spec_draft_n_max = 4
+# spec_draft_n_gpu_layers = -1
+# spec_draft_cache_type_k = "f16"
+# spec_draft_cache_type_v = "f16"
+
 [[generators]]
 type = "ggml-llm"
 [generators.backend]

package/lib/autodiscover/index.d.ts

@@ -0,0 +1,20 @@
+import type { AutodiscoverConfig } from '../types';
+import type { GetServerInfoFn } from './types';
+import { type AnnounceSigner } from './udp';
+export type { GetServerInfoFn } from './types';
+export { signEnvelope, buildAnnounceSigner, type AnnounceSigner } from './sign';
+/**
+ * Autodiscover service that manages discovery transports.
+ * Currently supports UDP announcements/responses.
+ * HTTP discovery is handled by the info route.
+ */
+export declare class AutodiscoverService {
+    private config;
+    private getServerInfo;
+    private signer;
+    private transports;
+    private started;
+    constructor(config: AutodiscoverConfig, getServerInfo: GetServerInfoFn, signer: AnnounceSigner | null);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}

package/lib/autodiscover/sign.d.ts

@@ -0,0 +1,10 @@
+import crypto from 'node:crypto';
+import type { WorkspaceState } from '../utils/workspaceState';
+import { type IDiscoveryProtocol } from './types';
+export interface AnnounceSigner {
+    kid: string;
+    privateKey: crypto.KeyObject;
+}
+export declare const canonicalBytes: (t: 'ANNOUNCE' | 'RESPONSE', d: unknown, ts: number) => Buffer;
+export declare const signEnvelope: (signer: AnnounceSigner | null, t: 'ANNOUNCE' | 'RESPONSE', d: IDiscoveryProtocol['d']) => IDiscoveryProtocol | null;
+export declare const buildAnnounceSigner: (workspaceState: WorkspaceState) => AnnounceSigner | null;

package/lib/autodiscover/types.d.ts

@@ -0,0 +1,32 @@
+import type { ServerInfo } from '../types';
+export declare const PROTOCOL_VERSION = "2.0";
+export declare const DEFAULT_PORT = 8089;
+export interface ITransport {
+    name: string;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+interface DiscoveryAnnounce {
+    info: Partial<ServerInfo>;
+}
+export interface DiscoveryRequest {
+    id: string;
+    filters?: {
+        generators?: string[];
+        min_version?: string;
+    };
+}
+interface DiscoveryResponse {
+    request_id: string;
+    info: Partial<ServerInfo>;
+}
+export interface IDiscoveryProtocol {
+    t: 'ANNOUNCE' | 'QUERY' | 'RESPONSE';
+    v: string;
+    d: DiscoveryAnnounce | DiscoveryRequest | DiscoveryResponse;
+    ts?: number;
+    kid?: string;
+    sig?: string;
+}
+export type GetServerInfoFn = () => ServerInfo;
+export {};

package/lib/autodiscover/udp.d.ts

@@ -0,0 +1,22 @@
+import type { AutodiscoverConfig } from '../types';
+import { ITransport, GetServerInfoFn } from './types';
+import { type AnnounceSigner } from './sign';
+export type { AnnounceSigner } from './sign';
+export declare class UdpTransport implements ITransport {
+    name: string;
+    private receiver;
+    private senders;
+    private announcementTimer;
+    private config;
+    private getServerInfo;
+    private port;
+    private signer;
+    constructor(config: AutodiscoverConfig['udp'], getServerInfo: GetServerInfoFn, signer: AnnounceSigner | null);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private bindReceiver;
+    private createSenders;
+    private handleMessage;
+    private sendAnnouncement;
+    private sendResponse;
+}

package/lib/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export default _default;
+declare function _default(): Promise<void>;

package/lib/functions/auth.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Optional operator-supplied auth for the `/functions` surface.
+ *
+ * Dropping `_auth.ts` (or `.js`) into the functions directory activates it —
+ * the underscore keeps it out of tool discovery like any other helper file.
+ * `meta.mode` decides how it composes with the built-in workspace auth:
+ *
+ *   - 'both' (default): workspace auth runs first, unchanged; the custom
+ *     function is an additional gate, so it can only narrow access.
+ *   - 'override': the custom function is the only authority. A presented
+ *     workspace token is still verified so the function can honor it via
+ *     `request.workspaceAuth` (e.g. accept workspace tokens OR an API key).
+ *
+ * Failure never widens access: while an `_auth` file exists but does not
+ * load, every call is rejected until it is fixed. Reload follows the same
+ * mtime-driven lazy scheme as function files, and deleting the file reverts
+ * the server to plain workspace auth on the next request.
+ */
+import type { FunctionsConfig, LoadedAuthFunction } from './types';
+export declare const AUTH_BASENAME = "_auth";
+export type AuthLoader = {
+    /**
+     * Current auth function, or null when no `_auth` file exists. Throws when
+     * the file is present but unloadable — callers must treat that as deny-all.
+     */
+    get: () => Promise<LoadedAuthFunction | null>;
+};
+export declare const createAuthLoader: (config: FunctionsConfig) => AuthLoader;

package/lib/functions/config.d.ts

@@ -0,0 +1,20 @@
+import type { GlobalConfig } from '../types';
+import type { FunctionsConfig } from './types';
+export declare const DEFAULT_TIMEOUT_MS: number;
+export type ResolveFunctionsOptions = {
+    /**
+     * Directory a relative `dir` is resolved against — the directory holding the
+     * `--config` file. Inline-TOML configs have no such directory, so callers
+     * pass `process.cwd()`.
+     */
+    configDir?: string;
+    env?: Record<string, string | undefined>;
+};
+/**
+ * Resolve the `[functions]` TOML table (plus env overrides) into the shape the
+ * runtime uses. Returns null when the feature is not enabled.
+ *
+ * Enablement follows the same env-or-config idiom as the compatibility
+ * endpoints: `ENABLE_FUNCTIONS_ENDPOINT=1` or `[functions] enabled = true`.
+ */
+export declare const resolveFunctionsConfig: (globalConfig: GlobalConfig | undefined, { configDir, env }?: ResolveFunctionsOptions) => FunctionsConfig | null;

package/lib/functions/constants.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared constants for the local function system.
+ *
+ * Kept apart from `transpile.ts` so discovery and scaffolding can import them
+ * without pulling in the native transpiler.
+ */
+/** File extensions a local function (or one of its helper modules) may use. */
+export declare const SUPPORTED_EXTENSIONS: string[];
+/** What a function (file) may be called. Doubles as a path-safety guarantee. */
+export declare const FUNCTION_NAME_PATTERN: RegExp;
+/**
+ * Static segments of the functions API a function may not be named after:
+ * `POST /functions/mcp` (MCP), `GET /functions/files/*` (downloads) and
+ * `POST /functions/upload` (uploads) would shadow — or be shadowed by — a
+ * function of the same name.
+ */
+export declare const RESERVED_FUNCTION_NAMES: Set<string>;

package/lib/functions/executor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Runs a loaded local function with a deadline, a scratch directory, and the
+ * capabilities it is allowed to reach (spawn, buttress inference, helper libs).
+ *
+ * Cancellation is cooperative *plus* forceful: the call's AbortSignal is
+ * surfaced to the function (so `fetch` and the inference helpers unwind), and
+ * every process the call spawned is terminated. Code that blocks the event loop
+ * synchronously cannot be interrupted — function files are trusted, and vm has
+ * no way to preempt a running script.
+ */
+import type { FunctionEmit, FunctionRuntime, FunctionsConfig, LoadedFunction } from './types';
+export declare class FunctionTimeoutError extends Error {
+    constructor(name: string, timeoutMs: number);
+}
+export declare class FunctionAbortError extends Error {
+    constructor(name: string);
+}
+export type ExecuteOptions = {
+    runtime: FunctionRuntime;
+    functionsConfig: FunctionsConfig;
+    /** Streams progress to the caller; ignored on non-streaming surfaces. */
+    emit?: FunctionEmit;
+    /** Aborts the call early (e.g. the HTTP client disconnected). */
+    signal?: AbortSignal;
+    callId?: string;
+};
+export declare const executeFunction: (fn: LoadedFunction, input: any, { runtime, functionsConfig, emit, signal, callId }: ExecuteOptions) => Promise<any>;

package/lib/functions/files.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Path mapping for the function file-download surface.
+ *
+ * A call's scratch directory lives at `<temp_file_dir>/functions/<name>-<id>/`;
+ * `GET /functions/files/<name>-<id>/<file>` serves what a function wrote there.
+ * Both directions of the mapping live here, pure and unit-testable: URL →
+ * filesystem path (with strict containment, for the route) and filesystem
+ * path → URL (for `context.fileUrl`).
+ */
+export declare const FUNCTIONS_FILES_PREFIX = "/functions/files";
+/**
+ * Resolve a raw wildcard path from `GET /functions/files/*` to an absolute
+ * path inside `tempRoot`. Null when the path is empty, escapes the root, or
+ * cannot be decoded — the route treats all of those as 404.
+ */
+export declare const resolveFunctionsFile: (tempRoot: string, rawPath: string) => string | null;
+/**
+ * Build the download URL path for an absolute file inside `tempRoot`.
+ * Null when the file is outside it.
+ */
+export declare const functionsFileUrl: (tempRoot: string, absolutePath: string) => string | null;
+/**
+ * Tame a client-supplied upload file name into something safe to place on
+ * disk. Every upload gets its own directory, so only the name itself needs
+ * care: no path segments, no control characters, no dot-prefixed (hidden /
+ * traversal-looking) names. The extension survives — ffmpeg and friends use
+ * it for format detection.
+ */
+export declare const sanitizeUploadFilename: (original: string) => string;

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 {};