@fugood/buttress-server 2.25.5 → 2.25.6

package/lib/agent/session-fs.d.ts

@@ -0,0 +1,42 @@
+import { FileError } from '@earendil-works/pi-agent-core';
+import type { Result } from '@earendil-works/pi-agent-core';
+/**
+ * Minimal FileSystem implementation for the jsonl session repo, over node:fs.
+ *
+ * pi's NodeExecutionEnv classifies fs failures with `error instanceof Error`,
+ * which breaks in vm-realm hosts (jest runs test code in a vm context, so
+ * node-core errors come from another realm and ENOENT stops mapping to
+ * not_found). This implementation reads `error.code` structurally — and also
+ * skips pulling the exec-capable execution env into the server for what is
+ * purely file storage.
+ */
+type FileResult<T> = Promise<Result<T, FileError>>;
+declare const toFileInfo: (target: string, stats: import('node:fs').Stats) => {
+    name: string;
+    path: string;
+    kind: "directory" | "file" | "symlink";
+    size: number;
+    mtimeMs: number;
+};
+/** The `Pick<FileSystem, …>` surface JsonlSessionRepo requires. */
+export declare const createSessionFs: (rootDir: string) => {
+    absolutePath: (target: string) => FileResult<string>;
+    joinPath: (parts: string[]) => FileResult<string>;
+    readTextFile: (target: string) => FileResult<string>;
+    readTextLines: (target: string, options?: {
+        maxLines?: number;
+    }) => FileResult<string[]>;
+    writeFile: (target: string, content: string | Uint8Array) => FileResult<void>;
+    appendFile: (target: string, content: string | Uint8Array) => FileResult<void>;
+    renameFile: (source: string, destination: string) => FileResult<void>;
+    fileInfo: (target: string) => FileResult<ReturnType<typeof toFileInfo>>;
+    listDir: (target: string) => FileResult<ReturnType<typeof toFileInfo>[]>;
+    exists: (target: string) => FileResult<boolean>;
+    createDir: (target: string, options?: {
+        recursive?: boolean;
+    }) => FileResult<void>;
+    remove: (target: string, options?: {
+        recursive?: boolean;
+    }) => FileResult<void>;
+};
+export {};

package/lib/agent/sessions.d.ts

@@ -0,0 +1,15 @@
+import { Session } from '@earendil-works/pi-agent-core';
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+import type { AgentSessionSummary, AgentsConfig } from './types';
+export type AgentSessionStore = {
+    create: (agentName: string) => Promise<Session<any>>;
+    /** Throws when the id is unknown within the agent's scope. */
+    open: (agentName: string, sessionId: string) => Promise<Session<any>>;
+    fork: (agentName: string, sessionId: string) => Promise<Session<any>>;
+    list: (agentName: string, limit?: number) => Promise<AgentSessionSummary[]>;
+    /** Reconstruct the pi message history for continuing a session. */
+    messages: (session: Session<any>) => Promise<AgentMessage[]>;
+    /** Retention sweep across every configured agent scope. */
+    sweep: (agentNames: string[]) => Promise<number>;
+};
+export declare const createAgentSessionStore: (config: AgentsConfig) => AgentSessionStore;

package/lib/agent/tools.d.ts

@@ -0,0 +1,32 @@
+import type { FunctionsService } from '../functions';
+import type { FunctionRuntime } from '../functions/types';
+import type { AgentDefinition } from './types';
+/**
+ * Local functions as agent tools. Each tool call funnels through the same
+ * executor as MCP/HTTP calls (lazy reload, per-call scratch dir, spawn
+ * tracking, the function's own deadline), and the run's abort signal chains
+ * in. Granting a function to an agent in config IS the authorization — no
+ * auth guard runs below the HTTP/MCP boundary.
+ */
+export type FunctionToolContext = {
+    functions: FunctionsService;
+    runtime: FunctionRuntime;
+    /** Agent-invocation depth for calls made BY this run's tools. */
+    depth: number;
+    /** Forwards `context.emit` progress as agent events. */
+    onToolEmit?: (toolName: string, event: string, data?: unknown) => void;
+};
+export type AgentFunctionTool = {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Record<string, any>;
+    execute: (toolCallId: string, args: any, signal?: AbortSignal) => Promise<any>;
+};
+/**
+ * Resolve the agent's configured tool list against the live registry.
+ * Fail-closed: a listed function that is missing (deleted, renamed, or the
+ * functions feature is off) rejects the run — a headless automation silently
+ * improvising around missing tools is worse than a loud failure.
+ */
+export declare const buildFunctionTools: (agent: AgentDefinition, { functions, runtime, depth, onToolEmit }: FunctionToolContext) => Promise<AgentFunctionTool[]>;

package/lib/agent/tui.d.ts

@@ -0,0 +1,17 @@
+/**
+ * pi-tui chat front-end for `bricks-buttress agent` — the interactive mode on
+ * a real terminal (line mode remains for pipes/scripts via --plain).
+ *
+ * Layout (main-screen mode, scrollback holds history):
+ *   [chat log: user prompts, dim thinking, tool lines, markdown answers]
+ *   [status line / spinner]
+ *   [editor]
+ */
+import { type Connection } from './client';
+export type AgentTuiOptions = {
+    connection: Connection;
+    agentName: string;
+    sessionId: string | null;
+    fork: boolean;
+};
+export declare const runAgentTui: ({ connection, agentName, sessionId: initialSessionId, fork: initialFork, }: AgentTuiOptions) => Promise<void>;

