@knightcodeai/cli-linux-arm64 0.9.1 → 0.9.3

package/bin/docs/keybindings.md

@@ -1,16 +1,35 @@
-# Keybindings
+# Keybindings Reference
 
-All keyboard shortcuts can be customized via `~/.knightcode/agent/keybindings.json`. Each action can be bound to one or more keys.
+KnightCode exposes named actions, such as `app.session.new`, that can be assigned keybindings. You can change default assignments or bind unassigned actions in KnightCode's [user configuration](configuration.md#agent-directory).
 
-The config file uses the same namespaced keybinding ids that knightcode uses internally and that extension authors use in `keyHint()` and injected `keybindings` managers.
+Run `/hotkeys` to see the active shortcuts for the main editor and application.
 
-Older configs using pre-namespaced ids such as `cursorUp` or `expandTools` are migrated automatically to the namespaced ids on startup.
+## Assign keybindings
 
-After editing `keybindings.json`, run `/reload` in knightcode to apply the changes without restarting the session.
+Create `<agent-dir>/keybindings.json`. The agent directory defaults to `~/.knightcode/agent` and is described in [Agent directory](configuration.md#agent-directory).
 
-## Key Format
+Map each action identifier to one key or a list of keys:
 
-`modifier+key` where modifiers are `ctrl`, `shift`, `alt`, `super` (combinable) and keys are:
+```json
+{
+  "app.session.new": "ctrl+shift+n",
+  "app.session.tree": ["ctrl+shift+t", "alt+shift+t"]
+}
+```
+
+A configured value replaces the default for that action. Use an empty list to disable an action's keybindings:
+
+```json
+{
+  "tui.altScreen.pageUp": []
+}
+```
+
+After editing the file, run `/reload` to apply the changes to the active session.
+
+## Key syntax
+
+Write a key as `modifier+key`. Modifiers are `ctrl`, `shift`, `alt`, and `super`. You can combine modifiers. Valid keys are:
 
 - **Letters:** `a-z`
 - **Digits:** `0-9`
@@ -18,20 +37,22 @@ After editing `keybindings.json`, run `/reload` in knightcode to apply the chang
 - **Function:** `f1`-`f12`
 - **Symbols:** `` ` ``, `-`, `=`, `[`, `]`, `\`, `;`, `'`, `,`, `.`, `/`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `(`, `)`, `_`, `+`, `|`, `~`, `{`, `}`, `:`, `<`, `>`, `?`
 
-Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `super+k`, `ctrl+super+k`, `ctrl+1`, etc.
+Examples: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `super+k`, `ctrl+super+k`, and `ctrl+1`.
 
 `super` bindings require a terminal that reports the modifier separately, typically through the Kitty keyboard protocol. They may not work in terminals without that support.
 
-## All Actions
+## Actions
+
+### Terminal UI
 
-### TUI Editor Cursor Movement
+#### Cursor movement
 
 | Keybinding id | Default | Description |
-|--------|---------|-------------|
+|---|---|---|
 | `tui.editor.cursorUp` | `up` | Move cursor up, browsing older history at the top |
 | `tui.editor.cursorDown` | `down` | Move cursor down, browsing newer history at the bottom |
-| `tui.editor.historyPrevious` | *(none)* | Select the previous prompt history entry |
-| `tui.editor.historyNext` | *(none)* | Select the next prompt history entry |
+| `tui.editor.historyPrevious` | None | Select the previous prompt history entry |
+| `tui.editor.historyNext` | None | Select the next prompt history entry |
 | `tui.editor.cursorLeft` | `left`, `ctrl+b` | Move cursor left |
 | `tui.editor.cursorRight` | `right`, `ctrl+f` | Move cursor right |
 | `tui.editor.cursorWordLeft` | `alt+left`, `ctrl+left`, `alt+b` | Move cursor word left |
@@ -43,39 +64,29 @@ Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `super+
 | `tui.editor.pageUp` | `pageUp`, `ctrl+pageUp` | Scroll up by page |
 | `tui.editor.pageDown` | `pageDown`, `ctrl+pageDown` | Scroll down by page |
 
-The dedicated history actions always change history entries, regardless of the cursor position in a multiline prompt. Explicit history bindings take precedence over application actions while the main editor is focused, so binding `tui.editor.historyPrevious` to `ctrl+p` overrides model cycling in that context without changing `Ctrl+P` in selectors.
+The dedicated history actions browse prompt history regardless of cursor position and take precedence over application actions using the same key.
 
-### TUI Editor Deletion
+#### Text editing
 
 | Keybinding id | Default | Description |
-|--------|---------|-------------|
+|---|---|---|
 | `tui.editor.deleteCharBackward` | `backspace` | Delete character backward |
 | `tui.editor.deleteCharForward` | `delete`, `ctrl+d` | Delete character forward |
 | `tui.editor.deleteWordBackward` | `ctrl+w`, `alt+backspace` | Delete word backward |
 | `tui.editor.deleteWordForward` | `alt+d`, `alt+delete` | Delete word forward |
 | `tui.editor.deleteToLineStart` | `ctrl+u` | Delete to line start |
 | `tui.editor.deleteToLineEnd` | `ctrl+k` | Delete to line end |
-
-### TUI Input
-
-| Keybinding id | Default | Description |
-|--------|---------|-------------|
-| `tui.input.newLine` | `shift+enter`, `ctrl+j` | Insert new line |
-| `tui.input.submit` | `enter` | Submit input |
-| `tui.input.tab` | `tab` | Tab / autocomplete |
-
-### TUI Kill Ring
-
-| Keybinding id | Default | Description |
-|--------|---------|-------------|
 | `tui.editor.yank` | `ctrl+y` | Paste most recently deleted text |
 | `tui.editor.yankPop` | `alt+y` | Cycle through deleted text after yank |
 | `tui.editor.undo` | `ctrl+-` (`ctrl+z` on Windows; `alt+z` on WSL) | Undo last edit |
 
-### TUI Clipboard and Selection
+#### Input and selection
 
 | Keybinding id | Default | Description |
-|--------|---------|-------------|
+|---|---|---|
+| `tui.input.newLine` | `shift+enter`, `ctrl+j` | Insert new line |
+| `tui.input.submit` | `enter` | Submit input |
+| `tui.input.tab` | `tab` | Tab or autocomplete |
 | `tui.input.copy` | `ctrl+c` | Copy selection |
 | `tui.select.up` | `up` | Move selection up |
 | `tui.select.down` | `down` | Move selection down |
@@ -84,31 +95,18 @@ The dedicated history actions always change history entries, regardless of the c
 | `tui.select.confirm` | `enter` | Confirm selection |
 | `tui.select.cancel` | `escape`, `ctrl+c` | Cancel selection |
 
-### TUI Fullscreen Viewport
-
-These actions apply when interactive mode uses `--tui-mode fullscreen` and target the primary transcript scroll region. Two-finger trackpad and mouse-wheel input scroll the region under the pointer, falling back to the transcript over the fixed editor/status/footer dock. Clicking an OSC 8 hyperlink opens it in the default handler. Dragging with the primary mouse button selects text and copies it to the clipboard; holding at the transcript's top or bottom edge auto-scrolls into off-screen content. While the transcript is scrolled up, a clickable "Jump to latest message" label on its bottom row shows the `tui.altScreen.bottom` shortcut. See [Terminal setup](terminal-setup.md) for terminal-specific mouse and trackpad behavior.
-
-Fullscreen transcript bindings take precedence over editor bindings. The default unmodified navigation keys therefore control the transcript in fullscreen mode, while their `ctrl` variants continue to control the editor. Outside fullscreen mode, both variants control the editor.
-
-The transcript search panel shows the configured previous/next shortcuts and clickable arrow controls. Press `tui.altScreen.search` again, or use `tui.altScreen.searchClose`, to close it.
+#### Fullscreen
 
-| Key | Default mode | Fullscreen mode |
-|-----|--------------|-----------------|
-| `home`, `end` | Editor | Transcript |
-| `ctrl+home`, `ctrl+end` | Editor | Editor |
-| `pageUp`, `pageDown` | Editor | Transcript |
-| `ctrl+pageUp`, `ctrl+pageDown` | Editor | Editor |
-
-This routing remains configurable through the ordinary action bindings. For example, `"tui.altScreen.pageUp": "ctrl+pageUp"` makes `pageUp` control the editor and `ctrl+pageUp` control the transcript in fullscreen mode. Bind `tui.altScreen.halfPageUp` and `tui.altScreen.halfPageDown` for half-page steps, or bind `tui.altScreen.lineUp` and `tui.altScreen.lineDown` for single-line steps. Setting `"tui.altScreen.pageUp": []` disables that transcript shortcut entirely. User bindings replace the defaults for that action.
+In fullscreen mode, these actions control the transcript and take precedence over editor actions using the same key.
 
 | Keybinding id | Default | Description |
-|--------|---------|-------------|
+|---|---|---|
 | `tui.altScreen.pageUp` | `pageUp` | Scroll the transcript up by one page |
 | `tui.altScreen.pageDown` | `pageDown` | Scroll the transcript down by one page |
-| `tui.altScreen.halfPageUp` | *(none)* | Scroll the transcript up by half a page |
-| `tui.altScreen.halfPageDown` | *(none)* | Scroll the transcript down by half a page |
-| `tui.altScreen.lineUp` | *(none)* | Scroll the transcript up by one line |
-| `tui.altScreen.lineDown` | *(none)* | Scroll the transcript down by one line |
+| `tui.altScreen.halfPageUp` | None | Scroll the transcript up by half a page |
+| `tui.altScreen.halfPageDown` | None | Scroll the transcript down by half a page |
+| `tui.altScreen.lineUp` | None | Scroll the transcript up by one line |
+| `tui.altScreen.lineDown` | None | Scroll the transcript down by one line |
 | `tui.altScreen.previousPrompt` | `ctrl+shift+up`, `ctrl+up` (`ctrl+up` only on Windows and WSL) | Jump to the previous marked message |
 | `tui.altScreen.nextPrompt` | `ctrl+shift+down`, `ctrl+down` (`ctrl+down` only on Windows and WSL) | Jump to the next marked message |
 | `tui.altScreen.search` | `ctrl+shift+f` (`ctrl+f` on Windows and WSL) | Search the rendered transcript |
@@ -125,18 +123,20 @@ This routing remains configurable through the ordinary action bindings. For exam
 | `app.interrupt` | `escape` | Cancel / abort |
 | `app.clear` | `ctrl+c` | Clear editor (first) / exit (second) |
 | `app.exit` | `ctrl+d` | Exit (when editor empty) |
-| `app.suspend` | `ctrl+z` (none on Windows) | Suspend to background |
+| `app.suspend` | `ctrl+z` (None on Windows) | Suspend to background |
 | `app.editor.external` | `ctrl+g` | Open in external editor (`externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere) |
 | `app.clipboard.pasteImage` | `ctrl+v` (`alt+v` on Windows and WSL) | Paste image or text from clipboard |
 
