@fugood/buttress-server 2.25.5-beta.1 → 2.25.6

package/lib/functions/templates.d.ts

@@ -9,6 +9,8 @@
 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 ButtressEmbeddingResult = {\n  /** Plain numbers, ready for JSON or conversion into a sqlite-vec float32 BLOB. */\n  embedding: 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      /**\n       * Raw prompt sent without the chat template \u2014 the fallback for models\n       * whose template the server cannot apply. Use instead of `messages`.\n       */\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    /**\n     * Embed text with a GGML generator whose `[generators.model]` table sets\n     * `embedding = true`. The vector is returned as plain numbers.\n     */\n    embedding: (options: {\n      model?: string\n      text: string\n      /** llama.cpp normalization mode; 2 (L2) is the native default. */\n      embd_normalize?: number\n    }) => Promise<ButtressEmbeddingResult>\n\n    /** Tokenize text with a configured GGML or MLX generator. */\n    tokenize: (options: {\n      model?: string\n      text: string\n      params?: Record<string, any>\n    }) => Promise<Record<string, any> & { tokens: number[] }>\n\n    /** Turn model token ids back into text. */\n    detokenize: (options: { model?: string; tokens: number[] }) => Promise<string>\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 or\n     * ggml-tts). The WAV is written into `tempDir`; return\n     * `fileUrl(path)` to let callers 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  /**\n   * The `[functions.config]` table from the server config. Read once at\n   * server start \u2014 unlike function files, config edits need a restart.\n   */\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 `GET`/`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\n// The only non-builtin packages the local-function loader accepts. These\n// declarations keep editor support working when this directory is outside the\n// server package's own node_modules resolution tree.\ndeclare module 'sqlite3' {\n  type SqliteCallback = (error: Error | null) => void\n\n  class Database {\n    constructor(filename: string, callback?: SqliteCallback)\n    run(sql: string, ...params: any[]): this\n    all<T = Record<string, any>>(\n      sql: string,\n      ...params: [...any[], (error: Error | null, rows: T[]) => void]\n    ): this\n    exec(sql: string, callback?: SqliteCallback): this\n    loadExtension(filename: string, callback?: SqliteCallback): this\n    close(callback?: SqliteCallback): void\n  }\n\n  const sqlite3: { Database: typeof Database }\n  export { Database }\n  export default sqlite3\n}\n\ndeclare module 'sqlite-vec' {\n  export function getLoadablePath(): string\n  export function load(database: { loadExtension(path: string): unknown }): void\n}\n";
+export declare const EXAMPLE_DAEMON_FILE_NAME = "_example-daemon.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 ButtressEmbeddingResult = {\n  /** Plain numbers, ready for JSON or conversion into a sqlite-vec float32 BLOB. */\n  embedding: number[]\n}\n\n/** 'InSubspace' scopes a property to the space; 'Global' is cross-application. */\ntype ButtressBankPropertyMeta = 'InSubspace' | 'Global'\n\ntype ButtressBankProperty = {\n  propertyId: string\n  meta: ButtressBankPropertyMeta\n  definition: Record<string, any> | null\n  value: any\n  tags: string[] | null\n  lastUpdateHash: string | null\n  lastUpdateNote: string | null\n  lastUpdateKey: string | null\n  createAt: string | null\n  updateAt: string | null\n}\n\n/**\n * The Bank replaces `value` unconditionally on update \u2014 an omitted `value`\n * clears the stored one. Read-merge first when a partial update is intended.\n */\ntype ButtressBankPropertyInput = {\n  propertyId: string\n  /** Defaults to 'InSubspace'. */\n  meta?: ButtressBankPropertyMeta\n  definition?: Record<string, any>\n  newDefinitionFallback?: Record<string, any>\n  value?: any\n  updateNote?: string\n  /** Bank defaults upsert to true; pass false to require an existing property. */\n  upsert?: boolean\n  tags?: string[]\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      /**\n       * Raw prompt sent without the chat template \u2014 the fallback for models\n       * whose template the server cannot apply. Use instead of `messages`.\n       */\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    /**\n     * Embed text with a GGML generator whose `[generators.model]` table sets\n     * `embedding = true`. The vector is returned as plain numbers.\n     */\n    embedding: (options: {\n      model?: string\n      text: string\n      /** llama.cpp normalization mode; 2 (L2) is the native default. */\n      embd_normalize?: number\n    }) => Promise<ButtressEmbeddingResult>\n\n    /** Tokenize text with a configured GGML or MLX generator. */\n    tokenize: (options: {\n      model?: string\n      text: string\n      params?: Record<string, any>\n    }) => Promise<Record<string, any> & { tokens: number[] }>\n\n    /** Turn model token ids back into text. */\n    detokenize: (options: { model?: string; tokens: number[] }) => Promise<string>\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 or\n     * ggml-tts). The WAV is written into `tempDir`; return\n     * `fileUrl(path)` to let callers 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  /**\n   * Daemon functions running on this server (files with `meta.daemon`).\n   */\n  daemons: {\n    /**\n     * Deliver an event to the named daemon's `context.onEvent` handlers;\n     * it arrives as `{ event, data, source }`. Throws when no daemon of\n     * that name is running, or when it registered no handler.\n     */\n    emit: (name: string, event: string, data?: unknown) => void\n    /** Names of the daemons currently running. */\n    list: () => string[]\n  }\n\n  /**\n   * The bound workspace's remote Data Bank (read/write; daemon functions can\n   * also subscribe to changes via `bank.subscribe`). Every method throws\n   * until credentials are stored via `bricks buttress bank-key` (run on\n   * this host, then restart the server).\n   */\n  bank: {\n    /** List properties, optionally filtered. */\n    list: (options?: {\n      /** Match against definition title/description or tags. */\n      keyword?: string\n      meta?: ButtressBankPropertyMeta\n      /** Restrict to these property ids. */\n      ids?: string[]\n    }) => Promise<ButtressBankProperty[]>\n\n    /** One property, or null when it does not exist. */\n    get: (propertyId: string) => Promise<ButtressBankProperty | null>\n\n    /**\n     * Create or update properties (upsert by default). Updates notify\n     * subscribed devices unless `dontNotify` is set.\n     */\n    update: (\n      properties: ButtressBankPropertyInput[],\n      options?: { dontNotify?: boolean },\n    ) => Promise<ButtressBankProperty[]>\n\n    /** Delete a property. Resolves false when it did not exist. */\n    remove: (propertyId: string) => Promise<boolean>\n\n    /**\n     * Watch property ids for remote changes. Only available inside daemon\n     * functions (throws elsewhere); closed automatically when the daemon\n     * stops. The connection is shared and reconnects on its own \u2014 a network\n     * drop never stops the daemon.\n     */\n    subscribe: (\n      propertyIds: string[],\n      onChange: (properties: ButtressBankProperty[]) => unknown,\n    ) => { close: () => void }\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  /**\n   * The `[functions.config]` table from the server config. Read once at\n   * server start \u2014 unlike function files, config edits need a restart.\n   */\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  /**\n   * Deadline for this function: ms, or a duration string like \"10m\".\n   * Ignored for daemons \u2014 a daemon has no deadline.\n   */\n  timeout?: number | string\n  /**\n   * `true` declares this file as a daemon: a long-lived background\n   * function. Its default export runs once, with a ButtressDaemonContext as\n   * its only argument, and stays alive \u2014 everything registered there\n   * (`setInterval` timers, `bank.subscribe` subscriptions, `onEvent`\n   * handlers) keeps firing until the file changes or the server stops.\n   * A daemon is not an MCP tool and cannot be called over HTTP.\n   */\n  daemon?: boolean\n}\n\n/** An event another local function sent via `context.daemons.emit`. */\ntype ButtressDaemonEmittedEvent = {\n  event: string\n  data?: unknown\n  /** Name of the local function (or daemon) that emitted it. */\n  source: string\n}\n\n/**\n * What a daemon's default export receives: the full function context plus\n * lifetime APIs. `context.signal` aborts when the daemon stops (file\n * changed/removed, or server shutdown); an optional cleanup function\n * *returned* by the handler also runs at that point.\n */\ntype ButtressDaemonContext = ButtressFunctionContext & {\n  /**\n   * A managed `setInterval`: the callback keeps firing until cleared or\n   * the daemon stops. A callback that throws is logged (and shown on\n   * /status) \u2014 it never stops the timer or the daemon.\n   */\n  setInterval: (callback: () => unknown, ms: number) => unknown\n  clearInterval: (handle: unknown) => void\n  /** Receive events other local functions send via `context.daemons.emit`. */\n  onEvent: (handler: (event: ButtressDaemonEmittedEvent) => unknown) => void\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 `GET`/`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\n// The only non-builtin packages the local-function loader accepts. These\n// declarations keep editor support working when this directory is outside the\n// server package's own node_modules resolution tree.\ndeclare module 'sqlite3' {\n  type SqliteCallback = (error: Error | null) => void\n\n  class Database {\n    constructor(filename: string, callback?: SqliteCallback)\n    run(sql: string, ...params: any[]): this\n    all<T = Record<string, any>>(\n      sql: string,\n      ...params: [...any[], (error: Error | null, rows: T[]) => void]\n    ): this\n    exec(sql: string, callback?: SqliteCallback): this\n    loadExtension(filename: string, callback?: SqliteCallback): this\n    close(callback?: SqliteCallback): void\n  }\n\n  const sqlite3: { Database: typeof Database }\n  export { Database }\n  export default sqlite3\n}\n\ndeclare module 'sqlite-vec' {\n  export function getLoadablePath(): string\n  export function load(database: { loadExtension(path: string): unknown }): void\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, at POST /functions/video-duration\n// with a JSON body, and at GET /functions/video-duration?path=... with the\n// input in the query string.\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";
+export declare const EXAMPLE_DAEMON_TEMPLATE = "// Example Buttress daemon function.\n//\n// Rename (or copy) this file to activate it: files starting with \"_\" are\n// ignored. A file with `meta.daemon = true` runs as a daemon \u2014 a\n// long-lived background function. It is not exposed as an MCP tool or\n// endpoint; its live status shows on /status.\n//\n// The default export runs ONCE when the daemon starts, and everything it\n// registers on the context keeps running after it returns:\n//\n//   context.setInterval(cb, ms)          periodic work (cleared on stop;\n//                                        a throwing callback never stops it)\n//   context.bank.subscribe(ids, cb)      Data Bank change notifications\n//                                        (needs `bricks buttress bank-key`)\n//   context.onEvent(cb)                  events from other local functions:\n//                                        context.daemons.emit(name, event, data)\n//\n// The daemon stops when this file changes or the server shuts down:\n// context.signal aborts, timers and subscriptions are cleaned up, and a\n// cleanup function returned here gets a final (bounded) run.\n\nexport const meta: ButtressFunctionMeta = {\n  description: 'Log a heartbeat and react to Data Bank changes',\n  daemon: true,\n}\n\nexport default async function (context: ButtressDaemonContext) {\n  let ticks = 0\n\n  context.setInterval(() => {\n    ticks += 1\n    context.log(`heartbeat #${ticks}`)\n  }, 60_000)\n\n  // Requires stored Bank credentials \u2014 uncomment after `bricks buttress bank-key`:\n  // context.bank.subscribe(['some-property-id'], (properties) => {\n  //   for (const property of properties) {\n  //     context.log(`bank property changed: ${property.propertyId}`)\n  //   }\n  // })\n\n  context.onEvent(({ event, data, source }) => {\n    context.log(`event \"${event}\" from ${source}`, data)\n  })\n\n  context.log('daemon started')\n  return () => context.log(`stopping after ${ticks} tick(s)`)\n}\n";

