@llblab/pi-actors 0.42.3 → 0.43.1

package/lib/runtime-identity.ts

@@ -0,0 +1,39 @@
+/**
+ * Immutable runtime package identity.
+ * Zones: source/installed package version resolution and Run-state schema marker
+ * Owns package-local identity reads; runtime status and Run persistence remain in their domains.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const RUN_STATE_SCHEMA = "run-kernel-v1" as const;
+
+let cachedVersion: string | undefined;
+
+export function getPackageVersion(): string {
+  if (cachedVersion) return cachedVersion;
+  const moduleDir = dirname(fileURLToPath(import.meta.url));
+  for (const path of [
+    join(moduleDir, "..", "package.json"),
+    join(moduleDir, "..", "..", "package.json"),
+  ]) {
+    try {
+      const pkg = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+      if (
+        pkg.name === "@llblab/pi-actors" &&
+        typeof pkg.version === "string" &&
+        pkg.version.length > 0 &&
+        pkg.version.length <= 128 &&
+        pkg.version.trim() === pkg.version
+      ) {
+        cachedVersion = pkg.version;
+        return cachedVersion;
+      }
+    } catch {
+      // Source and installed-dist modes resolve through different package ancestors.
+    }
+  }
+  throw new Error("pi-actors package identity is unavailable");
+}

package/lib/runtime-notifier.ts

@@ -1,7 +1,7 @@
 /**
  * Runtime wake notifications for actor state.
  * Zones: advisory wake layer, file-backed runtime state, cross-platform notification boundary
- * Owns best-effort live wake signals while durable mailbox/state files remain canonical.
+ * Owns best-effort live wake signals while durable Run state remains canonical.
  */
 
 import { randomUUID } from "node:crypto";

package/lib/runtime-triage.ts

@@ -0,0 +1,120 @@
+/**
+ * Pure runtime Control triage policy.
+ * Zones: pending admission, status-age classification, terminal/replacement staleness
+ * Owns Control triage decisions; journal reads and owner filtering stay in adapters, while safe fields come from control-projection.
+ */
+
+import * as ControlProjection from "./control-projection.ts";
+import type { RunControlRecord, RunControlStatus } from "./runs-controls.ts";
+
+export const RUNTIME_CONTROL_STALE_AFTER_MS = 5 * 60 * 1_000;
+
+const PENDING_STATUSES = new Set<RunControlStatus>([
+  "queued",
+  "delivered",
+  "claimed",
+]);
+const TERMINAL_STATUSES = new Set<RunControlStatus>(["handled", "failed"]);
+
+export interface RuntimeTriageRun {
+  run: string;
+  runInstanceId?: string;
+  status: string;
+}
+
+export interface RuntimePendingControl
+  extends ControlProjection.ProjectedRunControl {
+  age_ms: number;
+  reason: "age_threshold_reached" | "run_generation_replaced" | "run_generation_unavailable" | "run_terminal" | "within_age_threshold";
+  run: string;
+  status: "queued" | "delivered" | "claimed";
+  status_at: string;
+}
+
+export interface RuntimeControlDiagnostic {
+  reason: "invalid_action" | "invalid_control_id" | "invalid_generation" | "invalid_record" | "invalid_status" | "invalid_status_timestamp";
+  run: string;
+}
+
+export interface RuntimeControlClassification {
+  diagnostic?: RuntimeControlDiagnostic;
+  pending?: RuntimePendingControl;
+  stale?: RuntimePendingControl;
+}
+
+function diagnostic(
+  run: string,
+  reason: RuntimeControlDiagnostic["reason"],
+): RuntimeControlClassification {
+  return { diagnostic: { reason, run } };
+}
+
+function statusTimestamp(
+  record: Record<string, unknown>,
+  status: RunControlStatus,
+): unknown {
+  if (status === "failed") return record.failed_at;
+  if (status === "handled") return record.handled_at;
+  if (status === "claimed") return record.claimed_at;
+  if (status === "delivered") return record.delivered_at;
+  return record.queued_at;
+}
+
+export function classifyRuntimeControl(
+  run: RuntimeTriageRun,
+  value: unknown,
+  nowMs: number,
+): RuntimeControlClassification {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return diagnostic(run.run, "invalid_record");
+  }
+  const record = value as Record<string, unknown>;
+  const status = record.status as RunControlStatus;
+  if (!PENDING_STATUSES.has(status) && !TERMINAL_STATUSES.has(status)) {
+    return diagnostic(run.run, "invalid_status");
+  }
+  if (typeof record.id !== "string" || !record.id) {
+    return diagnostic(run.run, "invalid_control_id");
+  }
+  if (typeof record.action !== "string" || !record.action) {
+    return diagnostic(run.run, "invalid_action");
+  }
+  if (typeof record.run_instance_id !== "string" || !record.run_instance_id) {
+    return diagnostic(run.run, "invalid_generation");
+  }
+  const timestamp = statusTimestamp(record, status);
+  const timestampMs = typeof timestamp === "string" ? Date.parse(timestamp) : Number.NaN;
+  if (!Number.isFinite(timestampMs)) {
+    return diagnostic(run.run, "invalid_status_timestamp");
+  }
+  if (TERMINAL_STATUSES.has(status)) return {};
+  const ageMs = Math.max(0, Math.floor(nowMs - timestampMs));
+  const staleReason: RuntimePendingControl["reason"] | undefined =
+    !run.runInstanceId
+      ? "run_generation_unavailable"
+      : record.run_instance_id !== run.runInstanceId
+        ? "run_generation_replaced"
+        : run.status !== "running"
+          ? "run_terminal"
+          : ageMs >= RUNTIME_CONTROL_STALE_AFTER_MS
+            ? "age_threshold_reached"
+            : undefined;
+  const projected = ControlProjection.projectRunControl(
+    record as unknown as RunControlRecord,
+  );
+  const pending: RuntimePendingControl = {
+    ...projected,
+    age_ms: ageMs,
+    reason: staleReason ?? "within_age_threshold",
+    run: run.run,
+    status: status as RuntimePendingControl["status"],
+    status_at: statusTimestamp(
+      projected as unknown as Record<string, unknown>,
+      status,
+    ) as string,
+  };
+  return {
+    pending,
+    ...(staleReason ? { stale: pending } : {}),
+  };
+}

