@knightcodeai/cli 0.20.0 → 0.21.1

package/docs/app-server.md

@@ -372,8 +372,12 @@ 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.
+local thread or an editor made meanwhile is in the list too. A worktree
+thread's list is its own unless another thread runs in the same worktree (a
+start whose `cwd` is inside it), whose edits it can include. Untracked files
+count up to 500; past that, those under a folder holding 200 or more untracked
+files are left out, and if more than 500 still remain before or after the
+turn, only tracked files count.
 
 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
@@ -502,6 +506,36 @@ Connections, sign-in and status belong to the MCP extension in each thread
 {"id":28,"method":"mcp/add","params":{"scope":"global","name":"docs","config":{"url":"https://example.com/mcp"}}}
 ```
 
+### `mcp/app/readResource` and `mcp/app/callTool`
+
+MCP Apps ([MCP](mcp.md#mcp-apps)): a client that draws apps sends `desktop` as
+its mode; the thread's MCP servers then hear the client supports
+`io.modelcontextprotocol/ui`. A call to a tool with an app carries
+`mcpApp: {server, resourceUri, result?, resultOmitted?}` on its `toolCall`
+item, live and read back: `result` is the server's whole `CallToolResult`
+(with `_meta` and `structuredContent`), or `resultOmitted: true` past 256 KiB
+serialized, when the app gets the item's text output instead.
+
+`mcp/app/readResource {threadId, server, uri}` returns the server's
+`ReadResourceResult` `{contents, _meta?}`, the app's HTML first.
+`mcp/app/callTool {threadId, server, name, arguments?, confirmed?}` returns its
+`CallToolResult` `{content, structuredContent?, isError?, _meta?}`. Both reach
+only the named server, through the thread's MCP extension, and only while it is
+connected (`mcpUnavailable` otherwise); a call reaches only a tool whose
+`_meta.ui.visibility` includes `"app"` and that the configuration does not hide
+(`invalidParams` otherwise). Outside `fullAccess`, a tool not annotated
+`readOnlyHint` answers `approvalRequired` (`data: {server, tool}`) until sent
+again with `confirmed: true` after the user agreed. Arguments over 1 MiB and a
+resource over 4 MiB, serialized, answer `invalidParams`; a tool's result over
+4 MiB is left out of an answer whose text says the tool ran, since it did. A call
+during a turn runs
+at once; the server gives the MCP extension 60 seconds to answer a resource read
+(`internal` after that), and a tool call as long as the server's own `timeout`.
+
+```json
+{"id":29,"method":"mcp/app/callTool","params":{"threadId":"THREAD_ID","server":"counter","name":"increment","arguments":{"by":1},"confirmed":true}}
+```
+
 ### `resource/list` and `resource/set`
 
 Extensions, skills, prompt templates and themes as `knightcode config` lists them.
@@ -628,7 +662,7 @@ Diagnostics observe the shared server, not only this connection.
 ### `thread/diff/read`
 
 Params: `{threadId, scope?, against?, commit?, context?, ignoreWhitespace?}`.
-Result: `{scope, root, files, filesOmitted?, untrackedSkipped?, turnId?, stale?, against?}`.
+Result: `{scope, root, files, filesOmitted?, untrackedSkipped?, turnId?, stale?, against?, fromTree?, toTree?}`.
 `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
@@ -640,7 +674,9 @@ 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.
+action. Reads take no lock and never write the user's index. Unless
+`ignoreWhitespace` is set, the result also names the two trees it compared,
+`fromTree` and `toTree`, for `thread/diff/file`.
 Errors: `threadNotFound`, `notGitRepo`; `invalidParams` for a missing `commit`
 or no branch to compare with.
 
