@fugood/buttress-server 2.26.0-beta.16 → 2.26.0-beta.18

package/README.md

@@ -162,6 +162,7 @@ Configuration is loaded from a TOML file passed via `--config` / `-c`. Every top
 | `[autodiscover]`          | LAN UDP / HTTP / mDNS discovery toggles                                                            |
 | `[openai_compat]`         | Enable `/oai-compat/v1/*` — see [Compatibility Endpoints](#compatibility-endpoints-experimental)   |
 | `[anthropic_messages]`    | Enable `/anthropic-messages` — see [Compatibility Endpoints](#compatibility-endpoints-experimental)|
+| `[typesafe_compat]`       | Enable `/typesafe-compat/v1/*` — 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                                          |
@@ -241,7 +242,7 @@ Every generator entry has a `type`, an optional `[generators.backend]` table, an
 
 ```toml
 [[generators]]
-type = "ggml-llm"        # or "ggml-stt" / "ggml-tts" / "mlx-llm"
+type = "ggml-llm"        # or "ggml-stt" / "ggml-tts" / "ggml-decision" / "mlx-llm"
 
 [generators.backend]
 # (see per-type sections below)
@@ -261,7 +262,7 @@ Shared by **all** generator types:
 | `revision`                | string    | Default `"main"`                                                                 |
 | `download`                | boolean   | Pre-download at server startup (default `false`)                                 |
 
-Additional keys honored by **ggml-llm**, **ggml-stt** and **ggml-tts** (mlx-llm gets quantization from the repo itself and does not use these):
+Additional keys honored by **ggml-llm**, **ggml-stt**, **ggml-tts** and **ggml-decision** (mlx-llm gets quantization from the repo itself and does not use these):
 
 | Key                       | Type      | Notes                                                                            |
 | ------------------------- | --------- | -------------------------------------------------------------------------------- |
@@ -493,6 +494,106 @@ vocoder_batch_size = 4096
 
 ---
 
+### `ggml-decision` (typed decisions via `@fugood/llama.node`)
+
+Loads a typed decision model (System One — Julia-1, Laya, Kev, Jevling, lev,
+...) and answers `choice` / `score` / `noul` questions about a state with
+calibrated probabilities: one forward pass per answer, no generated tokens.
+Requests and results follow the TypeSafe `/v1/systemone` API that llama-server
+serves. Clients reach it through the Typed Decision (GGML) generator; local
+functions through `context.buttress.decide`.
+
+The model is checked when its context loads: a GGUF with no decision metadata
+(`<arch>.decision.type`) and no `system_one` template, or one whose decision
+type this build cannot serve, fails the load with the reason. Requests on one
+generator run one at a time.
+
+**Sharing a model with `ggml-llm`** — a model that both generates and decides
+(Jevling, for one) can be configured as both a `ggml-llm` and a
+`ggml-decision`. By default each loads its own context. Set
+`[generators.backend] share_llm_context = true` on the decision entry to run
+its decisions on the LLM's context instead, when the two entries name the same
+weights (same `repo_id`, `revision`, `filename`, `quantization`, `url` and
+`local_path`): the model is then loaded once, with the LLM's config. This
+applies to local functions, the TypeSafe-compatible endpoint and client
+sessions (whose decision runtime options then do not apply).
+
+Sharing trades throughput for memory. A decision takes one of the LLM's
+`n_parallel` slots, and its forward passes run between the LLM's batches, so
+concurrent completions stop generating while it runs (in a CPU test, a
+128-token completion took twice as long beside six decisions; with a separate
+decision context it did not slow down). Results are not affected: the slot's
+sequence and prompt cache are cleared after each decision. Without
+`kv_unified = true` on the LLM a slot holds `n_ctx / n_parallel` tokens, which
+must fit the state plus the questions. The decision loads its own context
+anyway when it sets `rank_pooling` (it needs an embedding context), when its
+projector differs from the LLM's, or when the LLM is embedding or vocab-only.
+The server logs at startup which decision models share.
+
+```toml
+[[generators]]
+type = "ggml-llm"
+[generators.model]
+repo_id = "BricksDisplay/jevling-0.8b-v1-GGUF"
+filename = "jevling-0.8b-v1-q8_0-embf16.gguf"
+[generators.runtime]
+n_ctx = 16384
+
+[[generators]]
+type = "ggml-decision"
+[generators.backend]
+share_llm_context = true
+[generators.model]
+repo_id = "BricksDisplay/jevling-0.8b-v1-GGUF"
+filename = "jevling-0.8b-v1-q8_0-embf16.gguf"
+```
+
+**`[generators.backend]`** — same keys as `ggml-tts` (`variant`,
+`variant_preference`, `gpu_memory_fraction`, `cpu_memory_fraction`).
+
+**`[generators.model]`** — common keys plus:
+
+| Key                       | Type     | Default                          | Notes                                                              |
+| ------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------ |
+| `preferred_quantizations` | string[] | `["q8_0", "q4_k_m", <no-quant>]` | Default fallback chain                                             |
+| `mmproj_repo_id`          | string   | falls back to `repo_id`          | Vision projector repo, for models whose prompt takes images        |
+| `mmproj_filename`         | string   | auto (`*mmproj*`)                | Pin a specific projector artifact                                  |
+| `mmproj_url`              | string   | —                                | Direct projector URL (skips manifest lookup)                       |
+| `mmproj_revision`         | string   | falls back to `revision`         |                                                                    |
+| `mmproj_local_path`       | string   | —                                | Requires `allow_local_file`                                        |
+| `rank_pooling`            | boolean  | `false`                          | `system_one` models with a classification head (`rank_head` readout) |
+| `use_gpu`                 | boolean  | `true`                           | Force-disable GPU even when available                              |
+| `n_gpu_layers`            | number   | `99`                             | Forced to `0` when the GPU is unused                               |
+
+Setting any `mmproj_*` key loads a projector; requests can then pass `images`
+(file paths or data URLs). The projector is ignored, with a warning, when the
+model's prompt has no place for images.
+
+**Runtime extras** — under `[runtime]` for ggml-decision:
+
+| Key                        | Type   | Default         | Notes                                    |
+| -------------------------- | ------ | --------------- | ---------------------------------------- |
+| `n_ctx`                    | number | `4096`          | Must hold the state plus every question  |
+| `n_batch` / `n_ubatch`     | number | `2048` / `512`  |                                          |
+| `max_threads`              | number | auto            | Caps the llama.cpp thread count          |
+| `flash_attn_type`          | string | `auto`          | `auto` / `on` / `off`                    |
+| `context_release_delay_ms` | number | `10000`         | `0` releases the context right away      |
+
+**Example**
+
+```toml
+[[generators]]
+type = "ggml-decision"
+[generators.model]
+repo_id = "ggml-org/Julia-1-GGUF"
+filename = "Julia-1-Q8_0.gguf"
+download = true
+[generators.runtime]
+n_ctx = 4096
+```
+
+---
+
 ### `mlx-llm` (Apple Silicon, Python `mlx-lm` / `mlx-vlm` bridge)
 
 Loads an MLX-format model on Apple Silicon. On first use, the backend creates a virtualenv at `{cache_dir}/mlx-env` and installs `mlx_lm_package`, `mlx_vlm_package`, plus `torch` and `torchvision` (required by some VLM processors). If an existing venv already has `mlx_vlm` and `torch` importable, the install step is skipped. There is no `[generators.backend]` section.
@@ -654,11 +755,40 @@ enabled = true
 | --------------------- | ------------------------------------ |
 | `/oai-compat/v1/*`    | `[openai_compat] enabled = true`     |
 | `/anthropic-messages` | `[anthropic_messages] enabled = true` |
+| `/typesafe-compat/v1/*` | `[typesafe_compat] enabled = true` |
 
 Completion requests may select only LLM models declared in `[[generators]]`. Use each
 endpoint's `GET /v1/models` response for valid model IDs; unknown IDs are rejected before the
 server starts or downloads a generator.
 
+### TypeSafe-compatible System One API
+
+`POST /typesafe-compat/v1/systemone` answers typed decisions in the shape of
+the hosted [TypeSafe API](https://docs.typesafe.ai/api) with this server's
+`ggml-decision` generators. A TypeSafe SDK reaches it with
+`TYPESAFE_BASE_URL=http://<host>:<port>/typesafe-compat`; models are listed at
+`GET /typesafe-compat/v1/models`.
+
+```toml
+[typesafe_compat]
+enabled = true
+# cors_allowed_origins = ["http://localhost:3000"]
+# SDKs send `model = "jev-latest"` unless told otherwise; map such names to a
+# configured decision generator id (as `GET /typesafe-compat/v1/models` lists it)
+[typesafe_compat.models]
+"jev-latest" = "BricksDisplay/jevling-0.8b-v1-GGUF:jevling-0.8b-v1-q8_0-embf16.gguf"
+```
+
+- `model` must be a configured decision generator id or a mapped name. An
+  unknown model gets a 422, never another model: a different model answers
+  with different calibration. The response `model` is the resolved generator id.
+- Auth is the same as the other endpoints: a bound server takes the
+  workspace-access JWT as the Bearer key; an unbound server is open.
+- Validation errors are 422 with a FastAPI-style `detail` list (`loc`, `msg`),
+  as the SDKs print them; other failures are `{ "error": { "message" } }`.
+- `images` (data URLs only) is a Buttress extension for models with a
+  projector. The hosted API is text-only.
+
 ## Local Functions (Experimental)
 
 Local functions are `.ts`/`.js` files you drop into a directory on the server. Each one becomes an MCP tool **and** an HTTP endpoint, so an agent (or any HTTP client) can run server-side work — shelling out to `ffmpeg`, calling this server's own LLM/STT generators — without you writing a service.
@@ -719,6 +849,7 @@ 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 }`. |
+| `buttress.decide({ model?, state, questions, images? })` | Answer typed `choice` / `score` / `noul` questions about `state` with this server's `ggml-decision` generator (TypeSafe `/v1/systemone` shape) → `{ model, answers, usage }`. `answers[id]` is typed from its question. `images` are local paths or data URLs. |
 | `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. |
@@ -894,6 +1025,7 @@ system_prompt_file = "./prompts/ops.md"       # or inline: system_prompt = "..."
 tools = ["get_server_status", "restart_service"]  # local function names (explicit; no wildcard)
 local_devices = false                        # opt in to LAN scan + device DevTools tools
 max_turns = 30                                 # assistant↔tool round-trips per run (default 30)
+# codemode = true                             # opt in: a sandboxed JS tool that calls the other tools
 # max_tokens_per_run = 200000                 # per-run token budget; unset = unlimited
 # temperature = 0.2                           # unrecognized keys pass through to generation
 
@@ -901,6 +1033,9 @@ max_turns = 30                                 # assistant↔tool round-trips pe
 url = "https://api.githubcopilot.com/mcp/"
 # headers = { Authorization = "Bearer ..." }
 # optional = true                             # continue without this server if it won't connect
+# timeout = 60                                # per-request seconds (progress renews it)
+# exposure = "direct"                         # "hidden": unreachable; "codemode": scripts only (needs codemode = true)
+# tool_exposure = { "delete_*" = "hidden" }   # per tool, by exact name or * pattern
 
 [agents_options]                              # optional; defaults shown
 # sessions_dir = "./.buttress-agent/sessions" # relative to this config file
@@ -924,8 +1059,54 @@ 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`.
+(`mcp__github__create_issue`; characters outside `[A-Za-z0-9_]` become `_`);
+MCP servers connect lazily on the first run and fail closed unless marked
+`optional = true`.
+
+**Codemode.** `codemode = true` on an `[[agents]]` entry (default `false`) adds a
+`codemode` tool: the model writes JavaScript that runs in a QuickJS sandbox and
+calls the agent's other tools (`await tools.<name>(args)`), so it can batch calls
+and filter large results before they reach the context. MCP servers of such an
+agent may use `exposure = "codemode"` (or `"deferred"`) to keep their tools out
+of the model's tool list; scripts find them with `searchTools()`.
+`models.classify()` runs pi-ai classifier models with the agent's credentials,
+including this server's decision generators (`buttress/<ggml-decision id>`).
+Small local models may write poor scripts — prefer it with capable models.
+
+**Decisions (System One).** `decision_model` gives an agent a typed-decision
+model: `buttress/<ggml-decision id>` (as `GET /typesafe-compat/v1/models` lists
+it), or a hosted classifier such as `typesafe/jev-latest` (`TYPESAFE_API_KEY`;
+the questions and the state are then sent to TypeSafe). Unset means no
+decisions; it never falls back to the chat model.
+
+```toml
+[[agents]]
+name = "ops-assistant"
+model = "buttress/unsloth/Qwen3.5-4B-GGUF"
+tools = ["host-info"]
+decision_model = "buttress/BricksDisplay/jevling-e2b-v1-GGUF:jevling-e2b-v1-q8_0-embf16.gguf"
+decision_assistance = true   # opt-in tool prefilter (default false)
+# decision_timeout_ms = 500  # prefilter deadline; past it the run keeps every tool
+```
+
+- With a `decision_model`, the agent gets a `decision_evaluate` tool. The model
+  calls it itself with a `state` and `choice` / `score` / `bool` questions, and
+  gets calibrated probabilities back. The tool sees only that state, not the
+  conversation. Its answers are evidence for the model, not permission.
+- With `decision_assistance = true` too, a tool prefilter runs before each run.
+  It asks three yes/no questions about the request: does it need live facts
+  about the system, does it ask for an action (or approve/retry one), and does
+  it point at something not in the conversation. Only when all three are
+  clearly no (each probability < 0.35) does the run go out **without tool
+  definitions**: a shorter prompt for greetings, thanks, explanations or
+  translations. Anything else, including a timeout or an error, keeps every
+  tool. It sends the request, the nearest user/assistant text (≤ 6,000
+  characters) and the tool names; never tool arguments, results or reasoning.
+  The server logs each outcome (`tool prefilter pruned|kept …`).
+- The prefilter never adds or allows a tool; it only withholds them for one
+  run. Small decision models judge it less reliably: jevling-0.8b pruned some
+  live-fact questions that need a tool, jevling-e2b kept them (about 170 ms per
+  run on a GPU). The first run after start may time out while the model loads.
 
 **Local devices.** Set `local_devices = true` on an individual `[[agents]]` entry
 (default `false`) to add just two built-in tools, independently of local functions/MCP:

package/config/function-samples/README.md

@@ -14,6 +14,7 @@ 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 |
+| `classify-ticket.ts` | Typed decisions (`context.buttress.decide`): a choice, a score and yes/no flags with calibrated probabilities | a `ggml-decision` `[[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 |

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/sample.toml

@@ -29,6 +29,15 @@ 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"]
+# [typesafe_compat.models]
+# "jev-latest" = "ggml-org/Julia-1-GGUF:Julia-1-Q8_0.gguf"
+
 # 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
@@ -57,6 +66,8 @@ enabled = true
 # 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
@@ -300,3 +311,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/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/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/mcp.d.ts

@@ -4,12 +4,11 @@ export type McpAgentTool = {
     label: string;
     description: string;
     parameters: Record<string, any>;
-    execute: (toolCallId: string, args: any, signal?: AbortSignal) => Promise<any>;
+    execute: (toolCallId: string, args: any, signal?: AbortSignal, onUpdate?: any) => Promise<any>;
     _mcpServer: string;
     _mcpToolName: string;
+    _mcpExposure: 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

package/lib/agent/models.d.ts

@@ -1,6 +1,7 @@
 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
@@ -13,8 +14,9 @@ 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.
+ * 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) => MutableModels;
+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/sessions.d.ts

@@ -1,17 +1,30 @@
-import type { AgentMessage, Session } from '@earendil-works/pi-agent-core';
+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<Session<any>>;
+    create: (agentName: string) => Promise<AgentSession>;
     /** 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>;
+    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: Session<any>) => Promise<AgentMessage[]>;
+    messages: (session: AgentSession) => Promise<AgentMessage[]>;
     /** Retention sweep across every configured agent scope. */
     sweep: (agentNames: string[]) => Promise<number>;
-    dispose: () => Promise<void>;
 };
 export declare const createAgentSessionStore: (config: AgentsConfig) => AgentSessionStore;
+export {};

package/lib/agent/types.d.ts

@@ -13,7 +13,18 @@ export type AgentMcpServerConfig = {
     env?: Record<string, string>;
     /** Degrade-and-continue when this server fails to connect (default: fail the run). */
     optional?: boolean;
+    /** Per-request timeout in seconds (default 60; progress notifications renew it). */
+    timeout?: number;
+    /**
+     * `direct` (default) declares every tool; `codemode` / `deferred` leave tools
+     * to codemode scripts (agents with `codemode = true` only); `hidden` makes
+     * them unreachable.
+     */
+    exposure?: AgentMcpExposure;
+    /** Per-tool exposure by exact tool name or `*` pattern. */
+    toolExposure?: Record<string, AgentMcpExposure>;
 };
+export type AgentMcpExposure = 'direct' | 'codemode' | 'deferred' | 'hidden';
 export type AgentDefinition = {
     /** Unique agent name — the session scope key. */
     name: string;
@@ -29,12 +40,31 @@ export type AgentDefinition = {
     tools: string[];
     /** Opt-in LAN discovery and device DevTools access (default false). */
     localDevices: boolean;
+    /**
+     * Opt-in `codemode` tool (default false): scripts that call the agent's
+     * tools, including MCP tools with `codemode` / `deferred` exposure.
+     */
+    codemode: boolean;
     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';
+    /**
+     * Classifier model (`provider/model-id`, e.g. `buttress/<decision generator>`
+     * or `typesafe/jev-latest`) for the `decision_evaluate` tool and decision
+     * assistance; null = no decisions (never falls back to the chat model).
+     */
+    decisionModel: {
+        provider: string;
+        modelId: string;
+        modelRef: string;
+    } | null;
+    /** Opt-in tool prefilter before each run (needs `decisionModel`; default false). */
+    decisionAssistance: boolean;
+    /** Prefilter deadline; past it the run keeps every tool. */
+    decisionTimeoutMs: number;
     /** Generation passthrough (temperature, top_p, …). */
     generation: Record<string, unknown>;
 };