@knightcodeai/cli-linux-arm64 0.9.1 → 0.9.3

package/bin/docs/how-knightcode-works.md

@@ -0,0 +1,49 @@
+# How KnightCode Works
+
+KnightCode coordinates model requests, tool execution, context assembly, and session storage. A session is KnightCode's record of a conversation, including messages, tool calls and results, model changes, compactions, and other events.
+
+Messages and events in a session form a tree. Each path through that tree is a branch. The branch ending at the current entry is the active branch and supplies the history for the next model request.
+
+## Agent loop
+
+A submitted message is added to the active branch. KnightCode builds a model request from the system prompt, active branch, available tools, and model settings, then sends it through the selected provider.
+
+The provider streams an assistant response, which can contain text and tool calls. KnightCode records the response, executes each tool call, and records the results. That completes one turn. If tool results or queued messages require another model request, KnightCode starts another turn. Otherwise, the run ends.
+
+Steering messages enter after the current assistant turn. Follow-up messages enter after the agent has finished its pending work. Aborting stops the current run and returns queued messages to the editor.
+
+## Context
+
+The active branch supplies conversation history. KnightCode converts its session entries into model-compatible user, assistant, and tool-result messages.
+
+KnightCode builds the system prompt from its base instructions and discovered context files. The request also carries tool definitions and skill descriptions.
+
+Full skill instructions are loaded on demand. Extensions can add instructions or transform context.
+
+Prompt templates expand editor input before it becomes a user message. Selected files, images, pasted text, and shell output can become message content.
+
+## Sessions
+
+Persistent sessions are JSONL files. Each tree entry has an ID and refers to its parent. The current entry identifies the active branch.
+
+Continuing from an earlier entry creates another branch in the same file. Forking and cloning copy selected history into a new session file.
+
+Model context is reconstructed from the active branch. Compaction inserts a summary entry that replaces older messages in subsequent model requests. The original entries remain in the session tree.
+
+## Interfaces
+
+Interactive mode renders session and agent events in the terminal. Print mode runs a prompt and writes the final response. JSON mode writes agent events as JSONL.
+
+RPC mode accepts JSONL commands on stdin and writes responses and events to stdout. The TypeScript SDK creates and controls agent sessions in process.
+
+All interfaces use the same agent and session mechanisms.
+
+## Extensions and resources
+
+Extensions are TypeScript modules loaded into the KnightCode process. Their factory functions register tools, commands, shortcuts, providers, event handlers, renderers, and terminal UI.
+
+Skills provide on-demand instructions and supporting files. Prompt templates provide reusable message text. Themes provide terminal colors. KnightCode packages distribute these resources through npm or git.
+
+## Trust and permissions
+
+KnightCode resolves project trust before loading project settings and resources. After the trust decision and project-resource loading, KnightCode loads context files. Enabled tools use the operating-system permissions of the KnightCode process. Extensions execute inside that process.

package/bin/docs/index.md

@@ -1,84 +1,39 @@
-# KnightCode Documentation
+# KnightCode
 
-KnightCode is a minimal terminal coding harness. It is designed to stay small at the core while being extended through TypeScript extensions, skills, prompt templates, themes, and knightcode packages.
+KnightCode is an extensible AI agent that works from your terminal. Give it a goal and a working folder, and it can inspect files, run commands, edit content, and work through multi-step tasks.
 
-## Quick start
+Use KnightCode for software development, research notes, writing projects, data files, or hobby work. You can use KnightCode as is, prompt it to adapt itself to your workflow, or build other applications powered by KnightCode using the SDK.
 
-Install KnightCode with npm:
+## Start using KnightCode
 
-```bash
-npm install -g --ignore-scripts @knightcodeai/cli
-```
+New to KnightCode? Follow the [Quickstart](quickstart.md) to install KnightCode, connect a model, and complete your first task.
 
-`--ignore-scripts` disables dependency lifecycle scripts during install. KnightCode does not require install scripts for normal npm installs.
+If KnightCode is already installed, choose what you want to do:
 
-On Linux or macOS, you can also use the installer:
+- [Use KnightCode interactively](usage.md) to add files, run commands, direct ongoing work, and export results.
+- [Choose a model](models.md) or connect a subscription, API key, local model, or compatible endpoint.
+- [Continue or branch a session](sessions.md) to resume work or explore another approach without losing history.
+- [Configure KnightCode](configuration.md) for your preferences, working folders, instructions, and reusable resources.
+- [Understand how KnightCode works](how-knightcode-works.md), including tools, context, sessions, and the agent loop.
 
-```bash
-curl -fsSL https://knightcode.dev/install.sh | sh
-```
+## Customize KnightCode
 
