@selesai/code 0.13.39 → 0.14.0

package/docs/security.md

@@ -1,51 +1,52 @@
 # Security
 
-Pi is a local coding agent. It runs with the permissions of the user account that starts it, and it treats files writable by that user as inside the same local trust boundary.
+Selesai is a local coding agent. It runs with the permissions of the user account that starts it, and it treats files writable by that user as inside the same local trust boundary.
 
 ## Project Trust
 
-Project trust controls whether pi loads project-local settings, resources, packages, and extensions. It is not a sandbox and it does not restrict what the model can ask tools to do after you start working in a directory.
+Project trust controls whether selesai loads project-local settings, resources, packages, and extensions. It is not a sandbox and it does not restrict what the model can ask tools to do after you start working in a directory.
 
-Pi considers a project to have resources that require trust when it finds any of these from the current working directory:
+Selesai considers a project to have resources that require trust when it finds any of these from the current working directory:
 
-- `.pi/settings.json`
-- `.pi/extensions`, `.pi/skills`, `.pi/prompts`, or `.pi/themes`
-- `.pi/SYSTEM.md` or `.pi/APPEND_SYSTEM.md`
+- `.selesai/settings.json`
+- `.selesai/mcp.json`
+- `.selesai/extensions`, `.selesai/skills`, `.selesai/prompts`, or `.selesai/themes`
+- `.selesai/SYSTEM.md` or `.selesai/APPEND_SYSTEM.md`
 - project `.agents/skills` in the current directory or an ancestor directory
 
-A bare `.pi` directory does not count as a project resource that requires trust.
+A bare `.selesai` directory does not count as a project resource that requires trust.
 
-When an interactive session starts in a project with resources that require trust and no saved decision for the current directory or a parent directory, pi follows `defaultProjectTrust` from global settings. The default value is `"ask"`, which asks whether to trust the project when UI is available. Saved decisions are stored by canonical directory in `~/.pi/agent/trust.json`, and the closest saved decision on the current or parent path applies before the global default.
+When an interactive session starts in a project with resources that require trust and no saved decision for the current directory or a parent directory, selesai follows `defaultProjectTrust` from global settings. The default value is `"ask"`, which asks whether to trust the project when UI is available. Saved decisions are stored by canonical directory in `~/.selesai/agent/trust.json`, and the closest saved decision on the current or parent path applies before the global default.
 
-Trusting a project allows pi to load project resources that require trust, including:
+Trusting a project allows selesai to load project resources that require trust, including:
 
-- `.pi/settings.json`
-- `.pi` resources such as extensions, skills, prompt templates, themes, and system prompt files
+- `.selesai/settings.json`
+- `.selesai` resources such as extensions, skills, prompt templates, themes, and system prompt files
 - missing project packages configured through project settings
 - project-local extensions and project package-managed extensions
 