package/lib/agent/types.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Agent feature types: config-defined agents that run pi-agent-core loops
+ * inside the buttress-server process, with local functions (and MCP servers)
+ * as their tools and config-scoped JSONL sessions.
+ */
+export type AgentMcpServerConfig = {
+    /** StreamableHTTP endpoint; mutually exclusive with `command`. */
+    url?: string;
+    headers?: Record<string, string>;
+    /** Stdio server command; mutually exclusive with `url`. */
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    /** Degrade-and-continue when this server fails to connect (default: fail the run). */
+    optional?: boolean;
+};
+export type AgentDefinition = {
+    /** Unique agent name — the session scope key. */
+    name: string;
+    /** Model reference split on the FIRST slash: `provider/model-id`. */
+    provider: string;
+    modelId: string;
+    /** Raw `model` string from config, for error messages. */
+    modelRef: string;
+    systemPrompt: string | null;
+    /** Resolved absolute path; loaded lazily so edits apply per run. */
+    systemPromptFile: string | null;
+    /** Local function names exposed as tools (explicit list, no wildcard). */
+    tools: string[];
+    mcpServers: Record<string, AgentMcpServerConfig>;
+    /** Assistant↔tool round-trips per run. */
+    maxTurns: number;
+    /** Cumulative token budget per run; null = unlimited (default). */
+    maxTokensPerRun: number | null;
+    thinking?: 'off' | 'minimal' | 'low' | 'medium' | 'high';
+    /** Generation passthrough (temperature, top_p, …). */
+    generation: Record<string, unknown>;
+};
+export type AgentsConfig = {
+    agents: AgentDefinition[];
+    /** Directory the TOML config lives in (stdio MCP servers run with this cwd). */
+    configDir: string;
+    /** Absolute sessions root (default `./.buttress-agent/sessions` next to the config). */
+    sessionsDir: string;
+    /** Absolute path of the 0600 file holding the internal token for same-host CLIs. */
+    runtimeTokenFile: string;
+    sessionMaxAgeMs: number | null;
+    sessionMaxCount: number | null;
+    /** Agent-invocation chain depth cap (function → agent → function → agent…). */
+    maxDepth: number;
+    /** Serve /agents endpoints on an unbound server (default false — fail closed). */
+    allowUnauthenticated: boolean;
+};
+export type AgentUsage = {
+    input: number;
+    output: number;
+    cacheRead: number;
+    totalTurns: number;
+};
+export type AgentStopReason = 'end_turn' | 'max_turns' | 'token_budget' | 'aborted' | 'error';
+export type AgentRunOptions = {
+    prompt: string;
+    /** Continue this session; omitted → new session. */
+    sessionId?: string;
+    /** With `sessionId`: fork it into a fresh session instead of continuing. */
+    fork?: boolean;
+    /** pi agent event passthrough (shape follows the pinned pi version). */
+    onEvent?: (event: unknown) => void;
+    /**
+     * Fires once the run's session exists (created, opened, or forked), before
+     * the model starts — the id to abort or continue with. A streaming client
+     * otherwise only learns it from the terminal event.
+     */
+    onSession?: (sessionId: string) => void;
+    /** Aborts the run (chains into tool calls and spawned processes). */
+    signal?: AbortSignal;
+    /** Internal: agent-invocation chain depth of the caller. */
+    depth?: number;
+};
+export type AgentRunResult = {
+    sessionId: string;
+    content: string;
+    reasoningContent?: string;
+    usage: AgentUsage;
+    stopReason: AgentStopReason;
+};
+export type AgentSessionSummary = {
+    sessionId: string;
+    createdAt: string;
+    updatedAt: string;
+    parentSession: string | null;
+    /** First user prompt (truncated) when available. */
+    preview: string | null;
+};
+export type AgentSessionListOptions = {
+    limit?: number;
+};
+/** Error whose `sessionId` survives a failed/aborted run (transcript is continuable). */
+export declare class AgentRunError extends Error {
+    sessionId: string | null;
+    stopReason: AgentStopReason;
+    constructor(message: string, sessionId: string | null, stopReason?: AgentStopReason);
+}
+export type AgentsService = {
+    config: AgentsConfig;
+    /** Configured agent names. */
+    list: () => string[];
+    run: (name: string, options: AgentRunOptions) => Promise<AgentRunResult>;
+    sessions: (name: string, options?: AgentSessionListOptions) => Promise<AgentSessionSummary[]>;
+    /** Full transcript of one session (pi AgentMessage array). */
+    transcript: (name: string, sessionId: string) => Promise<unknown[]>;
+    /** Abort the active run on a session; true when one was running. */
+    abort: (name: string, sessionId: string) => boolean;
+    /** Constant-time check of the internal loopback/CLI token. */
+    verifyInternalToken: (token: string | null | undefined) => boolean;
+    dispose: () => Promise<void>;
+};
+/** The `context.agents` surface local functions receive. */
+export type AgentsFunctionApi = {
+    run: (name: string, options: Omit<AgentRunOptions, 'signal' | 'depth'>) => Promise<AgentRunResult>;
+    list: () => string[];
+    sessions: (name: string, options?: AgentSessionListOptions) => Promise<AgentSessionSummary[]>;
+};

