@fugood/buttress-server 2.26.0-beta.2 → 2.26.0-beta.21

package/config/function-samples/classify-ticket.ts

@@ -0,0 +1,73 @@
+// Triage a support ticket with this server's typed decision model: which team
+// takes it, how urgent it is, and two yes/no flags — calibrated probabilities
+// from one forward pass per answer, no text generation and no output parsing.
+//
+// Needs a ggml-decision generator in the server config, e.g.:
+//
+//   [[generators]]
+//   type = "ggml-decision"
+//   [generators.model]
+//   repo_id = "ggml-org/Julia-1-GGUF"
+//   filename = "Julia-1-Q8_0.gguf"
+//
+//   curl -X POST http://<host>:<port>/functions/classify-ticket \
+//     -H 'Content-Type: application/json' \
+//     -d '{"message": "I was charged twice and nobody replies. I want my money back today."}'
+//   # → { "result": { "route": "billing", "urgency": 1.53, "urgencyLabel": "Today", "angry": true, … } }
+
+export const meta: ButtressFunctionMeta = {
+  description:
+    'Triage a support ticket: route it to a team, rate its urgency, and flag anger or a refund request',
+  parameters: {
+    type: 'object',
+    properties: {
+      message: { type: 'string', description: 'The customer message' },
+      model: { type: 'string', description: 'Optional decision model override' },
+    },
+    required: ['message'],
+  },
+  timeout: '2m',
+}
+
+type Input = { message: string; model?: string }
+
+const URGENCY_LEVELS = ['Can wait', 'This week', 'Today', 'Right now']
+
+export default async function ({ message, model }: Input, context: ButtressFunctionContext) {
+  const { answers, usage } = await context.buttress.decide({
+    model,
+    state: message,
+    questions: {
+      route: {
+        type: 'choice',
+        instructions: 'Which team should handle this?',
+        criteria: {
+          billing: 'Payments, charges, refunds',
+          shipping: 'Delivery and tracking',
+          technical: 'App or website problems',
+          account: 'Login and profile',
+        },
+      },
+      urgency: { type: 'score', instructions: 'How urgent is this?', criteria: URGENCY_LEVELS },
+      angry: { type: 'noul', instructions: 'The customer is angry' },
+      wants_refund: { type: 'noul', instructions: 'The customer asks for a refund' },
+    },
+  })
+
+  // `answers.route.choice` is typed as 'billing' | 'shipping' | 'technical' | 'account'
+  return {
+    route: answers.route.choice,
+    routeConfidence: answers.route.confidence,
+    // Expected level index (0 = "Can wait"), can fall between two levels
+    urgency: answers.urgency.score,
+    urgencyLabel: URGENCY_LEVELS[Math.round(answers.urgency.score)],
+    angry: answers.angry.noul >= 0.5,
+    wantsRefund: answers.wants_refund.noul >= 0.5,
+    probabilities: {
+      route: answers.route.probabilities,
+      angry: answers.angry.noul,
+      wantsRefund: answers.wants_refund.noul,
+    },
+    inputTokens: usage.input_tokens,
+  }
+}

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

@@ -29,6 +29,13 @@ enabled = true
 # cors_allowed_origins = ["http://localhost:3000", "https://example.com"]
 # cors_allowed_origins = "*"
 
+# TypeSafe-compatible System One API (`/typesafe-compat/v1/systemone`) for the
+# TypeSafe SDKs: TYPESAFE_BASE_URL=http://<host>:<port>/typesafe-compat.
+# Serves the decision generators below.
+# [typesafe_compat]
+# enabled = true
+# cors_allowed_origins = ["http://localhost:3000"]
+
 # Local functions (EXPERIMENTAL): .ts/.js files exposed as MCP tools and HTTP
 # endpoints. Interfaces may change between releases.
 # See the "Local Functions" section of README.md; ready-to-copy examples live
@@ -45,6 +52,31 @@ 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)
+# local_devices = false               # opt in: devices_scan + devtools (inspection AND control)
+# max_turns = 30
+# decision_model = "buttress/<ggml-decision id>"  # adds the decision_evaluate tool
+# decision_assistance = false        # opt in: skip tool definitions on runs that need no tool
+# [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"
@@ -55,6 +87,12 @@ cache_type_k = "q8_0"
 cache_type_v = "q8_0"
 n_threads = 6
 
+# Optional ggml-llm multi-GPU defaults (also supported under [generators.model]).
+# split_mode = "layer"   # none / layer (default) / row / tensor (experimental)
+# tensor_split = [3, 1]  # per-GPU proportions; also accepts "3,1"
+# Tensor mode requires a compatible GPU backend and model architecture.
+# TODO: Expose these Buttress-only options in the LLM (GGML) generator.
+
 # Delay before releasing context when refCount reaches 0 (default: 10000ms)
 # Set to 0 for immediate release
 context_release_delay_ms = 30000