+On native Windows, `app.suspend` has no default because Windows terminals do not support Unix job control. If you assign it manually, KnightCode shows a status message instead of suspending. WSL uses the normal `ctrl+z` and `fg` behavior.
+
 ### Sessions
 
 | Keybinding id | Default | Description |
 |--------|---------|-------------|
-| `app.session.new` | *(none)* | Start a new session (`/new`) |
-| `app.session.tree` | *(none)* | Open session tree navigator (`/tree`) |
-| `app.session.fork` | *(none)* | Fork current session (`/fork`) |
-| `app.session.resume` | *(none)* | Open session resume picker (`/resume`) |
+| `app.session.new` | None | Start a new session (`/new`) |
+| `app.session.tree` | None | Open session tree navigator (`/tree`) |
+| `app.session.fork` | None | Fork current session (`/fork`) |
+| `app.session.resume` | None | Open session resume picker (`/resume`) |
 | `app.session.togglePath` | `ctrl+p` | Toggle path display |
 | `app.session.toggleSort` | `ctrl+s` | Toggle sort mode |
 | `app.session.toggleNamedFilter` | `ctrl+n` | Toggle named-only filter |
@@ -192,48 +192,3 @@ Used inside the scoped models selector (opened via `/scoped-models`).
 | `app.models.toggleProvider` | `ctrl+p` | Toggle all models for the current provider |
 | `app.models.reorderUp` | `alt+up` | Move the selected model up in the cycle order |
 | `app.models.reorderDown` | `alt+down` | Move the selected model down in the cycle order |