-Declining trust skips protected resources. `AGENTS.md` and `CLAUDE.md` context files are loaded regardless of project trust unless context loading is disabled. Before trust is resolved, pi only loads context files, user/global extensions, and CLI `-e` extensions. User/global and CLI extensions can handle the `project_trust` event; the first extension that returns a yes/no decision owns the decision.
+Declining trust skips protected resources. `AGENTS.md` and `CLAUDE.md` context files are loaded regardless of project trust unless context loading is disabled. Before trust is resolved, selesai only loads context files, user/global extensions, and CLI `-e` extensions. User/global and CLI extensions can handle the `project_trust` event; the first extension that returns a yes/no decision owns the decision.
 
 Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, `defaultProjectTrust: "ask"` and `"never"` ignore such resources, while `"always"` trusts them. Use `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
 
 ## No Built-in Sandbox
 
-Pi does not include a built-in sandbox. Built-in tools can read files, write files, edit files, and run shell commands with the permissions of the pi process. Extensions are TypeScript modules that run with the same permissions. Package installs, shell commands, language servers, test commands, and other developer tools behave as ordinary local processes.
+Selesai does not include a built-in sandbox. Built-in tools can read files, write files, edit files, and run shell commands with the permissions of the selesai process. Extensions are TypeScript modules that run with the same permissions. Package installs, shell commands, language servers, test commands, and other developer tools behave as ordinary local processes.
 
-This is intentional. Pi is designed to operate on local source trees, invoke project toolchains, and integrate with the user's existing development environment. A partial in-process sandbox would be easy to misunderstand as a security boundary while still depending on the host shell, filesystem, package managers, credentials, and extension code. Real isolation needs to come from the operating system or a virtualization/container boundary.
+This is intentional. Selesai is designed to operate on local source trees, invoke project toolchains, and integrate with the user's existing development environment. A partial in-process sandbox would be easy to misunderstand as a security boundary while still depending on the host shell, filesystem, package managers, credentials, and extension code. Real isolation needs to come from the operating system or a virtualization/container boundary.
 
-Project trust is only an input-loading guard. It prevents a repository from silently changing pi's settings or extensions before you approve it. It does not make untrusted code, untrusted prompts, or untrusted model output safe. Prompt injection from repository files, comments, documentation, context files, or build output is expected local-agent risk and cannot be reliably prevented by pi.
+Project trust is only an input-loading guard. It prevents a repository from silently changing selesai's settings or extensions before you approve it. It does not make untrusted code, untrusted prompts, or untrusted model output safe. Prompt injection from repository files, comments, documentation, context files, or build output is expected local-agent risk and cannot be reliably prevented by pi.
 
 ## Running Untrusted or Unmonitored Work
 
-For untrusted repositories, generated code you do not intend to monitor closely, or unattended automation, run pi in a contained environment. Use a container, VM, micro-VM, remote sandbox, or policy-controlled sandbox with only the files and credentials required for the task.
+For untrusted repositories, generated code you do not intend to monitor closely, or unattended automation, run selesai in a contained environment. Use a container, VM, micro-VM, remote sandbox, or policy-controlled sandbox with only the files and credentials required for the task.
 
 Common patterns are documented in [Containerization](containerization.md):
 
-- run the whole `pi` process inside a container/sandbox
-- run host pi while routing built-in tool execution into a Gondolin micro-VM
+- run the whole `selesai` process inside a container/sandbox
+- run host selesai while routing built-in tool execution into a Gondolin micro-VM
 - mount only the workspace paths the agent should access
-- avoid mounting host `~/.pi/agent` unless the container should access host sessions, settings, and credentials
+- avoid mounting host `~/.selesai/agent` unless the container should access host sessions, settings, and credentials
 - pass the minimum required API keys or use short-lived credentials
 - restrict network access when the task does not need it
 - review diffs and outputs before copying results back to trusted systems
@@ -56,4 +57,4 @@ If you bind-mount a host workspace read/write, writes from inside the container
 
 To report a security issue, follow the repository [Security Policy](https://github.com/earendil-works/pi-mono/blob/main/SECURITY.md). Do not open a public issue for security-sensitive reports.
 
-Expected local-agent behavior, lack of a built-in sandbox, prompt injection from untrusted content, and behavior of user-installed extensions or skills are generally outside the security boundary unless the report demonstrates a real privilege-boundary bypass or shows how pi grants access that the local user did not already have.
+Expected local-agent behavior, lack of a built-in sandbox, prompt injection from untrusted content, and behavior of user-installed extensions or skills are generally outside the security boundary unless the report demonstrates a real privilege-boundary bypass or shows how selesai grants access that the local user did not already have.

package/docs/settings.md

@@ -124,53 +124,24 @@ is an ordinary abstention that leaves the existing memory policy and verificatio
 }
 ```
 
