@llblab/pi-kit 0.1.0

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

@@ -0,0 +1,125 @@
+/**
+ * Ambient run observability runtime.
+ * Zones: run watcher lifecycle, terminal reconciliation, status animation, shutdown teardown
+ * Owns event-driven run UI coordination without owning actor execution semantics.
+ */
+import * as AsyncRuns from "./async-runs.js";
+import * as Observability from "./observability.js";
+import * as Paths from "./paths.js";
+import * as Pi from "./pi.js";
+export function createRunUiRuntime(deps) {
+    let animationInterval;
+    let notifyTimeout;
+    let lastWatcherDiagnosticId = 0;
+    const observation = Observability.createRunUiObservationState();
+    const retirementAttempts = new Set();
+    const terminalNotificationsInFlight = new Set();
+    const retireCandidateRuns = (ctx, summary) => {
+        void Observability.executeRunRetirements(summary, {
+            attempted: retirementAttempts,
+            cancelRun: (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
+            notify: (message, level) => ctx.ui.notify(message, level),
+            sendStop: async (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
+        });
+    };
+    const update = (ctx, notify = false, terminalOnly = false) => {
+        const ownerId = deps.getRunOwnerId(ctx);
+        const snapshot = Observability.readRunUiSnapshot(observation, ownerId);
+        ctx.ui.setStatus("zz-pi-actors-runs", snapshot.status ? ctx.ui.theme.fg("dim", snapshot.status) : undefined);
+        if (!notify)
+            return;
+        const sink = Pi.createNotificationSink(deps.pi, ctx);
+        retireCandidateRuns(ctx, snapshot.summary);
+        Observability.deliverRunTransitionNotifications(snapshot.transitions, sink, terminalNotificationsInFlight);
+        Observability.pruneRunUiObservationState(observation, snapshot);
+        if (!terminalOnly) {
+            Observability.deliverRunAttentionNotifications(snapshot.attentionEvents, sink);
+        }
+    };
+    const reportDiagnostics = (ctx) => {
+        for (const diagnostic of watcher.getDiagnostics()) {
+            if (diagnostic.id <= lastWatcherDiagnosticId)
+                continue;
+            lastWatcherDiagnosticId = diagnostic.id;
+            ctx.ui.notify(diagnostic.message, diagnostic.code === "rearmed" ? "info" : "warning");
+        }
+    };
+    const scheduleUpdate = () => {
+        if (notifyTimeout)
+            clearTimeout(notifyTimeout);
+        notifyTimeout = setTimeout(() => {
+            const ctx = deps.getActiveContext();
+            if (!ctx)
+                return;
+            watcher.refresh();
+            update(ctx, true);
+            deps.onRunEvent();
+            reportDiagnostics(ctx);
+        }, 50);
+        notifyTimeout.unref?.();
+    };
+    const watcher = Observability.createRunStateWatcher({
+        stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
+        onChange: scheduleUpdate,
+    });
+    const reconciliation = Observability.createRunTerminalReconciliationLoop({
+        onError: (error) => {
+            const ctx = deps.getActiveContext();
+            if (!ctx)
+                return;
+            const message = error instanceof Error ? error.message : String(error);
+            ctx.ui.notify(`Actor terminal reconciliation failed: ${message}`, "error");
+        },
+        reconcile: () => {
+            const ctx = deps.getActiveContext();
+            if (!ctx)
+                return;
+            Observability.reconcileRunTerminalNotifications({
+                inFlight: terminalNotificationsInFlight,
+                ownerId: deps.getRunOwnerId(ctx),
+                sink: Pi.createNotificationSink(deps.pi, ctx),
+                state: observation,
+                includeAttention: true,
+            });
+            reportDiagnostics(ctx);
+        },
+        refreshWatcher: () => watcher.refresh(),
+    });
+    const close = () => {
+        watcher.close();
+        reconciliation.close();
+        if (notifyTimeout)
+            clearTimeout(notifyTimeout);
+        notifyTimeout = undefined;
+        if (animationInterval)
+            clearInterval(animationInterval);
+        animationInterval = undefined;
+    };
+    return {
+        close,
+        shutdown(eventReason, ctx) {
+            close();
+            const teardown = AsyncRuns.teardownRunsOwnedByParent(deps.getRunOwnerId(ctx), Paths.EXTENSION_RUNTIME_PATHS.runStateRoot, { trigger: `session_shutdown:${eventReason}` });
+            if (teardown.failed === 0)
+                return;
+            try {
+                ctx.ui.notify(`Actor shutdown teardown: killed=${teardown.killed} failed=${teardown.failed} skipped=${teardown.skipped} discovery_failed=${teardown.discoveryFailed}. Summary: ${teardown.summaryPath ?? "unavailable"}.`, "warning");
+            }
+            catch {
+                /* stale shutdown context */
+            }
+        },
+        start(ctx) {
+            close();
+            Observability.primeRunAttentionState(observation, deps.getRunOwnerId(ctx));
+            update(ctx, true, true);
+            watcher.refresh();
+            reconciliation.start();
+            animationInterval = setInterval(() => {
+                if (deps.getActiveContext() === ctx)
+                    update(ctx);
+            }, 1000);
+            animationInterval.unref?.();
+        },
+    };
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Async run artifact declarations and manifest resolution.
+ * Owns: artifact path template expansion and filesystem-backed artifact metadata.
+ */
+export type RunArtifactDeclaration = string | {
+    path: string;
+    kind?: string;
+    media_type?: string;
+    required?: boolean;
+};
+export interface RunArtifactManifestEntry {
+    exists: boolean;
+    kind?: string;
+    media_type?: string;
+    path: string;
+    required?: boolean;
+    sha256?: string;
+    size?: number;
+}
+export declare function resolveArtifactPaths(artifacts: Record<string, RunArtifactDeclaration> | undefined, values: Record<string, unknown>): Record<string, RunArtifactDeclaration> | undefined;
+export declare function resolveArtifactManifest(artifacts: Record<string, RunArtifactDeclaration> | undefined): Record<string, RunArtifactManifestEntry> | undefined;

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

@@ -0,0 +1,68 @@
+/**
+ * Async run artifact declarations and manifest resolution.
+ * Owns: artifact path template expansion and filesystem-backed artifact metadata.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { substituteCommandTemplateToken } from "./command-templates.js";
+export function resolveArtifactPaths(artifacts, values) {
+    if (!artifacts)
+        return undefined;
+    const resolved = {};
+    for (const [key, value] of Object.entries(artifacts)) {
+        if (!key.trim())
+            continue;
+        if (typeof value === "string") {
+            resolved[key] = substituteCommandTemplateToken(value, values, `recipe artifacts.${key}`);
+        }
+        else if (value &&
+            typeof value === "object" &&
+            typeof value.path === "string") {
+            resolved[key] = {
+                ...value,
+                path: substituteCommandTemplateToken(value.path, values, `recipe artifacts.${key}.path`),
+            };
+        }
+    }
+    return Object.keys(resolved).length > 0 ? resolved : undefined;
+}
+export function resolveArtifactManifest(artifacts) {
+    if (!artifacts)
+        return undefined;
+    const manifest = {};
+    for (const [name, artifact] of Object.entries(artifacts)) {
+        const declaration = typeof artifact === "string" ? { path: artifact } : artifact;
+        if (!declaration?.path)
+            continue;
+        try {
+            const content = readFileSync(declaration.path);
+            manifest[name] = {
+                exists: true,
+                ...(declaration.kind ? { kind: declaration.kind } : {}),
+                ...(declaration.media_type
+                    ? { media_type: declaration.media_type }
+                    : {}),
+                path: declaration.path,
+                ...(declaration.required !== undefined
+                    ? { required: declaration.required }
+                    : {}),
+                sha256: createHash("sha256").update(content).digest("hex"),
+                size: content.byteLength,
+            };
+        }
+        catch {
+            manifest[name] = {
+                exists: false,
+                ...(declaration.kind ? { kind: declaration.kind } : {}),
+                ...(declaration.media_type
+                    ? { media_type: declaration.media_type }
+                    : {}),
+                path: declaration.path,
+                ...(declaration.required !== undefined
+                    ? { required: declaration.required }
+                    : {}),
+            };
+        }
+    }
+    return Object.keys(manifest).length > 0 ? manifest : undefined;
+}

package/node_modules/@llblab/pi-actors/dist/lib/runs-control-delivery.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Run Control delivery.
+ * Zones: generation-fenced endpoint resolution, FIFO/named-pipe writes, durable outcomes
+ * Owns delivery of persisted actor-local Controls to ready service endpoints.
+ */
+export interface RunControlEndpoint {
+    path: string;
+    type: "fifo" | "named-pipe";
+}
+export interface DeliverRunControlOptions {
+    namedPipeSend?: (path: string, payload: string) => Promise<number>;
+    platform?: NodeJS.Platform;
+}
+export interface DeliverRunControlRequest {
+    action: string;
+    input?: unknown;
+    run_instance_id: string;
+}
+export declare function encodeRunControlWire(wire: {
+    action: string;
+    id: string;
+    input?: unknown;
+}): {
+    bytes: number;
+    payload: string;
+};
+export declare function readRunControlEndpoint(stateDir: string, runInstanceId: string): RunControlEndpoint | undefined;
+export declare function deliverRunControl(run: string, stateDir: string, request: DeliverRunControlRequest, options?: DeliverRunControlOptions): Promise<Record<string, unknown>>;

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

@@ -0,0 +1,150 @@
+/**
+ * Run Control delivery.
+ * Zones: generation-fenced endpoint resolution, FIFO/named-pipe writes, durable outcomes
+ * Owns delivery of persisted actor-local Controls to ready service endpoints.
+ */
+import { closeSync, constants, existsSync, openSync, statSync, writeSync, } from "node:fs";
+import { createConnection } from "node:net";
+import { join } from "node:path";
+import * as Control from "./control.js";
+import * as Limits from "./limits.js";
+import { appendRunControlInStateDir, updateRunControlStatusInStateDir, } from "./runs-controls.js";
+import { readJsonFileResilient } from "./state-readers.js";
+const PREFLIGHT_CONTROL_ID = "00000000-0000-4000-8000-000000000000";
+export function encodeRunControlWire(wire) {
+    const payload = `${JSON.stringify({
+        id: wire.id,
+        action: wire.action,
+        ...(wire.input !== undefined ? { input: wire.input } : {}),
+    })}\n`;
+    const bytes = Buffer.byteLength(payload);
+    if (bytes > Limits.CONTROL_WIRE_MAX_BYTES) {
+        throw new Error(`Run Control wire record exceeds the ${Limits.CONTROL_WIRE_MAX_BYTES}-byte portable bound`);
+    }
+    return { bytes, payload };
+}
+export function readRunControlEndpoint(stateDir, runInstanceId) {
+    const endpoint = readJsonFileResilient(join(stateDir, "control-endpoint.json"), {}).value;
+    if (endpoint.run_instance_id !== runInstanceId)
+        return undefined;
+    if ((endpoint.type === "fifo" || endpoint.type === "named-pipe") &&
+        typeof endpoint.path === "string" &&
+        endpoint.path.trim()) {
+        return { path: endpoint.path, type: endpoint.type };
+    }
+    return undefined;
+}
+function sendToFifo(endpoint, payload) {
+    if (!existsSync(endpoint.path))
+        throw new Error(`Run Control FIFO not found: ${endpoint.path}`);
+    const stat = statSync(endpoint.path);
+    if ((stat.mode & constants.S_IFMT) !== constants.S_IFIFO) {
+        throw new Error(`Run Control endpoint is not a FIFO: ${endpoint.path}`);
+    }
+    let fd;
+    try {
+        fd = openSync(endpoint.path, constants.O_WRONLY | constants.O_NONBLOCK);
+        return writeSync(fd, payload);
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function sendToNamedPipe(endpoint, payload, send) {
+    if (send)
+        return send(endpoint.path, payload);
+    return new Promise((resolve, reject) => {
+        const socket = createConnection(endpoint.path);
+        let settled = false;
+        const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            reject(new Error("named pipe connection timed out"));
+        }, 5000);
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (error)
+                reject(error);
+            else
+                resolve(Buffer.byteLength(payload));
+        };
+        socket.on("error", finish);
+        socket.on("connect", () => socket.end(payload, () => finish()));
+    });
+}
+export async function deliverRunControl(run, stateDir, request, options = {}) {
+    const action = Control.normalizeControlAction(request.action);
+    const input = request.input === undefined
+        ? undefined
+        : Control.normalizeControlInput(request.input);
+    const normalizedRequest = {
+        action,
+        ...(input !== undefined ? { input } : {}),
+        run_instance_id: request.run_instance_id,
+    };
+    encodeRunControlWire({
+        id: PREFLIGHT_CONTROL_ID,
+        action,
+        ...(input !== undefined ? { input } : {}),
+    });
+    const control = appendRunControlInStateDir(stateDir, normalizedRequest);
+    const endpoint = readRunControlEndpoint(stateDir, request.run_instance_id);
+    if (!endpoint) {
+        updateRunControlStatusInStateDir(stateDir, control.id, "failed", { error: "control endpoint is not ready for this Run generation" }, ["queued", "delivered"]);
+        throw Object.assign(new Error("Run Control endpoint is not ready."), {
+            action,
+            control_id: control.id,
+            reason: "endpoint_not_ready",
+            run,
+            run_instance_id: request.run_instance_id,
+        });
+    }
+    try {
+        const { bytes, payload } = encodeRunControlWire({
+            id: control.id,
+            action,
+            ...(input !== undefined ? { input } : {}),
+        });
+        let written;
+        if (endpoint.type === "fifo") {
+            if ((options.platform ?? process.platform) === "win32") {
+                throw new Error("FIFO Control delivery is unsupported on native Windows");
+            }
+            written = sendToFifo(endpoint, payload);
+        }
+        else {
+            written = await sendToNamedPipe(endpoint, payload, options.namedPipeSend);
+        }
+        if (written !== bytes) {
+            throw new Error(`Run Control endpoint wrote ${written} of ${bytes} bytes`);
+        }
+        updateRunControlStatusInStateDir(stateDir, control.id, "delivered");
+        return {
+            action,
+            bytes,
+            control_id: control.id,
+            delivery: "delivered",
+            endpoint_type: endpoint.type,
+            run,
+            run_instance_id: request.run_instance_id,
+        };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        updateRunControlStatusInStateDir(stateDir, control.id, "failed", { error: reason }, ["queued", "delivered"]);
+        throw Object.assign(new Error(`Run Control delivery failed: ${reason}`), {
+            action,
+            control_id: control.id,
+            endpoint_type: endpoint.type,
+            reason: "delivery_failed",
+            run,
+            run_instance_id: request.run_instance_id,
+        });
+    }
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Async run process control primitives.
+ * Owns: platform signal planning, owned-process signalling, and terminal control markers.
+ */
+import { spawnSync } from "node:child_process";
+import { type RunProcessIdentity, type RunProcessIdentityResult } from "./runs-process.ts";
+export interface RunProcessSignalPlan {
+    args?: string[];
+    command?: string;
+    signalTarget: "processGroup" | "process" | "processTree";
+}
+export declare function getRunProcessSignalPlan(pid: number, signal: NodeJS.Signals, runtimePlatform?: NodeJS.Platform): RunProcessSignalPlan;
+export interface RunProcessSignalDeps {
+    killProcess?: typeof process.kill;
+    runtimePlatform?: NodeJS.Platform;
+    spawnProcess?: typeof spawnSync;
+    verifyIdentity?: (pid: number, expected: RunProcessIdentity, runtimePlatform: NodeJS.Platform) => RunProcessIdentityResult;
+}
+export declare function signalOwnedRunProcess(pid: number, signal: NodeJS.Signals, expectedIdentity?: RunProcessIdentity, deps?: RunProcessSignalDeps): RunProcessSignalPlan;
+export declare function markTerminalHandled(stateDir: string, details: Record<string, unknown>): void;
+export declare function buildTerminalProgress(existing: Record<string, unknown> | undefined, phase: "cancelled" | "killed"): Record<string, unknown>;

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

@@ -0,0 +1,89 @@
+/**
+ * Async run process control primitives.
+ * Owns: platform signal planning, owned-process signalling, and terminal control markers.
+ */
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { writeJsonAtomic } from "./file-state.js";
+import { verifyRunProcessIdentity, } from "./runs-process.js";
+export function getRunProcessSignalPlan(pid, signal, runtimePlatform = process.platform) {
+    if (runtimePlatform === "win32") {
+        return {
+            args: [
+                "/PID",
+                String(pid),
+                "/T",
+                ...(signal === "SIGKILL" ? ["/F"] : []),
+            ],
+            command: "taskkill",
+            signalTarget: "processTree",
+        };
+    }
+    return { signalTarget: "processGroup" };
+}
+export function signalOwnedRunProcess(pid, signal, expectedIdentity, deps = {}) {
+    const runtimePlatform = deps.runtimePlatform ?? process.platform;
+    if (expectedIdentity) {
+        const proof = (deps.verifyIdentity ?? verifyRunProcessIdentity)(pid, expectedIdentity, runtimePlatform);
+        if (!proof.valid) {
+            throw new Error(`Run process identity changed before signaling: ${proof.status.replaceAll("_", " ")}`);
+        }
+    }
+    const plan = getRunProcessSignalPlan(pid, signal, runtimePlatform);
+    if (plan.command && plan.args) {
+        const spawnProcess = deps.spawnProcess ?? spawnSync;
+        let result = spawnProcess(plan.command, plan.args, { encoding: "utf8" });
+        if (runtimePlatform === "win32" &&
+            result.status !== 0 &&
+            !plan.args.includes("/F")) {
+            result = spawnProcess(plan.command, [...plan.args, "/F"], {
+                encoding: "utf8",
+            });
+        }
+        if (result.status !== 0) {
+            if (expectedIdentity) {
+                const finalProof = (deps.verifyIdentity ?? verifyRunProcessIdentity)(pid, expectedIdentity, runtimePlatform);
+                if (finalProof.status === "dead_pid")
+                    return plan;
+            }
+            throw new Error(result.stderr?.trim() ||
+                result.stdout?.trim() ||
+                `${plan.command} failed`);
+        }
+        return plan;
+    }
+    const killProcess = deps.killProcess ?? process.kill.bind(process);
+    try {
+        killProcess(-pid, signal);
+        return { signalTarget: "processGroup" };
+    }
+    catch (error) {
+        if (error.code !== "ESRCH")
+            throw error;
+        if (expectedIdentity) {
+            const fallbackProof = (deps.verifyIdentity ?? verifyRunProcessIdentity)(pid, expectedIdentity, runtimePlatform);
+            if (!fallbackProof.valid) {
+                throw new Error(`Run process identity changed before pid fallback: ${fallbackProof.status.replaceAll("_", " ")}`);
+            }
+        }
+        killProcess(pid, signal);
+        return { signalTarget: "process" };
+    }
+}
+export function markTerminalHandled(stateDir, details) {
+    writeJsonAtomic(join(stateDir, "terminal-handled.json"), {
+        ...details,
+        ts: new Date().toISOString(),
+    });
+}
+export function buildTerminalProgress(existing, phase) {
+    const progress = existing ?? {};
+    const { activeSubagents: _activeSubagents, ...rest } = progress;
+    return {
+        ...rest,
+        completed: typeof progress.completed === "number" ? progress.completed : 0,
+        failures: Array.isArray(progress.failures) ? progress.failures : [],
+        phase,
+        updatedAt: new Date().toISOString(),
+    };
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Run Control journal.
+ * Zones: durable records, atomic admission, claims, transitions, compaction
+ * Owns Run-local Control persistence; lifecycle authorization and transport stay in adapters.
+ */
+import { type RunControlStatus } from "./run-evidence-policy.ts";
+import type { JsonlReadResult } from "./state-readers.ts";
+export { RUN_CONTROL_TERMINAL_LIMIT } from "./limits.ts";
+export type { RunControlStatus } from "./run-evidence-policy.ts";
+export interface RunControlRecord {
+    id: string;
+    run_instance_id: string;
+    action: string;
+    input?: unknown;
+    status: RunControlStatus;
+    queued_at: string;
+    delivered_at?: string;
+    claimed_at?: string;
+    handled_at?: string;
+    failed_at?: string;
+    error?: string;
+}
+export interface ProcessRunControlsResult {
+    claimed: number;
+    failed: number;
+    handled: number;
+}
+export declare function runControlsFile(stateDir: string): string;
+export declare function readRunControlJournalFromStateDir(stateDir: string): JsonlReadResult<unknown>;
+export declare function readRunControlsFromStateDir(stateDir: string): RunControlRecord[];
+export declare function appendRunControlInStateDir(stateDir: string, request: {
+    run_instance_id: string;
+    action: string;
+    input?: unknown;
+}): RunControlRecord;
+export declare function updateRunControlStatusInStateDir(stateDir: string, id: string, nextStatus: RunControlStatus, metadata?: Pick<RunControlRecord, "error">, expectedStatuses?: readonly RunControlStatus[]): boolean;
+export declare function claimRunControlInStateDir(stateDir: string, runInstanceId: string): RunControlRecord | undefined;
+export declare function claimRunControlByIdInStateDir(stateDir: string, runInstanceId: string, controlId: string): RunControlRecord | undefined;
+export declare function processRunControlsInStateDir(stateDir: string, runInstanceId: string, handler: (control: RunControlRecord) => Promise<void> | void, limit?: number): Promise<ProcessRunControlsResult>;