@adhdev/daemon-core 0.9.82-rc.310 → 0.9.82-rc.312

package/src/mesh/mesh-work-queue.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from 'crypto';
 import { requireMeshHostQueueOwner } from './mesh-host-ownership.js';
 import type { RepoMeshDaemonRole } from '../repo-mesh-types.js';
+import { MESH_CONVERGE_REFINE_TAG, resolveAutoConvergeCodeChange } from '../repo-mesh-types.js';
 import { MeshRuntimeStore } from './mesh-runtime-store.js';
 import { getMesh } from '../config/mesh-config.js';
 
@@ -203,6 +204,45 @@ function firstProviderPriority(policy: unknown): string | undefined {
     return raw.find(type => typeof type === 'string' && type.trim())?.trim();
 }
 
+/**
+ * Synthetic `role=<x>` capability tags advertised by a node's policy.providerRoles.
+ *
+ * When a specific `providerType` is being evaluated, only that provider's declared
+ * role is emitted — so role-based routing (requiredTags: ["role=validation"]) gates
+ * the *selected* provider through the ordinary capability-tag filter. When no
+ * provider is selected (node-level eligibility scan), every declared role is emitted
+ * so the node passes the filter if ANY of its providers could satisfy the role; the
+ * per-provider tag set then narrows it during provider selection.
+ *
+ * Roles are lowercased and deduped. Missing/empty providerRoles emits nothing, so a
+ * node that never declares roles advertises no `role=` tags and is therefore only
+ * matched by role-unconstrained tasks (full backward compatibility).
+ */
+function roleCapabilityTags(policy: unknown, providerType: string | undefined): string[] {
+    const roles = policy && typeof policy === 'object' && !Array.isArray(policy)
+        ? (policy as Record<string, unknown>).providerRoles
+        : undefined;
+    if (!Array.isArray(roles)) return [];
+    const wantedProvider = typeof providerType === 'string' && providerType.trim()
+        ? providerType.trim().toLowerCase()
+        : '';
+    const out: string[] = [];
+    for (const entry of roles) {
+        if (!entry || typeof entry !== 'object') continue;
+        const type = typeof (entry as any).providerType === 'string'
+            ? (entry as any).providerType.trim().toLowerCase()
+            : '';
+        const role = typeof (entry as any).role === 'string'
+            ? (entry as any).role.trim().toLowerCase()
+            : '';
+        if (!role) continue;
+        // When narrowing to a selected provider, only emit that provider's role.
+        if (wantedProvider && type && type !== wantedProvider) continue;
+        out.push(`role=${role}`);
+    }
+    return out;
+}
+
 export function buildMeshNodeCapabilityTags(
     node: { capabilities?: unknown; policy?: unknown; isLocalWorktree?: unknown; worktreeBranch?: unknown } | undefined,
     providerType?: string,
@@ -222,6 +262,24 @@ export function buildMeshNodeCapabilityTags(
         // mesh_enqueue_task with required_tags: ["worktree=<branch>"] routes
         // only to the matching worktree node.
         ...(node?.isLocalWorktree === true && worktreeBranch ? [`worktree=${worktreeBranch}`] : []),
+        // Convergence routing: advertise how this node can land its work onto base.
+        //   - converge=refine: local worktree nodes (on ANY machine — refine_mesh_node
+        //     now forwards to the owning daemon) can run the Refinery merge → push →
+        //     cleanup against their own checkout, so they accept code_change tasks.
+        //   - converge=fast_forward: non-worktree nodes (the machine itself) can only
+        //     ff/push an already-converged branch; they are NOT a destination for
+        //     code_change work (a worktree is created first, and that worktree node
+        //     receives the task instead). Reuses the ordinary required-tags filter —
+        //     the load-balancing scheduler auto-injects converge=refine for code_change
+        //     so such work is hard-filtered onto refine-capable nodes.
+        ...(node?.isLocalWorktree === true ? ['converge=refine'] : ['converge=fast_forward']),
+        // Role-based routing: advertise role=<x> for each (node, provider) role
+        // declared in policy.providerRoles. Narrowed to the selected provider when
+        // one is given so the chosen provider must match a task's required role;
+        // when no provider is selected, all declared roles are advertised for the
+        // node-level eligibility scan. Reuses the ordinary required-tags filter —
+        // no separate role field/gate.
+        ...roleCapabilityTags(node?.policy, providerType),
     ]);
 }
 
