@knightcodeai/cli 0.18.4 → 0.20.0

package/docs/app-server.md

@@ -63,7 +63,8 @@ Start a thread with its project directory:
 ```
 
 Wait for each response. `thread/start` and `thread/fork` return
-`{thread, warnings}`. A fork is named after its source with ` (fork)` appended. `thread/resume` also returns warnings; render them from the
+`{thread, warnings, ui}` (`ui` is the thread's extension UI, see
+[Dialogs and extension UI](#dialogs-and-extension-ui)). A fork is named after its source with ` (fork)` appended. `thread/resume` also returns warnings; render them from the
 response, because they can occur before subscription. A warning has
 `{message, source, path?, line?, column?}`, where `source` is `settings`,
 `extension`, `trust`, or `server`. Malformed settings, refused extension loads,
@@ -72,9 +73,10 @@ send a subscriber-only `warning` with `threadId`.
 
 Threads and list summaries include `createdAt` (header creation time) and
 optional `forkedFromId` (the parent's header ID, not a UUID inferred from its
-filename). List summaries use file modification time for `updatedAt`; loaded
-threads use the latest entry time, falling back to the header. Their `status`
-is one of:
+filename). A loaded thread also carries `sessionFile`, the session file's path,
+once it has been saved. List summaries use file modification time for
+`updatedAt`; loaded threads use the latest entry time, falling back to the
+header. Their `status` is one of:
 
 - `{type: "notLoaded"}`
 - `{type: "idle"}`
@@ -159,9 +161,12 @@ lands in a later turn. A steer cannot be taken back once accepted.
 input starts a turn of its own once the thread is idle, oldest first; on an idle
 thread it starts at once. Until it starts it is removable with
 `turn/queue/remove`. A queued input that fails to start (no model, signed out) is
-dropped with an `error` notification. `turn/queue/updated` sends
-`{threadId, steering: [text], followUp: [{id, text}]}`: steers the agent has not
-delivered yet, and the queued inputs.
+dropped with an `error` notification carrying its `clientMessageId`, if it had
+one. `turn/queue/updated` sends
+`{threadId, steering: [text], followUp: [{id, text, attachments?}]}`: steers the
+agent has not delivered yet, and the queued inputs. `text` is the user's own (not
+a prompt composed with review comments); `attachments` counts the images and
+review comments an input carries that its text alone does not.
 
 `turn/interrupt` accepts optional `turnId`; a supplied stale ID returns
 `turnMismatch`, while omitting it retains interrupt-current behavior. It drops
@@ -201,9 +206,9 @@ Desktop OS notifications are for live outcomes, not initial history.
 `thread/resume` returns history and subscribes in the same synchronous send step.
 Its separate `runningTurn` is a current snapshot, even when an old history cursor
 is supplied. Its required `queue` and `usage` are also live send-time snapshots,
-not values from handler entry or the history cursor. Buffer queue/usage events
-while awaiting the response, install the snapshots (an empty queue clears stale
-state), then replay the buffered events. Invalid cursors subscribe nobody.
+not values from handler entry or the history cursor; so is `ui`. Buffer
+queue/usage/`ui/*` events while awaiting the response, install the snapshots (an
+empty queue clears stale state), then replay the buffered events. Invalid cursors subscribe nobody.
 Install `runningTurn` before applying buffered deltas. `thread/replaced` moves
 subscriptions to the new thread; captured old extension contexts become stale.
 `thread/unsubscribe` returns `{status: "unsubscribed" | "notSubscribed"}`.
@@ -281,6 +286,117 @@ The most recent initiating subscriber is asked first. Disconnect or unsubscribe
 cancels that attempt and migrates it to another subscriber; no subscribers means
 cancel. `serverRequest/cancelled` withdraws an outstanding request.
 
+## Dialogs and extension UI
+
+What KnightCode asks the user mid-turn reaches a desktop connection as a server
+request, asked the way approvals are; the thread reports `waitingOn: ["dialog"]`
+meanwhile.
+
+`item/toolCall/requestUserInput` carries `ask_user`'s questions, all at once,
+with the `itemId` of the call asking, so a client can move back and forth
+between them before answering. Each question has an `id`, its text and its
+options (`label`, `description`); a label ending in `(Recommended)` is the
+recommended one. Reply `{"answers": {"<id>": {"label": "..."}}}` with the
+chosen option's exact label and an optional `note`, or `{"other": "..."}` for
+the user's own answer; leave out a skipped question. `{}` dismisses the
+questions and stops the turn.
+
+`ui/dialog` carries the rest, such as the classifier gate's confirmation of a
+risky call and plan mode's review. `kind` says which: a select carries
+`options`, a confirm its `message`, an input its `placeholder`, an editor its
+`prefill`. Reply with `{"value": "..."}` for a select, input or editor,
+`{"confirmed": true}` for a confirm, or `{}` to cancel.
+
+Notices such as "Downloaded model" arrive as the notification `ui/notify` with
+a `level` of `info`, `warning` or `error`.
+
+What an extension shows beside the transcript is the thread's extension UI:
+
+- The `ui` of the `thread/start`, `thread/resume` and `thread/fork` results is
+  all of it as it stands when the response is written:
+  `{statuses: [{key, text}], title?, workingMessage?, workingVisible, widgets}`.
+  Statuses are sorted by key. Each widget is `{key, placement, lines}` or
+  `{key, placement, view}`, `placement` being `aboveEditor` or `belowEditor`;
+  those above come first, each group in the order they were last set.
+- `ui/state` carries every field but the widgets, whole, whenever one changes.
+  An absent `title` or `workingMessage` is a cleared one.
+  `workingVisible: false` asks the client to hide its waiting indicator, and
+  `workingMessage` replaces its text.
+- `ui/widget` carries one widget set or replaced (it moves to the end of its
+  placement), or `{threadId, key}` alone when it is removed.
+
+Install `ui` from the result, then apply the notifications, buffered across a
+resume as `queue` is. A `/reload` clears everything the old extensions showed,
+with one `ui/state` and a removal per widget, before the new ones start. The
+server strips ANSI escapes and keeps text on one line, at most 200 code points;
+widget lines keep their spacing. A [view](declarative-views.md) is data, never
+HTML; the server checked it before sending.
+
+A button or field in a widget's view answers with the request `ui/event`
+(below), which reaches every handler the thread's extensions registered with
+`ctx.ui.onViewEvent`. Views on `toolCall` and `extensionMessage` items (their
+optional `view`) are for display only.
+
+Widget factories, `custom()` components, header and footer components, raw
+terminal input and the working indicator draw only in the terminal: the server
+writes one line to its log per method per thread load and draws nothing. Editor
+access (`setEditorText`, `getEditorText`, `pasteToEditor`) does nothing.
+Threads a terminal-mode connection loads have no dialogs or extension UI yet.
+
+## Workspaces, diffs and git
+
+A thread runs in a workspace: the user's checkout (`{mode: "local"}`), or a git
+worktree of its own (`{mode: "worktree"}`), as in the Codex desktop app.
+
+`thread/start {cwd, workspace: {mode: "worktree", baseRef?, carryLocalChanges?, environment?}}`
+creates a worktree on a **detached `HEAD`** at `baseRef` (default:
+the checkout's `HEAD`) under `<worktrees.root>/<4 hex digits>/<repository name>`
+and runs the thread there, in the same subdirectory the `cwd` had. No branch is
+created until `git/branch/create` or a handoff makes one. `carryLocalChanges`
+brings the checkout's uncommitted changes (untracked files included, ignored
+files not) along as uncommitted edits. Creation runs no hook, filter or user
+code, so a failed creation leaves nothing behind. A start whose `cwd` is inside
+a managed worktree is a new thread in that worktree.
+
+`thread/workspace/progress {threadId, phase, output}` streams the output of an
+environment's setup or cleanup script to the connection that asked. Every
+`Thread` carries `workspace`; `ThreadSummary.workspaceMode` marks worktree
+threads in listings.
+
+Diffs come in Codex's Changes scopes: `lastTurn`, `uncommitted` (the default),
+`unstaged`, `staged`, `committed` and `branch`. Each hunk has a content-hash id;
+an action naming a hunk that changed since it was read answers `gitConflict`
+with `data.reason: "diffChanged"`. Files changed while a turn ran are reported
+by `turn/diff/updated {threadId, turnId, files}` after `turn/completed`, each
+file as `{path, additions, deletions}`: the net line totals between the working
+tree before and after the turn. A read-back turn carries the same list as
+`Turn.files`. This
+means "changed while the turn ran", not "changed by the turn": an edit another
+local thread or an editor made meanwhile is in the list too. A worktree thread
+is the only writer in its worktree, so its list is its own.
+
+Review comments are drafts the client keeps. They travel with the next
+`turn/start` or `turn/queue/add` as `comments`; the server quotes the commented
+lines from the diff the user reviewed, and the user item shows the comments
+next to the typed text.
+
+**Reverting an added file deletes it**, an untracked one included. Clients
+confirm with the user before a revert that removes files.
+
+`thread/handoff` moves a chat and its uncommitted changes between its worktree
+and the main checkout. The destination must be clean: "Stash or commit your
+local changes to hand off." Archiving a thread deletes its worktree after a
+snapshot, kept as `refs/knightcode/snapshots/<bucket>/<time>`, and
+`thread/worktree/restore` rebuilds it. Past `worktrees.keep` worktrees, the
+least recently used are pruned the same way. Outside a git repository, diff and
+git methods answer `notGitRepo`.
+
+`gitConflict` errors carry `data.reason`: `diffChanged`, `patchFailed`,
+`concurrentChange`, `pushRejected`, `localChanges`, `operationInProgress`,
+`branchExists`, `recoveryRequired`, `worktreeDeleted`, `worktreeMissing`,
+`worktreeInUse` or `submodules`, with `paths`, `output` or
+`recoveryInstructions` where they apply.
+
 ## Method reference
 
 All methods require the handshake. Common errors are `notInitialized`,
@@ -300,12 +416,13 @@ Errors: `threadNotFound`.
 
 ### `config/read`
 
-Params: optional `{cwd}`. Result: `{settings, origins, versions, errors}`.
+Params: optional `{cwd}`. Result: `{settings, defaults, origins, versions, paths, errors}`.
 Without cwd, only global settings are read. With cwd, trusted project settings
 merge over global settings; untrusted project files are not read. `origins`
 maps dotted leaf keys to `global` or `project`. `versions.global` and optional
 `versions.project` are SHA-256 hashes of raw file contents, or `"none"` for an
-absent or unread untrusted scope. Settings, origins, versions, and parse errors
+absent or unread untrusted scope. `defaults` is what an unset key means, in the
+shape of `settings`; `paths` names the global and, with cwd, the project file. Settings, origins, versions, and parse errors
 come from the same scope reads, not cached settings paired with fresh versions.
 Parse errors appear as structured `source: "settings"` warnings with an
 optional path and available one-based line/column; unaffected scopes still read.
@@ -336,6 +453,71 @@ malformed keys, and prototype-pollution segments (`__proto__`, `constructor`,
 {"id":12,"method":"config/write","params":{"scope":"global","key":"theme","value":"dark","expectedVersion":"none"}}
 ```
 
+### `tool/list`
+
+Params: optional `{cwd}`. Result: `{tools: [{name, description, source}], defaultTools}`.
+The tools a new thread in `cwd` would register (without cwd, a
+project-less one), from an in-memory session like `command/list`'s; hidden tools
+are left out, and MCP tools appear only once a thread connects. `defaultTools` is
+the global `defaultTools` setting resolved (`+name` and `-name` applied), or the
+built-in default `read`, `bash`, `edit`, `write`. Change it with `config/write`.
+
+```json
+{"id":26,"method":"tool/list","params":{}}
+```
+
+### `tool/settings/read` and `tool/settings/write`
+
+The KnightCode tools `/tools` manages, stored in `tools.json` in the agent
+directory. `tool/settings/read {}` returns
+`{tools: [{name, enabled, settings}], classifiers: [{provider, id, name}]}`: each tool's state (its default when the
+file does not set it) and its own settings, with values of keys ending in `Key`
+masked to their last four characters; `classifiers` are the classifier models
+with credentials, for the classifier gate's `model`.
+`tool/settings/write {name, key, value}` sets one setting; `enabled` takes a boolean, other keys a string,
+and `null` deletes the key. An unknown tool or a malformed key is
+`invalidParams`.
+
+```json
+{"id":27,"method":"tool/settings/write","params":{"name":"websearch","key":"provider","value":"brave"}}
+```
+
+### `mcp/list`, `mcp/update`, `mcp/add` and `mcp/remove`
+
+The servers of the global `mcp.json` and, for an explicitly trusted project, its
+`.knightcode/mcp.json` ([MCP](mcp.md)). `mcp/list {cwd?}` returns
+`{servers, errors, paths}`: each server's `name`, `scope`, defining file (`source`), the
+project file that overrides it (`override`), `transport` (`stdio` or `http`),
+`target` (command line or URL), `description`, `enabled` and `exposure`.
+`mcp/update {cwd?, name, enabled?, exposure?}` saves the change where `/mcp`
+would: in the project override when there is one, else in the defining file.
+`mcp/add {scope, cwd?, name, config}` validates `config` as an `mcpServers` entry
+and adds or replaces it (result `{replaced}`); `auth` is refused in a project
+file. `mcp/remove {scope, cwd?, name}` returns `{removed}`. Project writes need
+cwd and a trusted project (`invalidParams`, `data.reason: "untrusted"`).
+Connections, sign-in and status belong to the MCP extension in each thread
+(`/mcp`); loaded threads pick up file changes when they next load.
+
+```json
+{"id":28,"method":"mcp/add","params":{"scope":"global","name":"docs","config":{"url":"https://example.com/mcp"}}}
+```
+
+### `resource/list` and `resource/set`
+
+Extensions, skills, prompt templates and themes as `knightcode config` lists them.
+`resource/list {cwd?}` returns
+`{resources: [{type, path, name, enabled, scope, origin, source}]}` for what a thread in `cwd` (or with no project) would find,
+installing nothing. Built-in extensions are left out: they are always on, so
+`resource/set` refuses them like any unknown path. `resource/set {cwd?, type, path, enabled}` loads or
+skips one resource with a `+` or `-` pattern in the settings of the scope that
+defines it: a top-level resource in that scope's `extensions`, `skills`,
+`prompts` or `themes`, a package's in that package's filter. Project resources
+need a trusted project; an unknown path is `invalidParams`.
+
+```json
+{"id":29,"method":"resource/set","params":{"type":"skills","path":"/home/u/.knightcode/agent/skills/review/SKILL.md","enabled":false}}
+```
+
 ### `project/trust/read`
 
 Params: `{cwd}`. Result: `{trusted, needsTrust}`. `trusted` is true, false, or
@@ -394,6 +576,24 @@ and nothing is written. Built-in commands that only work in the terminal
 {"id":17,"method":"command/list","params":{"cwd":"/path/to/project"}}
 ```
 
+### `ui/event`
+
+Params: `{threadId, widgetKey, id, value?}`. Result: `{}`. A press of the button
+`id`, or a change of the field `id`, in the widget `widgetKey`'s view: `value` is
+a string for a text or select field, a boolean for a toggle, and absent for a
+button. Every handler of the thread gets `{widgetKey, id, value?}`; a handler
+that fails becomes a `warning`. The extension answers by setting the widget
+again: a field shows the view's value, not what was typed. A press of a widget or
+control that is gone answers `{}` and reaches nobody.
+
+Errors: `threadNotFound` when the thread is not loaded, and `invalidParams` when
+the value does not fit the control (a toggle's string, a select value outside its
+options, a button with a value).
+
+```json
+{"id":18,"method":"ui/event","params":{"threadId":"THREAD_ID","widgetKey":"checks","id":"verbose","value":true}}
+```
+
 ### `thread/delete`
 
 Params: `{threadId}`. Result: `{}`. Permanently removes an archived transcript;
@@ -425,6 +625,136 @@ Diagnostics observe the shared server, not only this connection.
 {"id":18,"method":"server/diagnostics","params":{}}
 ```
 
+### `thread/diff/read`
+
+Params: `{threadId, scope?, against?, commit?, context?, ignoreWhitespace?}`.
+Result: `{scope, root, files, filesOmitted?, untrackedSkipped?, turnId?, stale?, against?}`.
+`files` are `{path, oldPath?, status, binary, additions, deletions, tooLarge?, hunks}`,
+their paths relative to the repository's `root` (not the thread's cwd, which can
+be a subdirectory of it); each hunk keeps its lines with their `" "`, `"+"`, `"-"` or
+`"\"` prefix. `committed` needs `commit`; `branch` compares with `against`,
+else the worktree's base, the upstream or the default branch, and echoes it.
+More than 500 untracked files are counted in `untrackedSkipped` and left out.
+Files past the response budget come without hunks (`tooLarge`) or are only
+counted (`filesOmitted`). A hunk id hashes the file's header (its blob ids) and
+the hunk at the read's `context`: an action must pass the same `context` (a
+`context: 0` id matches no action), and after an action changes a file, read it
+again, as its other hunks' ids change too. A hunk id from an `ignoreWhitespace` read matches no
+action. Reads take no lock and never write the user's index.
+Errors: `threadNotFound`, `notGitRepo`; `invalidParams` for a missing `commit`
+or no branch to compare with.
+
+```json
+{"id":20,"method":"thread/diff/read","params":{"threadId":"THREAD_ID","scope":"uncommitted","context":3}}
+```
+
+### `thread/diff/revert`
+
+Params: `{threadId, scope?, against?, commit?, path?, hunkId?, context?, reapply?, turnId?}`.
+With `turnId` (`lastTurn` only), a last turn other than that one answers
+`gitConflict` `diffChanged`, so an Undo shown on one turn never reverts a newer one.
+Result: `{paths}`. Reverse-applies one hunk, one file, or the whole scope to the
+working tree; `lastTurn` without a path undoes the turn, and only while every
+affected file is exactly as the turn left it. With `reapply` (`lastTurn` only,
+no hunk), the turn's changes apply again instead, and only while every affected
+file is exactly as the turn found it. Hunks of renamed, added, deleted,
+binary or mode-changed files revert as whole files only. Refused while a turn
+runs in the checkout; no turn starts and no tool runs there until it ends.
+Errors: `turnInProgress`; `invalidParams` for `staged` and `committed` or a
+path outside the diff; `gitConflict` with `diffChanged` or `patchFailed`.
+
+```json
+{"id":21,"method":"thread/diff/revert","params":{"threadId":"THREAD_ID","path":"src/a.ts","hunkId":"HUNK_ID"}}
+```
+
+### `thread/handoff`
+
+Params: `{threadId, to: "local" | "worktree", branch?, environment?}`. Result:
+`{thread, branch?, warnings}`. To the main checkout: the worktree's `HEAD`
+becomes a branch checked out there (the worktree's own branch, else `branch`,
+else the previous handoff's branch fast-forwarded, else
+`<worktrees.branchPrefix><title>`), the uncommitted changes move, and the
+worktree stays, detached and clean. Back: the worktree is detached at the main
+checkout's `HEAD` and the changes move into it; a thread born in the main
+checkout gets a worktree. The changes are saved under `<agentDir>/handoff/`
+before anything moves and leave the source only after they landed. The thread
+is reloaded where it now runs: subscribers receive `thread/replaced` with the
+same id, and queued inputs follow it.
+Errors: `turnInProgress`; `invalidParams` for a thread with no message yet or
+already on that side; `gitConflict` with `localChanges`,
+`operationInProgress`, `branchExists`, `recoveryRequired` (with `data.patch`)
+or `worktreeDeleted`.
+
+```json
+{"id":22,"method":"thread/handoff","params":{"threadId":"THREAD_ID","to":"local"}}
+```
+
+### `thread/worktree/restore`
+
+Params: `{threadId}`. Result: `{thread}`. Rebuilds a deleted worktree at its
+old path from its snapshot: detached at the old `HEAD`, with the working files
+and the staged state as they were (ignored files were not kept). Then the
+thread loads there.
+Errors: `threadNotFound`; `invalidParams` when the worktree is not deleted;
+`gitConflict` with `worktreeMissing` (deleted without a snapshot: fork the chat
+into a new worktree instead) or `submodules`.
+
+```json
+{"id":23,"method":"thread/worktree/restore","params":{"threadId":"THREAD_ID"}}
+```
+
+### `worktree/list` and `worktree/delete`
+
+`worktree/list {cwd?}` →
+`{worktrees: [{path, projectCwd, head?, branch?, threadIds, lastUsedAt, deleted}]}`,
+the managed worktrees (of `cwd`'s project
+when given). `worktree/delete {path}` → `{snapshot?}` deletes one after its
+snapshot. A worktree a thread is loaded in, or one holding a nested repository
+(an initialized submodule or a repository inside it), is never deleted: archive
+and pruning skip it, and `worktree/delete` answers `gitConflict` with
+`worktreeInUse` or `submodules`. Only registrations in the managed layout are
+removed; the user's own worktrees are never touched.
+
+```json
+{"id":24,"method":"worktree/delete","params":{"path":"/home/u/.knightcode/agent/worktrees/ab12/project"}}
+```
+
+### `environment/list` and `environment/save`
+
+`environment/list {cwd}` → `{environments, trusted}` reads the project's
+`.knightcode/environments.json`; `environment/save {cwd, environments}` writes
+it (names unique, at most 50). An untrusted project's scripts never run. See
+[Settings](settings.md#worktrees).
+
+```json
+{"id":25,"method":"environment/save","params":{"cwd":"/p","environments":[{"name":"node","setup":{"default":"cd \"$KNIGHTCODE_WORKTREE_PATH\" && npm ci"}}]}}
+```
+
+### `git/*`
+
+Each acts on the thread's own checkout: its worktree, or the user's checkout.
+`git/status` → branch, upstream, ahead/behind, staged/unstaged/untracked/
+conflicted counts and an operation in progress. `git/stage` and `git/unstage`
+take `{threadId, path?, hunkId?, context?}`: no path is everything; paths are
+literal. `git/commit {threadId, message?, includeUnstaged?}` stages everything
+first unless `includeUnstaged: false`; an empty message is written by the
+thread's model from the staged diff, outside the conversation, and the commit
+answers `concurrentChange` when the checkout changed meanwhile. The user's
+hooks run. `git/push` pushes the current branch with one explicit,
+non-forcing refspec and sets the upstream the first time.
+`git/pr/create {threadId, title?, body?, draft?}` runs `gh pr create` (`toolMissing` without
+`gh`). `git/branches`, `git/branch/create {name}` ("Create branch here"),
+`git/branch/switch {name}` (refused when it would overwrite local changes or an
+ignored file the branch tracks) and `git/log {limit?}` (the commits since the
+base, for the `committed` scope) complete the set.
+Errors: `notGitRepo`, `invalidParams`, `authRequired`, `toolMissing`;
+`gitConflict` with `diffChanged`, `patchFailed`, `concurrentChange`,
+`pushRejected`, `branchExists` or `localChanges`.
+
+```json
+{"id":26,"method":"git/commit","params":{"threadId":"THREAD_ID","includeUnstaged":true}}
+```
+
 ## Ownership, unloading, and shutdown
 
 Only one process may own a persisted session file. Symlink/junction aliases share
@@ -461,6 +791,14 @@ Limits count UTF-8 bytes:
 - 1 MiB per history/list response, including envelope reserve.
 - 64 KiB per inline turn/item; larger values use references.
 - 48 KiB per payload chunk before base64 encoding.
+- 64 KiB per view in a tool result or an extension message, as serialized JSON;
+  a larger or invalid view is dropped and the raw output or text shows.
+- 16 KiB per widget (its lines or view), 16 widgets and 50 statuses per thread;
+  status and widget keys of 1 to 128 characters; status text, title and working
+  message cut to 200 code points. A refused widget or status gives one
+  `warning` per key per load (a load warning when it happened while the thread
+  loaded).
+- Views nest stacks and lists at most 8 levels deep.
 
 The in-repository `AppServerClient` supports typed `request`, `onNotification`,
 `onRequest`, `readPayload`, `resolveTurn`, and `resolveItem` calls. Its