@knightcodeai/cli-linux-x64 0.6.2 → 0.8.0

package/bin/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @knightcodeai/cli
 
+## 0.8.0
+
+### Added
+
+- Added `allowedFallbackModels` to Anthropic model overrides in `models.json`, so you can choose which models the server may fall back to — or set an empty array to turn server-side fallback off.
+
+- Added webfetch and websearch tools — a page as pageable, greppable markdown, and results from DuckDuckGo or Brave Search — off until enabled with the new `/tools` command, which turns each built-in tool off, on for the session, or on by default, and for websearch also picks the provider and stores the Brave API key.
+
+### Changed
+
+- Changed the system prompt and tool set to live in the transcript instead of being rewritten behind it. A session records when its instructions changed or tools became available, resuming or moving between branches restores that state, and providers that support it keep their cached prompt prefix across the change. Extensions can replace individual prompt sections through `systemPromptOptions.sections`, and the deferred-tool loading path is replaced by mid-conversation tool additions on the models that accept them.
+
+- Changed a failed copy to say why: instead of a bare "Copy failed" flash, the message now names the missing clipboard backend — `wl-clipboard`, `xclip`/`xsel` or the Termux API package — and stays on screen for five seconds.
+
+### Fixed
+
+- Fixed a `user_bash` handler that throws or returns a malformed result silently falling back to the local shell — the command is now reported as failed instead of running somewhere the extension meant to prevent. A handler must return `undefined`, exactly one of `{ operations }` or `{ result }`, and nothing else.
+
+- Fixed Baseten requests to carry session-affinity headers so a conversation keeps hitting the same replica and benefits from automatic prompt caching.
+
+- Fixed Bedrock cost reporting to bill one-hour cache writes at their higher rate instead of charging every cache write at the five-minute rate.
+
+- Fixed a local copy reporting success when no clipboard backend actually took the text: the terminal-escape fallback now only counts in a remote session, where it is the terminal that owns the clipboard.
+
+- Fixed the package's public types so extension authors can import the event and result types their hooks receive, such as `ModelSelectEvent`, `ThinkingLevelSelectEvent` and the `*Result` types, instead of redeclaring them.
+
+- Fixed the thinking levels offered for Gemini models: they now follow the reasoning efforts each model actually advertises instead of a version-number guess, so newer Flash and Pro models expose their real low/medium/high range.
+
+- Fixed resuming a session by its exact ID reading every transcript in the session directory first, which made startup slow in directories with long histories.
+
+## 0.7.0
+
+### Added
+
+- Added a `knightcode-engine` binary: a headless local server that owns inference for the desktop IDE, with OpenAI-shaped chat and fill-in-the-middle endpoints. It shares the CLI's `auth.json`, so signing in to either product signs in to both.
+
+- Added reopening saved sessions to `knightcode-engine`, so the desktop IDE restores its threads after a restart instead of failing with "Loading or resuming sessions is not supported by this agent".
+
+  Its ACP agent now:
+
+  - loads a session, replaying its history;
+  - resumes, lists, deletes and forks saved sessions;
+  - lists extension commands, prompt templates and skills under `/`;
+  - after an engine restart, reopens a session it no longer holds and retries the prompt.
+
+- Added native deferred tool loading for Fireworks models on the Messages API. Name the loader tool `ToolSearch` or `tool_search` so Fireworks keeps the deferred schemas out of the cached tool prefix.
+
+- Added a /remote command that publishes the running session to the web for the signed-in account, with a phone-first app at remote.knightcode.dev that lists live and past sessions, opens every tool call, and runs slash commands in the terminal.
+
+### Fixed
+
+- Fixed the full-output file of a truncated `!` bash command sometimes being empty when read straight away: the command now finishes writing that file before its result, and the file's path, are returned.
+
+- Fixed the desktop IDE's open threads offering stale model choices after signing in or out: `knightcode-engine` now refreshes them when an account or the model catalog changes.
+
+- Fixed API keys in a project's `.env` showing up in the desktop IDE as signed-in providers that signing out could not remove: `knightcode-engine` no longer reads a `.env` or `bunfig.toml` from the directory the IDE was launched in.
+
+- Fixed `/` listing no commands in a new, loaded, resumed or forked thread in the desktop IDE: `knightcode-engine` sent the list before the IDE had registered the session, and the IDE dropped it.
+
+- Fixed errors from OpenAI-compatible providers on the Responses API always being labelled as OpenAI errors: the message now names the provider that actually failed.
+
+- Fixed Tab predictions in the desktop IDE repeating the code after the cursor: `knightcode-engine`'s `/v1/completions` now shows the model your code with the cursor marked in place, and strips code fences from the answer.
+
 ## 0.6.2
 
 ### Added

