@llblab/pi-kit 0.38.4 → 0.39.0

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

@@ -5,36 +5,57 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { observeExecutionFileReference } from "./execution-files.js";
 import * as SessionEvidence from "./session-evidence.js";
+import * as Limits from "./limits.js";
 import { readJsonFileResilient } from "./state-readers.js";
-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;
-    }
-    catch {
-        return undefined;
-    }
-}
+export const EXECUTION_CHRONOLOGY = Symbol("execution-session-chronology");
 export function readExecutionTurns(stateDir) {
-    const execution = readJsonFileResilient(path.join(stateDir, "execution.json"), {}).value;
+    const read = readJsonFileResilient(path.join(stateDir, "execution.json"), {});
+    const execution = read.value;
+    const basis = "recorded_execution_metadata";
+    let reason = read.diagnostics.length ? "source_unavailable" : undefined;
+    const metadata = [];
+    let metadataBytes = Buffer.byteLength(JSON.stringify({ state: "available", basis, entries: [] }));
+    const refuse = (next) => { reason ??= next; metadata.length = 0; };
+    const collect = (commandId, sessionFile, frame) => {
+        if (reason)
+            return;
+        if (!frame || frame.state !== "available") {
+            refuse(frame?.state === "unavailable" ? frame.reason : "source_unavailable");
+            return;
+        }
+        if (SessionEvidence.redactSessionEvidenceValue(commandId) !== commandId || SessionEvidence.redactSessionEvidenceValue(sessionFile) !== sessionFile) {
+            refuse("namespace_unavailable");
+            return;
+        }
+        for (const item of frame.entries) {
+            const entry = Object.freeze({ ...item, commandId, sessionFile, sessionOrdinal: item.ordinal, ordinal: metadata.length + 1 });
+            metadataBytes += Buffer.byteLength(JSON.stringify(entry)) + Number(metadata.length > 0);
+            if (metadataBytes > Limits.SESSION_EVIDENCE_MAX_BYTES) {
+                refuse("metadata_too_large");
+                return;
+            }
+            metadata.push(entry);
+        }
+    };
     const commands = Array.isArray(execution.commands)
         ? execution.commands
         : [];
+    if ((execution.commands !== undefined && !Array.isArray(execution.commands)) || commands.some((command) => !command || typeof command !== "object" || Array.isArray(command) ||
+        (command.session_files !== undefined && (!Array.isArray(command.session_files) || command.session_files.some((file) => typeof file !== "string")))))
+        refuse("source_unavailable");
     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
+        const state = path.resolve(stateDir);
+        const sessionsDir = path.join(state, "sessions");
+        const root = fs.lstatSync(state);
+        const rootObserved = root.isDirectory() && !root.isSymbolicLink();
+        const namespace = fs.lstatSync(sessionsDir, { throwIfNoEntry: false });
+        if (!rootObserved || (namespace && (!namespace.isDirectory() || namespace.isSymbolicLink())))
+            refuse("source_unavailable");
+        discoveredCommands = rootObserved && namespace?.isDirectory() && !namespace.isSymbolicLink() ? fs
             .readdirSync(sessionsDir, { withFileTypes: true })
             .filter((entry) => entry.isDirectory())
             .flatMap((entry) => {
@@ -48,19 +69,30 @@ export function readExecutionTurns(stateDir) {
             return files.length > 0
                 ? [{ id: entry.name, session_files: files, stage: "subagent" }]
                 : [];
-        });
+        }) : [];
     }
     catch {
+        refuse("source_unavailable");
         discoveredCommands = [];
     }
