@llblab/pi-kit 0.38.3 → 0.39.0

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

@@ -1,16 +1,142 @@
 /**
- * Async run retention operations.
- * Owns: terminal-run archive and prune filesystem behavior.
+ * Run retirement owner.
+ * Owns: lifecycle-serialized manual archive/prune, age-based cleanup and shared ownership/scope fences.
+ * Excludes: native closure proof, process actuation and ordinary non-Run temp cleanup.
  */
 import { createHash, randomUUID } from "node:crypto";
-import { cpSync, mkdirSync, renameSync, rmSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { cpSync, lstatSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
 import { acquireFileMutationLock, writeJsonAtomic, writeTextAtomic } from "./file-state.js";
 import * as Limits from "./limits.js";
-import { readJsonlFileResilient } from "./state-readers.js";
+import { readJsonFileResilient, readJsonlFileResilient } from "./state-readers.js";
+import { readRunContextIdentity, RUN_CONTEXT_SOURCE_METADATA_MAX_BYTES } from "./runs-context-index.js";
+import { readProcessLiveness } from "./runs-process.js";
+import { acquireStateStartLock, assertNoActiveRunState } from "./runs-start.js";
 import { resolveArtifactManifest, } from "./runs-artifacts.js";
+import { assertNoRetainedDescendantLaunchScope } from "./runs-descendant-launches.js";
 import { safeRunId } from "./runs-identity.js";
+import { assertNoRetainedNativeLaunchScope } from "./runs-native-launches.js";
 import { assertOwnedRunStateDirectory } from "./runs-ownership.js";
+export const DEFAULT_RUN_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const RETIREMENT_FAILURE_MESSAGE = "Run retirement failed; effects may already exist.";
+function assertRetirableDirectory(status) {
+    const stateDir = String(status.state_dir);
+    assertOwnedRunStateDirectory(stateDir, String(status.run ?? basename(stateDir)));
+    assertNoRetainedDescendantLaunchScope(stateDir);
+    assertNoRetainedNativeLaunchScope(stateDir);
+}
+/** Manual API preserves its existing status/expected contract, not a native closure claim. */
+export function retainRun(stateDir, action, expected, readStatus, options = {}) {
+    const release = acquireStateStartLock(stateDir);
+    let status;
+    let evidenceId;
+    const failures = [];
+    try {
+        expected.onLocked?.();
+        status = readStatus(stateDir);
+        if (expected.ownerId !== undefined && status.ownerId !== expected.ownerId) {
+            return { [`${action}d`]: false, reason: "ownership changed", status };
+        }
+        if (expected.runInstanceId !== undefined && status.run_instance_id !== expected.runInstanceId) {
+            return { [`${action}d`]: false, reason: "run generation changed", status };
+        }
+        if (status.status === "running")
+            throw new Error("Only terminal runs can be archived or pruned.");
+        if (resolve(String(status.state_dir)) !== resolve(stateDir))
+            throw new Error("Run retirement state directory changed.");
+        evidenceId = appendRunRetentionEvidence(status, action, "queued");
+        const result = action === "archive" ? archiveTerminalRun(status) : pruneTerminalRun(status, options);
+        appendRunRetentionEvidence(status, action, "handled", { id: evidenceId, result });
+        return { ...result, retention_id: evidenceId };
+    }
+    catch (error) {
+        failures.push(error);
+        if (status && evidenceId) {
+            let text;
+            try {
+                text = String(error instanceof Error ? error.message : error);
+            }
+            catch (formattingError) {
+                text = "failure text unavailable";
+                failures.push(formattingError);
+            }
+            try {
+                appendRunRetentionEvidence(status, action, "failed", { error: text, id: evidenceId });
+            }
+            catch (recordingError) {
+                failures.push(recordingError);
+            }
+        }
+    }
+    finally {
+        try {
+            release();
+        }
+        catch (releaseError) {
+            if (failures.length)
+                throw new AggregateError([...failures, releaseError], RETIREMENT_FAILURE_MESSAGE, { cause: failures[0] });
+            throw releaseError;
+        }
+    }
+    if (failures.length === 1)
+        throw failures[0];
+    throw new AggregateError(failures, RETIREMENT_FAILURE_MESSAGE, { cause: failures[0] });
+}
+/** Filesystem age selects candidates; it grants neither retirement nor native scope authority. */
+export async function cleanupStaleRunEntries(runsDir, maxAgeMs = DEFAULT_RUN_MAX_AGE_MS, now = Date.now()) {
+    let entries;
+    const root = resolve(runsDir);
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    let removed = 0;
+    const readJson = (path) => {
+        const reading = readJsonFileResilient(path, undefined, { maxBytes: RUN_CONTEXT_SOURCE_METADATA_MAX_BYTES, strictUtf8: true });
+        if (reading.diagnostics.length)
+            throw new Error("Run retirement metadata is unavailable.");
+        return reading.value;
+    };
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const stateDir = join(root, entry.name);
+        try {
+            const selected = lstatSync(stateDir);
+            if (now - Math.min(selected.birthtimeMs || selected.mtimeMs, selected.mtimeMs) <= maxAgeMs)
+                continue;
+            const candidate = readRunContextIdentity(stateDir, readJson(join(stateDir, "run.json")));
+            if (candidate.state !== "available")
+                continue;
+            const release = acquireStateStartLock(stateDir);
+            try {
+                if (!candidate.unchanged())
+                    continue;
+                const current = lstatSync(stateDir);
+                if (now - Math.min(current.birthtimeMs || current.mtimeMs, current.mtimeMs) <= maxAgeMs)
+                    continue;
+                const meta = readJson(join(stateDir, "run.json"));
+                if (!meta || typeof meta.pid !== "number" || !candidate.unchanged())
+                    continue;
+                assertNoActiveRunState(stateDir, readJson, "");
+                if (readProcessLiveness(meta.pid) !== "dead" || !candidate.unchanged())
+                    continue;
+                pruneTerminalRun(meta);
+                removed++;
+            }
+            finally {
+                release();
+            }
+        }
+        catch {
+            // Best-effort startup cleanup retains unavailable, replaced or still-fenced candidates.
+        }
+    }
+    return removed;
+}
 export function appendRunRetentionEvidence(status, action, outcome, options = {}) {
     const stateDir = String(status.state_dir);
     const path = join(dirname(stateDir), "retention.jsonl");
@@ -26,6 +152,7 @@ export function appendRunRetentionEvidence(status, action, outcome, options = {}
         ts: new Date().toISOString(),
     };
     const release = acquireFileMutationLock(path);
+    let writeFailed = false, writeFailure;
     try {
         const records = [...readJsonlFileResilient(path).records, record]
             .slice(-Limits.RUN_RETENTION_MAX_RECORDS);
@@ -38,8 +165,20 @@ export function appendRunRetentionEvidence(status, action, outcome, options = {}
             throw new Error("Run retention record exceeds journal byte limit");
         writeTextAtomic(path, content);
     }
+    catch (error) {
+        writeFailed = true;
+        writeFailure = error;
+        throw error;
+    }
     finally {
-        release();
+        try {
+            release();
+        }
+        catch (releaseError) {
+            if (writeFailed)
+                throw new AggregateError([writeFailure, releaseError], "Run retention journal append and release failed", { cause: writeFailure });
+            throw releaseError;
+        }
     }
     return id;
 }
@@ -62,7 +201,7 @@ function archivePathFor(run, stateDir) {
 export function archiveTerminalRun(status) {
     const stateDir = String(status.state_dir);
     const run = String(status.run ?? basename(stateDir));
-    assertOwnedRunStateDirectory(stateDir, run);
+    assertRetirableDirectory(status);
     const archiveDir = archivePathFor(run, stateDir);
     renameSync(stateDir, archiveDir);
     mkdirSync(stateDir, { recursive: true });
@@ -80,8 +219,8 @@ export function archiveTerminalRun(status) {
 export function pruneTerminalRun(status, options = {}, deps = {}) {
     const stateDir = String(status.state_dir);
     const run = String(status.run ?? basename(stateDir));
-    assertOwnedRunStateDirectory(stateDir, run);
-    const manifest = resolveArtifactManifest(status.artifacts);
+    assertRetirableDirectory(status);
+    const manifest = options.preserveArtifacts ? resolveArtifactManifest(status.artifacts) : undefined;
     const preserved = {};
     if (options.preserveArtifacts && manifest) {
         const preserveRoot = join(dirname(stateDir), "preserved-artifacts", safeRunId(run));

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

@@ -0,0 +1,95 @@
+import { type RunContextEntry, type RunContextIndexIdentity, type RunContextIndexPublication } from "./runs-context-index.ts";
+import { type RunExecutionReferenceReading } from "./runs-execution-evidence.ts";
+import { type RunResultProducer } from "./runs-results.ts";
+export declare const SESSION_ASSISTANT_PREVIEW_MAX_BYTES: number;
+export interface SessionAssistantPreviewMessage {
+    readonly ordinal: number;
+    readonly assistant_text: string;
+    readonly text_chars_observed: number;
+    readonly text_chars_shown: number;
+    readonly text_chars_omitted: number;
+    readonly preview_clipped: boolean;
+}
+export interface SessionAssistantPreview {
+    readonly content_scope: "assistant_visible_text_preview";
+    readonly source_scope: "last_recorded_branch";
+    readonly primary_text: "not_exported";
+    readonly order: "oldest_first";
+    readonly coverage: {
+        readonly truncated: true;
+        readonly redacted: true;
+        readonly history_complete: false;
+    };
+    readonly text_limit_chars: number;
+    readonly messages_total: number;
+    readonly messages_shown: number;
+    readonly messages_omitted: number;
+    readonly messages: readonly Readonly<SessionAssistantPreviewMessage>[];
+}
+export type SessionAssistantPreviewReading = {
+    readonly state: "available";
+    readonly preview: Readonly<SessionAssistantPreview>;
+} | {
+    readonly state: "unavailable";
+    readonly reason: "session_invalid" | "preview_too_large";
+};
+/** Preview clipping happens after origin/secret projection, never by slicing raw/private session fields. */
+export declare function projectSessionAssistantPreview(source: string, recipe?: Record<string, unknown>, redactEvidence?: (value: unknown) => unknown): Readonly<SessionAssistantPreviewReading>;
+export type RunSessionPreviewReading = {
+    readonly state: "available";
+    readonly identity: Readonly<RunContextIndexIdentity>;
+    readonly command_id: string;
+    readonly source_updated_at: string;
+    readonly preview: Readonly<SessionAssistantPreview>;
+    readonly unchanged: () => boolean;
+} | {
+    readonly state: "unavailable";
+    readonly reason: Extract<RunExecutionReferenceReading, {
+        state: "unavailable";
+    }>["reason"] | "session_metadata_unavailable" | "session_metadata_redacted" | "session_unavailable" | "session_too_large" | "session_invalid" | "preview_too_large";
+};
+/** This policy is fixed in the kernel; serialized reference DTOs or actor visibility flags cannot widen it. */
+export declare function readRunSessionPreview(stateDir: string, expected: unknown, query: unknown): Readonly<RunSessionPreviewReading>;
+export declare const RUN_CONTEXT_SESSIONS_MAX_BYTES: number;
+declare const COVERAGE: Readonly<{
+    truncated: true;
+    redacted: true;
+    history_complete: false;
+}>;
+type Unavailable = {
+    readonly status: "unavailable";
+    readonly reason: Extract<RunSessionPreviewReading, {
+        state: "unavailable";
+    }>["reason"] | "session_view_too_large" | "session_admission_unavailable" | "session_identity_redacted";
+};
+export type RunSessionContextExportResult = Unavailable | {
+    readonly status: "written";
+    readonly captured_at: string;
+    readonly entry: Readonly<RunContextEntry>;
+};
+/** A real producer is required for both privacy capture and each subsequent evidence commit. */
+export declare function writeRunSessionContextExport(stateDir: string, producer: RunResultProducer, query: unknown): Readonly<RunSessionContextExportResult>;
+/** Preview, catalog and context index are separate effects; no failed phase rolls earlier commits back. */
+export declare function writeRunSessionContextIndex(stateDir: string, producer: RunResultProducer, query: unknown): Readonly<RunContextIndexPublication & {
+    status: "published";
+}>;
+export type RunSessionContextPreviewReading = {
+    readonly state: "available";
+    readonly identity: Readonly<RunContextIndexIdentity>;
+    readonly export_id: string;
+    readonly command_id: string;
+    readonly captured_at: string;
+    readonly path: string;
+    readonly media_type: "application/json";
+    readonly bytes_total: number;
+    readonly mutable: true;
+    readonly coverage: typeof COVERAGE;
+    readonly preview: Readonly<SessionAssistantPreview>;
+    readonly unchanged: () => boolean;
+} | {
+    readonly state: "unavailable";
+    readonly reason: "selection_invalid" | "identity_unavailable" | "identity_mismatch" | "observation_changed" | "index_unavailable" | "sessions_unavailable" | "catalog_unavailable" | "preview_not_listed" | "preview_unavailable" | "preview_invalid" | "preview_too_large";
+};
+/** Read only the selected published body: index metadata never substitutes for nested format/generation admission. */
+export declare function readRunSessionContextPreview(stateDir: string, expected: unknown, exportId: unknown): Readonly<RunSessionContextPreviewReading>;
+export {};