@knightcodeai/cli 0.18.4 → 0.20.0

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/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

@@ -2,9 +2,10 @@
 
 The KnightCode desktop app is an Electron window over the [app server](app-server.md). It
 runs one `knightcode app-server` process and every window talks to it, so the desktop and
-the terminal share sessions, settings, credentials and extensions. Nothing about the agent
-is configured in the app itself: models, approval defaults and extensions come from your
-`settings.json`, the same file the terminal reads.
+the terminal share sessions, settings, credentials and extensions. The agent's
+configuration lives in the files the terminal reads (`settings.json`, `mcp.json` and
+`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.
@@ -48,11 +49,51 @@ on Windows, `~/Library/Logs/KnightCode` on macOS, `~/.config/KnightCode/logs` on
   a card with the decisions the server offers; Enter allows once, Escape denies, and Deny
   can tell KnightCode why. Full access asks once per thread, and Settings can hide it.
 - Settings: send key, queue or steer, theme (System, Light, Dark), default model, signing
-  in to and out of providers, keyboard shortcuts, versions and logs.
+  in to and out of providers, keyboard shortcuts, versions and logs. Under Coding:
+  - Configuration: the agent's `settings.json` keys `/settings` offers (reasoning, compaction,
+    steering, images, transport and timeouts, cache warming, project trust, updates), and
+    per-model reasoning, for the user or for one trusted project. A row set in the file being
+    edited has a reset button. Keys without a row are one click away in the file.
+  - Tools: the KnightCode tools `/tools` manages (web fetch, web search with its provider and
+    Brave key, ask user, scratchpad, classifier gate with its model), the tools new threads
+    start with (`defaultTools`), and codemode.
+  - MCP servers: add, remove, turn on or off and set the exposure of the servers in the user's
+    or a trusted project's `mcp.json`, as `/mcp` and `knightcode mcp` do. Signing in to a
+    server and its live status stay with `/mcp` in a thread.
+  - Extensions & skills: load or skip each extension, skill, prompt template and theme you
+    added, as `knightcode config` does. Built-in extensions are always on and not listed.
+
+  Changes apply to threads that start or resume afterwards.
 - 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 |

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/extensions.md

@@ -387,8 +387,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/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/settings.md

@@ -119,6 +119,59 @@ See [Compaction Reference](compaction.md) for trigger, summarization, and valida
 
 See [Themes](themes.md) and [Terminal Setup](terminal-setup.md) for format and platform details.
 
+## Worktrees
+
+Worktree settings belong to the user: they are read from the agent-directory
+settings file only, never from a project's.
+
+| Setting | Type | Default | Description |
+| --- | --- | --- | --- |
+| `worktrees.root` | string | `<agent dir>/worktrees` | Absolute directory that holds managed worktrees as `<root>/<4 hex digits>/<repository name>`. Worktrees made under an earlier root are no longer managed. |
+| `worktrees.autoDelete` | boolean | `true` | Archiving a thread deletes its worktree, and the least recently used worktrees past `worktrees.keep` are pruned. Each deletion first keeps a snapshot under `refs/knightcode/snapshots/`. |
+| `worktrees.keep` | number | `15` | Managed worktrees kept before pruning starts. |
+| `worktrees.fetchBeforeCreate` | boolean | `false` | Fetch the base's remote before each new worktree. |
+| `worktrees.branchPrefix` | string | `"kc/"` | Prefix of the branch a handoff to the main checkout creates. |
+
+### Environments
+
+A project's environments live in `.knightcode/environments.json`, which can be
+committed:
+
+```json
+{
+  "version": 1,
+  "environments": [
+    {
+      "name": "node",
+      "setup": { "default": "cd \"$KNIGHTCODE_WORKTREE_PATH\" && npm ci" },
+      "cleanup": { "default": "rm -rf \"$KNIGHTCODE_WORKTREE_PATH/.cache\"" },
+      "actions": [{ "name": "Test", "command": { "default": "npm test" } }]
+    }
+  ]
+}
+```
+
+Each script has `default`, `macos`, `linux` and `windows` variants; the
+platform's wins. Scripts run in bash on every platform (Git Bash on Windows, or
+the `shellPath` setting), so one `default` usually covers all three; a platform
+variant is for a command that differs. The setup script runs when a worktree is
+created and the cleanup script before one is deleted, both at the project root,
+with
+`KNIGHTCODE_SOURCE_TREE_PATH` (the checkout the worktree came from) and
+`KNIGHTCODE_WORKTREE_PATH` (the worktree) set. Since they start in the main
+checkout, work on the worktree through `KNIGHTCODE_WORKTREE_PATH`, as the
+example does: a bare `npm ci` would install into the main checkout. A failing setup keeps the
+worktree and marks it `setupFailed`; a failing cleanup is a warning. An
+untrusted project's scripts never run. `actions` are for the desktop app's
+toolbar.
+
+### `.worktreeinclude`
+
+Ignored files are not copied into a new worktree unless the repository root's
+`.worktreeinclude` (gitignore syntax) lists them, such as `.env`. A file is
+copied only if the worktree ignores it too, so it can never be committed or
+handed off by accident, and nothing is created through a symlink or junction.
+
 ## Network and retries
 
 | Setting | Type | Default | Description |

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`) |

