@leanandmean/coding-agent 0.74.1-scramjet.32 → 0.74.1-scramjet.33

package/docs/extensions.md

@@ -891,7 +891,7 @@ UI methods for user interaction. See [Custom UI](#custom-ui) for full details.
 
 ### ctx.hasUI
 
-`false` in print mode (`-p`) and JSON mode. `true` in interactive and RPC mode. In RPC mode, dialog methods (`select`, `confirm`, `input`, `editor`) work via the extension UI sub-protocol, and fire-and-forget methods (`notify`, `setStatus`, `setWidget`, `setTitle`, `setEditorText`) emit requests to the client. Some TUI-specific methods are no-ops or return defaults (see [rpc.md](rpc.md#extension-ui-protocol)).
+`false` in print mode (`-p`) and JSON mode. `true` in interactive and RPC mode. This is a transport-level signal, not a guarantee that every UI method is supported. In RPC mode, dialog methods (`select`, `confirm`, `input`, `editor`) work via the extension UI sub-protocol, and fire-and-forget methods (`notify`, `setStatus`, `setWidget`, `setTitle`, `setEditorText`) emit requests to the client, but TUI-only `custom()` resolves `undefined`. Other TUI-specific methods are no-ops or return defaults (see [rpc.md](rpc.md#extension-ui-protocol)). Extensions that require a specific UI method must handle that method's documented unsupported result.
 
 ### ctx.cwd
 
@@ -1529,10 +1529,17 @@ if (pi.getFlag("plan")) {
 Execute a shell command.
 
 ```typescript
-const result = await pi.exec("git", ["status"], { signal, timeout: 5000 });
-// result.stdout, result.stderr, result.code, result.killed
+const result = await pi.exec("gh", ["api", "--method", "POST", "--input", "-", endpoint], {
+  signal,
+  timeout: 5000,
+  stdin: JSON.stringify(payload),
+});
+// result.stdout, result.stderr, result.code, result.killed,
+// result.spawnError, result.stdinError, result.stdoutError, result.stderrError
 ```
 
+When `stdin` is supplied, `pi.exec` writes that exact UTF-8 string once and closes standard input without adding a newline. `spawnError` is present only when the command failed before spawning; `stdinError` reports a write or close failure; `stdoutError` and `stderrError` report output-pipe failures after spawn. Each error contains a safe `message` and optional system `code`, never stdin or process output content. Once the child has spawned, callers must use command-specific semantics to decide whether a failed execution may have produced side effects.
+
 ### pi.getActiveTools() / pi.getAllTools() / pi.setActiveTools(names)
 
 Manage active tools. This works for both built-in tools and dynamically registered tools.
@@ -2423,6 +2430,22 @@ The callback receives:
 - `keybindings` - App keybinding manager (for checking shortcuts)
 - `done(value)` - Call to close component and return value
 
+A pending sequential tool can attach immutable long-form context to its own tool row before compact controls become interactive. Pass the current `toolCallId` from the tool's `execute()` method:
+
+```typescript
+const result = await ctx.ui.custom(
+  (_tui, _theme, _keybindings, done) => new ApprovalSelector(done),
+  {
+    toolAttachedContext: {
+      toolCallId,
+      render: (_tui, theme) => new Text(theme.fg("muted", completeContext), 0, 0),
+    },
+  },
+);
+```
+
+The context is rendered at that pending tool's transcript position, the editor is defocused, and the context is committed once and flushed before its controls receive focus. The complete context is emitted to native terminal scrollback; retention depends on terminal capacity and configuration. It is visual-only and is not persisted or sent to the model. The call fails closed if the named tool row is absent or no longer pending. Use this only from the sequential tool whose id is supplied; ordinary custom UIs remain live and terminal-height bounded.
+
 See [tui.md](tui.md) for the full component API.
 
 #### Overlay Mode (Experimental)
@@ -2577,7 +2600,7 @@ const highlighted = highlightCode(code, lang, theme);
 | Mode | UI Methods | Notes |
 |------|-----------|-------|
 | Interactive | Full TUI | Normal operation |
-| RPC (`--mode rpc`) | JSON protocol | Host handles UI, see [rpc.md](rpc.md) |
+| RPC (`--mode rpc`) | JSON protocol | Host handles supported UI methods; TUI-only `custom()` resolves `undefined`, see [rpc.md](rpc.md) |
 | JSON (`--mode json`) | No-op | Event stream to stdout, see [json.md](json.md) |
 | Print (`-p`) | No-op | Extensions run but can't prompt |
 

package/docs/tui.md

@@ -14,7 +14,7 @@ The interactive mode separates terminal output into append-only committed histor
 
 Mutable output is tail-windowed to at most `terminal.rows - 1` rendered lines before it is written, so live content cannot push mutable rows into native scrollback. Finalization removes the mutable preview and commits the component's finalized presentation once. Pending tools form an ordering barrier, and image-backed tools commit only after their conversions settle.
 
-At the TUI API level, `setLiveRegionStart(component)` selects the first direct child in the live canvas, `commit()` atomically appends newly finalized rows, and `rebuild()` deliberately repaints retained history. Detaching the selected component safely resets committed rendering and returns the TUI to legacy full-repaint rendering. Routine updates, content shrink, temporary-UI dismissal, and height-only resize do not clear scrollback or replay committed history. Width and theme changes, session reconstruction, presentation-setting changes, reload, resume, and external-editor return use deliberate rebuilds because retained output must be reflowed or restyled; those rebuilds intentionally bottom-anchor the display.
+At the TUI API level, `setLiveRegionStart(component)` selects the first direct child in the live canvas, `commit()` schedules atomic append of newly finalized rows, `commitNow()` renders immediately and waits for terminal output to flush when controls must not receive input first, and `rebuild()` deliberately repaints retained history. Detaching the selected component safely resets committed rendering and returns the TUI to legacy full-repaint rendering. Routine updates, content shrink, temporary-UI dismissal, and height-only resize do not clear scrollback or replay committed history. Width and theme changes, session reconstruction, presentation-setting changes, reload, resume, and external-editor return use deliberate rebuilds because retained output must be reflowed or restyled; those rebuilds intentionally bottom-anchor the display.
 
 Overlays remain screen-relative and are composed over the bounded live canvas. Closing an overlay or autocomplete restores the underlying live rows without mutating committed history.
 
@@ -108,16 +108,33 @@ pi.on("session_start", async (_event, ctx) => {
 });
 ```
 
-**In custom tools** via `pi.ui.custom()`:
+**In custom tools** via `ctx.ui.custom()`:
 
 ```typescript
 async execute(toolCallId, params, onUpdate, ctx, signal) {
-  const handle = pi.ui.custom(myComponent);
+  const result = await ctx.ui.custom((_tui, _theme, _keybindings, done) => myComponent(done));
   // ...
-  handle.close();
 }
 ```
 
+### Tool-attached committed context
+
+A pending sequential tool can pair compact live controls with immutable long-form context committed at that tool's transcript position:
+
+```typescript
+const result = await ctx.ui.custom(
+  (_tui, _theme, _keybindings, done) => new ApprovalSelector(done),
+  {
+    toolAttachedContext: {
+      toolCallId,
+      render: (_tui, theme) => new Markdown(completePayload, 0, 0, getMarkdownTheme()),
+    },
+  },
+);
+```
+
+The context is constructed after the controls factory resolves, anchored to the named pending tool row, and committed once. The editor is defocused before terminal flushing begins; controls receive focus only after that flush settles. It is retained internally for deliberate width/theme rebuilds but is not persisted or sent to the model. Native scrollback retention depends on terminal capacity and configuration. The operation fails closed when the row is missing, settled, or cannot be flushed; use it only from the sequential tool identified by `toolCallId`.
+
 ## Overlays
 
 Overlays render components on top of existing content without clearing the screen. Pass `{ overlay: true }` to `ctx.ui.custom()`:
@@ -722,6 +739,8 @@ pi.registerCommand("settings", {
       container.addChild(settingsList);
 
       return {
+        get focused() { return settingsList.focused; },
+        set focused(value) { settingsList.focused = value; },
         render: (w) => container.render(w),
         invalidate: () => container.invalidate(),
         handleInput: (data) => settingsList.handleInput?.(data),
@@ -731,6 +750,8 @@ pi.registerCommand("settings", {
 });
 ```
 
+With `enableSearch`, typing fuzzy-filters labels, Backspace edits the query, and Up/Down plus Enter/Space navigate and activate matches. `SettingsList` propagates focus to its search input and nested focusable submenus for IME cursor placement; a wrapper returned from `ctx.ui.custom()` must forward `focused` as shown above.
+
 **Examples:** [tools.ts](../examples/extensions/tools.ts)
 
 ### Pattern 4: Persistent Status Indicator

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leanandmean/coding-agent",
-  "version": "0.74.1-scramjet.32",
+  "version": "0.74.1-scramjet.33",
   "publishConfig": {
     "access": "public"
   },
@@ -35,7 +35,7 @@
   "dependencies": {
     "@leanandmean/agent": "0.74.1-scramjet.15",
     "@leanandmean/ai": "0.74.1-scramjet.11",
-    "@leanandmean/tui": "0.74.1-scramjet.9",
+    "@leanandmean/tui": "0.74.1-scramjet.10",
     "@silvia-odwyer/photon-node": "^0.3.4",
     "chalk": "^5.5.0",
     "dictionary-en": "^4.0.0",