@selesai/code 0.13.39 → 0.14.0

package/docs/json.md

@@ -1,7 +1,7 @@
 # JSON Event Stream Mode
 
 ```bash
-pi --mode json "Your prompt"
+selesai --mode json "Your prompt"
 ```
 
 Outputs all session events as JSON lines to stdout. Useful for integrating pi into other tools or custom UIs.
@@ -39,7 +39,7 @@ type AgentEvent =
   // Tool execution
   | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any }
   | { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any }
-  | { type: "tool_execution_end"; toolCallId: string; toolName: string; result: any; isError: boolean };
+  | { type: "tool_execution_end"; toolCallId: string; toolName: string; result: any; isError: boolean; durationMs?: number };
 ```
 
 ## Message Types
@@ -55,6 +55,10 @@ Extended messages from [`packages/coding-agent/src/core/messages.ts`](https://gi
 - `BranchSummaryMessage` (line 55)
 - `CompactionSummaryMessage` (line 62)
 
+## Wire streaming events
+
+JSON and RPC mode emit `JsonAgentSessionEvent`, a delta-only projection of SDK events. `message_update` includes cumulative `usage` and `assistantMessageEvent`, but omits the cumulative `message` and nested `partial` snapshots. Reconstruct text/thinking from deltas and use `message_end.message` as the authoritative final message. `toolcall_start` includes `contentIndex`, `id`, and `toolName`. Read stdout continuously; backpressure can pause generation.
+
 ## Output Format
 
 Each line is a JSON object. The first line is the session header:
@@ -69,7 +73,7 @@ Followed by events as they occur:
 {"type":"agent_start"}
 {"type":"turn_start"}
 {"type":"message_start","message":{"role":"assistant","content":[],...}}
-{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_delta","delta":"Hello",...}}
+{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_delta","delta":"Hello",...}}
 {"type":"message_end","message":{...}}
 {"type":"turn_end","message":{...},"toolResults":[]}
 {"type":"agent_end","messages":[...]}
@@ -78,5 +82,5 @@ Followed by events as they occur:
 ## Example
 
 ```bash
-pi --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'
+selesai --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'
 ```

package/docs/keybindings.md

@@ -2,11 +2,11 @@
 
 All keyboard shortcuts can be customized via `~/.selesai/agent/keybindings.json`. Each action can be bound to one or more keys.
 
-The config file uses the same namespaced keybinding ids that pi uses internally and that extension authors use in `keyHint()` and injected `keybindings` managers.
+The config file uses the same namespaced keybinding ids that Selesai uses internally and that extension authors use in `keyHint()` and injected `keybindings` managers.
 
 Older configs using pre-namespaced ids such as `cursorUp` or `expandTools` are migrated automatically to the namespaced ids on startup.
 
-After editing `keybindings.json`, run `/reload` in pi to apply the changes without restarting the session.
+After editing `keybindings.json`, run `/reload` in Selesai to apply the changes without restarting the session.
 
 ## Key Format
 
@@ -84,12 +84,12 @@ Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `super+
 
 These actions apply when interactive mode uses fullscreen TUI mode (the Selesai default; `tuiMode: "fullscreen"` in settings or `--tui-mode fullscreen`) and target the primary transcript scroll region. Two-finger trackpad and mouse-wheel input scroll the region under the pointer, falling back to the transcript over the fixed editor/status/footer dock. Clicking an OSC 8 hyperlink opens it in the default handler. Dragging with the primary mouse button selects text and copies it to the clipboard; holding at the transcript's top or bottom edge auto-scrolls into off-screen content.
 
-Fullscreen transcript bindings take precedence over editor bindings. The default unmodified navigation keys therefore control the transcript in fullscreen mode, while their `ctrl` variants continue to control the editor. Outside fullscreen mode, both variants control the editor.
+Fullscreen transcript bindings take precedence over editor bindings. `Home` and `End` now move the editor cursor; `Ctrl+Home` and `Ctrl+End` scroll the fullscreen transcript. Page keys still scroll the transcript, while their `ctrl` variants control the editor.
 
-| Key | Default mode | Fullscreen mode |
+| Key | Regular mode | Fullscreen mode |
 |-----|--------------|-----------------|