-To uninstall knightcode itself, use npm for curl and npm installs:
+KnightCode can reuse prompts, load specialized instructions, add executable integrations, change its terminal interface, connect model services, and distribute these resources as packages.
+Use the [Quickstart customization chooser](quickstart.md#choose-how-to-customize-knightcode) to select the smallest mechanism that meets your need.
 
-```bash
-npm uninstall -g @knightcodeai/cli
-```
+## Automate or embed KnightCode
 
-For pnpm, Yarn, or Bun installs, use the matching global remove command: `pnpm remove -g @knightcodeai/cli`, `yarn global remove @knightcodeai/cli`, or `bun uninstall -g @knightcodeai/cli`.
+- Use [print mode](cli.md#invocation-and-output) for one-off and scripted tasks.
+- Use [JSON event stream mode](json.md) to consume structured events from one run.
+- Use [RPC mode](rpc.md) to control a separate KnightCode process.
+- Use the [TypeScript SDK](sdk.md) to run KnightCode inside an application.
 
-Then run it in a project directory:
+## Find reference and setup information
 
-```bash
-knightcode
-```
+Use the reference pages to look up [CLI options](cli.md), [settings](settings.md), [provider authentication](providers.md), [keybindings](keybindings.md), and [environment variables](environment-variables.md).
 
-Authenticate with `/login` for subscription providers, or set an API key such as `ANTHROPIC_API_KEY` before starting knightcode.
+For platform-specific help, see [Terminal Setup](terminal-setup.md), [Windows](windows.md), [tmux](tmux.md), [Termux on Android](termux.md), or [Containerization](containerization.md).
 
-For the full first-run flow, see [Quickstart](quickstart.md).
+## Work safely
 
-## Start here
-
-- [Quickstart](quickstart.md) - install, authenticate, and run a first session.
-- [Using KnightCode](usage.md) - interactive mode, slash commands, context files, and CLI reference.
-- [Providers](providers.md) - subscription and API-key setup for built-in providers.
-- [llama.cpp](llama-cpp.md) - run a local router and manage models with `/llama`.
-- [Security](security.md) - project trust, sandbox boundaries, and vulnerability reporting.
-- [Containerization](containerization.md) - sandbox knightcode with Gondolin, Docker, or OpenShell.
-- [Settings](settings.md) - global and project settings.
-- [Keybindings](keybindings.md) - default shortcuts and custom keybindings.
-- [Sessions](sessions.md) - session management, branching, and tree navigation.
-- [Compaction](compaction.md) - context compaction and branch summarization.
-
-## Customization
-
-- [Extensions](extensions.md) - TypeScript modules for tools, commands, events, and custom UI.
-- [Skills](skills.md) - Agent Skills for reusable on-demand capabilities.
-- [Prompt templates](prompt-templates.md) - reusable prompts that expand from slash commands.
-- [Themes](themes.md) - built-in and custom terminal themes.
-- [KnightCode packages](packages.md) - bundle and share extensions, skills, prompts, and themes.
-- [Custom models](models.md) - add model entries for supported provider APIs.
-- [Custom providers](custom-provider.md) - implement custom APIs and OAuth flows.
-
-## Programmatic usage
-
-- [SDK](sdk.md) - embed knightcode in Node.js applications.
-- [RPC mode](rpc.md) - integrate over stdin/stdout JSONL.
-- [JSON event stream mode](json.md) - print mode with structured events.
-- [TUI components](tui.md) - build custom terminal UI for extensions.
-
-## Reference
-
-- [Environment variables](environment-variables.md) - KnightCode process configuration and session metadata available to bash tools.
-- [Session format](session-format.md) - JSONL session file format, entry types, and SessionManager API.
-
-## Platform setup
-
-- [Windows](windows.md)
-- [Termux on Android](termux.md)
-- [tmux](tmux.md)
-- [Terminal setup](terminal-setup.md)
-- [Shell aliases](shell-aliases.md)
-
-## Development
-
-- [Development](development.md) - local setup, project structure, and debugging.
+KnightCode's tools and extensions run with the permissions of the KnightCode process. Project trust controls which project resources KnightCode loads, but it does not sandbox tool calls. Review [Security](security.md) before using untrusted files, repositories, extensions, or unattended automation.

package/bin/docs/json.md

@@ -1,98 +1,226 @@
-# JSON Event Stream Mode
+# JSON Event Stream
+
+JSON mode emits structured progress for one invocation:
 
 ```bash
-knightcode --mode json "Your prompt"
+knightcode --mode json "Review this repository"
 ```
 
-Outputs all session events as JSON lines to stdout. Useful for integrating knightcode into other tools or custom UIs.
+KnightCode writes one session header followed by session events, then exits after the supplied prompts finish. RPC mode emits the same session-event shapes but has no session header because it is a bidirectional, long-lived protocol. See [RPC Mode](rpc.md).
 
-## Event Types
+This page is the canonical reference for events shared by JSON and RPC mode. Message values use the [shared message types](message-types.md).
 
-Wire events use `JsonAgentSessionEvent`. It matches
-[`AgentSessionEvent`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/coding-agent/src/core/agent-session.ts)
-except that streaming message updates omit cumulative snapshots:
+## Framing and process I/O
 
-```typescript
-type WithoutPartial<T> = T extends { partial: unknown } ? Omit<T, "partial"> : T;
+The stream uses strict JSONL framing. Each record is one JSON object terminated by LF (`\n`). Split records only on LF and strip an optional preceding carriage return. Unicode line and paragraph separators are valid inside JSON strings and are not record boundaries.
 
-type JsonAssistantMessageEvent<T> = T extends { type: "toolcall_start"; partial: unknown }
-  ? WithoutPartial<T> & { id: string; toolName: string }
-  : WithoutPartial<T>;
+Node.js `readline` is not suitable for this stream because it also recognizes those Unicode separators. Use a byte or UTF-8 stream decoder and split on LF.
 
-type JsonAgentSessionEvent =
-  | Exclude<AgentSessionEvent, { type: "message_update" }>
-  | {
-      type: "message_update";
-      usage: Usage;
-      assistantMessageEvent: JsonAssistantMessageEvent<AssistantMessageEvent>;
-    };
+Read stdout continuously. A reader that stops consuming records can stall KnightCode when the pipe buffer fills. Stdout is reserved for JSONL; diagnostics and application logging go to stderr.
+
+## Session header
+
+The first JSON-mode record is the current [session header](session-format.md#sessionheader):
+
+```json
+{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path"}
 ```
 
-`queue_update` emits the full pending steering and follow-up queues whenever they change. `compaction_start` and `compaction_end` cover both manual and automatic compaction.
+RPC mode does not emit this record. Use [`get_state`](rpc-commands.md#get_state) for its current session ID and file.
 
-Other base events come from
-[`AgentEvent`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/agent/src/types.ts):
+## Event sequence
 
-```typescript
-type AgentEvent =
-  // Agent lifecycle
-  | { type: "agent_start" }
-  | { type: "agent_end"; messages: AgentMessage[] }
-  // Turn lifecycle
-  | { type: "turn_start" }
-  | { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] }
-  // Message lifecycle
-  | { type: "message_start"; message: AgentMessage }
-  | { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }
-  | { type: "message_end"; message: AgentMessage }
-  // Tool execution
-  | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any }
-  | { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any }
-  | { type: "tool_execution_end"; toolCallId: string; toolName: string; result: any; isError: boolean };
+A basic run produces records like these:
+
+```json
+{"type":"agent_start"}
+{"type":"turn_start"}
+{"type":"message_start","message":{"role":"user","content":"Review this repository","timestamp":1733234401000}}
+{"type":"message_end","message":{"role":"user","content":"Review this repository","timestamp":1733234401000}}
+{"type":"message_start","message":{"role":"assistant","content":[],"stopReason":"pending","...":"..."}}
+{"type":"message_update","usage":{"...":"..."},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
+{"type":"message_end","message":{"role":"assistant","...":"..."}}
+{"type":"turn_end","message":{"role":"assistant","...":"..."},"toolResults":[]}
+{"type":"agent_end","messages":[{"...":"..."}],"willRetry":false}
+{"type":"agent_settled"}
 ```
 
-## Message Types
+`agent_end` closes one low-level agent run. Automatic retry, overflow recovery, compaction retry, steering, or follow-up work can still continue. `agent_settled` means KnightCode has no remaining automatic work for that session-level run.
+
+## Agent and turn events
 
-Base messages from [`packages/ai/src/types.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/ai/src/types.ts#L134):
-- `UserMessage` (line 134)
-- `AssistantMessage` (line 140)
-- `ToolResultMessage` (line 152)
+| Event | Fields | Meaning |
+|---|---|---|
+| `agent_start` | None | A low-level agent run started. |
+| `agent_end` | `messages`, `willRetry` | That low-level run ended. `messages` contains messages generated by the run. |
+| `agent_settled` | None | KnightCode will not continue automatically through retries, compaction recovery, or queued messages. |
+| `turn_start` | None | One assistant turn started. |
+| `turn_end` | `message`, `toolResults` | One assistant response and its resulting tool calls finished. |
 
-Extended messages from [`packages/coding-agent/src/core/messages.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/coding-agent/src/core/messages.ts#L29):
-- `BashExecutionMessage` (line 29)
-- `CustomMessage` (line 46)
-- `BranchSummaryMessage` (line 55)
-- `CompactionSummaryMessage` (line 62)
+A turn is one assistant response plus any tool calls and tool results produced by that response.
 
-## Output Format
+## Message events
 
-Each line is a JSON object. The first line is the session header:
+| Event | Fields | Meaning |
+|---|---|---|
+| `message_start` | `message` | A message started. |
+| `message_update` | `usage`, `assistantMessageEvent` | An assistant message emitted a content-block update. |
+| `message_end` | `message` | A message completed. This is the authoritative final message. |
+
+### Reconstruct streaming messages
+
+Wire `message_update` records are delta-only. They omit the SDK event's cumulative `message` field and every `assistantMessageEvent.partial` snapshot so stream size remains linear.
+
+The nested event is one of:
+
+| Type | Fields in addition to `type` | Meaning |
+|---|---|---|
+| `start` | None | The provider stream started; its cumulative `partial` field is removed on the wire. |
+| `text_start` | `contentIndex` | A text block started. |
+| `text_delta` | `contentIndex`, `delta` | Append text to the block. |
+| `text_end` | `contentIndex`, `content` | The text block ended with authoritative content. |
+| `thinking_start` | `contentIndex` | A thinking block started. |
+| `thinking_delta` | `contentIndex`, `delta` | Append thinking text to the block. |
+| `thinking_end` | `contentIndex`, `content` | The thinking block ended with authoritative content. |
+| `toolcall_start` | `contentIndex`, `id`, `toolName` | A tool-call block started. |
+| `toolcall_delta` | `contentIndex`, `delta` | Append serialized argument data. |
+| `toolcall_end` | `contentIndex`, `toolCall` | The tool call ended with the complete `ToolCall`. |
+| `done` | `reason`, `message` | The provider stream completed successfully. |
+| `error` | `reason`, `error` | The provider stream ended with an error or abort message. |
+
+The normal agent loop translates provider-level `start`, `done`, and `error` into `message_start` and `message_end` session events rather than emitting them as `message_update`. They remain admitted by the exported `JsonAgentSessionEvent` transformation for callers that construct a matching session event.
+
+Use `contentIndex` to identify the content block. Buffer `delta` fields for a live display, but replace reconstructed data with the completed content in `text_end`, `thinking_end`, or `toolcall_end`. Replace the whole partial message with `message_end.message` when it arrives.
+
+The top-level `usage` is the latest cumulative provider-reported usage for the assistant response. It can remain zero until completion when a provider does not report usage while streaming.
 
 ```json
-{"type":"session","version":3,"id":"uuid","timestamp":"...","cwd":"/path"}
+{"type":"message_update","usage":{"input":100,"output":1,"cacheRead":0,"cacheWrite":0,"totalTokens":101,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello "}}
 ```
 
-Followed by events as they occur:
+## Tool execution events
+
+| Event | Fields | Meaning |
+|---|---|---|
+| `tool_execution_start` | `toolCallId`, `toolName`, `args` | Tool execution started. |
+| `tool_execution_update` | `toolCallId`, `toolName`, `args`, `partialResult` | The tool reported a partial result. |
+| `tool_execution_end` | `toolCallId`, `toolName`, `result`, `isError` | Tool execution finished. |
+
+Use `toolCallId` to correlate the lifecycle. `partialResult` is the latest partial result supplied by the tool. Whether it replaces or extends an earlier update depends on that tool's result contract.
 
 ```json
-{"type":"agent_start"}
-{"type":"turn_start"}
-{"type":"message_start","message":{"role":"assistant","content":[],...}}
-{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
-{"type":"message_end","message":{...}}
-{"type":"turn_end","message":{...},"toolResults":[]}
-{"type":"agent_end","messages":[...]}
+{"type":"tool_execution_start","toolCallId":"call_abc123","toolName":"bash","args":{"command":"ls -la"}}
+{"type":"tool_execution_update","toolCallId":"call_abc123","toolName":"bash","args":{"command":"ls -la"},"partialResult":{"content":[{"type":"text","text":"partial output"}],"details":{}}}
+{"type":"tool_execution_end","toolCallId":"call_abc123","toolName":"bash","result":{"content":[{"type":"text","text":"complete output"}],"details":{}},"isError":false}
 ```
 
-`message_update` records are delta-only. They omit both the cumulative `message` field and
-`assistantMessageEvent.partial` to keep stream size linear. The top-level `usage` field contains
-the latest cumulative provider-reported usage and may remain zero when a provider only reports
-usage at completion. Use `contentIndex` and `delta` to assemble live text, thinking, or tool-call
-arguments if needed. A `toolcall_start` event also includes the constant-sized `id` and `toolName`
-fields. `message_end` contains the final authoritative message.
+## Queue and state events
+
+| Event | Fields | Meaning |
+|---|---|---|
+| `queue_update` | `steering`, `followUp` | The pending steering or follow-up queue changed. Both fields contain the complete current queue. |
+| `entry_appended` | `entry` | An extension appended a custom session entry through `knightcode.appendEntry()`. |
+| `session_info_changed` | `name` | The session display name changed. An absent `name` means it was cleared. |
+| `thinking_level_changed` | `level` | The active thinking level changed. |
+
+The `entry` value uses a persisted [session entry type](session-format.md#entry-types).
+
+## Compaction events
+
+`compaction_start` reports why compaction began:
+
+```json
+{"type":"compaction_start","reason":"threshold"}
+```
+
+`reason` is `"manual"`, `"threshold"`, or `"overflow"`.
+
+`compaction_end` contains the result when compaction succeeds:
+
+```json
+{
+  "type": "compaction_end",
+  "reason": "threshold",
+  "result": {
+    "summary": "Summary of conversation...",
+    "firstKeptEntryId": "abc123",
+    "tokensBefore": 150000,
+    "estimatedTokensAfter": 32000,
+    "usage": {"...": "..."},
+    "details": {}
+  },
+  "aborted": false,
+  "willRetry": false
+}
+```
+
+If compaction was aborted, `result` is absent and `aborted` is true. If it failed, `result` is absent, `aborted` is false, and `errorMessage` describes the failure. Successful overflow recovery sets `willRetry` to true before KnightCode retries the prompt.
+
+See [Compaction and Branch Summaries](compaction.md) for result semantics.
+
+## Retry events
+
+Assistant-turn retry emits:
+
+```json
+{"type":"auto_retry_start","attempt":1,"maxAttempts":3,"delayMs":2000,"errorMessage":"529 overloaded"}
+{"type":"auto_retry_end","success":true,"attempt":2}
+```
+
+On final failure, `auto_retry_end` has `success: false` and a `finalError` string.
+
+Compaction and branch-summary retry emit:
+
+```json
+{"type":"summarization_retry_scheduled","attempt":1,"maxAttempts":3,"delayMs":2000,"errorMessage":"terminated"}
+{"type":"summarization_retry_attempt_start","source":"compaction","reason":"threshold"}
+{"type":"summarization_retry_finished"}
+```
+
+For a branch summary, `source` is `"branchSummary"` and `reason` is absent. The `reason` on a compaction retry is `"manual"`, `"threshold"`, or `"overflow"`.
+
+## RPC-only events
+
+A direct RPC [`bash`](rpc-commands.md#bash) command emits one `bash_execution_update` for each output chunk. Its optional `id` matches the command ID. The final command response can contain truncated output, but these events stream all output:
+
+```json
+{"type":"bash_execution_update","id":"req-1","delta":"total 48\n"}
+```
+
+RPC also adds `extension_error` when an extension handler throws:
+
+```json
+{"type":"extension_error","extensionPath":"/path/to/extension.ts","event":"tool_call","error":"Error message"}
+```
+
+Extension UI records are a separate RPC subprotocol, not `AgentSessionEvent` values. See [RPC Extension UI](rpc-extension-ui.md).
+
+## TypeScript types
+
+The SDK's `AgentSessionEvent` contains cumulative streaming snapshots for in-process consumers. JSON and RPC transform only `message_update`:
+
+```typescript
+type WithoutPartial<T> = T extends { partial: unknown } ? Omit<T, "partial"> : T;
+
+type JsonAssistantMessageEvent<T> = T extends { type: "toolcall_start"; partial: unknown }
+  ? WithoutPartial<T> & { id: string; toolName: string }
+  : WithoutPartial<T>;
+
+type JsonAgentSessionEvent =
+  | Exclude<AgentSessionEvent, { type: "message_update" }>
+  | {
+      type: "message_update";
+      usage: Usage;
+      assistantMessageEvent: JsonAssistantMessageEvent<AssistantMessageEvent>;
+    };
+```
+
+Use the exported `JsonAgentSessionEvent` type from `@knightcodeai/cli`. Its implementation is in [`json-event.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/cli/src/modes/json-event.ts).
 
 ## Example
 
+Print completed messages from a one-shot run:
+
 ```bash
 knightcode --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'
 ```