@llblab/pi-actors 0.41.1 → 0.42.1

package/lib/review-control.ts

@@ -0,0 +1,137 @@
+/**
+ * Automatic recipe-review operator control.
+ * Owns: explicit retry/reset transitions over durable draft/tool admission state.
+ */
+
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { withFileMutationLock, writeJsonAtomic } from "./file-state.ts";
+import * as Paths from "./paths.ts";
+
+export type AutomaticReviewScope = "draft" | "tool";
+export type AutomaticReviewControlAction = "review.reset" | "review.retry";
+
+export interface AutomaticReviewControlOptions {
+  draftStatePath?: string;
+  scheduleDraft?(): void;
+  scheduleTool?(): void;
+  toolStatePath?: string;
+}
+
+function readState(path: string): Record<string, unknown> | undefined {
+  try {
+    const value = JSON.parse(readFileSync(path, "utf8"));
+    return value && typeof value === "object" && !Array.isArray(value)
+      ? value as Record<string, unknown>
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function statePath(
+  scope: AutomaticReviewScope,
+  options: AutomaticReviewControlOptions,
+): string {
+  return scope === "draft"
+    ? options.draftStatePath ?? Paths.getDraftSleepStatePath()
+    : options.toolStatePath ?? Paths.getToolReviewStatePath();
+}
+
+function schedule(
+  scope: AutomaticReviewScope,
+  options: AutomaticReviewControlOptions,
+): void {
+  if (scope === "draft") options.scheduleDraft?.();
+  else options.scheduleTool?.();
+}
+
+export function controlAutomaticReview(
+  action: AutomaticReviewControlAction,
+  scope: AutomaticReviewScope,
+  options: AutomaticReviewControlOptions = {},
+): Record<string, unknown> {
+  const path = statePath(scope, options);
+  const result = withFileMutationLock(path, () => {
+    const state = readState(path);
+    if (!state) {
+      return { action, changed: false, phase: "idle", reason: "review_state_unavailable", scope };
+    }
+    const phase = String(state.phase ?? "unknown");
+    if (action === "review.reset") {
+      if (!["completed", "failed", "processing_failed"].includes(phase)) {
+        return { action, changed: false, phase, reason: "review_state_not_terminal", scope };
+      }
+      if (
+        scope === "tool" &&
+        (state.approvedPath || state.transactionEvidencePath || state.lineageJournalPath)
+      ) {
+        return {
+          action,
+          changed: false,
+          phase,
+          reason: "review_recovery_evidence_requires_retry",
+          scope,
+        };
+      }
+      rmSync(path, { force: true });
+      return { action, changed: true, phase: "idle", previous_phase: phase, scope };
+    }
+    if (!["failed", "processing_failed"].includes(phase)) {
+      return { action, changed: false, phase, reason: "review_state_not_retryable", scope };
+    }
+    const resumeDraftTransaction =
+      scope === "draft" &&
+      phase === "processing_failed" &&
+      typeof state.inputPath === "string" &&
+      typeof state.runId === "string" &&
+      existsSync(join(dirname(state.inputPath), "journal.json"));
+    const nextPhase = resumeDraftTransaction
+      ? "launched"
+      : scope === "tool" && state.approvedPath
+        ? state.transactionEvidencePath
+          ? "lineage_pending"
+          : "approved"
+        : "captured";
+    const next = {
+      ...state,
+      attempts: 0,
+      lastError: undefined,
+      nextAction: undefined,
+      failedStage: undefined,
+      phase: nextPhase,
+      processingAttempts: 0,
+      runId: resumeDraftTransaction ? state.runId : undefined,
+      updatedAt: new Date().toISOString(),
+    };
+    writeJsonAtomic(path, next);
+    return {
+      action,
+      changed: true,
+      phase: nextPhase,
+      previous_phase: phase,
+      scope,
+    };
+  });
+  if (result.changed === true) schedule(scope, options);
+  const nextActions = ["inspect target=recipes view=reviews"];
+  if (
+    action === "review.retry" &&
+    scope === "tool" &&
+    (result.phase === "approved" || result.phase === "lineage_pending")
+  ) nextActions.push("/reload");
+  return {
+    ...result,
+    next_actions: nextActions,
+    sent: result.changed === true,
+  };
+}
+
+export function parseAutomaticReviewScope(body: unknown): AutomaticReviewScope {
+  const record = body && typeof body === "object" && !Array.isArray(body)
+    ? body as Record<string, unknown>
+    : {};
+  if (record.scope === "draft" || record.scope === "tool") return record.scope;
+  throw new Error("review control requires body.scope=draft or body.scope=tool.");
+}

package/lib/review-diagnostics.ts

@@ -0,0 +1,164 @@
+/**
+ * Automatic recipe-review diagnostics.
+ * Zones: bounded draft/tool cycle evidence, lineage summaries, revision snapshot inventory
+ * Owns read-only diagnostic projection; schedulers and transactions own mutation.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+import * as Paths from "./paths.ts";
+
+const MAX_FILE_BYTES = 1024 * 1024;
+const MAX_ENTRIES = 100;
+
+function readJson(path: string | undefined): Record<string, unknown> | undefined {
+  if (!path || !existsSync(path) || statSync(path).size > MAX_FILE_BYTES) return undefined;
+  try {
+    const value = JSON.parse(readFileSync(path, "utf8"));
+    return value && typeof value === "object" && !Array.isArray(value)
+      ? value as Record<string, unknown>
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function text(value: unknown, limit = 240): string | undefined {
+  if (typeof value !== "string") return undefined;
+  return value.length > limit ? `${value.slice(0, limit - 1)}…` : value;
+}
+
+function strings(value: unknown, limit = 20): string[] {
+  return Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === "string").slice(-limit)
+    : [];
+}
+
+function cycleState(state: Record<string, unknown> | undefined): Record<string, unknown> {
+  if (!state) return { phase: "idle" };
+  return {
+    phase: text(state.phase) ?? "unknown",
+    attempts: state.attempts,
+    failed_stage: text(state.failedStage),
+    last_error: text(state.lastError, 500),
+    next_action: text(state.nextAction, 500),
+    processing_attempts: state.processingAttempts,
+    batch_id: text(state.batchId),
+    review_id: text(state.reviewId),
+    run_id: text(state.runId),
+    sources: Array.isArray(state.sourcePaths) ? state.sourcePaths.length : undefined,
+    tools: Array.isArray(state.toolNames) ? state.toolNames.length : undefined,
+    updated_at: text(state.updatedAt),
+  };
+}
+
+function draftEvidence(state: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
+  const evidence = readJson(text(state?.evidencePath, 4096));
+  if (!evidence) return undefined;
+  const decisions = Array.isArray(evidence.decisions)
+    ? evidence.decisions as Array<Record<string, unknown>>
+    : [];
+  const garbage = evidence.garbageCollection as Record<string, unknown> | undefined;
+  return {
+    actions: Object.fromEntries(
+      ["promote", "discard"].map((action) => [
+        action,
+        decisions.filter((decision) => decision.action === action).length,
+      ]),
+    ),
+    garbage_collection: garbage
+      ? { reviewed_sources: garbage.reviewedSources, status: garbage.status }
+      : undefined,
+    reviewed_sources: decisions.length,
+  };
+}
+
+function toolEvidence(state: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
+  const approved = readJson(text(state?.approvedPath, 4096));
+  if (!approved) return undefined;
+  const decisions = Array.isArray(approved.decisions)
+    ? approved.decisions as Array<Record<string, unknown>>
+    : [];
+  return {
+    actions: Object.fromEntries(
+      ["keep", "evolve", "replace", "demote", "merge", "split"].map((action) => [
+        action,
+        decisions.filter((decision) => decision.action === action).length,
+      ]),
+    ),
+    lineage_phase: readJson(text(state?.lineageJournalPath, 4096))?.phase,
+    review_id: text(approved.reviewId),
+    sources: Array.isArray(approved.sources) ? approved.sources.length : 0,
+    targets: Array.isArray(approved.targets) ? approved.targets.length : 0,
+    transaction_phase: readJson(
+      join(dirname(text(state?.approvedPath, 4096)!), "journal.json"),
+    )?.phase,
+  };
+}
+
+function lineageSummaries(recipeRoot: string): Record<string, unknown>[] {
+  const root = join(recipeRoot, ".usage", "recipes");
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+    .map((entry) => join(root, entry.name))
+    .sort()
+    .slice(0, MAX_ENTRIES)
+    .flatMap((path) => {
+      const record = readJson(path);
+      if (!record) return [];
+      return [{
+        current_path: text(record.current_path),
+        demoted_at: text(record.demoted_at),
+        demoted_from_revision: record.demoted_from_revision,
+        lifetime_calls: record.lifetime_calls,
+        name: text(record.lineage_name) ?? basename(path, ".json"),
+        review_epochs: strings(record.review_epochs, 5),
+        revision: record.revision,
+        revision_calls: record.revision_calls,
+        rollback_of_revision: record.rollback_of_revision,
+      }];
+    });
+}
+
+function snapshotCount(recipeRoot: string): number {
+  const root = join(recipeRoot, ".usage", "revisions");
+  if (!existsSync(root)) return 0;
+  let count = 0;
+  for (const lineage of readdirSync(root, { withFileTypes: true }).slice(0, MAX_ENTRIES)) {
+    if (!lineage.isDirectory()) continue;
+    count += readdirSync(join(root, lineage.name), { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .length;
+  }
+  return count;
+}
+
+export interface AutomaticReviewDiagnosticOptions {
+  draftStatePath?: string;
+  recipeRoot?: string;
+  toolStatePath?: string;
+}
+
+export function readAutomaticReviewDiagnostics(
+  options: AutomaticReviewDiagnosticOptions = {},
+): Record<string, unknown> {
+  const recipeRoot = options.recipeRoot ?? Paths.getRecipeRoot();
+  const draftState = readJson(options.draftStatePath ?? Paths.getDraftSleepStatePath());
+  const toolState = readJson(options.toolStatePath ?? Paths.getToolReviewStatePath());
+  const lineages = lineageSummaries(recipeRoot);
+  return {
+    draft_review: {
+      ...cycleState(draftState),
+      evidence: draftEvidence(draftState),
+    },
+    lineage_count: lineages.length,
+    lineages,
+    revision_snapshots: snapshotCount(recipeRoot),
+    tool_review: {
+      ...cycleState(toolState),
+      evidence: toolEvidence(toolState),
+    },
+  };
+}

package/lib/review-projection.ts

@@ -0,0 +1,200 @@
+/**
+ * Automatic recipe-review confidentiality projection.
+ * Owns: value-free model inputs derived from trusted immutable draft/tool captures.
+ */
+
+import type {
+  DraftReviewInput,
+  DraftReviewResult,
+} from "./draft-review.ts";
+import type {
+  ToolReviewInput,
+  ToolReviewResult,
+} from "./tool-review.ts";
+
+function occurrenceId(prefix: string, index: number): string {
+  return `${prefix}_${String(index + 1).padStart(2, "0")}`;
+}
+
+export const draftReviewIdentity = (index: number): string => occurrenceId("draft", index);
+export const toolReviewIdentity = (index: number): string => occurrenceId("tool", index);
+
+function contentGroups(hashes: string[]): string[] {
+  const groups = new Map<string, string>();
+  return hashes.map((hash) => {
+    let group = groups.get(hash);
+    if (!group) {
+      group = occurrenceId("content_group", groups.size);
+      groups.set(hash, group);
+    }
+    return group;
+  });
+}
+
+function draftContentGroups(input: DraftReviewInput): string[] {
+  return contentGroups([
+    ...input.activeTools.map((tool) => tool.sha256),
+    ...input.drafts.map((draft) => draft.sha256),
+  ]);
+}
+
+export function draftReviewRevision(input: DraftReviewInput, index: number): string {
+  return draftContentGroups(input)[input.activeTools.length + index]!;
+}
+
+export function toolReviewRevision(input: ToolReviewInput, index: number): string {
+  return contentGroups(input.tools.map((tool) => tool.sha256))[index]!;
+}
+
+function countArray(value: unknown): number {
+  return Array.isArray(value) ? value.length : 0;
+}
+
+function countRecord(value: unknown): number {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? Object.keys(value).length
+    : 0;
+}
+
+function templateShape(value: unknown): Record<string, unknown> {
+  if (typeof value === "string") return { kind: "command", nodes: 1 };
+  if (Array.isArray(value)) {
+    return {
+      branches: value.length,
+      kind: "sequence",
+      nodes: 1 + value.reduce((total, child) => total + Number(templateShape(child).nodes ?? 0), 0),
+    };
+  }
+  if (!value || typeof value !== "object") return { kind: "invalid", nodes: 0 };
+  const record = value as Record<string, unknown>;
+  const children = Array.isArray(record.template)
+    ? record.template
+    : record.template === undefined
+      ? []
+      : [record.template];
+  return {
+    branches: children.length,
+    conditional: record.when !== undefined,
+    kind: record.parallel === true ? "parallel" : "object",
+    repeat: record.repeat !== undefined,
+    retry: record.retry !== undefined,
+    nodes: 1 + children.reduce(
+      (total, child) => total + Number(templateShape(child).nodes ?? 0),
+      0,
+    ),
+  };
+}
+
+function contractShape(recipe: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
+  if (!recipe) return undefined;
+  const mailbox = recipe.mailbox && typeof recipe.mailbox === "object" && !Array.isArray(recipe.mailbox)
+    ? recipe.mailbox as Record<string, unknown>
+    : {};
+  return {
+    argument_count: countArray(recipe.args),
+    artifact_count: countRecord(recipe.artifacts),
+    async: recipe.async === true,
+    default_count: countRecord(recipe.defaults),
+    import_count: countRecord(recipe.imports),
+    mailbox_accepts_count: countArray(mailbox.accepts),
+    mailbox_emits_count: countArray(mailbox.emits),
+    template_shape: templateShape(recipe.template),
+  };
+}
+
+function usageShape(usage: Record<string, unknown> | undefined): Record<string, number> {
+  const numeric = (key: string): number => {
+    const value = usage?.[key];
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+      ? value
+      : 0;
+  };
+  return {
+    lifetime_calls: numeric("lifetime_calls") || numeric("calls"),
+    revision: numeric("revision"),
+    revision_calls: numeric("revision_calls"),
+  };
+}
+
+export function projectDraftReviewInput(input: DraftReviewInput): Record<string, unknown> {
+  return {
+    activeTools: input.activeTools.map((_tool, index) => ({
+      name: occurrenceId("active_tool", index),
+      sha256: draftContentGroups(input)[index],
+    })),
+    batchId: input.batchId,
+    createdAt: input.createdAt,
+    drafts: input.drafts.map((draft, index) => ({
+      contract: contractShape(draft.recipe),
+      draft: draftReviewIdentity(index),
+      riskLabels: [...draft.riskLabels],
+      sha256: draftReviewRevision(input, index),
+      usage: usageShape(draft.usage),
+      valid: draft.valid,
+    })),
+  };
+}
+
+export function restoreDraftReviewResult(
+  input: DraftReviewInput,
+  result: DraftReviewResult,
+): DraftReviewResult {
+  const drafts = new Map(input.drafts.map((draft, index) => [draftReviewIdentity(index), {
+    draft,
+    revision: draftReviewRevision(input, index),
+  }]));
+  return {
+    ...result,
+    decisions: result.decisions.map((decision) => {
+      const captured = drafts.get(decision.draft);
+      return {
+        ...decision,
+        draft: captured?.draft.path ?? `unknown:${decision.draft}`,
+        sha256: captured && decision.sha256 === captured.revision
+          ? captured.draft.sha256
+          : `invalid:${decision.sha256}`,
+      };
+    }),
+  };
+}
+
+export function projectToolReviewInput(input: ToolReviewInput): Record<string, unknown> {
+  return {
+    createdAt: input.createdAt,
+    reviewId: input.reviewId,
+    tools: input.tools.map((tool, index) => ({
+      contract: contractShape(tool.recipe),
+      name: toolReviewIdentity(index),
+      riskLabels: [...tool.riskLabels],
+      sha256: toolReviewRevision(input, index),
+      usage: usageShape(tool.usage),
+      valid: tool.valid,
+    })),
+  };
+}
+
+export function restoreToolReviewResult(
+  input: ToolReviewInput,
+  result: ToolReviewResult,
+): ToolReviewResult {
+  const tools = new Map(input.tools.map((tool, index) => [toolReviewIdentity(index), {
+    revision: toolReviewRevision(input, index),
+    tool,
+  }]));
+  return {
+    ...result,
+    decisions: result.decisions.map((decision) => {
+      const captured = tools.get(decision.source);
+      return {
+        ...decision,
+        sha256: captured && decision.sha256 === captured.revision
+          ? captured.tool.sha256
+          : `invalid:${decision.sha256}`,
+        source: captured?.tool.name ?? `unknown:${decision.source}`,
+        ...(decision.target
+          ? { target: tools.get(decision.target)?.tool.name ?? decision.target }
+          : {}),
+      };
+    }),
+  };
+}

package/lib/run-ui-runtime.ts

@@ -0,0 +1,153 @@
+/**
+ * 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.ts";
+import * as Observability from "./observability.ts";
+import * as Paths from "./paths.ts";
+import * as Pi from "./pi.ts";
+
+export interface RunUiRuntime {
+  close(): void;
+  shutdown(eventReason: string, ctx: Pi.ExtensionContext): void;
+  start(ctx: Pi.ExtensionContext): void;
+}
+
+export interface RunUiRuntimeDeps {
+  getActiveContext(): Pi.ExtensionContext | undefined;
+  getRunOwnerId(ctx: Pi.ExtensionContext): string;
+  onRunEvent(): void;
+  pi: Pi.ExtensionAPI;
+}
+
+export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
+  let animationInterval: NodeJS.Timeout | undefined;
+  let notifyTimeout: NodeJS.Timeout | undefined;
+  let lastWatcherDiagnosticId = 0;
+  const observation = Observability.createRunUiObservationState();
+  const retirementAttempts = new Set<string>();
+  const terminalNotificationsInFlight = new Set<string>();
+
+  const retireCandidateRuns = (
+    ctx: Pi.ExtensionContext,
+    summary: Observability.RunSummary,
+  ): void => {
+    void Observability.executeRunRetirements(summary, {
+      attempted: retirementAttempts,
+      cancelRun: (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
+      notify: (message, level) => ctx.ui.notify(message, level),
+      sendStop: (candidate) => AsyncRuns.sendRunMessage(candidate.stateDir, "stop"),
+    });
+  };
+  const update = (
+    ctx: Pi.ExtensionContext,
+    notify = false,
+    terminalOnly = false,
+  ): void => {
+    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.deliverRunOutboxNotifications(snapshot.outboxEvents, sink);
+    }
+  };
+  const reportDiagnostics = (ctx: Pi.ExtensionContext): void => {
+    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 = (): void => {
+    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,
+      });
+      reportDiagnostics(ctx);
+    },
+    refreshWatcher: () => watcher.refresh(),
+  });
+  const close = (): void => {
+    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();
+      update(ctx, true, true);
+      watcher.refresh();
+      reconciliation.start();
+      animationInterval = setInterval(() => {
+        if (deps.getActiveContext() === ctx) update(ctx);
+      }, 1000);
+      animationInterval.unref?.();
+    },
+  };
+}

package/lib/runs-artifacts.ts

@@ -1,6 +1,6 @@
 /**
  * Async run artifact declarations and manifest resolution.
- * Owns artifact path template expansion and filesystem-backed artifact metadata.
+ * Owns: artifact path template expansion and filesystem-backed artifact metadata.
  */
 
 import { createHash } from "node:crypto";