-### Capability Gateway (experimental)
-
-The bundled `capability-gateway` extension keeps optional extension tools dormant until they are
-needed: a compact `capability_catalog` lists them, `capability_discover` activates one for the
-current run, and `capability_skill_show` loads one skill's full instructions. Set
-`SELESAI_CAPABILITY_GATEWAY=0` to disable the gateway and keep every tool visible.
-
-Routing has three rungs:
-
-1. A deterministic router activates a tool when the prompt uniquely matches its name, alias, or
-   discovery summary. Skills are never auto-loaded or auto-selected.
-2. Default-on Jev tie-breaking: when the deterministic router returns an ambiguous lexical hint
-   among optional tools, the Jev decisions model is asked which of two or three hinted tools (or
-   `none`) should be exposed. Jev sees only the bounded current prompt and each hinted tool's compact
-   discovery line — never conversation history or tool schemas. A prompt with no
-   lexical signal, a unique activation, and a skill-only match never reach Jev. Token-In credentials
-   are required; without them, no Jev request is sent and Selesai prompts you to run `/tokenin add`.
-3. The agent-driven route: `capability_discover` also takes a `job` instead of a name. Tools and
-   skills are separate decisions — a tool is callable code from an extension or MCP server that the
-   agent may use many times, a skill is a written procedure it reads once — so one Jev request asks
-   two questions, each from catalog metadata only (never a schema or skill body), each allowed to
-   answer `none`. A chosen tool is activated for the run and its parameters are returned; a chosen
-   skill is named for `capability_skill_show`. Tools are offered first, so only skills can be left out
-   of an oversized catalog, and a `none` then says how many were not considered. A skill found in
-   several sources is offered once. While Jev has no credential, the `job` route is left out of the
-   agent's instructions and the agent is pointed at `capability_catalog` plus an exact `name`.
-
-All Jev features share one warning per session, shown the first time one of them actually needs the
-missing credential; a user without a subscription is not warned just for starting a session.
+### Tools and skills
 
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `capabilityGateway.routing.jev.enabled` | boolean | `true` | Enable Jev tie-breaking for ambiguous tool hints; toggle it in `/settings` (requires Token-In credentials) |
-| `capabilityGateway.routing.jev.provider` | string | `"tokenin"` | Provider serving the Jev decisions deployment |
-| `capabilityGateway.routing.jev.model` | string | `"jev-1.13"` | Decisions model the tie-breaker calls |
-| `capabilityGateway.routing.jev.baseUrl` | string | inherited | Base URL override; defaults to any registered model of `provider` |
-| `capabilityGateway.routing.jev.timeoutMs` | number | `1000` | Pre-turn request timeout (ms); hard-capped at `2000` |
-| `capabilityGateway.routing.jev.discoverTimeoutMs` | number | `5000` | Timeout (ms) for `capability_discover({ job })`; hard-capped at `15000` |
-| `capabilityGateway.routing.jev.minConfidence` | number | `0.6` | Below this Jev confidence the tie-breaker abstains |
-| `capabilityGateway.routing.jev.payloadBytes` | number | `32768` | Hard cap on the serialized decision request; the pre-turn tie-break uses a few hundred bytes of it |
-
-This area is independent of `jevAdvisory`: gateway routing reads only
-`capabilityGateway.routing.jev` and shares just the Jev provider/model deployment identity. A
-failure, timeout, invalid answer, low confidence, missing Token-In credentials, or `none` is an
-ordinary abstention that leaves deterministic behavior in place. Temporary activations reset when the run settles, and
-content-free telemetry on the `capability-gateway` event channel records the route outcome and
-whether an activated tool was actually invoked.
+The bundled defaults use `"defaultTools": ["+codemode"]`: keep the normal tool selection and
+add codemode. Plain names replace the selection; `+name`/`-name` adjust it. The same applies to `--tools` for one invocation: `selesai --tools +tool_search` adjusts the resolved defaults, while plain names replace them. On `/reload`, a tool removed with `-name` stays removed. Frequently used
+owned tools remain direct; specialised tools use upstream deferred exposure. Discover deferred
+tools through codemode `searchTools()` or `tool_search` when enabled. Loaded tools remain active
+across settlement and resume; there is no gateway reset or Jev tie-breaking policy.
+
+The bundled `skills-index` extension replaces the eager skill listing with compact guidance.
+Use `skill_show` without a name to list eligible skills, `query` to filter their metadata, or an
+exact `name` to load instructions before applying a skill. It never activates tools or chooses
+skills automatically. If `skill_show` is excluded, the ordinary skill index is retained.
+The retired gateway environment variable and settings have no effect in the parent runtime.
+
+MCP OAuth uses Selesai-branded dynamic registration or a pre-registered `oauth.clientId`.
+`oauth.clientRegistration: "cimd"` is rejected: Selesai has no hosted client metadata document
+and must not identify itself through upstream Pi's document. OAuth browser page artwork comes
+from the upstream dependency and is unchanged.
 
 ### UI & Display
 
@@ -349,6 +320,7 @@ When multiple sources specify a session directory, precedence is `--session-dir`
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
 | `markdown.codeBlockIndent` | string | `"  "` | Indentation for code blocks |
+| `markdown.mermaid` | string | `"streaming"` | Render Mermaid fences as Unicode diagrams: `"off"`, `"final"`, or `"streaming"`. Also configurable in `/settings`. Diagrams that cannot render or fit retain their source fence. |
 
 ### Resources
 

package/docs/terminal-setup.md

