@knightcodeai/cli 0.19.0 → 0.21.1

package/dist/core/export-html/template.js

@@ -98,14 +98,12 @@
           }
         }
 
-        // Sort children by timestamp
-        function sortChildren(node) {
+        // Sort children by timestamp. Iterative: long sessions form chains deeper than the JS call stack.
+        for (const node of nodeMap.values()) {
           node.children.sort((a, b) =>
             new Date(a.entry.timestamp).getTime() - new Date(b.entry.timestamp).getTime()
           );
-          node.children.forEach(sortChildren);
         }
-        roots.forEach(sortChildren);
 
         return roots;
       }
@@ -134,14 +132,14 @@
         const path = [];
         let current = byId.get(targetId);
         while (current) {
-          path.unshift(current);
+          path.push(current);
           // Stop if no parent or self-referencing (root)
           if (!current.parentId || current.parentId === current.id) {
             break;
           }
           current = byId.get(current.parentId);
         }
-        return path;
+        return path.reverse();
       }
 
       // Tree node lookup for finding leaves
@@ -156,12 +154,12 @@
         // Build tree node map lazily
         if (!treeNodeMap) {
           treeNodeMap = new Map();
-          const tree = buildTree();
-          function mapNodes(node) {
+          const stack = [...buildTree()];
+          while (stack.length > 0) {
+            const node = stack.pop();
             treeNodeMap.set(node.entry.id, node);
-            node.children.forEach(mapNodes);
+            for (const child of node.children) stack.push(child);
           }
-          tree.forEach(mapNodes);
         }
 
         const node = treeNodeMap.get(nodeId);
@@ -185,16 +183,22 @@
         const multipleRoots = roots.length > 1;
 
         // Mark which subtrees contain the active leaf
+        // Iterative post-order: long sessions form chains deeper than the JS call stack.
         const containsActive = new Map();
-        function markActive(node) {
-          let has = activePathIds.has(node.entry.id);
-          for (const child of node.children) {
-            if (markActive(child)) has = true;
-          }
-          containsActive.set(node, has);
-          return has;
+        const postOrder = [];
+        const pending = [...roots];
+        while (pending.length > 0) {
+          const node = pending.pop();
+          postOrder.push(node);
+          for (const child of node.children) pending.push(child);
+        }
+        for (let i = postOrder.length - 1; i >= 0; i--) {
+          const node = postOrder[i];
+          containsActive.set(
+            node,
+            activePathIds.has(node.entry.id) || node.children.some(child => containsActive.get(child))
+          );
         }
-        roots.forEach(markActive);
 
         // Stack: [node, indent, justBranched, showConnector, isLast, gutters, isVirtualRootChild]
         const stack = [];
@@ -313,6 +317,76 @@
         return '';
       }
 
+      // ============================================================
+      // SYSTEM MESSAGES (pure data)
+      // ============================================================
+
+      function systemContentText(content) {
+        if (typeof content === 'string') return content;
+        if (Array.isArray(content)) {
+          return content.filter(c => c.type === 'text' && c.text).map(c => c.text).join('\n');
+        }
+        return '';
+      }
+
+      /** Full prompt text of a system message, mirroring getSystemMessageText() in @knightcode/ai. */
+      function getSystemMessageText(msg) {
+        const parts = [systemContentText(msg.content)];
+        for (const value of Object.values(msg.sections || {})) {
+          if (value !== null) parts.push(value);
+        }
+        return parts.filter(part => part.length > 0).join('\n\n');
+      }
+
+      /** Text of a later system message, mirroring renderSystemMessageUpdate() in @knightcode/ai. */
+      function renderSystemMessageUpdate(msg) {
+        const parts = [];
+        const text = systemContentText(msg.content);
+        if (text.length > 0) parts.push(text);
+        for (const [name, value] of Object.entries(msg.sections || {})) {
+          parts.push(value === null
+            ? `Removed system prompt section "${name}".`
+            : `Updated system prompt section "${name}":\n\n${value}`);
+        }
+        return parts.join('\n\n');
+      }
+
+      function carriesSystemState(entry) {
+        return (entry.type === 'message' && entry.message.role === 'system') ||
+          (entry.type === 'compaction' && entry.systemMessage);
+      }
+
+      /**
+       * Whether a system entry starts the prompt on its branch. Later system entries
+       * patch the prompt, so they render as updates instead of a full prompt.
+       */
+      function isLeadingSystemEntry(entry) {
+        let current = entry.parentId && entry.parentId !== entry.id ? byId.get(entry.parentId) : undefined;
+        while (current) {
+          if (carriesSystemState(current)) return false;
+          if (!current.parentId || current.parentId === current.id) break;
+          current = byId.get(current.parentId);
+        }
+        return true;
+      }
+
+      /** Short description of what a later system message changes, e.g. "project_context, -rules, tools +bash". */
+      function describeSystemUpdate(msg) {
+        const parts = [];
+        if (systemContentText(msg.content).length > 0) parts.push('instructions');
+        for (const [name, value] of Object.entries(msg.sections || {})) {
+          parts.push(value === null ? `-${name}` : name);
+        }
+        const toolChanges = [
+          ...(msg.toolsAdded || []).map(t => `+${t.name}`),
+          ...(msg.toolsRemoved || []).map(t => `-${t.name}`),
+        ];
+        if (toolChanges.length > 0) parts.push(`tools ${toolChanges.join(' ')}`);
+        return parts.join(', ');
+      }
+
+      const hasSystemEntries = entries.some(entry => entry.type === 'message' && entry.message.role === 'system');
+
       /**
        * Parse a skill block from message text.
        * Returns null if the text doesn't contain a skill block.
@@ -337,6 +411,13 @@
           case 'message': {
             const msg = entry.message;
             parts.push(msg.role);
+            if (msg.role === 'system') {
+              parts.push(isLeadingSystemEntry(entry) ? 'system prompt' : 'system update');
+              parts.push(getSystemMessageText(msg));
+              for (const name of Object.keys(msg.sections || {})) parts.push(name);
+              for (const tool of [...(msg.toolsAdded || []), ...(msg.toolsRemoved || [])]) parts.push(tool.name);
+              break;
+            }
             if (msg.content) parts.push(extractContent(msg.content));
             if (msg.role === 'bashExecution' && msg.command) parts.push(msg.command);
             break;
@@ -675,6 +756,13 @@
               const cmd = truncate(normalize(msg.command || ''));
               return labelHtml + `<span class="tree-role-tool">[bash]:</span> ${escapeHtml(cmd)}`;
             }
+            if (msg.role === 'system') {
+              if (isLeadingSystemEntry(entry)) {
+                return labelHtml + `<span class="tree-muted">[system prompt]</span>`;
+              }
+              const changes = describeSystemUpdate(msg);
+              return labelHtml + `<span class="tree-muted">[system update${changes ? ': ' + escapeHtml(truncate(changes)) : ''}]</span>`;
+            }
             return labelHtml + `<span class="tree-muted">[${escapeHtml(msg.role)}]</span>`;
           }
           case 'compaction':
@@ -1327,6 +1415,24 @@
           }
 
           if (msg.role === 'toolResult') return '';
+
+          if (msg.role === 'system') {
+            let html = '';
+            if (isLeadingSystemEntry(entry)) {
+              const text = getSystemMessageText(msg);
+              if (text) html += renderSystemPromptBlock('System Prompt', text);
+              html += renderToolsList('Available Tools', msg.toolsAdded);
+            } else {
+              const text = renderSystemMessageUpdate(msg);
+              const changes = describeSystemUpdate(msg);
+              if (text) html += renderSystemPromptBlock(`System Prompt Update${changes ? ': ' + changes : ''}`, text);
+              html += renderToolsList('Tools Added', msg.toolsAdded);
+              if (msg.toolsRemoved && msg.toolsRemoved.length > 0) {
+                html += `<div class="tools-list"><div class="tools-header">Tools Removed</div><div class="tools-content">${msg.toolsRemoved.map(t => `<div class="tool-item"><span class="tool-item-name">${escapeHtml(t.name)}</span></div>`).join('')}</div></div>`;
+              }
+            }
+            return html ? `<div class="system-entry" id="${entryDomId}">${tsHtml}${html}</div>` : '';
+          }
         }
 
         if (entry.type === 'model_change') {
@@ -1360,7 +1466,7 @@
         let userMessages = 0, assistantMessages = 0, toolResults = 0;
         let customMessages = 0, compactions = 0, branchSummaries = 0, toolCalls = 0;
         const tokens = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
-        const cost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+        const cost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
         const models = new Set();
 
         for (const entry of entryList) {
@@ -1376,10 +1482,18 @@
                 tokens.cacheRead += msg.usage.cacheRead || 0;
                 tokens.cacheWrite += msg.usage.cacheWrite || 0;
                 if (msg.usage.cost) {
+                  const componentTotal =
+                    (msg.usage.cost.input || 0) +
+                    (msg.usage.cost.output || 0) +
+                    (msg.usage.cost.cacheRead || 0) +
+                    (msg.usage.cost.cacheWrite || 0);
                   cost.input += msg.usage.cost.input || 0;
                   cost.output += msg.usage.cost.output || 0;
                   cost.cacheRead += msg.usage.cost.cacheRead || 0;
                   cost.cacheWrite += msg.usage.cost.cacheWrite || 0;
+                  // Provider-reported totals can intentionally differ from catalog-estimated components.
+                  // Fall back to the component sum for sessions written before cost.total was recorded.
+                  cost.total += typeof msg.usage.cost.total === 'number' ? msg.usage.cost.total : componentTotal;
                 }
               }
               toolCalls += msg.content.filter(c => c.type === 'toolCall').length;
@@ -1400,7 +1514,7 @@
       const globalStats = computeStats(entries);
 
       function renderHeader() {
-        const totalCost = globalStats.cost.input + globalStats.cost.output + globalStats.cost.cacheRead + globalStats.cost.cacheWrite;
+        const totalCost = globalStats.cost.total;
 
         const tokenParts = [];
         if (globalStats.tokens.input) tokenParts.push(`↑${formatTokens(globalStats.tokens.input)}`);
@@ -1438,30 +1552,39 @@
             </div>
           </div>`;
 
-        // Render system prompt (user's base prompt, applies to all providers)
-        if (systemPrompt) {
-          const lines = systemPrompt.split('\n');
-          const previewLines = 10;
-          if (lines.length > previewLines) {
-            const preview = lines.slice(0, previewLines).join('\n');
-            const remaining = lines.length - previewLines;
-            html += `<div class="system-prompt expandable" onclick="if(window.getSelection().toString())return;this.classList.toggle('expanded')">
-              <div class="system-prompt-header">System Prompt</div>
-              <div class="system-prompt-preview">${escapeHtml(preview)}</div>
-              <div class="system-prompt-expand-hint">... (${remaining} more lines, click to expand)</div>
-              <div class="system-prompt-full">${escapeHtml(systemPrompt)}</div>
-            </div>`;
-          } else {
-            html += `<div class="system-prompt">
-              <div class="system-prompt-header">System Prompt</div>
-              <div class="system-prompt-full" style="display: block">${escapeHtml(systemPrompt)}</div>
-            </div>`;
-          }
+        // Sessions with system entries render the prompt and tools in the transcript, where they
+        // occur. Older sessions have none, so fall back to the exporting agent's current state.
+        if (!hasSystemEntries) {
+          if (systemPrompt) html += renderSystemPromptBlock('System Prompt', systemPrompt);
+          html += renderToolsList('Available Tools', tools);
+        }
+
+        return html;
+      }
+
+      function renderSystemPromptBlock(title, text) {
+        const lines = text.split('\n');
+        const previewLines = 10;
+        if (lines.length > previewLines) {
+          const preview = lines.slice(0, previewLines).join('\n');
+          const remaining = lines.length - previewLines;
+          return `<div class="system-prompt expandable" onclick="if(window.getSelection().toString())return;this.classList.toggle('expanded')">
+            <div class="system-prompt-header">${escapeHtml(title)}</div>
+            <div class="system-prompt-preview">${escapeHtml(preview)}</div>
+            <div class="system-prompt-expand-hint">... (${remaining} more lines, click to expand)</div>
+            <div class="system-prompt-full">${escapeHtml(text)}</div>
+          </div>`;
         }
+        return `<div class="system-prompt">
+          <div class="system-prompt-header">${escapeHtml(title)}</div>
+          <div class="system-prompt-full" style="display: block">${escapeHtml(text)}</div>
+        </div>`;
+      }
 
-        if (tools && tools.length > 0) {
-          html += `<div class="tools-list">
-            <div class="tools-header">Available Tools</div>
+      function renderToolsList(title, tools) {
+        if (!tools || tools.length === 0) return '';
+        return `<div class="tools-list">
+            <div class="tools-header">${escapeHtml(title)}</div>
             <div class="tools-content">
               ${tools.map(t => {
                 const hasParams = t.parameters && typeof t.parameters === 'object' && t.parameters.properties && Object.keys(t.parameters.properties).length > 0;
@@ -1486,9 +1609,6 @@
               }).join('')}
             </div>
           </div>`;
-        }
-
-        return html;
       }
 
       // ============================================================

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,
@@ -205,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"}`.
@@ -285,7 +286,7 @@ 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
+## 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"]`
@@ -307,9 +308,40 @@ risky call and plan mode's review. `kind` says which: a select carries
 `{"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`. Widgets, status, header, footer
-and custom components draw only in the terminal and do nothing here. Threads a
-terminal-mode connection loads have no dialogs yet.
+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
 
@@ -340,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
@@ -470,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.
@@ -544,6 +610,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;
@@ -578,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
@@ -590,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.
 
@@ -598,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?}`.
@@ -619,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
@@ -630,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`)
@@ -684,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
@@ -741,6 +887,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