-| `home`, `end` | Editor | Transcript |
-| `ctrl+home`, `ctrl+end` | Editor | Editor |
+| `home`, `end` | Editor | Editor |
+| `ctrl+home`, `ctrl+end` | No default editor binding | Transcript |
 | `pageUp`, `pageDown` | Editor | Transcript |
 | `ctrl+pageUp`, `ctrl+pageDown` | Editor | Editor |
 
@@ -101,10 +101,10 @@ This routing remains configurable through the ordinary action bindings. For exam
 | `tui.altScreen.pageDown` | `pageDown` | Scroll the transcript down by one page |
 | `tui.altScreen.halfPageUp` | *(none)* | Scroll the transcript up by half a page |
 | `tui.altScreen.halfPageDown` | *(none)* | Scroll the transcript down by half a page |
-| `tui.altScreen.previousPrompt` | `ctrl+shift+up` | Jump to the previous marked message |
-| `tui.altScreen.nextPrompt` | `ctrl+shift+down` | Jump to the next marked message |
-| `tui.altScreen.top` | `home` | Scroll to the beginning of the transcript |
-| `tui.altScreen.bottom` | `end` | Scroll to the transcript end and follow new output |
+| `tui.altScreen.previousPrompt` | `ctrl+shift+up`, `ctrl+up` (`ctrl+up` on Windows/WSL) | Jump to the previous marked message |
+| `tui.altScreen.nextPrompt` | `ctrl+shift+down`, `ctrl+down` (`ctrl+down` on Windows/WSL) | Jump to the next marked message |
+| `tui.altScreen.top` | `ctrl+home` | Scroll to the beginning of the transcript |
+| `tui.altScreen.bottom` | `ctrl+end` | Scroll to the transcript end and follow new output |
 
 ### Application
 

package/docs/mcp.md