package/lib/tool-review-scheduler.ts

@@ -404,7 +404,7 @@ export function applyApprovedToolReviewAtSessionBoundary(
         ...state,
         failedStage: "approval_state",
         lastError: "approved review path is unavailable",
-        nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+        nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
         phase: "processing_failed" as const,
         updatedAt: (options.now ?? (() => new Date()))().toISOString(),
       };
@@ -427,7 +427,7 @@ export function applyApprovedToolReviewAtSessionBoundary(
           ...state,
           failedStage: "transaction",
           lastError: `tool review transaction remained ${transaction.phase}`,
-          nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+          nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
           phase: "processing_failed" as const,
           updatedAt: (options.now ?? (() => new Date()))().toISOString(),
         };
@@ -458,7 +458,7 @@ export function applyApprovedToolReviewAtSessionBoundary(
           ...pending,
           failedStage: "lineage",
           lastError: error instanceof Error ? error.message : String(error),
-          nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+          nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
         };
         writeJsonAtomic(statePath, failedPending);
         return { outcome: "lineage_pending", state: failedPending };
@@ -478,7 +478,7 @@ export function applyApprovedToolReviewAtSessionBoundary(
         ...state,
         failedStage: "transaction",
         lastError: error instanceof Error ? error.message : String(error),
-        nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+        nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
         phase: "processing_failed" as const,
         updatedAt: (options.now ?? (() => new Date()))().toISOString(),
       };
@@ -541,7 +541,7 @@ export function createToolReviewScheduler(
           ...existing,
           failedStage: processed.stage ?? "review_result",
           lastError: processed.error ?? "automatic tool reviewer failed",
-          nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+          nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
           phase: processed.outcome === "processing_failed"
             ? "processing_failed"
             : "failed",
@@ -577,7 +577,7 @@ export function createToolReviewScheduler(
             attempts: existing.attempts + 1,
             failedStage: "review_launch",
             lastError: error instanceof Error ? error.message : String(error),
-            nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+            nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
             phase: "failed",
             updatedAt: now().toISOString(),
           } satisfies ToolReviewAdmissionState);
@@ -612,7 +612,7 @@ export function createToolReviewScheduler(
           failedStage: "review_launch",
           inputPath: batch.inputPath,
           lastError: error instanceof Error ? error.message : String(error),
-          nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+          nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
           phase: "failed",
           reviewerInputPath: batch.reviewerInputPath,
           reviewId: batch.reviewId,