@@ -140,3 +140,17 @@ The built-in terminal has limited escape sequence support. Shift+Enter cannot be
 If you want the hardware cursor visible, set `PI_HARDWARE_CURSOR=1` before running pi (disabled by default for compatibility).
 
 Consider using a dedicated terminal emulator for the best experience.
+
+## Program status
+
+Selesai reports its state with the [Program Status Protocol (OSC 7501)](https://www.superlogical.com/rex/docs/build/program-status), so terminals and agent dashboards can show whether it is working, waiting for you, done, or failed:
+
+| State | When |
+|---|---|
+| `working` | An agent run or compaction is in progress. The message is the session name. |
+| `blocked` | An extension dialog or login waits for you. The message is the dialog title. |
+| `done` | A run finished. The message is the session name. |
+| `error` | A run ended with an error that is not retried. The message is the first line of the error. |
+| `idle` | Selesai started, or you cancelled the run. |
+
+Reports never contain prompts or model output. They are sent only after the terminal answers the protocol's support query; tmux and screen do not forward them. Set `PI_PROGRAM_STATUS=1` to send reports without asking, or `PI_PROGRAM_STATUS=0` to turn them off.

package/docs/virtual-models.md

@@ -0,0 +1,114 @@
+# Virtual Models
+
+A virtual model is a selectable model that picks a physical model for each request. Use one to route by task, cost, or conversation state. For example, a router can send quick questions to a small model and hard problems to a large one, while the user selects a single model.
+
+Register virtual models from an [extension](extensions.md). They appear in `/model`, `--model`, scoped models, and settings like any other model. A virtual model can be listed under any provider, including one with physical models, such as `openai-codex/auto`.
+
+## Selection and dispatch
+
+A virtual model selects a model and a thinking level. A router maps that pair to a physical pair for each request:
+
+```
+selected (virtual model, virtual level)  ->  dispatched (physical model, physical level)
+jev/auto:low                             ->  anthropic/claude-sonnet-4-5:high
+```
+
+The virtual thinking level is an input to the router. Its meaning is up to the router; it need not correspond to a reasoning budget.
+
+Selesai keeps the two pairs apart:
+
+| | Selection | Dispatch |
+|---|---|---|
+| Recorded in | `model_change` and `thinking_level_change` entries | Each assistant message: `provider`, `api`, `model`, `thinkingLevel` |
+| Visible as | `ctx.model`, `ctx.thinkingLevel`, `PI_MODEL`, `PI_REASONING_LEVEL`, `/model` | The assistant message of each response |
+
+Providers only receive physical models. Assistant messages name the physical model, so replaying a conversation across different physical models works the same as after a manual model switch. Resuming a session restores the virtual selection from its latest `model_change` entry. If the virtual model is no longer registered, Selesai falls back to the physical model that answered last.
+
+In interactive mode, the footer shows the routed model next to the selection, for example `auto • high → gpt-5.6-luna • medium`. `/session` lists the cost for each physical model.
+
+Context usage uses the limits of the physical model that produced the latest response, even if that response came before switching to the virtual model. Without such a response, it uses the limits declared on the virtual model, if any. Compaction checks the same limits, and again the limits of the model each request is routed to. If that model's context window is too small for the conversation, Selesai compacts before sending the request; the route stays as the router chose it.
+
+## Register a virtual model
+
+```typescript
+import type { ExtensionAPI } from "@selesai/code";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerVirtualModel({
+    provider: "router",
+    id: "auto",
+    name: "Auto",
+    thinkingLevels: ["low", "high"],
+    route(request, ctx) {
+      // Tool follow-ups and retries stay on the model that handled the turn.
+      const sticky = request.failed ?? request.previous;
+      if (request.reason !== "user" && sticky) {
+        return { model: sticky.model, thinkingLevel: sticky.thinkingLevel ?? "medium" };
+      }
+      const id = request.thinkingLevel === "high" ? "claude-sonnet-4-5" : "claude-haiku-4-5";
+      return { model: ctx.modelRegistry.find("anthropic", id)!, thinkingLevel: "medium" };
+    },
+  });
+}
+```
+
+- `provider` is the provider the model is listed under. It can be any provider ID. A provider can list several virtual models next to its physical ones. On a physical provider, the virtual model is available when that provider has credentials. Under an ID that no provider uses, it is always available.
+- `id` must not be the ID of a physical model of that provider. If a catalog refresh later adds a physical model with the same ID, the virtual model hides it.
+- `thinkingLevels` lists the levels offered for selection. It defaults to `["off"]`.
+- `contextWindow` and `maxTokens` are shown before the first response. Unset limits are unknown.
+- `input` lists the input types offered for selection. It defaults to text and images; physical models without image support receive placeholders.
+
+Registration follows the same queuing and reload rules as `pi.registerProvider()`. Registering the same provider and ID again replaces the virtual model. `pi.unregisterVirtualModel(provider, id)` removes it; `pi.unregisterProvider()` does not. SDK code can register one without an extension: `modelRuntime.registerVirtualModel(definition)`.
+
+## Route requests
+
+`route(request, ctx)` runs before every request made with the virtual model and returns `{ model, thinkingLevel }`. The model can be any physical model in the catalog whose provider has credentials; look it up with `ctx.modelRegistry`. A virtual model cannot route to another virtual model. Selesai clamps the thinking level to the returned model.
+
+| Field | Meaning |
+|---|---|
+| `model`, `thinkingLevel` | The selected virtual model and level |
+| `reason` | Why the request is made, see below |
+| `previous` | Physical model and thinking level of the latest successful response in `messages` |
+| `failed` | For `retry`: physical model, thinking level, and assistant `message` of the failed request, which `messages` no longer contains. The message carries `stopReason` and `errorMessage`. Absent when routing itself failed |
+| `state` | Router state last returned on this session branch, see below |
+| `messages` | The conversation for this request, including system messages |
+| `signal` | Abort signal of the request |
+
+| `reason` | Request |
+|---|---|
+| `user` | First request after a message the user wrote, including steering and follow-up messages |
+| `continuation` | Any other request in the agent loop, such as after tool results or extension messages |
+| `retry` | Automatic retry after a failed request, including after compaction for a context overflow |
+| `direct` | Request made outside the agent loop, such as a compaction summary or an extension calling `ctx.modelRegistry.streamSimple()` |
+
+Returning `previous` for `continuation` and `failed` for `retry` keeps prompt caches and thinking signatures valid. Switching models between turns is allowed but loses the prompt cache. A retry can also switch to another model, for example when `failed.message.errorMessage` reports that a provider is overloaded or the context overflowed.
+
+If `route()` throws, or returns a virtual model or a model without credentials, the request ends with an error response.
+
+## Keep routing state
+
+`route()` can return `state` next to the model. Selesai stores it on the session branch and passes it back as `request.state` on later requests. Use it for decisions the transcript does not record, such as classifier results or a routing phase:
+
+```typescript
+pi.registerVirtualModel<{ phase: "plan" | "build" }>({
+  provider: "router",
+  id: "phased",
+  name: "Phased",
+  route(request, ctx) {
+    const state = request.state ?? { phase: "plan" };
+    const id = state.phase === "plan" ? "claude-opus-4-5" : "claude-haiku-4-5";
+    return { model: ctx.modelRegistry.find("anthropic", id)!, thinkingLevel: "medium", state };
+  },
+});
+```
+
+- State must be JSON-serializable. Returning `undefined` or `request.state` itself keeps the current state.
+- Selesai stores any other returned object as new state, before the request is sent, even when it equals the current state. Return a new object only when the state changes. The state stays stored if the request later fails.
+- State follows the session tree, so forks and `/tree` navigation see the state of their branch. It survives compaction.
+- `direct` requests have no state, and Selesai ignores state they return.
+
+The transcript already records the selection and every dispatched model, and `ctx.sessionManager.getBranch()` exposes both.
+
+Routers can call other models through `ctx.modelRegistry`, for example `ctx.modelRegistry.classify()` with a classifier model from `ctx.modelRegistry.findOfType("classifier", provider, id)`. The call adds latency before the first token of the turn.
+
+See [`jev-router.ts`](../examples/extensions/jev-router.ts) for a complete router. It plans on a strong OpenAI Codex model chosen by the Jev classifier, lets that model make the first edit, and then switches once to a cheaper model, accepting a single prompt-cache miss. It keeps the phase as router state.

package/examples/extensions/jev-router.ts

@@ -0,0 +1,113 @@
+/**
+ * Jev router - a virtual model that plans on a strong model and implements on a cheap one.
+ *
+ * Registers `jev/auto`, which routes between three OpenAI Codex models:
+ *
+ * - Planning: GPT-5.6 Sol for complex work, GPT-5.6 Terra otherwise. The Jev classifier rates the
+ *   first user message; planning stays on the chosen model.
+ * - Implementation: GPT-5.6 Luna.
+ *
+ * The planning model explores, plans, and makes the first edit. After the first successful `edit`
+ * or `write` tool call, the next request of the same turn goes to Luna, and the session stays
+ * there. A session therefore switches models once and accepts a single prompt-cache miss.
+ *
+ * The phase is router state: Selesai stores it on the session branch, so it follows the session tree
+ * and survives compaction. The selected thinking level passes through as the reasoning effort of
+ * the chosen model. Requests outside the agent loop, such as compaction summaries, go to Luna.
+ *
+ * Requires TypeSafe credentials (TYPESAFE_API_KEY) and an OpenAI Codex login.
+ * Usage: selesai -e ./jev-router.ts --model jev/auto
+ */
+
+import type { Message } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext, ModelRoute, ModelRouteRequest } from "@selesai/code";
+
+const PROVIDER = "openai-codex";
+const SOL = "gpt-5.6-sol";
+const TERRA = "gpt-5.6-terra";
+const LUNA = "gpt-5.6-luna";
+
+/** Tools whose successful result means implementation has started. */
+const EDIT_TOOLS = new Set(["edit", "write"]);
+
+interface JevState {
+	phase: "planning" | "implementation";
+	/** OpenAI Codex model for this phase. */
+	model: string;
+}
+
+type JevRequest = ModelRouteRequest<JevState>;
+
+function routeTo(request: JevRequest, ctx: ExtensionContext, id: string, state?: JevState): ModelRoute<JevState> {
+	const model = ctx.modelRegistry.find(PROVIDER, id);
+	if (!model) throw new Error(`Model ${PROVIDER}/${id} is not in the catalog`);
+	return { model, thinkingLevel: request.thinkingLevel, state };
+}
+
+function lastUserText(messages: readonly Message[]): string {
+	const content = messages.filter((message) => message.role === "user").at(-1)?.content ?? "";
+	if (typeof content === "string") return content;
+	return content.flatMap((block) => (block.type === "text" ? [block.text] : [])).join("\n");
+}
+
+/** Whether a tool call since the last user message edited a file successfully. */
+function editedThisTurn(messages: readonly Message[]): boolean {
+	const lastUser = messages.findLastIndex((message) => message.role === "user");
+	return messages
+		.slice(lastUser + 1)
+		.some((message) => message.role === "toolResult" && EDIT_TOOLS.has(message.toolName) && !message.isError);
+}
+
+/** Planning model for a new session: Sol for complex work, Terra otherwise or when Jev is unavailable. */
+async function choosePlanningModel(request: JevRequest, ctx: ExtensionContext): Promise<string> {
+	// Keep a planning model the session already uses, so switching to jev/auto costs no cache miss.
+	const previous = request.previous?.model;
+	if (previous?.provider === PROVIDER && (previous.id === SOL || previous.id === TERRA)) return previous.id;
+
+	const jev = ctx.modelRegistry.findOfType("classifier", "typesafe", "jev-latest");
+	if (!jev) return TERRA;
+	const result = await ctx.modelRegistry.classify(
+		jev,
+		{
+			state: { prompt: lastUserText(request.messages).slice(0, 16_000) },
+			questions: {
+				complexity: {
+					type: "choice",
+					instructions: "How demanding is the software engineering work requested in `prompt`?",
+					criteria: {
+						standard: "Ordinary features, fixes, reviews, or questions",
+						complex: "Subtle design, cross-cutting changes, or hard debugging",
+					},
+				},
+			},
+		},
+		{ signal: request.signal },
+	);
+	const answer = result.stopReason === "stop" ? result.answers.complexity : undefined;
+	return answer?.type === "choice" && (answer.probabilities.complex ?? 0) >= 0.5 ? SOL : TERRA;
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerVirtualModel<JevState>({
+		provider: "jev",
+		id: "auto",
+		name: "Auto (Jev)",
+		thinkingLevels: ["low", "medium", "high", "xhigh"],
+		// Shared by all three models; shown before the first response.
+		contextWindow: 272_000,
+		maxTokens: 128_000,
+		async route(request, ctx) {
+			if (request.reason === "direct") return routeTo(request, ctx, LUNA);
+			const state = request.state;
+			if (!state) {
+				const model = await choosePlanningModel(request, ctx);
+				return routeTo(request, ctx, model, { phase: "planning", model });
+			}
+			// The planning model made the first edit: hand the rest of the work to Luna.
+			if (state.phase === "planning" && editedThisTurn(request.messages)) {
+				return routeTo(request, ctx, LUNA, { phase: "implementation", model: LUNA });
+			}
+			return routeTo(request, ctx, state.model);
+		},
+	});
+}