package/lib/cli-DrbWX4ea.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import{a as e,i as t,n,r,t as i}from"./client-BCBBen9i.mjs";import a from"node:readline";const o=`\x1B[2m`,s=`\x1B[33m`,c=`\x1B[31m`,l=`\x1B[0m`,u=e=>{let t={name:null,configArg:null,url:null,token:null,sessionId:null,fork:!1,listSessions:!1,plain:!1};for(let n=0;n<e.length;n+=1){let r=e[n];r===`-h`||r===`--help`?(console.log(`
+bricks-buttress agent — chat with a configured agent on a running server
+
+Usage:
+  bricks-buttress agent [name] [options]
+
+Options:
+  -c, --config <path|toml>  Config file (finds server port + local token)
+      --url <url>           Server base URL (default from config, else http://127.0.0.1:2080)
+      --token <token>       Access token (default: the config's runtime token file)
+      --session <id>        Continue an existing session
+      --fork <id>           Fork a session, then continue the fork
+      --sessions            List the agent's sessions and exit
+      --plain               Line-based output (default when not a TTY)
+  -h, --help                Show this help
+
+In the chat: /exit quits, /new starts a fresh session, Ctrl+C aborts the
+current run (a second Ctrl+C quits).
+`),process.exit(0)):r===`-c`||r===`--config`?t.configArg=e[++n]??null:r===`--url`?t.url=e[++n]??null:r===`--token`?t.token=e[++n]??null:r===`--session`?t.sessionId=e[++n]??null:r===`--fork`?(t.sessionId=e[++n]??null,t.fork=!0):r===`--sessions`?t.listSessions=!0:r===`--plain`?t.plain=!0:!r.startsWith(`-`)&&!t.name?t.name=r:(console.error(`Unknown argument: ${r}`),process.exit(1))}return t},d=e=>{console.error(`${c}${e}${l}`),process.exit(1)},f=async(t,n,r,i,a,u)=>{let d=i,f=!1,p=!1,m=()=>{f&&=(process.stdout.write(`${l}\n`),!1)},h=await e(t,n,{prompt:r,sessionId:i??void 0,fork:a},{signal:u,onFrame:({event:e,payload:t})=>{if(e===`session`){t.sessionId&&t.sessionId!==d&&(d=t.sessionId,i||console.log(`${o}session ${d}${l}`));return}if(e!==`agent`)return;let n=t?.event;if(t?.type===`message_update`&&n)n.type===`thinking_delta`?(f||=(process.stdout.write(`${o}`),!0),process.stdout.write(n.delta??``),p=!0):n.type===`text_delta`&&(m(),process.stdout.write(n.delta??``),p=!0);else if(t?.type===`tool_execution_start`){m(),p&&process.stdout.write(`
+`);let e=JSON.stringify(t.args??{});console.log(`${s}⚙ ${t.toolName}${l}${o}(${e.length>160?`${e.slice(0,160)}…`:e})${l}`),p=!1}else t?.type===`tool_execution_end`?console.log(t.isError?`${c}✗ ${t.toolName} failed${l}`:`${o}✓ ${t.toolName}${l}`):t?.type===`tool_emit`&&console.log(`${o}  ${t.toolName} → ${t.event}${l}`)}});if(m(),h.kind===`result`){let e=h.result;d=e.sessionId??d;let t=e.usage||{};return process.stdout.write(`
+`),console.log(`${o}— ${e.stopReason} · ${t.totalTurns??`?`} turn(s) · ${t.input??0} in / ${t.output??0} out · session ${d}${l}`),{sessionId:d,ok:!0}}return h.kind===`aborted`?(console.log(`\n${s}(aborted)${l}`),{sessionId:h.sessionId??d,ok:!1}):h.kind===`error`?(console.error(`\n${c}Run failed: ${h.message}${l}`),{sessionId:h.sessionId??d,ok:!1}):(console.error(`\n${c}Connection lost mid-run.${l}`),{sessionId:h.sessionId??d,ok:!1})},p=async(e,t,n,r)=>{let s=n,u=r;console.log(`${t}${l} @ ${e.baseUrl}`+(s?` ${o}(${u?`forking`:`continuing`} ${s})${l}`:``)),console.log(`${o}/exit to quit, /new for a fresh session, Ctrl+C aborts a running turn${l}`);let d=a.createInterface({input:process.stdin,output:process.stdout}),p=!1;d.on(`close`,()=>{p=!0});let m=e=>new Promise(t=>{if(p){t(null);return}d.question(e,t),d.once(`close`,()=>t(null))}),h=null;for(d.on(`SIGINT`,()=>{h?(h.abort(),h=null):(d.close(),process.exit(0))});;){let n=await m(`> ${l}`);if(n==null)break;let r=n.trim();if(!r)continue;if(r===`/exit`||r===`/quit`)break;if(r===`/new`){s=null,u=!1,console.log(`${o}Started a fresh session.${l}`);continue}h=new AbortController;let a=s;try{let n=await f(e,t,r,s,u,h.signal);n.sessionId&&(s=n.sessionId),i(a,s)&&(u=!1)}catch(e){console.error(`${c}${e?.message||e}${l}`)}finally{h=null}}d.close()},m=async e=>{let i=u(e),{config:a,agentsConfig:s}=n(i.configArg),c=a.server.port||2080,f=(i.url||`http://127.0.0.1:${c}`).replace(/\/$/,``),m={baseUrl:f,token:i.token||(s?r(s.runtimeTokenFile):null)||process.env.BUTTRESS_AGENT_TOKEN||null},h=await t(m,`/agents`).catch(e=>d(`Cannot reach ${f}: ${e?.message||e} (is the server running?)`));if(!h.ok){let e=await h.text().catch(()=>``);d(`Server rejected the request (${h.status}): ${e.slice(0,300)}`)}let{agents:g}=await h.json();if(!i.name){console.log(`Configured agents on ${f}:`);for(let e of g)console.log(`- ${e}`);g.length===0&&console.log(`(none — add [[agents]] to the server config)`);return}if(g.includes(i.name)||d(`Unknown agent "${i.name}" (configured: ${g.join(`, `)||`none`})`),i.listSessions){let{sessions:e}=await(await t(m,`/agents/${encodeURIComponent(i.name)}/sessions`)).json();if(!e?.length){console.log(`No sessions yet.`);return}for(let t of e)console.log(`${t.sessionId}  ${o}${t.updatedAt}${l}${t.parentSession?`  ${o}(fork of ${t.parentSession})${l}`:``}`),t.preview&&console.log(`  ${o}${t.preview}${l}`);return}if(process.stdin.isTTY&&process.stdout.isTTY&&!i.plain){let{runAgentTui:e}=await import(`./tui-7B7x6A08.mjs`);await e({connection:m,agentName:i.name,sessionId:i.sessionId,fork:i.fork});return}await p(m,i.name,i.sessionId,i.fork)};export{m as runAgentCommand};