@@ -0,0 +1,262 @@
+# MCP Servers
+
+Selesai connects to [Model Context Protocol](https://modelcontextprotocol.io) servers over stdio or streamable HTTP and makes their tools and resources available to the model.
+
+## Quick setup
+
+Add a local stdio server, check the connection, then start Selesai:
+
+```bash
+selesai mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
+selesai mcp list
+selesai
+```
+
+For a remote server:
+
+```bash
+selesai mcp add docs --url https://example.com/mcp --bearer-token-env-var DOCS_TOKEN
+selesai mcp list
+```
+
+These commands add user-level servers by default. Add `--local` or `-l` to write the project configuration instead:
+
+```bash
+selesai mcp add -l tools --env API_KEY='${TOOLS_KEY}' -- uvx tools-mcp
+```
+
+Use `/mcp` inside an interactive session to inspect connections, sign in, reconnect, change exposure, or enable and disable servers. Run `/reload` after adding, removing, or changing a server outside the session.
+
+## Configure servers
+
+Selesai reads user-level servers from `~/.selesai/agent/mcp.json` and project servers from `.selesai/mcp.json`. Project configuration is read only after [project trust](security.md#project-trust) is granted. A project entry replaces a user-level entry with the same name.
+
+A project entry without `command`, `url`, or `type` overrides only `enabled`, `exposure`, and `toolExposure` of the user-level server with the same name and keeps the rest, including `env`, `headers`, and `auth`. For example, this turns off a user-level server in one project:
+
+```json
+{
+  "mcpServers": {
+    "internal-tools": { "enabled": false }
+  }
+}
+```
+
+The format matches other MCP clients:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
+    },
+    "docs": {
+      "url": "https://example.com/mcp",
+      "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" },
+      "description": "Search and read the product documentation"
+    }
+  }
+}
+```
+
+Stdio servers use `command`, `args`, `env`, and `cwd`. Relative `cwd` values resolve against the session directory. A leading `~/` in `command`, an argument, or `cwd` names the home directory.
+
+HTTP servers use `url`, `headers`, and `oauth` (see [Authenticate with OAuth](#authenticate-with-oauth)). The legacy SSE transport is not supported.
+
+Both server types support:
+
+- `timeout`: per-request timeout in seconds (default 60). Progress notifications reset it.
+- `enabled: false`: keep the entry without connecting to it.
+- `exposure` and `toolExposure`: control how tools reach the model (see [Control tool exposure](#control-tool-exposure)).
+- `description`: what the server offers, in a sentence. It lists the server in the system prompt (see [Control tool exposure](#control-tool-exposure)), tool search ranks the server's tools by it, and codemode's `describeNamespace()` returns it. Without it, the first line of the server instructions is used once the server connects.
+
+Keep personal servers and servers with credentials in the user-level file. Use the project file only for servers the project requires, and only in trusted projects.
+
+### Configuration rules
+
+- Server names may contain only letters, digits, `_`, and `-`. Tools are named `mcp__<server>__<tool>`, with every character other than letters, digits, and `_` replaced by `_`; tools of a server whose names then collide all get a hash suffix. Server names that differ only in `-` and `_` count as the same server: a second one is rejected, and a `mcp.json` server overrides a registered one.
+- `type` is optional. A `command` selects stdio and a `url` selects streamable HTTP. When present, `type` must be `stdio`, `http`, or `streamable-http`.
+- `sse` is rejected. Servers that document an SSE endpoint often also provide streamable HTTP, commonly at `/mcp` instead of `/sse`.
+- `command` is one executable and `args` contains its arguments. It is not a shell command string.
+- `env` and `headers` values can use environment variables such as `${GITHUB_TOKEN}`. They can also run a command with `!command`, but the command must make up the whole value, for example `"Authorization": "!echo Bearer $(gh auth token)"`.
+- Invalid entries are reported and skipped without preventing other servers from connecting.
+
+`selesai mcp add` and `selesai mcp remove` cover common changes from a shell. See [MCP commands](cli.md#mcp-commands) for their options.
+
+### Inspect or change a server
+
+`/mcp` lists configured servers with their state, tool count, exposure, and configuration source. Servers that need attention appear first. Select a server to inspect its tools and connection details, reconnect, sign in or out, change exposure, or enable and disable it.
+
+Exposure and enabled-state changes are saved to the file that defines the server without replacing unrelated content. In a trusted project, "Enable in this project" and "Disable in this project" add a project override for a user-level server; later changes to that server are saved to the override. Disabled servers remain listed. Outside the interactive TUI, `/mcp` prints server status; `/mcp login <server>`, `/mcp logout <server>`, and `/mcp reconnect <server>` perform those actions directly.
+
+Shell commands work without a session: `selesai mcp add`, `selesai mcp remove`, `selesai mcp list`, `selesai mcp login`, and `selesai mcp logout`. Shell commands do not load extensions.
+
+### Diagnose connection problems
+
+Run `selesai mcp list` to connect to every enabled server and print its state, tools, and errors. It exits with status 1 when an entry is invalid or an enabled server is not connected. `/mcp` shows the full connection error and the tail of stderr from a failed stdio server.
+
+Selesai reports configuration errors, failed connections, and required sign-ins once after startup. Server logging notifications are appended to `~/.selesai/agent/mcp.log` as `<time> [<server>] <level> <logger>: <message>`. The file moves to `mcp.log.1` after it grows past 5 MB.
+
+Selesai connects every enabled server in the background when a session starts. A server's tools appear once it connects; the `codemode` description does not list them, so it does not change when servers connect. The first prompt waits up to 10 seconds only for servers with `direct` tools, which must be declared in its request. Other servers are waited for when they are needed: a codemode script waits for the servers it names (`mcp__<server>`) and, when it calls `searchTools()` or reads `ALL_TOOLS`, for all of them; `tool_search` and the resource tools also wait for all of them. HTTP network errors and transient statuses (408, 429, and 5xx) are retried twice. A dropped connection is shown as disconnected and reconnects on the next call. When a server announces a changed tool list, new tools are added and withdrawn tools become unreachable.
+
+Stopping a stdio server closes its stdin, sends SIGTERM, then sends SIGKILL to its process group. This also stops servers launched through wrappers such as `npx` or `uvx`.
+
+## Migrate configuration from another client
+
+Move the converted entry under `mcpServers` in `mcp.json`, then run `selesai mcp list` to validate it.
+
+| Client | Conversion |
+|---|---|
+| Claude Desktop, Claude Code, or Cursor | Copy the existing `mcpServers` entry. |
+| VS Code | Move an entry from the top-level `servers` object and replace `${input:...}` prompts with `${NAME}` environment variables. |
+| Codex | Convert `[mcp_servers.<name>]` TOML fields such as `command`, `args`, `env`, and `url` to JSON. |
+| OpenCode | Convert `"type": "local"` to a stdio entry, split its `command` array into `command` and `args`, rename `environment` to `env`, and replace `{env:NAME}` with `${NAME}`. Convert `"type": "remote"` to a URL entry. |
+
+## Authenticate with OAuth
+
+Remote servers that use OAuth, such as Sentry, need no credentials in `mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "sentry": { "url": "https://mcp.sentry.dev/mcp" }
+  }
+}
+```
+
+When the server rejects an unauthenticated connection, `/mcp` shows that it needs sign-in. Select "Sign in", run `/mcp login sentry`, or run `selesai mcp login sentry`. Selesai opens the authorization page and waits for approval. If the browser runs on another machine, such as over SSH, paste its redirected URL into the sign-in screen. A running session uses the new credentials on its next turn.
+
+Selesai registers itself with the authorization server, stores tokens in `~/.selesai/agent/mcp-auth.json`, and refreshes access tokens when they expire or the server rejects them. If a server later requests additional scope, Selesai asks for sign-in again. Signing out deletes the stored credentials.
+
+Credentials belong to a server name and URL. Servers with the same URL under different names, such as one per account, sign in separately; servers with the same name and URL in different `mcp.json` files share one sign-in.
+
+OAuth applies to HTTP servers without an `Authorization` header. For a server that does not support dynamic client registration, configure a registered client:
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "url": "https://mcp.example.com/mcp",
+      "oauth": { "clientId": "my-client", "clientSecret": "${EXAMPLE_SECRET}", "callbackPort": 8765 }
+    }
+  }
+}
+```
+
+The redirect URI must match the registered URI. `callbackPort` uses `http://127.0.0.1:<port>/callback`. To use another URI, set `callbackUrl`; it must use HTTP on `localhost`, `127.0.0.1`, or `[::1]`. Selesai sends it exactly as written. When `callbackUrl` omits a port, Selesai uses `callbackPort` or a free port and adds it to the URI, as allowed for loopback redirects by RFC 8252. `clientSecret` is optional and can use an environment variable or command.
+
+Set `scope` to a space-separated list for servers that do not advertise their required scopes. Otherwise, Selesai requests the advertised scopes. Later scope requests are added to the configured value.
+
+Selesai registers as `selesai`. Some servers only accept registrations from known clients. Set `clientName` to send another name:
+
+```json
+{
+  "mcpServers": {
+    "figma": { "url": "https://mcp.figma.com/mcp", "oauth": { "clientName": "Claude Code" } }
+  }
+}
+```
+
+The name is only sent when Selesai registers a client. To register again under a new name, sign out first.
+
+Client ID Metadata Document (`clientRegistration: "cimd"`) registration is disabled in Selesai. No Selesai CIMD hosting contract is available. Use dynamic client registration (the default, or `"dcr"`) or a pre-registered `clientId`; unsupported modes are rejected before OAuth side effects.
+
+Selesai finds the authorization server through the server's protected resource metadata (RFC 9728) and checks that the authorization server's metadata names the expected issuer (RFC 8414). Some servers advertise the wrong authorization server or none, so sign-in opens a page that does not exist. Set `authServerMetadataUrl` to the metadata document of the right authorization server:
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "url": "https://mcp.example.com/mcp",
+      "oauth": { "authServerMetadataUrl": "https://example.okta.com/.well-known/openid-configuration" }
+    }
+  }
+}
+```
+
+Selesai uses that document instead of discovery and trusts it as configured, so only point it at a document you trust. The URL must use HTTPS, except on `localhost`, `127.0.0.1`, or `[::1]`.
+
+## Control tool exposure
+
+Each server tool is registered as `mcp__<server>__<tool>`. The server's `exposure` determines how the model reaches it:
+
+| Exposure | Behavior | Typical use |
+|---|---|---|
+| `codemode` (default) | Callable from [`codemode`](cli.md#tools) scripts, but neither declared to the model nor listed in the codemode description. Scripts find tools with `searchTools()`, `describeTool()`, or `ALL_TOOLS`. | General MCP servers, especially when scripts should combine or filter calls. |
+| `deferred` | Not declared until [`tool_search`](cli.md#tools) loads a match for the next model call. | Large servers whose tools should be called directly after discovery. |
+| `direct` | Declared to the model like a built-in tool and also callable from codemode. | Small, frequently used tool sets. |
+| `hidden` | Registered but unreachable. | Servers or tools that should remain unavailable. |
+
+`codemode-deferred` is accepted as an alias for `codemode`.
+
+Servers with `codemode` or `deferred` tools are listed in the `mcp_servers` section of the system prompt, with how their tools are reached and one line from the configured `description` or, once connected, from the server instructions. Selesai updates the section when a prompt starts, after waiting for servers with `direct` tools. When it changed, for example because a server connected and its summary became available, Selesai appends the new section to the conversation instead of changing tool declarations, so earlier messages stay cached. `describeNamespace()` and the `namespace` option of `searchTools()` accept `mcp__dev-radius`, `mcp__dev_radius`, `dev-radius`, or `dev_radius`.
+
+Selesai activates `codemode` when a server with `codemode` exposure connects. It activates `tool_search` for a server with `deferred` exposure. To make the model see a tool without searching, give it `direct` exposure with `toolExposure`.
+
+`toolExposure` overrides the server exposure for individual tools. Keys are exact server tool names or patterns where `*` matches any characters. Exact names win over patterns; among patterns, the first match wins. A server with `hidden` exposure can expose only selected tools:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "url": "https://api.githubcopilot.com/mcp/",
+      "exposure": "deferred",
+      "toolExposure": {
+        "search_code": "direct",
+        "get_*": "codemode",
+        "delete_*": "hidden"
+      }
+    }
+  }
+}
+```
+
+`selesai mcp list` marks tools whose exposure differs from their server. The Tools view in `/mcp` also shows the effective exposure.
+
+Tools with `codemode` or `deferred` exposure can be reached through either indirect mechanism: codemode scripts can call them, and `tool_search` can load them. Codemode calls do not depend on the active tool set, so they remain available after `/tree`, resume, and fork. Tools loaded by `tool_search` are recorded in the transcript and remain declared on that branch.
+
+`--tools` does not remove MCP tools unless one of its entries starts with `mcp__`; `selesai --tools read,codemode,'mcp__radius__*'` keeps only the tools of `radius`. `--exclude-tools` accepts the same patterns, and `--no-mcp` disables MCP for one run (see [Tools](cli.md#mcp-tools)).
+
+Selesai factory settings already add `codemode` without MCP servers. To retain this in custom settings, add `"defaultTools": ["+codemode"]` to [settings](settings.md#tools-and-skills). To prevent automatic codemode activation, set `"autoEnableCodemode": false` beside `mcpServers`. A project value overrides the user-level value. Selesai warns once when neither `codemode` nor `tool_search` is active and non-direct tools cannot be called.
+
+Text results over 20 KB reach the model with their middle removed around a `…N chars truncated…` marker. The full text is saved to a temporary file named in the result. Codemode scripts receive the complete result and can reduce it before returning output to the model.
+
+Codemode scripts receive the complete MCP `CallToolResult`, including `content`, `structuredContent`, and `isError`. A result with `isError` resolves inside scripts but is reported as an error for direct calls. `image(result.content[0])` forwards an image block. Server instructions are not part of any tool description; scripts read them with `describeNamespace("mcp__<server>")`, which also returns the server's tool names.
+
+## Use resources
+
+When a connected server offers [resources](https://modelcontextprotocol.io/specification/2025-11-25/server/resources), Selesai adds the resource tools used by Codex and OpenCode:
+
+- `list_mcp_resources` lists resources as JSON: `{ server?, resources: [{ server, uri, name, ... }], nextCursor? }`. With `server`, it lists one page; `cursor` continues with the next page. Without `server`, it lists every resource from every server.
+- `list_mcp_resource_templates` lists URI templates for resources the servers do not list directly.
+- `read_mcp_resource` reads a resource by `server` and `uri`. Text reaches the model as text and images as images. Other binary resources are saved to temporary files, and the model receives the path. Scripts receive `{ server, uri, contents }`.
+
+These tools reach every enabled, non-hidden server with resources. Their exposure is the widest exposure among those servers: `direct`, then `codemode` or `deferred`. Resource links in tool results identify `read_mcp_resource` and the server.
+
+Resources for MCP Apps, identified by `ui://` URIs or `text/html;profile=mcp-app`, are omitted because Selesai does not render them. Resource icons are also omitted.
+
+Reading and listing resources is retried once after a transient HTTP error (408, 429, or 5xx). Tool calls are not retried because the server may already have performed them.
+
+## Permissions
+
+Every MCP call passes through Selesai's tool pipeline. Extension `tool_call` and `tool_result` handlers, including permission gates, therefore apply to MCP tools. Calls made from codemode scripts carry the codemode call ID as `parentToolCallId`.
+
+`pi.getAllTools()` reports the annotations declared by each server: `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`. Permission extensions can use these hints to decide which calls require confirmation (see [Tool exposure](extensions.md#tool-exposure)). Resource tools are marked read-only.
+
+## Extensions and SDK
+
+### Add servers from extensions
+
+Extensions can add servers for the current session with `pi.registerMcpServer(name, config)`, using the same shape as an `mcpServers` entry (see [MCP servers in extensions](extensions.md#mcp-servers)). Registered servers connect like configured servers and appear in `/mcp` with the extension as their source.
+
+Changes to enabled state or exposure apply only to the current session. A file-configured server with the same name takes precedence, and `/mcp` lists the overridden registration. `selesai mcp` shell commands do not load extensions and only see file-configured servers.
+
+### Replace the built-in MCP support
+
+An installed extension that registers `/mcp`, such as `pi-mcp-adapter`, replaces the built-in MCP support for sessions. Selesai then does not read `mcp.json` or connect its servers in a session, and `/mcp` belongs to the extension. Remove the extension to restore the built-in behavior. To disable built-in MCP support without a replacement, disable `mcp` under Built-in in `selesai config`, or set `"extensions": ["-builtin:mcp"]` in [settings](settings.md#resources). `--no-mcp` disables it for one run.
+
+An extension that registers `codemode` or `tool_search` similarly replaces the built-in tool with that name. Shell-level `selesai mcp` commands always use the built-in implementation.
+
+### Use MCP from the SDK
+
+SDK sessions do not load built-in extensions. Add the MCP extension, the codemode extension for `codemode` servers, and the tool-search extension for `deferred` servers to the resource loader. See [Codemode and MCP](sdk.md#codemode-and-mcp).

package/docs/models.md

@@ -1,6 +1,8 @@
 # Custom Models
 
-Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.pi/agent/models.json`.
+Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.selesai/agent/models.json`.
+
+The runtime catalog supports chat, image, and classifier operations. Only chat models appear in `/model`; use [codemode](codemode.md#models) or the model registry for non-chat operations. **`models.json` definitions and overrides are chat-only**; provider extensions register image and classifier entries.
 
 ## Table of Contents
 
@@ -13,6 +15,11 @@ Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.pi/ag
 - [Per-model Overrides](#per-model-overrides)
 - [Anthropic Messages Compatibility](#anthropic-messages-compatibility)
 - [OpenAI Compatibility](#openai-compatibility)
+- [Image Limits and Prompt Caching](#image-limits-and-prompt-caching)
+- [Sampling by Thinking Level](#sampling-by-thinking-level)
+- [Use Classifier Models](#use-classifier-models)
+- [Use Image Models](#use-image-models)
+- [Virtual Models](virtual-models.md)
 
 ## Minimal Example
 
@@ -200,6 +207,10 @@ If your command is slow, expensive, rate-limited, or should keep using a previou
 | `id` | Yes | — | Model identifier (passed to the API) |
 | `name` | No | `id` | Human-readable model label. Used for matching (`--model` patterns) and shown as secondary model detail text. |
 | `api` | No | provider's `api` | Override provider's API for this model |
+| `inputLimits` | No | omitted | Image encoding limits (see below) |
+| `promptCache` | No | omitted | Best-effort cache lifetime in seconds per retention tier |
+| `samplingParams` | No | omitted | OpenAI-compatible sampling defaults |
+| `samplingParamsByThinkingLevel` | No | omitted | Sampling overrides per effective thinking level |
 | `reasoning` | No | `false` | Supports extended thinking |
 | `thinkingLevelMap` | No | omitted | Maps pi thinking levels to provider values and marks unsupported levels (see below) |
 | `input` | No | `["text"]` | Input types: `["text"]` or `["text", "image"]` |
@@ -214,7 +225,7 @@ Current behavior:
 
 ### Thinking Level Map
 
-Use `thinkingLevelMap` on a model to describe model-specific thinking controls. Keys are pi thinking levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`.
+Use `thinkingLevelMap` on a model to describe model-specific thinking controls. Keys are Selesai thinking levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
 
 Values are tristate:
 
@@ -314,7 +325,7 @@ Use `modelOverrides` to customize specific built-in models without replacing the
 }
 ```
 
-`modelOverrides` supports these fields per model: `name`, `reasoning`, `input`, `cost` (partial), `contextWindow`, `maxTokens`, `headers`, `compat`.
+`modelOverrides` supports these fields per model: `name`, `reasoning`, `input`, `inputLimits`, `cost` (partial), `contextWindow`, `maxTokens`, `headers`, `compat`, `thinkingLevelMap`, `promptCache`, `samplingParams`, and `samplingParamsByThinkingLevel`.
 
 Behavior notes:
 - `modelOverrides` are applied to built-in provider models.
@@ -500,3 +511,93 @@ Vercel AI Gateway example:
   }
 }
 ```
+
+## Image Limits and Prompt Caching
+
+Use `inputLimits.images.resize` to control encoding of new attachments, `read` results, and tool-result images before they enter history:
+
+```json
+{
+  "id": "vision-model",
+  "input": ["text", "image"],
+  "inputLimits": {
+    "images": {
+      "resize": { "maxWidth": 1568, "maxHeight": 1568, "maxBytes": 524288, "jpegQuality": 75 }
+    }
+  }
+}
+```
+
+`maxBytes` limits the base64-encoded payload. Omitted resize fields default to 2000 by 2000 pixels, 4.5 MiB encoded, and JPEG quality 80. Changing models does not rewrite historical images. Catalog metadata can also describe `inputLimits.maxRequestBytes`, `images.maxPerMessage`, and `images.maxPerRequest`; history is not automatically rewritten or rejected against those limits.
+
+`promptCache` declares best-effort cache lifetimes in seconds, for example `"promptCache": { "short": 300, "long": 3600 }`. Use only verified provider lifetimes, conservatively; models without a lifetime for the active tier are not eligible for cache warming. `modelOverrides` can supply both `inputLimits` and `promptCache`. Metadata does not prove a cache hit or account charge.
+
+## Sampling by Thinking Level
+
+`samplingParams` sets OpenAI-compatible defaults. `samplingParamsByThinkingLevel` overrides them by Selesai thinking level (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`), not by the provider values in `thinkingLevelMap`:
+
+```json
+{
+  "id": "qwen-thinking-model",
+  "reasoning": true,
+  "samplingParams": { "temperature": 1.0, "top_p": 0.95 },
+  "samplingParamsByThinkingLevel": {
+    "off": { "temperature": 0.7, "top_p": 0.8 },
+    "high": { "top_k": 20 }
+  }
+}
+```
+
+After clamping unsupported thinking levels, Selesai merges model defaults, the effective level's overrides, and request-level sampling parameters, in that order. Later keys win; missing levels inherit defaults. `modelOverrides` merges per-level entries per key. These fields apply to `openai-completions`, `openai-responses`, and `azure-openai-responses`; other APIs ignore them. The former `azure-openai-responses-v1` API name is now `azure-openai-responses`.
+
+## Use Classifier Models
+
+Classifiers answer typed questions about JSON state without producing chat. Native questions use `choice`, `score`, or `bool`. The public Jev tools preserve their `noul` spelling and map it to native `bool` at the boundary.
+
+Selesai registers `tokenin/jev-1.13` with the native `typesafe-system-one` API at `https://lite.andlet.me/v1/systemone`, authenticated with a Bearer TokenIn credential. Sign in to TokenIn through the normal onboarding/login flow. There is no chat-completion fallback. The catalog preserves existing chat and image entries alongside classifiers. Provider extensions register non-chat entries using `type: "classifier"` or `type: "image"`; `models.json` definitions and overrides remain chat-only.
+
+Upstream classifier providers are available too, including OpenAI's `openai/gpt-6-luna` through the [Decisions API](https://developers.openai.com/api/docs/guides/decisions). It needs `OPENAI_API_KEY`: Sign in with ChatGPT credentials do not work with it, so it is not listed as available while `openai` is logged in through `/login`. GPT-6 Luna also judges images passed in `images` (see [Codemode](codemode.md#classify)); other classifier models return an error for them.
+
+Factory CLI settings enable `codemode`; SDK users enable it explicitly (see [Codemode and MCP](sdk.md#codemode-and-mcp)). List authenticated classifiers with `models.getAvailableOfType("classifier")`:
+
+```js
+const jev = await models.getModelOfType("classifier", "tokenin", "jev-1.13");
+if (!jev) return "TokenIn Jev is not registered";
+const result = await models.classify(jev, {
+  state: { message: "The change works, thanks." },
+  questions: {
+    approved: {
+      type: "bool",
+      instructions: "Does the user approve of the result?",
+      criteria: { true: "Approval", false: "No approval" }
+    }
+  }
+});
+if (result.stopReason !== "stop") return result.errorMessage;
+return result.answers;
+```
+
+Extensions call `ctx.modelRegistry.classify()` directly. [Codemode](codemode.md#classify) documents native answer types; [virtual models](virtual-models.md#route-requests) can use classifiers for routing.
+
+TokenIn keeps structured state internally and serializes it to a string only at the transport boundary. The actual escaped wire payload, including callback changes, is bounded to 64 KiB.
+
+**TokenIn billing is service-only.** A complete monetary breakdown is exposed as `usage.cost`; a scalar service charge is `reportedCost`; counts without recognized pricing are `unpricedUsage`. Zero catalog cost fields are placeholders, not a free-price claim. Service-reported cost is not independent proof of an account debit. Other providers retain their own upstream usage/catalog handling.
+
+## Use Image Models
+
+Image models generate images from text and optional image blocks. They do not appear in `/model`. Codemode scripts list authenticated entries with `models.getAvailableOfType("image")` and call `models.generateImages(model, { input })`:
+
+```js
+const available = await models.getAvailableOfType("image");
+if (!available.length) return "No authenticated image model is available";
+const result = await models.generateImages(available[0], {
+  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);
+}
+```
+
+Use `image()` rather than printing base64 data; it attaches the image and saves it to a temporary file. Extensions call `ctx.modelRegistry.generateImages()` without codemode. See [Codemode](codemode.md#generate-images) for the full API.

package/docs/providers.md

@@ -173,6 +173,8 @@ OAuth credentials are also stored here after `/login` and managed automatically.
 
 ### Azure OpenAI
 
+The provider ID is `azure` (formerly `azure-openai-responses`). Use it as the key in `auth.json`, `models.json`, and `settings.json`, and in model references such as `--model azure/gpt-5.4`. It serves OpenAI models through the Responses API and Microsoft Foundry models through Chat Completions, such as `azure/deepseek-v4-pro`.
+
 ```bash
 export AZURE_OPENAI_API_KEY=...
 export AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
@@ -182,8 +184,24 @@ export AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
 export AZURE_OPENAI_RESOURCE_NAME=your-resource
 
 # Optional
-export AZURE_OPENAI_API_VERSION=2024-02-01
-export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4,gpt-4o=my-gpt4o
+export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-5.4=my-gpt-deployment,deepseek-v4-pro=my-deepseek
+```
+
+The model ID is sent as the deployment name unless `AZURE_OPENAI_DEPLOYMENT_NAME_MAP` maps it. `AZURE_OPENAI_API_VERSION` overrides the API version for OpenAI models (default `v1`).
+
+To use a Foundry model that is not built in, add it under `azure` in [`models.json`](models.md#configure-a-compatible-endpoint) with `api: "openai-completions"`. Custom models require a `baseUrl`; `AZURE_OPENAI_BASE_URL` and `AZURE_OPENAI_RESOURCE_NAME` take priority over it when set:
+
+```json
+{
+  "providers": {
+    "azure": {
+      "baseUrl": "https://your-resource.services.ai.azure.com",
+      "models": [
+        { "id": "your-deployment", "api": "openai-completions" }
+      ]
+    }
+  }
+}
 ```
 
 ### Amazon Bedrock