@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-actors/dist/lib/schema.js

@@ -0,0 +1,428 @@
+/**
+ * Auto-tools schema helpers
+ * Zones: tool schema, registry args, command-template placeholders
+ * Owns tool argument declarations, placeholder-derived tool schemas, and persisted registry normalization
+ */
+import * as CommandTemplates from "./command-templates.js";
+export function stringSchema(description) {
+    return { description, type: "string" };
+}
+export function typedArgSchema(description, type) {
+    if (!type)
+        return stringSchema(description);
+    switch (type.kind) {
+        case "int":
+            return { description, type: "integer" };
+        case "number":
+            return { description, type: "number" };
+        case "bool":
+            return { description, type: "boolean" };
+        case "array":
+            return { description, items: {}, type: "array" };
+        case "enum":
+            return { description, enum: type.values, type: "string" };
+        case "path":
+        case "string":
+            return stringSchema(description);
+    }
+}
+export function booleanSchema(description) {
+    return { description, type: "boolean" };
+}
+export function nullSchema(description) {
+    return { description, type: "null" };
+}
+export function arraySchema(description) {
+    return { description, items: {}, type: "array" };
+}
+export function unionSchema(anyOf) {
+    return { anyOf };
+}
+export function objectSchema(properties, required = []) {
+    return { additionalProperties: false, properties, required, type: "object" };
+}
+export function looseObjectSchema(description) {
+    return { additionalProperties: true, description, type: "object" };
+}
+function mergeUnique(items) {
+    return [...new Set(items.filter(Boolean))];
+}
+function parseArgType(value) {
+    const source = value?.trim();
+    if (!source)
+        return { kind: "string" };
+    if (source === "string")
+        return { kind: "string" };
+    if (source === "path")
+        return { kind: "path" };
+    if (source === "int")
+        return { kind: "int" };
+    if (source === "number")
+        return { kind: "number" };
+    if (source === "bool")
+        return { kind: "bool" };
+    if (source === "array")
+        return { kind: "array" };
+    const enumMatch = source.match(/^enum\(([^)]*)\)$/);
+    if (enumMatch) {
+        const values = enumMatch[1]
+            .split(",")
+            .map((item) => item.trim())
+            .filter(Boolean);
+        return values.length > 0 ? { kind: "enum", values } : undefined;
+    }
+    return undefined;
+}
+function splitArgDeclarations(value) {
+    const items = [];
+    let depth = 0;
+    let current = "";
+    for (const char of value) {
+        if (char === "(")
+            depth += 1;
+        if (char === ")" && depth > 0)
+            depth -= 1;
+        if (char === "," && depth === 0) {
+            if (current.trim())
+                items.push(current.trim());
+            current = "";
+            continue;
+        }
+        current += char;
+    }
+    if (current.trim())
+        items.push(current.trim());
+    return items;
+}
+function canonicalArgDeclaration(arg, type) {
+    switch (type.kind) {
+        case "string":
+            return arg;
+        case "path":
+        case "int":
+        case "number":
+        case "bool":
+        case "array":
+            return `${arg}:${type.kind}`;
+        case "enum":
+            return `${arg}:enum(${type.values.join(",")})`;
+    }
+}
+export function parseToolArgToken(value) {
+    const separatorIndex = value.indexOf("=");
+    const rawName = separatorIndex === -1 ? value : value.slice(0, separatorIndex);
+    const defaultValue = separatorIndex === -1 ? undefined : value.slice(separatorIndex + 1).trim();
+    const typedMatch = rawName.trim().match(/^([^:\s]+)(?::(.+))?$/);
+    if (!typedMatch) {
+        return {
+            arg: rawName.trim(),
+            defaultValue,
+            declaration: rawName.trim(),
+            type: { kind: "string" },
+        };
+    }
+    const arg = typedMatch[1].trim();
+    const type = parseArgType(typedMatch[2]) ?? { kind: "string" };
+    return {
+        arg,
+        defaultValue,
+        declaration: canonicalArgDeclaration(arg, type),
+        type,
+    };
+}
+function isValidDefault(type, value) {
+    switch (type.kind) {
+        case "int":
+            return /^-?\d+$/.test(value);
+        case "number":
+            return /^-?(?:\d+(?:\.\d+)?|\.\d+)$/.test(value);
+        case "bool":
+            return /^(?:true|false|1|0|yes|no)$/i.test(value);
+        case "enum":
+            return type.values.includes(value);
+        case "path":
+        case "array":
+        case "string":
+            return true;
+    }
+}
+export function parseToolArgDeclarations(value) {
+    return parseToolArgDeclarationList(splitArgDeclarations(value));
+}
+export function parseToolArgDeclarationList(value) {
+    const source = value.map(String);
+    const seen = new Set();
+    const duplicates = new Set();
+    const args = [];
+    const argTypes = {};
+    const declarations = [];
+    const defaults = {};
+    for (const item of source) {
+        const parsed = parseToolArgToken(item);
+        if (!parsed.arg)
+            continue;
+        if (seen.has(parsed.arg))
+            duplicates.add(parsed.arg);
+        seen.add(parsed.arg);
+        args.push(parsed.arg);
+        if (parsed.type.kind !== "string")
+            argTypes[parsed.arg] = parsed.type;
+        declarations.push(parsed.declaration);
+        if (parsed.defaultValue !== undefined) {
+            if (!isValidDefault(parsed.type, parsed.defaultValue)) {
+                return {
+                    args: [],
+                    argTypes: {},
+                    declarations: [],
+                    defaults: {},
+                    error: `Invalid default for ${parsed.arg}:${parsed.type.kind}`,
+                };
+            }
+            defaults[parsed.arg] = parsed.defaultValue;
+        }
+    }
+    if (duplicates.size > 0) {
+        return {
+            args: [],
+            argTypes: {},
+            declarations: [],
+            defaults: {},
+            error: `Duplicate argument name(s): ${[...duplicates].join(", ")}`,
+        };
+    }
+    return { args, argTypes, declarations, defaults };
+}
+export function normalizeStoredToolArgDeclarations(argsValue, defaultsValue) {
+    const provided = argsValue !== undefined || defaultsValue !== undefined;
+    const source = Array.isArray(argsValue)
+        ? argsValue
+        : typeof argsValue === "string"
+            ? splitArgDeclarations(argsValue)
+            : [];
+    const rawDefaults = defaultsValue && typeof defaultsValue === "object"
+        ? defaultsValue
+        : {};
+    const seen = new Set();
+    const args = [];
+    const argTypes = {};
+    const declarations = [];
+    const defaults = {};
+    for (const item of source) {
+        const parsed = parseToolArgToken(String(item).trim());
+        if (!parsed.arg || seen.has(parsed.arg))
+            continue;
+        seen.add(parsed.arg);
+        args.push(parsed.arg);
+        if (parsed.type.kind !== "string")
+            argTypes[parsed.arg] = parsed.type;
+        declarations.push(parsed.declaration);
+        const storedDefault = rawDefaults[parsed.arg];
+        if (typeof storedDefault === "string")
+            defaults[parsed.arg] = storedDefault;
+        else if (parsed.defaultValue !== undefined)
+            defaults[parsed.arg] = parsed.defaultValue;
+    }
+    for (const [key, value] of Object.entries(rawDefaults)) {
+        const arg = key.trim();
+        if (!arg || Object.hasOwn(defaults, arg))
+            continue;
+        defaults[arg] = value === undefined || value === null ? "" : String(value);
+    }
+    const canonicalArgs = argsValue === undefined ? undefined : declarations;
+    const canonicalDefaults = Object.keys(defaults).length > 0 ? defaults : {};
+    const changed = provided &&
+        (JSON.stringify(canonicalArgs ?? []) !== JSON.stringify(argsValue ?? []) ||
+            JSON.stringify(canonicalDefaults) !==
+                JSON.stringify(defaultsValue ?? {}));
+    return { args, argTypes, changed, declarations, defaults, provided };
+}
+export function formatToolArgs(args) {
+    return args.length > 0 ? args.join(", ") : "none";
+}
+function parseTemplatePlaceholderDeclaration(content) {
+    if (content.startsWith("_("))
+        return undefined;
+    const nullish = content.match(/^([A-Za-z_][A-Za-z0-9_-]*)\?\?.*$/);
+    if (nullish)
+        return parseToolArgToken(nullish[1]);
+    const ternary = content.match(/^([A-Za-z_][A-Za-z0-9_-]*)\?[^:]*:.*$/);
+    if (ternary)
+        return parseToolArgToken(`${ternary[1]}:bool=false`);
+    const typedMatch = content.match(/^([A-Za-z_][A-Za-z0-9_-]*)(?::(?:string|path|int|number|bool|array|enum\([^)]*\)))?(?:=([^}]*))?$/);
+    if (!typedMatch)
+        return undefined;
+    const parsed = parseToolArgToken(content);
+    if (!parsed.arg ||
+        CommandTemplates.isCommandTemplateRepeatPlaceholder(parsed.arg))
+        return undefined;
+    return parsed;
+}
+function collectTemplatePlaceholderDeclarations(source, declarations) {
+    for (const match of source.matchAll(/\{([^{}]+)\}/g)) {
+        const parsed = parseTemplatePlaceholderDeclaration(match[1]);
+        if (parsed)
+            declarations.push(parsed);
+    }
+}
+function collectWhenDeclarations(source, declarations) {
+    collectTemplatePlaceholderDeclarations(source, declarations);
+    const bareCondition = source.match(/^!?([A-Za-z_][A-Za-z0-9_-]*)$/);
+    if (bareCondition)
+        declarations.push(parseToolArgToken(`${bareCondition[1]}:bool=false`));
+}
+function collectCommandTemplateConfigDeclarations(config, declarations) {
+    if (typeof config === "string") {
+        collectTemplatePlaceholderDeclarations(config, declarations);
+        return;
+    }
+    if (!config || typeof config !== "object")
+        return;
+    if (Array.isArray(config)) {
+        for (const step of config)
+            collectCommandTemplateConfigDeclarations(step, declarations);
+        return;
+    }
+    if (config.template !== undefined)
+        collectCommandTemplateConfigDeclarations(config.template, declarations);
+    if (config.recover !== undefined)
+        collectCommandTemplateConfigDeclarations(config.recover, declarations);
+    for (const field of [config.timeout, config.delay, config.retry, config.repeat]) {
+        if (typeof field === "string")
+            collectTemplatePlaceholderDeclarations(field, declarations);
+    }
+    if (typeof config.when === "string")
+        collectWhenDeclarations(config.when, declarations);
+}
+function getTemplatePlaceholderDeclarations(config) {
+    const declarations = [];
+    collectCommandTemplateConfigDeclarations(config, declarations);
+    return declarations;
+}
+export function getTemplatePlaceholderNames(config) {
+    return mergeUnique(getTemplatePlaceholderDeclarations(config).map((item) => item.arg));
+}
+function toolArgTypesEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+export function assertCompatibleToolArgTypes(...sources) {
+    const seen = {};
+    for (const source of sources) {
+        for (const [name, type] of Object.entries(source ?? {})) {
+            const previous = seen[name];
+            if (previous && !toolArgTypesEqual(previous, type)) {
+                throw new Error(`Conflicting argument type for ${name}: ${canonicalArgDeclaration(name, previous)} vs ${canonicalArgDeclaration(name, type)}`);
+            }
+            seen[name] = type;
+        }
+    }
+}
+export function getTemplateArgTypes(config) {
+    const argTypes = {};
+    for (const declaration of getTemplatePlaceholderDeclarations(config)) {
+        const previous = argTypes[declaration.arg];
+        if (previous &&
+            declaration.type.kind !== "string" &&
+            !toolArgTypesEqual(previous, declaration.type)) {
+            throw new Error(`Conflicting argument type for ${declaration.arg}: ${canonicalArgDeclaration(declaration.arg, previous)} vs ${declaration.declaration}`);
+        }
+        if (declaration.type.kind !== "string")
+            argTypes[declaration.arg] = declaration.type;
+    }
+    return argTypes;
+}
+export function getExplicitToolArgNames(args) {
+    return mergeUnique((args ?? []).map((item) => parseToolArgToken(String(item)).arg));
+}
+export function getExplicitToolArgDefaults(args) {
+    const declarations = typeof args === "string" ? splitArgDeclarations(args) : (args ?? []);
+    return Object.fromEntries(declarations
+        .map((item) => parseToolArgToken(String(item)))
+        .filter((item) => item.defaultValue !== undefined)
+        .map((item) => [item.arg, item.defaultValue]));
+}
+export function getToolArgNames(config) {
+    const normalizedConfig = CommandTemplates.normalizeCommandTemplateConfig(config);
+    const declaredArgs = Array.isArray(normalizedConfig.args)
+        ? normalizedConfig.args.map((item) => parseToolArgToken(String(item)).arg)
+        : [];
+    return mergeUnique([...declaredArgs, ...getTemplatePlaceholderNames(config)]);
+}
+export function getRequiredToolArgNames(config) {
+    const required = new Set();
+    for (const step of CommandTemplates.expandCommandTemplateConfigs(config)) {
+        const defaults = CommandTemplates.getCommandTemplateDefaults(step);
+        for (const declaration of getTemplatePlaceholderDeclarations(step)) {
+            if (declaration.defaultValue === undefined &&
+                !Object.hasOwn(defaults, declaration.arg))
+                required.add(declaration.arg);
+        }
+    }
+    return required;
+}
+function normalizeTypedArgValue(name, type, value) {
+    if (value === undefined || value === null)
+        return "";
+    switch (type.kind) {
+        case "int": {
+            if (typeof value === "number" && Number.isInteger(value))
+                return String(value);
+            if (typeof value === "string" && /^-?\d+$/.test(value.trim()))
+                return value.trim();
+            throw new Error(`Argument ${name} must be an integer.`);
+        }
+        case "number": {
+            if (typeof value === "number" && Number.isFinite(value))
+                return String(value);
+            if (typeof value === "string" &&
+                /^-?(?:\d+(?:\.\d+)?|\.\d+)$/.test(value.trim()))
+                return value.trim();
+            throw new Error(`Argument ${name} must be a number.`);
+        }
+        case "bool": {
+            if (typeof value === "boolean")
+                return value ? "true" : "false";
+            if (typeof value === "string") {
+                const normalized = value.trim().toLowerCase();
+                if (["true", "1", "yes"].includes(normalized))
+                    return "true";
+                if (["false", "0", "no"].includes(normalized))
+                    return "false";
+            }
+            throw new Error(`Argument ${name} must be a boolean.`);
+        }
+        case "enum": {
+            const normalized = String(value);
+            if (type.values.includes(normalized))
+                return normalized;
+            throw new Error(`Argument ${name} must be one of: ${type.values.join(", ")}.`);
+        }
+        case "array": {
+            if (Array.isArray(value))
+                return value;
+            if (typeof value === "string") {
+                try {
+                    const parsed = JSON.parse(value);
+                    if (Array.isArray(parsed))
+                        return parsed;
+                }
+                catch {
+                    // Fall through to error.
+                }
+            }
+            throw new Error(`Argument ${name} must be an array.`);
+        }
+        case "path":
+        case "string":
+            return String(value);
+    }
+}
+export function normalizeRuntimeValues(values, argTypes) {
+    if (!argTypes || Object.keys(argTypes).length === 0)
+        return values;
+    const normalized = { ...values };
+    for (const [name, type] of Object.entries(argTypes)) {
+        if (Object.hasOwn(normalized, name))
+            normalized[name] = normalizeTypedArgValue(name, type, normalized[name]);
+    }
+    return normalized;
+}

package/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/dist/lib/state-readers.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Resilient state readers.
+ * Zones: file-backed actor state, JSON/JSONL diagnostics, inspect safety
+ * Owns best-effort JSON and JSONL parsing helpers for operator-facing state reads.
+ */
+export interface StateReadDiagnostic {
+    line?: number;
+    message: string;
+    path: string;
+}
+export interface JsonReadResult<T> {
+    diagnostics: StateReadDiagnostic[];
+    value: T;
+}
+export interface JsonlReadResult<T> {
+    diagnostics: StateReadDiagnostic[];
+    records: T[];
+}
+export declare function readJsonFileResilient<T>(path: string, fallback: T): JsonReadResult<T>;
+export declare function readJsonlFileResilient<T>(path: string): JsonlReadResult<T>;
+export declare function formatStateReadDiagnostics(diagnostics: StateReadDiagnostic[], limit?: number): string[];