@llblab/pi-kit 0.38.4 → 0.39.0

package/node_modules/@llblab/pi-actors/dist/lib/session-evidence.d.ts

@@ -4,6 +4,14 @@
  * Owns read-only normalization of session JSONL into inspector-ready turns.
  */
 import { type StateReadDiagnostic } from "./state-readers.ts";
+interface SessionEntry {
+    id?: unknown;
+    message?: unknown;
+    parentId?: unknown;
+    timestamp?: unknown;
+    type?: unknown;
+    [key: string]: unknown;
+}
 export interface SessionEvidenceToolCall {
     arguments?: unknown;
     id: string;
@@ -11,7 +19,16 @@ export interface SessionEvidenceToolCall {
     result?: unknown;
     resultError?: boolean;
 }
+export declare const SESSION_TURN_IDENTITY: unique symbol;
+interface SessionTurnIdentity {
+    basis: "entry" | "record";
+    entryId?: string;
+    sessionId?: string;
+    role: "assistant" | "user";
+    ordinal?: number;
+}
 export interface SessionEvidenceTurn {
+    [SESSION_TURN_IDENTITY]?: Readonly<SessionTurnIdentity>;
     assistantEntryId?: string;
     assistantText?: string;
     error?: string;
@@ -27,7 +44,24 @@ export interface SessionEvidenceTurn {
     userEntryId?: string;
     userText?: string;
 }
+export declare const SESSION_EVIDENCE_CHRONOLOGY: unique symbol;
+export interface SessionChronologyEntry {
+    ordinal: number;
+    timestamp: string;
+    identity: Readonly<SessionTurnIdentity>;
+}
+export type SessionChronologyReason = "source_unavailable" | "identity_unavailable" | "timestamp_unavailable" | "metadata_too_large";
+export type SessionChronology = Readonly<{
+    basis: "recorded_branch_metadata";
+    entries: readonly Readonly<SessionChronologyEntry>[];
+} & ({
+    state: "available";
+} | {
+    state: "unavailable";
+    reason: SessionChronologyReason;
+})>;
 export interface SessionEvidence {
+    [SESSION_EVIDENCE_CHRONOLOGY]?: SessionChronology;
     activeLeafId?: string;
     diagnostics: StateReadDiagnostic[];
     path: string;
@@ -59,4 +93,7 @@ export interface ActiveSessionEntryEvidenceInput {
 /** Walk only the active parent chain under exact entry and byte ceilings. */
 export declare function inspectBoundedActiveSessionEntries(input: ActiveSessionEntryEvidenceInput): ActiveSessionEntryEvidence;
 export declare function redactSessionEvidenceValue(value: unknown, maxTextChars?: number, seen?: WeakSet<object>): unknown;
+/** Physical last-leaf ancestry, not current model context or a claim about a live SessionManager leaf. */
+export declare function selectLastRecordedSessionBranch(entries: SessionEntry[], path: string, diagnostics: StateReadDiagnostic[]): SessionEntry[];
 export declare function readSessionEvidence(path: string, options?: SessionEvidenceReadOptions): SessionEvidence;
+export {};

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

@@ -5,6 +5,9 @@
  */
 import * as Limits from "./limits.js";
 import { readJsonlFileResilient, } from "./state-readers.js";
+// Non-JSON provenance data. The enumerable Symbol survives turn copies; it grants no source/lifecycle authority.
+export const SESSION_TURN_IDENTITY = Symbol("session-turn-identity");
+export const SESSION_EVIDENCE_CHRONOLOGY = Symbol("session-evidence-chronology");
 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;
 function boundedJsonStringBytes(value) {
     let bytes = Buffer.byteLength(value, "utf8") + 2;
@@ -206,7 +209,8 @@ function contentText(message, type, maxChars) {
         .join("\n");
     return boundedText(text, maxChars);
 }
-function activeBranch(entries, path, diagnostics) {
+/** Physical last-leaf ancestry, not current model context or a claim about a live SessionManager leaf. */
+export function selectLastRecordedSessionBranch(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")
@@ -247,6 +251,31 @@ function toolCalls(message, maxTextChars, maxToolCalls) {
         name: String(block.name),
     }));
 }
+function sessionChronology(turns, sourceAvailable) {
+    const basis = "recorded_branch_metadata";
+    const unavailable = (reason) => Object.freeze({
+        state: "unavailable", basis, reason, entries: Object.freeze([]),
+    });
+    if (!sourceAvailable)
+        return unavailable("source_unavailable");
+    const entries = [];
+    let bytes = Buffer.byteLength(JSON.stringify({ state: "available", basis, entries: [] }));
+    for (const turn of turns) {
+        const identity = turn[SESSION_TURN_IDENTITY];
+        if (identity?.basis !== "entry")
+            return unavailable("identity_unavailable");
+        const timestamp = turn.timestamp;
+        if (typeof timestamp !== "string" || timestamp.length !== 24 || !Number.isFinite(Date.parse(timestamp)) ||
+            new Date(timestamp).toISOString() !== timestamp || redactSessionEvidenceValue(timestamp) !== timestamp)
+            return unavailable("timestamp_unavailable");
+        const entry = Object.freeze({ ordinal: turn.index, timestamp, identity });
+        bytes += Buffer.byteLength(JSON.stringify(entry)) + Number(entries.length > 0);
+        if (bytes > Limits.SESSION_EVIDENCE_MAX_BYTES)
+            return unavailable("metadata_too_large");
+        entries.push(entry);
+    }
+    return Object.freeze({ state: "available", basis, entries: Object.freeze(entries) });
+}
 export function readSessionEvidence(path, options = {}) {
     const maxBytes = Math.max(1, options.maxBytes ?? Limits.SESSION_EVIDENCE_MAX_BYTES);
     const maxTextChars = Math.max(1, options.maxTextChars ?? Limits.SESSION_EVIDENCE_TEXT_CHARS);
@@ -255,7 +284,27 @@ export function readSessionEvidence(path, options = {}) {
     const read = readJsonlFileResilient(path, { maxBytes });
     const diagnostics = [...read.diagnostics];
     const header = read.records.find((entry) => entry.type === "session");
-    const branch = activeBranch(read.records, path, diagnostics);
+    const branch = selectLastRecordedSessionBranch(read.records, path, diagnostics);
+    const ordinals = new Map(branch.map(entry => [entry, 0]));
+    const idCounts = new Map(branch.map(entry => [String(entry.id), 0]));
+    let sessionHeaders = 0;
+    for (const [index, entry] of read.records.entries()) {
+        if (entry.type === "session")
+            sessionHeaders++;
+        if (ordinals.has(entry))
+            ordinals.set(entry, index + 1);
+        if (entry.type !== "session" && typeof entry.id === "string" && idCounts.has(entry.id)) {
+            idCounts.set(entry.id, idCounts.get(entry.id) + 1);
+        }
+    }
+    const sessionId = sessionHeaders === 1 && typeof header?.id === "string" && header.id &&
+        redactSessionEvidenceValue(header.id, maxTextChars) === header.id ? header.id : undefined;
+    const identity = (entry, role) => {
+        const entryId = typeof entry.id === "string" ? entry.id : "";
+        const basis = sessionId && entryId && idCounts.get(entryId) === 1 && diagnostics.length === 0 &&
+            redactSessionEvidenceValue(entryId, maxTextChars) === entryId ? "entry" : "record";
+        return Object.freeze({ basis, role, ...(basis === "entry" ? { sessionId, entryId } : { ordinal: ordinals.get(entry) }) });
+    };
     const turns = [];
     let pendingUser;
     let currentTurn;
@@ -267,6 +316,7 @@ export function readSessionEvidence(path, options = {}) {
         if (role === "user") {
             pendingUser = {
                 id: String(entry.id),
+                identity: identity(entry, "user"),
                 text: contentText(message, "text", maxTextChars),
             };
             currentTurn = undefined;
@@ -274,6 +324,7 @@ export function readSessionEvidence(path, options = {}) {
         }
         if (role === "assistant") {
             currentTurn = {
+                [SESSION_TURN_IDENTITY]: identity(entry, "assistant"),
                 ...(typeof entry.id === "string" ? { assistantEntryId: entry.id } : {}),
                 ...(contentText(message, "text", maxTextChars)
                     ? { assistantText: contentText(message, "text", maxTextChars) }
@@ -328,6 +379,7 @@ export function readSessionEvidence(path, options = {}) {
             toolCalls: [],
             unmatchedToolResults: 0,
             userEntryId: pendingUser.id,
+            [SESSION_TURN_IDENTITY]: pendingUser.identity,
             ...(pendingUser.text ? { userText: pendingUser.text } : {}),
         });
     }
@@ -336,7 +388,7 @@ export function readSessionEvidence(path, options = {}) {
         ...turn,
         index: firstVisibleIndex + index + 1,
     }));
-    return {
+    const evidence = {
         ...(branch.at(-1)?.id ? { activeLeafId: String(branch.at(-1)?.id) } : {}),
         diagnostics,
         path,
@@ -345,4 +397,8 @@ export function readSessionEvidence(path, options = {}) {
         truncated: read.truncated === true || turns.length > visibleTurns.length,
         turns: visibleTurns,
     };
+    Object.defineProperty(evidence, SESSION_EVIDENCE_CHRONOLOGY, {
+        value: sessionChronology(turns, sessionId !== undefined && read.truncated !== true && diagnostics.length === 0),
+    });
+    return evidence;
 }

package/node_modules/@llblab/pi-actors/dist/lib/state-readers.d.ts

@@ -20,6 +20,9 @@ export interface JsonlReadResult<T> {
 export interface JsonlReadOptions {
     maxBytes?: number;
 }
-export declare function readJsonFileResilient<T>(path: string, fallback: T): JsonReadResult<T>;
+export declare function readJsonFileResilient<T>(path: string, fallback: T, options?: {
+    maxBytes?: number;
+    strictUtf8?: boolean;
+}): JsonReadResult<T>;
 export declare function readJsonlFileResilient<T>(path: string, options?: JsonlReadOptions): JsonlReadResult<T>;
 export declare function formatStateReadDiagnostics(diagnostics: StateReadDiagnostic[], limit?: number): string[];

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

@@ -3,20 +3,23 @@
  * Zones: file-backed actor state, JSON/JSONL diagnostics, inspect safety
  * Owns best-effort JSON and JSONL parsing helpers for operator-facing state reads.
  */
-import { closeSync, fstatSync, openSync, readFileSync, readSync, } from "node:fs";
+import { closeSync, constants, fstatSync, openSync, readFileSync, readSync, } from "node:fs";
 function isEnoent(error) {
     return error.code === "ENOENT";
 }
 function diagnosticMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
-function readTextFileCapped(path, maxBytes) {
+function readTextFileCapped(path, maxBytes, strictUtf8 = false) {
     if (maxBytes === undefined)
-        return readFileSync(path, "utf8");
+        return strictUtf8 ? new TextDecoder("utf-8", { fatal: true }).decode(readFileSync(path)) : readFileSync(path, "utf8");
     const limit = Math.max(0, Math.floor(maxBytes));
-    const fd = openSync(path, "r");
+    const fd = openSync(path, strictUtf8 ? constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0) : "r");
     try {
-        const size = fstatSync(fd).size;
+        const opened = fstatSync(fd);
+        if (strictUtf8 && !opened.isFile())
+            throw new Error("bounded strict read requires a regular file");
+        const size = opened.size;
         if (size > limit) {
             throw Object.assign(new Error(`file exceeds bounded read limit (${size} > ${limit} bytes)`), { code: "EFBIG" });
         }
@@ -28,17 +31,20 @@ function readTextFileCapped(path, maxBytes) {
                 break;
             offset += bytesRead;
         }
-        return content.subarray(0, offset).toString("utf8");
+        if (strictUtf8 && offset !== size)
+            throw new Error("file ended before its bounded strict read completed");
+        const observed = content.subarray(0, offset);
+        return strictUtf8 ? new TextDecoder("utf-8", { fatal: true }).decode(observed) : observed.toString("utf8");
     }
     finally {
         closeSync(fd);
     }
 }
-export function readJsonFileResilient(path, fallback) {
+export function readJsonFileResilient(path, fallback, options = {}) {
     try {
         return {
             diagnostics: [],
-            value: JSON.parse(readFileSync(path, "utf8")),
+            value: JSON.parse(readTextFileCapped(path, options.maxBytes, options.strictUtf8)),
         };
     }
     catch (error) {

package/node_modules/@llblab/pi-actors/dist/lib/temp.d.ts

@@ -1,10 +1,8 @@
 /**
  * Extension temp-directory helpers
  * Zones: temp directory, cleanup, runtime files
- * Owns pi-agent tmp directory preparation and stale-entry cleanup
+ * Owns ordinary pi-agent tmp directory preparation and stale-entry cleanup; Run retirement is separate.
  */
 export declare const DEFAULT_TEMP_MAX_AGE_MS: number;
-export declare const DEFAULT_RUN_MAX_AGE_MS: number;
 export declare function cleanupStaleTempEntries(tempDir: string, maxAgeMs?: number, now?: number, preservedEntries?: Set<string>): Promise<number>;
-export declare function cleanupStaleRunEntries(runsDir: string, maxAgeMs?: number, now?: number): Promise<number>;
-export declare function prepareExtensionTempDir(tempDir: string, maxAgeMs?: number, runMaxAgeMs?: number): Promise<number>;
+export declare function prepareExtensionTempDir(tempDir: string, maxAgeMs?: number): Promise<number>;

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

@@ -1,12 +1,11 @@
 /**
  * Extension temp-directory helpers
  * Zones: temp directory, cleanup, runtime files
- * Owns pi-agent tmp directory preparation and stale-entry cleanup
+ * Owns ordinary pi-agent tmp directory preparation and stale-entry cleanup; Run retirement is separate.
  */
-import { mkdir, readdir, readFile, rm, stat } from "node:fs/promises";
+import { mkdir, readdir, rm, stat } from "node:fs/promises";
 import { join } from "node:path";
 export const DEFAULT_TEMP_MAX_AGE_MS = 24 * 60 * 60 * 1000;
-export const DEFAULT_RUN_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 export async function cleanupStaleTempEntries(tempDir, maxAgeMs = DEFAULT_TEMP_MAX_AGE_MS, now = Date.now(), preservedEntries = new Set(["runs", "delivery"])) {
     let entries;
     let removed = 0;
@@ -33,58 +32,7 @@ export async function cleanupStaleTempEntries(tempDir, maxAgeMs = DEFAULT_TEMP_M
     }
     return removed;
 }
-function isPidAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-async function isRunEntryAlive(path) {
-    try {
-        const raw = await readFile(join(path, "run.json"), "utf8");
-        const meta = JSON.parse(raw);
-        const pid = Number(meta.pid || 0);
-        return pid > 0 && isPidAlive(pid);
-    }
-    catch {
-        return false;
-    }
-}
-export async function cleanupStaleRunEntries(runsDir, maxAgeMs = DEFAULT_RUN_MAX_AGE_MS, now = Date.now()) {
-    let entries;
-    let removed = 0;
-    try {
-        entries = await readdir(runsDir, { withFileTypes: true });
-    }
-    catch {
-        return 0;
-    }
-    for (const entry of entries) {
-        if (!entry.isDirectory())
-            continue;
-        const path = join(runsDir, entry.name);
-        try {
-            const info = await stat(path);
-            const timestamp = Math.min(info.birthtimeMs || info.mtimeMs, info.mtimeMs);
-            if (now - timestamp <= maxAgeMs)
-                continue;
-            if (await isRunEntryAlive(path))
-                continue;
-            await rm(path, { force: true, recursive: true });
-            removed += 1;
-        }
-        catch {
-            // Ignore temp cleanup races.
-        }
-    }
-    return removed;
-}
-export async function prepareExtensionTempDir(tempDir, maxAgeMs = DEFAULT_TEMP_MAX_AGE_MS, runMaxAgeMs = DEFAULT_RUN_MAX_AGE_MS) {
+export async function prepareExtensionTempDir(tempDir, maxAgeMs = DEFAULT_TEMP_MAX_AGE_MS) {
     await mkdir(tempDir, { recursive: true });
-    const removedTemp = await cleanupStaleTempEntries(tempDir, maxAgeMs);
-    const removedRuns = await cleanupStaleRunEntries(join(tempDir, "runs"), runMaxAgeMs);
-    return removedTemp + removedRuns;
+    return cleanupStaleTempEntries(tempDir, maxAgeMs);
 }

package/node_modules/@llblab/pi-actors/dist/lib/tools-access.d.ts

@@ -3,12 +3,15 @@
  * Zones: session ownership, run visibility guards, tool authorization errors
  * Owns consistent session-mismatch diagnostics for public tool execution paths
  */
+import * as RunIndex from "./runs-index.ts";
 export interface SessionContext {
     sessionManager?: {
         getSessionId?: () => string;
     };
 }
 export declare function getContextSessionId(ctx: unknown): string | undefined;
+/** Optional post-launch navigation never fails or rolls back work already admitted by the launch owner. */
+export declare function readRunFileNavigationForContext(status: object, ctx: unknown): Readonly<RunIndex.RunDirectoryNavigation>;
 export declare function requireContextSessionId(ctx: unknown, actor: string): string;
 export declare function sessionMismatchError(input: {
     currentSession?: string;

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

@@ -4,9 +4,22 @@
  * Owns consistent session-mismatch diagnostics for public tool execution paths
  */
 import * as AsyncRuns from "./async-runs.js";
+import * as RunIndex from "./runs-index.js";
 export function getContextSessionId(ctx) {
     return ctx?.sessionManager?.getSessionId?.();
 }
+/** Optional post-launch navigation never fails or rolls back work already admitted by the launch owner. */
+export function readRunFileNavigationForContext(status, ctx) {
+    try {
+        const sessionId = getContextSessionId(ctx);
+        const directory = Object.getOwnPropertyDescriptor(status, "state_dir");
+        const navigation = RunIndex.readRunDirectoryNavigation(typeof directory?.value === "string" ? directory.value : "", status, sessionId);
+        return getContextSessionId(ctx) === sessionId ? navigation : Object.freeze({ state: "unavailable", reason: "session_changed" });
+    }
+    catch {
+        return Object.freeze({ state: "unavailable", reason: "navigation_unavailable" });
+    }
+}
 export function requireContextSessionId(ctx, actor) {
     const sessionId = getContextSessionId(ctx);
     if (!sessionId) {

package/node_modules/@llblab/pi-actors/dist/lib/tools-inspect.d.ts

@@ -10,6 +10,7 @@ export interface InspectToolDeps<TContext = unknown> {
     getToolStatus?: (name: string) => Record<string, unknown> | undefined;
     listRuns?: () => Array<Record<string, any>>;
     recipeRoot?: string;
+    runStateRoot?: string;
     registryStatus?: () => Runtime.RecipeRegistryStatus;
 }
 export declare function createInspectToolDefinition<TContext = unknown>(deps?: InspectToolDeps<TContext>): any;