-
-## Custom Configuration
-
-Create `~/.knightcode/agent/keybindings.json`:
-
-```json
-{
-  "tui.editor.historyPrevious": "ctrl+p",
-  "tui.editor.historyNext": "ctrl+n",
-  "tui.editor.deleteWordBackward": ["ctrl+w", "alt+backspace"]
-}
-```
-
-Each action can have a single key or an array of keys. User config overrides defaults.
-
-On native Windows, `app.suspend` has no default binding because Windows terminals do not support Unix job control. If you bind it manually, knightcode shows a status message instead of suspending. In WSL, the normal Linux `ctrl+z`/`fg` behavior still applies.
-
-### Emacs Example
-
-```json
-{
-  "tui.editor.historyPrevious": "ctrl+p",
-  "tui.editor.historyNext": "ctrl+n",
-  "tui.editor.cursorLeft": ["left", "ctrl+b"],
-  "tui.editor.cursorRight": ["right", "ctrl+f"],
-  "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
-  "tui.editor.cursorWordRight": ["alt+right", "alt+f"],
-  "tui.editor.deleteCharForward": ["delete", "ctrl+d"],
-  "tui.editor.deleteCharBackward": ["backspace", "ctrl+h"],
-  "tui.input.newLine": ["shift+enter", "ctrl+j"]
-}
-```
-
-### Vim Example
-
-```json
-{
-  "tui.editor.cursorUp": ["up", "alt+k"],
-  "tui.editor.cursorDown": ["down", "alt+j"],
-  "tui.editor.cursorLeft": ["left", "alt+h"],
-  "tui.editor.cursorRight": ["right", "alt+l"],
-  "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
-  "tui.editor.cursorWordRight": ["alt+right", "alt+w"]
-}
-```