package/examples/extensions/desktop-view.ts

@@ -0,0 +1,72 @@
+/**
+ * Desktop View - declarative views in a widget, answering presses, and in a tool result
+ *
+ * Shows a widget with a toggle and a button, drawn by the terminal and by the desktop app from the same data
+ * (docs/declarative-views.md). In the desktop app the controls are live: a press reaches `ctx.ui.onViewEvent`, and
+ * the extension answers by setting the widget again. The `check_summary` tool returns a table view, which both
+ * clients draw in place of the tool's text output.
+ *
+ * Usage:
+ *   knightcode --extension examples/extensions/desktop-view.ts
+ */
+
+import { Type } from "@knightcode/ai";
+import { defineTool, type ExtensionAPI, type ExtensionContext, type View } from "@knightcodeai/cli";
+
+const WIDGET = "desktop-view:checks";
+
+const checkSummary = defineTool({
+	name: "check_summary",
+	label: "Check summary",
+	description: "Summarize the project's checks as a table",
+	parameters: Type.Object({}),
+	async execute() {
+		const view: View = {
+			type: "table",
+			columns: ["check", "result"],
+			rows: [
+				["types", "passed"],
+				["tests", "2 failed"],
+			],
+		};
+		return { content: [{ type: "text", text: "types: passed\ntests: 2 failed" }], details: { view } };
+	},
+});
+
+export default function (knightcode: ExtensionAPI) {
+	// Per session: the factory runs again for every thread that loads the extension.
+	let verbose = false;
+	let resets = 0;
+
+	const show = (ctx: ExtensionContext) => {
+		const view: View = {
+			type: "stack",
+			children: [
+				{ type: "text", text: `Checks reset ${resets} time${resets === 1 ? "" : "s"}`, tone: "muted" },
+				{
+					type: "stack",
+					direction: "horizontal",
+					children: [
+						{ type: "field", id: "verbose", kind: "toggle", label: "Verbose", value: verbose },
+						{ type: "button", id: "reset", label: "Reset" },
+					],
+				},
+			],
+		};
+		ctx.ui.setWidget(WIDGET, view);
+	};
+
+	knightcode.registerTool(checkSummary);
+
+	knightcode.on("session_start", (_event, ctx) => {
+		if (!ctx.hasUI) return;
+		show(ctx);
+		// Only where widgets are interactive (the desktop app); the terminal draws the controls as text.
+		ctx.ui.onViewEvent?.((event) => {
+			if (event.widgetKey !== WIDGET) return;
+			if (event.id === "verbose" && typeof event.value === "boolean") verbose = event.value;
+			if (event.id === "reset") resets++;
+			show(ctx);
+		});
+	});
+}

package/examples/extensions/gondolin/index.ts

@@ -7,20 +7,20 @@
  * isolated to the VM.
  *
  * Setup:
- *   cd packages/coding-agent/examples/extensions/gondolin
+ *   cd packages/cli/examples/extensions/gondolin
  *   npm install --ignore-scripts
  *
  * Usage:
  *   cd /path/to/project
- *   knightcode -e /path/to/knightcode/packages/coding-agent/examples/extensions/gondolin
+ *   knightcode -e /path/to/knightcode/packages/cli/examples/extensions/gondolin
  *
  * Requirements:
- *   - Node.js >= 23.6.0 for @KnightCodeAI/gondolin
+ *   - Node.js >= 22.19.0 for @earendil-works/gondolin
  *   - QEMU installed (for example, `brew install qemu` on macOS)
  */
 
 import path from "node:path";
