@llblab/pi-actors 0.40.1 → 0.41.0

package/dist/lib/inspector.d.ts

@@ -3,6 +3,7 @@
  * Zones: terminal run inspection, room/direct message previews, no-dependency UI formatting
  * Owns read-only previews and TUI-ready summaries; actor routing stays outside.
  */
+import * as SessionEvidence from "./session-evidence.ts";
 export interface ActorInspectorPreview {
     body_preview?: string;
     branch?: string;
@@ -45,47 +46,30 @@ export interface ActorInspectorPreviewReadOptions {
     ownerId?: string;
     branch?: string;
     currentRunOnly?: boolean;
+    run?: string;
     channels?: ActorInspectorPreview["channel"][];
     mention?: string;
     readKeys?: Iterable<string>;
     roomLimitPerRun?: number;
     unreadOnly?: boolean;
 }
-export interface ActorInspectorControllerState {
-    branch?: string;
-    channels?: ActorInspectorPreview["channel"][];
-    mention?: string;
-    readKeys: Set<string>;
-    roomLimitPerRun: number;
-    rows: number;
-    selectedSequence?: number;
-    unreadOnly: boolean;
-    visible: boolean;
+export interface ActorInspectorRunItem {
+    run: string;
+    status: string;
+    updatedAt?: string;
 }
-export interface ActorInspectorCommandResult {
-    notify: string;
-    type: "info" | "warning";
-    update: boolean;
+export declare function readActorInspectorRuns(stateRoot: string, ownerId: string): ActorInspectorRunItem[];
+export interface ActorInspectorTurnItem extends SessionEvidence.SessionEvidenceTurn {
+    commandId: string;
+    diagnostics: string[];
+    promptBytes?: number;
+    promptFile?: string;
+    recipeContext?: unknown;
+    sessionFile: string;
+    sessionTruncated: boolean;
+    stage?: string;
 }
-export declare const DEFAULT_ACTOR_INSPECTOR_ROWS = 12;
-export declare const ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS: {
-    filter: string;
-    inspect: string;
-    toggle: string;
-};
-export declare function createActorInspectorControllerState(): ActorInspectorControllerState;
-export declare function getActorInspectorPreviewOptions(state: ActorInspectorControllerState, ownerId: string): ActorInspectorPreviewReadOptions;
-export declare function handleActorInspectorToggle(state: ActorInspectorControllerState, args: unknown): ActorInspectorCommandResult;
-export declare function handleActorInspectorFilter(state: ActorInspectorControllerState, args: unknown): ActorInspectorCommandResult;
-export declare function handleActorInspectorInspect(state: ActorInspectorControllerState, args: unknown, previews: ActorInspectorPreview[]): ActorInspectorCommandResult;
-export declare function selectActorInspectorSequence(state: ActorInspectorControllerState, sequence: number, previews: ActorInspectorPreview[]): ActorInspectorCommandResult;
-export declare function renderActorInspectorPanel(input: {
-    stateRoot: string;
-    state: ActorInspectorControllerState;
-    ownerId: string;
-    width: number;
-    style: ActorInspectorWidgetStyle;
-}): string[];
+export declare function readActorInspectorTurns(stateDir: string): ActorInspectorTurnItem[];
 export declare function inspectorPreviewReadKey(preview: ActorInspectorPreview): string;
 export declare function readActorInspectorPreviews(stateRoot?: string, limit?: number, options?: ActorInspectorPreviewReadOptions): ActorInspectorPreview[];
 export declare function readActorInspectorRoster(stateRoot: string | undefined, run: string, room?: string): ActorInspectorRosterMember[];

package/dist/lib/inspector.js

@@ -8,164 +8,108 @@ import * as path from "node:path";
 import { visibleWidth } from "@earendil-works/pi-tui";
 import * as Limits from "./limits.js";
 import * as Paths from "./paths.js";
+import * as SessionEvidence from "./session-evidence.js";
 import { readJsonFileResilient, readJsonlFileResilient, } from "./state-readers.js";
-export const DEFAULT_ACTOR_INSPECTOR_ROWS = 12;
-export const ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS = {
-    filter: "Filter actor inspector rows: all, room, direct, broadcast, unread, branch <name>, mention <text>",
-    inspect: "Inspect actor message by visible number",
-    toggle: "Toggle actor inspector widget; optional row count",
-};
-export function createActorInspectorControllerState() {
-    return {
-        readKeys: new Set(),
-        roomLimitPerRun: DEFAULT_ACTOR_INSPECTOR_ROWS,
-        rows: DEFAULT_ACTOR_INSPECTOR_ROWS,
-        unreadOnly: false,
-        visible: false,
-    };
-}
-export function getActorInspectorPreviewOptions(state, ownerId) {
-    return {
-        channels: state.channels,
-        currentRunOnly: true,
-        branch: state.branch,
-        mention: state.mention,
-        ownerId,
-        readKeys: state.readKeys,
-        roomLimitPerRun: state.roomLimitPerRun,
-        unreadOnly: state.unreadOnly,
-    };
-}
-export function handleActorInspectorToggle(state, args) {
-    const raw = Array.isArray(args) ? args[0] : String(args ?? "");
-    if (String(raw).trim()) {
-        const rows = Number.parseInt(String(raw), 10);
-        if (!Number.isFinite(rows) || rows <= 0) {
-            return {
-                notify: "Usage: /actors-inspector-toggle [rows] where rows > 0",
-                type: "warning",
-                update: false,
-            };
-        }
-        state.rows = rows;
-        state.roomLimitPerRun = rows;
-        state.selectedSequence = undefined;
-        state.visible = true;
-        return {
-            notify: `Actor inspector rows ${rows}`,
-            type: "info",
-            update: true,
-        };
-    }
-    if (state.selectedSequence !== undefined) {
-        state.selectedSequence = undefined;
-        state.visible = true;
-        return { notify: "Actor inspector table", type: "info", update: true };
+export function readActorInspectorRuns(stateRoot, ownerId) {
+    try {
+        return fs
+            .readdirSync(stateRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .flatMap((entry) => {
+            const stateDir = path.join(stateRoot, entry.name);
+            if (!matchesOwner(stateDir, ownerId))
+                return [];
+            const progress = readJsonFileResilient(path.join(stateDir, "progress.json"), {}).value;
+            const result = readJsonFileResilient(path.join(stateDir, "result.json"), {}).value;
+            return [{
+                    run: entry.name,
+                    status: String(progress.phase ?? (Object.keys(result).length ? "terminal" : "unknown")),
+                    ...(typeof progress.updatedAt === "string"
+                        ? { updatedAt: progress.updatedAt }
+                        : typeof result.completedAt === "string"
+                            ? { updatedAt: result.completedAt }
+                            : {}),
+                }];
+        })
+            .sort((left, right) => String(left.updatedAt ?? "").localeCompare(String(right.updatedAt ?? "")));
     }
-    if (state.visible)
-        state.visible = false;
-    else {
-        state.rows = DEFAULT_ACTOR_INSPECTOR_ROWS;
-        state.roomLimitPerRun = DEFAULT_ACTOR_INSPECTOR_ROWS;
-        state.visible = true;
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        return [];
     }
-    return {
-        notify: `Actor inspector ${state.visible ? "shown" : "hidden"}`,
-        type: "info",
-        update: true,
-    };
 }
-export function handleActorInspectorFilter(state, args) {
-    const parts = Array.isArray(args)
-        ? args.map(String)
-        : String(args ?? "").split(/\s+/);
-    const mode = (parts[0] ?? "").trim().toLowerCase();
-    if (!mode || mode === "all" || mode === "clear") {
-        state.channels = undefined;
-        state.mention = undefined;
-        state.branch = undefined;
-        state.unreadOnly = false;
-    }
-    else if (mode === "room" || mode === "direct" || mode === "broadcast") {
-        state.channels = [mode];
-        state.mention = undefined;
-    }
-    else if (mode === "unread") {
-        state.unreadOnly = true;
-    }
-    else if (mode === "branch" || mode === "current-branch") {
-        const branch = parts.slice(1).join(" ").trim();
-        if (!branch) {
-            return {
-                notify: `Usage: /actors-inspector-filter ${mode} <branch-name>`,
-                type: "warning",
-                update: false,
-            };
-        }
-        state.branch = branch;
-    }
-    else if (mode === "mention") {
-        const mention = parts.slice(1).join(" ").trim();
-        if (!mention) {
-            return {
-                notify: "Usage: /actors-inspector-filter mention <text>",
-                type: "warning",
-                update: false,
-            };
-        }
-        state.channels = undefined;
-        state.mention = mention;
+function ownedSessionPath(stateDir, sessionFile) {
+    if (path.isAbsolute(sessionFile))
+        return undefined;
+    const sessionsRoot = path.resolve(stateDir, "sessions");
+    const resolved = path.resolve(stateDir, sessionFile);
+    if (!resolved.startsWith(`${sessionsRoot}${path.sep}`))
+        return undefined;
+    try {
+        const canonicalRoot = fs.realpathSync(sessionsRoot);
+        const canonicalFile = fs.realpathSync(resolved);
+        return canonicalFile.startsWith(`${canonicalRoot}${path.sep}`)
+            ? canonicalFile
+            : undefined;
     }
-    else {
-        return {
-            notify: "Usage: /actors-inspector-filter all|room|direct|broadcast|unread|branch <name>|mention <text>",
-            type: "warning",
-            update: false,
-        };
+    catch {
+        return undefined;
     }
-    state.selectedSequence = undefined;
-    state.visible = true;
-    return {
-        notify: `Actor inspector filter ${mode || "all"}`,
-        type: "info",
-        update: true,
-    };
 }
-export function handleActorInspectorInspect(state, args, previews) {
-    const raw = Array.isArray(args) ? args[0] : String(args ?? "");
-    return selectActorInspectorSequence(state, Number.parseInt(String(raw), 10), previews);
-}
-export function selectActorInspectorSequence(state, sequence, previews) {
-    if (!Number.isFinite(sequence) || sequence <= 0) {
-        return {
-            notify: "Usage: /actors-inspect <number>",
-            type: "warning",
-            update: false,
-        };
+export function readActorInspectorTurns(stateDir) {
+    const evidence = readJsonFileResilient(path.join(stateDir, "review-evidence.json"), {}).value;
+    const commands = Array.isArray(evidence.commands)
+        ? evidence.commands
+        : [];
+    const recordedFiles = new Set(commands.flatMap((command) => (Array.isArray(command.session_files) ? command.session_files : []).filter((file) => typeof file === "string")));
+    let discoveredCommands = [];
+    try {
+        const sessionsDir = path.join(stateDir, "sessions");
+        discoveredCommands = fs
+            .readdirSync(sessionsDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .flatMap((entry) => {
+            const files = fs
+                .readdirSync(path.join(sessionsDir, entry.name), {
+                withFileTypes: true,
+            })
+                .filter((file) => file.isFile() && file.name.endsWith(".jsonl"))
+                .map((file) => path.join("sessions", entry.name, file.name))
+                .filter((file) => !recordedFiles.has(file));
+            return files.length > 0
+                ? [{ id: entry.name, session_files: files, stage: "subagent" }]
+                : [];
+        });
     }
-    const preview = previews.find((item) => item.sequence === sequence);
-    if (preview)
-        state.readKeys.add(inspectorPreviewReadKey(preview));
-    state.selectedSequence = sequence;
-    state.visible = true;
-    return {
-        notify: `Actor inspect item ${sequence}`,
-        type: "info",
-        update: true,
-    };
-}
-export function renderActorInspectorPanel(input) {
-    const previews = readActorInspectorPreviews(input.stateRoot, input.state.rows, getActorInspectorPreviewOptions(input.state, input.ownerId));
-    const rows = (input.state.selectedSequence !== undefined
-        ? renderInspectorItemView(previews, input.width, input.style, {
-            sequence: input.state.selectedSequence,
-        })
-        : renderInspectorWidget(previews, input.width, input.style)) ?? [];
-    const run = previews[0]?.run;
-    const roster = input.state.selectedSequence === undefined && run
-        ? renderInspectorRosterPanel(readActorInspectorRoster(input.stateRoot, run), input.width, input.style)
-        : undefined;
-    return roster ? [...roster, ...rows] : rows;
+    catch {
+        discoveredCommands = [];
+    }
+    return [...commands, ...discoveredCommands].flatMap((command) => (Array.isArray(command.session_files) ? command.session_files : [])
+        .filter((file) => typeof file === "string")
+        .flatMap((file) => {
+        const sessionPath = ownedSessionPath(stateDir, file);
+        if (!sessionPath)
+            return [];
+        const session = SessionEvidence.readSessionEvidence(sessionPath);
+        return session.turns.map((turn) => ({
+            ...turn,
+            commandId: String(command.id ?? "unknown"),
+            diagnostics: session.diagnostics.map((item) => `${item.line === undefined ? "" : `line ${item.line}: `}${item.message}`),
+            ...(typeof command.prompt_bytes === "number"
+                ? { promptBytes: command.prompt_bytes }
+                : {}),
+            ...(typeof command.prompt_file === "string"
+                ? { promptFile: command.prompt_file }
+                : {}),
+            ...(command.recipe_context !== undefined
+                ? { recipeContext: command.recipe_context }
+                : {}),
+            sessionFile: file,
+            sessionTruncated: session.truncated,
+            ...(typeof command.stage === "string" ? { stage: command.stage } : {}),
+        }));
+    })).map((turn, index) => ({ ...turn, index: index + 1 }));
 }
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
@@ -178,7 +122,8 @@ function readJsonLines(file) {
 function previewValue(value, maxLength = Limits.INSPECTOR_BODY_PREVIEW_CHARS) {
     if (value === undefined)
         return undefined;
-    const text = typeof value === "string" ? value : JSON.stringify(value);
+    const redacted = SessionEvidence.redactSessionEvidenceValue(value);
+    const text = typeof redacted === "string" ? redacted : JSON.stringify(redacted);
     const compact = text.replaceAll(/\s+/g, " ").trim();
     if (!compact)
         return undefined;
@@ -393,6 +338,8 @@ export function readActorInspectorPreviews(stateRoot = Paths.getRunStateRoot(),
             const stateDir = path.join(stateRoot, entry.name);
             if (!matchesOwner(stateDir, options.ownerId))
                 return [];
+            if (options.run && entry.name !== options.run)
+                return [];
             return [
                 ...readRoomPreviews(entry.name, stateDir),
                 ...readInboxPreviews(entry.name, stateDir),

package/dist/lib/limits.d.ts

@@ -9,3 +9,6 @@ export declare const COMPACT_PREVIEW_CHARS = 160;
 export declare const INSPECTOR_BODY_PREVIEW_CHARS = 320;
 export declare const ROOM_MESSAGE_PREVIEW_CHARS = 320;
 export declare const DOCTOR_ACTION_PREVIEW_CHARS = 72;
+export declare const SESSION_EVIDENCE_MAX_TURNS = 100;
+export declare const SESSION_EVIDENCE_TEXT_CHARS = 4000;
+export declare const SESSION_EVIDENCE_MAX_TOOL_CALLS = 100;

package/dist/lib/limits.js

@@ -9,3 +9,6 @@ export const COMPACT_PREVIEW_CHARS = 160;
 export const INSPECTOR_BODY_PREVIEW_CHARS = 320;
 export const ROOM_MESSAGE_PREVIEW_CHARS = 320;
 export const DOCTOR_ACTION_PREVIEW_CHARS = 72;
+export const SESSION_EVIDENCE_MAX_TURNS = 100;
+export const SESSION_EVIDENCE_TEXT_CHARS = 4_000;
+export const SESSION_EVIDENCE_MAX_TOOL_CALLS = 100;

package/dist/lib/recipes-context.d.ts

@@ -14,6 +14,11 @@ export declare function markRecipeContextRecords(records: TemplateRecipeContextR
 export declare function formatRecipeContextJsonl(records: TemplateRecipeContextRecord[], context?: CommandTemplateActorRecipeContext): string;
 export declare function buildRecipeContextPromptBlock(records: TemplateRecipeContextRecord[], context?: CommandTemplateActorRecipeContext): string;
 export declare function appendRecipeContextToPiArgs(command: string, args: string[], records: TemplateRecipeContextRecord[] | undefined, context?: CommandTemplateActorRecipeContext): string[];
+export interface ManagedPiSessionArgs {
+    args: string[];
+    sessionDir?: string;
+}
+export declare function attachPiSessionDir(command: string, args: string[], sessionDir: string): ManagedPiSessionArgs;
 export interface MaterializedPiPrintPromptArgs {
     args: string[];
     promptBytes?: number;

package/dist/lib/recipes-context.js

@@ -134,6 +134,21 @@ export function appendRecipeContextToPiArgs(command, args, records, context) {
     next[promptIndex] = `${next[promptIndex]}\n\n${block}`;
     return next;
 }
+const PI_SESSION_POLICY_FLAGS = new Set([
+    "--fork",
+    "--no-session",
+    "--session",
+    "--session-dir",
+    "--session-id",
+]);
+export function attachPiSessionDir(command, args, sessionDir) {
+    if (!isPiCommand(command) || findPiPrintPromptIndex(args) === undefined) {
+        return { args };
+    }
+    if (args.some((arg) => PI_SESSION_POLICY_FLAGS.has(arg)))
+        return { args };
+    return { args: ["--session-dir", sessionDir, ...args], sessionDir };
+}
 export function materializePiPrintPromptArg(command, args, promptFile) {
     if (!isPiCommand(command))
         return { args };

package/dist/lib/session-evidence.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Persisted Pi session evidence reader.
+ * Zones: subagent turns, active session branches, bounded/redacted previews
+ * Owns read-only normalization of session JSONL into inspector-ready turns.
+ */
+import { type StateReadDiagnostic } from "./state-readers.ts";
+export interface SessionEvidenceToolCall {
+    arguments?: unknown;
+    id: string;
+    name: string;
+    result?: unknown;
+    resultError?: boolean;
+}
+export interface SessionEvidenceTurn {
+    assistantEntryId?: string;
+    assistantText?: string;
+    error?: string;
+    index: number;
+    model?: string;
+    provider?: string;
+    stopReason?: string;
+    thinking?: string;
+    timestamp?: string;
+    toolCalls: SessionEvidenceToolCall[];
+    unmatchedToolResults: number;
+    usage?: unknown;
+    userEntryId?: string;
+    userText?: string;
+}
+export interface SessionEvidence {
+    activeLeafId?: string;
+    diagnostics: StateReadDiagnostic[];
+    path: string;
+    session?: Record<string, unknown>;
+    totalTurns: number;
+    truncated: boolean;
+    turns: SessionEvidenceTurn[];
+}
+export interface SessionEvidenceReadOptions {
+    maxTextChars?: number;
+    maxToolCalls?: number;
+    maxTurns?: number;
+}
+export declare function redactSessionEvidenceValue(value: unknown, maxTextChars?: number, seen?: WeakSet<object>): unknown;
+export declare function readSessionEvidence(path: string, options?: SessionEvidenceReadOptions): SessionEvidence;

package/dist/lib/session-evidence.js

@@ -0,0 +1,204 @@
+/**
+ * Persisted Pi session evidence reader.
+ * Zones: subagent turns, active session branches, bounded/redacted previews
+ * Owns read-only normalization of session JSONL into inspector-ready turns.
+ */
+import * as Limits from "./limits.js";
+import { readJsonlFileResilient, } from "./state-readers.js";
+const SENSITIVE_KEY = /(?:^|[_-])(?:api[-_]?key|authorization|cookie|credential|password|private[-_]?key|secret|secret[-_]?access[-_]?key|token)$|^(?:access|refresh|auth|api)Token$|^(?:clientSecret|privateKey|secretAccessKey)$/i;
+const SENSITIVE_TEXT = /(bearer\s+)[A-Za-z0-9._~+/=-]+|["']?\b(api[-_]?key|authorization|clientSecret|cookie|password|private[-_]?key|privateKey|secret|secretAccessKey|token)["']?(\s*[:=]\s*)["']?([^\s,;"'}]+)/gi;
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function boundedText(value, maxChars) {
+    if (typeof value !== "string")
+        return undefined;
+    if (/^\s*[\[{]/.test(value)) {
+        try {
+            const structured = JSON.stringify(redactSessionEvidenceValue(JSON.parse(value), maxChars));
+            return structured.length > maxChars
+                ? `${structured.slice(0, Math.max(0, maxChars - 1))}…`
+                : structured;
+        }
+        catch {
+            // Fall through to bounded text redaction.
+        }
+    }
+    const redacted = value.replaceAll(SENSITIVE_TEXT, (match, bearer, key, separator) => bearer ? `${bearer}[REDACTED]` : `${key}${separator}[REDACTED]`);
+    return redacted.length > maxChars
+        ? `${redacted.slice(0, Math.max(0, maxChars - 1))}…`
+        : redacted;
+}
+export function redactSessionEvidenceValue(value, maxTextChars = Limits.SESSION_EVIDENCE_TEXT_CHARS, seen = new WeakSet()) {
+    if (typeof value === "string")
+        return boundedText(value, maxTextChars);
+    if (!value || typeof value !== "object")
+        return value;
+    if (seen.has(value))
+        return "[CIRCULAR]";
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => redactSessionEvidenceValue(item, maxTextChars, seen));
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        key,
+        SENSITIVE_KEY.test(key)
+            ? "[REDACTED]"
+            : redactSessionEvidenceValue(item, maxTextChars, seen),
+    ]));
+}
+function contentBlocks(message) {
+    return Array.isArray(message.content)
+        ? message.content.map(asRecord)
+        : typeof message.content === "string"
+            ? [{ type: "text", text: message.content }]
+            : [];
+}
+function contentText(message, type, maxChars) {
+    const text = contentBlocks(message)
+        .filter((block) => block.type === type && typeof block[type] === "string")
+        .map((block) => String(block[type]))
+        .join("\n");
+    return boundedText(text, maxChars);
+}
+function activeBranch(entries, path, diagnostics) {
+    const treeEntries = entries.filter((entry) => entry.type !== "session" && typeof entry.id === "string");
+    const leaf = treeEntries.at(-1);
+    if (!leaf || typeof leaf.id !== "string")
+        return [];
+    const byId = new Map(treeEntries.map((entry) => [String(entry.id), entry]));
+    const branch = [];
+    const visited = new Set();
+    let current = leaf;
+    while (current && typeof current.id === "string") {
+        if (visited.has(current.id)) {
+            diagnostics.push({ message: `session entry cycle at ${current.id}`, path });
+            break;
+        }
+        visited.add(current.id);
+        branch.push(current);
+        if (current.parentId === null || current.parentId === undefined)
+            break;
+        if (typeof current.parentId !== "string" || !byId.has(current.parentId)) {
+            diagnostics.push({
+                message: `missing parent ${String(current.parentId)} for ${current.id}`,
+                path,
+            });
+            break;
+        }
+        current = byId.get(current.parentId);
+    }
+    return branch.reverse();
+}
+function toolCalls(message, maxTextChars, maxToolCalls) {
+    return contentBlocks(message)
+        .filter((block) => block.type === "toolCall" &&
+        typeof block.id === "string" &&
+        typeof block.name === "string")
+        .slice(0, maxToolCalls)
+        .map((block) => ({
+        arguments: redactSessionEvidenceValue(block.arguments, maxTextChars),
+        id: String(block.id),
+        name: String(block.name),
+    }));
+}
+export function readSessionEvidence(path, options = {}) {
+    const maxTextChars = Math.max(1, options.maxTextChars ?? Limits.SESSION_EVIDENCE_TEXT_CHARS);
+    const maxToolCalls = Math.max(1, options.maxToolCalls ?? Limits.SESSION_EVIDENCE_MAX_TOOL_CALLS);
+    const maxTurns = Math.max(1, options.maxTurns ?? Limits.SESSION_EVIDENCE_MAX_TURNS);
+    const read = readJsonlFileResilient(path);
+    const diagnostics = [...read.diagnostics];
+    const header = read.records.find((entry) => entry.type === "session");
+    const branch = activeBranch(read.records, path, diagnostics);
+    const turns = [];
+    let pendingUser;
+    let currentTurn;
+    for (const entry of branch) {
+        if (entry.type !== "message")
+            continue;
+        const message = asRecord(entry.message);
+        const role = message.role;
+        if (role === "user") {
+            pendingUser = {
+                id: String(entry.id),
+                text: contentText(message, "text", maxTextChars),
+            };
+            currentTurn = undefined;
+            continue;
+        }
+        if (role === "assistant") {
+            currentTurn = {
+                ...(typeof entry.id === "string" ? { assistantEntryId: entry.id } : {}),
+                ...(contentText(message, "text", maxTextChars)
+                    ? { assistantText: contentText(message, "text", maxTextChars) }
+                    : {}),
+                ...(typeof message.errorMessage === "string"
+                    ? { error: boundedText(message.errorMessage, maxTextChars) }
+                    : {}),
+                index: turns.length + 1,
+                ...(typeof message.model === "string" ? { model: message.model } : {}),
+                ...(typeof message.provider === "string"
+                    ? { provider: message.provider }
+                    : {}),
+                ...(typeof message.stopReason === "string"
+                    ? { stopReason: message.stopReason }
+                    : {}),
+                ...(contentText(message, "thinking", maxTextChars)
+                    ? { thinking: contentText(message, "thinking", maxTextChars) }
+                    : {}),
+                ...(typeof entry.timestamp === "string"
+                    ? { timestamp: entry.timestamp }
+                    : {}),
+                toolCalls: toolCalls(message, maxTextChars, maxToolCalls),
+                unmatchedToolResults: 0,
+                ...(message.usage !== undefined
+                    ? { usage: redactSessionEvidenceValue(message.usage, maxTextChars) }
+                    : {}),
+                ...(pendingUser
+                    ? {
+                        userEntryId: pendingUser.id,
+                        ...(pendingUser.text ? { userText: pendingUser.text } : {}),
+                    }
+                    : {}),
+            };
+            pendingUser = undefined;
+            turns.push(currentTurn);
+            continue;
+        }
+        if (role === "toolResult" && currentTurn) {
+            const callId = typeof message.toolCallId === "string" ? message.toolCallId : "";
+            const call = currentTurn.toolCalls.find((item) => item.id === callId);
+            if (!call) {
+                currentTurn.unmatchedToolResults += 1;
+                continue;
+            }
+            call.result = redactSessionEvidenceValue(message.content, maxTextChars);
+            call.resultError = message.isError === true;
+        }
+    }
+    if (pendingUser) {
+        turns.push({
+            index: turns.length + 1,
+            toolCalls: [],
+            unmatchedToolResults: 0,
+            userEntryId: pendingUser.id,
+            ...(pendingUser.text ? { userText: pendingUser.text } : {}),
+        });
+    }
+    const firstVisibleIndex = Math.max(0, turns.length - maxTurns);
+    const visibleTurns = turns.slice(firstVisibleIndex).map((turn, index) => ({
+        ...turn,
+        index: firstVisibleIndex + index + 1,
+    }));
+    return {
+        ...(branch.at(-1)?.id ? { activeLeafId: String(branch.at(-1)?.id) } : {}),
+        diagnostics,
+        path,
+        ...(header ? { session: asRecord(header) } : {}),
+        totalTurns: turns.length,
+        truncated: turns.length > visibleTurns.length,
+        turns: visibleTurns,
+    };
+}

package/dist/lib/tools-response.d.ts

@@ -3,6 +3,9 @@
  * Zones: compact text summaries, verbose JSON switching, next-action rendering
  * Owns model-facing response helpers shared by public tool execution paths
  */
+export declare function withLeadingBlankLine(text: string): string;
+export declare function spaceToolResult<T>(result: T): T;
+export declare function spaceToolError(error: unknown): unknown;
 export declare function asRecord(value: unknown): Record<string, unknown>;
 export declare function jsonText(value: unknown): string;
 export declare function compactPreview(value: unknown, maxLength?: number): string | undefined;