@fugood/buttress-server 2.26.0-beta.3 → 2.26.0-beta.5

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]`
@@ -850,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/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,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[]>;
+};