package/bin/docs/llama-cpp.md

@@ -1,4 +1,4 @@
-# llama.cpp
+# Local Models with llama.cpp
 
 KnightCode supports the [llama.cpp](https://github.com/ggml-org/llama.cpp) router server. The router discovers multiple GGUF models and loads or unloads them on demand.
 
@@ -82,7 +82,7 @@ Hugging Face search uses `HF_TOKEN` when set, then checks `$HF_TOKEN_PATH`, `$HF
 
 If other models are loaded, KnightCode asks whether to unload them first or keep them loaded. KnightCode does not silently unload models and never deletes model files. The router may be shared with other clients, so `/llama` always displays the router's current state.
 
-Only loaded models appear in `/model`. After loading a model, run `/model` to select it for the current KnightCode session.
+Loaded and sleeping models appear in `/model`. Sleeping models wake automatically when selected. With router autoload enabled, unloaded preset models also appear and load when selected. With `--no-models-autoload`, load a model through `/llama` before selecting it.
 
 If the router disconnects, `/llama` shows **Retry** and **Close**. Retry reconnects and refreshes model state without replaying the interrupted operation.
 
@@ -96,6 +96,6 @@ curl http://127.0.0.1:8080/models
 ```
 
 - **No models in `/llama`:** Check `--models-dir`, the directory layout, and restart the router.
-- **Model missing from `/model`:** Load it with `/llama` first.
+- **Model missing from `/model` with `--no-models-autoload`:** Load it with `/llama` first.
 - **Load fails or uses too much memory:** Lower `-c` or unload another model.
 - **Server is not in router mode:** Start it without `--model`, `-m`, or `-hf`.

package/bin/docs/message-types.md

@@ -0,0 +1,261 @@
+# Message Types
+
+KnightCode uses `AgentMessage` values in SDK state, lifecycle events, RPC responses, and persisted session message entries. This page defines those shared messages and their content blocks.
+
+Message timestamps are Unix timestamps in milliseconds. They are different from the ISO 8601 timestamps on [session entries](session-format.md#entry-base).
+
+Source definitions:
+
+- [`packages/ai/src/types.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/ai/src/types.ts) defines provider-facing messages and content blocks.
+- [`packages/agent/src/types.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/agent/src/types.ts) defines the extensible `AgentMessage` union.
+- [`packages/cli/src/core/messages.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/cli/src/core/messages.ts) adds CLI message roles.
+
+## Content blocks
+
+### TextContent
+
+```typescript
+interface TextContent {
+  type: "text";
+  text: string;
+  textSignature?: string;
+}
+```
+
+`textSignature` contains provider-specific message metadata. Treat it as opaque.
+
+### ImageContent
+
+```typescript
+interface ImageContent {
+  type: "image";
+  data: string;
+  mimeType: string;
+}
+```
+
+`data` is base64-encoded image data. `mimeType` identifies its media type, such as `image/png` or `image/jpeg`.
+
+### ThinkingContent
+
+```typescript
+interface ThinkingContent {
+  type: "thinking";
+  thinking: string;
+  thinkingSignature?: string;
+  redacted?: boolean;
+}
+```
+
+Thinking signatures contain provider-specific replay data. Treat them as opaque. A redacted block can have no visible thinking text while retaining an encrypted payload in `thinkingSignature`.
+
+### ToolCall
+
+```typescript
+interface ToolCall {
+  type: "toolCall";
+  id: string;
+  name: string;
+  arguments: Record<string, any>;
+  thoughtSignature?: string;
+  namespace?: string;
+}
+```
+
+`thoughtSignature` is provider-specific. `namespace` identifies an OpenAI Responses namespace for dynamically loaded or namespaced tools.
+
+## Usage
+
+Assistant messages always contain usage. Tool results can contain usage when the tool performed nested model work.
+
+```typescript
+interface Usage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cacheWrite1h?: number;
+  reasoning?: number;
+  totalTokens: number;
+  cost: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+  };
+}
+```
+
+When present, `reasoning` is already included in `output`; do not add it again. `cacheWrite1h` is the subset of `cacheWrite` written with one-hour retention.
+
+## Base messages
+
+### SystemMessage
+
+```typescript
+interface SystemMessage {
+  role: "system";
+  content: string | TextContent[];
+  sections?: Record<string, string | null>;
+  toolsAdded?: Tool[];
+  toolsRemoved?: ToolReference[];
+  replace?: boolean;
+  timestamp: number;
+}
+```
+
+The leading system message declares the initial prompt and tools. Later system messages can append instructions, replace or remove named prompt sections, and add or remove tools. Replaying them in order yields the current state. A message with `replace: true` discards the earlier state and establishes a complete new baseline.
+
+### UserMessage
+
+```typescript
+interface UserMessage {
+  role: "user";
+  content: string | (TextContent | ImageContent)[];
+  timestamp: number;
+}
+```
+
+### AssistantMessage
+
+```typescript
+interface AssistantMessage {
+  role: "assistant";
+  content: (TextContent | ThinkingContent | ToolCall)[];
+  api: string;
+  provider: string;
+  model: string;
+  responseModel?: string;
+  responseId?: string;
+  providerThinkingLevel?: string;
+  diagnostics?: AssistantMessageDiagnostic[];
+  usage: Usage;
+  stopReason: "pending" | "stop" | "length" | "toolUse" | "error" | "aborted" | "deferred";
+  deferred?: DeferredHandle;
+  errorMessage?: string;
+  rawStopReason?: string;
+  endTurn?: boolean;
+  timestamp: number;
+}
+```
+
+`responseModel` records a concrete provider response model when it differs from the requested model. `responseId`, `providerThinkingLevel`, `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.
+
+A `"deferred"` response has a `DeferredHandle` with the provider data needed to retrieve it:
+
+```typescript
+interface DeferredHandle {
+  provider: string;
+  modelId: string;
+  api: string;
+  id: string;
+  expiresAt?: number;
+  pollAfterMs?: number;
+  data?: JsonValue;
+}
+```
+
+### ToolResultMessage
+
+```typescript
+interface ToolResultMessage<TDetails = any> {
+  role: "toolResult";
+  toolCallId: string;
+  toolName: string;
+  content: (TextContent | ImageContent)[];
+  details?: TDetails;
+  usage?: Usage;
+  isError: boolean;
+  timestamp: number;
+}
+```
+
+`details` is tool-specific. Optional `usage` reports nested model work performed by the tool and contributes to full-session statistics, but it is not part of the main model-call usage.
+
+## Coding-agent messages
+
+The CLI package extends `AgentMessage` with four roles.
+
+### BashExecutionMessage
+
+Created by direct shell commands, including the RPC [`bash`](rpc-commands.md#bash) command. It is not an LLM tool result.
+
+```typescript
+interface BashExecutionMessage {
+  role: "bashExecution";
+  command: string;
+  output: string;
+  exitCode: number | undefined;
+  cancelled: boolean;
+  truncated: boolean;
+  fullOutputPath?: string;
+  excludeFromContext?: boolean;
+  timestamp: number;
+}
+```
+
+Unless `excludeFromContext` is true, KnightCode converts this message to user-role text before the next model request.
+
+### CustomMessage
+
+Created when an extension sends a context message.
+
+```typescript
+interface CustomMessage<T = unknown> {
+  role: "custom";
+  customType: string;
+  content: string | (TextContent | ImageContent)[];
+  display: boolean;
+  details?: T;
+  timestamp: number;
+}
+```
+
+KnightCode converts its content to a user message for model requests. `display` controls terminal rendering; `details` is not sent to the model.
+
+### BranchSummaryMessage
+
+```typescript
+interface BranchSummaryMessage {
+  role: "branchSummary";
+  summary: string;
+  fromId: string | null;
+  timestamp: number;
+}
+```
+
+KnightCode creates this context message from a persisted `branch_summary` entry.
+
+### CompactionSummaryMessage
+
+```typescript
+interface CompactionSummaryMessage {
+  role: "compactionSummary";
+  summary: string;
+  tokensBefore: number;
+  timestamp: number;
+}
+```
+
+KnightCode creates this context message from a persisted `compaction` entry.
+
+## AgentMessage union
+
+In the coding agent, the union is equivalent to:
+
+```typescript
+type AgentMessage =
+  | SystemMessage
+  | UserMessage
+  | AssistantMessage
+  | ToolResultMessage
+  | BashExecutionMessage
+  | CustomMessage
+  | BranchSummaryMessage
+  | CompactionSummaryMessage;
+```
+
+At the lower-level agent package, `AgentMessage` is `Message | CustomAgentMessages[keyof CustomAgentMessages]`. Applications can add roles through TypeScript declaration merging, so consumers should tolerate unknown custom roles when they accept messages from an augmented host.