@@ -100,6 +138,7 @@ n_ctx = 12800 # Max: 131072
 
 [[generators]]
 type = "ggml-llm"
+# enabled = false  # keep this entry in the file but skip it at startup (default: true)
 [generators.backend]
 variant_preference = ["cuda", "vulkan", "snapdragon", "default"]
 gpu_memory_fraction = 0.95
@@ -271,3 +310,31 @@ use_gpu = true
 [generators.runtime]
 n_ctx = 8192
 vocoder_batch_size = 4096
+
+# Typed decision generators
+#
+# A typed decision model (System One) answers `choice` / `score` / `noul`
+# questions about a state with calibrated probabilities — one forward pass per
+# answer, no generated tokens. Clients reach it through the Typed Decision
+# (GGML) generator, and local functions through `context.buttress.decide`.
+# Uncomment to enable:
+#
+# [[generators]]
+# type = "ggml-decision"
+# [generators.model]
+# repo_id = "ggml-org/Julia-1-GGUF"
+# filename = "Julia-1-Q8_0.gguf"
+# download = true
+# # Models whose prompt takes images also need a projector:
+# # mmproj_repo_id = "..."
+# # mmproj_filename = "mmproj-....gguf"
+# # system_one models with a classification head (rank_head readout):
+# # rank_pooling = true
+# [generators.runtime]
+# n_ctx = 4096
+#
+# A model that also generates (Jevling, for one) can be configured as both a
+# ggml-llm and a ggml-decision. To load it once, add to the decision entry
+#   [generators.backend]
+#   share_llm_context = true
+# (decisions then compete with completions for the LLM's slots; see README).

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/codemode-worker.d.ts

@@ -0,0 +1 @@
+import '@earendil-works/pi-codemode/worker';

package/lib/agent/codemode.d.ts

@@ -0,0 +1,7 @@
+import type { MutableModels } from '@earendil-works/pi-ai';
+export declare function createAgentCodemodeTool({ tools, declaredNames, getState, models, }: {
+    tools: any[];
+    declaredNames: Set<string>;
+    getState: () => any;
+    models: MutableModels;
+}): Promise<any>;

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/decisions.check.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/agent/decisions.d.ts

@@ -0,0 +1,113 @@
+/**
+ * System One decisions for Buttress agents.
+ *
+ * - Buttress decision generators as pi-ai classifier models (`buttress/<id>`),
+ *   answered in-process. Codemode `models.classify()` and the pieces below go
+ *   through pi-ai, so a hosted classifier (`typesafe/jev-latest`) is
+ *   interchangeable with a local one.
+ * - `decision_evaluate`: a tool the model calls itself with typed questions.
+ * - Tool prefilter (`decision_assistance`): before a run, three yes/no questions
+ *   decide whether its request needs tools at all; a conversational request
+ *   is sent without tool definitions, which shortens the prompt.
+ *
+ * A decision is evidence, never permission: it can only withhold tools for one
+ * run, never grant one, and any failure keeps the full tool set.
+ */
+import type { ClassifierModel, ClassifierResult, MutableModels, ProviderClassifier } from '@earendil-works/pi-ai';
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+import type { Config, DecisionRequest, DecisionResult } from '../types';
+import type { AgentDefinition } from './types';
+export declare const BUTTRESS_DECISION_API = "buttress-decision";
+export type DecideFn = (request: DecisionRequest & {
+    model?: string;
+}) => Promise<DecisionResult>;
+/** One pi-ai classifier model per configured decision generator. */
+export declare const buttressClassifierModels: (config: Config, provider: string, baseUrl: string) => ClassifierModel<string>[];
+/**
+ * Answers classifier requests with this server's decision generators. Never
+ * rejects. A decision cannot be stopped once started, so a caller that gives
+ * up (timeout, abort) leaves it running; until it settles, new requests for
+ * that model fail fast instead of piling up behind it (a cold model load
+ * would otherwise start one more per agent run).
+ */
+export declare const createButtressClassifier: (decide: DecideFn) => ProviderClassifier;
+/** The agent's decision model, or null when it has none. Throws on an unknown one. */
+export declare const resolveDecisionModel: (models: MutableModels, agent: AgentDefinition) => ClassifierModel<any> | null;
+export declare const DECISION_TOOL_NAME = "decision_evaluate";
+/** Typed questions about a state the model supplies. Results never authorize actions. */
+export declare const createDecisionEvaluateTool: (models: MutableModels, model: ClassifierModel<any>) => {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            state: {
+                type: string;
+                description: string;
+            };
+            questions: {
+                type: string;
+                description: string;
+                additionalProperties: {
+                    type: string;
+                    properties: {
+                        type: {
+                            type: string;
+                            enum: string[];
+                        };
+                        instructions: {
+                            type: string;
+                        };
+                        criteria: {};
+                    };
+                    required: string[];
+                };
+            };
+        };
+        required: string[];
+    };
+    execute: (_toolCallId: string, args: any, signal?: AbortSignal) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        details: {};
+    }>;
+};
+/** Every probability must be below this to send a run without tools. */
+export declare const PREFILTER_THRESHOLD = 0.35;
+/**
+ * The prefilter's evidence: the request, the nearest user/assistant exchanges
+ * that fit, and only counts for what is left out. Tool arguments and results,
+ * reasoning and system messages are never sent.
+ */
+export declare const buildPrefilterState: (prompt: string, history: readonly AgentMessage[], toolNames: string[]) => {
+    latestRequest: string;
+    recentConversation: {
+        role: string;
+        text: string;
+    }[];
+    availableTools: string[];
+    omittedContext: {
+        olderConversation: number;
+        toolPayloads: number;
+    };
+};
+export type PrefilterOutcome = {
+    prune: boolean;
+    reason: 'conversational' | 'action-or-uncertain' | 'unavailable' | 'skipped';
+    detail?: string;
+};
+/** Prune only on clear "no" answers to every question; anything else keeps every tool. */
+export declare const interpretPrefilter: (result: ClassifierResult) => PrefilterOutcome;
+/** Decide whether this run's request can go out without tool definitions. */
+export declare const runToolPrefilter: ({ models, model, prompt, history, toolNames, timeoutMs, signal, }: {
+    models: MutableModels;
+    model: ClassifierModel<any>;
+    prompt: string;
+    history: readonly AgentMessage[];
+    toolNames: string[];
+    timeoutMs: number;
+    signal?: AbortSignal;
+}) => Promise<PrefilterOutcome>;