package/lib/client-BCBBen9i.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import{a as e,n as t}from"./config-lP89VahD.mjs";import n from"node:path";import r from"node:fs";import i from"@iarna/toml";const a=a=>{let o={},s=process.cwd();a&&(r.existsSync(a)?(o=i.parse(r.readFileSync(a,`utf8`)),s=n.dirname(n.resolve(a))):o=i.parse(a));let c=e(o);return{config:c,configDir:s,agentsConfig:t(c,{configDir:s})}},o=e=>{try{return r.readFileSync(e,`utf8`).trim()||null}catch{return null}},s=async(e,t,n)=>fetch(`${e.baseUrl}${t}`,{...n,headers:{"content-type":`application/json`,...e.token?{authorization:`Bearer ${e.token}`}:{},...n?.headers}});async function*c(e){let t=e.getReader(),n=new TextDecoder,r=``;try{for(;;){let{done:e,value:i}=await t.read();if(e)break;r+=n.decode(i,{stream:!0});let a=r.indexOf(`
+
+`);for(;a!==-1;){let e=r.slice(0,a);r=r.slice(a+2),a=r.indexOf(`
+
+`);let t=`message`,n=[];for(let r of e.split(`
+`))r.startsWith(`event:`)?t=r.slice(6).trim():r.startsWith(`data:`)&&n.push(r.slice(5).trimStart());n.length>0&&(yield{event:t,data:n.join(`
+`)})}}}finally{t.releaseLock()}}const l=(e,t)=>t!=null&&t!==e,u=async(e,t,n,{signal:r,onFrame:i})=>{let a=n.sessionId??null,o;try{o=await s(e,`/agents/${encodeURIComponent(t)}/run?stream=1`,{method:`POST`,body:JSON.stringify({prompt:n.prompt,...n.sessionId?{sessionId:n.sessionId}:{},...n.fork?{fork:!0}:{}}),signal:r})}catch(e){if(r?.aborted)return{kind:`aborted`,sessionId:a};throw e}if(!o.ok||!o.body){let e=await o.text().catch(()=>``);return{kind:`error`,message:`Run request failed (${o.status}): ${e.slice(0,400)}`,sessionId:a}}try{for await(let e of c(o.body)){let t;try{t=JSON.parse(e.data)}catch{continue}if(e.event===`session`&&t?.sessionId&&(a=t.sessionId),e.event===`result`)return i({event:e.event,payload:t}),{kind:`result`,result:t};if(e.event===`error`)return i({event:e.event,payload:t}),{kind:`error`,message:t?.message||`run failed`,sessionId:t?.sessionId??a};i({event:e.event,payload:t})}}catch(e){if(r?.aborted)return{kind:`aborted`,sessionId:a};throw e}return r?.aborted?{kind:`aborted`,sessionId:a}:{kind:`disconnected`,sessionId:a}};export{u as a,s as i,a as n,o as r,l as t};