package/bin/docs/custom-provider.md

@@ -406,25 +406,31 @@ For providers with non-standard APIs, implement `streamSimple`. Study the existi
 
 ### Stream Pattern
 
-All providers follow the same pattern:
+All providers follow the same pattern. The context is a normalized transcript: the system prompt and tool declarations live in its system messages, so read them with `getCurrentSystemPrompt(context.messages)` and `getCurrentTools(context.messages)` rather than expecting `context.systemPrompt` or `context.tools`. Models that accept system messages mid-conversation can send them in place; otherwise call `collapseSystemMessages(context)` first to fold later system messages into the leading one.
 
 ```typescript
 import {
   type AssistantMessage,
   type AssistantMessageEventStream,
-  type Context,
   type Model,
   type SimpleStreamOptions,
+  type TranscriptContext,
   calculateCost,
+  collapseSystemMessages,
   createAssistantMessageEventStream,
+  getCurrentSystemPrompt,
+  getCurrentTools,
 } from "@knightcode/ai";
 
 function streamMyProvider(
   model: Model<any>,
-  context: Context,
+  context: TranscriptContext,
   options?: SimpleStreamOptions
 ): AssistantMessageEventStream {
   const stream = createAssistantMessageEventStream();
+  const transcript = collapseSystemMessages(context);
+  const systemPrompt = getCurrentSystemPrompt(transcript.messages);
+  const tools = getCurrentTools(transcript.messages);
 
   (async () => {
     // Initialize output message
@@ -668,10 +674,10 @@ interface ProviderConfig {
   /** API type for streaming. Required at provider or model level when defining models. */
   api?: Api;
 
-  /** Custom streaming implementation for non-standard APIs. */
+  /** Custom streaming implementation for non-standard APIs. Receives a normalized transcript. */
   streamSimple?: (
     model: Model<Api>,
-    context: Context,
+    context: TranscriptContext,
     options?: SimpleStreamOptions
   ) => AssistantMessageEventStream;
 

package/bin/docs/docs.json

@@ -39,6 +39,10 @@
           "title": "Sessions",
           "path": "sessions.md"
         },
+        {
+          "title": "Remote sessions",
+          "path": "remote.md"
+        },
         {
           "title": "Compaction",
           "path": "compaction.md"

package/bin/docs/environment-variables.md

@@ -93,6 +93,7 @@ These variables are read by KnightCode itself:
 | `KNIGHTCODE_IMAGE_PROTOCOL` | Override inline image detection with `kitty`, `iterm2`, `none`, or `auto` |
 | `KNIGHTCODE_TRUE_COLOR` | Override truecolor detection with `1`, `0`, or `auto` |
 | `KNIGHTCODE_TUI_ESC_TIMEOUT` | How long to wait after a lone ESC before treating it as Escape, in milliseconds; defaults to `100` over SSH and `10` otherwise. Increase if Alt-key input is misread as Escape |
+| `BRAVE_API_KEY` | Brave Search key for `websearch` when none is stored with `/tools`; see [Web tools](usage.md#web-tools) |
 | `VISUAL`, `EDITOR` | External editor fallback when `externalEditor` is unset |
 | `HTTP_PROXY`, `HTTPS_PROXY` | Proxy outbound HTTP requests |
 

package/bin/docs/extensions.md

@@ -538,10 +538,13 @@ knightcode.on("before_agent_start", async (event, ctx) => {
   // event.systemPrompt - current chained system prompt for this handler
   //   (includes changes from earlier before_agent_start handlers)
   // event.systemPromptOptions - structured options used to build the system prompt
-  //   .customPrompt - any custom system prompt (from --system-prompt, SYSTEM.md, or custom templates)
+  //   .customPrompt - exact prompt prefix from --system-prompt, SYSTEM.md, or custom templates
+  //   .forceSystemPrompt - optional exact replacement for the complete prompt
   //   .selectedTools - tools currently active in the prompt
   //   .toolSnippets - one-line descriptions for each tool
-  //   .promptGuidelines - custom guideline bullets
+  //   .toolGuidelines - guideline bullets keyed by tool name
+  //   .promptGuidelines - additional custom guideline bullets
+  //   .sections - custom XML-wrapped sections keyed by tag name
   //   .appendSystemPrompt - text from --append-system-prompt flags
   //   .cwd - working directory
   //   .contextFiles - AGENTS.md files and other loaded context files
@@ -560,7 +563,7 @@ knightcode.on("before_agent_start", async (event, ctx) => {
 });
 ```
 