package/lib/agent/device-auth.d.ts

@@ -0,0 +1,3 @@
+import type { WorkspaceState } from '../utils/workspaceState';
+/** Select only the bound workspace's credential; never reuse an inbound Buttress (k=ba) JWT. */
+export declare const resolveDeviceAccessToken: (address: string, port: number, state?: WorkspaceState, signal?: AbortSignal) => Promise<string | undefined>;

package/lib/agent/device-tools.d.ts

@@ -0,0 +1,5 @@
+import type { AgentFunctionTool } from './tools';
+import type { AgentDefinition } from './types';
+import type { WorkspaceState } from '../utils/workspaceState';
+/** Two tools regardless of device count; no remote tool-list expansion or persistent sockets. */
+export declare const buildLocalDeviceTools: (agent: Pick<AgentDefinition, 'localDevices'>, configDir: string, workspaceState?: WorkspaceState) => AgentFunctionTool[];

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,22 @@
+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, onUpdate?: any) => Promise<any>;
+    _mcpServer: string;
+    _mcpToolName: string;
+    _mcpExposure: 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,22 @@
+import { type Model, type MutableModels } from '@earendil-works/pi-ai';
+import type { Config } from '../types';
+import type { AgentDefinition } from './types';
+import { type DecideFn } from './decisions';
+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, and the
+ * configured decision generators as classifier models, answered by `decide`.
+ */
+export declare const buildAgentModels: (config: Config, loopbackFetch: LoopbackFetch, decide: DecideFn) => 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/sessions.d.ts

@@ -0,0 +1,30 @@
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+import type { AgentSessionSummary, AgentsConfig } from './types';
+type SessionMeta = {
+    id: string;
+    createdAt: number;
+    parentSessionId?: string;
+    path: string;
+    modifiedAt: number;
+    /** Written by pi-agent-core's v4 repo; converted on the first append. */
+    legacy: boolean;
+};
+export type AgentSession = {
+    metadata: SessionMeta;
+    /** True once the file is in the current format with no torn tail. */
+    appendable: boolean;
+};
+export type AgentSessionStore = {
+    create: (agentName: string) => Promise<AgentSession>;
+    /** Throws when the id is unknown within the agent's scope. */
+    open: (agentName: string, sessionId: string) => Promise<AgentSession>;
+    fork: (agentName: string, sessionId: string) => Promise<AgentSession>;
+    append: (session: AgentSession, message: AgentMessage) => Promise<void>;
+    list: (agentName: string, limit?: number) => Promise<AgentSessionSummary[]>;
+    /** Reconstruct the pi message history for continuing a session. */
+    messages: (session: AgentSession) => Promise<AgentMessage[]>;
+    /** Retention sweep across every configured agent scope. */
+    sweep: (agentNames: string[]) => Promise<number>;
+};
+export declare const createAgentSessionStore: (config: AgentsConfig) => AgentSessionStore;
+export {};

package/lib/agent/tools.d.ts

@@ -0,0 +1,35 @@
+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. `toolCallId` tells calls of
+     * one tool apart: pi runs the calls of a turn in parallel.
+     */
+    onToolEmit?: (toolName: string, event: string, data: unknown, toolCallId: string) => 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>;