@llblab/pi-actors 0.43.0 → 0.44.0

package/lib/runtime-triage.ts

@@ -0,0 +1,106 @@
+/**
+ * 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 {
+  classifyRunControlRecord,
+  runControlStatusTimestamp,
+  type RunControlStatus,
+} from "./run-evidence-policy.ts";
+import type { RunControlRecord } from "./runs-controls.ts";
+
+export const RUNTIME_CONTROL_STALE_AFTER_MS = 5 * 60 * 1_000;
+
+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 } };
+}
+
+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;
+  const recordClass = classifyRunControlRecord(record);
+  if (!recordClass) 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 = runControlStatusTimestamp(record, status);
+  const timestampMs = typeof timestamp === "string" ? Date.parse(timestamp) : Number.NaN;
+  if (!Number.isFinite(timestampMs)) {
+    return diagnostic(run.run, "invalid_status_timestamp");
+  }
+  if (recordClass === "terminal") 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: runControlStatusTimestamp(
+      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,

package/lib/tools-inspect.ts

@@ -4,17 +4,22 @@
  * Owns exact inspect target/view dispatch; source projection stays in domain modules.
  */
 
+import { statSync } from "node:fs";
 import { join } from "node:path";
 
 import * as AsyncRuns from "./async-runs.ts";
+import * as ControlProjection from "./control-projection.ts";
 import * as Inspector from "./inspector.ts";
 import * as Limits from "./limits.ts";
+import { computeRunControlCapacity } from "./run-evidence-policy.ts";
 import * as Paths from "./paths.ts";
 import * as RecipesDiscovery from "./recipes-discovery.ts";
 import * as ReviewDiagnostics from "./review-diagnostics.ts";
 import * as RunsControls from "./runs-controls.ts";
 import * as RunControlDelivery from "./runs-control-delivery.ts";
 import * as RunsTrace from "./runs-trace.ts";
+import * as RuntimeIdentity from "./runtime-identity.ts";
+import * as RuntimeTriage from "./runtime-triage.ts";
 import * as Schema from "./schema.ts";
 import * as ToolsAccess from "./tools-access.ts";
 import * as ToolsResponse from "./tools-response.ts";
@@ -35,7 +40,8 @@ function runtimeStatus(): Record<string, unknown> {
   return {
     automatic_review: process.env.PI_ACTORS_AUTOMATIC_REVIEW !== "off",
     run_root: Paths.getRunStateRoot(),
-    version: process.env.npm_package_version ?? "unknown",
+    state_schema: RuntimeIdentity.RUN_STATE_SCHEMA,
+    version: RuntimeIdentity.getPackageVersion(),
   };
 }
 