-    return [...commands, ...discoveredCommands]
+    const turns = [...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)
+        const reference = observeExecutionFileReference(stateDir, { kind: "session", path: file });
+        if (reference.availability !== "available") {
+            refuse("source_unavailable");
+            return [];
+        }
+        const session = SessionEvidence.readSessionEvidence(reference.local_path);
+        if (!reference.unchanged()) {
+            refuse("source_changed");
             return [];
-        const session = SessionEvidence.readSessionEvidence(sessionPath);
+        }
+        if (typeof command.id !== "string" || !command.id)
+            refuse("namespace_unavailable");
+        else
+            collect(command.id, file, session[SessionEvidence.SESSION_EVIDENCE_CHRONOLOGY]);
         return session.turns.map((turn) => ({
             ...turn,
             commandId: String(command.id ?? "unknown"),
@@ -82,4 +114,8 @@ export function readExecutionTurns(stateDir) {
         }));
     }))
         .map((turn, index) => ({ ...turn, index: index + 1 }));
+    Object.defineProperty(turns, EXECUTION_CHRONOLOGY, { value: Object.freeze(reason
+            ? { state: "unavailable", basis, reason, entries: Object.freeze([]) }
+            : { state: "available", basis, entries: Object.freeze(metadata) }) });
+    return turns;
 }

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

@@ -96,4 +96,7 @@ export interface RegisteredToolExecutionResult {
 }
 export type RegisteredToolExec = (command: string, args: string[], options?: ToolExecOptions) => Promise<ToolExecResult>;
 export declare function applyOutputAcceptancePolicy(result: ToolExecResult, output: string | undefined): Promise<ToolExecResult>;
-export declare function executeRegisteredTool(cfg: RegisteredTool, params: Record<string, unknown>, exec: RegisteredToolExec, cwd: string, signal?: AbortSignal): Promise<RegisteredToolExecutionResult>;
+export declare function executeRegisteredTool(cfg: RegisteredTool, params: Record<string, unknown>, exec: RegisteredToolExec, cwd: string, signal?: AbortSignal, kernel?: {
+    readonly onPrimaryCommandSelected?: (result: Readonly<ToolExecResult>) => void | Promise<void>;
+    readonly onFinalResponseSelected?: (text: string, upstreamTruncated: boolean) => void | Promise<void>;
+}): Promise<RegisteredToolExecutionResult>;

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

@@ -674,7 +674,7 @@ function getCaptureDetails(result) {
         ...(result.stderrTruncated ? { stderrTruncated: true } : {}),
     };
 }
-export async function executeRegisteredTool(cfg, params, exec, cwd, signal) {
+export async function executeRegisteredTool(cfg, params, exec, cwd, signal, kernel) {
     const executed = await executeTemplateSteps(cfg, Schema.normalizeRuntimeValues(params, cfg.argTypes), exec, cwd, signal);
     const command = formatCommandDetail(executed.commands);
     const result = executed.result;
@@ -700,6 +700,11 @@ export async function executeRegisteredTool(cfg, params, exec, cwd, signal) {
             },
         });
     }
