@selesai/code 0.13.40 → 0.14.3

package/docs/codemode.md

@@ -0,0 +1,230 @@
+# Codemode
+
+The `codemode` tool lets the model write a JavaScript script that calls Selesai's other tools and runs non-LLM models, such as classifiers and image models. Only the script's output reaches the model, so a script can run calls in parallel and filter large results before the model sees them. To turn it on, see [Enable codemode](cli.md#enable-codemode).
+
+## Scripts
+
+The tool input is raw JavaScript source, not JSON and not a markdown code fence. It runs as the body of an async function in a QuickJS sandbox, so top-level `await` and `return` work. The sandbox has no Node APIs, file system, network, or timers; scripts reach the outside world only through tools and `models`.
+
+A script may start with an options line:
+
+```js
+// @options: {"max_output_tokens": 2000, "timeout_ms": 60000}
+```
+
+- `max_output_tokens` (default 10000) limits the output. Longer output keeps its start and end, and the full text is written to a temp file whose path is included in the result. A script fails when its output passes 16777216 characters of text and base64 image data or 100000 `text()`, `image()`, and `console` calls; write large data to a file with a tool instead.
+- `timeout_ms` is a hard deadline for the whole script. It is unset by default. Image generation can take minutes, so do not set a short deadline for scripts that generate images.
+
+The result starts with `Script completed` or `Script failed`, the wall time, and the output. Text and image items appear in order, each on its own line. When the output has more than one text item (from `text()` or `return`), each starts with a `==> text N/M <==` line. `console` calls follow in one `<console_output>` block with one line per call. A failed script keeps its partial output, followed by `Script error:` and the error. Tool calls are real: calls made before a failure are not undone. Calls still running when the script ends are cancelled, and unawaited promises are discarded.
+
+## Globals
+
+| Global | Purpose |
+|---|---|
+| `tools.<name>(args)` | Call a tool. See [Call tools](#call-tools). |
+| `text(value)` | Add a text item to the output. Strings are added as is, other values as JSON. |
+| `image(value)` | Add an image to the output: a base64 `data:` URL, an `{ image_url }` object, or an image block `{ type: "image", data, mimeType }` such as those returned by MCP tools and `models.generateImages()`. Remote URLs are not supported. PNG, JPEG, GIF, and WebP are accepted. Each image is also saved to a temp file, and the result names the path before the image. |
+| `console.log(...)` | Add a line to the `<console_output>` block after the other output. Arguments are joined with spaces; `info`, `warn`, `error`, and `debug` do the same. |
+| `return value` | A top-level `return` adds the value like `text()`. |
+| `exit()` | End the script successfully. |
+| `store(key, value)` / `load(key)` | Keep small JSON values across `codemode` calls. See [Store values](#store-values). |
+| `ALL_TOOLS` | Every callable tool as `{ name, description }`, including tools the description does not list. |
+| `searchTools(query, { limit?, namespace? })` | Rank callable tools by relevance (default limit 8). Asks Jev (`jevAdvisory.routes.toolSearch`) when a Token-In account is available, for the first 8 searches of a script; otherwise BM25. Resolves to `{ name, description }[]`. |
+| `describeTool(name)` | Resolves to a tool's description and TypeScript declaration, or `undefined`. |
+| `describeNamespace(name)` | Resolves to `{ name, description?, instructions?, tools }` for a namespace such as an MCP server, or `undefined`. |
+| `models` | List and run non-LLM models. See [Models](#models). |
+
+## Call tools
+
+Every tool the session can call is a method of `tools`, named by its identifier: characters that are not valid in a JavaScript identifier become `_`, so the MCP tool `mcp__dev-radius__search` is `tools.mcp__dev_radius__search`. Each method takes one object with the tool's arguments.
+
+What a call resolves to depends on the tool:
+
+- Tools with an output schema resolve to a structured value. `bash` resolves to `{ output, truncated, full_output_path?, exit_code, wall_time_seconds }`, also for non-zero exit codes. Its `output` is not limited to the 2000 lines or 50KB the model sees: it holds up to 1 MiB, and longer output keeps its first and last 512 KiB around an omission marker, with `truncated` set and the full output in `full_output_path`.
+- MCP tools resolve to their `CallToolResult`, including `isError` and `structuredContent`.
+- `read` resolves to the file's text, or for an image to an image block `{ type: "image", data, mimeType, note }` that `image()` shows. `data` is the base64 image the model would see and `note` the text that goes with it, such as resize hints.
+- Other tools, such as `edit` and `write`, resolve to their text output.
+
+A call that fails, is blocked, or gets invalid arguments rejects with an `Error` that carries the tool's error text. Use `Promise.allSettled()` to keep the results of the calls that succeed.
+
+The `codemode` description lists tools with their TypeScript declarations, grouped by namespace (for example one MCP server). Tools with `deferred` exposure, which includes MCP tools with the default `codemode` exposure, are not listed, so the description stays the same while MCP servers connect. Listed declarations share a budget of 3000 estimated tokens (`codemode.inlineBudget` in [settings](settings.md#tools-and-skills)). Scripts find the other tools with `searchTools()`, `describeTool()`, `describeNamespace()`, or by filtering `ALL_TOOLS`.
+
+While `codemode` is active, `codemode.mode` in [settings](settings.md#tools-and-skills) decides how the other tools are presented. With `on` (default) declared tools stay declared, and their descriptions say how to call them from scripts. With `only` they are hidden from the model and listed in the `codemode` description instead, so the model calls them through scripts. Tool declarations in the `codemode` description, `describeTool()`, and `ALL_TOOLS` carry the tools' prompt guidelines, since the system prompt rules only cover declared tools.
+
+## Store values
+
+`store(key, value)` keeps a JSON value under a string key for later `codemode` calls; storing `undefined` deletes the key. `load(key)` returns the value, or `undefined`. Writes are kept only when the script succeeds: each successful script that stores values appends a `codemode-store` custom entry to the session, so resumed sessions keep the values and each branch sees only the values written on its path.
+
+The store is for small state such as IDs, cursors, or summaries. One value may have at most 262144 characters of JSON and all values together at most 1048576. Do not store image data; show images with `image()`, which also saves them to a temp file.
+
+## Models
+
+`models` reaches the model catalog and runs non-LLM models with the session's credentials: classifiers, which answer typed questions about JSON state and, for some models, images, and image models, which generate images. Chat models are listed but cannot be run from scripts. Which classifier and image models exist is described in [Use classifier models](models.md#use-classifier-models) and [Use image models](models.md#use-image-models).
+
+```ts
+type ModelType = "chat" | "image" | "classifier";
+
+/** A catalog entry. `provider` and `id` identify it; other fields depend on the type. */
+interface ModelInfo {
+  type?: ModelType;
+  provider: string;
+  id: string;
+  name: string;
+  api: string;
+  input: ("text" | "image")[];
+  contextWindow?: number;
+  [key: string]: unknown;
+}
+
+declare const models: {
+  /** Every known model of a type, optionally for one provider. */
+  getModelsOfType(type: ModelType, provider?: string): Promise<ModelInfo[]>;
+  /** Models of a type whose provider has working credentials. */
+  getAvailableOfType(type: ModelType, provider?: string): Promise<ModelInfo[]>;
+  /** One catalog entry, or undefined. */
+  getModelOfType(type: ModelType, provider: string, id: string): Promise<ModelInfo | undefined>;
+  /** Answer `context.questions` about `context.state`; answers are in `result.answers` by question ID. */
+  classify(model: ModelInfo, context: ClassifierContext): Promise<ClassifierResult>;
+  /** Generate images from `context.input` text and image blocks; show `result.output` blocks with image(). Can take minutes. */
+  generateImages(model: ModelInfo, context: ImagesContext): Promise<ImagesResult>;
+};
+```
+
+`classify()` and `generateImages()` use only the `provider` and `id` of `model`, so `{ provider, id }` works as well. They do not throw on provider errors: check `stopReason` and `errorMessage`. At most four such calls run at once per script; more calls wait for a free slot, so `Promise.all()` over many items is fine. Their usage is added to the `codemode` tool result and counts toward the session cost.
+
+TokenIn Jev uses service-only billing: a full breakdown is `usage.cost`, a scalar service charge is `reportedCost`, and counts without recognized pricing are `unpricedUsage`. These fork-specific fields may replace `usage`; zero catalog values do not mean free usage. See [TokenIn classifier billing](models.md#use-classifier-models).
+
+Model IDs differ between providers, for example `typesafe/jev-latest` and `openrouter/typesafe/jev-1.13`. Use `models.getAvailableOfType(type)` to find the IDs that work with the current credentials.
+
+### Classify
+
+```ts
+interface ClassifierContext {
+  /** The data to classify. */
+  state: Record<string, unknown>;
+  /** Images judged together with `state`. Only models whose `input` includes "image" accept them. */
+  images?: { type: "image"; data: string; mimeType: string }[];
+  /** Questions by ID. One call answers all of them. */
+  questions: Record<string, ClassifierQuestion>;
+}
+
+type ClassifierQuestion =
+  /** Pick one label. `criteria` maps each label to what it means. */
+  | { type: "choice"; instructions: string; criteria: Record<string, string> }
+  /** Score on an ordered scale. `criteria` describes each level, lowest first. */
+  | { type: "score"; instructions: string; criteria: string[] }
+  /** Yes or no. */
+  | { type: "bool"; instructions: string; criteria: { true: string; false: string } };
+
+interface ClassifierResult {
+  provider: string;
+  model: string;
+  /** Answers by question ID. */
+  answers: Record<string, ClassifierAnswer>;
+  usage?: ModelUsage;
+  stopReason: "stop" | "error" | "aborted";
+  errorMessage?: string;
+}
+
+type ClassifierAnswer =
+  | { type: "choice"; choice: string; probabilities: Record<string, number>; confidence: number }
+  /** `score` is the expected level index, from 0 to `criteria.length - 1`. */
+  | { type: "score"; score: number; confidence: number }
+  /** Probability of `true`. */
+  | { type: "bool"; probability: number };
+
+/** Token counts and cost in USD, when the service reports them. */
+type ModelUsage = { input: number; output: number; totalTokens: number; cost: { total: number } };
+```
+
+Classify several items by calling `classify()` once per item. This script sorts feedback messages, for example ones a tool returned earlier in the script:
+
+```js
+const jev = await models.getModelOfType("classifier", "typesafe", "jev-latest");
+const results = await Promise.all(
+  messages.map((message) =>
+    models.classify(jev, {
+      state: { message },
+      questions: {
+        sentiment: {
+          type: "choice",
+          instructions: "How does the user feel about the product?",
+          criteria: { positive: "Satisfied or happy", negative: "Unhappy or frustrated", neutral: "Neither" },
+        },
+        urgency: {
+          type: "score",
+          instructions: "How urgently does this need a reply?",
+          criteria: ["no reply needed", "reply this week", "reply today"],
+        },
+      },
+    }),
+  ),
+);
+return results.map((result, i) =>
+  result.stopReason === "stop"
+    ? { message: messages[i], sentiment: result.answers.sentiment.choice, urgency: result.answers.urgency.score }
+    : { message: messages[i], error: result.errorMessage },
+);
+```
+
+Classifiers whose `input` includes `"image"` also judge images. `tools.read()` returns an image file as an image block that `images` accepts. Other classifiers return an error result when `images` is not empty.
+
+```js
+const luna = await models.getModelOfType("classifier", "openai", "gpt-6-luna");
+const photo = await tools.read({ path: "screenshot.png" });
+const result = await models.classify(luna, {
+  state: { task: "Settings page redesign" },
+  images: [photo],
+  questions: {
+    broken: {
+      type: "bool",
+      instructions: "Does the screenshot show a broken layout?",
+      criteria: { true: "Overlapping, cut-off, or misaligned elements", false: "Clean layout" },
+    },
+  },
+});
+```
+
+### Generate images
+
+```ts
+interface ImagesContext {
+  /** The prompt as text blocks, plus image blocks to edit or use as references. */
+  input: (TextBlock | ImageBlock)[];
+}
+
+interface ImagesResult {
+  provider: string;
+  model: string;
+  /** Generated images, and text blocks for models that also return text. */
+  output: (TextBlock | ImageBlock)[];
+  usage?: ModelUsage;
+  stopReason: "stop" | "error" | "aborted";
+  errorMessage?: string;
+}
+
+type TextBlock = { type: "text"; text: string };
+/** `data` is base64. */
+type ImageBlock = { type: "image"; data: string; mimeType: string };
+```
+
+Show generated images with `image(block)`. Do not print `data` with `text()`, `console`, or `return`: it is large and the model cannot read it as text. `image()` also saves each image to a temp file and puts its path in the result, so a later turn can copy or move the file.
+
+```js
+// @options: {"timeout_ms": 300000}
+const painter = await models.getModelOfType("image", "openrouter", "google/gemini-2.5-flash-image");
+const result = await models.generateImages(painter, {
+  input: [{ type: "text", text: "A red fox in the snow, watercolor" }],
+});
+if (result.stopReason !== "stop") return result.errorMessage;
+for (const block of result.output) {
+  if (block.type === "image") image(block);
+  else text(block.text);
+}
+```
+
+## Limits
+
+- A script's VM has 256 MB of memory. Running out throws `InternalError: out of memory`; filter or aggregate large data instead of accumulating it.
+- A script that waits on a promise that can never settle (no tool call pending) fails immediately, since there are no timers.
+- Scripts cannot start other `codemode` scripts.

package/docs/configuration.md

@@ -0,0 +1,47 @@
+# Configuration
+
+Selesai supports user-level and project configuration. User-level configuration lives in the agent directory, which defaults to `~/.selesai/agent`. Project configuration lives in `.selesai` under the working directory and loads after [project trust](security.md#project-trust) is granted. The only exception is `sessionDir`, which Selesai reads before resolving trust so it can locate sessions.
+
+In interactive mode, use `/settings` to change common preferences. For other options, ask Selesai to update the configuration or edit the relevant files directly. Run `/reload` after manually changing settings, keybindings, instructions, or resources.
+
+## Agent directory
+
+The agent directory is shown as `<agent-dir>` below. Set its location with the `SELESAI_CODING_AGENT_DIR` environment variable or the SDK's [`agentDir`](sdk.md) option.
+
+| Path | Responsibility |
+|---|---|
+| `<agent-dir>/settings.json` | User-level [settings](settings.md), including preferences, defaults, resource paths, and Selesai package declarations. |
+| `<agent-dir>/keybindings.json` | Custom terminal UI and application [keybindings](keybindings.md). |
+| `<agent-dir>/mcp.json` | [MCP servers](mcp.md) available in every project. |
+| `<agent-dir>/models.json` | [Compatible endpoints, models, and model overrides](models.md#minimal-example). |
+| `<agent-dir>/auth.json` | Saved API keys and OAuth credentials. |
+| `<agent-dir>/AGENTS.override.md`, `AGENTS.md`, `AGENTS.MD`, `CLAUDE.md`, or `CLAUDE.MD` | User instructions applied across working directories. |
+| `<agent-dir>/SYSTEM.md` | Replaces Selesai’s default system prompt. |
+| `<agent-dir>/APPEND_SYSTEM.md` | Adds instructions to Selesai’s system prompt. |
+| `<agent-dir>/extensions/` | User [extensions](extensions.md). |
+| `<agent-dir>/skills/` | User [skills](skills.md) and supporting files. |
+| `<agent-dir>/prompts/` | User [prompt templates](prompt-templates.md) exposed as slash commands. |
+| `<agent-dir>/themes/` | User [theme](themes.md) files. |
+
+## Project `.selesai` directory
+
+| Path | Responsibility |
+|---|---|
+| `.selesai/settings.json` | Project-level [settings](settings.md), resource paths, and Selesai package declarations. |
+| `.selesai/mcp.json` | Project [MCP servers](mcp.md). |
+| `.selesai/SYSTEM.md` | Replaces the system prompt for the project. |
+| `.selesai/APPEND_SYSTEM.md` | Adds project-specific instructions to the system prompt. |
+| `.selesai/extensions/` | Project extensions. |
+| `.selesai/skills/` | Project skills and supporting files. |
+| `.selesai/prompts/` | Project prompt templates exposed as slash commands. |
+| `.selesai/themes/` | Project theme files. |
+
+For `SYSTEM.md` and `APPEND_SYSTEM.md`, the trusted project file takes precedence over the corresponding agent-directory file. Files with the same name are not combined.
+
+## Context files
+
+Context files are separate from project `.selesai` configuration. Selesai loads them from the agent directory, the working directory, and its parent directories. A context file applies whenever Selesai runs in its directory or anywhere below it.
+
+An `AGENTS.override.md` replaces `AGENTS.md` or `CLAUDE.md` only in the same directory. It does not suppress context files from the agent directory or other directories.
+
+Context-file discovery does not require project trust.

package/docs/environment-variables.md

@@ -80,6 +80,11 @@ When disabled, Selesai removes inherited values for these variables so nested co
 | `PI_CACHE_RETENTION` | Set to `long` for extended provider prompt caching where supported |
 | `PI_SHARE_VIEWER_URL` | Override the base URL used by `/share` |
 | `PI_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
+| `PI_HYPERLINKS` | Override OSC 8 hyperlink detection with `1`, `0`, or `auto` |
+| `PI_PROGRAM_STATUS` | Override OSC 7501 program status detection: `1` always reports, `0` never reports; otherwise reports are sent only after the terminal confirms support. See [Terminal setup](terminal-setup.md#program-status) |
+| `PI_IMAGE_PROTOCOL` | Override inline image detection with `kitty`, `iterm2`, `none`, or `auto` |
+| `PI_TRUE_COLOR` | Override truecolor detection with `1`, `0`, or `auto` |
+| `PI_TUI_ESC_TIMEOUT` | How long to wait after a lone ESC before treating it as Escape, in milliseconds; defaults to `100` over SSH and `10` otherwise. Increase if Alt-key input is misread as Escape |
 | `VISUAL`, `EDITOR` | External editor fallback when `externalEditor` is unset |
 | `HTTP_PROXY`, `HTTPS_PROXY` | Proxy outbound HTTP requests |
 

package/docs/extensions.md

@@ -4,7 +4,7 @@
 
 Extensions are TypeScript modules that extend pi's behavior. They can subscribe to lifecycle events, register custom tools callable by the LLM, add commands, and more.
 
-> **Placement for /reload:** Put extensions in `~/.pi/agent/extensions/` (global) or `.pi/extensions/` (project-local) for auto-discovery. Use `pi -e ./path.ts` only for quick tests. Extensions in auto-discovered locations can be hot-reloaded with `/reload`.
+> **Placement for /reload:** Put extensions in `~/.selesai/agent/extensions/` (global) or `.selesai/extensions/` (project-local) for auto-discovery. Use `selesai -e ./path.ts` only for quick tests. Extensions in auto-discovered locations can be hot-reloaded with `/reload`.
 
 **Key capabilities:**
 - **Custom tools** - Register tools the LLM can call via `pi.registerTool()`
@@ -54,10 +54,10 @@ See [examples/extensions/](../examples/extensions/) for working implementations.
 
 ## Quick Start
 
-Create `~/.pi/agent/extensions/my-extension.ts`:
+Create `~/.selesai/agent/extensions/my-extension.ts`:
 
 ```typescript
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@selesai/code";
 import { Type } from "typebox";
 
 export default function (pi: ExtensionAPI) {
@@ -109,14 +109,14 @@ pi -e ./my-extension.ts
 
 > **Security:** Extensions run with your full system permissions and can execute arbitrary code. Only install from sources you trust.
 
-Extensions are auto-discovered from trusted locations. Project-local `.pi/extensions` entries load only after the project is trusted.
+Extensions are auto-discovered from trusted locations. Project-local `.selesai/extensions` entries load only after the project is trusted.
 
 | Location | Scope |
 |----------|-------|
-| `~/.pi/agent/extensions/*.ts` | Global (all projects) |
-| `~/.pi/agent/extensions/*/index.ts` | Global (subdirectory) |
-| `.pi/extensions/*.ts` | Project-local |
-| `.pi/extensions/*/index.ts` | Project-local (subdirectory) |
+| `~/.selesai/agent/extensions/*.ts` | Global (all projects) |
+| `~/.selesai/agent/extensions/*/index.ts` | Global (subdirectory) |
+| `.selesai/extensions/*.ts` | Project-local |
+| `.selesai/extensions/*/index.ts` | Project-local (subdirectory) |
 
 Additional paths via `settings.json`:
 
@@ -135,13 +135,13 @@ Additional paths via `settings.json`:
 
 To share extensions via npm or git as pi packages, see [packages.md](packages.md).
 
-> **Fork users (selesai):** If you run selesai alongside pi, selesai also reads extensions from `~/.pi/agent/extensions/` as a fallback. When the same extension exists in both dirs, you pick the winner with `extensionHost` in settings. See [Shared Host Extensions](shared-host-extensions.md).
+> **Fork users (selesai):** If you run selesai alongside pi, selesai also reads extensions from `~/.selesai/agent/extensions/` as a fallback. When the same extension exists in both dirs, you pick the winner with `extensionHost` in settings. See [Shared Host Extensions](shared-host-extensions.md).
 
 ## Available Imports
 
 | Package | Purpose |
 |---------|---------|
-| `@earendil-works/pi-coding-agent` | Extension types (`ExtensionAPI`, `ExtensionContext`, events) |
+| `@selesai/code` | Extension types (`ExtensionAPI`, `ExtensionContext`, events) |
 | `typebox` | Schema definitions for tool parameters |
 | `@earendil-works/pi-ai` | AI utilities (`StringEnum` for Google-compatible enums) |
 | `@earendil-works/pi-tui` | TUI components for custom rendering |
@@ -157,7 +157,7 @@ Node.js built-ins (`node:fs`, `node:path`, etc.) are also available.
 An extension exports a default factory function that receives `ExtensionAPI`. The factory can be synchronous or asynchronous:
 
 ```typescript
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@selesai/code";
 
 export default function (pi: ExtensionAPI) {
   // Subscribe to events
@@ -186,7 +186,7 @@ If the factory returns a `Promise`, pi awaits it before continuing startup. That
 Use an async factory for one-time startup work such as fetching remote configuration or dynamically discovering available models.
 
 ```typescript
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@selesai/code";
 
 export default async function (pi: ExtensionAPI) {
   const response = await fetch("http://localhost:1234/v1/models");
@@ -229,14 +229,14 @@ Defer background resource startup until `session_start` or the command/tool/even
 **Single file** - simplest, for small extensions:
 
 ```
-~/.pi/agent/extensions/
+~/.selesai/agent/extensions/
 └── my-extension.ts
 ```
 
 **Directory with index.ts** - for multi-file extensions:
 
 ```
-~/.pi/agent/extensions/
+~/.selesai/agent/extensions/
 └── my-extension/
     ├── index.ts        # Entry point (exports default function)
     ├── tools.ts        # Helper module
@@ -246,7 +246,7 @@ Defer background resource startup until `session_start` or the command/tool/even
 **Package with dependencies** - for extensions that need npm packages:
 
 ```
-~/.pi/agent/extensions/
+~/.selesai/agent/extensions/
 └── my-extension/
     ├── package.json    # Declares dependencies and entry points
     ├── package-lock.json
@@ -621,7 +621,7 @@ pi.on("tool_execution_end", async (event, ctx) => {
 
 #### context
 
-Fired before each LLM call. Modify messages non-destructively. See [Session Format](session-format.md) for message types.
+Fired before each LLM call. `event.messages` is a deep-copied conversation **without system messages**. Handlers can return a replacement list or edit the list in place; Selesai restores prompt and tool state after each handler. Use this for presentation cleanup or conversation-only filtering. See [Session Format](session-format.md) for message types.
 
 ```typescript
 pi.on("context", async (event, ctx) => {
@@ -631,6 +631,18 @@ pi.on("context", async (event, ctx) => {
 });
 ```
 
+#### context_with_system
+
+Runs after all ordinary `context` handlers and prompt/tool restoration. It receives the **full transcript**, including system messages, and its output is sent as returned. The handler owns request-local prompt and tool declarations; keep a system message at index zero. Dropping the leading system message is reported as an extension error, not silently repaired. Use this only when the transformation must control the full transcript.
+
+#### provider_stream_event
+
+Notification-only hook for parsed provider stream events before normalization. The event identifies `provider`, `api`, `model`, and adapter-owned `data`; this is not necessarily raw HTTP bytes or an SSE frame. Treat `data` as read-only. Handlers are awaited in stream order, so slow handlers delay consumption. Events are not persisted; handler errors are reported without replacing the provider response.
+
+#### agent_before_settle
+
+Final actionable boundary before `agent_settled`. Handlers can append validated `custom`, `custom_message`, `context_edit`, or `compaction` entries and request one next model call with `continue: true`, using the exported `BoundaryResult` contract. Guard continuation conditions to avoid loops. `agent_settled` remains final and notification-only; `agent_end` can still be followed by automatic recovery or queued work.
+
 #### before_provider_request
 
 Fired after the provider-specific payload is built, right before the request is sent. Handlers run in extension load order. Returning `undefined` keeps the payload unchanged. Returning any other value replaces the payload for later handlers and for the actual request.
@@ -721,7 +733,7 @@ Behavior guarantees:
 - Return values from `tool_call` only control blocking via `{ block: true, reason?: string }`
 
 ```typescript
-import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
+import { isToolCallEventType } from "@selesai/code";
 
 pi.on("tool_call", async (event, ctx) => {
   // event.toolName - "bash", "read", "write", "edit", etc.
@@ -757,7 +769,7 @@ export type MyToolInput = Static<typeof myToolSchema>;
 Use `isToolCallEventType` with explicit type parameters:
 
 ```typescript
-import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
+import { isToolCallEventType } from "@selesai/code";
 import type { MyToolInput } from "my-extension";
 
 pi.on("tool_call", (event) => {
@@ -781,7 +793,7 @@ In parallel tool mode, `tool_result` and `tool_execution_end` may interleave in
 Use `ctx.signal` for nested async work inside the handler. This lets Esc cancel model calls, `fetch()`, and other abort-aware operations started by the extension.
 
 ```typescript
-import { isBashToolResult } from "@earendil-works/pi-coding-agent";
+import { isBashToolResult } from "@selesai/code";
 
 pi.on("tool_result", async (event, ctx) => {
   // event.toolName, event.toolCallId, event.input
@@ -809,7 +821,7 @@ pi.on("tool_result", async (event, ctx) => {
 Fired when user executes `!` or `!!` commands. **Can intercept.**
 
 ```typescript
-import { createLocalBashOperations } from "@earendil-works/pi-coding-agent";
+import { createLocalBashOperations } from "@selesai/code";
 
 pi.on("user_bash", (event, ctx) => {
   // event.command - the bash command
@@ -908,7 +920,7 @@ Current working directory.
 Use `CONFIG_DIR_NAME` instead of hardcoding `.pi` when constructing project-local config paths. Rebranded distributions can use a different config directory name.
 
 ```typescript
-import { CONFIG_DIR_NAME, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { CONFIG_DIR_NAME, type ExtensionAPI } from "@selesai/code";
 import { join } from "node:path";
 
 export default function (pi: ExtensionAPI) {
@@ -1162,7 +1174,7 @@ Options:
 To discover available sessions, use the static `SessionManager.list()` or `SessionManager.listAll()` methods:
 
 ```typescript
-import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { SessionManager } from "@selesai/code";
 
 pi.registerCommand("switch", {
   description: "Switch to another session",
@@ -1256,7 +1268,7 @@ Tools run with `ExtensionContext`, so they cannot call `ctx.reload()` directly.
 Example tool the LLM can call to trigger reload:
 
 ```typescript
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@selesai/code";
 import { Type } from "typebox";
 
 export default function (pi: ExtensionAPI) {
@@ -1754,7 +1766,7 @@ Pass the real target file path to `withFileMutationQueue()`, not the raw user ar
 Queue the entire mutation window on that target path. That includes read-modify-write logic, not just the final write.
 
 ```typescript
-import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { withFileMutationQueue } from "@selesai/code";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 
@@ -1934,7 +1946,7 @@ Built-in tool implementations:
 Built-in tools support pluggable operations for delegating to remote systems (SSH, containers, etc.):
 
 ```typescript
-import { createReadTool, createBashTool, type ReadOperations } from "@earendil-works/pi-coding-agent";
+import { createReadTool, createBashTool, type ReadOperations } from "@selesai/code";
 
 // Create tool with custom operations
 const remoteRead = createReadTool(cwd, {
@@ -1965,7 +1977,7 @@ For `user_bash`, extensions can reuse pi's local shell backend via `createLocalB
 The bash tool also supports a spawn hook to adjust the command, cwd, or env before execution:
 
 ```typescript
-import { createBashTool } from "@earendil-works/pi-coding-agent";
+import { createBashTool } from "@selesai/code";
 
 const bashTool = createBashTool(cwd, {
   spawnHook: ({ command, cwd, env }) => ({
@@ -2003,7 +2015,7 @@ import {
   formatSize,        // Human-readable size (e.g., "50KB", "1.5MB")
   DEFAULT_MAX_BYTES, // 50KB
   DEFAULT_MAX_LINES, // 2000
-} from "@earendil-works/pi-coding-agent";
+} from "@selesai/code";
 
 async execute(toolCallId, params, signal, onUpdate, ctx) {
   const output = await runCommand();
@@ -2139,7 +2151,7 @@ If a slot intentionally has no visible content, return an empty `Component` such
 Use `keyHint()` to display keybinding hints that respect the active keybinding configuration:
 
 ```typescript
-import { keyHint } from "@earendil-works/pi-coding-agent";
+import { keyHint } from "@selesai/code";
 
 renderResult(result, { expanded }, theme, context) {
   let text = theme.fg("success", "✓ Done");
@@ -2483,7 +2495,7 @@ See [tui.md](tui.md) for the full `OverlayOptions` and `OverlayHandle` API and [
 Replace the main input editor with a custom implementation (vim mode, emacs mode, etc.):
 
 ```typescript
-import { CustomEditor, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { CustomEditor, type ExtensionAPI } from "@selesai/code";
 import { matchesKey } from "@earendil-works/pi-tui";
 
 class VimEditor extends CustomEditor {
@@ -2583,7 +2595,7 @@ theme.strikethrough(text)
 For syntax highlighting in custom tool renderers:
 
 ```typescript
-import { highlightCode, getLanguageFromPath } from "@earendil-works/pi-coding-agent";
+import { highlightCode, getLanguageFromPath } from "@selesai/code";
 
 // Highlight code with explicit language
 const highlighted = highlightCode("const x = 1;", "typescript", theme);
@@ -2662,6 +2674,7 @@ All examples in [examples/extensions/](../examples/extensions/).
 | `modal-editor.ts` | Vim-style modal editor | `setEditorComponent`, `CustomEditor` |
 | `rainbow-editor.ts` | Custom editor styling | `setEditorComponent` |
 | `widget-placement.ts` | Widget above/below editor | `setWidget` |
+| `tokenin-usage-widget.ts` | Poll Token-In balance/usage and keep a widget updated | `getProviderAuth`, `getProvider`, `setWidget`, session events |
 | `overlay-test.ts` | Overlay components | `ui.custom` with overlay options |
 | `overlay-qa-tests.ts` | Comprehensive overlay tests | `ui.custom`, all overlay options |
 | `notify.ts` | Simple notifications | `ui.notify` |
@@ -2694,3 +2707,67 @@ All examples in [examples/extensions/](../examples/extensions/).
 | `inline-bash.ts` | Inline bash in tool calls | `on("tool_call")` |
 | `bash-spawn-hook.ts` | Adjust bash command, cwd, and env before execution | `createBashTool`, `spawnHook` |
 | `with-deps/` | Extension with npm dependencies | Package structure with `package.json` |
+
+
+## v1.0.4 Tool and MCP Contracts
+
+### Tool exposure
+
+`exposure` controls how the model reaches a tool. "Callable" means callable from other tools through `ctx.executeTool()` (`ctx.tools`), as the `codemode` tool's scripts do:
+
+- `direct` (default): declared to the model while active, and callable while active.
+- `model-only`: declared to the model while active, never callable. Use it for tools that orchestrate other tools or ask the user.
+- `codemode`: callable whenever registered, and listed by the `codemode` tool. Not declared to the model unless activated explicitly.
+- `deferred`: like `codemode`, but codemode tools do not list it; `tool_search` can find and activate it.
+- `hidden`: registered but unreachable. Re-register a tool with `exposure: "hidden"` to withdraw it, since tools cannot be unregistered.
+
+`namespace: { name, description, instructions }` groups related tools, as MCP servers do. Codemode tools list a namespace under one heading with its `description`. `instructions` holds longer usage guidance; it is not listed, and codemode scripts read it with `describeNamespace(name)`.
+
+Registering a `direct` or `model-only` tool activates it by default (`defaultActive: false` opts out); the other exposures are not activated on registration. The active set (`pi.getActiveTools()`, `pi.setActiveTools()`) is the set of tools declared to the model. `pi.getAllTools()` reports each tool's `exposure`, `namespace`, and `annotations`.
+
+`annotations` are hints about what a tool does, with the meaning of MCP tool annotations: `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`. MCP tools carry the hints their server declares. Missing hints take the MCP defaults: a tool is not read-only, and may be destructive and reach an open world. The hints are not verified, but a permission extension can use them to decide which calls to confirm. This confirms the calls Codex asks approval for:
+
+```typescript
+pi.on("tool_call", async (event, ctx) => {
+  const hints = pi.getAllTools().find((tool) => tool.name === event.toolName)?.annotations;
+  const needsApproval =
+    hints?.destructiveHint === true ||
+    (!hints?.readOnlyHint && ((hints?.destructiveHint ?? true) || (hints?.openWorldHint ?? true)));
+  if (needsApproval && !(await ctx.ui.confirm("Allow tool call?", event.toolName))) {
+    return { block: true, reason: `${event.toolName} was not approved` };
+  }
+});
+```
+
+A tool that orchestrates other tools can adjust what the model sees while it is active with `prepareLoadout(loadout)`. It runs whenever the active tools change and receives the declared tools, the callable tools, and every registered tool with its exposure, namespace, and prompt guidelines. It returns replacement `descriptions` for declared tools (including its own) and `hiddenDeclarations`: active tools whose declarations requests leave out while they stay active and callable. The default system prompt leaves hidden tools out of its tool list and rules, and names no tool in the skills hint when the file reader is hidden, so the orchestrating tool should present their guidelines itself. `codemode` uses only this hook, `exposure`, and `ctx.executeTool()`, so another tool can implement the same behavior under a different name.
+
+### Activate tools dynamically
+
+Register every tool first, keep optional tools inactive, and use `pi.setActiveTools()` from a loader tool to select the desired active tools. Names must already be registered; unknown names are ignored.
+
+Selesai records the initial prompt and tool set in the transcript's first system message, then appends tool and prompt changes before the next model request. Providers that cannot represent the transition receive a complete transcript checkpoint, which can invalidate the cached prefix.
+
+### Tool rendering
+
+A tool's `renderCall` and `renderResult` draw its calls in the interactive transcript and in HTML exports. `pi.registerToolRenderer((toolName, next) => renderers)` chooses renderers for calls to any tool, including tools that are not registered yet, such as MCP tools in a resumed session before their server connected. `next()` returns what the remaining resolvers (in extension load order), then the registered tool, would use, so `next() ?? mine` only fills in.
+
+### MCP servers
+
+`pi.registerMcpServer(name, config)` adds an MCP server for the current session. `config` has the shape of an `mcpServers` entry in [`mcp.json`](mcp.md): `command`, `args`, `env`, and `cwd` for stdio servers, `url`, `headers`, and `oauth` for HTTP servers, plus `exposure`, `toolExposure`, `description`, `enabled`, and `timeout`.
+
+```typescript
+pi.registerMcpServer("jira", { url: "https://mcp.example.com/jira", exposure: "codemode" });
+pi.unregisterMcpServer("jira");
+```
+
+Servers registered while the extension loads connect when the session starts, together with the `mcp.json` servers; servers registered later connect right away, and `pi.unregisterMcpServer()` closes the connection and makes the server's tools unreachable. Registrations are not saved: register again on every load, for example based on the extension's own settings. A server in `mcp.json` with the same name takes precedence, and `/mcp` shows the override. Registering the same name again replaces the extension's earlier registration; names registered by another extension, invalid names, and invalid configs throw.
+
+The built-in MCP support connects registered servers. When nothing does, because another extension replaced it (see [MCP](mcp.md#replace-the-built-in-mcp-support)), each registration is reported as an extension error. Other MCP extensions can connect registered servers too: read them with `pi.getMcpServers()` on `session_start` and handle the `mcp_servers_change` event for later changes.
+
+### Structured outputs and nested calls
+
+Declare `outputSchema` and return matching `structuredContent` for programmatic results. The model still receives `content`; codemode receives the structured value. A result may carry `isError: true` without throwing. Redaction handlers must also replace structured data; replacing only `content` drops stale `structuredContent`.
+
+Inside a tool, `ctx.executeTool(name, args, { signal, onUpdate })` runs nested calls through argument validation, hooks, and permission checks. Its outcomes carry `isError` rather than rejecting for ordinary tool failures. Nested execution events carry `parentToolCallId`; results do not create separate transcript tool turns. Nested usage is rolled into the calling tool, so report only the caller’s own usage. `ctx.tools` lists callable tools, not necessarily model-declared tools.
+
+The old core `discovery` metadata is retired. Use exposure, namespace, annotations, and upstream codemode/tool search; Selesai has no separate capability-gateway selection or reset layer. Classifier and image operations are available through `ctx.modelRegistry`; see [Models](models.md#use-classifier-models).