@@ -69,13 +75,45 @@ function runtimeTriage(
   const inventory = runtimeRuns(ctx, deps, undefined);
   const runs = inventory.runs as Array<Record<string, unknown>>;
   const failed = runs.filter((run) => run.status === "failed");
-  const staleControls = runs.flatMap((run) => {
+  const pendingControls: RuntimeTriage.RuntimePendingControl[] = [];
+  const staleControls: RuntimeTriage.RuntimePendingControl[] = [];
+  const backpressuredRuns: Array<Record<string, unknown>> = [];
+  const controlDiagnostics: Array<Record<string, unknown>> = [];
+  const traceDiagnostics: Array<Record<string, unknown>> = [];
+  const nowMs = Date.now();
+  for (const run of runs) {
     const stateDir = typeof run.state_dir === "string" ? run.state_dir : undefined;
-    if (!stateDir) return [];
-    return RunsControls.readRunControlsFromStateDir(stateDir)
-      .filter((control) => control.status === "queued" || control.status === "claimed")
-      .map((control) => ({ run: run.run, control }));
-  });
+    if (!stateDir) continue;
+    const runId = String(run.run ?? "unknown");
+    const journal = RunsControls.readRunControlJournalFromStateDir(stateDir);
+    const capacity = computeRunControlCapacity(journal.records);
+    controlDiagnostics.push(...journal.diagnostics.map((diagnostic) => ({
+      ...(diagnostic.line === undefined ? {} : { line: diagnostic.line }),
+      reason: diagnostic.line === undefined ? "unreadable_control_journal" : "invalid_control_json", run: runId,
+    })));
+    if (capacity.backpressured) backpressuredRuns.push({
+      run: runId, pending: capacity.pending, pending_limit: capacity.limit,
+      journal_bytes: statSync(RunsControls.runControlsFile(stateDir)).size,
+    });
+    const traceSummary = RunsTrace.summarizeRunTraceJournal(RunsTrace.readRunTraceJournal(stateDir));
+    if (!traceSummary.history_complete) traceDiagnostics.push({ run: runId, ...traceSummary });
+    for (const control of journal.records) {
+      const classified = RuntimeTriage.classifyRuntimeControl(
+        {
+          run: runId,
+          ...(typeof run.run_instance_id === "string"
+            ? { runInstanceId: run.run_instance_id }
+            : {}),
+          status: String(run.status ?? "unknown"),
+        },
+        control,
+        nowMs,
+      );
+      if (classified.pending) pendingControls.push(classified.pending);
+      if (classified.stale) staleControls.push(classified.stale);
+      if (classified.diagnostic) controlDiagnostics.push({ ...classified.diagnostic });
+    }
+  }
   const attentionEvents = runs.flatMap((run) => {
     const stateDir = typeof run.state_dir === "string" ? run.state_dir : undefined;
     if (!stateDir) return [];
@@ -90,18 +128,32 @@ function runtimeTriage(
         ts: event.ts,
       }));
   });