@@ -232,6 +290,44 @@ export function nodeSatisfiesRequiredTags(requiredTags: unknown, capabilityTags:
     return required.every(tag => available.has(tag));
 }
 
+/**
+ * Convergence-aware required-tags resolution (load-balancing scheduler, opt-in).
+ *
+ * When the mesh enables policy.autoConvergeCodeChange, a `converge=refine` required
+ * tag is merged into a code_change task's required tags at enqueue time, so the
+ * scheduler hard-filters the task onto refine-capable worktree nodes only (on any
+ * machine — refine_mesh_node forwards to the owning daemon). Because the tag is
+ * persisted on the queue entry, BOTH the eligibility scan (maybeAutoLaunchOneQueueSession)
+ * and the claim transaction (claimNextQueueTask → nodeSatisfiesRequiredTags) enforce
+ * it consistently.
+ *
+ * Strict backward compatibility — the injection is skipped (returns the explicit tags
+ * unchanged) when ANY of:
+ *   - the mesh does not opt in (autoConvergeCodeChange !== true), or
+ *   - the task is not code_change (validation / live_debug_readonly / launch_app /
+ *     convergence carry no merge cost and may run anywhere), or
+ *   - the task is explicitly targeted (targetNodeId): the operator chose the node, so
+ *     we do not second-guess it by filtering on convergence capability.
+ * Idempotent: normalizeMeshCapabilityTags dedupes, so re-injection is a no-op.
+ */
+export function resolveConvergeRequiredTags(
+    meshId: string,
+    taskMode: MeshTaskMode | undefined,
+    explicitRequiredTags: string[],
+    opts?: { targetNodeId?: string },
+): string[] {
+    if (taskMode !== 'code_change') return explicitRequiredTags;
+    if (typeof opts?.targetNodeId === 'string' && opts.targetNodeId.trim()) return explicitRequiredTags;
+    let optedIn = false;
+    try {
+        optedIn = resolveAutoConvergeCodeChange(getMesh(meshId)?.policy as any);
+    } catch {
+        optedIn = false;
+    }
+    if (!optedIn) return explicitRequiredTags;
+    return normalizeMeshCapabilityTags([...explicitRequiredTags, MESH_CONVERGE_REFINE_TAG]);
+}
+
 function withQueueLock<T>(_meshId: string, fn: () => T): T {
     return MeshRuntimeStore.getInstance().transaction(fn);
 }
@@ -325,7 +421,15 @@ export function enqueueTask(
             taskMode: modeValidation.taskMode,
             targetNodeId: opts?.targetNodeId,
             targetSessionId: opts?.targetSessionId,
-            requiredTags: normalizeMeshCapabilityTags(opts?.requiredTags),
+            // Convergence routing (opt-in): auto-inject converge=refine for code_change
+            // tasks so they hard-filter onto refine-capable worktree nodes. No-op unless
+            // the mesh opts in; explicit target_node_id / required_tags are preserved.
+            requiredTags: resolveConvergeRequiredTags(
+                meshId,
+                modeValidation.taskMode,
+                normalizeMeshCapabilityTags(opts?.requiredTags),
+                { targetNodeId: opts?.targetNodeId },
+            ),
             ...(dependsOn.length > 0 ? { dependsOn } : {}),
             ...(typeof opts?.missionId === 'string' && opts.missionId.trim() ? { missionId: opts.missionId.trim() } : {}),
             createdAt: new Date().toISOString(),

package/src/providers/spec/cli-adapter.ts

@@ -21,7 +21,7 @@
 import { FsmDriver, type DashboardEvent, type ISpecDriver } from './fsm-driver.js';
 import { executeNativeHistory } from './native-history-executor.js';
 import * as fs from 'node:fs';
-import type { NativeHistoryConfig, Control } from './types.js';
+import type { NativeHistoryConfig, Control, ControlAction } from './types.js';
 import type { CliAdapter, CliAdapterStatus } from '../../cli-adapter-types.js';
 import type { ChatMessage } from '../../types.js';
 import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
@@ -47,6 +47,10 @@ function stripAnsi(text: string): string {
         .replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, '');
 }
 