-import { RealFSProvider, VM } from "@KnightCodeAI/gondolin";
+import { RealFSProvider, VM } from "@earendil-works/gondolin";
 import type { ExtensionAPI, ExtensionContext } from "@knightcodeai/cli";
 import {
 	type BashOperations,
@@ -249,7 +249,6 @@ async function executeGondolinGrep(
 	const contextLines = params.context && params.context > 0 ? params.context : 0;
 	const effectiveLimit = Math.max(1, params.limit ?? DEFAULT_GREP_LIMIT);
 	const outputLines: string[] = [];
-	const details: GrepToolDetails = {};
 	let matchCount = 0;
 	let matchLimitReached = false;
 	let linesTruncated = false;
@@ -285,12 +284,14 @@ async function executeGondolinGrep(
 		signal,
 	);
 
-	if (matchCount === 0) return { content: [{ type: "text", text: "No matches found" }], details: undefined };
+	if (matchCount === 0) return { content: [{ type: "text", text: "No matches found" }], details: { matchCount: 0 } };
 
 	const rawOutput = outputLines.join("\n");
 	const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
 	const notices: string[] = [];
 	let output = truncation.content;
+	// The renderer counts output lines when this is missing, and context lines are not matches.
+	const details: GrepToolDetails = { matchCount };
 
 	if (matchLimitReached) {
 		details.matchLimitReached = effectiveLimit;
@@ -306,10 +307,7 @@ async function executeGondolinGrep(
 	}
 	if (notices.length > 0) output += `\n\n[${notices.join(". ")}]`;
 
-	return {
-		content: [{ type: "text", text: output }],
-		details: Object.keys(details).length > 0 ? details : undefined,
-	};
+	return { content: [{ type: "text", text: output }], details };
 }
 
 function sanitizeEnv(env: NodeJS.ProcessEnv | undefined): Record<string, string> | undefined {

package/examples/extensions/gondolin/package-lock.json

@@ -8,7 +8,7 @@
 			"name": "knightcode-extension-gondolin",
 			"version": "0.84.3",
 			"dependencies": {
-				"@KnightCodeAI/gondolin": "0.12.0"
+				"@earendil-works/gondolin": "0.14.0"
 			}
 		},
 		"node_modules/@cto.af/wtf8": {
@@ -20,32 +20,31 @@
 				"node": ">=20"
 			}
 		},
-		"node_modules/@KnightCodeAI/gondolin": {
-			"version": "0.12.0",
-			"resolved": "https://registry.npmjs.org/@KnightCodeAI/gondolin/-/gondolin-0.12.0.tgz",
-			"integrity": "sha512-BXbvzQKb5QmxY5NtthRDONJTu7+IDKbzqWGrJyyNXMP7N681Tx0Q9TK8pK1ba8nUvYQTipNJyGZOsJfYiZll1A==",
+		"node_modules/@earendil-works/gondolin": {
+			"version": "0.14.0",
+			"resolved": "https://registry.npmjs.org/@earendil-works/gondolin/-/gondolin-0.14.0.tgz",
+			"integrity": "sha512-MSw+EGcqFJeyKHdXEfm+nMRr74ytT4x8DGIohav0oPCHeVQAB9AajquM94cv2xqvIU3VDAaZZVC07IXsOY6OVQ==",
 			"license": "Apache-2.0",
 			"dependencies": {
 				"cbor2": "^2.3.0",
-				"node-forge": "^1.3.3",
 				"ssh2": "^1.17.0",
-				"undici": "^6.21.0"
+				"undici": "^6.29.0"
 			},
 			"bin": {
 				"gondolin": "dist/bin/gondolin.js"
 			},
 			"engines": {
-				"node": ">=23.6.0"
+				"node": ">=22.19.0"
 			},
 			"optionalDependencies": {
-				"@KnightCodeAI/gondolin-krun-runner-darwin-arm64": "0.12.0",
-				"@KnightCodeAI/gondolin-krun-runner-linux-x64": "0.12.0"
+				"@earendil-works/gondolin-krun-runner-darwin-arm64": "0.14.0",
+				"@earendil-works/gondolin-krun-runner-linux-x64": "0.14.0"
 			}
 		},
-		"node_modules/@KnightCodeAI/gondolin-krun-runner-darwin-arm64": {
-			"version": "0.12.0",
-			"resolved": "https://registry.npmjs.org/@KnightCodeAI/gondolin-krun-runner-darwin-arm64/-/gondolin-krun-runner-darwin-arm64-0.12.0.tgz",
-			"integrity": "sha512-ftDlusht4PcT7Y3TuPrZIKrCXy3isiBTVMvlXYK0pcud2uXY6uwFTGeunYgP+8ND/60ddb+MImqbfmkcK8B84A==",
+		"node_modules/@earendil-works/gondolin-krun-runner-darwin-arm64": {
+			"version": "0.14.0",
+			"resolved": "https://registry.npmjs.org/@earendil-works/gondolin-krun-runner-darwin-arm64/-/gondolin-krun-runner-darwin-arm64-0.14.0.tgz",
+			"integrity": "sha512-fvuhz1CZPaEbmXC0luZoXd1obAb0bjaaGJz33Jo63bhMlosYunAahItakh7cU0dnTlNFzufOSnpGOPqtuYjnpQ==",
 			"cpu": [
 				"arm64"
 			],
@@ -58,10 +57,10 @@
 				"gondolin-krun-runner": "bin/gondolin-krun-runner"
 			}
 		},
-		"node_modules/@KnightCodeAI/gondolin-krun-runner-linux-x64": {
-			"version": "0.12.0",
-			"resolved": "https://registry.npmjs.org/@KnightCodeAI/gondolin-krun-runner-linux-x64/-/gondolin-krun-runner-linux-x64-0.12.0.tgz",
-			"integrity": "sha512-RRYsgwe2r5ApKmFNy469QgwnyjAHpAs9XANdWpTd9ol4iUYOY3sX7e0xIooAKxd+ktxGI4N/xRWicwGen3D/Ow==",
+		"node_modules/@earendil-works/gondolin-krun-runner-linux-x64": {
+			"version": "0.14.0",
+			"resolved": "https://registry.npmjs.org/@earendil-works/gondolin-krun-runner-linux-x64/-/gondolin-krun-runner-linux-x64-0.14.0.tgz",
+			"integrity": "sha512-91iw4smoOH/yOoAuQS6N2UZOxqSFwRhtk8rTyrokXBoWiWcveAzg4kHvnLcm40ZlNrWwzIDFrere4bkZeGDQcA==",
 			"cpu": [
 				"x64"
 			],
@@ -134,15 +133,6 @@
 			"license": "MIT",
 			"optional": true
 		},
-		"node_modules/node-forge": {
-			"version": "1.4.0",
-			"resolved": "https://registry.npmjs.org/node-forge/-/node-forge-1.4.0.tgz",
-			"integrity": "sha512-LarFH0+6VfriEhqMMcLX2F7SwSXeWwnEAJEsYm5QKWchiVYVvJyV9v7UDvUv+w5HO23ZpQTXDv/GxdDdMyOuoQ==",
-			"license": "(BSD-3-Clause OR GPL-2.0)",
-			"engines": {
-				"node": ">= 6.13.0"
-			}
-		},
 		"node_modules/safer-buffer": {
 			"version": "2.1.2",
 			"resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
@@ -173,9 +163,9 @@
 			"license": "Unlicense"
 		},
 		"node_modules/undici": {
-			"version": "6.26.0",
-			"resolved": "https://registry.npmjs.org/undici/-/undici-6.26.0.tgz",
-			"integrity": "sha512-4yqz8a3n5HmGTlsbADNtr/dJlhkh/55Rq798G6ibiULcXbDtaLpTl1pvdqcbFfeoj3iSi52lePFM7h9H21cw/A==",
+			"version": "6.29.1",
+			"resolved": "https://registry.npmjs.org/undici/-/undici-6.29.1.tgz",
+			"integrity": "sha512-EvRlUt/QqAEvXdQeRMYUfwOQsfzpDztykrG2owGEE/rBOBoYv9uF39ZzsNDh4lTFHhTr2XOZjKkYgueD12ZmGA==",
 			"license": "MIT",
 			"engines": {
 				"node": ">=18.17"

package/examples/extensions/gondolin/package.json

@@ -14,6 +14,6 @@
 		]
 	},
 	"dependencies": {
-		"@KnightCodeAI/gondolin": "0.12.0"
+		"@earendil-works/gondolin": "0.14.0"
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knightcodeai/cli",
-  "version": "0.18.4",
+  "version": "0.20.0",
   "description": "KnightCode — a local, BYOK terminal coding agent powered by OpenRouter.",
   "type": "module",
   "repository": {