package/lib/config-lP89VahD.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import e from"node:path";import t from"node:os";import n from"bytes";import r from"ms";import i from"node-machine-id";const a=(e={},t={})=>{let n=Array.isArray(e)?[...e]:{...e};return Object.entries(t||{}).forEach(([e,t])=>{t&&typeof t==`object`&&!Array.isArray(t)?n[e]=a(n[e]||{},t):n[e]=t}),n},o=e=>e&&typeof e==`object`?structuredClone(e):null,s=(e,t)=>{let n=o(e)||{},r=o(t)||{};return a(n,r)},c=(e,t)=>a(structuredClone(e.global),t||{}),l=(e,t,n,r)=>{if(e.generators.length>0){let i=e.generators.filter(e=>e?.type===n);if(i.length>0&&r){let a=i.find(e=>t.getModelIdentifier(n,e)===r);if(a)return c(e,a)}}return Object.keys(e.global).length>0?c(e,{}):null},u={udp:{port:8089,announcements:{enabled:!0,interval:5e3},requests:{enabled:!0,responseDelay:100}},http:{enabled:!0,path:`/buttress/info`,cors:!0}},d=e=>e?e===!0?{...u}:a(u,e):null,f=(e,t)=>{if(!e.generators||e.generators.length===0)return t.map(e=>({type:e}));let n=new Set;return e.generators.forEach(e=>{e.type&&n.add(e.type)}),n.size===0?t.map(e=>({type:e})):Array.from(n).map(e=>({type:e}))},p=(e,t,n)=>e===void 0?n:typeof e==`number`?e:t(e)??n,m=6e4,h=1024*1024*50,g=s=>{let c=i.machineIdSync(),l={server:{id:`buttress-${c}`,name:`Buttress Server (${c.slice(-8)})`,port:2080,temp_file_dir:e.join(t.tmpdir(),`.buttress`),session_timeout:m,max_body_size:h},autodiscover:!1},u=a(l,o(s)||{}),f=Array.isArray(u.generators)?u.generators:[],{server:g,generators:_,autodiscover:v,...y}=u;return{autodiscover:d(v),server:{id:g.id,name:g.name,port:g.port,log_level:g.log_level,temp_file_dir:g.temp_file_dir,max_body_size:p(g.max_body_size,n.parse,h),session_timeout:p(g.session_timeout,e=>r(e),m)},global:y,generators:f}},_=/^[A-Za-z0-9_-]{1,64}$/,v=n=>n===`~`||n.startsWith(`~/`)?e.join(t.homedir(),n.slice(1)):n;var y=class extends Error{constructor(e){super(`[Agents] ${e}`),this.name=`AgentsConfigError`}};const b=(e,t,n)=>{if(t==null)return n;if(t===0||t===!1)return null;if(typeof t==`number`){if(Number.isFinite(t)&&t>0)return t}else if(typeof t==`string`){let e;try{e=r(t)}catch{e=void 0}if(typeof e==`number`&&e>0)return e}throw new y(`agents_options.${e} must be a duration string (e.g. "30d") or a positive number of milliseconds; use 0 to disable it`)},x=(e,t)=>{if(t==null)return{};if(typeof t!=`object`||Array.isArray(t))throw new y(`agent "${e}": mcp_servers must be a table`);let n={};for(let[r,i]of Object.entries(t)){if(!_.test(r))throw new y(`agent "${e}": MCP server name "${r}" must match ${_}`);let t=!!(typeof i?.url==`string`&&i.url),a=!!(typeof i?.command==`string`&&i.command);if(t===a)throw new y(`agent "${e}": MCP server "${r}" needs exactly one of url / command`);n[r]={url:t?i.url:void 0,headers:i?.headers&&typeof i.headers==`object`?i.headers:void 0,command:a?i.command:void 0,args:Array.isArray(i?.args)?i.args.map(String):void 0,env:i?.env&&typeof i.env==`object`?i.env:void 0,optional:i?.optional===!0}}return n},S=(e,t,n)=>{let r=e?.name;if(typeof r!=`string`||!_.test(r))throw new y(`[[agents]] #${t+1}: name is required and must match ${_}`);let i=e?.model;if(typeof i!=`string`||!i.includes(`/`))throw new y(`agent "${r}": model must be "provider/model-id" (e.g. "buttress/ggml-org/gpt-oss-20b-GGUF")`);let a=i.indexOf(`/`),o=i.slice(0,a),s=i.slice(a+1);if(!o||!s)throw new y(`agent "${r}": invalid model reference "${i}"`);if(o===`buttress`&&!n.generators.filter(e=>e.type===`ggml-llm`||e.type===`mlx-llm`).some(e=>(e.model?.repo_id||e.model?.repository)===s))throw new y(`agent "${r}": model "${s}" does not match any configured [[generators]] ggml-llm/mlx-llm repo_id`);if(e?.system_prompt!=null&&e?.system_prompt_file!=null)throw new y(`agent "${r}": set system_prompt or system_prompt_file, not both`);let c=[];if(e?.tools!=null){if(!Array.isArray(e.tools))throw new y(`agent "${r}": tools must be an array of function names`);for(let t of e.tools){if(typeof t!=`string`||!_.test(t))throw new y(`agent "${r}": tool name "${t}" must match ${_} (local function names only)`);if(c.includes(t))throw new y(`agent "${r}": duplicate tool "${t}"`);c.push(t)}}let l=Number(e?.max_turns??30);if(!Number.isInteger(l)||l<1)throw new y(`agent "${r}": max_turns must be a positive integer`);let u=null;if(e?.max_tokens_per_run!=null&&(u=Number(e.max_tokens_per_run),!Number.isInteger(u)||u<1))throw new y(`agent "${r}": max_tokens_per_run must be a positive integer`);let{name:d,model:f,system_prompt:p,system_prompt_file:m,tools:h,mcp_servers:g,max_turns:v,max_tokens_per_run:b,thinking:S,...C}=e;return{name:r,provider:o,modelId:s,modelRef:i,systemPrompt:typeof p==`string`?p:null,systemPromptFile:typeof m==`string`?m:null,tools:c,mcpServers:x(r,g),maxTurns:l,maxTokensPerRun:u,thinking:typeof S==`string`?S:void 0,generation:C}},C=(t,{configDir:n=process.cwd()}={})=>{let r=t.global||{},i=r.agents;if(i==null)return null;if(!Array.isArray(i))throw new y(`agents must be an array of tables ([[agents]])`);if(i.length===0)return null;let a=i.map((e,n)=>S(e,n,t)),o=new Set;for(let e of a){if(o.has(e.name))throw new y(`duplicate agent name "${e.name}"`);o.add(e.name)}let s=r.agents_options||{},c=typeof s.sessions_dir==`string`&&s.sessions_dir?s.sessions_dir:`./.buttress-agent/sessions`,l=v(c),u=e.isAbsolute(l)?l:e.resolve(n,l);for(let t of a)if(t.systemPromptFile){let r=v(t.systemPromptFile);t.systemPromptFile=e.isAbsolute(r)?r:e.resolve(n,r)}let d=Number(s.max_depth??2);if(!Number.isInteger(d)||d<1)throw new y(`agents_options.max_depth must be a positive integer`);let f=s.session_max_count,p=500;if(f===0||f===!1)p=null;else if(f!=null&&(p=Number(f),!Number.isInteger(p)||p<1))throw new y(`agents_options.session_max_count must be a positive integer`);return{agents:a,configDir:n,sessionsDir:u,runtimeTokenFile:e.join(e.dirname(u),`runtime-token`),sessionMaxAgeMs:b(`session_max_age`,s.session_max_age,2592e6),sessionMaxCount:p,maxDepth:d,allowUnauthenticated:s.allow_unauthenticated===!0}};export{g as a,o as i,C as n,l as o,s as r,f as s,y as t};