@@ -648,6 +684,60 @@ or no branch to compare with.
 {"id":20,"method":"thread/diff/read","params":{"threadId":"THREAD_ID","scope":"uncommitted","context":3}}
 ```
 
+### `thread/diff/file`
+
+Params: `{threadId, fromTree, toTree, path, oldPath?}`. Result:
+`{old?, new?, binary, tooLarge}`. Both sides of one file from a
+`thread/diff/read` result, by the trees it named, so a client can show the
+unchanged lines between its hunks. `old` is the file in `fromTree` at `oldPath`
+(else `path`), `new` the file in `toTree` at `path`; a side the file is absent
+from is left out. Neither side comes when the file is binary (a NUL in its first
+8 KiB) or either side is larger than 2 MiB. The trees stay readable after the
+working tree moves on, so the sides always match the read's hunks.
+Errors: `threadNotFound`, `notGitRepo`; `invalidParams` when a tree is not a
+full object id of a tree in the repository, or the file is in neither tree.
+
+```json
+{"id":24,"method":"thread/diff/file","params":{"threadId":"THREAD_ID","fromTree":"FROM_TREE","toTree":"TO_TREE","path":"src/a.ts"}}
+```
+
+### `file/read`
+
+Params: `{threadId, path, maxBytes?}`. Result: `{path, size, binary, tooLarge,
+text?, mtimeMs}`. A file's text, `path` resolved against the thread's cwd like a
+tool's path. `maxBytes` is 1 byte to 8 MiB (default 2 MiB). `text` comes only
+when the file is neither binary (a NUL in its first 8 KiB, or bytes that are not
+UTF-8, which decoded and saved would be replaced) nor larger than
+`maxBytes`; `size` is its length in bytes; `mtimeMs` its modification time when
+read, for `file/write`.
+Errors: `threadNotFound`; `invalidParams` when there is no such file or the path
+is not a file.
+
+```json
+{"id":25,"method":"file/read","params":{"threadId":"THREAD_ID","path":"src/a.ts"}}
+```
+
+### `file/list`
+
+Params: `{threadId, path?}`. Result: `{root, entries, truncated}`. One folder's
+entries for a file tree: `path` resolved like `file/read`'s, the thread's cwd
+when absent; `root` is the cwd and each entry `{path, type}` is relative to it,
+`/`-separated, `type` `file` or `directory` (a link to a folder is a folder).
+Hidden entries are included. Past 5,000 entries the rest are left out and
+`truncated` is true.
+Errors: `threadNotFound`; `invalidParams` when the path is not a folder or
+cannot be read.
+
+### `file/write`
+
+Params: `{threadId, path, text, expectedMtimeMs?}`. Result: `{mtimeMs}`. Writes
+`text` (UTF-8, at most 8 MiB) to the file in place, so it keeps its mode and
+links; a missing file is created. With `expectedMtimeMs` (the `mtimeMs` of the
+read the text came from), a file modified since is refused with `fileChanged`
+and left as it is.
+Errors: `threadNotFound`; `fileChanged`; `invalidParams` when the path is a
+folder or cannot be written.
+
 ### `thread/diff/revert`
 
 Params: `{threadId, scope?, against?, commit?, path?, hunkId?, context?, reapply?, turnId?}`.
@@ -669,7 +759,7 @@ path outside the diff; `gitConflict` with `diffChanged` or `patchFailed`.
 
 ### `thread/handoff`
 
-Params: `{threadId, to: "local" | "worktree", branch?, environment?}`. Result:
+Params: `{threadId, to: "local" | "worktree", branch?, environment?, dryRun?}`. 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
@@ -680,6 +770,10 @@ 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.
+With `dryRun`, the server runs every check the handoff would and answers with
+the same refusal, or with the unchanged thread and the branch the main checkout
+would get; it writes nothing, creates no worktree, and never holds up a real
+handoff.
 Errors: `turnInProgress`; `invalidParams` for a thread with no message yet or
 already on that side; `gitConflict` with `localChanges`,
 `operationInProgress`, `branchExists`, `recoveryRequired` (with `data.patch`)
@@ -734,7 +828,9 @@ it (names unique, at most 50). An untrusted project's scripts never run. See
 
 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`
+conflicted counts and an operation in progress. `git/origin` → the checkout's
+`root`, the `url` of its origin remote (else its first remote) and the `branch`
+checked out, each absent when there is none. `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