klyro 0.1.61 → 0.1.63

package/READ.md

@@ -465,3 +465,71 @@ Global flags `src/index.ts:60` `--cwd/--config/--debug/--verbose/--quiet/--json/
 
 Run: `pnpm build && pnpm test && node dist/index.js --help` → `klyro -p "fix login test" --output json` → `klyro doctor`.
 
+---
+
+## 20. Session Ledger v0.1.39 → v0.1.61 (what was done, what failed)
+
+All work below was done live against user-reported production issues, verified with
+`typecheck 0` + full `vitest` + built-`dist` smoke tests before every publish.
+Current: **`klyro@0.1.61` `latest`, 51 test files, 442/442 tests, commits as
+`siddu-lingampelli`** (history rewritten from `Mythicai-lab`, tags moved, §20.6).
+
+### 20.1 Release history
+
+| Version | Commit | What shipped |
+|---|---|---|
+| 0.1.39 | base | Single-column Klyro TUI, true `#E8843C` orange via 24-bit, hello Direct-LLM (no tools) |
+| 0.1.40 | `ca85d56` | True `#FF6B1A` orange, clean single-column, no `g`-letter corruption |
+| 0.1.41 | `1884807` | `useChatScroll` hook (pin/unpin, snap-to-message, new-messages pill) |
+| 0.1.42 | `50c84dc` | Audit batch: git-blame argv+path validation, `NODE_OPTIONS`/`LD_PRELOAD` block, ordered transcript, configurable `rerunOnce` timeout, model-aware `estimateCost`, Buffer-based (non-O(n²)) verify collectors, deleted empty `packages/cli+core`, `snippets.ts`, `util/log.ts`, `stuckCount`; TUI ellipsis `…`→`...`, mojibake purge |
+| 0.1.43 | `04bd24e` | Slash groundwork: `/provider` `/effort` `/model` `/compact` `/plan` `/login` `/logout` `/init` handlers |
+| 0.1.44 | `81d9627` | **Priority 1 per `commands.md`** (~39 cmds): session/model/project/perms/auth groups; TUI orphan-file reconciliation (deleted `app.inline/banner/input-box/activity-line/thinking-block/components/Header`) |
+| 0.1.45 | `feb30ff` | **Priority 2 per `commands.md`** (~70 cmds): review/build/git/files/agents/config/misc; `/` autocomplete popup + Tab |
+| 0.1.46 | `b8947d1` | **`scroll.md` S1–S9 Ink adaptation**: `measure.ts` (display-width/wrap/cache/line-index), `scroll-model.ts` (anchor reducer), input history + contextual ↑/↓, run-length activity merge, console-patch, exit transcript replay |
+| 0.1.47 | `c440bc3` | **Dead scroll trap fix** (directional epsilon — line/wheel up from bottom could never escape) + mouse-wheel capture + `Ctrl+F/B` pager keys |
+| 0.1.48 | `1e7f85c` | **Set-once auth**: persisted provider resolution (env → config+credentials → probe), first-run setup, `/model` `/provider` persist, `/reload` rebuilds adapter |
+| 0.1.49 | `f0e840d` + `262b8fc` | Plain-HTTP endpoints explain+confirm with persisted `allowInsecure` opt-in, loud rejections (`lastProviderError`), prefilled setup, keep-saved-key; (+ separate commit preserving a concurrent working-tree `scroll.md` rewrite) |
+| 0.1.50 | `5b3d3ee` | **`design.md` conformance**: half-page keys, Esc/Ctrl+C/Shift+Enter semantics, full Markdown renderer, header/statusbar/plan restyle |
+| 0.1.51 | `6ba47de` | **`scroll.md` command architecture**: `transcript-commands.ts` keybind mapper + 4-command handle, submit-key settle effect |
+| 0.1.52 | `db09e5f` | **Markdown columns bug**: `MarkdownText` fragment rendered lines as side-by-side columns — back to single `<Text>` |
+| 0.1.53 | `5f9fa84` | Root `overflow:hidden` I1 guard (input can never be pushed out), tool results patch start-items in place (no forever-`running` spinners), narrow-terminal hints |
+| 0.1.54 | `1ec3d0c` | **Full audit application** (P0+P1, §20.3) |
+| 0.1.55 | `eb8776f` | Live working spinner (Thinking row, running tool groups, status bar) |
+| 0.1.56 | `cf1a94d` | **Thinking channel**: `reasoning_content`/Anthropic-thinking capture → dim display → cleared on response |
+| 0.1.57 | `f6fd749` | Composer audit: `flexShrink={0}` chrome, position/multiline/aggregation tests |
+| 0.1.58 | `a57d526` | Abort clears thinking, `/clear` resets scroll anchor, badge overlap fix |
+| 0.1.59 | `bbe9ba6` | Scroll position readout (`⇅ top/max`) in status bar |
+| 0.1.60 | `6627b5b` | **Wheel tap fix**: intercept `stdin.read` (Ink7 paused mode), not `data` events that never fire |
+| 0.1.61 | `5a1a97f` | Brand sweep: Claude naming removed, `CLAUDE.md` fallback dropped (Klyro-only) |
+
+### 20.2 What was built (by area)
+
+- **Slash commands (113, all smoke-tested on built `dist`)**: session (`/new` `/resume` `/sessions` `/rename` `/fork` `/branch` `/export` `/copy`), model (`/model` `/models` `/provider` `/effort` `/fast`), project (`/init` `/status` `/context` `/diff` `/plan` `/todos` `/memory`), perms (`/permissions` `/mode` `/sandbox` `/approve` `/deny`), app (`/login` `/logout` `/auth` `/version` `/update` `/cancel` `/shell` `!` `/mention` `@` `/tools`), workflow (`/review` `/code-review` `/security-review` `/simplify` `/test` `/lint` `/build` `/run` `/fix` `/explain` `/format` `/ask`), checkpoints (`/undo` `/redo`→honest-noop `/rewind` `/checkpoint` `/accept` `/reject`), activity (`/details` `/verbose` `/raw` `/activity` `/tasks` `/ps` `/stop` `/queue` `/retry` `/kill`), agents+MCP, files (`/attach`→in-context `/drop` `/files` `/image` `/paste` `/ls` `/tree` `/search` `/web` `/read` `/map` `/tokens`), git (`/commit` via temp file `/push` `/pull` `/pr` `/issue`), config UI (`/editor` argv-spawn `/keymap` `/vim` `/theme` `/statusline` `/output-style`), diagnostics (`/doctor` `/debug` `/whoami` `/reload` `/reset` `/bug` `/changelog`), library (`/prompt` `/alias`→auto-expand `/commands` `/env` (injection keys blocked) `/deps` `/install`).
+- **Scroll system** (`src/tui/scroll-model.ts` + `measure.ts` + `mouse.ts` + `transcript-commands.ts`): anchor `{itemId,lineInItem}` (never raw rows), measured wrapped display lines (CJK=2/emoji=2/combining=0), `MeasureCache`, follow-at-bottom / freeze-when-pinned / `↓ N new` badge, `End`/`Ctrl+G`/empty-Enter dismiss, wheel ±3, PageUp/Dn half-page, Home/End first/last, exit transcript replay, degraded tiny-terminal mode.
+- **Auth persistence**: `~/.klyro/settings.json` + `credentials.json` (0600); resolution env → config → stored keys → local probe; `KLYRO_CONFIG`/`KLYRO_CONFIG_DIR`/`KLYRO_CREDENTIALS_FILE` overrides (also used by tests); persisted `allowInsecure` replaces per-terminal `KLYRO_ALLOW_INSECURE=1`.
+- **Verification**: denylist (destructive-only; metachars allowed since commands are user/config-sourced), sanity checks fail-fast *before* the suite, scoped→full, flaky rerun with configured timeout, `hasEdits` drives `--require-verify` (exit 8 only when edits exist).
+- **Safety**: `resolveAndFollowSymlinks` everywhere incl. checkpoints (traversal-contained undo that also restores deletions), `wasRead` guards on all four mutators with normalized + per-task history, `readFileSizeRule` stats real files, `clonePolicyConfig` per engine, `setByPath` proto-pollution guard, shell full-output caps + POSIX process-group kill, `startBackgroundArgv` (shell:false), secret redaction before model/summary paths.
+
+### 20.3 Audit application (the big diagnostic)
+
+Every claim was verified against code before touching. **Confirmed + fixed (P0)**: ApprovalModal never rendered (+ single-listener bridge deafened it — also the flake root cause); Anthropic `role:tool` flattened to empty turns; duplicate `message_end`; edit-file fuzzy rewriting whole files (plus a dead line-window tier); apply-patch append-only stub → real hunk applier; `require()` in ESM (`run-verify`, later all touched files → static imports). **Confirmed + fixed (P1)**: shared policy config; `inferFileChanged` gaps; tokenizer pair orphans; klyro-md import escape + no caps; verify-order waste + `$()` overblock; unbounded full buffers; `/web` caps; checkpoint traversal/undo; store locking + `delete()`/`fork()` with messages; SIGINT-once; silent-mode newline; retry sleep ignores abort; read-history normalization; dotfile flag; `read_fileBody` shape bug in `/attach` `/mention` `/read` `/review` `/explain`; Ctrl+C-safe login/setup; `isToolErrorCode` swallowing custom codes; read-size rule via stat; multi-edit guards; `last.diff` writer; dry-run real prompt; debug.log rotation; `/cd` cwd reset; cost/context single source; headless URL policy. **Deliberately not changed**: `isSimpleChat` fast-path (intended UX); Ink-vs-OpenTUI architecture (approved); eval/MCP/L10–L20 (roadmap); `$EDITOR`/user-typed shell passthrough (user's own intent); trace paths; `isToolErrorCode`-adjacent churn that worked.
+
+### 20.4 What FAILED along the way (honest log)
+
+- **Markdown columns regression (shipped 0.1.50, caught by user screenshot, fixed 0.1.52)**: fragment of `<Text>` in a row `Box` laid lines out as columns. Lesson: frame-level regression test added (fails on old code, passes on new).
+- **Dead scroll trap (mine)**: symmetric follow-epsilon made line/wheel-up from bottom re-stick forever. Found by tracing, fixed directional, regression-tested.
+- **Deaf wheel tap (mine)**: intercepted `data` events; Ink7 only uses `readable`+`read()`. Found by reading installed Ink source, rewrote + tested the wrapper contract.
+- **Silent setup loop (mine)**: saved-but-rejected base URLs were swallowed → infinite first-run. Fixed with recorded reasons + prefilled recovery.
+- **`require()` in ESM**: would have thrown `ReferenceError` in production `dist` while passing under `tsx`/`vitest` shims. Converted everything touched to static imports.
+- **My own test-math errors**: indent tier (4sp→2 tabs), wheel maxTop, badge line counts, half-page expectations — each caught by running tests, fixed, and (for scroll-reset) proven discriminating by noop-check.
+- **Infra friction**: npm `E409` staging + `E404` propagation delays (60–150s waits per publish); PowerShell mangling inline `python`/`node` quoting (rule learned: script files only); `git add -A` twice scooped a concurrent agent's doc rewrites (split into separate commits; own files only since); vitest load flakes under parallel sessions (fixed sleeps → poll-with-timeout; one residual publish-gate flake at 0.1.59, green on rerun).
+- **Authorship**: 49 commits + 10 tags rewritten to `siddu-lingampelli` (force-with-lease, trees verified identical); repo-local git identity set.
+
+### 20.5 Environment notes for future sessions
+
+- Windows PowerShell 5.1: chain with `;`, never `&&`; quote paths; never inline `python -c` with brackets/quotes (write temp scripts under `C:\Users\L.Siddhartha\AppData\Local\Temp\opencode`).
+- Never `git add -A` blindly — another agent rewrites `design.md`/`scroll.md`/`TUI_DESIGN.md`/`commands.md` concurrently; stage own files explicitly.
+- `npm publish` runs `typecheck && test && build`; expect CDN delays; `latest` flips ~1–3 min after `+ klyro@x`.
+- Test isolation for anything reading `~/.klyro`: set `KLYRO_CONFIG` + `KLYRO_CONFIG_DIR` + `KLYRO_CREDENTIALS_FILE` to temp dirs.
+- `ink-testing-library` has fixed terminal geometry (no resize tests) and normalizes keys like production Ink; production-only paths (stdin tap, alt-screen) need contract tests, not frame tests.
+

package/dist/agent/anthropic-adapter.d.ts

@@ -8,14 +8,15 @@
  *  1. `system` is a top-level field, not a message with role=system.
  *  2. Tool definitions use `input_schema` not `parameters`, and have no
  *     `type: 'function'` wrapper.
- *  3. `tool_use_id` becomes our `id`; the tool input is sent as a single
- *     `input_json_delta` block.
+ *  3. `tool_use_id` becomes our `id`; tool input arrives fragmented across
+ *     `input_json_delta` frames, assembled per content_block index (never
+ *     assumed whole, never silently dropped).
  *
  * Auth: `x-api-key: <key>`. Version header is sent as `anthropic-version`.
  * Auth can be a Bearer token (for proxies) — the adapter accepts either.
  */
 import type { Message } from './message.js';
-import type { ProviderAdapter, ToolDefinition } from './provider-adapter.js';
+import type { ProviderAdapter, StreamEvent, ToolDefinition } from './provider-adapter.js';
 export interface AnthropicAdapterOptions {
     baseURL?: string;
     apiKey: string;
@@ -50,17 +51,37 @@ interface AnthropicMessage {
         is_error?: boolean;
     }>;
 }
+interface AnthropicSseEvent {
+    type: string;
+    [key: string]: unknown;
+}
 export declare class AnthropicApiError extends Error {
     readonly status: number;
     readonly body: string;
     constructor(status: number, body: string);
 }
 export declare function anthropicAdapter(opts: AnthropicAdapterOptions): ProviderAdapter;
-/** Match an Anthropic content_block index to the tool_use id we emitted. */
-declare function findToolIdByIndex(index: number | undefined, buffers: Map<string, {
-    name: string;
-    argsJson: string;
-}>, indexToToolId?: Map<number, string>): string | undefined;
+/**
+ * Mutable per-stream assembly state. Blocks are keyed by content_block
+ * index; the tool id is carried inside the block entry. There is no global
+ * "current tool" — concurrent or interleaved blocks stay correctly routed.
+ */
+interface AnthropicStreamState {
+    blocks: Map<number, {
+        id: string;
+        name: string;
+        argsJson: string;
+        open: boolean;
+    }>;
+    /** Fragments for an index with no open block yet (flushed on block start). */
+    orphans: Map<number, string>;
+    thinkingIdx: number | null;
+    usage: {
+        input?: number;
+        output?: number;
+    };
+}
+declare function translateSse(event: string, parsed: AnthropicSseEvent, state: AnthropicStreamState): StreamEvent[];
 declare function toAnthropicMessages(messages: Message[]): AnthropicMessage[];
 declare function toAnthropicTool(t: ToolDefinition): {
     name: string;
@@ -70,6 +91,6 @@ declare function toAnthropicTool(t: ToolDefinition): {
 export declare const _internal: {
     toAnthropicMessages: typeof toAnthropicMessages;
     toAnthropicTool: typeof toAnthropicTool;
-    findToolIdByIndex: typeof findToolIdByIndex;
+    translateSse: typeof translateSse;
 };
 export {};

package/dist/agent/anthropic-adapter.js

@@ -8,8 +8,9 @@
  *  1. `system` is a top-level field, not a message with role=system.
  *  2. Tool definitions use `input_schema` not `parameters`, and have no
  *     `type: 'function'` wrapper.
- *  3. `tool_use_id` becomes our `id`; the tool input is sent as a single
- *     `input_json_delta` block.
+ *  3. `tool_use_id` becomes our `id`; tool input arrives fragmented across
+ *     `input_json_delta` frames, assembled per content_block index (never
+ *     assumed whole, never silently dropped).
  *
  * Auth: `x-api-key: <key>`. Version header is sent as `anthropic-version`.
  * Auth can be a Bearer token (for proxies) — the adapter accepts either.
@@ -111,12 +112,14 @@ async function* streamAnthropic(req, opts) {
     const reader = resp.body.getReader();
     const decoder = new TextDecoder('utf-8');
     let buf = '';
-    // Track in-progress tool calls so we can emit start/delta/end.
-    const toolBuffers = new Map();
-    // Map content_block index → tool_use id (persists after tool completes to handle late deltas)
-    const indexToToolId = new Map();
-    // Active thinking-block index (Anthropic reasoning channel).
-    const thinkingState = { idx: null };
+    // Per-block assembly keyed by content_block index (tool input IS
+    // fragmented across input_json_delta frames — never assume otherwise).
+    const state = {
+        blocks: new Map(),
+        orphans: new Map(),
+        thinkingIdx: null,
+        usage: {},
+    };
     // message_stop already yields message_end — don't emit a second one at EOF.
     let sawMessageEnd = false;
     try {
@@ -155,7 +158,7 @@ async function* streamAnthropic(req, opts) {
                 catch {
                     continue;
                 }
-                const out = translateSse(e.event, parsed, toolBuffers, indexToToolId, thinkingState);
+                const out = translateSse(e.event, parsed, state);
                 for (const ev of out) {
                     if (ev.kind === 'message_end')
                         sawMessageEnd = true;
@@ -172,23 +175,69 @@ async function* streamAnthropic(req, opts) {
     finally {
         reader.releaseLock();
     }
-    if (!sawMessageEnd)
-        yield { kind: 'message_end', finishReason: 'stop' };
+    // Truncated stream: close open blocks so the runtime finalizes them as
+    // (malformed) structured errors instead of hanging, then terminate.
+    for (const b of state.blocks.values()) {
+        if (b.open) {
+            b.open = false;
+            yield { kind: 'tool_call_end', id: b.id };
+        }
+    }
+    state.blocks.clear();
+    // Fragments that could never be attributed to a tool block are a stream
+    // integrity failure — surface loudly, never silently drop.
+    if (state.orphans.size > 0 && !sawMessageEnd) {
+        const count = [...state.orphans.values()].reduce((n, s) => n + s.length, 0);
+        state.orphans.clear();
+        yield {
+            kind: 'error',
+            code: 'ORPHAN_TOOL_DELTAS',
+            message: `stream ended with ${count} chars of tool input that match no content block`,
+            retryable: false,
+        };
+        return;
+    }
+    state.orphans.clear();
+    if (!sawMessageEnd) {
+        yield {
+            kind: 'message_end',
+            finishReason: 'stop',
+            ...(state.usage.input !== undefined || state.usage.output !== undefined
+                ? { usage: { input: state.usage.input ?? 0, output: state.usage.output ?? 0 } }
+                : {}),
+        };
+    }
 }
-function translateSse(event, parsed, toolBuffers, indexToToolId, thinking) {
+function translateSse(event, parsed, state) {
     const out = [];
     switch (event) {
+        case 'message_start': {
+            const usage = parsed.message?.usage;
+            if (typeof usage?.input_tokens === 'number')
+                state.usage.input = usage.input_tokens;
+            return out;
+        }
+        case 'message_delta': {
+            const usage = parsed.usage;
+            if (typeof usage?.output_tokens === 'number') {
+                state.usage.output = (state.usage.output ?? 0) + usage.output_tokens;
+            }
+            return out;
+        }
         case 'content_block_start': {
             const block = parsed.content_block;
             const idx = parsed.index;
-            if (block?.type === 'tool_use' && block.id && block.name) {
-                toolBuffers.set(block.id, { name: block.name, argsJson: '' });
-                if (idx !== undefined)
-                    indexToToolId.set(idx, block.id);
+            if (block?.type === 'tool_use' && block.id && block.name && idx !== undefined) {
+                // Flush any fragments that arrived before the block start.
+                const stashed = state.orphans.get(idx);
+                state.orphans.delete(idx);
+                state.blocks.set(idx, { id: block.id, name: block.name, argsJson: stashed ?? '', open: true });
                 out.push({ kind: 'tool_call_start', id: block.id, name: block.name });
+                if (stashed)
+                    out.push({ kind: 'tool_call_delta', id: block.id, argsJson: stashed });
             }
-            else if ((block?.type === 'thinking' || block?.type === 'redacted_thinking') && thinking && idx !== undefined) {
-                thinking.idx = idx;
+            else if ((block?.type === 'thinking' || block?.type === 'redacted_thinking') && idx !== undefined) {
+                state.thinkingIdx = idx;
             }
             return out;
         }
@@ -202,31 +251,50 @@ function translateSse(event, parsed, toolBuffers, indexToToolId, thinking) {
                 out.push({ kind: 'thinking_delta', text: delta.thinking });
             }
             else if (delta?.type === 'input_json_delta' && typeof delta.partial_json === 'string') {
-                const id = findToolIdByIndex(index, toolBuffers, indexToToolId);
-                if (id) {
-                    const buf = toolBuffers.get(id);
-                    if (buf) {
-                        buf.argsJson += delta.partial_json;
-                        out.push({ kind: 'tool_call_delta', id, argsJson: delta.partial_json });
+                const entry = index !== undefined ? state.blocks.get(index) : undefined;
+                if (entry && entry.open) {
+                    entry.argsJson += delta.partial_json;
+                    out.push({ kind: 'tool_call_delta', id: entry.id, argsJson: delta.partial_json });
+                }
+                else if (index !== undefined) {
+                    const open = [...state.blocks.values()].filter((b) => b.open);
+                    if (open.length === 1) {
+                        // Single in-flight tool: attribute here (documented heuristic).
+                        open[0].argsJson += delta.partial_json;
+                        out.push({ kind: 'tool_call_delta', id: open[0].id, argsJson: delta.partial_json });
+                    }
+                    else {
+                        // No safe attribution — stash for a later block start, or
+                        // surface as ORPHAN_TOOL_DELTAS at stream end. Never drop.
+                        state.orphans.set(index, (state.orphans.get(index) ?? '') + delta.partial_json);
                     }
                 }
+                else {
+                    state.orphans.set(-1, (state.orphans.get(-1) ?? '') + delta.partial_json);
+                }
             }
             return out;
         }
         case 'content_block_stop': {
             const index = parsed.index;
-            if (thinking && index !== undefined && index === thinking.idx)
-                thinking.idx = null;
-            const id = findToolIdByIndex(index, toolBuffers, indexToToolId);
-            if (id) {
-                toolBuffers.delete(id);
-                // Keep index mapping for late deltas that may arrive after stop (rare)
-                out.push({ kind: 'tool_call_end', id });
+            if (index !== undefined && index === state.thinkingIdx)
+                state.thinkingIdx = null;
+            const entry = index !== undefined ? state.blocks.get(index) : undefined;
+            if (entry && entry.open) {
+                entry.open = false;
+                state.blocks.delete(index);
+                out.push({ kind: 'tool_call_end', id: entry.id });
             }
             return out;
         }
         case 'message_stop': {
-            out.push({ kind: 'message_end', finishReason: 'stop' });
+            out.push({
+                kind: 'message_end',
+                finishReason: 'stop',
+                ...(state.usage.input !== undefined || state.usage.output !== undefined
+                    ? { usage: { input: state.usage.input ?? 0, output: state.usage.output ?? 0 } }
+                    : {}),
+            });
             return out;
         }
         case 'error': {
@@ -243,21 +311,6 @@ function translateSse(event, parsed, toolBuffers, indexToToolId, thinking) {
             return out;
     }
 }
-/** Match an Anthropic content_block index to the tool_use id we emitted. */
-function findToolIdByIndex(index, buffers, indexToToolId) {
-    if (index === undefined)
-        return undefined;
-    if (indexToToolId) {
-        const direct = indexToToolId.get(index);
-        if (direct)
-            return direct;
-    }
-    // Single-buffer fallback: if only one in-flight tool, any delta belongs to it
-    if (buffers.size === 1)
-        return buffers.keys().next().value;
-    // No reliable mapping — drop the delta rather than misroute to wrong tool (prevents _parse_error loops)
-    return undefined;
-}
 function toAnthropicMessages(messages) {
     return messages.map((m) => {
         if (m.role === 'user') {
@@ -320,4 +373,4 @@ function toAnthropicTool(t) {
     };
 }
 // Re-export for testability.
-export const _internal = { toAnthropicMessages, toAnthropicTool, findToolIdByIndex };
+export const _internal = { toAnthropicMessages, toAnthropicTool, translateSse };

package/dist/agent/provider-adapter.js

@@ -195,10 +195,41 @@ async function* streamChatCompletions(url, opts, req, fetchImpl) {
     const reader = res.body.getReader();
     const decoder = new TextDecoder();
     let buf = '';
-    // Track per-tool-call id by index.
-    const toolIds = new Map();
-    const toolNames = new Map();
+    const blocks = new Map();
     let pendingUsage;
+    // Canonical contract: exactly one terminal event per stream.
+    let terminalEmitted = false;
+    function* emitTerminal(finishReason, usage) {
+        if (terminalEmitted)
+            return;
+        terminalEmitted = true;
+        for (const b of blocks.values()) {
+            if (b.started && !b.ended && b.id) {
+                b.ended = true;
+                yield { kind: 'tool_call_end', id: b.id };
+            }
+        }
+        // Fragments that never gained an identity are surfaced as incomplete
+        // calls (the runtime turns them into structured errors) — never dropped.
+        let incomplete = 0;
+        for (const b of blocks.values()) {
+            if (!b.started && (b.argsJson || b.id || b.name)) {
+                const id = b.id ?? `incomplete_${incomplete++}`;
+                yield { kind: 'tool_call_start', id, name: b.name ?? 'unknown' };
+                if (b.argsJson)
+                    yield { kind: 'tool_call_delta', id, argsJson: b.argsJson };
+                yield { kind: 'tool_call_end', id };
+                b.started = true;
+                b.ended = true;
+            }
+        }
+        const end = { kind: 'message_end' };
+        if (finishReason)
+            end.finishReason = finishReason;
+        if (usage)
+            end.usage = usage;
+        yield end;
+    }
     try {
         while (true) {
             const { value, done } = await reader.read();
@@ -215,7 +246,7 @@ async function* streamChatCompletions(url, opts, req, fetchImpl) {
                         continue;
                     const data = line.slice(5).trim();
                     if (data === '[DONE]') {
-                        yield { kind: 'message_end' };
+                        yield* emitTerminal(undefined, pendingUsage);
                         return;
                     }
                     let chunk;
@@ -248,17 +279,28 @@ async function* streamChatCompletions(url, opts, req, fetchImpl) {
                             yield { kind: 'thinking_delta', text: thinking };
                         }
                         for (const tc of choice.delta.tool_calls ?? []) {
-                            if (tc.id && tc.function?.name) {
-                                toolIds.set(tc.index, tc.id);
-                                toolNames.set(tc.index, tc.function.name);
-                                yield { kind: 'tool_call_start', id: tc.id, name: tc.function.name };
+                            let b = blocks.get(tc.index);
+                            if (!b) {
+                                b = { argsJson: '', started: false, ended: false };
+                                blocks.set(tc.index, b);
                             }
-                            else if (tc.id) {
-                                toolIds.set(tc.index, tc.id);
+                            if (tc.id)
+                                b.id = tc.id;
+                            if (tc.function?.name)
+                                b.name = tc.function.name;
+                            const newArgs = tc.function?.arguments;
+                            if (newArgs)
+                                b.argsJson += newArgs;
+                            if (b.id && b.name && !b.started) {
+                                // Identity arrived (possibly after earlier fragments). Emit
+                                // start, then flush any accumulated args as one delta.
+                                b.started = true;
+                                yield { kind: 'tool_call_start', id: b.id, name: b.name };
+                                if (b.argsJson)
+                                    yield { kind: 'tool_call_delta', id: b.id, argsJson: b.argsJson };
                             }
-                            if (tc.function?.arguments) {
-                                const id = toolIds.get(tc.index) ?? `call_${tc.index}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
-                                yield { kind: 'tool_call_delta', id, argsJson: tc.function.arguments };
+                            else if (b.started && b.id && newArgs) {
+                                yield { kind: 'tool_call_delta', id: b.id, argsJson: newArgs };
                             }
                         }
                         if (choice.finish_reason) {
@@ -266,38 +308,19 @@ async function* streamChatCompletions(url, opts, req, fetchImpl) {
                                 ? { input: chunk.usage.prompt_tokens, output: chunk.usage.completion_tokens }
                                 : undefined);
                             pendingUsage = undefined;
-                            // Clear tool tracking per message to avoid stale ids on next turn
-                            const ids = [...toolIds.values()];
-                            toolIds.clear();
-                            toolNames.clear();
-                            for (const id of ids)
-                                yield { kind: 'tool_call_end', id };
-                            yield { kind: 'message_end', finishReason: choice.finish_reason, usage };
+                            yield* emitTerminal(choice.finish_reason, usage);
                         }
                     }
                 }
             }
         }
-        if (toolIds.size) {
-            for (const id of toolIds.values())
-                yield { kind: 'tool_call_end', id };
-            if (pendingUsage) {
-                yield { kind: 'message_end', usage: pendingUsage };
-            }
-            else {
-                yield { kind: 'message_end' };
-            }
-        }
-        else if (pendingUsage) {
-            yield { kind: 'message_end', usage: pendingUsage };
-        }
-        else {
-            yield { kind: 'message_end' };
-        }
+        yield* emitTerminal(undefined, pendingUsage);
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        yield { kind: 'error', code: 'STREAM', message: msg, retryable: true };
+        if (!terminalEmitted) {
+            const msg = err instanceof Error ? err.message : String(err);
+            yield { kind: 'error', code: 'STREAM', message: msg, retryable: true };
+        }
     }
     finally {
         clearTimeout(timer);

package/dist/agent/runtime.d.ts

@@ -139,6 +139,7 @@ export type RuntimeEvent = {
     kind: 'usage';
     input: number;
     output: number;
+    estimated?: boolean;
 } | {
     kind: 'final_text';
     text: string;
@@ -171,7 +172,7 @@ export type RuntimeEvent = {
     sessionId: string;
 };
 export interface RunResult {
-    status: 'complete' | 'max_steps' | 'aborted' | 'no_final' | 'verify_failed' | 'limit' | 'blocked';
+    status: 'complete' | 'max_steps' | 'aborted' | 'no_final' | 'verify_failed' | 'limit' | 'blocked' | 'stuck';
     steps: number;
     toolCalls: number;
     finalText: string;
@@ -181,6 +182,7 @@ export interface RunResult {
     usage: {
         input: number;
         output: number;
+        estimated?: boolean;
     };
     /** Number of policy-driven user prompts the user accepted. */
     repairs?: number;