package/lib/functions/bank-subscribe.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Data Bank change subscriptions for daemon functions.
+ *
+ * The Bank's `/api/subscriptions` WebSocket speaks the *legacy* `graphql-ws`
+ * protocol (`connection_init` → `connection_ack`, `start` → `data`, `ka`
+ * keep-alives) — that is what the deployed juniper handler serves, and what
+ * every production client falls back to. The vocabulary is four message types,
+ * so this is a small hand-rolled client rather than a protocol library (the
+ * maintained `graphql-ws` npm package only speaks the newer
+ * `graphql-transport-ws` protocol, which the Bank does not).
+ *
+ * Auth rides on the upgrade request's query string (`?spacename=&spacekey=`),
+ * which the Bank accepts as an alternative to headers — the standard
+ * `WebSocket` global cannot set custom headers.
+ *
+ * One connection multiplexes every daemon's subscription (one `start` per
+ * daemon, ids routed on `data`). The socket opens when the first subscription
+ * is added, reconnects with backoff while any remain, and closes when the
+ * last one is removed. The Bank pushes `ka` every ~10s, so a silent socket is
+ * a dead one: a watchdog forces a reconnect when nothing arrives for a while.
+ */
+import type { BankBinding } from '../utils/workspaceState';
+import type { BankProperty } from './types';
+export type BankSubscriberStatus = 'idle' | 'connecting' | 'connected' | 'disconnected';
+export type BankSubscription = {
+    close: () => void;
+};
+export type BankSubscriberOptions = {
+    /** Injectable for tests; defaults to the global WebSocket. */
+    webSocketImpl?: typeof WebSocket;
+    /** Injectable timer fns for tests. */
+    setTimeoutFn?: typeof setTimeout;
+    clearTimeoutFn?: typeof clearTimeout;
+};
+/** Build the legacy-protocol subscriptions URL for a Bank binding. */
+export declare const bankSubscriptionsUrl: (binding: BankBinding) => string;
+export type BankSubscriber = ReturnType<typeof createBankSubscriber>;
+export declare const createBankSubscriber: (binding: BankBinding, { webSocketImpl, setTimeoutFn, clearTimeoutFn, }?: BankSubscriberOptions) => {
+    status: () => BankSubscriberStatus;
+    /**
+     * Watch a set of property ids. `onProperties` receives each change batch;
+     * `onStatus` follows the shared connection's health.
+     */
+    subscribe(filteredProps: string[], onProperties: (properties: BankProperty[]) => void, onStatus: (status: BankSubscriberStatus) => void): BankSubscription;
+    dispose(): void;
+};

package/lib/functions/bank.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `context.bank` — remote Data Bank access for local functions.
+ *
+ * Talks to the public Data Bank GraphQL API (SPACENAME/SPACEKEY headers) with
+ * credentials issued by `bricks buttress bank-key` and stored in the buttress
+ * state file. Read/write only in v1 — no subscription surface. Mirrors the
+ * client in packages/bricks-cli/src/utils/bank-client.js.
+ */
+import type { BankContext, BankProperty } from './types';
+import type { BankBinding } from '../utils/workspaceState';
+export declare const PROPERTY_FIELDS = "\n  propertyId\n  meta\n  definition\n  value\n  tags\n  lastUpdateHash\n  lastUpdateNote\n  lastUpdateKey\n  createAt\n  updateAt\n";
+export declare const normalizeProperty: (property: any) => BankProperty;
+export declare class BankNotConfiguredError extends Error {
+    constructor();
+}
+type CreateBankContextOptions = {
+    /** Ends in-flight Bank requests when the call is aborted or times out. */
+    signal: AbortSignal;
+};
+export declare const createBankContext: (binding: BankBinding | null | undefined, { signal }: CreateBankContextOptions) => BankContext;
+export {};

package/lib/functions/daemons.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Daemon functions: long-lived local functions.
+ *
+ * A file with `meta.daemon = true` is a daemon. Its default export runs
+ * **once** when the daemon starts, with a `DaemonContext` — the ordinary
+ * function context plus lifetime APIs — and everything it registers there
+ * keeps running after the invocation returns:
+ *
+ *   - `context.setInterval(cb, ms)` / `context.clearInterval(handle)` —
+ *     managed timers; a callback that throws is logged, never fatal.
+ *   - `context.bank.subscribe(ids, onChange)` — remote Data Bank change
+ *     notifications over one shared, auto-reconnecting connection.
+ *   - `context.onEvent(handler)` — events other local functions send via
+ *     `context.daemons.emit(name, event, data)`.
+ *
+ * No deadline applies to a daemon (`meta.timeout` is ignored). It stops when
+ * its file changes or disappears (the manager's reconcile — eager with the
+ * hot-reload watcher, a periodic sweep otherwise) or on server shutdown:
+ * `context.signal` aborts, timers and subscriptions are torn down, spawned
+ * children are killed, and a cleanup function returned by the handler (if
+ * any) gets a bounded run. A file edit then starts a fresh module.
+ */
+import { createBankSubscriber } from './bank-subscribe';
+import type { FunctionsRegistry } from './registry';
+import type { FunctionsStatusTracker } from './status';
+import type { DaemonSummary, DaemonsHub, FunctionRuntime, FunctionsConfig } from './types';
+export type CreateDaemonManagerOptions = {
+    registry: FunctionsRegistry;
+    runtime: FunctionRuntime;
+    functionsConfig: FunctionsConfig;
+    tracker?: FunctionsStatusTracker;
+    /** Injectable for tests; defaults to `createBankSubscriber`. */
+    subscriberFactory?: typeof createBankSubscriber;
+    reconcileIntervalMs?: number;
+    /** Called after every reconcile with the current daemon count. */
+    onReconciled?: (count: number) => void;
+};
+export type DaemonManager = ReturnType<typeof createDaemonManager>;
+export declare const createDaemonManager: ({ registry, runtime, functionsConfig, tracker, subscriberFactory, reconcileIntervalMs, onReconciled, }: CreateDaemonManagerOptions) => {
+    hub: DaemonsHub;
+    reconcile: () => Promise<void>;
+    count: () => number;
+    list: () => DaemonSummary[];
+    dispose: () => Promise<void>;
+};