-The `systemPromptOptions` field gives extensions access to the same structured data KnightCode uses to build the system prompt. This lets you inspect what KnightCode has loaded — custom prompts, guidelines, tool snippets, context files, skills — without re-discovering resources or re-parsing flags. Use it when your extension needs to make deep, informed changes to the system prompt while respecting user-provided configuration.
+The `systemPromptOptions` field gives extensions access to the same structured data KnightCode uses to build the system prompt. Collections are mutable. Prefer changing `sections`, `selectedTools`, or `promptGuidelines`: KnightCode diffs the resulting prompt sections against what the model already has and appends one system message patching only the changed sections. Returning `systemPrompt`, or setting `forceSystemPrompt`, replaces the whole prompt with a single untagged `preamble` section. Tool selection changes update both the prompt contributions and executable provider tools; calling `knightcode.setActiveTools()` inside the handler has the same effect as editing `selectedTools`. Models that accept system messages mid-conversation receive the patch in place and keep their cached prefix; other models get the replayed prompt as their system prompt, which is a cache miss once per change.
 
 Inside `before_agent_start`, `event.systemPrompt` and `ctx.getSystemPrompt()` both reflect the chained system prompt as of the current handler. Later `before_agent_start` handlers can still modify it again.
 
@@ -906,6 +909,8 @@ knightcode.on("user_bash", (event, ctx) => {
 });
 ```
 
+Returning `undefined` continues to the next handler, then local execution if none handles the event. A valid result stops propagation: `operations` executes the command through the supplied backend, while `result` records the completed command without executing it.
+
 ### Input Events
 
 #### input
@@ -1125,7 +1130,7 @@ const options = ctx.getSystemPromptOptions();
 const contextPaths = options.contextFiles?.map((file) => file.path) ?? [];
 ```
 
-This has the same shape and mutability as `before_agent_start` `event.systemPromptOptions`: custom prompt, active tools, tool snippets, prompt guidelines, appended system prompt text, cwd, loaded context files, and loaded skills. It may include full context file contents, so treat it as sensitive extension-local data and avoid exposing it through command lists, logs, or autocomplete metadata.
+This has the same shape and mutability as `before_agent_start` `event.systemPromptOptions`: custom or forced prompt, active tools, tool snippets, per-tool and custom rules, custom sections, appended prompt text, cwd, loaded context files, and loaded skills. It may include full context file contents, so treat it as sensitive extension-local data and avoid exposing it through command lists, logs, or autocomplete metadata.
 
 This reports the current base prompt inputs. It does not include per-turn `before_agent_start` chained system-prompt changes, later `context` event message mutations, or `before_provider_request` payload rewrites.
 
@@ -2370,38 +2375,13 @@ If a slot renderer is not defined or throws:
 
 ### Dynamic Tool Loading
 
-Extensions can register many tools while keeping only a small initial set active. A tool can then add more tools with `knightcode.setActiveTools()` during execution. KnightCode detects purely additive changes, records the newly available tool names on that tool result, and applies the updated active set before the next model request.
-
-This works with every model. Models with native deferred-loading support preserve the stable prompt prefix and load the new definitions at the tool-result position. Other models use the fallback described below.
+Extensions can register many tools while keeping only a small initial set active. A tool can then change the active set with `knightcode.setActiveTools()` during execution. KnightCode stores the initial prompt and tool loadout in the transcript's first system message, then appends tool and prompt deltas before the next model request. Providers that cannot represent a transition receive a complete transcript checkpoint, which may invalidate the cached prefix.
 
 The lifecycle is:
 
 1. Register every tool with `knightcode.registerTool()` so it appears in `knightcode.getAllTools()`.
 2. Keep loader tools, such as `search_tools`, active and leave searchable tools inactive.
