@llblab/pi-actors 0.43.0 → 0.44.0

package/lib/trace-projection.ts

@@ -7,19 +7,20 @@
 import { existsSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 
+import * as ControlProjection from "./control-projection.ts";
 import * as ExecutionSessions from "./execution-sessions.ts";
 import * as Limits from "./limits.ts";
 import {
   resolveArtifactManifest,
   type RunArtifactDeclaration,
 } from "./runs-artifacts.ts";
+import * as RunsControls from "./runs-controls.ts";
 import type { RunControlRecord } from "./runs-controls.ts";
 import { tailFile } from "./runs-status.ts";
-import type { TraceEvent } from "./runs-trace.ts";
+import * as RunsTrace from "./runs-trace.ts";
 import * as SessionEvidence from "./session-evidence.ts";
 import {
   readJsonFileResilient,
-  readJsonlFileResilient,
   type StateReadDiagnostic,
 } from "./state-readers.ts";
 
@@ -43,19 +44,52 @@ export interface TraceItem {
   detail: unknown;
 }
 
+interface OrderedTraceItem {
+  item: TraceItem;
+  ordinal: number;
+  sourceKey: string;
+}
+
 const LIFECYCLE_PREFIXES = ["run.", "command."];
 const SOURCE_LIMIT = 100;
+const SOURCE_RANK: Record<TraceSource, number> = {
+  lifecycle: 6,
+  control: 5,
+  process: 4,
+  agent: 3,
+  artifact: 2,
+  runtime: 1,
+};
 
 function redact(value: unknown): unknown {
   return SessionEvidence.redactSessionEvidenceValue(value);
 }
 
-function sourceForEvent(event: TraceEvent): TraceSource {
+function sourceForEvent(event: RunsTrace.TraceEvent): TraceSource {
   return LIFECYCLE_PREFIXES.some((prefix) => event.kind.startsWith(prefix))
     ? "lifecycle"
     : "runtime";
 }
 
+function ordered(
+  item: TraceItem,
+  sourceKey: string,
+  ordinal: number,
+): OrderedTraceItem {
+  return { item, ordinal, sourceKey };
+}
+
+function compareTraceItems(left: OrderedTraceItem, right: OrderedTraceItem): number {
+  const timestamp = right.item.ts.localeCompare(left.item.ts);
+  if (timestamp) return timestamp;
+  if (left.sourceKey === right.sourceKey) {
+    const ordinal = right.ordinal - left.ordinal;
+    if (ordinal) return ordinal;
+  }
+  return SOURCE_RANK[right.item.source] - SOURCE_RANK[left.item.source] ||
+    right.item.id.localeCompare(left.item.id);
+}
+
 function latestControlTimestamp(control: RunControlRecord): string {
   return (
     control.failed_at ??
@@ -78,122 +112,173 @@ function diagnosticItems(diagnostics: StateReadDiagnostic[]): TraceItem[] {
   }));
 }
 
-function traceEventItems(stateDir: string): TraceItem[] {
-  const read = readJsonlFileResilient<TraceEvent>(join(stateDir, "trace.jsonl"));
-  return [
-    ...read.records.slice(-SOURCE_LIMIT).map((event) => ({
-      id: event.id,
-      ts: event.ts,
-      source: sourceForEvent(event),
-      kind: event.kind,
-      summary: event.summary ?? event.kind,
-      ...(event.level ? { level: event.level } : {}),
-      detail: redact({
-        ...(event.attention ? { attention: event.attention } : {}),
-        ...(event.data !== undefined ? { data: event.data } : {}),
-      }),
-    } satisfies TraceItem)),
-    ...diagnosticItems(read.diagnostics),
-  ];
+function controlDiagnosticItems(
+  diagnostics: StateReadDiagnostic[],
+): TraceItem[] {
+  return diagnostics.slice(-SOURCE_LIMIT).map((diagnostic, index) => ({
+    id: `control-diagnostic:${diagnostic.line ?? 0}:${index}`,
+    ts: new Date(0).toISOString(),
+    source: "runtime",
+    kind: "state.read_error",
+    summary: "Malformed or unreadable Control evidence",
+    level: "warning",
+    detail: {
+      ...(diagnostic.line === undefined ? {} : { line: diagnostic.line }),
+      reason: diagnostic.line === undefined
+        ? "unreadable_control_journal"
+        : "invalid_control_json",
+    },
+  }));
 }
 
-function controlItems(stateDir: string): TraceItem[] {
-  const read = readJsonlFileResilient<RunControlRecord>(
-    join(stateDir, "controls.jsonl"),
+function traceEventItems(stateDir: string): OrderedTraceItem[] {
+  const read = RunsTrace.readRunTraceJournal(stateDir);
+  const retained = read.events.slice(-SOURCE_LIMIT);
+  const projected = retained.map(({ event, ordinal }) => ordered({
+    id: event.id,
+    ts: event.ts,
+    source: sourceForEvent(event),
+    kind: event.kind,
+    summary: event.summary ?? event.kind,
+    ...(event.level ? { level: event.level } : {}),
+    detail: redact({
+      ...(event.attention ? { attention: event.attention } : {}),
+      ...(event.data !== undefined ? { data: event.data } : {}),
+    }),
+  }, "trace", ordinal));
+  const diagnostics = diagnosticItems(read.diagnostics).map((item, index) =>
+    ordered(item, "trace", read.events.length + index + 1)
+  );
+  const hasMarker = read.events.some(
+    ({ event }) => event.kind === "runtime.trace_compacted",
   );
+  if (read.omittedPrefixBytes > 0 && !hasMarker) {
+    diagnostics.push(ordered({
+      id: "runtime:trace-history-incomplete",
+      ts: new Date(0).toISOString(),
+      source: "runtime",
+      kind: "runtime.trace_history_incomplete",
+      summary: "Trace history is incomplete",
+      level: "warning",
+      detail: {
+        omitted_prefix_bytes: read.omittedPrefixBytes,
+        read_bytes: read.readBytes,
+        retained_events: read.events.length,
+      },
+    }, "trace", 0));
+  }
+  return [...projected, ...diagnostics];
+}
+
+function controlItems(stateDir: string): OrderedTraceItem[] {
+  const read = RunsControls.readRunControlJournalFromStateDir(stateDir);
+  const start = Math.max(0, read.records.length - SOURCE_LIMIT);
+  const projected = read.records.slice(start).map((control, index) => {
+    const value = ControlProjection.projectRunControl(control as RunControlRecord);
+    return ordered({
+      id: `control:${value.id}`,
+      ts: latestControlTimestamp(value),
+      source: "control",
+      kind: `control.${value.status}`,
+      summary: `${value.action} ${value.status}`,
+      ...(value.status === "failed" ? { level: "error" as const } : {}),
+      detail: value,
+    }, "control", start + index + 1);
+  });
   return [
-    ...read.records.slice(-SOURCE_LIMIT).map((control) => ({
-      id: `control:${control.id}`,
-      ts: latestControlTimestamp(control),
-      source: "control" as const,
-      kind: `control.${control.status}`,
-      summary: `${control.action} ${control.status}`,
-      ...(control.status === "failed" ? { level: "error" as const } : {}),
-      detail: redact(control),
-    })),
-    ...diagnosticItems(read.diagnostics),
+    ...projected,
+    ...controlDiagnosticItems(read.diagnostics).map((item, index) =>
+      ordered(item, "control", read.records.length + index + 1)
+    ),
   ];
 }
 
-function agentItems(stateDir: string): TraceItem[] {
+function agentItems(stateDir: string): OrderedTraceItem[] {
   return ExecutionSessions.readExecutionTurns(stateDir)
     .slice(-SOURCE_LIMIT)
     .map((turn) => {
       const text = turn.assistantText ?? turn.userText ?? "Agent turn";
       const summary = text.replaceAll(/\s+/g, " ").trim().slice(0, 160);
-      return {
+      return ordered({
         id: `agent:${turn.commandId}:${turn.sessionFile}:${turn.index}`,
         ts: turn.timestamp ?? new Date(0).toISOString(),
-        source: "agent" as const,
+        source: "agent",
         kind: "agent.turn",
         summary: summary || "Agent turn",
         ...(turn.error ? { level: "error" as const } : {}),
         detail: redact(turn),
-      };
+      }, "agent", turn.index);
     });
 }
 
-function processItems(stateDir: string): TraceItem[] {
+function processItems(stateDir: string): OrderedTraceItem[] {
   return ["stdout", "stderr"].flatMap((stream) => {
     const path = join(stateDir, `${stream}.log`);
     if (!existsSync(path)) return [];
     const stat = statSync(path);
     const tail = tailFile(path, Limits.DEFAULT_INSPECT_LINES);
     if (!tail && stat.size === 0) return [];
-    return [{
+    return [ordered({
       id: `process:${stream}`,
       ts: stat.mtime.toISOString(),
-      source: "process" as const,
+      source: "process",
       kind: `process.${stream}`,
       summary: `${stream} (${stat.size} bytes)`,
       ...(stream === "stderr" ? { level: "warning" as const } : {}),
       detail: redact({ bytes: stat.size, path, tail }),
-    }];
+    }, `process:${stream}`, 1)];
   });
 }
 
-function resultItems(stateDir: string): TraceItem[] {
+function resultItems(stateDir: string): OrderedTraceItem[] {
   const path = join(stateDir, "result.json");
   const read = readJsonFileResilient<Record<string, unknown>>(path, {});
-  if (Object.keys(read.value).length === 0) return diagnosticItems(read.diagnostics);
+  if (Object.keys(read.value).length === 0) {
+    return diagnosticItems(read.diagnostics).map((item, index) =>
+      ordered(item, "process:result", index)
+    );
+  }
   const stat = statSync(path);
   const failed = Number(read.value.code ?? 0) !== 0;
-  return [{
+  return [ordered({
     id: "process:result",
-    ts:
-      typeof read.value.completedAt === "string"
-        ? read.value.completedAt
-        : stat.mtime.toISOString(),
+    ts: typeof read.value.completedAt === "string"
+      ? read.value.completedAt
+      : stat.mtime.toISOString(),
     source: "process",
     kind: failed ? "process.failed" : "process.result",
     summary: failed ? "Run process failed" : "Run process completed",
     ...(failed ? { level: "error" as const } : {}),
     detail: redact(read.value),
-  }, ...diagnosticItems(read.diagnostics)];
+  }, "process:result", 1), ...diagnosticItems(read.diagnostics).map(
+    (item, index) => ordered(item, "process:result", index + 2),
+  )];
 }
 
 function artifactItems(
   stateDir: string,
   declarations: Record<string, RunArtifactDeclaration> | undefined,
-): TraceItem[] {
+): OrderedTraceItem[] {
   const manifest = resolveArtifactManifest(declarations);
   if (!manifest) return [];
-  return Object.entries(manifest).slice(0, SOURCE_LIMIT).map(([name, artifact]) => ({
-    id: `artifact:${name}`,
-    ts: artifact.exists && existsSync(artifact.path)
-      ? statSync(artifact.path).mtime.toISOString()
-      : new Date(0).toISOString(),
-    source: "artifact",
-    kind: artifact.exists ? "artifact.ready" : "artifact.missing",
-    summary: `${name}: ${artifact.exists ? "ready" : "missing"}`,
-    ...(artifact.required && !artifact.exists ? { level: "warning" as const } : {}),
-    detail: redact({
-      exists: artifact.exists,
-      path: relative(stateDir, artifact.path).replaceAll("\\", "/"),
-      required: artifact.required,
-      ...(artifact.size !== undefined ? { size: artifact.size } : {}),
-    }),
-  }));
+  return Object.entries(manifest).slice(0, SOURCE_LIMIT).map(
+    ([name, artifact], index) => ordered({
+      id: `artifact:${name}`,
+      ts: artifact.exists && existsSync(artifact.path)
+        ? statSync(artifact.path).mtime.toISOString()
+        : new Date(0).toISOString(),
+      source: "artifact",
+      kind: artifact.exists ? "artifact.ready" : "artifact.missing",
+      summary: `${name}: ${artifact.exists ? "ready" : "missing"}`,
+      ...(artifact.required && !artifact.exists ? { level: "warning" as const } : {}),
+      detail: redact({
+        exists: artifact.exists,
+        path: relative(stateDir, artifact.path).replaceAll("\\", "/"),
+        required: artifact.required,
+        ...(artifact.size !== undefined ? { size: artifact.size } : {}),
+      }),
+    }, "artifact", index + 1),
+  );
 }
 
 export function projectRunTrace(
@@ -213,9 +298,9 @@ export function projectRunTrace(
     ...resultItems(stateDir),
     ...artifactItems(stateDir, options.artifacts),
   ]
-    .filter((item) => source === "all" || item.source === source)
-    .sort((left, right) =>
-      right.ts.localeCompare(left.ts) || right.id.localeCompare(left.id),
-    );
-  return items.slice(0, Math.max(1, Math.min(options.limit ?? 100, 200)));
+    .filter(({ item }) => source === "all" || item.source === source)
+    .sort(compareTraceItems);
+  return items
+    .slice(0, Math.max(1, Math.min(options.limit ?? 100, 200)))
+    .map(({ item }) => item);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [

package/scripts/conformance.mjs

@@ -15,6 +15,11 @@ const conformanceSuites = [
   "tests/control.test.ts",
   "tests/runs-controls.test.ts",
   "tests/runs-trace.test.ts",
+  "tests/observability.test.ts",
+  "tests/async-run-control.test.ts",
+  "tests/run-kernel-dogfood.test.ts",
+  "tests/installed.scripts.test.ts",
+  "tests/inspector-overlay.test.ts",
   "tests/tools-inspect-kernel.test.ts",
   "tests/recipes-discovery.test.ts",
   "tests/review-swarm-dogfood.test.ts",

package/scripts/locker.mjs

@@ -9,13 +9,11 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { createHash, randomUUID } from "node:crypto";
+import { createHash } from "node:crypto";
 import {
-  appendFileSync,
   existsSync,
   mkdirSync,
   readFileSync,
-  rmSync,
 } from "node:fs";
 import { createServer } from "node:net";
 import { dirname, join, resolve } from "node:path";
@@ -33,8 +31,13 @@ async function importRuntimeModule(name) {
   return await import(pathToFileURL(existsSync(compiled) ? compiled : source).href);
 }
 
-const { acquireFileMutationLock, writeJsonAtomic, writeTextAtomic } =
-  await importRuntimeModule("file-state");
+const { acquireFileMutationLock, writeJsonAtomic, writeTextAtomic } = await importRuntimeModule("file-state");
+const { readJsonlFileResilient } = await importRuntimeModule("state-readers");
+const LOCKER_JOURNAL_MAX_RECORDS = 512;
+const LOCKER_JOURNAL_MAX_BYTES = 1024 * 1024;
+const { claimRunControlByIdInStateDir, updateRunControlStatusInStateDir } =
+  await importRuntimeModule("runs-controls");
+const { appendRunTraceEvent } = await importRuntimeModule("runs-trace");
 
 function parseArgs(argv) {
   const args = { mode: "serve", stateDir: "", leaseMs: 600000, lines: 20 };
@@ -59,8 +62,6 @@ async function runLocker(argv = process.argv.slice(2)) {
   const queuePath = join(stateDir, "queue.json");
   const locksPath = join(stateDir, "locks.json");
   const journalPath = join(stateDir, "journal.jsonl");
-  const tracePath = join(stateDir, "trace.jsonl");
-  const controlsPath = join(stateDir, "controls.jsonl");
   const controlPath = join(stateDir, "control.fifo");
   let runInstanceId;
   mkdirSync(stateDir, { recursive: true });
@@ -97,25 +98,32 @@ async function runLocker(argv = process.argv.slice(2)) {
   }
 
   function journal(event, data = {}) {
-    appendFileSync(
-      journalPath,
-      `${JSON.stringify({ event, ts: new Date().toISOString(), ...data })}\n`,
-    );
+    const release = acquireFileMutationLock(journalPath);
+    try {
+      const records = [...readJsonlFileResilient(journalPath).records,
+        { event, ts: new Date().toISOString(), ...data }]
+        .slice(-LOCKER_JOURNAL_MAX_RECORDS);
+      let content = encodeJournal(records);
+      while (records.length && Buffer.byteLength(content) > LOCKER_JOURNAL_MAX_BYTES) {
+        records.shift();
+        content = encodeJournal(records);
+      }
+      writeTextAtomic(journalPath, content);
+    } finally { release(); }
+  }
+
+  function encodeJournal(records) {
+    return records.length ? `${records.map((record) => JSON.stringify(record)).join("\n")}\n` : "";
   }
 
   function emitTrace(kind, summary, data = {}, level = "info") {
-    appendFileSync(
-      tracePath,
-      `${JSON.stringify({
-        attention: "followup",
-        data,
-        id: randomUUID(),
-        kind,
-        level,
-        summary,
-        ts: new Date().toISOString(),
-      })}\n`,
-    );
+    appendRunTraceEvent(stateDir, {
+      attention: "followup",
+      data,
+      kind,
+      level,
+      summary,
+    });
   }
 
   function now() {
@@ -153,69 +161,6 @@ async function runLocker(argv = process.argv.slice(2)) {
     }
   }
 
-  function acquireControlsLock() {
-    return acquireFileMutationLock(controlsPath);
-  }
-
-  function readControls() {
-    if (!existsSync(controlsPath)) return [];
-    return readFileSync(controlsPath, "utf8")
-      .split("\n")
-      .filter((line) => line.trim())
-      .map((line) => {
-        try {
-          return JSON.parse(line);
-        } catch {
-          return undefined;
-        }
-      })
-      .filter(Boolean);
-  }
-
-  function writeControls(controls) {
-    writeTextAtomic(
-      controlsPath,
-      controls.length
-        ? `${controls.map((control) => JSON.stringify(control)).join("\n")}\n`
-        : "",
-    );
-  }
-
-  function claimControl(id) {
-    const release = acquireControlsLock();
-    try {
-      const controls = readControls();
-      const control = controls.find((item) => item.id === id);
-      if (
-        !control ||
-        control.run_instance_id !== runInstanceId ||
-        (control.status !== "queued" && control.status !== "delivered")
-      ) {
-        return undefined;
-      }
-      control.claimed_at = new Date().toISOString();
-      control.status = "claimed";
-      writeControls(controls);
-      return { ...control };
-    } finally {
-      release();
-    }
-  }
-
-  function finalizeControl(id, status, error) {
-    const release = acquireControlsLock();
-    try {
-      const controls = readControls();
-      const control = controls.find((item) => item.id === id);
-      if (!control || control.status !== "claimed") return;
-      control.status = status;
-      control[`${status}_at`] = new Date().toISOString();
-      if (error) control.error = error;
-      writeControls(controls);
-    } finally {
-      release();
-    }
-  }
 
   function tailJournal(count) {
     if (!existsSync(journalPath)) return [];
@@ -403,7 +348,9 @@ async function runLocker(argv = process.argv.slice(2)) {
   function handleLine(line) {
     const control = normalizeControl(line);
     if (!control) return false;
-    const claimed = claimControl(control.id);
+    const claimed = claimRunControlByIdInStateDir(
+      stateDir, runInstanceId, control.id,
+    );
     if (!claimed) {
       emitTrace(
         "lock.control_rejected",
@@ -415,11 +362,15 @@ async function runLocker(argv = process.argv.slice(2)) {
     }
     try {
       const stopping = handle(claimed) === true;
-      finalizeControl(claimed.id, "handled");
+      updateRunControlStatusInStateDir(
+        stateDir, claimed.id, "handled", {}, ["claimed"],
+      );
       return stopping;
     } catch (error) {
       const text = error instanceof Error ? error.message : String(error);
-      finalizeControl(claimed.id, "failed", text);
+      updateRunControlStatusInStateDir(
+        stateDir, claimed.id, "failed", { error: text }, ["claimed"],
+      );
       journal("lock.error", { error: text });
       emitTrace("lock.error", text, { error: text }, "error");
       return false;
@@ -454,7 +405,6 @@ async function runLocker(argv = process.argv.slice(2)) {
   }
 
   async function serveNamedPipe(endpoint) {
-    rmSync(endpoint.path, { force: true });
     let resolveStopped;
     const stopped = new Promise((resolve) => {
       resolveStopped = resolve;