package/lib/functions/executor.d.ts

@@ -8,20 +8,47 @@
  * 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';
+import type { DaemonsHub, FunctionContext, 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 = {
+export type CallContextOptions = {
     runtime: FunctionRuntime;
     functionsConfig: FunctionsConfig;
     /** Streams progress to the caller; ignored on non-streaming surfaces. */
     emit?: FunctionEmit;
+    callId?: string;
+    /** Routes `context.daemons`; absent when the daemon manager is not running. */
+    daemons?: DaemonsHub;
+    /**
+     * Agent-invocation chain depth of this call (0 = a person/HTTP/MCP caller).
+     * Agent-invoked tool calls pass depth+1 so `context.agents.run` can cap
+     * function -> agent -> function -> agent recursion.
+     */
+    agentDepth?: number;
+};
+export type ExecuteOptions = CallContextOptions & {
     /** 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>;
+/** A live function context plus the levers that end it. */
+export type FunctionCallHandle = {
+    context: FunctionContext;
+    /** Aborted when the run is stopped or times out. */
+    signal: AbortSignal;
+    /** Abort the run and terminate every child process it spawned. */
+    abort: () => void;
+    /** Final cleanup: stop `emit` delivery and kill leftover children. */
+    finish: () => void;
+};
+/**
+ * Build the context a function runs against, without any deadline or
+ * lifecycle policy. `executeFunction` wraps this for ordinary calls (deadline
+ * + abort race); the daemon manager uses it directly for its long-lived
+ * runs, where the context must outlive the initial invocation.
+ */
+export declare const createCallContext: (fn: LoadedFunction, { runtime, functionsConfig, emit, callId, daemons, agentDepth, }: CallContextOptions) => FunctionCallHandle;
+export declare const executeFunction: (fn: LoadedFunction, input: any, { signal, ...contextOptions }: ExecuteOptions) => Promise<any>;

package/lib/functions/index.d.ts

@@ -6,9 +6,9 @@
  * owns discovery/reload (registry) and execution (executor), and prepares the
  * directory for authoring on startup.
  */
-import type { FunctionEmit, FunctionRuntime, FunctionSummary, FunctionsConfig, LoadedAuthFunction } from './types';
+import type { DaemonSummary, FunctionEmit, FunctionRuntime, FunctionSummary, FunctionsConfig, LoadedAuthFunction } from './types';
 export { resolveFunctionsConfig } from './config';
-export { FunctionNotFoundError } from './registry';
+export { FunctionNotFoundError, FunctionNotCallableError } from './registry';
 export { FunctionAbortError, FunctionTimeoutError } from './executor';
 export { FunctionImportError } from './loader';
 export { AUTH_BASENAME } from './auth';
@@ -19,12 +19,16 @@ export type CallOptions = {
     signal?: AbortSignal;
     callId?: string;
     /** Which API carried the call — recorded in the status history. */
-    surface?: 'http' | 'sse' | 'mcp';
+    surface?: 'http' | 'sse' | 'mcp' | 'agent';
+    /** Agent-invocation chain depth (agent tool calls pass their run's depth). */
+    agentDepth?: number;
 };
 export type FunctionsService = {
     config: FunctionsConfig;
     dir: string;
     list: () => Promise<FunctionSummary[]>;
+    /** Daemons the manager is currently running (empty when daemons are off). */
+    listDaemons: () => DaemonSummary[];
     /** One function's summary; rejects when it is unknown or fails to load. */
     describe: (name: string) => Promise<FunctionSummary>;
     call: (name: string, input: any, options: CallOptions) => Promise<any>;
@@ -35,18 +39,24 @@ export type FunctionsService = {
     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.
+     * `list()` (and every daemon reconcile) so the announced counts follow the
+     * directory instead of freezing at whatever was on disk during startup.
      */
     stats: {
         enabled: true;
         count: number;
+        daemons: number;
     };
-    /** Stop the hot-reload watcher, when one is running. Safe to call always. */
+    /** Stop the hot-reload watcher and daemons. Safe to call always. */
     dispose: () => void;
 };
 export type CreateFunctionsServiceOptions = {
     /** `server.temp_file_dir`; per-call scratch space lives under it. */
     tempFileDir: string;
+    /**
+     * Server-wide runtime for daemon invocations. Daemon files are inert (with
+     * a warning) when omitted — request surfaces still pass a runtime per call.
+     */
+    runtime?: FunctionRuntime;
 };
-export declare const createFunctionsService: (config: FunctionsConfig, { tempFileDir }: CreateFunctionsServiceOptions) => Promise<FunctionsService>;
+export declare const createFunctionsService: (config: FunctionsConfig, { tempFileDir, runtime }: CreateFunctionsServiceOptions) => Promise<FunctionsService>;

package/lib/functions/registry.d.ts

@@ -10,7 +10,7 @@
  * 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';
+import type { DaemonSummary, FunctionSummary, FunctionsConfig, LoadedFunction } from './types';
 type Entry = {
     name: string;
     file: string;
@@ -22,6 +22,9 @@ type Entry = {
 export declare class FunctionNotFoundError extends Error {
     constructor(name: string);
 }
+export declare class FunctionNotCallableError extends Error {
+    constructor(name: string);
+}
 export type FunctionsRegistry = ReturnType<typeof createFunctionsRegistry>;
 export declare const createFunctionsRegistry: (config: FunctionsConfig) => {
     dir: string;
@@ -30,6 +33,9 @@ export declare const createFunctionsRegistry: (config: FunctionsConfig) => {
     get: (name: string) => Promise<LoadedFunction>;
     describe: (name: string) => Promise<FunctionSummary>;
     list: () => Promise<FunctionSummary[]>;
+    listDaemons: () => Promise<LoadedFunction[]>;
     entries: Map<string, Entry>;
 };
+/** A daemon's public shape, as reported by `GET /functions` and the status page. */
+export declare const toDaemonSummary: (fn: LoadedFunction) => DaemonSummary;
 export {};

package/lib/functions/status.d.ts

@@ -13,11 +13,41 @@
 export type FunctionCallRecord = {
     timestamp: string;
     name: string;
-    surface: 'http' | 'sse' | 'mcp';
+    surface: 'http' | 'sse' | 'mcp' | 'agent';
     durationMs: number;
     success: boolean;
     error?: string;
 };
+export type DaemonActivityRecord = {
+    timestamp: string;
+    name: string;
+    /** Which daemon callback ran ('start', 'interval', 'bank', 'event', 'stop'). */
+    event: string;
+    durationMs: number;
+    success: boolean;
+    error?: string;
+};
+/** Live state of one daemon, provided by the daemon manager. */
+export type DaemonStateSnapshot = {
+    name: string;
+    state: 'running' | 'error';
+    description: string;
+    startedAt: string | null;
+    /** Active `context.setInterval` timers. */
+    timers: number;
+    /** Active `context.bank.subscribe` subscriptions. */
+    bankSubscriptions: number;
+    /** Data Bank connection health; null while the daemon holds no subscriptions. */
+    bank: 'connected' | 'connecting' | 'disconnected' | null;
+    /** Whether the daemon registered a `context.onEvent` handler. */
+    listening: boolean;
+    counts: {
+        runs: number;
+        failed: number;
+    };
+    /** Why the daemon is in 'error' state (start failed / file no longer loads). */
+    error?: string;
+};
 export type FunctionUploadRecord = {
     timestamp: string;
     /** 'upload' = POST /functions/upload, 'call' = multipart function call. */
@@ -51,6 +81,9 @@ export declare const createFunctionsStatusTracker: (maxHistory?: number) => {
     recordCall(record: Omit<FunctionCallRecord, 'timestamp'>): void;
     recordUpload(record: Omit<FunctionUploadRecord, 'timestamp'>): void;
     recordDownload(record: Omit<FunctionDownloadRecord, 'timestamp'>): void;
+    recordDaemonActivity(record: Omit<DaemonActivityRecord, 'timestamp'>): void;
+    /** Register (or clear, with null) the daemon manager's live-state source. */
+    setDaemonsProvider(provider: (() => DaemonStateSnapshot[]) | null): void;
     recordAuth(record: Omit<FunctionAuthRecord, 'timestamp'>): void;
     snapshot(): {
         counters: {
@@ -72,12 +105,18 @@ export declare const createFunctionsStatusTracker: (maxHistory?: number) => {
                 total: number;
                 denied: number;
             };
+            daemons: {
+                invocations: number;
+                failed: number;
+            };
         };
+        daemons: DaemonStateSnapshot[];
         history: {
             calls: FunctionCallRecord[];
             uploads: FunctionUploadRecord[];
             downloads: FunctionDownloadRecord[];
             auth: FunctionAuthRecord[];
+            daemons: DaemonActivityRecord[];
         };
     };
 };
@@ -87,6 +126,9 @@ export declare const functionsStatusTracker: {
     recordCall(record: Omit<FunctionCallRecord, 'timestamp'>): void;
     recordUpload(record: Omit<FunctionUploadRecord, 'timestamp'>): void;
     recordDownload(record: Omit<FunctionDownloadRecord, 'timestamp'>): void;
+    recordDaemonActivity(record: Omit<DaemonActivityRecord, 'timestamp'>): void;
+    /** Register (or clear, with null) the daemon manager's live-state source. */
+    setDaemonsProvider(provider: (() => DaemonStateSnapshot[]) | null): void;
     recordAuth(record: Omit<FunctionAuthRecord, 'timestamp'>): void;
     snapshot(): {
         counters: {
@@ -108,12 +150,18 @@ export declare const functionsStatusTracker: {
                 total: number;
                 denied: number;
             };
+            daemons: {
+                invocations: number;
+                failed: number;
+            };
         };
+        daemons: DaemonStateSnapshot[];
         history: {
             calls: FunctionCallRecord[];
             uploads: FunctionUploadRecord[];
             downloads: FunctionDownloadRecord[];
             auth: FunctionAuthRecord[];
+            daemons: DaemonActivityRecord[];
         };
     };
 };