@knightcodeai/cli 0.19.0 → 0.21.1

package/docs/cli.md

@@ -13,7 +13,7 @@ knightcode update [target] [options]
 knightcode list
 knightcode config [options]
 knightcode auth <check|print-api-key|print-bearer-token> [options]
-knightcode mcp <list|login|logout> [options]
+knightcode mcp <add|remove|list|login|logout> [options]
 knightcode app-server [-e <extension>]... [--session-dir <dir>]
 ```
 
@@ -167,7 +167,7 @@ The MCP resource tools (`list_mcp_resources`, `list_mcp_resource_templates`, `re
 
 The [web tools](usage.md#web-tools) `webfetch` and `websearch` and the [question tool](usage.md#questions) `ask_user` are off until enabled with `/tools` or named here. A tool excluded here stays off whatever `/tools` says, and one turned off with `/tools` stays off even when named here.
 
-Built-in extensions add two more tools. They are off by default; the MCP extension turns them on when an MCP server needs them (see [MCP](mcp.md#exposure)). To enable them yourself, name them in `--tools` or `defaultTools`.
+Built-in extensions add two more tools. They are off by default; the MCP extension turns them on when an MCP server needs them (see [MCP](mcp.md#control-tool-exposure)). To enable them yourself, name them in `--tools` or `defaultTools`.
 
 | Built-in extension | Purpose |
 |---|---|
@@ -388,6 +388,6 @@ These commands work outside a session, so agents can run them through `bash`. Se
 | `knightcode mcp login <server> [--timeout <seconds>]` | Sign in to an OAuth server: open the authorization page and wait for the browser; a terminal also accepts the pasted redirect URL. `--timeout` limits the whole sign-in, including requests to the authorization server (default 300 seconds) |
 | `knightcode mcp logout <server>` | Delete the stored OAuth credentials of a server |
 
-`add` and `remove` change `~/.knightcode/agent/mcp.json`, or `.knightcode/mcp.json` in the current directory with `--local` (`-l`). `add` also takes `--exposure <mode>` (see [Exposure](mcp.md#exposure)) and `--description <text>` and does not connect; run `knightcode mcp list` to check the server.
+`add` and `remove` change `~/.knightcode/agent/mcp.json`, or `.knightcode/mcp.json` in the current directory with `--local` (`-l`). `add` also takes `--exposure <mode>` (see [Exposure](mcp.md#control-tool-exposure)) and `--description <text>` and does not connect; run `knightcode mcp list` to check the server.
 
 Project `.knightcode/mcp.json` files are only read for projects that are already trusted.

package/docs/containerization.md

@@ -112,11 +112,11 @@ OpenShell inference routing can keep raw model credentials outside the sandbox.
 
 ## Route tools through Gondolin
 
-[Gondolin](https://github.com/KnightCodeAI/gondolin) is a local Linux micro-VM. Its example extension keeps the KnightCode process and file-based provider credentials on the host while routing the built-in tools and user `!` commands into the VM.
+[Gondolin](https://github.com/earendil-works/gondolin) is a local Linux micro-VM. Its example extension keeps the KnightCode process and file-based provider credentials on the host while routing the built-in tools and user `!` commands into the VM.
 
 Commands inside the VM inherit the host process environment. Provider keys supplied through environment variables can therefore be visible inside the VM. Do not use this pattern as a credential boundary unless you remove sensitive variables or change the extension's environment handling.
 
-Gondolin requires Node.js 23.6 or newer and QEMU installed through your operating-system package manager.
+Gondolin requires Node.js 22.19 or newer and QEMU installed through your operating-system package manager.
 
 ### Install the extension
 

package/docs/custom-provider.md

@@ -138,6 +138,8 @@ An OAuth provider supplies a display name, login flow, token refresh, and access
 
 OAuth callbacks are UI-neutral. They can open an authorization URL, show a device code, report progress, request input, or ask the user to choose a login method. Honor cancellation and the supplied abort signal during network requests.
 
+Press Enter (`tui.select.confirm`) to open the device-login URL and copy the code, or log in manually. Providers can disable either action with `openBrowserOnConfirm: false` or `copyCodeOnConfirm: false` in `onDeviceCode` or native `AuthEvent` notifications.
+
 Never write access tokens, refresh tokens, authorization headers, or complete provider responses to ordinary logs.
 
 ## Supply and refresh models

package/docs/declarative-views.md

@@ -0,0 +1,118 @@
+# Declarative Views
+
+A view is a small tree of data that describes what to draw: text, markdown, a
+table, a progress bar, a button. An extension hands one to a widget, a tool
+result or an extension message, and every client draws it with its own
+components: the terminal with TUI components, the [desktop app](desktop.md) with
+its own. A view is data only. It never holds HTML, scripts or URLs that load.
+
+```ts
+import type { View } from "@knightcodeai/cli";
+
+const view: View = {
+	type: "stack",
+	children: [
+		{ type: "text", text: "2 checks failed", tone: "error" },
+		{ type: "table", columns: ["check", "result"], rows: [["parser", "failed"], ["lexer", "failed"]] },
+		{ type: "button", id: "rerun", label: "Run again" },
+	],
+};
+```
+
+## Nodes
+
+| Node | Fields | Example |
+| --- | --- | --- |
+| `text` | `text`, optional `tone`: `muted`, `accent`, `success`, `warning`, `error` | `{type: "text", text: "Saved", tone: "success"}` |
+| `markdown` | `markdown`; raw HTML shows as text, images do not load | `{type: "markdown", markdown: "**3** files"}` |
+| `stack` | `children`, optional `direction`: `vertical` (default) or `horizontal` | `{type: "stack", direction: "horizontal", children: [...]}` |
+| `list` | `items`, each a view, drawn as bullets | `{type: "list", items: [{type: "text", text: "one"}]}` |
+| `table` | `columns` (at least one), `rows` of strings, each row as wide as `columns` | `{type: "table", columns: ["a"], rows: [["1"]]}` |
+| `progress` | `value` (0 or more), `max` (over 0), optional `label`; a value over `max` draws full | `{type: "progress", value: 3, max: 10, label: "tests"}` |
+| `button` | `id` (1 to 128 characters), `label` | `{type: "button", id: "reset", label: "Reset"}` |
+| `field` | `id`, `kind`: `text`, `toggle` or `select`, `label`, `value`, and `options` for a select | `{type: "field", id: "mode", kind: "select", label: "Mode", value: "fast", options: ["fast", "slow"]}` |
+
+## Rules and limits
+
+A view that breaks a rule is refused as a whole:
+
+- No members other than those above, and no other node types.
+- Stacks and lists nest at most 8 levels.
+- Control ids (`button` and `field`) are unique within the view.
+- A toggle's `value` is a boolean; a text or select field's is a string. A
+  select has `options` and its `value` is one of them; a text field or toggle
+  has no `options`.
+- Its JSON is at most 64 KiB in a tool result or an extension message, and at
+  most 16 KiB in a widget.
+
+The view is copied through JSON when it is used, so a getter, a `toJSON` or a
+change you make to the object later does not change what was drawn. Call
+`setWidget` again to change a widget.
+
+Terminal escape sequences and control characters other than tab and newline
+are removed from every string of the copy, so colour a view with `tone`, not
+ANSI codes.
+
+A thread shows at most 16 widgets and 50 statuses, with keys of 1 to 128
+characters. Status text, the title and the working message are cut to 200
+characters and kept on one line.
+
+## Widgets
+
+```ts
+ctx.ui.setWidget("checks:summary", view, { placement: "aboveEditor" });
+ctx.ui.setWidget("checks:summary", undefined); // remove it
+```
+
+`placement` is `aboveEditor` (the default) or `belowEditor`. Widget and status
+keys are shared by every extension of a thread, so prefix them with your
+extension's name. In the terminal, an invalid view draws one warning line in
+its place; the app server sends nothing and reports it once per key as a
+warning.
+
+## Tool results and extension messages
+
+Put a view in `details.view` and clients draw it in place of the text output:
+
+```ts
+return { content: [{ type: "text", text: "parser: failed" }], details: { view } };
+
+knightcode.sendMessage({ customType: "checks", content: "2 failed", display: true, details: { view } });
+```
+
+Keep the text content meaningful: the model reads it, not the view, and a client
+that cannot draw the view shows the text. An invalid view is ignored and the
+text shows. In the terminal a tool's own `renderResult`, or a registered message
+renderer, still wins over the view.
+
+## Buttons and fields
+
+In a widget on the desktop app, buttons and fields are live. A press or a
+change reaches every handler the thread's extensions registered:
+
+```ts
+ctx.ui.onViewEvent?.((event) => {
+	if (event.widgetKey !== "checks:summary") return;
+	if (event.id === "rerun") runChecks();
+	if (event.id === "verbose" && typeof event.value === "boolean") verbose = event.value;
+	ctx.ui.setWidget("checks:summary", render());
+});
+```
+
+`event` is `{widgetKey, id, value?}`: `value` is a string for a text or select
+field, a boolean for a toggle, absent for a button. A field shows the value in
+the view, so answer a change by setting the widget again. `onViewEvent` is
+present only where widgets are interactive; the `?.` keeps the code working
+elsewhere. A handler that throws becomes a warning in the app.
+
+## Where views draw
+
+| Client | Widgets | Tool results and messages | Controls |
+| --- | --- | --- | --- |
+| Terminal | yes | yes | drawn as text |
+| Desktop app | yes | yes | live in widgets, disabled elsewhere |
+| RPC, JSON and print modes | no | no | no |
+
+[`examples/extensions/desktop-view.ts`](../examples/extensions/desktop-view.ts)
+puts all of it together. For the protocol side see
+[app-server.md](app-server.md#dialogs-and-extension-ui).

package/docs/desktop.md

@@ -7,8 +7,40 @@ configuration lives in the files the terminal reads (`settings.json`, `mcp.json`
 `tools.json`); the app's Settings edit those same files, so a change made in either place
 shows in both.
 
-The app is in development and not yet published. Phase S1 (threads, transcript, composer,
-approvals) is usable from a source checkout.
+Installers come from the GitHub releases tagged `desktop-v<version>`; none is published yet,
+so for now the app runs from a source checkout.
+
+## Installing
+
+Each installer carries its own `knightcode` binary as the app server, so nothing needs to be
+on `PATH`. None is signed by a recognised publisher yet:
+
+- Windows: run `KnightCode-<version>.Setup.exe`. It installs for your user only, into
+  `%LOCALAPPDATA%\KnightCodeDesktop`, with Start menu and desktop shortcuts; remove it from
+  Settings › Apps. SmartScreen says "Windows protected your PC" the first time: choose
+  More info, then Run anyway.
+- macOS: open the `.dmg` for your Mac (`arm64` for Apple silicon, `x64` for Intel) and drag
+  KnightCode to Applications. The app is signed ad hoc, not notarized, so the first launch
+  is refused: open System Settings › Privacy & Security and choose Open Anyway, or run
+  `xattr -dr com.apple.quarantine /Applications/KnightCode.app` once.
+- Linux: install the `.deb` (`sudo apt install ./knightcode-desktop_<version>_amd64.deb`) or
+  the `.rpm` (`sudo dnf install ./knightcode-desktop-<version>-1.x86_64.rpm`).
+
+Check a download against the release's `SHA256SUMS`.
+
+## Updates
+
+- Windows: the app checks at launch and every 4 hours, and downloads a newer version in
+  the background. An Update button then shows at the right of the title bar, and Settings ›
+  About offers Restart to update; if threads are running it asks first, since quitting
+  interrupts them. Help › Check for Updates… checks now.
+- macOS: the app checks the same way and shows Update when a newer version exists, which
+  opens the release page to download it (it cannot install itself while it is signed ad
+  hoc). KnightCode › Check for Updates… checks now.
+- Linux: install the newer `.deb` or `.rpm` over the old one.
+
+Settings › About shows the app's and the app server's versions and when the app last
+checked.
 
 ## Running from source
 
@@ -25,7 +57,22 @@ quoting, so a path containing spaces (`C:\Program Files\...`) cannot be named; p
 on `PATH` and give the bare name. A packaged build ignores it and runs only its bundled binary.
 
 Server output goes to `app-server.log` in the app's logs folder (`%APPDATA%\KnightCode\logs`
-on Windows, `~/Library/Logs/KnightCode` on macOS, `~/.config/KnightCode/logs` on Linux).
+on Windows, `~/Library/Logs/KnightCode` on macOS, `~/.config/KnightCode/logs` on Linux). At
+5 MiB it moves to `app-server.log.1`, the older ones to `.2` up to `.4`, so at most five files
+are kept. Settings › About › Show logs opens the folder.
+
+To build the installers for this machine, stage the app server and make them; the
+installers land in `apps/desktop/out/make/`:
+
+```sh
+bun run apps/desktop/scripts/stage-server.ts   # builds knightcode for this platform
+cd apps/desktop && bun run make
+```
+
+The end-to-end tests launch the production build that packaging leaves in
+`apps/desktop/.vite/`, against an app server whose model is scripted
+(`packages/cli/test/fixtures/faux-app-server.ts`): run `bun run package`, then
+`bun run test:e2e`.
 
 ## What works
 
@@ -64,10 +111,62 @@ on Windows, `~/Library/Logs/KnightCode` on macOS, `~/.config/KnightCode/logs` on
     added, as `knightcode config` does. Built-in extensions are always on and not listed.
 
   Changes apply to threads that start or resume afterwards.
+- Side panel: Changes shows the thread's diff; the separators between hunks expand to
+  the unchanged lines around them. A file named in a tool row or in Changes opens in a
+  read-only tab beside it, at the line the tool read or changed. A tab opened in passing
+  is italic and the next one replaces it; double-click it to keep it. Each thread keeps
+  its own tabs, at most 12 files.
+- Open in: a file tab's Open button sends the file, at its line, to an editor, terminal
+  or IDE found on your machine, or to the system's default app or file manager. The app
+  remembers the last choice, per project and overall.
+- Terminal: Ctrl+\` opens a terminal in the thread's folder, in a region under the chat and
+  the side panel; Ctrl+J shows or hides it, and its top edge resizes it. The + menu offers
+  the shells found (PowerShell, Windows PowerShell, Command Prompt, Git Bash and WSL on
+  Windows; your login shell elsewhere), and the last one picked is the default. Terminals
+  belong to their thread: they keep running when the window reloads or another thread
+  opens, and end when you close them, archive or delete the thread, or quit. Copy needs a
+  selection (Ctrl+C, Ctrl+Shift+C or Ctrl+Insert); paste with Ctrl+V, Ctrl+Shift+V or
+  Shift+Insert (on macOS, Cmd+C and Cmd+V). Links in the output open in your browser.
+- Preview: the side panel's + (Ctrl+T) opens a page in a preview tab, http and https only
+  (`localhost:3000` is enough). A link to a local server in a message opens there too.
+  Each thread keeps its own cookies and storage, cleared when the thread is deleted; pages
+  get no permissions, and downloads ask where to save. Annotate (Ctrl+Shift+.) lets you
+  drag over part of the page to attach it to the message you are writing, with the page's
+  address.
+- MCP Apps: a tool from an [MCP server](mcp.md#mcp-apps) that has an app shows it in the
+  thread, under the turn's work. The app can call its own server's tools (asking you
+  first for one that may change things), send a follow-up message once you confirm it,
+  and open full screen in the side panel.
 - Archived threads: search, unarchive, or delete for good.
 - Command palette (Ctrl+K): actions and threads in one search.
 - Quitting while threads run asks first.
 
+## Extensions
+
+Extensions load in desktop threads as they do in the terminal (`ctx.mode` is
+`"desktop"`). What they show appears in the app:
+
+- Dialogs (`select`, `confirm`, `input`, `editor`) and `ask_user`'s questions take
+  the composer's place; notices (`notify`) show as toasts.
+- Statuses (`setStatus`) are chips in the thread's header, with the full text on
+  hover.
+- `setTitle` names the window while the thread is open; the thread's own name stays.
+- `setWorkingMessage` replaces the "Thinking" text while a turn waits on the model,
+  and `setWorkingVisible(false)` hides it.
+- Widgets (`setWidget`) show in a panel above the composer, lines in a monospace
+  font, at most 10 per widget. A widget can be a
+  [declarative view](declarative-views.md) whose buttons and fields work: a press
+  reaches the extension's `ctx.ui.onViewEvent` handler.
+- A tool result or an extension message with a view in `details.view` shows the view
+  in its row.
+
+Terminal-only UI does not draw: widget factories, `custom()` components, header
+and footer components, raw terminal input, the working indicator and editor access
+(`setEditorText`, `getEditorText`, `pasteToEditor`, custom editors and autocomplete).
+The app server notes each such call once per thread in `app-server.log`. A widget or
+status the server refuses (an invalid view, too large, too many) shows a warning
+once. The protocol side is in [app-server.md](app-server.md#dialogs-and-extension-ui).
+
 ## Keyboard shortcuts
 
 | Action | Default |
@@ -79,10 +178,16 @@ on Windows, `~/Library/Logs/KnightCode` on macOS, `~/.config/KnightCode/logs` on
 | Toggle the sidebar | Ctrl+B |
 | Back / forward | Alt+Left / Alt+Right |
 | Archive the thread | Ctrl+Shift+A |
+| Close the side panel's file tab | Ctrl+Shift+W |
+| Open a terminal / show or hide them | Ctrl+\` / Ctrl+J |
+| Next / previous terminal | Ctrl+PageDown / Ctrl+PageUp |
+| Open a preview / focus its address bar | Ctrl+T / Ctrl+L |
+| Annotate the preview | Ctrl+Shift+. |
 | Send | Enter |
 | New line | Shift+Enter |
 | Steer the running turn | Ctrl+Enter |
 | Stop the running turn | Escape (empty composer) |
 | Allow / deny an approval | Enter / Escape (card focused) |
 
-On macOS, Ctrl is Cmd. Settings › Keyboard shortcuts lists every binding.
+On macOS, Ctrl is Cmd, except in Ctrl+\` and Ctrl+PageDown/PageUp, which stay Control.
+Settings › Keyboard shortcuts lists every binding.

package/docs/docs.json

@@ -121,6 +121,10 @@
               "title": "Build Extensions",
               "path": "extensions.md"
             },
+            {
+              "title": "Draw Declarative Views",
+              "path": "declarative-views.md"
+            },
             {
               "title": "Add Custom Providers",
               "path": "custom-provider.md"

package/docs/environment-variables.md

@@ -90,6 +90,7 @@ These variables are read by KnightCode itself:
 | `KNIGHTCODE_CACHE_RETENTION` | Set to `long` for extended provider prompt caching where supported |
 | `KNIGHTCODE_SHARE_VIEWER_URL` | Override the base URL used by `/share` |
 | `KNIGHTCODE_BUG_ENDPOINT` | Override the origin `/bug` uploads go to; default is `https://remote.knightcode.dev` |
+| `KNIGHTCODE_CLEAR_ON_SHRINK` | Set to `1` to clear empty rows when rendered content shrinks; the `terminal.clearOnShrink` setting takes precedence. See [Settings](settings.md) |
 | `KNIGHTCODE_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
 | `KNIGHTCODE_CLIPBOARD_OSC52` | Set to `1` to also send copied text to the terminal with OSC 52 after the local clipboard write, as KnightCode does over SSH. Use it when a remote client reaches KnightCode without SSH variables, such as a multiplexer attached from another machine or a remote IDE daemon |
 | `KNIGHTCODE_HYPERLINKS` | Override OSC 8 hyperlink detection with `1`, `0`, or `auto` |

package/docs/extensions.md

@@ -262,6 +262,8 @@ A tool can run other tools with `ctx.executeTool(name, args, { signal, onUpdate
 
 See [`hello.ts`](../examples/extensions/hello.ts), [`todo.ts`](../examples/extensions/todo.ts), [`dynamic-tools.ts`](../examples/extensions/dynamic-tools.ts), and [`truncated-tool.ts`](../examples/extensions/truncated-tool.ts).
 
+A tool registered under a built-in name replaces the built-in tool. Re-registering a copy of `createBashToolDefinition(cwd)` or `createPowerShellToolDefinition(cwd)` with object spread, for example to change its rendering, keeps [background commands](usage.md#background-commands): the session runs them with its own background manager as long as the copy keeps the built-in `execute` and `parameters`. A copy that replaces `execute`, such as one that routes commands to a sandbox or a remote host, runs commands in the foreground only, and `task_stop` is not declared for it.
+
 ### 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:
@@ -315,7 +317,7 @@ knightcode.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 `knightcode.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#other-mcp-extensions)), each registration is reported as an extension error. Other MCP extensions can connect registered servers too: read them with `knightcode.getMcpServers()` on `session_start` and handle the `mcp_servers_change` event for later changes.
+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 `knightcode.getMcpServers()` on `session_start` and handle the `mcp_servers_change` event for later changes.
 
 <a id="extensioncontext"></a>
 <a id="extensioncommandcontext"></a>
@@ -387,8 +389,10 @@ Use `ctx.ui.custom()` only when the interaction needs its own rendering and inpu
 See [Terminal UI](tui.md) for component, focus, overlay, theme, and performance guidance.
 
 Extensions load in interactive, RPC, JSON, print, and desktop modes.
-Desktop mode currently has no extension UI (`hasUI` is false); terminal
-components remain unavailable even when desktop dialogs are added.
+Desktop mode draws dialogs, notices, statuses, titles, working text and widgets,
+including [declarative views](declarative-views.md) with live buttons and
+fields; terminal components (widget factories, `custom()`, header, footer) do not
+draw there. See [Desktop App](desktop.md#extensions).
 Interactive mode provides the complete terminal UI. The [DOOM overlay example](../examples/extensions/doom-overlay/) uses a custom overlay component to render a game frame by frame:
 
 <p align="center"><img src="images/doom-extension.png" alt="The DOOM overlay example running over a KnightCode session" width="750"></p>

package/docs/keybindings.md

@@ -164,6 +164,7 @@ On native Windows, `app.suspend` has no default because Windows terminals do not
 | Keybinding id | Default | Description |
 |--------|---------|-------------|
 | `app.tools.expand` | `ctrl+o` | Collapse or expand tool output |
+| `app.tools.background` | `ctrl+b` | Move running shell commands to the [background](usage.md#background-commands). Only while a command runs; otherwise the key reaches the editor, where `ctrl+b` moves the cursor left |
 | `app.message.copy` | `ctrl+x` | Copy the selected message in `/tree`; otherwise copy the active fullscreen text selection when `fullscreenCopyOnSelect` is disabled, falling back to the last assistant message. On OAuth sign-in screens, copy the sign-in URL |
 | `app.message.followUp` | `alt+enter` (`ctrl+q` on Windows and WSL) | Queue follow-up message |
 | `app.message.dequeue` | `alt+up` (`alt+q` on Windows and WSL) | Restore queued messages to editor |

package/docs/mcp.md

@@ -243,13 +243,27 @@ When a connected server offers [resources](https://modelcontextprotocol.io/speci
 
 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 KnightCode does not render them. Resource icons are also omitted.
+Resources for MCP Apps, identified by `ui://` URIs or `text/html;profile=mcp-app`, are omitted from these tools: the desktop app draws them (see [MCP Apps](#mcp-apps)). 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.
 
+## MCP Apps
+
+A server can give a tool an interactive view with the MCP Apps extension (`io.modelcontextprotocol/ui`, Stable 2026-01-26): the tool names a `ui://` resource in `_meta.ui.resourceUri`, and the resource is an HTML document of type `text/html;profile=mcp-app`. The [desktop app](desktop.md) draws it in the tool's row. The terminal draws no apps, so KnightCode tells servers it supports them only in the desktop, and elsewhere servers answer with their text fallback.
+
+In the desktop:
+
+- A tool with an app is declared to the model whatever the server's exposure, and it cannot be called from codemode scripts: a call drawn as an app must be the model's own, which the session keeps. A tool you configured as `hidden` stays hidden and draws no app.
+- A tool whose `_meta.ui.visibility` leaves out `"model"` is not declared to the model, whatever its exposure and whether or not it has an app of its own. An app can still call it.
+- An app calls only tools of its own server whose visibility includes `"app"`. In Full access its calls run. In Ask and Auto-edit, a call to a tool not annotated `readOnlyHint` asks you first, naming the server and the tool. An app's calls do not go through the session's tool pipeline, so extension `tool_call` and `tool_result` handlers, permission gates included, do not see them.
+- An app can send a follow-up message to the thread after you confirm it, open http and https links in your browser, and ask to be shown full screen in the side panel. It cannot update the model's context.
+- The app runs in a sandboxed frame on its own origin, with no permissions (no camera, microphone, location or clipboard). It reaches the network only through the domains its resource declares in `_meta.ui.csp`; a declaration that is not a list of host sources is refused and the app does not load.
+
+[`examples/mcp-app/server.mjs`](../examples/mcp-app/server.mjs) is a small stdio server with a counter app: one tool that shows the app, one only the app may call, and one read-only tool.
+
 ## Permissions
 
-Every MCP call passes through KnightCode'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`.
+Every MCP call the model makes passes through KnightCode's tool pipeline. Extension `tool_call` and `tool_result` handlers, including permission gates, therefore apply to MCP tools; an [MCP App](#mcp-apps)'s own calls are the exception. Calls made from codemode scripts carry the codemode call ID as `parentToolCallId`.
 
 `knightcode.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.
 

package/docs/message-types.md

@@ -140,7 +140,7 @@ interface AssistantMessage {
 }
 ```
 
-`responseModel` records a concrete provider response model when it differs from the requested model. `responseId`, `providerThinkingLevel`, `thinkingLevel`, `diagnostics`, and `rawStopReason` preserve provider or runtime details.
+`responseModel` records the concrete model reported by the provider, when the provider reports one. It may equal the requested model. `responseId`, `providerThinkingLevel`, `thinkingLevel`, `diagnostics`, and `rawStopReason` preserve provider or runtime details.
 
 `"pending"` is used for a partial assistant message while it streams. The completed message in `message_end` has a terminal stop reason, and KnightCode does not persist `"pending"` assistant messages in session JSONL.
 

package/docs/models-configuration.md

@@ -185,3 +185,12 @@ Also applies to `azure-openai-responses` and `openai-codex-responses`.
 | Field | Type | Default | Description |
 |---|---|---|---|
 | `supportsMidConvoSystemMessages` | boolean | `false` | Whether the exact model accepts system messages after the conversation has started. When false, later system messages are folded into the leading system message. |
+
+### `typesafe-system-one`
+
+Also applies to `cloudflare-workers-ai-system-one`.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `imageInput` | `"assets" \| "images" \| "state-image-urls"` |  | How the service takes classifier images. "assets" sends TypeSafe's assets map (PNG and JPEG) and references the images from the state, as TypeSafe and Jev on Workers AI expect. "images" sends Clef's images list of data URLs (PNG, JPEG, and WebP, at most four), as Clef on Workers AI expects. "state-image-urls" places image_url parts before the state, as OpenRouter expects; OpenRouter drops assets without an error. Auto-detected from the provider, baseUrl, and model ID. Classifier models read it from the provider-level compat; models and modelOverrides entries apply to chat models only. |
+| `sendImageOptInHeader` | boolean |  | Whether requests with images send the TypeSafe-Danger-Zone-Images: true header, which TypeSafe's own API requires for its experimental image input. Defaults to true for the typesafe-system-one API unless the model is detected as OpenRouter. |

package/docs/models.md

@@ -141,20 +141,20 @@ Compatibility settings should describe verified differences in the endpoint's re
 
 ## Use classifier models
 
-Classifier models do not chat. They answer typed questions about JSON state: pick one of several choices, answer yes or no, or give a score, each with probabilities. KnightCode includes TypeSafe's Jev model from these providers, Cloudflare's Clef and Clef Flash models from Workers AI, and OpenAI's GPT-6 Luna through the [Decisions API](https://developers.openai.com/api/docs/guides/decisions):
+Classifier models do not chat. They answer typed questions about JSON state: pick one of several choices, answer yes or no, or give a score, each with probabilities. KnightCode includes TypeSafe's Jev model from these providers, Cloudflare's Clef, Clef Flash, and Clef Omni models from Workers AI and OpenRouter, and OpenAI's GPT-6 Luna through the [Decisions API](https://developers.openai.com/api/docs/guides/decisions):
 
 | Provider | Model IDs | Authentication |
 |---|---|---|
 | `typesafe` | `jev-latest` | `TYPESAFE_API_KEY` |
-| `openrouter` | `typesafe/jev-1.13`, `~typesafe/jev-latest` | `OPENROUTER_API_KEY` or `/login` |
-| `cloudflare-workers-ai` | `typesafe/jev`, `@cf/cloudflare/clef`, `@cf/cloudflare/clef-flash` | `CLOUDFLARE_API_KEY` and `CLOUDFLARE_ACCOUNT_ID` |
+| `openrouter` | `typesafe/jev-1.13`, `typesafe/jev-1.14`, `~typesafe/jev-latest`, `cloudflare/clef`, `cloudflare/clef-flash`, `cloudflare/clef-omni` | `OPENROUTER_API_KEY` or `/login` |
+| `cloudflare-workers-ai` | `typesafe/jev`, `typesafe/jev-1.14.0`, `@cf/cloudflare/clef`, `@cf/cloudflare/clef-flash`, `@cf/cloudflare/clef-omni` | `CLOUDFLARE_API_KEY` and `CLOUDFLARE_ACCOUNT_ID` |
 | `vercel-ai-gateway` | `typesafe-ai/jev` | `AI_GATEWAY_API_KEY` |
 | `opencode` | `jev-1.13`, `jev-1.13-free` | `OPENCODE_API_KEY` |
 | `openai` | `gpt-6-luna` | `OPENAI_API_KEY` |
 
 A [llama.cpp router](llama-cpp.md#classification) lists decision models as native classifiers, and also lists each chat model as a classifier.
 
-OpenAI's Decisions API needs an API key. ChatGPT sign-in does not work with it, so `gpt-6-luna` is not listed as available while `openai` is logged in through `/login`, even when `OPENAI_API_KEY` is set; log out of `openai` to use the key. GPT-6 Luna also judges images passed in `images` (see [Codemode](codemode.md#classify)); other classifier models return an error for them. The API rejects inputs above 922K tokens, but requests that run longer than about five seconds, currently above roughly 600K input tokens, fail with a gateway timeout.
+OpenAI's Decisions API needs an API key. ChatGPT sign-in does not work with it, so `gpt-6-luna` is not listed as available while `openai` is logged in through `/login`, even when `OPENAI_API_KEY` is set; log out of `openai` to use the key. The API rejects inputs above 922K tokens, but requests that run longer than about five seconds, currently above roughly 600K input tokens, fail with a gateway timeout.
 
 Classifier models do not appear in `/model`. The [classifier gate](usage.md#classifier-gate) uses one to screen risky tool calls. The model reaches them through the [`codemode`](cli.md#enable-codemode) tool, which is off unless an MCP server turned it on. Enable it with `"defaultTools": ["+codemode"]` in [settings](settings.md#tools). Scripts then list classifier models with `models.getAvailableOfType("classifier")` and call `models.classify(model, { state, questions })`:
 
@@ -175,6 +175,10 @@ return result.answers;
 
 [Codemode](codemode.md#classify) describes the question and answer types.
 
+Classifier models whose `input` includes `"image"` also judge images passed in `images`; other classifier models return an error for them. Image input works with GPT-6 Luna, with Jev from `typesafe` and `cloudflare-workers-ai`, with Clef from `cloudflare-workers-ai`, and with the OpenRouter models whose catalog lists image input. Jev takes PNG and JPEG images, and image input is experimental on TypeSafe's own API. Clef takes PNG, JPEG, and WebP images, at most four per request. Jev from `vercel-ai-gateway` and `opencode` takes text only.
+
+Each System One service takes images in its own request format, set by the model's `compat.imageInput`. Built-in models set it, so overriding a provider's `baseUrl` keeps it. A custom provider that proxies another service's classifiers sets it in its provider-level `compat` in `models.json` (see [System One compatibility](models-configuration.md#typesafe-system-one)). OpenRouter in particular answers requests in TypeSafe's format without an error but drops the images.
+
 When the service reports token counts, as all System One services do, `result.usage` carries them with their cost. KnightCode adds the usage of a script's classifier calls to the `codemode` tool result, so it counts toward the session cost in the footer and `/session`. The cost uses the model's catalog price; models without one, such as TypeSafe's direct `jev-latest`, report tokens at no cost.
 
 Extensions call classifiers through `ctx.modelRegistry.classify()`, without codemode. [Virtual models](virtual-models.md#route-requests) can use them to route requests; see the `jev-router.ts` example.

package/docs/packages.md

@@ -16,6 +16,8 @@ knightcode install ./local-package
 
 `knightcode list` shows configured packages. Use `knightcode remove <source>` to remove one and `knightcode update --extensions` to reconcile package installations. See [Command Line](cli.md#package-commands) for every package command and option.
 
+If a configured package fails to install at startup, for example because npm cannot reach the registry, KnightCode warns about it, skips that package's resources, and keeps running. KnightCode tries to install it again on the next start or `/reload`. `knightcode install` and `knightcode update --extensions` still report the failure and exit non-zero.
+
 Personal installs are written to `~/.knightcode/agent/settings.json`. Add `--local` or `-l` to write the package declaration to `.knightcode/settings.json`. KnightCode reads declarations from that file only after project trust is granted.
 
 Project packages are installed and loaded only after project trust is resolved. Packages can execute extension code and can include skills that instruct the model to run programs. Review third-party package source before installing it. Review project package declarations before granting project trust.

package/docs/plan-mode.md

@@ -69,6 +69,10 @@ to the highlighted choice; on an implement choice it is sent with the
 approval, and on Keep planning it is sent as feedback. Escape keeps planning. Review does not open automatically on resume. Session replacement, tree navigation, or a new run cancels an open
 picker. An action rechecks the shown revision before changing state.
 
+The desktop app opens review by itself too, asking "Implement this plan?":
+Yes, implement this plan; Implement in a new thread; or Exit planning.
+A fresh session is named after the plan's first line of prose.
+
 RPC reports a submission notification; `/plan` opens its review selection.
 JSON mode adds no extra output:
 the submission tool-call events contain the Markdown.

package/docs/settings.md

@@ -107,7 +107,7 @@ See [Compaction Reference](compaction.md) for trigger, summarization, and valida
 | `showHardwareCursor` | boolean | `false` | Use the terminal cursor instead of KnightCode's drawn cursor. KnightCode still positions it for input methods. |
 | `terminal.showImages` | boolean | `true` | Display inline images when supported. |
 | `terminal.imageWidthCells` | number | `60` | Preferred inline image width in terminal cells. |
-| `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when rendered content shrinks. |
+| `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when rendered content shrinks. When unset, `KNIGHTCODE_CLEAR_ON_SHRINK=1` enables it. |
 | `terminal.showTerminalProgress` | boolean | `false` | Show OSC 9;4 progress in the terminal tab. |
 | `terminal.hyperlinks` | `boolean \| "auto"` | `"auto"` | Override OSC 8 hyperlink detection. |
 | `terminal.images` | `"kitty" \| "iterm2" \| "auto" \| false` | `"auto"` | Override inline-image protocol detection. |
@@ -178,8 +178,8 @@ handed off by accident, and nothing is created through a symlink or junction.
 |---|---|---|---|
 | `transport` | `"auto" \| "sse" \| "websocket" \| "websocket-cached"` | `"auto"` | Preferred transport for AI providers that support multiple transports. |
 | `httpProxy` | string | None | Proxy URL applied as `HTTP_PROXY` and `HTTPS_PROXY` for KnightCode-managed HTTP clients. **Can only be set in agent-directory settings.** |
-| `httpIdleTimeoutMs` | number | `300000` | HTTP header and body idle timeout in milliseconds. Set to `0` to disable. |
-| `websocketConnectTimeoutMs` | number | `15000` | WebSocket connection timeout in milliseconds. Set to `0` to disable. |
+| `httpIdleTimeoutMs` | number \| `"disabled"` | `300000` | HTTP header and body idle timeout in milliseconds. Set to `0` or `"disabled"` to disable. |
+| `websocketConnectTimeoutMs` | number \| `"disabled"` | `15000` | WebSocket connection timeout in milliseconds. Set to `0` or `"disabled"` to disable. |
 | `retry.enabled` | boolean | `true` | Enable automatic agent-level retry for transient failures. |
 | `retry.maxRetries` | number | `3` | Maximum agent-level retry attempts. |
 | `retry.baseDelayMs` | number | `2000` | Initial exponential-backoff delay in milliseconds. |

package/docs/slash-commands.md

@@ -64,8 +64,10 @@ Review a session before exporting or sharing it. Sessions can contain prompts, t
 | Command | Description |
 |---|---|
 | `/trust` | Save a project trust decision for future KnightCode processes |
+| `/mcp` | Manage MCP servers: sign in, reconnect, enable or disable, and change exposure |
 | `/reload` | Reload keybindings, extensions, skills, templates, themes, and context files |
 | `/hotkeys` | Show active keyboard shortcuts |
+| `/tasks` | List [background commands](usage.md#background-commands), show their output, and stop them |
 | `/changelog` | Show changelog entries |
 | `/quit` | Quit KnightCode |
 

package/docs/usage.md

@@ -41,6 +41,7 @@ You can send more input while KnightCode is working:
 | Adjust the current task | Type a message and press `Enter` |
 | Add work after the current task | Type a message and press `Alt+Enter` |
 | Return queued messages to the editor | Press `Alt+Up` |
+| Let a long command run on while KnightCode continues | Press `Ctrl+B` (see [Background commands](#background-commands)) |
 | Stop the current task | Press `Escape` |
 
 A message sent with `Enter` waits until the current response and its tool calls finish, then guides the next response. A follow-up sent with `Alt+Enter` waits until KnightCode finishes the current task. Aborting returns queued messages to the editor.
@@ -83,6 +84,28 @@ Prefix a command with `!` to run it and include its output in the conversation:
 
 Use `!!` when you want to run a command without sending its output to the model.
 
+## Background commands
+
+KnightCode can start a command in the background, and decides per command whether to. It does so for work that takes long or never exits, such as a dev server, a file watcher, or a long build or test run. The tool call returns at once and the command keeps running while KnightCode works, across turns. When the command exits, KnightCode is told how it ended, with the last lines of its output, and carries on from there; you see the same notice in the transcript.
+
+Press `Ctrl+B` while a command runs in the foreground to move it to the background. The same process keeps running; nothing starts again. The key works only while a command runs; otherwise `Ctrl+B` moves the cursor as usual.
+
+While commands run, a pill above the footer counts them: `1 shell`, `3 shells`. Press `Down` in an empty editor to select it and `Enter` to open the **Background tasks** list, or click it; `Esc` or `Up` returns to the editor. `/tasks` opens the same list. With a single command it opens on that command's details.
+
+| Key | In the list | In a command's details |
+|-----|-------------|------------------------|
+| `Up`/`Down` | Choose a command | |
+| `Enter` | Show its details | Close |
+| `x` | Stop the chosen command | Stop it |
+| `Left` | Close | Back to the list |
+| `Esc` | Close | Close |
+
+A command's details show its status and exit code, runtime, command, and the last 10 lines of its output as it arrives. Its output is also written to a file, and KnightCode reads that file when it needs the output sooner. If writing that file fails, for example on a full disk, the file is incomplete and KnightCode is told so. KnightCode stops a command with the `task_stop` tool, which is on whenever `bash` or `powershell` is.
+
+A background command ends when it exits, when KnightCode or you stop it, or when the session ends: quitting, `/new`, `/resume`, and `/fork` stop it, while `/reload` keeps it. Resuming or forking a session does not start its commands again; with your next message KnightCode is told that they were stopped. A `timeout` given with the command still stops it in the background. A command that writes more than 1 GiB of output is stopped, and at most 32 run at once.
+
+A background command has no input: one that asks a question reads end-of-file. If you press `Escape` to stop the current task, a command that ends afterwards is recorded in the conversation without starting KnightCode again; the next message you send re-arms that. In print and JSON modes KnightCode does not exit while a command it started in the background is running, so it can act on how the command ended.
+
 ## Web Tools
 
 Two tools give the agent read access to the web. Both ship disabled; turn them on with `/tools`.

package/examples/extensions/README.md

@@ -32,6 +32,7 @@ cp permission-gate.ts ~/.knightcode/agent/extensions/
 |-----------|-------------|
 | `todo.ts` | Todo list tool + `/todos` command with custom rendering and state persistence |
 | `hello.ts` | Minimal custom tool example |
+| `desktop-view.ts` | Declarative views: a widget with a live toggle and button (`ctx.ui.onViewEvent`), and a tool result drawn as a table |
 | `question.ts` | Demonstrates `ctx.ui.select()` for asking the user questions with custom UI |
 | `questionnaire.ts` | Multi-question input with tab bar navigation between questions |
 | `tool-override.ts` | Override built-in tools (e.g., add logging/access control to `read`) |