-3. During loader execution, call `knightcode.setActiveTools([...currentTools, ...matchingTools])`. The change must be additive: do not remove currently active tools in the same call.
-4. KnightCode records which tools were added on the loader's tool result.
-5. Before the next model response, KnightCode exposes the added definitions using native deferred loading when supported, or the normal active tool list otherwise.
-
-You do not need to return provider-specific tool references or mark the loader as a special search tool. The active-tool change is the signal. Names passed to `knightcode.setActiveTools()` must already be registered; unknown names are ignored.
-
-#### Models with native deferred loading
-
-- **Anthropic**
-  - **Models:** Sonnet, Opus, Fable version 4.5 or newer (without Haiku)
-  - **Native representation:** Deferred definitions use `defer_loading`; the load point uses `tool_reference` content.
-- **OpenAI**
-  - **Models:** `gpt-5.4` and newer family
-  - **Native representation:** KnightCode adds completed client `tool_search_call` and `tool_search_output` items at the load point.
-
-For a verified custom model or proxy, native handling can be enabled with `compat.supportsToolReferences: true` for `anthropic-messages`, or `compat.supportsToolSearch: true` for `openai-responses` and `openai-codex-responses`. Leave these disabled unless the endpoint and model accept the corresponding native protocol.
-
-#### Fallback behavior
-
-For all other models and providers, dynamic activation still works: KnightCode sends the complete current active tool list normally on the next request. The model can call the newly activated tools, but adding their definitions may invalidate the provider's cached prompt prefix.
-
-KnightCode also uses this safe fallback when the active set is not purely additive, such as replacing one group of tools with another. Tool removals therefore work, but they do not use deferred loading.
-
-For the best cache behavior, keep the loader tool active for the whole session and add tools instead of replacing the active set. Also note that activating a tool with `promptSnippet` or `promptGuidelines` rebuilds the system prompt; that system-prompt change can invalidate the prefix even when the provider supports deferred schemas. Lazily loaded tools should usually rely on their tool `description` and omit active-only prompt metadata.
+3. During loader execution, call `knightcode.setActiveTools()` with the desired active tool names. Names must already be registered; unknown names are ignored.
 
 #### Search tool example
 