+    // Only the plain successful leaf is admitted initially; compositions/acceptance policies are separate contracts.
+    if (typeof cfg.template === "string" && executed.commands.length === 1 && !executed.failures.length) {
+        await kernel?.onPrimaryCommandSelected?.(result);
+    }
+    await kernel?.onFinalResponseSelected?.(result.stdout, result.stdoutTruncated === true || executed.branches.some(branch => branch.status !== "done" && (branch.stderrTruncated === true || branch.stderrBytes > Buffer.byteLength(branch.stderr ?? ""))));
     const formatted = formatOutput(cfg.name, "stdout", result.stdout);
     const templateWarnings = CommandTemplates.getCommandTemplateWarnings(createTemplateConfig(cfg));
     return {

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

@@ -5,6 +5,10 @@
  */
 import * as Pi from "./pi.ts";
 import * as RecipesReferences from "./recipes-references.ts";
+import * as RunUiRuntime from "./run-ui-runtime.ts";
+import { type RunSupervisionOwnerSnapshotReading } from "./runs-supervision.ts";
+import type { RunSupervisionControllerPorts } from "./run-supervision.ts";
+import type { AsyncRunStartOptions } from "./async-runs.ts";
 export interface ActorExtensionRuntime {
     beforeAgentStart(systemPrompt: string, skills: RecipesReferences.ActiveSkillRecipeSource[], ctx: Pi.ExtensionContext): {
         systemPrompt: string;
@@ -17,7 +21,10 @@ export interface ActorExtensionRuntime {
     onTurnEnd(event: Pi.TurnEndEvent, ctx: Pi.ExtensionContext): Pi.TurnEndEventResult | undefined;
     onContext(messages: unknown[], ctx: Pi.ExtensionContext): unknown[];
     onSessionShutdown(reason: string, ctx: Pi.ExtensionContext): void;
-    onSessionStart(ctx: Pi.ExtensionContext): Promise<void>;
+    onSessionStart(ctx: Pi.ExtensionContext, event?: Pi.SessionStartEvent): Promise<void>;
     registerCoreTools(): void;
+    /** Private kernel observation only; no public tool route or reconstructed origin. */
+    observeRunSnapshot(expected: unknown, capturedAt: unknown, stateDir?: string): Readonly<RunSupervisionOwnerSnapshotReading>;
+    getRunAdmissionObserver(ctx: Pi.ExtensionContext): AsyncRunStartOptions["onSupervisionClockCaptured"];
 }
-export declare function createActorExtensionRuntime(pi: Pi.ExtensionAPI): ActorExtensionRuntime;
+export declare function createActorExtensionRuntime(pi: Pi.ExtensionAPI, supervisionPorts?: Omit<RunSupervisionControllerPorts, "readCurrent">, completionStreamSessionAdmission?: RunUiRuntime.RunUiRuntimeDeps["completionStreamSessionAdmission"], captureCompletionBatch?: RunUiRuntime.RunUiRuntimeDeps["captureCompletionBatch"]): ActorExtensionRuntime;

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

@@ -3,6 +3,7 @@
  * Zones: extension session lifecycle, host tool adaptation, runtime service composition
  * Owns low-level Pi lifecycle effects and tool wrapping without owning event registration.
  */
+import { join } from "node:path";
 import * as AutomaticReviewRuntime from "./automatic-review-runtime.js";
 import * as CommandTemplates from "./command-templates.js";
 import * as Paths from "./paths.js";
@@ -13,14 +14,38 @@ import * as RecipesReferences from "./recipes-references.js";
 import * as RunUiRuntime from "./run-ui-runtime.js";
 import * as Runtime from "./runtime.js";
 import * as Temp from "./temp.js";
+import * as RunRetention from "./runs-retention.js";
 import * as Tools from "./tools.js";
 import * as ToolsResponse from "./tools-response.js";
-export function createActorExtensionRuntime(pi) {
+import { createRunSupervisionOwner, } from "./runs-supervision.js";
+export function createActorExtensionRuntime(pi, supervisionPorts, completionStreamSessionAdmission, captureCompletionBatch) {
     let activeRunContext;
     let activeRunOwnerId;
-    const runOwnerIdsByContext = new WeakMap();
+    let sessionStartTicket;
+    let parentSession;
+    const parentSessionsByContext = new WeakMap();
+    const seenParentManagers = new WeakSet();
     const recipeResolutionContextsBySession = new Map();
     const getRunOwnerId = Pi.getSessionId;
+    let supervision;
+    const closeSupervision = () => {
+        const scope = supervision;
+        supervision = undefined;
+        scope?.owner.close();
+    };
+    const getRunAdmissionObserver = (ctx) => {
+        if (!supervisionPorts)
+            return undefined;
+        const scope = supervision;
+        const sessionManager = ctx.sessionManager;
+        const ownerId = sessionManager.getSessionId();
+        return capture => {
+            if (!scope || supervision !== scope || !scope.ready || scope.sessionManager !== sessionManager || scope.ownerId !== ownerId || capture.identity.ownerId !== ownerId) {
+                throw new Error("Run supervision coordinator admission is unavailable or changed.");
+            }
+            scope.owner.onSupervisionClockCaptured(capture);
+        };
+    };
     const getRecipeResolutionContext = (ctx) => {
         const sessionId = getRunOwnerId(ctx);
         const resolutionContext = recipeResolutionContextsBySession.get(sessionId);
@@ -33,6 +58,7 @@ export function createActorExtensionRuntime(pi) {
         getActiveContext: () => activeRunContext,
         getRunOwnerId,
         getThinkingLevel: () => pi.getThinkingLevel(),
+        getRunAdmissionObserver,
     });
     let recipeReload;
     let runUiRuntime;
@@ -40,13 +66,17 @@ export function createActorExtensionRuntime(pi) {
         const ownerId = activeRunOwnerId;
         activeRunContext = undefined;
         activeRunOwnerId = undefined;
+        sessionStartTicket = undefined;
         runUiRuntime?.close();
         automaticReview.close();
         recipeReload?.close();
         if (ownerId)
             recipeResolutionContextsBySession.delete(ownerId);
     };
+    RunUiRuntime.registerRunCompletionRenderer(pi);
     runUiRuntime = RunUiRuntime.createRunUiRuntime({
+        completionStreamSessionAdmission,
+        captureCompletionBatch,
         getActiveContext: () => activeRunContext,
         onCallbackError: closeActiveSessionRuntimes,
         onRunEvent: automaticReview.schedule,
@@ -67,6 +97,7 @@ export function createActorExtensionRuntime(pi) {
                         ...ctx,
                         recipeResolutionContext: getRecipeResolutionContext(ctx),
                         getThinkingLevel: () => pi.getThinkingLevel(),
+                        onSupervisionClockCaptured: getRunAdmissionObserver(ctx),
                     };
                 }
                 try {
@@ -112,7 +143,13 @@ export function createActorExtensionRuntime(pi) {
             return skillPaths.length > 0 ? { skillPaths } : undefined;
         },
         getRunOwnerId,
+        getRunAdmissionObserver,
+        observeRunSnapshot(expected, capturedAt, stateDir) {
+            return supervision?.owner.observeSnapshot(expected, capturedAt, stateDir) ?? Object.freeze({ state: "unavailable", reason: "origin_not_retained" });
+        },
         onAgentSettled(ctx) {
+            if ((completionStreamSessionAdmission || captureCompletionBatch) && !runUiRuntime.isCurrentSessionContext(ctx))
+                return;
             if (!activeRunOwnerId || getRunOwnerId(ctx) !== activeRunOwnerId)
                 return;
             if (!runUiRuntime.flushCompletionBatch(ctx))
@@ -125,29 +162,70 @@ export function createActorExtensionRuntime(pi) {
             return runUiRuntime.projectContext(messages, ctx);
         },
         onSessionShutdown(reason, ctx) {
-            const ownerId = runOwnerIdsByContext.get(ctx);
-            runOwnerIdsByContext.delete(ctx);
-            if (activeRunContext === ctx)
-                closeActiveSessionRuntimes();
-            if (ownerId)
-                recipeResolutionContextsBySession.delete(ownerId);
-            runUiRuntime.shutdown(reason, ownerId, ctx);
+            const scope = parentSession;
+            if (!scope?.shutdownAdmitted)
+                return;
+            const known = parentSessionsByContext.get(ctx);
+            if (known && known !== scope)
+                return;
+            if (!known) {
+                try {
+                    if (ctx.sessionManager !== scope.sessionManager || scope.sessionManager.getSessionId() !== scope.ownerId)
+                        return;
+                }
+                catch {
+                    return; /* Unknown invalidated wrappers cannot identify this lifetime. */
+                }
+            }
+            if (parentSession !== scope)
+                return;
+            // Consume before cleanup/teardown: stale or reentrant callbacks cannot stop a replacement.
+            scope.shutdownAdmitted = false;
+            parentSessionsByContext.set(ctx, scope);
+            closeSupervision();
+            if (parentSession !== scope)
+                return;
+            closeActiveSessionRuntimes();
+            if (parentSession !== scope)
+                return;
+            recipeResolutionContextsBySession.delete(scope.ownerId);
+            runUiRuntime.shutdown(reason, scope.ownerId, ctx);
         },
-        async onSessionStart(ctx) {
-            const sessionId = getRunOwnerId(ctx);
+        async onSessionStart(ctx, event) {
+            const ticket = {};
+            sessionStartTicket = ticket;
+            parentSession = undefined;
+            const sessionManager = ctx.sessionManager;
+            const sessionId = sessionManager.getSessionId();
+            if (sessionStartTicket !== ticket)
+                return;
+            const scopeBinding = { ownerId: sessionId, sessionManager,
+                shutdownAdmitted: !seenParentManagers.has(sessionManager) && !parentSessionsByContext.has(ctx) };
+            seenParentManagers.add(sessionManager);
+            if (!parentSessionsByContext.has(ctx))
+                parentSessionsByContext.set(ctx, scopeBinding);
+            parentSession = scopeBinding;
+            closeSupervision();
             recipeResolutionContextsBySession.set(sessionId, RecipeResolution.createEmptyRecipeResolutionContext(sessionId, ctx.cwd));
             ctx.ui.setWidget("zz-pi-actors-comms", undefined);
             activeRunContext = ctx;
             activeRunOwnerId = sessionId;
-            runOwnerIdsByContext.set(ctx, sessionId);
             runUiRuntime.close();
             automaticReview.close();
             recipeReload.close();
+            const scope = supervisionPorts ? {
+                context: ctx, ownerId: sessionId, owner: createRunSupervisionOwner(supervisionPorts),
+                ready: false, sessionManager,
+            } : undefined;
+            supervision = scope;
             await Temp.prepareExtensionTempDir(Paths.EXTENSION_RUNTIME_PATHS.tempDir);
-            if (activeRunContext !== ctx || activeRunOwnerId !== sessionId)
+            await RunRetention.cleanupStaleRunEntries(join(Paths.EXTENSION_RUNTIME_PATHS.tempDir, "runs"));
+            if (sessionStartTicket !== ticket || activeRunContext !== ctx || activeRunOwnerId !== sessionId || supervision !== scope)
                 return;
+            if (scope)
+                scope.ready = true;
             automaticReview.start(ctx);
-            runUiRuntime.start(ctx, sessionId);
+            runUiRuntime.start(ctx, sessionId, event);
             recipeReload.watch(ctx);
         },
         registerCoreTools() {

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

@@ -266,11 +266,24 @@ export function acquireFileMutationLock(path, options = {}) {
 }
 export function withFileMutationLock(path, mutate, options = {}) {
     const release = acquireFileMutationLock(path, options);
+    let mutationFailed = false, mutationFailure;
     try {
         return mutate();
     }
+    catch (error) {
+        mutationFailed = true;
+        mutationFailure = error;
+        throw error;
+    }
     finally {
-        release();
+        try {
+            release();
+        }
+        catch (releaseError) {
+            if (mutationFailed)
+                throw new AggregateError([mutationFailure, releaseError], "File mutation callback and lock release failed; effects may already exist.", { cause: mutationFailure });
+            throw releaseError;
+        }
     }
 }
 function replaceFileWithRetry(source, target) {
@@ -280,7 +293,13 @@ function replaceFileWithRetry(source, target) {
             return;
         }
         catch (error) {
-            const code = error.code;
+            let code;
+            try {
+                code = error?.code;
+            }
+            catch (observationError) {
+                throw new AggregateError([error, observationError], "File replacement failed and retry-code inspection also failed; effects may already exist.", { cause: error });
+            }
             if ((code !== "EPERM" && code !== "EBUSY") || attempt >= 19)
                 throw error;
             Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);

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

@@ -4,7 +4,7 @@
  * Owns host-facing Inspector launch wiring without owning Inspector state or actions.
  */
 import * as AsyncRuns from "./async-runs.js";
-import * as InspectorActions from "./inspector-actions.js";
+import * as Inspector from "./inspector.js";
 import * as InspectorOverlay from "./inspector-overlay.js";
 import * as Paths from "./paths.js";
 export function registerActorInspectorCommand(pi, getRunOwnerId) {
@@ -14,7 +14,7 @@ export function registerActorInspectorCommand(pi, getRunOwnerId) {
             ctx.ui.setWidget("zz-pi-actors-comms", undefined);
             await ctx.ui.custom((tui, theme, _keybindings, done) => new InspectorOverlay.ActorInspectorOverlay({
                 done,
-                killRun: (run, runInstanceId) => InspectorActions.killOwnedRunFromInspector(getRunOwnerId(ctx), run, Paths.EXTENSION_RUNTIME_PATHS.runStateRoot, runInstanceId, {
+                killRun: (run, runInstanceId) => Inspector.killOwnedRunFromInspector(getRunOwnerId(ctx), run, Paths.EXTENSION_RUNTIME_PATHS.runStateRoot, runInstanceId, {
                     getRunStatus: AsyncRuns.getRunStatus,
                     killRun: AsyncRuns.killRun,
                 }),

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

@@ -3,7 +3,7 @@
  * Zones: owned actor selection, Recipe/Trace/Control tabs, safe Run Kill confirmation
  * Owns manual kernel navigation; evidence parsing and lifecycle mutation stay in ports.
  */
-import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Theme } from "@earendil-works/pi-coding-agent";
 import { type TUI } from "@earendil-works/pi-tui";
 import * as ActorInspector from "./inspector.ts";
 import * as TraceProjection from "./trace-projection.ts";
@@ -37,12 +37,20 @@ export declare class ActorInspectorOverlay {
     private documentScroll;
     private detailScroll;
     private feedback?;
+    private feedbackFromAction;
+    private feedbackScroll;
+    private feedbackPageRows;
+    private inspectorFrame?;
     private focus;
     private killConfirmation?;
     private killDialogChoice;
+    private killDialogScroll;
+    private killDialogPageRows;
     private rowIndex;
     private runCache?;
     private selectedTraceId?;
+    private controlCache?;
+    private controlSelection?;
     private runIndex;
     private selectorIndex;
     private selectorMode?;
@@ -55,6 +63,7 @@ export declare class ActorInspectorOverlay {
     invalidate(): void;
     handleInput(data: string): void;
     render(width: number): string[];
+    private renderInspector;
     private get tab();
     private runs;
     private contentViewportRows;
@@ -71,25 +80,34 @@ export declare class ActorInspectorOverlay {
     private renderRunControl;
     private renderTabs;
     private renderContent;
+    private modalUnderlay;
+    private compositePopup;
+    private popupLayout;
+    private renderFeedbackPopup;
+    private closureWarning;
     private renderSelector;
     private runSelectorOptions;
     private renderMenuBox;
+    private traceTableLine;
     private renderTraceList;
     private renderTraceDetail;
+    private agentDetailSegments;
+    private metadataText;
+    private agentDetailProjection;
     private controlDocument;
+    private controlObservation;
+    private selectedControl;
+    private openControlList;
+    private handleControlInput;
+    private renderControlContent;
     private allTraceItems;
     private traceSources;
     private traceSource;
     private traceItems;
     private readRunMeta;
     private documentProjection;
-    private inlineDocumentValue;
-    private labeledDocumentLines;
-    private labeledScalarLines;
-    private document;
     private wrapDocument;
-    private styleDocumentLine;
-    private visiblePrefix;
+    private keyHints;
     private renderKeyHints;
     private statusColor;
     private footerBorder;