package/examples/extensions/tokenin-usage-widget.ts

@@ -0,0 +1,124 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const WIDGET_KEY = "tokenin-usage";
+const REFRESH_MS = 60_000;
+const DEFAULT_BASE_URL = "https://lite.andlet.me/v1";
+
+type Balance = {
+	available_usd: number;
+	fixed_available_usd?: number;
+	payg_available_usd?: number;
+	debt_usd?: number;
+};
+
+type LegacyUsage = {
+	spend: number;
+	max_budget?: number;
+};
+
+function proxyRoot(baseUrl: string): string {
+	return baseUrl.replace(/\/+$/, "").replace(/\/v1$/, "");
+}
+
+function money(value: number): string {
+	return `$${value.toFixed(2)}`;
+}
+
+async function requestJson(url: string, apiKey: string): Promise<{ status: number; body?: unknown }> {
+	const response = await fetch(url, {
+		headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
+		signal: AbortSignal.timeout(5_000),
+	});
+	let body: unknown;
+	try {
+		body = await response.json();
+	} catch {
+		// The status still lets the caller distinguish a missing balance route.
+	}
+	return { status: response.status, body };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function readNumber(record: Record<string, unknown>, key: string): number | undefined {
+	const value = record[key];
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+async function getUsageLines(ctx: ExtensionContext): Promise<string[]> {
+	const resolved = await ctx.modelRegistry.getProviderAuth("tokenin");
+	const apiKey = resolved?.auth.apiKey;
+	if (!apiKey) return ["Token-In: not connected (run /tokenin add)"];
+
+	const provider = ctx.modelRegistry.getProvider("tokenin");
+	const baseUrl = resolved.auth.baseUrl ?? provider?.baseUrl ?? DEFAULT_BASE_URL;
+	const root = proxyRoot(baseUrl);
+	const balanceResponse = await requestJson(`${root}/tokenin/account/me/balance`, apiKey);
+
+	if (balanceResponse.status >= 200 && balanceResponse.status < 300 && isRecord(balanceResponse.body)) {
+		const available = readNumber(balanceResponse.body, "available_usd");
+		if (available !== undefined) {
+			const balance: Balance = {
+				available_usd: available,
+				fixed_available_usd: readNumber(balanceResponse.body, "fixed_available_usd"),
+				payg_available_usd: readNumber(balanceResponse.body, "payg_available_usd"),
+				debt_usd: readNumber(balanceResponse.body, "debt_usd"),
+			};
+			const debt = balance.debt_usd && balance.debt_usd > 0 ? ` · debt ${money(balance.debt_usd)}` : "";
+			return [
+				`Token-In available: ${money(balance.available_usd)}`,
+				`Plan ${money(balance.fixed_available_usd ?? 0)} · PAYG ${money(balance.payg_available_usd ?? 0)}${debt}`,
+			];
+		}
+	}
+
+	// Match /tokenin usage: fall back only when the account balance is absent or unusable.
+	if (balanceResponse.status !== 404 && (balanceResponse.status < 200 || balanceResponse.status >= 300)) {
+		throw new Error(`balance endpoint returned HTTP ${balanceResponse.status}`);
+	}
+
+	const usageResponse = await requestJson(`${root}/key/info`, apiKey);
+	if (usageResponse.status < 200 || usageResponse.status >= 300 || !isRecord(usageResponse.body)) {
+		throw new Error(`usage endpoint returned HTTP ${usageResponse.status}`);
+	}
+	const info = isRecord(usageResponse.body.info) ? usageResponse.body.info : usageResponse.body;
+	const spend = readNumber(info, "spend");
+	if (spend === undefined) throw new Error("usage endpoint returned an unexpected payload");
+	const usage: LegacyUsage = { spend, max_budget: readNumber(info, "max_budget") };
+	const remaining = usage.max_budget === undefined ? "no budget limit" : `${money(Math.max(0, usage.max_budget - spend))} remaining`;
+	return [`Token-In spent: ${money(spend)}`, remaining];
+}
+
+export default function tokenInUsageWidget(pi: ExtensionAPI) {
+	let timer: ReturnType<typeof setInterval> | undefined;
+	let refreshing = false;
+
+	pi.on("session_start", async (_event, ctx) => {
+		if (!ctx.hasUI) return;
+		if (timer) clearInterval(timer);
+
+		const refresh = async () => {
+			if (refreshing) return;
+			refreshing = true;
+			try {
+				ctx.ui.setWidget(WIDGET_KEY, await getUsageLines(ctx), { placement: "belowEditor" });
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				ctx.ui.setWidget(WIDGET_KEY, [`Token-In usage unavailable: ${message}`], { placement: "belowEditor" });
+			} finally {
+				refreshing = false;
+			}
+		};
+
+		await refresh();
+		timer = setInterval(() => void refresh(), REFRESH_MS);
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => {
+		if (timer) clearInterval(timer);
+		timer = undefined;
+		if (ctx.hasUI) ctx.ui.setWidget(WIDGET_KEY, undefined);
+	});
+}

package/examples/rpc-client.ts

@@ -0,0 +1,35 @@
+/**
+ * Run one prompt through a Selesai RPC child process.
+ *
+ * Build the coding-agent package first, then run:
+ * node examples/rpc-client.ts "Explain this repository"
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { RpcClient } from "@selesai/code";
+
+const exampleDirectory = dirname(fileURLToPath(import.meta.url));
+const prompt = process.argv.slice(2).join(" ") || "Explain this repository in one paragraph.";
+
+const client = new RpcClient({
+	cliPath: join(exampleDirectory, "../dist/cli.js"),
+	args: ["--no-session"],
+});
+
+const unsubscribe = client.onEvent((event) => {
+	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+		process.stdout.write(event.assistantMessageEvent.delta);
+	} else if (event.type === "tool_execution_start") {
+		process.stderr.write(`\n[tool: ${event.toolName}]\n`);
+	}
+});
+
+try {
+	await client.start();
+	await client.promptAndWait(prompt);
+	process.stdout.write("\n");
+} finally {
+	unsubscribe();
+	await client.stop();
+}

package/examples/sdk/14-codemode-mcp.ts

@@ -0,0 +1,67 @@
+/**
+ * Codemode, Tool Search, and MCP
+ *
+ * The CLI loads `codemode`, `tool_search`, and MCP as built-in extensions. SDK sessions add
+ * them to the resource loader's extension factories.
+ *
+ * `codemode` and `tool_search` are registered inactive. Enable them through the `defaultTools` setting
+ * (`tools` would also restrict the session to the named tools, which hides MCP tools), or let the
+ * MCP extension activate them: `codemode` for servers with `codemode` exposure, `tool_search` for
+ * servers with `deferred` exposure.
+ */
+
+import {
+	createAgentSession,
+	createCodemodeExtension,
+	createMcpExtension,
+	createToolSearchExtension,
+	DefaultResourceLoader,
+	getAgentDir,
+	SessionManager,
+	SettingsManager,
+} from "@selesai/code";
+
+const cwd = process.cwd();
+
+const resourceLoader = new DefaultResourceLoader({
+	cwd,
+	agentDir: getAgentDir(),
+	extensionFactories: [
+		createCodemodeExtension({ mode: "on" }),
+		createToolSearchExtension(),
+		// Reads mcp.json from the agent directory and the trusted project, like the CLI.
+		createMcpExtension(),
+	],
+});
+await resourceLoader.reload();
+
+const settingsManager = SettingsManager.create(cwd);
+// `+name` adds to the configured default tools instead of replacing them.
+settingsManager.applyOverrides({ defaultTools: ["+codemode", "+tool_search"] });
+
+const { session } = await createAgentSession({
+	resourceLoader,
+	settingsManager,
+	sessionManager: SessionManager.inMemory(),
+});
+
+try {
+	// Emits session_start, which connects the MCP servers in the background.
+	await session.bindExtensions({});
+	console.log("Active tools:", session.getActiveToolNames().join(", "));
+	session.subscribe((event) => {
+		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+			process.stdout.write(event.assistantMessageEvent.delta);
+		}
+	});
+	await session.prompt("Use codemode to count the TypeScript files in src/ and list the three largest.");
+	console.log();
+} finally {
+	try {
+		// Hosts emit shutdown before disposal; dispose() itself invalidates the runtime,
+		// but does not await session_shutdown handlers that close MCP processes.
+		await session.extensionRunner.emit({ type: "session_shutdown", reason: "quit" });
+	} finally {
+		session.dispose();
+	}
+}