@llblab/pi-kit 0.6.0 → 0.7.1

package/node_modules/@llblab/pi-actors/lib/command-templates.ts

@@ -4,7 +4,7 @@
  * Owns portable command-template parsing, expansion, risk checks, retries, timeouts, and direct execution.
  */
 
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { accessSync, appendFileSync, constants, mkdirSync, mkdtempSync, statSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, delimiter, extname, isAbsolute, join, resolve as resolvePath } from "node:path";
@@ -1010,12 +1010,50 @@ function execCommandTemplateOnce(
     let settled = false;
     let timeoutId: NodeJS.Timeout | undefined;
     let killTimeoutId: NodeJS.Timeout | undefined;
+    const signalProcessTree = (signal: NodeJS.Signals): void => {
+      if (proc.pid === undefined) return;
+      if (process.platform === "win32") {
+        spawnSync("taskkill", [
+          "/PID",
+          String(proc.pid),
+          "/T",
+          ...(signal === "SIGKILL" ? ["/F"] : []),
+        ]);
+        return;
+      }
+      const snapshot = spawnSync("ps", ["-eo", "pid=,ppid="], { encoding: "utf8" });
+      const children = new Map<number, number[]>();
+      for (const line of snapshot.stdout?.split(/\r?\n/u) ?? []) {
+        const [pidText, parentText] = line.trim().split(/\s+/u);
+        const pid = Number(pidText);
+        const parent = Number(parentText);
+        if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(parent)) continue;
+        const siblings = children.get(parent) ?? [];
+        siblings.push(pid);
+        children.set(parent, siblings);
+      }
+      const descendants: number[] = [];
+      const collect = (parent: number): void => {
+        for (const child of children.get(parent) ?? []) {
+          collect(child);
+          descendants.push(child);
+        }
+      };
+      collect(proc.pid);
+      for (const pid of [...descendants, proc.pid]) {
+        try {
+          process.kill(pid, signal);
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
+        }
+      }
+    };
     const killProcess = (): void => {
       if (killed) return;
       killed = true;
-      proc.kill("SIGTERM");
+      signalProcessTree("SIGTERM");
       killTimeoutId = setTimeout(() => {
-        if (!settled) proc.kill("SIGKILL");
+        if (!settled) signalProcessTree("SIGKILL");
       }, options.killGrace ?? 5000);
     };
     const settle = (code: number): void => {

package/node_modules/@llblab/pi-actors/lib/extension-runtime.ts

@@ -143,7 +143,7 @@ export function createActorExtensionRuntime(
     },
     getRunOwnerId,
     onAgentSettled(ctx) {
-      if (activeRunContext !== ctx) return;
+      if (!activeRunOwnerId || getRunOwnerId(ctx) !== activeRunOwnerId) return;
       if (!runUiRuntime.flushCompletionBatch(ctx)) automaticReview.schedule();
     },
     onContext(messages, ctx) {

package/node_modules/@llblab/pi-actors/lib/observability.ts

@@ -43,6 +43,12 @@ export interface RunObservation {
   activeSubagents?: number;
   completed?: number;
   descendantSubagents?: number;
+  deliveryOwnerId?: string;
+  deliveryParent?: {
+    run: string;
+    run_instance_id: string;
+    state_dir: string;
+  };
   failures?: number;
   ownerId?: string;
   artifacts?: Record<string, string>;
@@ -136,6 +142,21 @@ export function readRunUiSnapshot(
   };
 }
 
+/** Observe every Run generation routed to one root coordinator. */
+export function readRunDeliverySnapshot(
+  state: RunUiObservationState,
+  deliveryOwnerId: string,
+  stateRoot?: string,
+): RunUiSnapshot {
+  const summary = summarizeRuns(stateRoot, undefined, deliveryOwnerId);
+  return {
+    attentionEvents: [],
+    status: undefined,
+    summary,
+    transitions: detectRunTransitions(state.observed, summary),
+  };
+}
+
 export function pruneRunUiObservationState(
   state: RunUiObservationState,
   snapshot: Pick<RunUiSnapshot, "summary" | "transitions">,
@@ -383,6 +404,11 @@ export interface RunRetirementExecutorOptions {
 }
 
 export interface RunTransition {
+  deliveryParent?: {
+    run: string;
+    run_instance_id: string;
+    state_dir: string;
+  };
   from: RunObservedStatus;
   run: string;
   runInstanceId?: string;
@@ -584,6 +610,23 @@ function observeRun(stateDir: string): RunObservation | undefined {
       failures: Array.isArray(progress.failures)
         ? progress.failures.length
         : undefined,
+      ...(typeof status.delivery_owner_id === "string"
+        ? { deliveryOwnerId: status.delivery_owner_id }
+        : {}),
+      ...(status.delivery_parent &&
+      typeof status.delivery_parent === "object" &&
+      !Array.isArray(status.delivery_parent) &&
+      typeof (status.delivery_parent as Record<string, unknown>).run === "string" &&
+      typeof (status.delivery_parent as Record<string, unknown>).run_instance_id === "string" &&
+      typeof (status.delivery_parent as Record<string, unknown>).state_dir === "string"
+        ? {
+            deliveryParent: status.delivery_parent as {
+              run: string;
+              run_instance_id: string;
+              state_dir: string;
+            },
+          }
+        : {}),
       ...(typeof status.ownerId === "string"
         ? { ownerId: status.ownerId }
         : {}),
@@ -630,6 +673,7 @@ function observeRun(stateDir: string): RunObservation | undefined {
 export function summarizeRuns(
   stateRoot = Paths.getRunStateRoot(),
   ownerId?: string,
+  deliveryOwnerId?: string,
 ): RunSummary {
   if (!existsSync(stateRoot)) {
     return {
@@ -650,7 +694,10 @@ export function summarizeRuns(
   )
     .map((stateDir) => observeRun(stateDir))
     .filter((run): run is RunObservation => Boolean(run))
-    .filter((run) => ownerId === undefined || run.ownerId === ownerId)
+    .filter((run) => deliveryOwnerId !== undefined
+      ? run.deliveryOwnerId === deliveryOwnerId ||
+        (run.deliveryOwnerId === undefined && run.ownerId === deliveryOwnerId)
+      : ownerId === undefined || run.ownerId === ownerId)
     .sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
   const processSubagentsByRun = countRunningSubagentsByRun(stateRoot, ownerId);
   const runsWithDescendants = runs.map((run) => {
@@ -1005,6 +1052,7 @@ export function detectRunTransitions(
       transitions.push({
         from: old ?? "running",
         run: run.run,
+        ...(run.deliveryParent ? { deliveryParent: run.deliveryParent } : {}),
         ...(run.stateDir ? { stateDir: run.stateDir } : {}),
         ...(run.artifacts ? { artifacts: run.artifacts } : {}),
         ...(run.launchCorrelation ? { launchCorrelation: run.launchCorrelation } : {}),
@@ -1282,11 +1330,57 @@ export function shouldNotifyRunTransition(transition: RunTransition): boolean {
   );
 }
 
-/** Build exact immutable generation members for owner-journal admission. */
+function deliveryGenerationIdentity(input: {
+  runInstanceId?: string;
+  stateDir?: string;
+}): string | undefined {
+  return input.stateDir && input.runInstanceId
+    ? `${input.stateDir}\0${input.runInstanceId}`
+    : undefined;
+}
+
+function deliveryTreePosition(
+  input: {
+    deliveryParent?: RunObservation["deliveryParent"];
+    runInstanceId?: string;
+    stateDir?: string;
+  },
+  runsByIdentity: Map<string, RunObservation>,
+): { depth: number; rootIdentity: string } | undefined {
+  const ownIdentity = deliveryGenerationIdentity(input);
+  if (!ownIdentity) return undefined;
+  let parent = input.deliveryParent;
+  let depth = 0;
+  let rootIdentity = ownIdentity;
+  const visited = new Set([ownIdentity]);
+  while (parent) {
+    const identity = `${parent.state_dir}\0${parent.run_instance_id}`;
+    if (visited.has(identity)) return undefined;
+    visited.add(identity);
+    const ancestor = runsByIdentity.get(identity);
+    if (!ancestor || ancestor.notificationPolicy === "silent") return undefined;
+    depth += 1;
+    rootIdentity = identity;
+    parent = ancestor.deliveryParent;
+  }
+  return { depth, rootIdentity };
+}
+
+/** Build exact immutable members only after each containing root Run is terminal. */
 export function collectRunCompletionBatchMembers(
   transitions: RunTransition[],
+  deliveryRuns: RunObservation[] = [],
 ): RunCompletionBatchMember[] {
-  return transitions.flatMap((transition) => {
+  const runsByIdentity = new Map(deliveryRuns.flatMap((run) => {
+    const identity = deliveryGenerationIdentity(run);
+    return identity ? [[identity, run] as const] : [];
+  }));
+  const incompleteRoots = new Set(deliveryRuns.flatMap((run) => {
+    if (TERMINAL.has(run.status)) return [];
+    const position = deliveryTreePosition(run, runsByIdentity);
+    return position ? [position.rootIdentity] : [];
+  }));
+  const admitted = transitions.flatMap((transition) => {
     if (
       !shouldNotifyRunTransition(transition) ||
       !transition.stateDir ||
@@ -1294,6 +1388,9 @@ export function collectRunCompletionBatchMembers(
       !transition.terminalAt ||
       Number.isNaN(Date.parse(transition.terminalAt))
     ) return [];
+    const position = deliveryTreePosition(transition, runsByIdentity);
+    if (!position || incompleteRoots.has(position.rootIdentity)) return [];
+    const { depth } = position;
     const artifactEntries = Object.entries(transition.artifacts ?? {})
       .filter((entry): entry is [string, string] =>
         typeof entry[1] === "string" && Boolean(entry[1]))
@@ -1304,6 +1401,20 @@ export function collectRunCompletionBatchMembers(
       ...(artifactEntries.length > 0
         ? { artifacts: Object.fromEntries(artifactEntries) }
         : {}),
+      ...(transition.semanticResult?.body?.trim()
+        ? {
+            output: transition.semanticResult.body.trim().length > 4_000
+              ? `${transition.semanticResult.body.trim().slice(0, 3_999)}…`
+              : transition.semanticResult.body.trim(),
+          }
+        : {}),
+      ...(transition.deliveryParent
+        ? {
+            parent_run: transition.deliveryParent.run,
+            parent_run_instance_id: transition.deliveryParent.run_instance_id,
+            parent_state_dir: transition.deliveryParent.state_dir,
+          }
+        : {}),
       run: transition.run,
       run_instance_id: transition.runInstanceId,
       state_dir: transition.stateDir,
@@ -1312,13 +1423,16 @@ export function collectRunCompletionBatchMembers(
         ? `${rawSummary.slice(0, 999)}…`
         : rawSummary,
       terminal_at: transition.terminalAt,
+      tree_depth: depth,
     }];
-  }).sort((left, right) =>
+  });
+  return admitted.sort((left, right) =>
+    left.tree_depth - right.tree_depth ||
     left.terminal_at.localeCompare(right.terminal_at) ||
     left.run.localeCompare(right.run) ||
     left.run_instance_id.localeCompare(right.run_instance_id) ||
     left.state_dir.localeCompare(right.state_dir)
-  );
+  ).map(({ tree_depth: _depth, ...member }) => member);
 }
 
 const TERMINAL_FOLLOW_UP_ARTIFACT_LIMIT = 4;

package/node_modules/@llblab/pi-actors/lib/pi.ts

@@ -52,7 +52,7 @@ export function sendRunCompletionBatch(
   pi.sendMessage({
     customType: RUN_COMPLETION_BATCH_CUSTOM_TYPE,
     content,
-    display: false,
+    display: true,
     details: {
       pi_actors_delivery: {
         batch_id: batchId,
@@ -96,17 +96,20 @@ function completionBatchMessage(
     typeof record.content !== "string"
   ) return undefined;
   const details = record.details;
-  if (!details || typeof details !== "object" || Array.isArray(details)) return undefined;
-  const delivery = (details as Record<string, unknown>).pi_actors_delivery;
-  if (!delivery || typeof delivery !== "object" || Array.isArray(delivery)) return undefined;
-  const envelope = delivery as Record<string, unknown>;
-  if (
-    envelope.kind !== "completion_batch" ||
-    typeof envelope.batch_id !== "string" ||
-    !envelope.batch_id ||
-    envelope.batch_id.length > 128
-  ) return undefined;
-  return { batchId: envelope.batch_id, content: record.content };
+  const delivery = details && typeof details === "object" && !Array.isArray(details)
+    ? (details as Record<string, unknown>).pi_actors_delivery
+    : undefined;
+  const envelope = delivery && typeof delivery === "object" && !Array.isArray(delivery)
+    ? delivery as Record<string, unknown>
+    : undefined;
+  const detailedId = envelope?.kind === "completion_batch" &&
+    typeof envelope.batch_id === "string"
+    ? envelope.batch_id
+    : undefined;
+  const contentId = /^Batch: `([^`]{1,128})`$/mu.exec(record.content)?.[1];
+  const batchId = detailedId ?? contentId;
+  if (!batchId || batchId.length > 128) return undefined;
+  return { batchId, content: record.content };
 }
 
 /** Collapse exact retry duplicates and remove conflicting delivery envelopes. */
@@ -233,22 +236,6 @@ export function inspectRunSteerSessionEvidence(
   });
 }
 
-export function inspectRunCompletionBatchSessionEvidence(
-  ctx: ExtensionContext,
-  batchId: string,
-  content: string,
-): SessionEvidence.ActiveSessionEntryEvidence {
-  return SessionEvidence.inspectBoundedActiveSessionEntries({
-    getEntry: (id) => ctx.sessionManager.getEntry(id),
-    leaf: ctx.sessionManager.getLeafEntry(),
-    match: (entry) => {
-      const batch = completionBatchMessage(entry);
-      if (!batch || batch.batchId !== batchId) return undefined;
-      return batch.content === content ? "present" : "conflict";
-    },
-  });
-}
-
 export function registerToolDefinitions(
   pi: ExtensionAPI,
   definitions: Iterable<unknown>,

package/node_modules/@llblab/pi-actors/lib/run-delivery-lineage.ts

@@ -0,0 +1,68 @@
+/**
+ * Run delivery lineage.
+ * Zones: inherited coordinator root, parent Run generation, delivery-tree filtering
+ * Owns durable completion ancestry; excludes delivery persistence and Pi scheduling.
+ */
+
+export interface RunDeliveryParent {
+  run: string;
+  run_instance_id: string;
+  state_dir: string;
+}
+
+export interface RunDeliveryLineage {
+  delivery_owner_id: string;
+  delivery_parent?: RunDeliveryParent;
+}
+
+const DELIVERY_OWNER_ENV = "PI_ACTORS_DELIVERY_OWNER_ID";
+const PARENT_RUN_ENV = "PI_ACTORS_DELIVERY_PARENT_RUN";
+const PARENT_INSTANCE_ENV = "PI_ACTORS_DELIVERY_PARENT_INSTANCE";
+const PARENT_STATE_DIR_ENV = "PI_ACTORS_DELIVERY_PARENT_STATE_DIR";
+
+function nonEmpty(value: string | undefined): string | undefined {
+  const text = value?.trim();
+  return text || undefined;
+}
+
+export function inheritedRunDeliveryLineage(
+  ownerId: string | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): RunDeliveryLineage | undefined {
+  const localOwner = nonEmpty(ownerId);
+  if (!localOwner) return undefined;
+  const deliveryOwner = nonEmpty(env[DELIVERY_OWNER_ENV]) ?? localOwner;
+  const run = nonEmpty(env[PARENT_RUN_ENV]);
+  const runInstanceId = nonEmpty(env[PARENT_INSTANCE_ENV]);
+  const stateDir = nonEmpty(env[PARENT_STATE_DIR_ENV]);
+  const completeParent = run && runInstanceId && stateDir
+    ? { run, run_instance_id: runInstanceId, state_dir: stateDir }
+    : undefined;
+  if ((run || runInstanceId || stateDir) && !completeParent) {
+    throw new Error("Inherited Run delivery parent lineage is incomplete");
+  }
+  return {
+    delivery_owner_id: deliveryOwner,
+    ...(completeParent ? { delivery_parent: completeParent } : {}),
+  };
+}
+
+export function runDeliveryChildEnv(
+  lineage: RunDeliveryLineage,
+  parent: RunDeliveryParent,
+  env: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  return {
+    ...env,
+    [DELIVERY_OWNER_ENV]: lineage.delivery_owner_id,
+    [PARENT_RUN_ENV]: parent.run,
+    [PARENT_INSTANCE_ENV]: parent.run_instance_id,
+    [PARENT_STATE_DIR_ENV]: parent.state_dir,
+  };
+}
+
+export function getProcessDeliveryOwnerId(
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  return nonEmpty(env[DELIVERY_OWNER_ENV]);
+}

package/node_modules/@llblab/pi-actors/lib/run-delivery.ts

@@ -16,6 +16,10 @@ export type RunDeliveryPhase = "pending" | "queued" | "presented";
 
 export interface RunCompletionBatchMember {
   artifacts?: Record<string, string>;
+  parent_run?: string;
+  parent_run_instance_id?: string;
+  parent_state_dir?: string;
+  output?: string;
   run: string;
   run_instance_id: string;
   state_dir: string;
@@ -109,6 +113,10 @@ export interface RunSteerTransitionInput {
 const RUN_DELIVERY_SCHEMA = "run-delivery-v1";
 const MEMBER_FIELDS = new Set([
   "artifacts",
+  "parent_run",
+  "parent_run_instance_id",
+  "parent_state_dir",
+  "output",
   "run",
   "run_instance_id",
   "state_dir",
@@ -216,8 +224,40 @@ function parseMember(value: unknown): RunCompletionBatchMember {
   const record = asRecord(value, "Completion batch member");
   assertExactFields(record, MEMBER_FIELDS, "Completion batch member");
   const parsedArtifacts = artifacts(record.artifacts);
+  const parentRun = record.parent_run === undefined
+    ? undefined
+    : boundedString(record.parent_run, "Completion batch member parent_run", 120);
+  const parentRunInstanceId = record.parent_run_instance_id === undefined
+    ? undefined
+    : boundedString(
+        record.parent_run_instance_id,
+        "Completion batch member parent_run_instance_id",
+        256,
+      );
+  const parentStateDir = record.parent_state_dir === undefined
+    ? undefined
+    : boundedString(
+        record.parent_state_dir,
+        "Completion batch member parent_state_dir",
+        4_096,
+      );
+  if (Boolean(parentRun) !== Boolean(parentRunInstanceId) ||
+    Boolean(parentRun) !== Boolean(parentStateDir)) {
+    throw new Error("Completion batch member parent lineage is incomplete");
+  }
+  const output = record.output === undefined
+    ? undefined
+    : boundedString(record.output, "Completion batch member output", 4_000);
   return {
     ...(parsedArtifacts ? { artifacts: parsedArtifacts } : {}),
+    ...(output ? { output } : {}),
+    ...(parentRun
+      ? {
+          parent_run: parentRun,
+          parent_run_instance_id: parentRunInstanceId!,
+          parent_state_dir: parentStateDir!,
+        }
+      : {}),
     run: boundedString(record.run, "Completion batch member run", 120),
     run_instance_id: boundedString(
       record.run_instance_id,
@@ -740,7 +780,75 @@ function compactModelText(value: string, limit: number): string {
   return compact.length > limit ? `${compact.slice(0, limit - 1)}…` : compact;
 }
 
-function formatCompletionMember(member: RunCompletionBatchMember): string {
+function memberIdentity(member: RunCompletionBatchMember): string {
+  return `${member.state_dir}\0${member.run_instance_id}`;
+}
+
+function completionDepth(
+  member: RunCompletionBatchMember,
+  byIdentity: Map<string, RunCompletionBatchMember>,
+): number {
+  const visited = new Set<string>();
+  let current = member;
+  let depth = 0;
+  while (current.parent_state_dir && current.parent_run_instance_id) {
+    const identity = `${current.parent_state_dir}\0${current.parent_run_instance_id}`;
+    if (visited.has(identity)) break;
+    visited.add(identity);
+    const parent = byIdentity.get(identity);
+    if (!parent) break;
+    depth += 1;
+    current = parent;
+  }
+  return depth;
+}
+
+function orderCompletionForest(
+  members: RunCompletionBatchMember[],
+): RunCompletionBatchMember[] {
+  const byIdentity = new Map(members.map((member) => [memberIdentity(member), member]));
+  const children = new Map<string, RunCompletionBatchMember[]>();
+  const roots: RunCompletionBatchMember[] = [];
+  for (const member of members) {
+    const parentIdentity = member.parent_state_dir && member.parent_run_instance_id
+      ? `${member.parent_state_dir}\0${member.parent_run_instance_id}`
+      : undefined;
+    if (!parentIdentity || !byIdentity.has(parentIdentity)) {
+      roots.push(member);
+      continue;
+    }
+    const siblings = children.get(parentIdentity) ?? [];
+    siblings.push(member);
+    children.set(parentIdentity, siblings);
+  }
+  const ordered: RunCompletionBatchMember[] = [];
+  const visited = new Set<string>();
+  const visit = (member: RunCompletionBatchMember): void => {
+    const identity = memberIdentity(member);
+    if (visited.has(identity)) return;
+    visited.add(identity);
+    ordered.push(member);
+    for (const child of children.get(identity) ?? []) visit(child);
+  };
+  for (const root of roots) visit(root);
+  for (const member of members) visit(member);
+  return ordered;
+}
+
+function formatModelOutput(value: string, indent: string): string {
+  return value
+    .replaceAll("`", "'")
+    .split(/\r?\n/u)
+    .map((line) => line.trimEnd())
+    .filter((line, index, lines) => line || (index > 0 && index < lines.length - 1))
+    .map((line) => `${indent}  ${line}`)
+    .join("\n");
+}
+
+function formatCompletionMember(
+  member: RunCompletionBatchMember,
+  byIdentity: Map<string, RunCompletionBatchMember>,
+): string {
   const summary = compactModelText(member.summary, 200);
   const artifactEntries = Object.entries(member.artifacts ?? {}).slice(0, 4);
   const artifactText = artifactEntries.length === 0
@@ -748,7 +856,11 @@ function formatCompletionMember(member: RunCompletionBatchMember): string {
     : `; artifacts: ${artifactEntries.map(([name, path]) =>
       `${compactModelText(name, 120)}=\`${compactModelText(path, 320)}\``
     ).join(", ")}`;
-  return `- \`${compactModelText(member.run, 120)}\` — \`${member.status}\`: ${summary}${artifactText}`;
+  const indent = "  ".repeat(Math.min(completionDepth(member, byIdentity), 8));
+  const output = member.output
+    ? `\n${indent}  Output:\n${formatModelOutput(member.output, indent)}`
+    : "";
+  return `${indent}- \`${compactModelText(member.run, 120)}\` — \`${member.status}\`: ${summary}${artifactText}${output}`;
 }
 
 function formatStatusCounts(members: RunCompletionBatchMember[]): string {
@@ -772,9 +884,13 @@ export function formatRunCompletionBatchMessage(batch: RunCompletionBatch): stri
     `Window: \`${terminalTimes[0]}\` → \`${terminalTimes.at(-1)}\``,
     `Statuses: \`${formatStatusCounts(safe.members)}\``,
   ];
-  const candidateRows = safe.members
+  const byIdentity = new Map(safe.members.map((member) => [
+    memberIdentity(member),
+    member,
+  ]));
+  const candidateRows = orderCompletionForest(safe.members)
     .slice(0, Limits.RUN_DELIVERY_MODEL_MAX_MEMBERS)
-    .map(formatCompletionMember);
+    .map((member) => formatCompletionMember(member, byIdentity));
   const rows: string[] = [];
   for (const row of candidateRows) {
     const omitted = safe.members.length - rows.length - 1;