@fugood/buttress-server 2.26.0-beta.1 → 2.26.0-beta.10

package/README.md

@@ -154,6 +154,7 @@ Configuration is loaded from a TOML file passed via `--config` / `-c`. Every top
 | `[openai_compat]`         | Enable `/oai-compat/v1/*` — see [Compatibility Endpoints](#compatibility-endpoints-experimental)   |
 | `[anthropic_messages]`    | Enable `/anthropic-messages` — see [Compatibility Endpoints](#compatibility-endpoints-experimental)|
 | `[functions]`             | Enable local functions — see [Local Functions](#local-functions-experimental)                      |
+| `[[agents]]`              | Config-defined agents — see [Agents](#agents-experimental)                                         |
 | `[[generators]]`          | Array of generator instances — one entry per loaded model                                          |
 
 ### `[env]`
@@ -653,9 +654,9 @@ dir = "./functions"           # relative paths resolve against this config file
 
 `ENABLE_FUNCTIONS_ENDPOINT=1` and `BUTTRESS_FUNCTIONS_DIR=<dir>` are equivalent to the first two keys.
 
-On startup the server creates the directory if needed and writes `buttress-functions.d.ts` (ambient types, refreshed every start), plus a `tsconfig.json` and a commented `_example.ts` when the directory holds no functions yet.
+On startup the server creates the directory if needed and writes `buttress-functions.d.ts` (ambient types, refreshed every start), plus a `tsconfig.json` and commented `_example.ts` / `_example-daemon.ts` files when the directory holds no functions yet.
 
-Ready-to-copy examples — a no-prerequisite starter, LLM summarization, sqlite-vec RAG, ffmpeg + STT transcription, TTS with a downloadable result, and a custom auth gate — live in [`config/function-samples/`](config/function-samples/).
+Ready-to-copy examples — a no-prerequisite starter, LLM summarization, sqlite-vec RAG, ffmpeg + STT transcription, TTS with a downloadable result, a remote Data Bank read/write, a Data Bank–watching daemon, and a custom auth gate — live in [`config/function-samples/`](config/function-samples/).
 
 ### Writing a function
 
@@ -693,6 +694,8 @@ export default async function ({ path }: { path: string }, context: ButtressFunc
 | `buttress.detokenize({ model?, tokens })` | Convert token ids back into text with the same model. |
 | `buttress.transcribe({ model?, filePath \| audioData, options? })` | Transcribe audio with this server's STT generator. |
 | `buttress.synthesize({ model?, text, options? })` | Synthesize speech with this server's TTS generator (`onnx-tts` or `ggml-tts`); the WAV lands in `tempDir` → `{ path, sampling_rate, channels }`. |
+| `bank.list({ keyword?, meta?, ids? })` / `bank.get(id)` / `bank.update(properties, { dontNotify? })` / `bank.remove(id)` | Read/write the bound workspace's remote **Data Bank** (see below). To listen for changes, use `bank.subscribe` inside a daemon function. |
+| `daemons.emit(name, event, data?)` / `daemons.list()` | Signal a running **daemon function**'s `onEvent` handlers (see below) / list running daemon names. |
 | `emit(event, data)` | Progress event; delivered to SSE callers, ignored otherwise. |
 | `signal` | `AbortSignal`, aborted on timeout or caller disconnect. |
 | `tempDir` | Per-call scratch directory, created on first access. |
@@ -700,6 +703,52 @@ export default async function ({ path }: { path: string }, context: ButtressFunc
 | `log`, `fetch`, `env`, `config`, `dir` | Prefixed logging, host `fetch`, `process.env`, the `[functions.config]` table, the functions directory. |
 | `libs` | `_`/`lodash`, `moment`, `math`/`mathjs`, `voca`, `chroma`, `json5`, `qs`, `bytes`, `ms`, `nanoid`, `md5`. |
 
+#### Remote Data Bank (`context.bank`)
+
+A bound server can read and write the workspace's remote **Data Bank** — the same property space the `bricks data` CLI commands and remote-update apps use. Credentials are issued through the Workspace API by the CLI and stored next to the workspace binding:
+
+```bash
+bricks buttress bank-key      # on the server host, from a workspace-authed CLI
+# then restart buttress-server
+```
+
+This writes a `bank` entry (Data Bank endpoint + spacename + space key) into `~/.bricks-cli/buttress/state.json`. Until it exists, every `context.bank` method throws with a hint. `bricks buttress bank-key --revoke` revokes the key and removes the entry; re-running `bank-key` rotates it.
+
+`context.bank` is read/write; to *react* to Data Bank changes, use `bank.subscribe` inside a daemon function (below) — it throws elsewhere. Mind one Bank semantic: `update` **replaces `value` unconditionally** (an omitted `value` clears the stored one), so read-merge first when only part of an object should change. Updates notify subscribed devices unless you pass `{ dontNotify: true }`. See `config/function-samples/bank-note.ts` for the end-to-end shape.
+
+#### Daemon functions (`meta.daemon`)
+
+A file with `meta.daemon = true` runs as a **daemon**: a long-lived background function. Its default export runs **once** when the daemon starts — with a `ButtressDaemonContext` as its only argument — and everything it registers there keeps running after it returns. Daemons are not MCP tools and cannot be called over HTTP (a direct call returns `400 FUNCTION_NOT_CALLABLE`); `GET /functions` lists them in a separate `daemons` array. `meta.timeout` does not apply — a daemon has no deadline.
+
+```ts
+export const meta: ButtressFunctionMeta = {
+  description: 'Watch the Data Bank and keep a summary fresh',
+  daemon: true,
+}
+
+export default async function (context: ButtressDaemonContext) {
+  context.setInterval(async () => {
+    // periodic work; an error here is logged, the timer keeps firing
+  }, 5 * 60 * 1000)
+
+  context.bank.subscribe(['orders', 'menu'], async (properties) => {
+    // remote Data Bank changes to the watched property ids
+  })
+
+  context.onEvent(async ({ event, data, source }) => {
+    // another local function called context.daemons.emit('<this-file>', event, data)
+  })
+
+  return () => {
+    // optional cleanup, runs when the daemon stops
+  }
+}
+```
+
+The daemon context is the full function context plus lifetime APIs. `setInterval(cb, ms)` / `clearInterval(handle)` are managed timers: a callback that throws is logged (and recorded on `/status`) but never stops the timer or the daemon; everything is cleared when the daemon stops. `bank.subscribe(propertyIds, onChange)` uses the same Bank credentials as `context.bank` (`bricks buttress bank-key`; throws until stored); all subscriptions share one auto-reconnecting connection, so a network drop never stops the daemon — note a daemon that writes the properties it watches also notifies itself unless it passes `{ dontNotify: true }`. `onEvent(handler)` receives what other local functions (and daemons) send with `context.daemons.emit(name, event, data?)`, as `{ event, data, source }`; `emit` throws when the target daemon is not running or registered no handler, and events emitted while a daemon is still starting are buffered until it settles.
+
+The handler runs with no deadline; `context.signal` aborts when the daemon stops. A file edit restarts it (cleanup → fresh module → start) — on save with `hot_reload = true`, otherwise on the periodic (~60s) reconcile sweep. A start invocation that throws, or a file that stops loading, suspends the daemon (shown as an error on `/status`) until the file changes again. On stop, timers and subscriptions are torn down, spawned children are killed, and the returned cleanup gets a bounded (~10s) run. `context.emit` (SSE progress) is a no-op inside a daemon — there is no caller; use `context.log` and the status page.
+
 Functions may `import` Node builtins (`node:fs/promises`, …), sibling files inside the functions directory, and the two provided database packages `sqlite3` and `sqlite-vec`. Other package imports are rejected. `sqlite-vec` supports macOS and Linux on x64/arm64, plus Windows x64; its upstream package does not ship a Windows arm64 extension, so the standalone Windows arm64 build does not provide either SQLite import.
 
 Edits are picked up on the next call — the server re-transpiles when a file in the function's module graph changes, so no restart is needed. A file that fails to load is logged and skipped; the rest keep working.
@@ -718,7 +767,7 @@ For faster authoring feedback, opt into eager reloading with `[functions] hot_re
 | `GET /functions/files/<path>` | Download a file a function wrote to its `tempDir` — functions hand out these URLs via `context.fileUrl` |
 | `POST /functions/upload` | Stage an input file on the server (multipart, `file` field) → `{ "path", "url", "name", "size" }` |
 
-Errors come back as `{ "error": { "code", "message" } }` with `FUNCTION_NOT_FOUND` (404), `FUNCTION_TIMEOUT` (504), `FUNCTION_FAILED` (500) or `FUNCTION_FILE_NOT_FOUND` (404).
+Errors come back as `{ "error": { "code", "message" } }` with `FUNCTION_NOT_FOUND` (404), `FUNCTION_NOT_CALLABLE` (400, the name is a daemon), `FUNCTION_TIMEOUT` (504), `FUNCTION_FAILED` (500) or `FUNCTION_FILE_NOT_FOUND` (404).
 
 #### Calling with GET
 
@@ -752,7 +801,7 @@ curl -X POST <base>/functions/transcribe-media -F file=@interview.mp4
 
 To stage a file once and reuse it across calls, `curl -F file=@interview.mp4 <base>/functions/upload` stores it in its own scratch directory and returns `{ "path", "url", "name", "size" }` — pass `path` as the function's input. Either way the client file name is sanitized to a bare name, and staged files share the auth guard and the ~24h sweep. Requests are capped by `[server] max_body_size` (default 50MB) — raise it for large media.
 
-All of this activity is observable: the `/status` dashboard (and the `/buttress/status` JSON it polls) carries a **Local Functions** card with counters since startup and recent history for calls (per surface: HTTP/SSE/MCP, with durations and failure reasons), uploads, downloads, and auth decisions (allowed/denied with mode and subject — never credentials).
+All of this activity is observable: the `/status` dashboard (and the `/buttress/status` JSON it polls) carries a **Local Functions** card with counters since startup and recent history for calls (per surface: HTTP/SSE/MCP, with durations and failure reasons), daemon callback runs, uploads, downloads, and auth decisions (allowed/denied with mode and subject — never credentials). Daemons additionally get a live table: running/error state, start time, active timers, Bank subscription health, listening flag, and callback run/failure counts.
 
 To point an agent at the MCP endpoint:
 
@@ -802,6 +851,117 @@ The handler receives `{ method, path, name?, headers, query, token, workspaceAut
 
 Function files themselves are trusted input, exactly like this config file. They run in a `node:vm` context with a clean global (no ambient `process` or `require`), but that is for clarity, not isolation — a function that is handed `spawn` can do anything the server process can. Only put code you wrote (or reviewed) in the functions directory.
 
+## Agents (Experimental)
+
+Buttress can host **agents**: pi-based LLM loops that run inside the server
+process, use **local functions** (and MCP servers) as their tools, and keep
+**config-scoped sessions** on disk. The primary consumer is automation — a
+local function or daemon calls `context.agents.run(...)` to add multi-step
+reasoning to a server-side workflow; an interactive CLI exists for driving and
+inspecting the same agents.
+
+```toml
+[[agents]]
+name = "ops-assistant"                        # unique; the session scope key
+model = "buttress/ggml-org/gpt-oss-20b-GGUF"  # split on the FIRST slash: provider/model-id
+# model = "anthropic/claude-sonnet-5"         # any pi-supported provider; API key from env
+system_prompt_file = "./prompts/ops.md"       # or inline: system_prompt = "..."
+tools = ["get_server_status", "restart_service"]  # local function names (explicit; no wildcard)
+max_turns = 30                                 # assistant↔tool round-trips per run (default 30)
+# max_tokens_per_run = 200000                 # per-run token budget; unset = unlimited
+# temperature = 0.2                           # unrecognized keys pass through to generation
+
+[agents.mcp_servers.github]                   # optional MCP servers (StreamableHTTP or stdio)
+url = "https://api.githubcopilot.com/mcp/"
+# headers = { Authorization = "Bearer ..." }
+# optional = true                             # continue without this server if it won't connect
+
+[agents_options]                              # optional; defaults shown
+# sessions_dir = "./.buttress-agent/sessions" # relative to this config file
+# session_max_age = "30d"                     # retention sweep; 0 disables
+# session_max_count = 500                     # per agent; 0 disables
+# max_depth = 2                               # function → agent → function → agent chain cap
+# allow_unauthenticated = false               # serve /agents on an UNBOUND server (see below)
+```
+
+**Models.** `buttress/<repo_id>` targets a configured `[[generators]]` LLM
+(ggml/mlx) and is validated at startup; traffic flows through an in-process
+OpenAI-compat loopback (no socket, no extra config — `[openai_compat] enabled`
+still only governs the external HTTP route). Any other provider prefix is a pi
+built-in provider (`anthropic/…`, `openai/…`, `google/…`, …) authenticated by
+its usual environment variable (`ANTHROPIC_API_KEY`, …) — set it via `[env]`
+or the process environment. OAuth-based logins are not supported headless.
+
+**Tools.** `tools` lists local function names explicitly. Each tool call runs
+through the normal functions executor (same lazy reload, scratch dir, spawn
+tracking, and the function's own `meta.timeout` deadline), and aborting the
+run aborts in-flight tool calls and their spawned processes. A listed function
+that is missing fails the run loudly rather than letting a headless automation
+improvise around it. MCP tools get server-qualified names
+(`mcp__github__create_issue`); MCP servers connect lazily on the first run and
+fail closed unless marked `optional = true`.
+
+**Sessions.** Each run returns a `sessionId`; pass it back to continue the
+conversation, or add `fork: true` to branch it into a fresh session. Sessions
+are JSONL files under `sessions_dir`, scoped by agent name (renaming an agent
+orphans its sessions), written as the run streams — an aborted or timed-out
+run still leaves a continuable transcript. Same-session runs queue; different
+sessions run in parallel. A retention sweep prunes by age and count.
+
+**From a local function** (the primary surface):
+
+```ts
+export default async ({ service }, context) => {
+  const result = await context.agents.run('ops-assistant', {
+    prompt: `Investigate the '${service}' service and fix it if needed.`,
+    // sessionId, fork, onEvent are also accepted
+  })
+  return { conclusion: result.content, sessionId: result.sessionId }
+}
+```
+
+`context.agents.run` resolves within the caller's lifetime and deadline
+(`context.signal` aborts it); long-running agent work belongs in a **daemon**
+(no deadline) or a function with a raised `meta.timeout`. `context.agents.list()`
+and `context.agents.sessions(name)` round out the surface. Chained invocations
+(a tool function calling another agent) are capped by `agents_options.max_depth`.
+
+**HTTP endpoints** (also what the CLI uses):
+
+```
+GET  /agents                           configured agent names
+POST /agents/:name/run                 { prompt, sessionId?, fork? }; ?stream=1 for SSE
+                                       (a `session` event with the id arrives first,
+                                       then `agent` events, then `result`/`error`)
+GET  /agents/:name/sessions            newest-first summaries (id, timestamps, preview)
+GET  /agents/:name/sessions/:id        full transcript
+POST /agents/:name/sessions/:id/abort  abort the active run
+```
+
+Auth mirrors the functions surface, not the open inference endpoints: a bound
+server requires a workspace JWT; an **unbound server rejects remote calls**
+unless `allow_unauthenticated = true`. The server also writes an ephemeral
+internal token to `<sessions_dir>/../runtime-token` (mode 0600) at startup —
+same-host CLIs authenticate with it automatically, bound or not.
+
+**Interactive CLI**:
+
+```sh
+bricks-buttress agent -c config.toml                 # list agents
+bricks-buttress agent ops-assistant -c config.toml   # chat (streams text, thinking, tool calls)
+bricks-buttress agent ops-assistant --sessions -c config.toml
+bricks-buttress agent ops-assistant --session <id> -c config.toml   # continue
+bricks-buttress agent ops-assistant --fork <id> -c config.toml      # fork, then continue the fork
+```
+
+On a real terminal the chat runs a pi-tui interface (markdown answers, dim
+thinking, tool-call lines, Ctrl+C aborts the running turn); pipes/scripts —
+or `--plain` — get a line-based renderer with identical semantics.
+
+Like function files, agent definitions are trusted input: an agent is only as
+safe as the functions and MCP servers you hand it.
+
+
 ## Session State Cache
 
 The server supports session state caching for ggml-llm generators, which saves KV cache state to disk after completions. This enables:

package/config/function-samples/README.md

@@ -14,6 +14,8 @@ needed. On first start the server scaffolds `buttress-functions.d.ts` and a
 | `simple-rag.ts` | Token chunking, embeddings, `sqlite3` + `sqlite-vec` retrieval, then completion | a chat LLM + a GGML embedding `[[generators]]` entry (below) |
 | `transcribe-media.ts` | `context.spawn` (ffmpeg), the scratch dir, SSE progress, STT | `ffmpeg` on PATH + an STT `[[generators]]` entry |
 | `text-to-speech.ts` | TTS (`context.buttress.synthesize`) + downloadable output (`context.fileUrl`) | an `onnx-tts` `[[generators]]` entry |
+| `bank-note.ts` | Reading/writing the workspace's remote Data Bank (`context.bank`) | `bricks buttress bank-key` run on this host |
+| `bank-watch-daemon.ts` | A daemon (`meta.daemon = true`): `context.bank.subscribe`, `context.setInterval`, `context.onEvent` | `bricks buttress bank-key` run on this host |
 | `_auth.ts` | Custom auth: keep workspace tokens working, add static API keys | see the file header |
 
 `_auth.ts` is not a function: copying it changes how every `/functions` endpoint

package/config/function-samples/bank-note.ts

@@ -0,0 +1,47 @@
+// Read and write a property in the workspace's remote Data Bank.
+//
+// Needs stored Data Bank credentials: run `bricks buttress bank-key` from a
+// workspace-authed CLI on this host, then restart the server. Without them
+// every `context.bank` method throws.
+//
+//   curl -X POST http://<host>:<port>/functions/bank-note \
+//     -H 'content-type: application/json' \
+//     -d '{"propertyId": "shared-note", "text": "hello from buttress"}'
+//
+// Omit `text` to read the property without writing.
+
+export const meta: ButtressFunctionMeta = {
+  description: 'Read a Data Bank property, optionally replacing its text value first',
+  parameters: {
+    type: 'object',
+    properties: {
+      propertyId: { type: 'string', description: 'Data Bank property id' },
+      text: { type: 'string', description: 'New value; omit to only read' },
+    },
+    required: ['propertyId'],
+  },
+}
+
+export default async function (
+  { propertyId, text }: { propertyId: string; text?: string },
+  context: ButtressFunctionContext,
+) {
+  if (text != null) {
+    // `update` replaces the stored value unconditionally (an omitted `value`
+    // clears it) — read-merge first when only part of an object should change.
+    await context.bank.update([
+      { propertyId, value: text, updateNote: 'Updated via bank-note function' },
+    ])
+  }
+
+  const property = await context.bank.get(propertyId)
+  if (!property) return { propertyId, exists: false }
+
+  return {
+    propertyId,
+    exists: true,
+    value: property.value,
+    updateAt: property.updateAt,
+    lastUpdateNote: property.lastUpdateNote,
+  }
+}

package/config/function-samples/bank-watch-daemon.ts

@@ -0,0 +1,63 @@
+// Daemon: watch Data Bank properties and keep a change journal.
+//
+// A file with `meta.daemon = true` runs as a daemon — a long-lived
+// background function. Its default export runs ONCE when the daemon starts,
+// and everything registered on the context keeps running after it returns.
+// Daemons are not MCP tools and cannot be called over HTTP; their live
+// status shows on the /status page.
+//
+// This one reacts to remote Data Bank changes (needs stored credentials —
+// run `bricks buttress bank-key` on this host, then restart the server),
+// flushes hourly, and accepts a `flush` event from other local functions:
+//
+//   context.daemons.emit('bank-watch-daemon', 'flush')
+
+export const meta: ButtressFunctionMeta = {
+  description: 'Journal changes to watched Data Bank properties',
+  daemon: true,
+}
+
+export default async function (context: ButtressDaemonContext) {
+  let journal: { at: string; propertyId: string; value: unknown }[] = []
+
+  const flush = async () => {
+    if (journal.length === 0) return
+    const entries = journal
+    journal = []
+    // `dontNotify` keeps this daemon from waking itself up with its own write.
+    await context.bank.update([{ propertyId: 'shared-note-journal', value: entries }], {
+      dontNotify: true,
+    })
+    context.log(`flushed ${entries.length} journal entr${entries.length === 1 ? 'y' : 'ies'}`)
+  }
+
+  // Changes to the watched ids arrive here over a shared, auto-reconnecting
+  // connection — a network drop never stops the daemon.
+  context.bank.subscribe(['shared-note'], (properties) => {
+    for (const property of properties) {
+      journal.push({
+        at: new Date().toISOString(),
+        propertyId: property.propertyId,
+        value: property.value,
+      })
+    }
+    context.log(`journaled ${properties.length} change(s), ${journal.length} pending`)
+  })
+
+  // A managed setInterval: cleared automatically when the daemon stops, and
+  // a callback that throws is logged without stopping the timer.
+  context.setInterval(flush, 60 * 60 * 1000)
+
+  // Other local functions can force a flush via context.daemons.emit.
+  context.onEvent(({ event, source }) => {
+    if (event === 'flush') {
+      context.log(`flush requested by ${source}`)
+      return flush()
+    }
+  })
+
+  context.log('watching shared-note')
+
+  // Runs when the daemon stops (file edited/removed, or server shutdown).
+  return () => flush()
+}

package/config/function-samples/run-agent.ts

@@ -0,0 +1,39 @@
+// Local functions can drive a configured agent (see [[agents]] in the server
+// config): context.agents.run executes a full tool-using LLM loop server-side
+// and returns the final answer plus the session id for follow-ups.
+//
+// The run shares this call's lifetime — the function's deadline (meta.timeout)
+// and client disconnects abort it, including in-flight tool calls. Long agent
+// work belongs in a daemon (no deadline) instead.
+
+export const meta = {
+  description: 'Ask a configured agent to investigate something and return its conclusion.',
+  parameters: {
+    type: 'object',
+    properties: {
+      agent: { type: 'string', description: 'Configured agent name' },
+      question: { type: 'string' },
+      sessionId: { type: 'string', description: 'Continue an earlier session (optional)' },
+    },
+    required: ['agent', 'question'],
+  },
+  timeout: '10m',
+}
+
+export default async (
+  { agent, question, sessionId }: { agent: string; question: string; sessionId?: string },
+  context: any,
+) => {
+  const result = await context.agents.run(agent, {
+    prompt: question,
+    sessionId,
+    // Progress mirrors onto this call's SSE stream automatically; onEvent is
+    // available for custom handling of the raw pi events.
+  })
+  return {
+    conclusion: result.content,
+    sessionId: result.sessionId,
+    turns: result.usage.totalTurns,
+    stopReason: result.stopReason,
+  }
+}

package/config/sample.toml

@@ -45,6 +45,28 @@ enabled = true
 # api_base = "https://example.internal"
 # api_keys = ["a-long-random-string"]  # e.g. consumed by function-samples/_auth.ts
 
+# Agents (EXPERIMENTAL): pi-based LLM loops running in this server, with local
+# functions (and MCP servers) as tools and config-scoped sessions on disk.
+# Local functions call them via context.agents.run(...); an interactive CLI
+# (`bricks-buttress agent <name> -c <config>`) drives the same agents.
+# See the "Agents" section of README.md.
+# [[agents]]
+# name = "ops-assistant"
+# model = "buttress/ggml-org/gpt-oss-20b-GGUF"  # provider/model-id, split on the FIRST slash
+# system_prompt = "You are an ops automation agent. Use the provided tools."
+# tools = ["host-info"]                # local function names (explicit; no wildcard)
+# max_turns = 30
+# [agents.mcp_servers.example]
+# url = "https://example.com/mcp/"
+# optional = true
+
+# [agents_options]
+# sessions_dir = "./.buttress-agent/sessions"
+# session_max_age = "30d"              # retention; 0 disables
+# session_max_count = 500              # per agent; 0 disables
+# max_depth = 2                        # function -> agent -> function chain cap
+# allow_unauthenticated = false        # serve /agents on an UNBOUND server
+
 [runtime]
 cache_dir = "./.buttress-cache"
 # huggingface_token = "hf_xx"

package/lib/agent/cli.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `bricks-buttress agent` — chat client for configured agents.
+ *
+ * A thin remote client of the /agents endpoints on a RUNNING server: the agent
+ * loop, tools, and sessions all live server-side. Reads the config file only
+ * to find the server port and the local runtime token (written 0600 by the
+ * server at startup), so the same-host flow needs zero extra setup.
+ *
+ * On a real terminal the pi-tui chat UI runs (see tui.ts); pipes/scripts (or
+ * --plain) get a line-based streaming renderer with identical semantics.
+ *
+ *   bricks-buttress agent                    list configured agents
+ *   bricks-buttress agent <name>             chat (new session)
+ *   bricks-buttress agent <name> --session <id>   continue a session
+ *   bricks-buttress agent <name> --fork <id>      fork then chat
+ *   bricks-buttress agent <name> --sessions       list sessions
+ *   Common: -c/--config <path|toml>, --url <server>, --token <token>, --plain
+ */
+export declare const runAgentCommand: (argv: string[]) => Promise<void>;

package/lib/agent/client.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Shared client plumbing for the `bricks-buttress agent` front-ends (line mode
+ * and the pi-tui chat): config/token discovery, authenticated requests, SSE
+ * parsing, and the streaming run call. UI-free on purpose.
+ */
+export type Connection = {
+    baseUrl: string;
+    token: string | null;
+};
+/** Same config-argument semantics as the server CLI: a path or inline TOML. */
+export declare const loadClientConfig: (configArg: string | null) => {
+    config: import("../types").Config;
+    configDir: string;
+    agentsConfig: import("./types").AgentsConfig | null;
+};
+export declare const readRuntimeToken: (file: string) => string | null;
+export declare const request: (connection: Connection, route: string, init?: RequestInit) => Promise<Response>;
+/** Minimal text/event-stream reader: yields { event, data } frames. */
+export declare function readSse(body: ReadableStream<Uint8Array>): AsyncGenerator<{
+    event: string;
+    data: string;
+}, void, unknown>;
+export type RunFrame = {
+    event: string;
+    payload: any;
+};
+export type RunOutcome = {
+    kind: 'result';
+    result: any;
+} | {
+    kind: 'error';
+    message: string;
+    sessionId: string | null;
+} | {
+    kind: 'aborted';
+    sessionId: string | null;
+} | {
+    kind: 'disconnected';
+    sessionId: string | null;
+};
+export type StreamRunBody = {
+    prompt: string;
+    sessionId?: string;
+    fork?: boolean;
+};
+/**
+ * Whether a `--fork` chat has actually forked yet, i.e. whether the flag has
+ * been consumed and later prompts should continue rather than fork again.
+ *
+ * The server only forks once it accepts the run, and announces the new id
+ * (`session` event, or `result.sessionId` on an older server). A run that
+ * failed before that — a rejected token, an unknown agent, a dropped
+ * connection, an immediate Ctrl+C — leaves the client on the SOURCE session, so
+ * the flag has to survive: clearing it would make the user's retry append to
+ * the transcript `--fork` exists to keep untouched.
+ */
+export declare const forkTookEffect: (startedFrom: string | null, sessionId: string | null) => boolean;
+/**
+ * Run a prompt over the streaming endpoint, delivering every parsed frame to
+ * `onFrame` and returning the terminal outcome. Frame handler errors are the
+ * caller's problem — they propagate.
+ */
+export declare const streamRun: (connection: Connection, name: string, body: StreamRunBody, { signal, onFrame }: {
+    signal?: AbortSignal;
+    onFrame: (frame: RunFrame) => void;
+}) => Promise<RunOutcome>;

package/lib/agent/config.d.ts

@@ -0,0 +1,15 @@
+import type { Config } from '../types';
+import type { AgentsConfig } from './types';
+export declare class AgentsConfigError extends Error {
+    constructor(message: string);
+}
+export type ResolveAgentsOptions = {
+    /** Directory relative paths resolve against — the `--config` file's directory. */
+    configDir?: string;
+};
+/**
+ * Resolve `[[agents]]` + `[agents_options]` into the runtime shape. Returns
+ * null when no agents are configured. Invalid definitions throw — a wrong
+ * agent config should stop startup, not silently drop an agent.
+ */
+export declare const resolveAgentsConfig: (config: Config, { configDir }?: ResolveAgentsOptions) => AgentsConfig | null;

package/lib/agent/context.d.ts

@@ -0,0 +1,11 @@
+import type { AgentsFunctionApi, AgentsService } from './types';
+/**
+ * The `context.agents` surface local functions receive. Binds the caller's
+ * abort signal (function deadline / client disconnect cascades into the run),
+ * its emit stream, and its agent-invocation depth.
+ */
+export declare const buildAgentsFunctionApi: (service: AgentsService | null | undefined, { signal, emit, depth, }: {
+    signal: AbortSignal;
+    emit?: (event: string, data?: unknown) => void;
+    depth: number;
+}) => AgentsFunctionApi;

package/lib/agent/loopback.d.ts

@@ -0,0 +1,21 @@
+/**
+ * In-process loopback for agent → buttress model traffic, plus the internal
+ * bearer token that authorizes it (and same-host CLIs) without a cloud-minted
+ * workspace JWT — a bound server only holds the issuer *public* key and
+ * cannot mint its own JWTs.
+ */
+export type ElysiaHandle = (request: Request) => Response | Promise<Response>;
+export declare const generateInternalToken: () => string;
+export declare const makeInternalTokenVerifier: (token: string) => (candidate: string | null | undefined) => boolean;
+/**
+ * Write the internal token where a same-host `bricks-buttress agent` CLI can
+ * read it (0600, next to the sessions dir — config-scoped like everything
+ * else about agents). Rewritten on every startup: the token is ephemeral.
+ */
+export declare const writeRuntimeTokenFile: (file: string, token: string) => void;
+/**
+ * Fetch-shaped dispatcher into the local Elysia app. The request never touches
+ * a socket; the internal token replaces whatever Authorization the client
+ * library synthesized so the shared auth guard accepts it on bound servers.
+ */
+export declare const createLoopbackFetch: (getHandle: () => ElysiaHandle | null, token: string) => typeof fetch;

package/lib/agent/mcp.d.ts

@@ -0,0 +1,23 @@
+import type { AgentMcpServerConfig } from './types';
+export type McpAgentTool = {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Record<string, any>;
+    execute: (toolCallId: string, args: any, signal?: AbortSignal) => Promise<any>;
+    _mcpServer: string;
+    _mcpToolName: string;
+};
+/** `mcp__<server>__<tool>`, hashed into the cap when too long or colliding. */
+export declare const qualifyToolName: (serverName: string, toolName: string, usedNames: Set<string>) => string;
+export type McpManager = {
+    /**
+     * Tools for every configured server of an agent. Fail-closed: a server that
+     * won't connect rejects the whole call unless it is marked `optional`.
+     */
+    toolsFor: (agentName: string, servers: Record<string, AgentMcpServerConfig>) => Promise<McpAgentTool[]>;
+    dispose: () => Promise<void>;
+};
+export declare const createMcpManager: ({ configDir }: {
+    configDir: string;
+}) => McpManager;

package/lib/agent/models.d.ts

@@ -0,0 +1,20 @@
+import { type Model, type MutableModels } from '@earendil-works/pi-ai';
+import type { Config } from '../types';
+import type { AgentDefinition } from './types';
+export declare const BUTTRESS_PROVIDER_ID = "buttress";
+/**
+ * Loopback requests never leave the process: this host name only exists so the
+ * OpenAI client has a syntactically valid base URL to resolve paths against.
+ * The injected fetch dispatches the request straight into the Elysia app.
+ */
+export declare const LOOPBACK_BASE_URL = "http://buttress.internal/oai-compat/v1";
+/** Fetch-shaped dispatcher into the local Elysia app (see loopback.ts). */
+export type LoopbackFetch = typeof fetch;
+/**
+ * A `Models` collection with every pi built-in provider (env-var API keys)
+ * plus the `buttress` pseudo-provider whose models are the configured LLM
+ * generators, streamed over the in-process OpenAI-compat loopback.
+ */
+export declare const buildAgentModels: (config: Config, loopbackFetch: LoopbackFetch) => MutableModels;
+/** Resolve an agent's model reference against the registry, with clear errors. */
+export declare const resolveAgentModel: (models: MutableModels, agent: AgentDefinition) => Model<any>;

package/lib/agent/service.d.ts

@@ -0,0 +1,16 @@
+import type { Config } from '../types';
+import type { FunctionsService } from '../functions';
+import type { FunctionRuntime } from '../functions/types';
+import { type ElysiaHandle } from './loopback';
+import { type AgentsConfig, type AgentsService } from './types';
+export type CreateAgentsServiceOptions = {
+    config: Config;
+    agentsConfig: AgentsConfig;
+    /** Server runtime handed to function tool calls; `agents` is added here. */
+    runtimeBase: Omit<FunctionRuntime, 'agents'>;
+    /** Late-bound: the Elysia app exists only after the service (circular wiring). */
+    getHandle: () => ElysiaHandle | null;
+    /** Late-bound for the same reason (functions service needs the agents service). */
+    getFunctions: () => FunctionsService | null;
+};
+export declare const createAgentsService: ({ config, agentsConfig, runtimeBase, getHandle, getFunctions, }: CreateAgentsServiceOptions) => AgentsService;

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

@@ -0,0 +1,3 @@
+import type { FileSystem } from '@earendil-works/pi-agent-core';
+/** File storage for agent sessions that classifies errors structurally across vm realms. */
+export declare const createSessionFs: (rootDir: string) => FileSystem;

package/lib/agent/sessions.d.ts

@@ -0,0 +1,17 @@
+import type { AgentMessage, Session } 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>>;
+    append: (session: Session<any>, message: AgentMessage) => Promise<string>;
+    close: (session: Session<any>) => Promise<void>;
+    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>;
+    dispose: () => Promise<void>;
+};
+export declare const createAgentSessionStore: (config: AgentsConfig) => AgentSessionStore;