@knightcodeai/cli-linux-x64 0.9.1 → 0.9.2

package/bin/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @knightcodeai/cli
 
+## 0.9.2
+
+### Added
+
+- Added Claude Opus 5.5 to the Anthropic catalog: 1M context, image input, xhigh and max effort levels, and the mid-conversation effort and system-message support the newer Opus models use.
+
+- Added Grok 4.7 to the xAI catalog and made it the default xAI model. xAI models now carry their long-context pricing tier, so requests above 200k input tokens are costed at the higher rate.
+
+- Added the `context_with_system` extension event. It runs after the `context` handlers on the full transcript, system messages included, and its result is sent as returned.
+
+- Added per-model image resize profiles through `inputLimits.images.resize` in `models.json` and `modelOverrides`. File attachments, `read` and tool-result images are resized once for the selected model before they enter history; built-in vision models carry the previous 2000x2000, 4.5 MiB default explicitly.
+
+- Added a crash hint naming loaded extensions whose files appear in the crash stack trace, with the commands to disable them.
+
+- Added append-only context edits and actionable turn boundaries for extensions. A `context_edit` entry omits or replaces an earlier message in future model requests without changing raw history, usage or exports, and `turn_end` plus the new `agent_before_settle` event can append entries and ask for one more provider request. See `docs/extensions.md` and `docs/session-format.md`.
+
+- Added a session scratchpad, off by default: `/tools scratchpad on` gives the agent a private per-session temp directory for throwaway files and restores its `notes.md` there after each compaction.
+
+### Changed
+
+- Changed the session file to be the source of model context. SDK code that assigned `session.agent.state.messages` to restore history no longer affects the next request: restore with `SessionManager.inMemory(cwd, { id }, entries)` or move with `session.navigateTree()`. Extensions that switch exhaustively must handle the `context_edit` entry and the `agent_before_settle` event, `turn_end` events now carry the persisted entry ids, and runs started from an `agent_settled` handler wait until every settled handler has finished.
+
+### Removed
+
+- Removed the `shouldStopAfterTurn` agent option. Return `{ action: "end" }` from `finishTurn` instead, and return nothing for error and aborted responses to keep the old normal-response-only behaviour.
+
+### Fixed
+
+- Fixed a missing or invalid `--mode` value being silently ignored; KnightCode now reports the valid values and exits with a nonzero status.
+
+- Fixed split-turn compaction summaries being refused by Claude Fable 5.1. The summarization request now separates the conversation from the instructions and asks for a continuation checkpoint instead of a prefix summary.
+
+- Fixed image-only prompts being rejected by some OpenAI-compatible providers, which refused the empty text part sent alongside the image.
+
+- Fixed text files that begin with `GIF` being treated as images and left out of `read` and `@file` input. Detection now requires the full GIF87a or GIF89a signature.
+
+- Fixed `/bug` uploading a report in offline mode. Uploads are refused with a pointer to Export as Zip, which still works offline.
+
+- Fixed prompt templates with invalid YAML frontmatter being dropped silently. They are now reported as resource warnings, and valid templates beside them still load.
+
+- Fixed the jump-to-latest label in fullscreen mode shifting sideways when the scrollbar auto-hides.
+
+- Fixed abandoned attempts staying in the model's context after an error retry or a length/overflow recovery. The retried request now omits them; the raw transcript, exports and usage totals still show them.
+
+- Fixed `context` extension handlers that filter or slice messages dropping the system prompt and tool declarations, which after extension-driven compaction left requests without built-in tools. Handlers no longer see system messages, and KnightCode restores the prompt and tools after they run.
+
+- Fixed custom OpenAI-compatible endpoints receiving strict tool schemas they may reject. Built-in models that support strict tools keep them, and a custom model can opt back in with `compat.supportsStrictMode: true`.
+
+- Fixed session files with an invalid session id in their header opening normally. Extensions build directory paths from that id, so such a file is now refused with the same error as an invalid `--session-id`.
+
 ## 0.9.1
 
 ### Added

package/bin/README.md