+function delay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
 export class SpecCliAdapter implements CliAdapter {
     readonly cliType: string;
     readonly cliName: string;
@@ -311,9 +315,15 @@ export class SpecCliAdapter implements CliAdapter {
      * drives the dispatch:
      *
      *   send_keys     → click_control                   (e.g. stop)
-     *   open_picker   → click_control then resolve when extract_choices
-     *                   surface; choice index comes from args.choiceIndex
-     *                   or args.choice (string label match), defaulting to 0
+     *   open_picker   → two roles, driven by the screen, not a hardcoded list:
+     *                   - LIST  (no choice arg): open the picker, wait for it
+     *                     to render, parse the on-screen options via
+     *                     `extract_choices`, and return them as
+     *                     `controlResult.options` (+ `currentValue`). This is
+     *                     how the dashboard's Model/Mode controls learn what is
+     *                     actually selectable in this CLI right now.
+     *                   - SELECT (args.choiceIndex / args.choiceLabel): drive
+     *                     the picker to that option using `submit_key`.
      *   attach_image  → attach_image dispatch; expects args.blob (data url
      *                   or base64) and args.mime
      *
@@ -341,16 +351,148 @@ export class SpecCliAdapter implements CliAdapter {
             this.driver.dispatch({ kind: 'attach_image', blob, mime });
             return Promise.resolve({ ok: true, effects: [{ type: 'attached_image', controlId: ctl.id }] });
         }
-        // send_keys + open_picker both route through click_control. For
-        // open_picker the dashboard sees the picker modal arrive via a
-        // state_changed event, then submits the choice using
-        // resolveModal/click_modal_button. invokeScript's synchronous
-        // return is just an acknowledgement that the trigger fired.
+        if (action.type === 'open_picker') {
+            const choiceIndex = typeof flat.choiceIndex === 'number' ? flat.choiceIndex
+                : typeof flat.choiceIndex === 'string' && flat.choiceIndex.trim() ? Number(flat.choiceIndex)
+                : undefined;
+            const choiceLabel = typeof flat.choiceLabel === 'string' ? flat.choiceLabel
+                : typeof flat.choice === 'string' ? flat.choice
+                : undefined;
+            if ((typeof choiceIndex === 'number' && Number.isFinite(choiceIndex)) || (choiceLabel && choiceLabel.trim())) {
+                return this.selectPickerChoice(ctl, action, choiceIndex, choiceLabel);
+            }
+            return this.openPickerAndListChoices(ctl, action);
+        }
+        // send_keys routes through click_control.
         this.driver.dispatch({ kind: 'click_control', control_id: ctl.id, payload: flat });
-        const effects: { type: string; controlId: string }[] = [];
-        if (action.type === 'open_picker') effects.push({ type: 'opened_picker', controlId: ctl.id });
-        else if (action.type === 'send_keys') effects.push({ type: 'sent_keys', controlId: ctl.id });
-        return Promise.resolve({ ok: true, effects });
+        return Promise.resolve({ ok: true, effects: [{ type: 'sent_keys', controlId: ctl.id }] });
+    }
+
+    /**
+     * Open an `open_picker` control and return the options the CLI is showing,
+     * parsed live from the screen via `extract_choices`. Nothing is selected —
+     * the picker is left open so a follow-up SELECT invoke can commit a choice.
+     */
+    private async openPickerAndListChoices(
+        ctl: Control,
+        action: Extract<ControlAction, { type: 'open_picker' }>,
+    ): Promise<unknown> {
+        this.driver.dispatch({ kind: 'click_control', control_id: ctl.id });
+        const ready = await this.waitForPickerRendered(action);
+        const options = this.extractPickerChoices(action);
+        const currentValue = options.find(o => o.current)?.label;
+        return {
+            ok: true,
+            effects: [{ type: 'opened_picker', controlId: ctl.id }],
+            controlResult: {
+                options: options.map(o => ({ value: o.label, label: o.label, current: o.current })),
+                ...(currentValue ? { currentValue } : {}),
+                source: 'screen-parse',
+                ...(ready ? {} : { warning: 'picker_render_timeout' }),
+            },
+        };
+    }
+
+    /**
+     * Drive an already-listable picker to a specific option. The option can be
+     * named (choiceLabel — matched against the parsed on-screen labels) or
+     * positional (choiceIndex — the on-screen number). The actual keystrokes
+     * come from the spec's `submit_key` with `{index}` substituted, so the spec
+     * — not this code — decides how a selection is keyed for each CLI.
+     */
+    private async selectPickerChoice(
+        ctl: Control,
+        action: Extract<ControlAction, { type: 'open_picker' }>,
+        choiceIndex: number | undefined,
+        choiceLabel: string | undefined,
+    ): Promise<unknown> {
+        // Open + wait so the choice list is on screen before we resolve the
+        // label → index mapping (a fresh invoke may arrive with the picker
+        // closed; re-opening an open picker is a no-op on these CLIs).
+        this.driver.dispatch({ kind: 'click_control', control_id: ctl.id });
+        await this.waitForPickerRendered(action);
+        const options = this.extractPickerChoices(action);
+
+        let index = choiceIndex;
+        if ((index == null || !Number.isFinite(index)) && choiceLabel) {
+            const needle = choiceLabel.trim().toLowerCase();
+            const match = options.find(o => o.label.toLowerCase().includes(needle));
+            if (!match) {
+                return { ok: false, error: `choice not found on screen: ${choiceLabel}`, controlResult: { options: options.map(o => ({ value: o.label, label: o.label })) } };
+            }
+            index = match.index;
+        }
+        if (index == null || !Number.isFinite(index)) {
+            return { ok: false, error: 'choiceIndex or choiceLabel required to select' };
+        }
+
+        const keys = (action.submit_key || '{index}\r').replace(/\{index\}/g, String(index));
+        this.driver.dispatch({ kind: 'pty_write', data: keys });
+        const selected = options.find(o => o.index === index);
+        return {
+            ok: true,
+            effects: [{ type: 'selected_choice', controlId: ctl.id }],
+            controlResult: {
+                ok: true,
+                ...(selected ? { currentValue: selected.label } : {}),
+                selectedIndex: index,
+            },
+        };
+    }
+
+    /** Poll the live screen until the picker's `wait_for` condition matches,
+     *  up to a short budget. Returns true if it rendered, false on timeout. */
+    private async waitForPickerRendered(action: Extract<ControlAction, { type: 'open_picker' }>): Promise<boolean> {
+        const wf = action.wait_for;
+        if (!wf?.regex) { await delay(250); return true; }
+        const re = new RegExp(wf.regex, wf.flags ?? 'i');
+        const deadline = Date.now() + 2500;
+        while (Date.now() < deadline) {
+            await delay(120);
+            const hay = this.readScreenSectionText(wf.section);
+            if (re.test(hay)) return true;
+        }
+        return false;
+    }
+
+    /** Parse the picker's `extract_choices` pattern against the live screen.
+     *  Each match yields { index, label, current }. `current` is true for the
+     *  line the CLI marks with its cursor glyph (❯ ›). Purely screen-driven —
+     *  no model/mode names are baked in. */
+    private extractPickerChoices(action: Extract<ControlAction, { type: 'open_picker' }>): Array<{ index: number; label: string; current: boolean }> {
+        const ec = action.extract_choices;
+        if (!ec?.pattern) return [];
+        const text = this.readScreenSectionText(ec.section);
+        const out: Array<{ index: number; label: string; current: boolean }> = [];
+        const seen = new Set<number>();
+        for (const rawLine of text.split('\n')) {
+            const line = rawLine.replace(/\r$/, '');
+            const m = new RegExp(ec.pattern, ec.flags ?? '').exec(line);
+            if (!m) continue;
+            const idx = Number(m[1]);
+            if (!Number.isFinite(idx) || seen.has(idx)) continue;
+            const label = (m[2] ?? '').replace(/\s+/g, ' ').trim();
+            if (!label) continue;
+            const current = /^\s*[❯›>]/.test(line) || /[✔✓●]\s*$/.test(label);
+            seen.add(idx);
+            out.push({ index: idx, label, current });
+        }
+        return out;
+    }
+
+    /** Live text of a named screen section (or the whole screen when no
+     *  section is named), resolved from the driver's current sections. */
+    private readScreenSectionText(sectionId?: string): string {
+        try {
+            const sections = this.driver.getSections();
+            if (sectionId && sections) {
+                const hit = sections.find(s => s.id === sectionId);
+                if (hit) return hit.text;
+            }
+            return this.driver.getScreen();
+        } catch {
+            return '';
+        }
     }
     getDebugSnapshot(): unknown {
         let screen = '';

package/src/providers/spec/fsm-driver.ts

@@ -752,7 +752,20 @@ export class FsmDriver implements ISpecDriver {
         switch (a.type) {
             case 'send_keys': this.adapter.send_keys(a.keys); return;
             case 'open_picker':
-                this.adapter.send_keys(a.trigger_keys);
+                // Some TUIs (e.g. codex) don't register a slash command if its
+                // text and the submitting Enter arrive in the same write — the
+                // composer needs a beat to recognise the command before the CR.
+                // Split a trailing CR/LF off the trigger and send it after a
+                // short delay, mirroring send_message's delay_ms_before_submit.
+                {
+                    const m = /^([\s\S]*?)([\r\n]+)$/.exec(a.trigger_keys);
+                    if (m && m[1]) {
+                        this.adapter.send_keys(m[1]);
+                        setTimeout(() => this.adapter.send_keys(m[2]), 200);
+                    } else {
+                        this.adapter.send_keys(a.trigger_keys);
+                    }
+                }
                 this.pickerInProgress = { control_id: ctl.id, spec: ctl };
                 return;
             case 'attach_image': {

package/src/providers/spec/native-history-executor.ts

@@ -26,6 +26,7 @@ import type {
     NativeHistoryJsonlSource,
     NativeHistoryMessageMap,
     NativeHistorySqliteSource,
+    NativeHistoryToolMap,
 } from './types.js';
 
 export interface NativeHistoryInput {
@@ -163,8 +164,7 @@ function executeJsonl(src: NativeHistoryJsonlSource, input: NativeHistoryInput):
     for (let i = 0; i < lines.length; i += 1) {
         const rec = lines[i];
         if (filter && !filter(rec)) continue;
-        const msg = projectMessage(rec, src.message_map, i, lines.length, mtime);
-        if (msg) {
+        for (const msg of projectMessages(rec, src.message_map, i, lines.length, mtime)) {
             if (transcriptWorkspace) msg.workspace = transcriptWorkspace;
             messages.push(msg);
         }
@@ -256,8 +256,9 @@ function executeSqlite(src: NativeHistorySqliteSource, input: NativeHistoryInput
         const mtime = safeMtimeMs(resolved);
         const messages: NativeHistoryMessage[] = [];
         for (let i = 0; i < messageRows.length; i += 1) {
-            const msg = projectMessage(messageRows[i], src.message_map, i, messageRows.length, mtime);
-            if (msg) messages.push(msg);
+            for (const msg of projectMessages(messageRows[i], src.message_map, i, messageRows.length, mtime)) {
+                messages.push(msg);
+            }
         }
         if (messages.length === 0) return null;
 
@@ -749,11 +750,75 @@ function jsonPathGet(record: any, expr: string): unknown {
     return cur;
 }
 
-function projectMessage(record: any, map: NativeHistoryMessageMap, index: number, total: number, sourceMtimeMs: number): NativeHistoryMessage | null {
+/**
+ * Project one on-disk record into zero or more transcript messages.
+ *
+ * A record yields at most one text bubble (the prose turn) plus — when the
+ * spec declares `message_map.tools` — one `kind:'tool'` bubble per tool-call
+ * or tool-result content block. Without `tools`, behaviour is identical to
+ * the old single-message projection: text-only, tool blocks dropped.
+ */
+function projectMessages(record: any, map: NativeHistoryMessageMap, index: number, total: number, sourceMtimeMs: number): NativeHistoryMessage[] {
     const roleRaw = jsonPathGet(record, map.role);
-    const contentRaw = jsonPathGet(record, map.content);
     const role = normalizeRole(roleRaw);
-    let content = stringifyContent(contentRaw);
+
+    // Records are passed in chronological order (oldest → newest), so the
+    // last record's receivedAt should be ~sourceMtimeMs (when the file was
+    // last touched) and earlier records should walk backwards. Earlier
+    // version had this inverted, which made the dashboard render bubbles
+    // in reverse order and produce the "chat jumping" effect.
+    let receivedAt = sourceMtimeMs - ((total - 1 - index) * 1000);
+    if (map.timestamp_ms) {
+        const tsRaw = jsonPathGet(record, map.timestamp_ms);
+        const parsed = parseTimestamp(tsRaw);
+        if (parsed != null) receivedAt = parsed;
+    }
+    const kindRaw = map.kind ? jsonPathGet(record, map.kind) : undefined;
+    const kind = typeof kindRaw === 'string' && kindRaw ? kindRaw : 'standard';
+
+    const out: NativeHistoryMessage[] = [];
+
+    // Two transcript shapes carry tool activity:
+    //   - record-level: the whole record IS a tool call/result (codex stores
+    //     each function_call / function_call_output as its own jsonl record).
+    //   - block-nested: tool blocks live inside the message's content array
+    //     (claude stores tool_use / tool_result as content blocks).
+    // When the spec opts into `tools`, try the record itself first; if it's a
+    // tool record we emit only that bubble (it has no prose). Otherwise emit
+    // the text bubble plus a tool bubble per matching content block.
+    if (map.tools) {
+        const recordTool = projectToolBlock(record, role, map.tools);
+        if (recordTool) {
+            out.push({ ...recordTool, receivedAt });
+            return out;
+        }
+    }
+
+    const contentRaw = jsonPathGet(record, map.content);
+    const content = cleanContent(stringifyContent(contentRaw), map);
+    if (content) out.push({ role, content, receivedAt, kind });
+
+    // Block-nested tool bubbles are ordered just after the text bubble of the
+    // same record by nudging receivedAt forward a millisecond per bubble, so a
+    // turn's prose still renders before its tool activity without colliding
+    // with the next record's timestamp.
+    if (map.tools && Array.isArray(contentRaw)) {
+        let nudge = 1;
+        for (const block of contentRaw) {
+            const tool = projectToolBlock(block, role, map.tools);
+            if (tool) {
+                out.push({ ...tool, receivedAt: receivedAt + nudge });
+                nudge += 1;
+            }
+        }
+    }
+
+    return out;
+}
+
+/** Apply content_strip / content_unwrap tag surgery and trim. */
+function cleanContent(input: string, map: NativeHistoryMessageMap): string {
+    let content = input;
     if (content && map.content_strip) {
         for (const tag of map.content_strip) {
             const safeTag = tag.replace(/[.+^${}()|[\]\\]/g, '\\$&');
@@ -769,23 +834,50 @@ function projectMessage(record: any, map: NativeHistoryMessageMap, index: number
             content = content.replace(open, '').replace(close, '');
         }
     }
-    if (content) content = content.trim();
-    if (!content) return null;
+    return content ? content.trim() : '';
+}
 
-    // Records are passed in chronological order (oldest → newest), so the
-    // last record's receivedAt should be ~sourceMtimeMs (when the file was
-    // last touched) and earlier records should walk backwards. Earlier
-    // version had this inverted, which made the dashboard render bubbles
-    // in reverse order and produce the "chat jumping" effect.
-    let receivedAt = sourceMtimeMs - ((total - 1 - index) * 1000);
-    if (map.timestamp_ms) {
-        const tsRaw = jsonPathGet(record, map.timestamp_ms);
-        const parsed = parseTimestamp(tsRaw);
-        if (parsed != null) receivedAt = parsed;
+const DEFAULT_TOOL_CALL_TYPES = ['tool_use', 'function_call', 'custom_tool_call'];
+const DEFAULT_TOOL_RESULT_TYPES = ['tool_result', 'function_call_output', 'custom_tool_call_output'];
+
+/**
+ * Turn a single content block into a `kind:'tool'` message, or null if the
+ * block is not a tool call/result. Field locations come from the spec's
+ * `tools` map with Anthropic-block defaults.
+ *
+ * Both tool calls and tool results render on the assistant side: a tool call
+ * is the agent's action, and a tool result is part of the agent's work, not a
+ * user turn (claude/codex persist results under the user / no role, which would
+ * otherwise misattribute them). Calls render as `↗ {name}: {one-line args}`,
+ * results as `↘ {one-line result}`. The `role` param is accepted for symmetry
+ * but tool bubbles are always assistant.
+ */
+function projectToolBlock(block: any, role: 'user' | 'assistant' | 'system', tmap: NativeHistoryToolMap): NativeHistoryMessage | null {
+    void role;
+    if (block == null || typeof block !== 'object') return null;
+    const typeVal = String(jsonPathGet(block, tmap.block_type || '$.type') ?? '');
+    if (!typeVal) return null;
+    const callTypes = tmap.call_types ?? DEFAULT_TOOL_CALL_TYPES;
+    const resultTypes = tmap.result_types ?? DEFAULT_TOOL_RESULT_TYPES;
+
+    if (callTypes.includes(typeVal)) {
+        const name = String(jsonPathGet(block, tmap.call_name || '$.name') ?? 'tool').trim() || 'tool';
+        const args = oneLine(stringifyContent(jsonPathGet(block, tmap.call_args || '$.input')), 240);
+        const content = args ? `↗ ${name}: ${args}` : `↗ ${name}`;
+        return { role: 'assistant', content, receivedAt: 0, kind: 'tool' };
     }
-    const kindRaw = map.kind ? jsonPathGet(record, map.kind) : undefined;
-    const kind = typeof kindRaw === 'string' && kindRaw ? kindRaw : 'standard';
-    return { role, content, receivedAt, kind };
+    if (resultTypes.includes(typeVal)) {
+        const result = oneLine(stringifyContent(jsonPathGet(block, tmap.result_content || '$.content')), 600);
+        if (!result) return null;
+        return { role: 'assistant', content: `↘ ${result}`, receivedAt: 0, kind: 'tool' };
+    }
+    return null;
+}
+
+/** Collapse whitespace to single spaces and cap length for a tool summary. */
+function oneLine(s: string, max: number): string {
+    const flat = s.replace(/\s+/g, ' ').trim();
+    return flat.length > max ? flat.slice(0, max - 1) + '…' : flat;
 }
 
 /**

package/src/providers/spec/types.ts

@@ -98,6 +98,43 @@ export interface NativeHistoryMessageMap {
     content_unwrap?: string[];
     timestamp_ms?: string;
     kind?: string;
+    /**
+     * Declarative tool-bubble extraction. Without it the executor only emits
+     * the text-bearing parts of each record, so a turn that is purely a tool
+     * call or tool result (no prose) is dropped — the restored transcript
+     * loses every tool interaction. When present, the executor walks each
+     * record's content blocks and emits an extra `kind:'tool'` message for
+     * any block whose `$.type` matches a tool shape.
+     *
+     * Defaults target the Anthropic-style content-block shape that claude-cli
+     * and codex-cli persist (blocks of `{ type: 'tool_use' | 'tool_result',
+     * name, input, content }`); a provider with a different on-disk shape
+     * overrides the field paths. Set `tools: {}` to opt in with the defaults.
+     */
+    tools?: NativeHistoryToolMap;
+}
+
+/**
+ * How to surface tool-call / tool-result blocks as `kind:'tool'` bubbles.
+ * Every field is optional — the defaults read the Anthropic block shape.
+ * Paths are jsonpath-lite evaluated against a single content block (the
+ * element of `$.message.content[]`), not the whole record.
+ */
+export interface NativeHistoryToolMap {
+    /** Path to a block's discriminator. Default `$.type`. */
+    block_type?: string;
+    /** Block-type values that mean "a tool was invoked". Default
+     *  `['tool_use', 'function_call', 'custom_tool_call']`. */
+    call_types?: string[];
+    /** Block-type values that mean "a tool returned". Default
+     *  `['tool_result', 'function_call_output', 'custom_tool_call_output']`. */
+    result_types?: string[];
+    /** Path to the tool name on a call block. Default `$.name`. */
+    call_name?: string;
+    /** Path to the tool arguments on a call block. Default `$.input`. */
+    call_args?: string;
+    /** Path to the result payload on a result block. Default `$.content`. */
+    result_content?: string;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────