@knightcodeai/cli 0.17.3 → 0.18.0

package/docs/extensions.md

@@ -0,0 +1,314 @@
+# Extensions
+
+Extensions are TypeScript modules that add executable behavior to KnightCode. Use one when a workflow needs tools, commands, event handlers, model providers, session state, or terminal UI rather than instructions alone.
+
+An extension runs inside the KnightCode process with the same operating-system permissions. It can inspect prompts, tool calls, files, credentials, and session history, so load extensions only from sources you trust.
+
+Typical extensions add an agent tool, protect paths, confirm dangerous commands, react to session events, modify context, expose a command, or display persistent status.
+
+<a id="quick-start"></a>
+<a id="writing-an-extension"></a>
+<a id="create-an-extension"></a>
+
+## Create and load an extension
+
+An extension exports a default factory that receives `ExtensionAPI`. The factory registers capabilities for the current extension runtime.
+
+Create `~/.knightcode/agent/extensions/hello.ts`:
+
+```typescript
+import type { ExtensionAPI } from "@knightcodeai/cli";
+
+export default function (knightcode: ExtensionAPI) {
+  knightcode.registerCommand("hello", {
+    description: "Show a greeting",
+    handler: async (name, ctx) => {
+      ctx.ui.notify(`Hello, ${name || "world"}!`, "info");
+    },
+  });
+}
+```
+
+Start KnightCode and run `/hello`. During development, load a file directly:
+
+```bash
+knightcode --extension ./hello.ts
+```
+
+KnightCode uses `jiti`, so local TypeScript extensions do not need a separate compilation step. Use [KnightCode packages](packages.md) for distributed extensions and dependencies.
+
+<a id="extension-locations"></a>
+<a id="available-imports"></a>
+<a id="choose-where-it-loads"></a>
+
+## Add it to KnightCode
+
+Place the extension in your user or project extensions directory. KnightCode loads direct TypeScript or JavaScript files and subdirectories containing an `index.ts` or `index.js` entry point.
+
+Use a single file for a small extension and a directory for a multi-file implementation. Put npm dependencies in a nearby `package.json`. See [Configuration](configuration.md) for conventional locations and [Settings](settings.md#resources) for additional paths.
+
+Reload replaces the extension runtime, so code after `await ctx.reload()` must not reuse state from the old runtime. Only personal and explicit command-line extensions can participate in the `project_trust` event that runs before project extensions load.
+
+<a id="understand-the-lifecycle"></a>
+
+## Respect the runtime lifecycle
+
+The factory can be synchronous or asynchronous. KnightCode waits for an asynchronous factory before startup continues, allowing it to fetch configuration or register providers needed during startup.
+
+Do not start processes, sockets, watchers, or timers in the factory because some invocations load extensions without starting a session.
+Start long-lived resources from `session_start` or from the command or tool that needs them.
+Close session-scoped resources from an idempotent `session_shutdown` handler.
+
+A run proceeds from input and `before_agent_start`, through model, message, and tool events, to `agent_end`.
+KnightCode counts as busy while a run starts, including the compaction check and `before_agent_start`, so messages sent meanwhile go into the starting run.
+Automatic retries, recovery, compaction, or queued work can continue afterward.
+<a id="agent_start--agent_end--agent_before_settle--agent_settled"></a>
+
+`agent_before_settle` is the final actionable boundary: it can append entries and request one continuation.
+`agent_settled` is final and notification-only; use it when an integration needs to know KnightCode will not continue automatically.
+
+<a id="extensionapi-methods"></a>
+
+## Choose an integration point
+
+| Capability | Main API |
+|---|---|
+| Observe or modify lifecycle behavior | `knightcode.on()` |
+| Add a model-callable operation | `knightcode.registerTool()` |
+| Add a `/` command | `knightcode.registerCommand()` |
+| Add a shortcut or CLI flag | `knightcode.registerShortcut()` or `knightcode.registerFlag()` |
+| Send user or custom messages | `knightcode.sendUserMessage()` or `knightcode.sendMessage()` |
+| Persist non-context session data | `knightcode.appendEntry()` |
+| Change active tools, model, or thinking level | Session control methods on `knightcode` |
+| Add a model provider | `knightcode.registerProvider()` |
+| Add an MCP server | `knightcode.registerMcpServer()` |
+| Route each request to a model | [`knightcode.registerVirtualModel()`](virtual-models.md) |
+| Add terminal rendering | Renderer registration and `ctx.ui` |
+| Communicate with another extension | `knightcode.events` |
+
+Use the exported declarations in [`extensions/types.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/cli/src/core/extensions/types.ts) for exact event, context, tool, and result types.
+
+## Follow the extension contracts
+
+<a id="events"></a>
+<a id="work-with-events"></a>
+
+### Events and concurrency
+
+Handlers run in extension load and registration order. `knightcode.on()` returns a function that unsubscribes that registration; changes do not affect a dispatch already in progress.
+Some events notify; others transform data, replace results, or cancel an operation.
+Use each event’s declared result type rather than assuming every return value has an effect.
+
+Events cover resource discovery, sessions, agent and message lifecycle, providers, tools, and raw input.
+
+`before_agent_start` exposes both the current prompt and its structured `systemPromptOptions`. `event.messageType` says what started the run: `"user"` for a prompt or `knightcode.sendUserMessage()`, with `prompt` and `images`; `"custom"` for `knightcode.sendMessage(..., { triggerTurn: true })`, with the starting `message` and no `prompt`. A returned `message` is added to either kind of run; check `messageType` to skip runs started by custom messages. Prefer changing prompt sections, selected tools, or guidelines so KnightCode can append a transcript delta. Returning `systemPrompt`, or setting `forceSystemPrompt`, replaces the whole prompt for that run while the transcript continues recording the structured sections. Providers receive the forced text as their leading system prompt.
+
+`message_end` can replace a finalized message while preserving its role. `tool_call` can mutate input or block execution. `tool_result` handlers compose, with each handler seeing prior changes.
+
+<a id="provider_stream_event"></a>
+
+`provider_stream_event` fires for each parsed provider stream event before KnightCode normalizes it. The event identifies the provider, API, and model; `event.data` is the earliest structured value available to KnightCode, not necessarily the original HTTP bytes or SSE frame. Treat it as read-only because mutation can affect normalization. The event is notification-only and is not persisted.
+
+Handlers are awaited in stream order, so slow handlers delay stream consumption. Handler errors are reported without changing the provider response. See [`debug-provider.ts`](../examples/extensions/debug-provider.ts) for an opt-in viewer that groups raw events by assistant message.
+
+<a id="context_with_system"></a>
+
+`context` transforms conversation messages without prompt and tool system messages; KnightCode restores that state afterward. Use `context_with_system` only when a request-local transformation must own the complete transcript, and keep a system message at index zero.
+
+`turn_end` and `agent_before_settle` are actionable boundaries. Their handlers can chain proposed `custom`, `custom_message`, `context_edit`, or `compaction` entries and return `continue: true` for one next model request. Returning `end: true` ends the owning run after valid entries are committed; it overrides continuation and does not drain queued user input. `event.end` exposes the accumulated end request, which later handlers cannot undo. Guard continuation conditions because an unconditional continuation can loop. Use the exported event declarations for the complete validation and ordering contract.
+
+<a id="cache_warming_decision"></a>
+
+`cache_warming_decision` can override an idle prompt-cache refresh with `{ action: "warm" }` or `{ action: "stop" }`. The last handler that returns an action wins.
+
+Tool calls from one assistant message can run in parallel.
+Do not assume a sibling call or result exists when another tool event runs.
+Use `ctx.signal` for nested work owned by an active turn; commands and idle session events often have no operation signal.
+
+A `user_bash` handler that returns `undefined` passes the command to the next handler and then to local execution if no handler handles it. Returning `operations` or `result` stops propagation. A handler failure blocks the command rather than falling through to local execution.
+
+<a id="custom-tools"></a>
+<a id="register-tools"></a>
+
+### Tools
+
+A custom tool defines a name, model-facing description, TypeBox parameter schema, and `execute()` function.
+Its result requires model-facing `content` and a `details` field for rendering or state reconstruction.
+Use `details: undefined` when there are no structured details. If the tool makes nested model calls, include their `usage` in the result so session totals remain accurate.
+
+Throw from `execute()` to produce a failed tool result.
+Returning an object does not mark it as an error.
+Return `terminate: true` only when the agent should skip its automatic follow-up after every completed tool in that batch agrees to terminate.
+
+Use sequential execution when tools share mutable in-memory state.
+File-mutating tools should wrap the complete read-modify-write operation with `withFileMutationQueue()`.
+Truncate large model-facing results and tell the model where to read the complete output.
+
+Declare `outputSchema` and return a matching `structuredContent` when the result is data. The model still receives `content`; programmatic callers such as codemode scripts receive `structuredContent` instead of the text. Tools without `outputSchema` are passed to scripts as their text content. To report a failure that still carries data, return the result with `isError: true` instead of throwing: the model sees an error, and scripts still receive `structuredContent`.
+
+A tool can run other tools with `ctx.executeTool(name, args, { signal, onUpdate })`. Nested calls go through argument validation and the `tool_call` and `tool_result` handlers like model-issued calls, and emit `tool_execution_start`, `tool_execution_update`, and `tool_execution_end`; all of these events carry `parentToolCallId`, and their `toolCallId` is assigned by knightcode as `<parent id>/<n>`. These ids do not appear as tool calls or tool results in the transcript. Nested calls do not add transcript entries: their results only reach the calling tool, which reports them itself, for example through `onUpdate` and `details`. The session keeps a bounded record of them (name, arguments, status, duration, error; never results) as `nestedCalls` on the calling tool's result message. It is used for compaction file lists and shown in HTML exports. Arguments over 8 KiB per call or 32 KiB per tool result are omitted, at most 256 calls are kept, and `complete: false` marks a record that lost anything. The `usage` of nested results, at every depth, is added to the calling tool's result `usage`, so a tool reports only its own usage, not that of the tools it called. `ctx.tools` lists the tools `ctx.executeTool()` can call. `tool_result` handlers that redact `content` should also replace `structuredContent`; replacing only `content` drops it.
+
+See [`hello.ts`](../examples/extensions/hello.ts), [`todo.ts`](../examples/extensions/todo.ts), [`dynamic-tools.ts`](../examples/extensions/dynamic-tools.ts), and [`truncated-tool.ts`](../examples/extensions/truncated-tool.ts).
+
+### Tool exposure
+
+`exposure` controls how the model reaches a tool. "Callable" means callable from other tools through `ctx.executeTool()` (`ctx.tools`), as the `codemode` tool's scripts do:
+
+- `direct` (default): declared to the model while active, and callable while active.
+- `model-only`: declared to the model while active, never callable. Use it for tools that orchestrate other tools or ask the user.
+- `codemode`: callable whenever registered, and listed by the `codemode` tool. Not declared to the model unless activated explicitly.
+- `deferred`: like `codemode`, but codemode tools do not list it; `tool_search` can find and activate it.
+- `hidden`: registered but unreachable. Re-register a tool with `exposure: "hidden"` to withdraw it, since tools cannot be unregistered.
+
+`namespace: { name, aliases, description, instructions }` groups related tools, as MCP servers do. Codemode tools list a namespace under one heading with its `description`. `instructions` holds longer usage guidance; it is not listed, and codemode scripts read it with `describeNamespace(name)`. `aliases` are other names scripts may look the namespace up by, for example the server name `docs` for `mcp__docs`; a name and the same name as a script identifier (`my-docs`, `my_docs`) match alike.
+
+Registering a `direct` or `model-only` tool activates it unless `defaultActive: false` keeps it optional; the other exposures are not activated on registration. The active set (`knightcode.getActiveTools()`, `knightcode.setActiveTools()`) is the set of tools declared to the model. `knightcode.getAllTools()` reports each tool's `exposure`, `namespace`, `annotations`, and `reachesTools`.
+
+`annotations` are hints about what a tool does, with the meaning of MCP tool annotations: `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`. MCP tools carry the hints their server declares. Missing hints take the MCP defaults: a tool is not read-only, and may be destructive and reach an open world. The hints are not verified, but a permission extension can use them to decide which calls to confirm. This confirms the calls Codex asks approval for:
+
+```typescript
+knightcode.on("tool_call", async (event, ctx) => {
+  const hints = knightcode.getAllTools().find((tool) => tool.name === event.toolName)?.annotations;
+  const needsApproval =
+    hints?.destructiveHint === true ||
+    (!hints?.readOnlyHint && ((hints?.destructiveHint ?? true) || (hints?.openWorldHint ?? true)));
+  if (needsApproval && !(await ctx.ui.confirm("Allow tool call?", event.toolName))) {
+    return { block: true, reason: `${event.toolName} was not approved` };
+  }
+});
+```
+
+A tool that orchestrates other tools can adjust what the model sees while it is active with `prepareLoadout(loadout)`. It runs whenever the active tools change and receives the declared tools, the callable tools, and every registered tool with its exposure, namespace, and prompt guidelines. It returns replacement `descriptions` for declared tools (including its own) and `hiddenDeclarations`: active tools whose declarations requests leave out while they stay active and callable. The default system prompt leaves hidden tools out of its tool list and rules, and names no tool in the skills hint when the file reader is hidden, so the orchestrating tool should present their guidelines itself. `codemode` uses only this hook, `exposure`, `reachesTools`, and `ctx.executeTool()`, so another tool can implement the same behavior under a different name.
+
+A tool that reaches other tools declares which ones a call may reach with `reachesTools(input)`: `"all"`, or the words of the input that may name them, where a word refers to every tool or namespace whose name it contains. `codemode` returns `"all"` for scripts that search or list tools and the words of the script otherwise; `tool_search` always returns `"all"`. Extensions that register tools late use it from their `tool_call` handler to finish registering the tools a call needs before it runs, as the MCP extension does for servers that are still connecting. The MCP extension also activates `codemode` or `tool_search` for MCP tools only when the tool of that name declares `reachesTools`.
+
+### Activate tools dynamically
+
+Register every tool first, keep optional tools inactive, and use `knightcode.setActiveTools()` from a loader tool to select the desired active tools. Names must already be registered; unknown names are ignored.
+
+KnightCode records the initial prompt and tool set in the transcript's first system message, then appends tool and prompt changes before the next model request. Providers that cannot represent the transition receive a complete transcript checkpoint, which can invalidate the cached prefix.
+
+### Tool rendering
+
+A tool's `renderCall` and `renderResult` draw its calls in the interactive transcript and in HTML exports. `knightcode.registerToolRenderer((toolName, next) => renderers)` chooses renderers for calls to any tool, including tools that are not registered yet, such as MCP tools in a resumed session before their server connected. `next()` returns what the remaining resolvers (in extension load order), then the registered tool, would use, so `next() ?? mine` only fills in.
+
+### MCP servers
+
+`knightcode.registerMcpServer(name, config)` adds an MCP server for the current session. `config` has the shape of an `mcpServers` entry in [`mcp.json`](mcp.md): `command`, `args`, `env`, and `cwd` for stdio servers, `url`, `headers`, and `oauth` for HTTP servers, plus `exposure`, `toolExposure`, `description`, `enabled`, and `timeout`.
+
+```typescript
+knightcode.registerMcpServer("jira", { url: "https://mcp.example.com/jira", exposure: "codemode" });
+knightcode.unregisterMcpServer("jira");
+```
+
+Servers registered while the extension loads connect when the session starts, together with the `mcp.json` servers; servers registered later connect right away, and `knightcode.unregisterMcpServer()` closes the connection and makes the server's tools unreachable. Registrations are not saved: register again on every load, for example based on the extension's own settings. A server in `mcp.json` with the same name takes precedence, and `/mcp` shows the override. Registering the same name again replaces the extension's earlier registration; names registered by another extension, invalid names, and invalid configs throw.
+
+The built-in MCP support connects registered servers. When nothing does, because another extension replaced it (see [MCP](mcp.md#other-mcp-extensions)), each registration is reported as an extension error. Other MCP extensions can connect registered servers too: read them with `knightcode.getMcpServers()` on `session_start` and handle the `mcp_servers_change` event for later changes.
+
+<a id="extensioncontext"></a>
+<a id="extensioncommandcontext"></a>
+<a id="use-extension-context"></a>
+
+### Context and session changes
+
+`ExtensionContext` provides the working directory, mode, UI, session manager, model runtime, abort signal, context usage, and controls for compaction and shutdown.
+Use `ctx.modelRegistry.streamSimple()` for provider-neutral nested model calls.
+Use `ctx.modelRegistry.getAvailableClassifiers()` and `ctx.modelRegistry.classify()` to ask a classifier model structured questions, as the built-in [classifier gate](usage.md#classifier-gate) does.
+
+Command handlers receive `ExtensionCommandContext`, which adds operations for waiting until idle, reloading, tree navigation, and session replacement.
+These operations are command-only because calling them from lifecycle handlers can deadlock the runtime.
+
+Use `await ctx.sendUserMessage(content, options)` in a command when completion
+must include the dispatched run. It rejects dispatch or preflight failures and
+resolves after command handling or complete agent settlement. During an active
+run, a message sent with `deliverAs` is only queued: the promise resolves once
+it is queued, not when that run settles. The replacement context's method has
+the same contract. The originating prompt receives the nested dispatch's
+acceptance once, before settlement; command-only completion reports `handled`. Command-handler failures are reported and rethrown rather
+than acknowledged as successful. `knightcode.sendUserMessage()` remains
+fire-and-forget; waiting for idle after calling it is not equivalent because
+asynchronous preflight may still be running.
+
+`ctx.newSession({ preserveModel: true, setup, withSession })` optionally keeps
+the outgoing model and reasoning level instead of the host defaults. Capture
+plain data before replacement and dispatch through `withSession`'s context.
+
+Session replacement invalidates the old context. Capture only plain data before switching, then use the fresh context supplied to `withSession` for session-bound work.
+
+<a id="state-management"></a>
+<a id="persist-state"></a>
+
+### State
+
+Module-level variables are shared by every session in the process that loads
+the extension, and so are the providers it registers: one session calling
+`unregisterProvider` removes the provider for all of them. The desktop app's
+app server runs many sessions in one process, so keep per-session state inside
+the factory closure, not at module level. Virtual models are the exception:
+each session keeps its own route. Active cached factories are pinned; up to
+256 inactive factories remain. Eviction or `/reload` can re-evaluate a module
+on a future load, so module globals are not persistent storage. Eviction
+never tears down a live session's extension.
+
+Choose storage based on how state participates in the conversation:
+
+| State | Storage |
+|---|---|
+| Tool state that follows the active branch | Tool-result `details` |
+| Durable data excluded from model context | `knightcode.appendEntry()` |
+| Custom content stored and sent to the model | `knightcode.sendMessage()` |
+| Data outside one session | External storage |
+
+Reconstruct branch-sensitive state from `ctx.sessionManager.getBranch()` during `session_start`.
+Do not rebuild it from every file entry because abandoned branches represent alternative histories.
+Register an entry or message renderer when custom stored content should appear in the transcript.
+
+<a id="custom-ui"></a>
+<a id="mode-behavior"></a>
+<a id="interact-with-the-user"></a>
+<a id="account-for-each-mode"></a>
+
+### UI and modes
+
+`ctx.ui` provides dialogs, notifications, status text, widgets, titles, editor access, and custom components.
+Use `ctx.ui.custom()` only when the interaction needs its own rendering and input.
+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.
+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>
+
+RPC can forward supported dialogs and notifications through the [RPC Extension UI protocol](rpc-extension-ui.md), but not custom terminal components; JSON and print modes have no UI.
+Guard terminal-only behavior with `ctx.mode === "tui"` and use `ctx.hasUI` for interactions supported by interactive and RPC clients.
+
+Keep tool and event behavior independent from rendering so non-interactive modes remain functional.
+
+<a id="error-handling"></a>
+<a id="handle-errors-and-shutdown"></a>
+
+### Errors and cleanup
+
+KnightCode reports handler errors and continues where possible. A `tool_call` handler failure blocks the tool as a fail-safe; a tool execution failure becomes an error result for the model.
+
+Throw the exported `ExtensionStartupError` from `session_start` when an unsafe
+runtime must refuse initialization. Binding or reload propagates it to the
+host, and the failed session cannot prompt a provider, compact, or run
+extension commands until successful startup/reload clears the failure. Ordinary
+handler errors remain nonfatal.
+
+Release resources in `session_shutdown` even when normal operation attempted cleanup.
+Keep cleanup idempotent because cancellation, reload, session replacement, and process exit can converge on the same path.
+Use `ctx.shutdown()` to request an orderly process shutdown.
+
+<a id="examples-reference"></a>
+<a id="use-examples-as-the-implementation-reference"></a>
+
+## Examples and reference
+
+The checked [extension examples](../examples/extensions/) cover tools, lifecycle events, commands, flags, shortcuts, state, rendering, providers, OAuth, remote execution, and terminal components.
+Start with the smallest example matching your integration point.
+
+Use [Custom Providers](custom-provider.md) for model-service integrations, [Terminal UI](tui.md) for custom components, and [KnightCode Packages](packages.md) to install or distribute extensions with other resources.

package/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/docs/index.md

@@ -0,0 +1,39 @@
+# KnightCode
+
+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.
+
+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.
+
+## Start using KnightCode
+
+New to KnightCode? Follow the [Quickstart](quickstart.md) to install KnightCode, connect a model, and complete your first task.
+
+If KnightCode is already installed, choose what you want to do:
+
+- [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.
+
+## Customize KnightCode
+
+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.
+
+## Automate or embed KnightCode
+
+- 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.
+
+## Find reference and setup information
+
+Use the reference pages to look up [CLI options](cli.md), [settings](settings.md), [providers](providers.md), [keybindings](keybindings.md), and [environment variables](environment-variables.md).
+
+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).
+
+## Work safely
+
+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/docs/json.md

@@ -0,0 +1,226 @@
+# JSON Event Stream
+
+JSON mode emits structured progress for one invocation:
+
+```bash
+knightcode --mode json "Review this repository"
+```
+
+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).
+
+This page is the canonical reference for events shared by JSON and RPC mode. Message values use the [shared message types](message-types.md).
+
+## Framing and process I/O
+
+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.
+
+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.
+
+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"}
+```
+
+RPC mode does not emit this record. Use [`get_state`](rpc-commands.md#get_state) for its current session ID and file.
+
+## Event sequence
+
+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","aborted":false}
+```
+
+`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
+
+| 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` | `aborted` | KnightCode will not continue automatically through retries, compaction recovery, or queued messages. `aborted` is `true` when the run ended because it was aborted. |
+| `turn_start` | None | One assistant turn started. |
+| `turn_end` | `message`, `toolResults` | One assistant response and its resulting tool calls finished. |
+
+A turn is one assistant response plus any tool calls and tool results produced by that response.
+
+## Message events
+
+| 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":"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 "}}
+```
+
+## 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`, `durationMs` | Tool execution finished. `durationMs` is how long the tool's `execute()` took, measured with a monotonic clock; absent when the tool did not run. |
+
+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":"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}
+```
+
+## 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")'
+```