@@ -1,36 +1,69 @@
-# @knightcodeai/cli
+<p align="center">
+  <a href="https://knightcode.dev">
+    <img alt="KnightCode logo" src="https://knightcode.dev/knightcode-mark.svg" width="128">
+  </a>
+</p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@knightcodeai/cli"><img alt="npm" src="https://img.shields.io/npm/v/@knightcodeai/cli?style=flat-square&logo=npm&logoColor=white" /></a>
+</p>
 
-`knightcode` — a local-first, bring-your-own-key AI coding CLI for your terminal.
+> New issues and PRs from new contributors are closed automatically. Maintainers review closed submissions daily. See [CONTRIBUTING.md](https://github.com/KnightCodeAI/knightcode/blob/main/CONTRIBUTING.md).
 
-## Install
+# KnightCode
+
+KnightCode is a minimal, extensible AI agent for the terminal. Adapt KnightCode to your workflow, not the other way around.
+
+Ask KnightCode to create the prompt templates, skills, extensions, and themes you need, or install a KnightCode package. Use KnightCode directly, automate it in print, JSON, or RPC mode, or build applications with the TypeScript SDK.
+
+## Getting started
+
+Install the command-line interface with npm:
 
 ```bash
-npm install -g @knightcodeai/cli
+npm install -g --ignore-scripts @knightcodeai/cli
 ```
 
-You don't need Bun — it's bundled into the platform binary. The small launcher
-(`bin/knightcode`) that spawns it runs on Node.js (>=18), which you already have
-if you installed with npm. The right platform binary installs automatically as
-an optional dependency.
+This requires Node.js 22 or newer. KnightCode does not require dependency lifecycle scripts for a normal npm installation. You do not need Bun: it is bundled into the platform binary, which installs automatically as an optional dependency for Linux (x64, arm64), macOS (x64, arm64), and Windows (x64).
 
-## Quick start
+On macOS or Linux, you can instead use the installer:
 
 ```bash
+curl -fsSL https://knightcode.dev/install.sh | sh
+```
+
+Start KnightCode in the directory where you want it to work:
+
+```bash
+cd /path/to/project
 knightcode
 ```
 
-On first run, set your OpenRouter API key from inside the app.
+For a built-in AI provider, run `/login` inside KnightCode to connect a subscription or API key. Then give KnightCode a task.
+
+See the [documentation](docs/index.md) for full setup and usage instructions.
 
-## Configuration
+## Development
 
-State lives in `~/.knightcode/` (sessions, settings, local SQLite database).
+Clone the repository, install its dependencies, and run KnightCode from source:
+
+```bash
+git clone https://github.com/KnightCodeAI/knightcode
+cd knightcode
+bun install
+bun run start
+```
+
+`bun run start` runs the CLI from source with the repository's `.env` loaded.
+
+Before submitting changes, run:
+
+```bash
+bun run check-types
+cd packages/<package> && bun x vitest --run test/<changed>.test.ts
+```
 
-| Command / env var | Effect |
-| ----------------- | ------ |
-| `knightcode --version` | Print the installed version |
-| `knightcode doctor` | Print diagnostics (config, database, API key, runtime) |
-| `KNIGHTCODE_NO_UPDATE_CHECK=1` | Disable the background update check |
+Read [CONTRIBUTING.md](https://github.com/KnightCodeAI/knightcode/blob/main/CONTRIBUTING.md) before opening an issue or pull request. It defines the contribution gate, issue quality bar, and required checks. Read [AGENTS.md](https://github.com/KnightCodeAI/knightcode/blob/main/AGENTS.md) for repository-specific implementation, testing, dependency, and release rules.
 
-## Supported platforms
+## License
 
-Linux (x64, arm64), macOS (x64, arm64), Windows (x64).
+MIT

package/bin/docs/cli-integration.md

@@ -0,0 +1,106 @@
+# CLI Integration
+
+By default, running `knightcode` opens the interactive terminal interface. When input or output is piped or redirected, KnightCode uses print mode instead. You can also select print, JSON, or RPC mode explicitly for scripts and applications.
+
+All four modes use the same agent, sessions, resources, and tools. The mode determines how input enters KnightCode, how output is exposed, and whether the process remains available for more commands.
+
+The SDK is not a CLI mode. It embeds the agent directly in a Node.js or Bun process. See the [SDK](sdk.md) when direct TypeScript access is preferable to a process boundary.
+
+## Choose a mode
+
+| Mode | Interface | Lifetime | Use it when |
+|---|---|---|---|
+| Interactive | Terminal UI | Until the user exits | A person is working with KnightCode directly |
+| Print | Final text on stdout | One invocation | A script needs the final assistant response |
+| JSON | JSONL events on stdout | One invocation | A process needs structured progress from a run |
+| RPC | JSONL commands, responses, and events | Long-lived | A process needs bidirectional control |
+
+CLI options still select the working directory, model, tools, resources, and session persistence independently of the mode. See [Command Line](cli.md) for the complete startup options.
+
+## Print to stdout
+
+Print mode runs the supplied prompts, writes the final assistant text to stdout, and exits:
+
+```bash
+knightcode --print "Summarize the changes in this repository"
+```
+
+Use print mode when only the final text is needed, including command substitution, pipelines, and one-shot jobs. Intermediate events are not exposed.
+
+Print mode writes errors to stderr. A final assistant response with an `error` or `aborted` stop reason produces a nonzero exit status.
+
+When no mode is selected explicitly, non-TTY stdin or stdout also selects print mode. This allows piped input and output without adding `--print`.
+
+## Stream JSON events
+
+JSON mode writes a session header followed by agent and session events as newline-delimited JSON:
+
+```bash
+knightcode --mode json "Review this repository" > events.jsonl
+```
+
+This is structured event output, not a single JSON result or a constraint on the format of the model’s response.
+
+All prompts are supplied when the process starts. The process streams events for that run and then exits; it does not accept later commands.
+
+A failed or aborted assistant response appears in the event stream but does not by itself produce a nonzero exit status. Inspect the events when success or failure matters. KnightCode still exits nonzero if the invocation throws an error.
+
+Streaming `message_update` records contain deltas rather than a growing message snapshot. Assemble live output from the delta events, then replace it with the authoritative message from `message_end`.
+
+`agent_end` can be followed by automatic recovery or queued work. `agent_settled` marks the end of automatic work for the current run.
+
+Stdout is reserved for JSONL. Diagnostics and application logging are written to stderr. See [JSON Event Stream](json.md) for framing, event shapes, and reconstruction rules.
+
+## Control KnightCode with RPC
+
+RPC mode keeps KnightCode running while another process sends commands and receives responses and events:
+
+```bash
+knightcode --mode rpc --no-session
+```
+
+Commands are JSON objects written to stdin. Responses and events are JSON objects written to stdout. Every record occupies one line.
+
+Add an `id` to commands that need correlation. The matching response repeats that ID. Events generally have no command ID because they describe session activity rather than one request.
+
+A successful `prompt` response means the prompt was accepted, queued, or handled. It does not mean the run completed. Continue consuming events through `agent_settled` when completion matters.
+
+RPC commands can change models, inspect state, manage sessions, run shell commands, and answer extension UI requests.
+
+Extension dialogs form a request-response subprotocol. Other extension UI updates are notifications that a client may display or ignore. TUI-only extension capabilities are unavailable or degraded outside interactive mode.
+
+For Node.js or TypeScript integrations, prefer `RpcClient` from `@knightcodeai/cli`. It starts a KnightCode RPC child process, correlates requests, exposes typed command methods, and delivers session events to listeners.
+
+The [RPC client example](../examples/rpc-client.ts) sends one prompt, streams text and tool activity, waits for `agent_settled`, and shuts down the child process. It is included in the repository’s TypeScript checks.
+
+`RpcClient.promptAndWait()` installs its event listener before sending the prompt, avoiding a race with fast completions. For separate operations, subscribe before calling `prompt()` and call `waitForIdle()` only while a run is active.
+
+The client requires a path to a runnable KnightCode CLI. The repository example points at `dist/cli.js`, so the package must be built before that example runs from a checkout.
+
+If you are building a client without `RpcClient`, start with [RPC Protocol](rpc.md), then use [RPC Commands](rpc-commands.md) and [JSON Event Stream](json.md) as the wire references.
+
+## Fork and rebrand KnightCode
+
+A source fork can change the CLI name and configuration directory through `package.json`:
+
+```json
+{
+  "piConfig": {
+    "name": "my-agent",
+    "configDir": ".my-agent"
+  }
+}
+```
+
+Change the top-level `bin` field to set the executable name. These settings affect the CLI banner, configuration paths, and derived environment variable names.
+
+## Examples and references
+
+- [RPC client](../examples/rpc-client.ts): typed Node.js integration
+- [RPC extension UI](../examples/rpc-extension-ui.ts): custom terminal client with extension dialogs
+- [Command Line](cli.md): startup options and mode selection
+- [JSON Event Stream](json.md): JSON event reference
+- [RPC Protocol](rpc.md): RPC lifecycle, framing, errors, and shutdown
+- [RPC Commands](rpc-commands.md): command and response reference
+- [RPC Extension UI](rpc-extension-ui.md): extension interaction subprotocol
+- [SDK examples](../examples/sdk/): in-process TypeScript integrations

package/bin/docs/cli.md

@@ -0,0 +1,270 @@
+<a id="cli-and-modes-reference"></a>
+
+# Command Line
+
+This page documents KnightCode's built-in command-line commands and options. Run `knightcode --help` or append `--help` to a command for the exact interface in your installed version. The top-level help also includes options registered by loaded extensions.
+
+```sh
+knightcode [options] [--] [@files...] [messages...]
+knightcode install <source> [options]
+knightcode remove <source> [options]
+knightcode uninstall <source> [options]
+knightcode update [target] [options]
+knightcode list
+knightcode config [options]
+knightcode auth <check|print-api-key|print-bearer-token> [options]
+```
+
+<a id="modes"></a>
+
+## Invocation and output
+
+```sh
+knightcode
+knightcode --print "Summarize this repository"
+git diff | knightcode --print "Review this change"
+knightcode --mode json "Inspect this repository" > events.jsonl
+```
+
+With terminal stdin and stdout, KnightCode opens the terminal UI unless `--print`, `--mode json`, or `--mode rpc` selects another interface. When either stream is redirected and neither JSON nor RPC mode is selected, KnightCode uses print mode. See [CLI Integration](cli-integration.md) for choosing between interactive, print, JSON, RPC, and SDK integration.
+
+| Input | Behavior |
+|---|---|
+| `message` | Provide an initial prompt |
+| `@path` | Include a text file or image in the first prompt |
+| Piped stdin | Prepend its contents to the first prompt |
+| `--` | Stop option parsing so a prompt can begin with `-` |
+
+KnightCode resolves `@path` from the current working directory. The working directory also controls project configuration, resource discovery, and session grouping.
+
+`--print` controls whether KnightCode runs once and exits. `--mode` selects the output interface. `--mode text` does not force one-shot execution when stdin and stdout are terminals; use `--print` for that behavior.
+
+| Option | Behavior |
+|---|---|
+| `-p`, `--print` | Run the supplied prompts, write the final assistant text to stdout, then exit |
+| `--mode text` | Select text output; still open the terminal UI when stdin and stdout are terminals |
+| `--mode json` | Run the supplied prompts, write JSONL events to stdout, then exit |
+| `--mode rpc` | Read JSONL commands from stdin and write responses and events to stdout until shutdown |
+| `--export <input> [output]` | Export a session file to HTML and exit; derive the destination when `output` is omitted |
+
+RPC mode rejects `@file` arguments. JSON and RPC modes reserve stdout for protocol records. See [JSON Event Stream](json.md) and [RPC Protocol](rpc.md).
+
+<a id="model-options"></a>
+
+## Models
+
+```sh
+knightcode --model sonnet:high
+```
+
+See [Choose a Model](models.md) for model selection and [Provider Authentication](providers.md) for credentials.
+
+- `--provider <name>`<br>
+  Restricts `--model` lookup to one provider.
+- `--model <pattern>`<br>
+  Selects by exact ID or fuzzy ID/name match. It accepts `provider/id` and an optional `:<thinking>` suffix.
+- `--api-key <key>`<br>
+  Uses a non-persistent API-key override. It requires a model selected through `--model` or `--models`.
+- `--thinking <level>`<br>
+  Sets `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. It overrides a `--model` suffix and is clamped to the model's capabilities.
+- `--models <patterns>`<br>
+  Sets a comma-separated scope for startup and cycling. It accepts exact IDs, fuzzy matches, case-insensitive globs, and optional `:<thinking>` suffixes.
+- `--list-models [search]`<br>
+  Lists available models, optionally filtered by a fuzzy search, then exits.
+
+<a id="session-options"></a>
+
+## Sessions
+
+```sh
+knightcode --continue
+```
+
+See [Sessions and Context](sessions.md) for resuming, forking, naming, and storing sessions.
+
+- `-c`, `--continue`<br>
+  Continues the most recent session for the current project.
+- `-r`, `--resume`<br>
+  Opens the session selector.
+- `--session <path|id>`<br>
+  Opens by file path, exact ID, or partial ID. KnightCode searches the current project first and offers to fork a cross-project match.
+- `--session-id <id>`<br>
+  Opens the exact project session ID or creates it if absent. IDs accept letters, numbers, `.`, `_`, and `-`.
+- `--fork <path|id>`<br>
+  Forks an existing session into a new session for the current project.
+- `--session-dir <dir>`<br>
+  Overrides storage and lookup. It takes precedence over `KNIGHTCODE_CODING_AGENT_SESSION_DIR` and the `sessionDir` setting.
+- `--no-session`<br>
+  Uses an in-memory session that is not persisted.
+- `-n`, `--name <name>`<br>
+  Sets the session display name.
+
+Constraints:
+
+- Session IDs must start and end with a letter or number.
+- `--fork` cannot be combined with `--session`, `--continue`, `--resume`, or `--no-session`.
+- `--session-id` cannot be combined with `--session`, `--continue`, or `--resume`. Combine it with `--fork` to choose the new ID.
+
+<a id="tool-options"></a>
+
+## Tools
+
+```sh
+knightcode --tools read,grep,find,ls --print "Review this project"
+```
+
+See [Settings](settings.md#tools) for configuring the default tool selection.
+
+- `-t`, `--tools <list>`<br>
+  Replaces the default selection with a comma-separated allowlist of built-in, extension, or custom tools.
+- `-xt`, `--exclude-tools <list>`<br>
+  Disables comma-separated tool names after all other selection options.
+- `-nbt`, `--no-builtin-tools`<br>
+  Disables default built-in tools while retaining extension and custom tools.
+- `-nt`, `--no-tools`<br>
+  Starts with all built-in, extension, and custom tools disabled.
+
+Default enabled tools are `read`, `bash`, `edit`, and `write`, unless `defaultTools` changes them.
+
+| Built-in | Purpose |
+|---|---|
+| `read` | Read text files and supported images |
+| `bash` | Run shell commands |
+| `powershell` | Run PowerShell commands on Windows |
+| `edit` | Apply exact text replacements to an existing file |
+| `write` | Create or overwrite a file |
+| `grep` | Search file contents |
+| `find` | Find paths using glob patterns |
+| `ls` | List directory contents |
+
+The [web tools](usage.md#web-tools) `webfetch` and `websearch` are off until enabled with `/tools`. A tool excluded here stays off whatever `/tools` says.
+
+<a id="resource-options"></a>
+
+## Resources
+
+```sh
+knightcode --extension ./review.ts
+```
+
+See [Configuration](configuration.md) for conventional directories and project trust, [Settings](settings.md#resources) for configured paths, and [KnightCode Packages](packages.md) for package sources.
+
+- `-e`, `--extension <path>`<br>
+  Loads an extension file or directory and is repeatable.
+- `-ne`, `--no-extensions`<br>
+  Disables discovered and configured extensions. Explicit `-e` paths still load.
+- `--skill <path>`<br>
+  Loads a skill file or directory and is repeatable.
+- `-ns`, `--no-skills`<br>
+  Disables discovered and configured skills. Explicit `--skill` paths still load.
+- `--prompt-template <path>`<br>
+  Loads a prompt-template file or directory and is repeatable.
+- `-np`, `--no-prompt-templates`<br>
+  Disables discovered and configured templates. Explicit `--prompt-template` paths still load.
+- `--theme <path>`<br>
+  Loads a theme file or directory and is repeatable.
+- `--use-theme <name[/name]>`<br>
+  Selects the initial interactive theme for this run.
+- `--no-themes`<br>
+  Disables discovered and configured themes. Explicit `--theme` paths still load.
+- `-nc`, `--no-context-files`<br>
+  Disables `AGENTS.md` and `CLAUDE.md` discovery.
+
+Resource paths apply only to the current process. Relative paths resolve from the current working directory.
+
+<a id="prompt-and-display-options"></a>
+
+## Prompts and process
+
+```sh
+knightcode --append-system-prompt ./instructions.md
+```
+
+See [Configuration](configuration.md) for saved configuration, [Security](security.md#understand-project-trust) for project trust, and [Environment Variables](environment-variables.md) for process controls.
+
+- `--system-prompt <text|path>`<br>
+  Replaces the default system prompt with text or the contents of an existing file.
+- `--append-system-prompt <text|path>`<br>
+  Appends text or an existing file to the system prompt and is repeatable.
+- `--tui-mode <mode>`<br>
+  Uses `regular` or `fullscreen` terminal mode.
+- `--verbose`<br>
+  Shows verbose interactive startup information, overriding `quietStartup`.
+- `-a`, `--approve`<br>
+  Trusts project-local configuration and resources for this process.
+- `-na`, `--no-approve`<br>
+  Ignores trust-gated project-local configuration and resources for this process.
+- `--offline`<br>
+  Disables automatic network activity, including model catalog refreshes. Equivalent to `KNIGHTCODE_OFFLINE=1`.
+- `-h`, `--help`<br>
+  Shows help, including flags registered by loaded extensions, then exits.
+- `-v`, `--version`<br>
+  Shows the KnightCode version, then exits.
+
+Extensions may register additional long-form options. Unknown short options are rejected.
+
+## Package commands
+
+```sh
+knightcode install npm:@scope/package
+```
+
+See [KnightCode Packages](packages.md) for source formats, filtering, installation, and project scope.
+
+### Common tasks
+
+| Task | Command |
+|---|---|
+| Install a package | `knightcode install <source>` |
+| List configured packages | `knightcode list` |
+| Remove a package and its settings entry | `knightcode remove <source>` |
+| Configure which package resources load | `knightcode config` |
+
+Add `--local` or `-l` to `install`, `remove`, `uninstall`, or `config` to use project settings instead of global settings.
+
+### Update KnightCode or packages
+
+Running `knightcode update` without a target updates KnightCode itself.
+
+| Task | Command |
+|---|---|
+| Update KnightCode | `knightcode update` |
+| Update all installed packages | `knightcode update --extensions` |
+| Update one installed package | `knightcode update <source>` |
+| Refresh model catalogs | `knightcode update --models` |
+| Update KnightCode and all installed packages | `knightcode update --all` |
+
+Add `--force` to reinstall KnightCode when the selected update includes KnightCode.
+
+### Aliases and command options
+
+- `knightcode uninstall <source>` is an alias for `knightcode remove <source>`.
+- `knightcode update --self`, `knightcode update self`, and `knightcode update knightcode` are aliases for `knightcode update`.
+- `knightcode update --extension <source>` is an alias for `knightcode update <source>`.
+- `-a`, `--approve` trusts project-local files for one command. `-na`, `--no-approve` ignores trust-gated project-local files.
+- Append `-h` or `--help` to a command for its exact usage and option constraints.
+
+## Credential commands
+
+```sh
+knightcode auth check --provider openai --json
+```
+
+Authentication commands require `--provider <provider>` or `--model <model>`. See [Provider Authentication](providers.md) for supported methods.
+
+| Command | Description |
+|---|---|
+| `knightcode auth check` | Print `ready`, `not_ready`, or `invalid`; exit with status `0`, `1`, or `2`, respectively |
+| `knightcode auth print-api-key` | Print the resolved API key |
+| `knightcode auth print-bearer-token` | Print a resolved OAuth bearer token |
+
+| Option | Applies to | Description |
+|---|---|---|
+| `--provider <provider>` | All | Resolve credentials for a provider |
+| `--model <model>` | All | Resolve credentials from a model; may be combined with `--provider` |
+| `--json` | `auth check` | Write the structured result as JSON |
+| `--credentials` | `auth check` | Emit the resolved credential when ready |
+| `--no-refresh` | `auth check` | Do not refresh expired OAuth credentials; refresh is the default |
+| `--min-expiry <duration>` | `print-bearer-token` | Require remaining token lifetime using `ms`, `s`, `m`, or `h`, such as `30m` |
+
+Credential-printing commands write secrets to stdout.