package/lib/functions/types.d.ts

@@ -1,6 +1,8 @@
+import type { AgentsFunctionApi, AgentsService } from '../agent/types';
 import type { Backend } from '../index';
 import type { Config } from '../types';
 import type { VerifiedIdentity } from '../utils/buttressAuth';
+import type { WorkspaceState } from '../utils/workspaceState';
 /**
  * Declarative metadata a local function file exports alongside its handler.
  *
@@ -12,6 +14,23 @@ export type FunctionMeta = {
     parameters?: Record<string, any>;
     /** Per-function deadline. Number of ms, or an `ms()` string like "10m". */
     timeout?: number | string;
+    /**
+     * `true` declares the file as a daemon: a long-lived background function.
+     * Its default export runs once, with a `DaemonContext`, and stays alive —
+     * timers (`context.setInterval`), Data Bank subscriptions
+     * (`context.bank.subscribe`) and event handlers (`context.onEvent`) keep
+     * firing until the file changes or the server stops. Daemon files are not
+     * exposed as MCP tools or callable endpoints, and `timeout` does not apply
+     * to them.
+     */
+    daemon?: boolean;
+};
+/** An event another local function sent via `context.daemons.emit`. */
+export type DaemonEmittedEvent = {
+    event: string;
+    data?: unknown;
+    /** Name of the local function (or daemon) that emitted it. */
+    source: string;
 };
 export type FunctionEmit = (event: string, data?: unknown) => void;
 export type SpawnOptions = {
@@ -102,6 +121,72 @@ export type SynthesizeResult = {
     sampling_rate: number;
     channels: number;
 };
+/** 'InSubspace' scopes a property to the space; 'Global' is cross-application. */
+export type BankPropertyMeta = 'InSubspace' | 'Global';
+export type BankProperty = {
+    propertyId: string;
+    meta: BankPropertyMeta;
+    definition: Record<string, any> | null;
+    value: any;
+    tags: string[] | null;
+    lastUpdateHash: string | null;
+    lastUpdateNote: string | null;
+    lastUpdateKey: string | null;
+    createAt: string | null;
+    updateAt: string | null;
+};
+export type BankListOptions = {
+    /** Match against definition title/description or tags. */
+    keyword?: string;
+    meta?: BankPropertyMeta;
+    /** Restrict to these property ids. */
+    ids?: string[];
+};
+/**
+ * The Bank replaces `value` unconditionally on update — an omitted `value`
+ * clears the stored one. Read-merge first when a partial update is intended.
+ */
+export type BankPropertyInput = {
+    propertyId: string;
+    /** Defaults to 'InSubspace'. */
+    meta?: BankPropertyMeta;
+    definition?: Record<string, any>;
+    newDefinitionFallback?: Record<string, any>;
+    value?: any;
+    updateNote?: string;
+    /** Bank defaults upsert to true; pass false to require an existing property. */
+    upsert?: boolean;
+    tags?: string[];
+};
+export type BankUpdateOptions = {
+    /** Skip notifying subscribed devices about this update. */
+    dontNotify?: boolean;
+};
+/** A live Data Bank change subscription (daemon functions only). */
+export type BankSubscriptionHandle = {
+    close: () => void;
+};
+/** Remote Data Bank access for the bound workspace. */
+export type BankContext = {
+    list: (options?: BankListOptions) => Promise<BankProperty[]>;
+    /** Null when the property does not exist. */
+    get: (propertyId: string) => Promise<BankProperty | null>;
+    update: (properties: BankPropertyInput[], options?: BankUpdateOptions) => Promise<BankProperty[]>;
+    remove: (propertyId: string) => Promise<boolean>;
+    /**
+     * Watch property ids for remote changes. Only available inside daemon
+     * functions — a call-scoped function has no lifetime to attach it to.
+     * Closed automatically when the daemon stops.
+     */
+    subscribe: (propertyIds: string[], onChange: (properties: BankProperty[]) => void) => BankSubscriptionHandle;
+};
+/** What the executor needs to route `context.daemons` calls. */
+export type DaemonsHub = {
+    /** Enqueue an `event` invocation on a running daemon; throws when unknown. */
+    emit: (name: string, event: string, data: unknown, source: string) => void;
+    /** Names of the daemons currently running. */
+    names: () => string[];
+};
 /** The second argument every local function handler receives. */
 export type FunctionContext = {
     spawn: (command: string, args?: string[], options?: SpawnOptions) => Promise<SpawnResult>;
@@ -114,6 +199,23 @@ export type FunctionContext = {
         transcribe: (options: TranscribeOptions) => Promise<any>;
         synthesize: (options: SynthesizeOptions) => Promise<SynthesizeResult>;
     };
+    /**
+     * Workspace Data Bank (read/write, v1 — no subscribe). Every method throws
+     * until credentials are stored via `bricks buttress bank-key`.
+     */
+    bank: BankContext;
+    /** Signal running daemon functions from any local function (or daemon). */
+    daemons: {
+        /** Deliver an event to the named daemon. Throws when it is not running. */
+        emit: (name: string, event: string, data?: unknown) => void;
+        /** Names of the daemons currently running. */
+        list: () => string[];
+    };
+    /**
+     * Configured agents (see `[[agents]]`). Every method throws when no agents
+     * are configured on this server.
+     */
+    agents: AgentsFunctionApi;
     fetch: typeof fetch;
     log: (...args: unknown[]) => void;
     emit: FunctionEmit;
@@ -131,12 +233,30 @@ export type FunctionContext = {
     libs: Record<string, any>;
 };
 export type FunctionHandler = (input: any, context: FunctionContext) => any;
+/**
+ * The context a daemon's default export receives (as its only argument):
+ * everything a function gets, plus lifetime APIs. Registered timers,
+ * subscriptions and event handlers stay live after the invocation returns.
+ */
+export type DaemonContext = FunctionContext & {
+    /**
+     * A managed `setInterval`: the callback keeps firing until cleared or the
+     * daemon stops; a callback that throws is logged and never stops the timer.
+     */
+    setInterval: (callback: () => unknown, ms: number) => NodeJS.Timeout;
+    clearInterval: (handle: NodeJS.Timeout) => void;
+    /** Receive events other local functions send via `context.daemons.emit`. */
+    onEvent: (handler: (event: DaemonEmittedEvent) => unknown) => void;
+};
+export type DaemonHandler = (context: DaemonContext) => any;
 export type LoadedFunction = {
     name: string;
     file: string;
     meta: FunctionMeta;
     handler: FunctionHandler;
     timeoutMs: number;
+    /** True for daemon files (`meta.daemon = true`). */
+    daemon?: boolean;
     /** Every file in this function's module graph → mtimeMs when it was loaded. */
     files: Map<string, number>;
 };
@@ -145,6 +265,11 @@ export type FunctionSummary = {
     description: string;
     parameters: Record<string, any>;
 };
+/** What `GET /functions` and the status page report about a daemon. */
+export type DaemonSummary = {
+    name: string;
+    description: string;
+};
 export type FunctionsConfig = {
     enabled: boolean;
     dir: string;
@@ -162,6 +287,10 @@ export type FunctionsConfig = {
 export type FunctionRuntime = {
     backend: Backend;
     config: Config;
+    /** Carries the Data Bank binding; absent means `context.bank` is unconfigured. */
+    workspaceState?: WorkspaceState;
+    /** Agents service; absent means `context.agents` throws. */
+    agents?: AgentsService;
 };
 /** Metadata an `_auth` file exports alongside its authorize handler. */
 export type AuthMeta = {

package/lib/index.d.ts

@@ -3,10 +3,12 @@ import * as backendCore from '@fugood/buttress-backend-core';
 import { AutodiscoverService } from './autodiscover';
 import type { Config } from './types';
 import { compareVersions } from './utils/update';
+import type { AgentsConfig, AgentsService } from './agent/types';
 import type { FunctionsConfig, FunctionsService } from './functions';
 export { startModelDownload } from '@fugood/buttress-backend-core';
 export { processConfig } from './utils/config';
 export { resolveFunctionsConfig } from './functions';
+export { resolveAgentsConfig } from './agent/config';
 export type { FunctionsConfig, FunctionsService } from './functions';
 export declare const checkForUpdates: () => Promise<string | null>;
 export { compareVersions };
@@ -21,17 +23,21 @@ export interface StartServerOptions {
     enableAnthropicMessages?: boolean;
     /** Resolved `[functions]` config; null/omitted leaves the feature off. */
     functions?: FunctionsConfig | null;
+    /** Resolved `[[agents]]` config; null/omitted leaves the feature off. */
+    agents?: AgentsConfig | null;
 }
-export declare const createServer: ({ backend, router, config, enableOpenAICompat, enableAnthropicMessages, functions: functionsConfig, }: StartServerOptions) => Promise<{
+export declare const createServer: ({ backend, router, config, enableOpenAICompat, enableAnthropicMessages, functions: functionsConfig, agents: agentsConfig, }: StartServerOptions) => Promise<{
     app: AnyElysia;
     config: Config;
     functions: FunctionsService | null;
+    agents: AgentsService | null;
 }>;
-export declare const startServer: ({ backend, router, config, enableOpenAICompat, enableAnthropicMessages, functions: functionsConfig, }: StartServerOptions) => Promise<{
+export declare const startServer: ({ backend, router, config, enableOpenAICompat, enableAnthropicMessages, functions: functionsConfig, agents: agentsConfig, }: StartServerOptions) => Promise<{
     app: AnyElysia;
     port: number;
     openaiEnabled: boolean;
     anthropicMessagesEnabled: boolean;
     functions: FunctionsService | null;
+    agents: AgentsService | null;
     autoDiscover: AutodiscoverService | null;
 }>;