@@ -2503,7 +2483,7 @@ export default function (knightcode: ExtensionAPI) {
 }
 ```
 
-When `search_tools` adds a match, the model receives that definition on the immediately following request. On a native-capable model the definition is anchored after the search result without changing the initial tool-schema prefix. On other models it appears in the normal tool list on that same following request.
+When `search_tools` adds a match, the model receives the complete updated tool list on the immediately following request.
 
 ## Custom UI
 

package/bin/docs/models.md

@@ -436,6 +436,7 @@ Built-in Anthropic models enable `supportsStrictTools` in their model metadata.
 | `supportsMidConvoEffort` | Whether the exact Claude model transport supports per-turn effort system messages and thinking binding controls. KnightCode persists native effort levels and always sends `drop_block` when enabled. Default: `false`. |
 | `allowEmptySignature` | Whether to replay empty thinking signatures as `signature: ""` instead of converting thinking to text. Default: `false`. |
 | `supportsStrictTools` | Whether the provider accepts strict JSON-schema tool definitions. Default: `false`; built-in Anthropic models enable it in generated metadata. |
+| `allowedFallbackModels` | Up to three server-side fallback models, each with `provider`, `model`, and complete `cost` metadata. An empty array disables fallback. |
 
 ## OpenAI Compatibility
 
@@ -482,7 +483,6 @@ For providers with partial OpenAI compatibility, use the `compat` field.
 | `sessionAffinityFormat` | For `openai-completions` and `openai-responses`, the session-affinity header format: `openai` sends `session_id`/`x-client-request-id` (completions also `x-session-affinity`), `openai-nosession` omits the underscore-containing `session_id` header, `openrouter` sends `x-session-id`. Does not affect the `prompt_cache_key` body param. Default: auto-detected. |
 | `supportsStrictMode` | Whether the provider accepts strict JSON-schema function tool definitions. Defaults depend on the API; built-in OpenAI models carry explicit capability metadata. |
 | `supportsOpenAIGrammarTools` | Whether OpenAI-compatible APIs emit custom Lark/regex grammar tools. When `false`, grammar-constrained tools fall back to normal function tools. Default: `false`; the built-in model catalog enables it for GPT-5+ models on OpenAI, OpenAI Codex, Azure OpenAI, GitHub Copilot, opencode, and Cloudflare AI Gateway. |
-| `deferredToolsMode` | Use provider-specific deferred tool serialization. Currently only `"kimi"` is supported for Kimi's OpenAI-compatible Chat Completions format. |
 | `supportsLongCacheRetention` | Whether the provider accepts long cache retention when cache retention is `long`: `prompt_cache_options.ttl: "30m"` for GPT-5.6+ Responses models, `prompt_cache_retention: "24h"` for earlier OpenAI models, or `cache_control.ttl: "1h"` when `cacheControlFormat` is `anthropic`. Default: `true`. |
 | `openRouterRouting` | OpenRouter provider routing preferences. This object is sent as-is in the `provider` field of the [OpenRouter API request](https://openrouter.ai/docs/guides/routing/provider-selection). |
 | `vercelGatewayRouting` | Vercel AI Gateway routing config for provider selection (`only`, `order`) |

package/bin/docs/remote.md

@@ -0,0 +1,87 @@
+# Remote sessions
+
+`/remote` publishes the session running in your terminal to the web, so you can
+watch it and reply from another device. The terminal keeps working normally.
+
+## Getting started
+
+Run `/remote`. The first time, a sign-in screen opens your browser on the
+approval page and shows an eight-character code: sign in with GitHub, check the
+page shows the same code, and approve. Escape cancels. The credential is stored
+in `~/.knightcode/remote-auth.json` and reused afterwards, and the screen also
+prints the URL for a headless box where nothing launched. Once the browser
+approves, the screen confirms it and continues on enter, or by itself a few
+seconds later.
+
+Once signed in, `/remote` prints a link. You do not have to copy it: open
+<https://remote.knightcode.dev> on your phone and the session appears in the
+list.
+
+## The web app
+
+The list shows every session you have published, newest first, with its state:
+**Working** while a turn is running in the terminal, **Connected** while the
+terminal is attached and idle, **Disconnected** once it has gone. Filter it to
+active or past sessions from the menu on the right.
+
+Open a session to read the transcript. Runs of tool calls are folded into one
+line such as _Ran 2 commands, created a file_; tap it to list the calls, and
+tap a call to see what it did — the command and its output, the file and its
+content, the diff an edit made.
+
+The composer sends replies to the terminal. Type `/` to list the slash commands
+the terminal can run from a message: extension commands, skills and prompt
+templates. Built-in commands that open a terminal UI, such as `/model`, are not
+offered.
+
+The menu in the session's top-right corner copies the link or deletes the
+session from the relay.
+
+## Commands
+
+| Command | Effect |
+| --- | --- |
+| `/remote` | Toggle publishing: start and print the link, or pause. Pausing keeps the room readable, and the next `/remote` resumes the same link |
+| `/remote status` | Show the link and how many viewers are connected |
+| `/remote stop` | Stop publishing and delete the room |
+| `/remote logout` | Revoke the stored account credential and delete it locally |
+
+`/remote` runs in the interactive terminal only. In `--print`, RPC and JSON
+modes it reports that and does nothing.
+
+## What the remote can and cannot do
+
+A viewer can read the transcript, send prompts, run the slash commands listed
+above, and stop the current turn. Prompts arrive as ordinary user messages and
+appear in your terminal; `/remote` itself is never offered to a viewer.
+
+A viewer cannot end your session, quit KnightCode, switch sessions, or change
+model. Closing the browser tab, losing signal, or losing the relay does nothing
+to the terminal. Your session ends only when you end it.
+
+If the relay becomes unreachable the command does not fail: it reconnects with
+backoff indefinitely, the footer shows `remote retrying`, and the agent carries
+on working.
+
+## Privacy and retention
+
+Room contents pass through and are briefly stored by the relay so a device that
+reconnects can catch up. That includes tool output, which can contain secrets if
+a command prints them. Nothing is redacted: anything visible in your terminal is
+visible in the room while it lives. Only the account that created a room can
+read it.
+
+A room stays readable as a past session for 30 days after the terminal
+disconnects, and is deleted then, on `/remote stop`, or when you delete it from
+the web app. Stored history is capped at 8 MB per room; older content is
+dropped as the session grows. Images are not mirrored in either direction — an
+image in the transcript appears as a placeholder recording its type and size.
+
+## Configuration
+
+| Environment variable | Default | Effect |
+| --- | --- | --- |
+| `KNIGHTCODE_REMOTE_RELAY` | `https://remote.knightcode.dev` | Relay origin to publish to |
+| `KNIGHTCODE_REMOTE_CONFIG_DIR` | `~/.knightcode` | Directory holding `remote-auth.json` |
+
+`/remote` refuses to start when `KNIGHTCODE_OFFLINE` is set.