+  const boundedStaleControls = staleControls.slice(0, 40);
+  const staleKeys = new Set(boundedStaleControls.map((control) =>
+    `${control.run}\0${control.run_instance_id}\0${control.id}`,
+  ));
+  const boundedPendingControls = [
+    ...boundedStaleControls,
+    ...pendingControls.filter((control) =>
+      !staleKeys.has(`${control.run}\0${control.run_instance_id}\0${control.id}`),
+    ),
+  ].slice(0, 40);
   return {
     ...inventory,
     failed_runs: failed,
-    stale_controls: staleControls.slice(0, 40),
+    pending_control_count: pendingControls.length,
+    pending_controls: boundedPendingControls,
+    stale_control_count: staleControls.length,
+    stale_controls: boundedStaleControls,
+    backpressured_run_count: backpressuredRuns.length, backpressured_runs: backpressuredRuns.slice(0, 40),
+    control_diagnostic_count: controlDiagnostics.length, control_diagnostics: controlDiagnostics.slice(0, 40),
+    trace_diagnostic_count: traceDiagnostics.length, trace_diagnostics: traceDiagnostics.slice(0, 40),
     attention_events: attentionEvents.slice(-40).reverse(),
     next_actions: [
       ...(failed.length ? ["inspect target=runtime view=runs status=failed"] : []),
-      ...(staleControls.length
-        ? staleControls.slice(0, 3).map((entry) =>
-            `inspect target=run:${String(entry.run)} view=control`,
-          )
-        : []),
+      ...new Set([...staleControls, ...backpressuredRuns].slice(0, 3).map((entry) =>
+        `inspect target=run:${entry.run} view=control`,
+      )),
       ...(attentionEvents.length
         ? attentionEvents.slice(-3).map((entry) =>
             `inspect target=run:${String(entry.run)} view=trace source=runtime`,
@@ -116,9 +168,9 @@ function compactRuntime(view: string, details: Record<string, unknown>): string
     return `\nruntime runs=${(details.runs as unknown[] | undefined)?.length ?? 0}`;
   }
   if (view === "triage") {
-    return `\nruntime failed=${(details.failed_runs as unknown[] | undefined)?.length ?? 0} stale_controls=${(details.stale_controls as unknown[] | undefined)?.length ?? 0} attention=${(details.attention_events as unknown[] | undefined)?.length ?? 0}`;
+    return `\nruntime failed=${(details.failed_runs as unknown[] | undefined)?.length ?? 0} pending_controls=${Number(details.pending_control_count ?? 0)} stale_controls=${Number(details.stale_control_count ?? 0)} backpressured=${Number(details.backpressured_run_count ?? 0)} incomplete_trace=${Number(details.trace_diagnostic_count ?? 0)} attention=${(details.attention_events as unknown[] | undefined)?.length ?? 0}`;
   }
-  return `\nruntime version=${String(details.version ?? "unknown")} automatic_review=${String(details.automatic_review)}`;
+  return `\nruntime version=${String(details.version)} state_schema=${String(details.state_schema)} automatic_review=${String(details.automatic_review)}`;
 }
 
 function inspectRuntime(
@@ -209,8 +261,8 @@ function inspectRun(
       throw new Error(`unsupported Trace source: ${source}`);
     }
     return {
-      run,
-      source,
+      run, source,
+      summary: RunsTrace.summarizeRunTraceJournal(RunsTrace.readRunTraceJournal(stateDir)),
       items: TraceProjection.projectRunTrace(stateDir, {
         artifacts: status.artifacts as
           | Record<string, AsyncRuns.RunArtifactDeclaration>
@@ -221,18 +273,40 @@ function inspectRun(
     };
   }
   const runInstanceId = String(status.run_instance_id ?? "");
+  const journal = RunsControls.readRunControlJournalFromStateDir(stateDir);
+  const capacity = computeRunControlCapacity(journal.records);
+  const structuralDiagnostics = journal.records.flatMap((value) => {
+    const classified = RuntimeTriage.classifyRuntimeControl({ run,
+      runInstanceId: runInstanceId || undefined, status: String(status.status ?? "unknown") }, value, Date.now());
+    return classified.diagnostic ? [classified.diagnostic.reason] : [];
+  });
+  let journalBytes = 0;
+  try { journalBytes = statSync(RunsControls.runControlsFile(stateDir)).size; } catch {}
+  const diagnostics = [...journal.diagnostics.map((item) => ({
+    ...(item.line === undefined ? {} : { line: item.line }),
+    reason: item.line === undefined ? "unreadable_control_journal" : "invalid_control_json",
+  })), ...structuralDiagnostics.map((reason) => ({ reason }))].slice(0, 40);
+  const nowMs = Date.now();
+  const stalePending = journal.records.reduce<number>((count, control) => count + Number(Boolean(
+    RuntimeTriage.classifyRuntimeControl({ run, runInstanceId: runInstanceId || undefined,
+      status: String(status.status ?? "unknown") }, control, nowMs).stale)), 0);
   return {
     run,
     run_instance_id: runInstanceId,
     status: status.status,
+    pending: capacity.pending, pending_limit: capacity.limit,
+    available: capacity.available, backpressured: capacity.backpressured,
+    journal_bytes: journalBytes, journal_limit: Limits.RUN_CONTROL_JOURNAL_MAX_BYTES,
+    ...(capacity.oldest_pending_at ? { oldest_pending_at: capacity.oldest_pending_at } : {}),
+    stale_pending: stalePending,
+    diagnostics,
     actor_actions: Array.isArray(status.control) ? status.control : [],
     runtime_actions: status.status === "running" ? ["kill"] : ["archive", "prune"],
     endpoint: runInstanceId
       ? RunControlDelivery.readRunControlEndpoint(stateDir, runInstanceId)
       : undefined,
-    recent_controls: RunsControls.readRunControlsFromStateDir(stateDir)
-      .slice(-Math.max(1, Number(input.lines || 20)))
-      .reverse(),
+    recent_controls: journal.records.slice(-Math.max(1, Number(input.lines || 20))).reverse()
+      .map((control) => ControlProjection.projectRunControl(control as RunsControls.RunControlRecord)),
   };
 }
 

package/lib/tools-message.ts

@@ -46,8 +46,7 @@ function runNextActions(run: string, result: Record<string, unknown>): string[]
 }
 
 export interface ControlToolDeps {
-  getTool?: (name: string) => unknown;
-  handleRuntimeMessage?: (
+  handleRuntimeControl?: (
     action: string,
     input: unknown,
   ) => Record<string, unknown>;
@@ -64,11 +63,11 @@ export function createControlToolDefinition<TContext = unknown>(
     parameters: Schema.objectSchema(
       {
         target: Schema.stringSchema("Run target run:<id>, or literal runtime."),
-        action: Schema.stringSchema("Lowercase semantic Control action."),
+        action: Schema.stringSchema("Lowercase ASCII Control action, at most 64 characters."),
         input: Schema.unionSchema([
-          Schema.stringSchema("Optional Control input string."),
-          Schema.looseObjectSchema("Optional structured Control input."),
-          Schema.arraySchema("Optional structured Control input array."),
+          Schema.stringSchema("Optional Control input string; serialized JSON must fit 380 bytes."),
+          Schema.looseObjectSchema("Optional structured Control input; serialized JSON must fit 380 bytes."),
+          Schema.arraySchema("Optional structured Control input array; serialized JSON must fit 380 bytes."),
         ]),
         verbose: Schema.booleanSchema("Return full JSON instead of compact text."),
       },
@@ -89,10 +88,10 @@ export function createControlToolDefinition<TContext = unknown>(
             `unsupported runtime Control action: ${request.action}; use review.retry or review.reset`,
           );
         }
-        if (!deps.handleRuntimeMessage) {
+        if (!deps.handleRuntimeControl) {
           throw new Error("runtime Control is unavailable");
         }
-        result = deps.handleRuntimeMessage(request.action, request.input);
+        result = deps.handleRuntimeControl(request.action, request.input);
       } else {
         const run = request.target.slice(4);
         const status = ToolsAccess.assertRunAccessibleToContext(run, ctx);

package/lib/tools-response.ts

@@ -133,18 +133,6 @@ export function compactAsyncRunStatus(value: unknown): string {
   return `\n${tokens.join(" ")}`;
 }
 
-export function artifactNextActions(
-  run: unknown,
-  artifacts: Record<string, unknown>,
-): string[] {
-  const id = String(run ?? "").trim();
-  if (!id || Object.keys(artifacts).length === 0) return [];
-  return [
-    `inspect target=run:${id} view=artifacts verbose=true`,
-    `inspect target=run:${id} view=messages`,
-  ];
-}
-
 export function maybeJsonText(
   value: unknown,
   verbose: boolean | undefined,

package/lib/tools.ts

@@ -25,9 +25,9 @@ export interface CoreActorToolDefinitionDeps<
   configPath: string;
   getActiveTools: () => string[];
   getRuntimeTool: (name: string) => unknown;
-  handleRuntimeMessage?: (
-    type: string,
-    body: unknown,
+  handleRuntimeControl?: (
+    action: string,
+    input: unknown,
   ) => Record<string, unknown>;
   registryRuntime: Pick<
     RegisterToolRuntimeDeps<TContext>,
@@ -74,7 +74,7 @@ export function createCoreActorToolDefinitions<
     }),
     ToolsSpawn.createSpawnToolDefinition<TContext>(),
     ToolsMessage.createControlToolDefinition<TContext>({
-      handleRuntimeMessage: deps.handleRuntimeMessage,
+      handleRuntimeControl: deps.handleRuntimeControl,
     }),
     ToolsInspect.createInspectToolDefinition<TContext>({
       getTool: (name) => deps.getRuntimeTool(name),