@knightcodeai/cli 0.19.0 → 0.20.0

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
 
@@ -544,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;
@@ -741,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