package/bin/docs/sdk.md

@@ -246,8 +246,8 @@ const state = session.agent.state;
 // state.messages: AgentMessage[] - conversation history
 // state.model: Model - current model
 // state.thinkingLevel: ThinkingLevel - current thinking level
-// state.systemPrompt: string - system prompt
-// state.tools: AgentTool[] - available tools
+// state.systemPrompt: string - read-only, replayed from the transcript's system messages
+// state.tools: AgentTool[] - executable tools; changes are declared to the model before the next request
 // state.streamingMessage?: AgentMessage - current partial assistant message
 // state.errorMessage?: string - latest assistant error
 

package/bin/docs/session-format.md

@@ -77,6 +77,14 @@ interface ToolCall {
 ### Base Message Types (from @knightcode/ai)
 
 ```typescript
+interface SystemMessage {
+  role: "system";
+  content: string | TextContent[];
+  toolsAdded?: Tool[];
+  toolsRemoved?: Array<{ name: string }>;
+  timestamp: number;  // Unix ms
+}
+
 interface UserMessage {
   role: "user";
   content: string | (TextContent | ImageContent)[];
@@ -109,7 +117,6 @@ interface ToolResultMessage {
   content: (TextContent | ImageContent)[];
   details?: any;      // Tool-specific metadata
   usage?: Usage;      // Nested LLM work performed by the tool
-  addedToolNames?: string[];
   isError: boolean;
   timestamp: number;
 }
@@ -177,6 +184,7 @@ interface CompactionSummaryMessage {
 
 ```typescript
 type AgentMessage =
+  | SystemMessage
   | UserMessage
   | AssistantMessage
   | ToolResultMessage
@@ -217,7 +225,14 @@ For sessions with a parent (created via `/fork`, `/clone`, or `newSession({ pare
 
 ### SessionMessageEntry
 
-A message in the conversation. The `message` field contains an `AgentMessage`.
+A message in the conversation. The `message` field contains an `AgentMessage`. System messages carry the prompt and tool loadout: the first request of a session persists one with every prompt section and tool declaration, and later changes persist as system messages that patch `sections` by name (`null` removes one) and list `toolsAdded`/`toolsRemoved`. Replaying them in order yields the current prompt and tools; there is no separate prompt state entry.
+
+```json
+{"type":"message","id":"a0b1c2d3","parentId":null,"timestamp":"2024-12-03T14:00:00.000Z","message":{"role":"system","content":"","sections":{"preamble":"You are an expert coding assistant...","tools":"<tools>\n- read: ...\n</tools>","cwd":"/project"},"toolsAdded":[{"name":"read","description":"...","parameters":{}}],"timestamp":1733234400000}}
+{"type":"message","id":"d4e5f6g7","parentId":"c3d4e5f6","timestamp":"2024-12-03T14:04:00.000Z","message":{"role":"system","content":"","sections":{"skills":"<skills>...</skills>"},"toolsRemoved":[{"name":"write"}],"timestamp":1733234640000}}
+```
+
+Sessions created before system messages existed have no leading system message; the first request declares the current prompt as a later system message, which replays the same way.
 
 ```json
 {"type":"message","id":"a1b2c3d4","parentId":"prev1234","timestamp":"2024-12-03T14:00:01.000Z","message":{"role":"user","content":"Hello","timestamp":1733234401000}}
@@ -243,15 +258,16 @@ Emitted when the user changes the thinking/reasoning level.
 
 ### CompactionEntry
 
-Created when context is compacted. Stores a summary of earlier messages.
+Created when context is compacted. Stores a summary of earlier messages and a complete system prompt/tool checkpoint.
 
 ```json
-{"type":"compaction","id":"f6g7h8i9","parentId":"e5f6g7h8","timestamp":"2024-12-03T14:10:00.000Z","summary":"User discussed X, Y, Z...","firstKeptEntryId":"c3d4e5f6","tokensBefore":50000}
+{"type":"compaction","id":"f6g7h8i9","parentId":"e5f6g7h8","timestamp":"2024-12-03T14:10:00.000Z","summary":"User discussed X, Y, Z...","firstKeptEntryId":"c3d4e5f6","tokensBefore":50000,"systemMessage":{"role":"system","content":"You are a coding assistant.","toolsAdded":[],"timestamp":1733235000000}}
 ```
 
 `firstKeptEntryId` is required. It identifies the first entry retained from before the compaction entry. When rebuilding context, KnightCode replaces older summarized entries with the compaction summary and keeps the range beginning at this entry.
 
 Optional fields:
+- `systemMessage`: The replayed prompt sections and tool declarations at the compaction boundary; it becomes the leading system message of the compacted context, and system messages among the kept entries are dropped in its favor. It is absent on older session entries.
 - `usage`: LLM usage from generating the summary; included in session token and cost totals
 - `details`: Implementation-specific data (e.g., `{ readFiles: string[], modifiedFiles: string[] }` for default, or custom data for extensions)
 - `fromHook`: `true` if generated by an extension, `false`/`undefined` if knightcode-generated (legacy field name)
@@ -336,7 +352,7 @@ Entries normally form one tree, but navigation APIs can create multiple roots:
 1. Collects all entries on the path
 2. If one or more `CompactionEntry` values are on the path, uses the latest one:
    - Includes the compaction entry first
-   - Includes entries from `firstKeptEntryId` up to, but not including, the compaction entry
+   - Includes non-system entries from `firstKeptEntryId` up to, but not including, the compaction entry
    - Includes entries after the compaction entry
 3. Preserves non-message entries in the selected range so interactive mode can render them
 
@@ -345,12 +361,12 @@ Entries normally form one tree, but navigation APIs can create multiple roots:
 1. Extracts current model and thinking level settings from the full path
 2. Converts selected entries to messages:
    - `message` -> stored `AgentMessage`
-   - `compaction` -> `compactionSummary`
+   - `compaction` -> complete system checkpoint followed by `compactionSummary`
    - `branch_summary` -> `branchSummary`
    - `custom_message` -> `CustomMessage`
    - `custom` -> no context message
 
-The compaction summary replaces entries before `firstKeptEntryId`. The retained entries and all entries after the compaction remain available to the LLM.
+The compaction summary replaces entries before `firstKeptEntryId`. Pre-compaction system messages are folded into the complete checkpoint rather than replayed from the retained range. Retained non-system entries and all entries after the compaction remain available to the LLM.
 
 ## Parsing Example
 

package/bin/docs/settings.md

@@ -279,6 +279,8 @@ On Windows, select `powershell` instead of `bash`, or include both:
 
 An empty array starts with no built-in tools while preserving extension and SDK custom tools. `--tools` replaces this behavior with a strict allowlist for all tools, `--no-tools` disables all tools, and `--no-builtin-tools` disables the built-in defaults. `--exclude-tools` filters the resulting list. A project `defaultTools` array replaces the global array.
 
+The [web tools](usage.md#web-tools) `webfetch` and `websearch` are not part of `defaultTools`. `/tools` turns them on and stores their settings, including the search provider and Brave key, in `~/.knightcode/agent/tools.json`.
+
 ### Sessions
 
 | Setting | Type | Default | Description |

package/bin/docs/usage.md

@@ -42,6 +42,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/thinking` | Switch thinking level; Ctrl+S or Ctrl+D in the picker saves the startup default |
 | `/scoped-models` | Enable/disable models for Ctrl+P cycling |
 | `/settings` | Theme, message delivery, transport, and other preferences |
+| [`/tools`](#web-tools) | Turn `webfetch` and `websearch` off, on for this session, or on by default; pick the search provider and store its key |
 | `/resume` | Pick from previous sessions |
 | `/new` | Start a new session |
 | `/name <name>` | Set session display name |
@@ -60,6 +61,37 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/changelog` | Display version history |
 | `/quit` | Quit knightcode |
 
+## Web Tools
+
+Two tools give the agent read access to the web. Both ship disabled; turn them on with `/tools`.
+
+| Tool | What it does |
+|------|--------------|
+| `webfetch` | Fetches a URL and returns the page as markdown, 400 lines at a time. The agent pages with `offset`/`limit` like `read`, or passes `grep` to get only matching lines. Responses are cached for 15 minutes, capped at 5 MB, and time out after 30 seconds. Private, loopback, and link-local addresses are refused. |
+| `websearch` | Searches the web and returns up to 10 results (default 5) as title, URL, and snippet. DuckDuckGo needs no key but may rate-limit; Brave Search needs an API key. |
+
+`/tools` lists each tool with its current state; pick one to open its settings panel. **Status** cycles through three states:
+
+| State | Effect |
+|-------|--------|
+| Disabled | The tool is not offered to the model |
+| Enabled for this session | On until knightcode exits, including across `/new`, `/resume`, and `/fork`; nothing is written to disk |
+| Enabled by default | On in every session |
+
+The `websearch` panel adds two rows: **Provider** (`duckduckgo` or `brave`) and **Brave API key**. Choosing Brave without a stored key opens the key prompt at once. Get a key at https://brave.com/search/api/; the free plan is enough. The key is also read from `BRAVE_API_KEY` when none is stored, but the provider only switches to Brave when you pick it. Keys show masked in the panel.
+
+The same changes work without the panel:
+
+```bash
+/tools websearch on        # this session
+/tools webfetch always     # every session
+/tools webfetch off
+```
+
+Settings are stored in `~/.knightcode/agent/tools.json`, owner-readable only because it can hold the Brave key. `--tools` and `--exclude-tools` still apply: a tool excluded on the command line stays off whatever `/tools` says.
+
+Fetched pages and search results are marked as untrusted in the tool output so the model treats instructions inside them as data, but treat the tools like any other network access: a fetched page can still influence what the agent does next.
+
 ## Message Queue
 
 You can submit messages while the agent is still working:
@@ -212,7 +244,7 @@ cat README.md | knightcode -p "Summarize this text"
 | `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep extension/custom tools enabled |
 | `--no-tools`, `-nt` | Disable all tools |
 
-Built-in tools: `read`, `bash`, `powershell` (Windows), `edit`, `write`, `grep`, `find`, `ls`.
+Built-in tools: `read`, `bash`, `powershell` (Windows), `edit`, `write`, `grep`, `find`, `ls`. The [web tools](#web-tools) `webfetch` and `websearch` are off until enabled with `/tools`.
 
 ### Resource Options
 

package/bin/knightcode

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/bin/knightcode
-size: 116632000 bytes
-sha256: e16a45c14c56d51e900ecb6426e53c498cd6401df16eff82c987b9156c5c5753
+size: 117447166 bytes
+sha256: 7d7e0678a4920ce09880c0016816a1a91fd224d7f3e2e110851deb0939894967

package/bin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knightcodeai/cli",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "KnightCode — a local, BYOK terminal coding agent powered by OpenRouter.",
   "type": "module",
   "repository": {
@@ -37,17 +37,20 @@
     "test": "vitest --run"
   },
   "optionalDependencies": {
-    "@knightcodeai/cli-linux-x64": "0.6.2",
-    "@knightcodeai/cli-linux-arm64": "0.6.2",
-    "@knightcodeai/cli-darwin-x64": "0.6.2",
-    "@knightcodeai/cli-darwin-arm64": "0.6.2",
-    "@knightcodeai/cli-win32-x64": "0.6.2"
+    "@knightcodeai/cli-linux-x64": "0.8.0",
+    "@knightcodeai/cli-linux-arm64": "0.8.0",
+    "@knightcodeai/cli-darwin-x64": "0.8.0",
+    "@knightcodeai/cli-darwin-arm64": "0.8.0",
+    "@knightcodeai/cli-win32-x64": "0.8.0"
   },
   "devDependencies": {
+    "@agentclientprotocol/sdk": "1.4.0",
     "@knightcode/agent": "workspace:*",
     "@knightcode/ai": "workspace:*",
     "@knightcode/client": "workspace:*",
     "@knightcode/protocol": "workspace:*",
+    "@knightcode/remote": "workspace:*",
+    "@knightcode/tools": "workspace:*",
     "@knightcode/server": "workspace:*",
     "@knightcode/session-backend-sqlite": "workspace:*",
     "@knightcode/tui": "workspace:*",
@@ -70,6 +73,7 @@
     "semver": "7.8.5",
     "typebox": "1.3.27",
     "undici": "8.10.2",
-    "yaml": "2.9.0"
+    "yaml": "2.9.0",
+    "zod": "4.4.3"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knightcodeai/cli-linux-x64",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "license": "MIT",
   "repository": {
     "type": "git",