@llblab/pi-actors 0.43.1 → 0.45.0

package/lib/schema.ts

@@ -185,7 +185,11 @@ function isValidDefault(type: ToolArgType, value: string): boolean {
 }
 
 export function parseToolArgDeclarations(value: string): ToolArgSpec {
-  const source = splitArgDeclarations(value);
+  return parseToolArgDeclarationList(splitArgDeclarations(value));
+}
+
+export function parseToolArgDeclarationList(value: unknown[]): ToolArgSpec {
+  const source = value.map(String);
   const seen = new Set<string>();
   const duplicates = new Set<string>();
   const args: string[] = [];
@@ -324,6 +328,7 @@ function collectCommandTemplateConfigDeclarations(
     collectTemplatePlaceholderDeclarations(config, declarations);
     return;
   }
+  if (!config || typeof config !== "object") return;
   if (Array.isArray(config)) {
     for (const step of config)
       collectCommandTemplateConfigDeclarations(step, declarations);
@@ -356,11 +361,42 @@ export function getTemplatePlaceholderNames(
   );
 }
 
+function toolArgTypesEqual(left: ToolArgType, right: ToolArgType): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+export function assertCompatibleToolArgTypes(
+  ...sources: Array<Record<string, ToolArgType> | undefined>
+): void {
+  const seen: Record<string, ToolArgType> = {};
+  for (const source of sources) {
+    for (const [name, type] of Object.entries(source ?? {})) {
+      const previous = seen[name];
+      if (previous && !toolArgTypesEqual(previous, type)) {
+        throw new Error(
+          `Conflicting argument type for ${name}: ${canonicalArgDeclaration(name, previous)} vs ${canonicalArgDeclaration(name, type)}`,
+        );
+      }
+      seen[name] = type;
+    }
+  }
+}
+
 export function getTemplateArgTypes(
   config: CommandTemplates.CommandTemplateConfig,
 ): Record<string, ToolArgType> {
   const argTypes: Record<string, ToolArgType> = {};
   for (const declaration of getTemplatePlaceholderDeclarations(config)) {
+    const previous = argTypes[declaration.arg];
+    if (
+      previous &&
+      declaration.type.kind !== "string" &&
+      !toolArgTypesEqual(previous, declaration.type)
+    ) {
+      throw new Error(
+        `Conflicting argument type for ${declaration.arg}: ${canonicalArgDeclaration(declaration.arg, previous)} vs ${declaration.declaration}`,
+      );
+    }
     if (declaration.type.kind !== "string")
       argTypes[declaration.arg] = declaration.type;
   }
@@ -373,6 +409,22 @@ export function getExplicitToolArgNames(args: string[] | undefined): string[] {
   );
 }
 
+export function getExplicitToolArgDefaults(
+  args: string[] | string | undefined,
+): Record<string, string> {
+  const declarations =
+    typeof args === "string" ? splitArgDeclarations(args) : (args ?? []);
+  return Object.fromEntries(
+    declarations
+      .map((item) => parseToolArgToken(String(item)))
+      .filter(
+        (item): item is ParsedToolArgToken & { defaultValue: string } =>
+          item.defaultValue !== undefined,
+      )
+      .map((item) => [item.arg, item.defaultValue]),
+  );
+}
+
 export function getToolArgNames(
   config: CommandTemplates.CommandTemplateConfig,
 ): string[] {

package/lib/tools-inspect.ts

@@ -4,14 +4,17 @@
  * 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 RecipesReferences from "./recipes-references.ts";
 import * as ReviewDiagnostics from "./review-diagnostics.ts";
 import * as RunsControls from "./runs-controls.ts";
 import * as RunControlDelivery from "./runs-control-delivery.ts";
@@ -75,20 +78,26 @@ function runtimeTriage(
   const failed = runs.filter((run) => run.status === "failed");
   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) 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,
+      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(
         {
@@ -137,14 +146,15 @@ function runtimeTriage(
     pending_controls: boundedPendingControls,
     stale_control_count: staleControls.length,
     stale_controls: boundedStaleControls,
-    control_diagnostic_count: controlDiagnostics.length,
-    control_diagnostics: controlDiagnostics.slice(0, 40),
+    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.slice(0, 3).map((entry) =>
+      ...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`,
@@ -159,7 +169,7 @@ 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} pending_controls=${Number(details.pending_control_count ?? 0)} stale_controls=${Number(details.stale_control_count ?? 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)} state_schema=${String(details.state_schema)} automatic_review=${String(details.automatic_review)}`;
 }
@@ -205,8 +215,18 @@ function inspectRecipes(
     { root: recipeRoot, defaultTool: true, mutableUsage: true },
     { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
   ]);
+  const skillRecipeNamespaces =
+    RecipesReferences.getActiveSkillRecipeNamespaces();
   const summary = {
     ...RecipesDiscovery.summarizeDiscovery(discovered),
+    skill_recipe_namespaces: skillRecipeNamespaces,
+    skill_recipe_namespace_diagnostics: Object.entries(skillRecipeNamespaces)
+      .filter(([, roots]) => roots.length > 1)
+      .map(([name, roots]) => ({
+        name,
+        roots,
+        error: `Ambiguous active Skill Recipe namespace ${name}`,
+      })),
     drafts: RecipesDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
   };
   return {
@@ -252,8 +272,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>
@@ -264,19 +284,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()
-      .map(ControlProjection.projectRunControl),
+    recent_controls: journal.records.slice(-Math.max(1, Number(input.lines || 20))).reverse()
+      .map((control) => ControlProjection.projectRunControl(control as RunsControls.RunControlRecord)),
   };
 }
 

package/lib/tools-local.ts

@@ -67,11 +67,16 @@ function formatRuntimeToolUsageHint(
   includeRunId: boolean,
 ): string {
   const optional = cfg.args.filter((arg) => !required.includes(arg));
+  const exampleDefaults = {
+    ...Schema.getExplicitToolArgDefaults(cfg.recipe?.args),
+    ...cfg.defaults,
+    ...(cfg.recipe?.values ?? {}),
+  };
   const example: Record<string, unknown> = {};
   for (const arg of required)
-    example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], cfg.defaults);
+    example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], exampleDefaults);
   for (const arg of optional)
-    example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], cfg.defaults);
+    example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], exampleDefaults);
   if (includeRunId) example.run_id = `${cfg.name}-1`;
   const lines = [
     `Expected call shape for ${cfg.name}:`,
@@ -85,6 +90,32 @@ function formatRuntimeToolUsageHint(
   return lines.join("\n");
 }
 
+function resolveRecipeToolValues(
+  cfg: RegisteredTool,
+  callerValues: Record<string, unknown>,
+  ctx: RuntimeToolContext,
+): Record<string, unknown> {
+  const recipeRuntimeValues = {
+    ...(cfg.recipe?.recipe_dir
+      ? { recipe_dir: cfg.recipe.recipe_dir }
+      : {}),
+    ...(cfg.recipe?.skill_dir ? { skill_dir: cfg.recipe.skill_dir } : {}),
+  };
+  return Schema.normalizeRuntimeValues(
+    ModelContext.withCurrentModelValues(
+      {
+        ...Schema.getExplicitToolArgDefaults(cfg.recipe?.args),
+        ...cfg.defaults,
+        ...(cfg.recipe?.values ?? {}),
+        ...callerValues,
+        ...recipeRuntimeValues,
+      },
+      ctx,
+    ),
+    cfg.argTypes,
+  );
+}
+
 function formatRuntimeToolArgumentError(
   cfg: RegisteredTool,
   error: unknown,
@@ -128,9 +159,18 @@ export function createRuntimeToolDefinition(
           defaults: cfg.defaults,
           template: requiredTemplate,
         };
+  const recipeInlineDefaults = Schema.getExplicitToolArgDefaults(
+    cfg.recipe?.args,
+  );
   const requiredArgs =
     isRecipe && cfg.storedArgs !== undefined
-      ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
+      ? new Set(
+          cfg.args.filter(
+            (arg) =>
+              !Object.hasOwn(cfg.defaults, arg) &&
+              !Object.hasOwn(recipeInlineDefaults, arg),
+          ),
+        )
       : RecipesReferences.isRecipeReference(cfg.template) && !recipeTemplate
         ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
         : Schema.getRequiredToolArgNames(requiredTemplateConfig);
@@ -200,13 +240,7 @@ export function createRuntimeToolDefinition(
                 { ...(cfg.recipe?.values ?? {}), ...values },
                 ctx,
               ),
-              values: Schema.normalizeRuntimeValues(
-                ModelContext.withCurrentModelValues(
-                  { ...(cfg.recipe?.values ?? {}), ...cfg.defaults, ...values },
-                  ctx,
-                ),
-                cfg.argTypes,
-              ),
+              values: resolveRecipeToolValues(cfg, values, ctx),
             },
             ctx.cwd,
           );
@@ -221,17 +255,13 @@ export function createRuntimeToolDefinition(
           };
         }
         if (isRecipe && recipeTemplate) {
-          const paramsWithDefaults = ModelContext.withCurrentModelValues(
-            {
-              ...(cfg.recipe?.values ?? {}),
-              ...cfg.defaults,
-              ...(params as Record<string, unknown>),
-            },
-            ctx,
-          );
           return await Execution.executeRegisteredTool(
             { ...cfg, template: recipeTemplate },
-            Schema.normalizeRuntimeValues(paramsWithDefaults, cfg.argTypes),
+            resolveRecipeToolValues(
+              cfg,
+              params as Record<string, unknown>,
+              ctx,
+            ),
             exec,
             ctx.cwd,
             signal,

package/lib/tools-spawn.ts

@@ -138,10 +138,10 @@ export function createSpawnToolDefinition<
           "Optional Run identity in exact run:<id> form.",
         ),
         file: Schema.stringSchema(
-          "Optional template recipe JSON file. Bare names resolve under ~/.pi/agent/recipes.",
+          "Optional template Recipe reference. Supports paths, bare user/adjacent/std names, std:<name>, and skill:<skill>/<recipe>.",
         ),
         recipe: Schema.stringSchema(
-          "Alias for file; template recipe JSON file/name to spawn.",
+          "Alias for file; qualified Skill/std or ordinary Recipe reference to spawn.",
         ),
         template: Schema.unionSchema([
           Schema.stringSchema("Inline command template string"),

package/lib/trace-projection.ts

@@ -14,13 +14,13 @@ 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";
 
@@ -44,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 ??
@@ -98,125 +131,154 @@ function controlDiagnosticItems(
   }));
 }
 
-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 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): TraceItem[] {
-  const read = readJsonlFileResilient<RunControlRecord>(
-    join(stateDir, "controls.jsonl"),
-  );
+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) => {
-      const projected = ControlProjection.projectRunControl(control);
-      return {
-        id: `control:${projected.id}`,
-        ts: latestControlTimestamp(projected),
-        source: "control" as const,
-        kind: `control.${projected.status}`,
-        summary: `${projected.action} ${projected.status}`,
-        ...(projected.status === "failed" ? { level: "error" as const } : {}),
-        detail: projected,
-      };
-    }),
-    ...controlDiagnosticItems(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(
@@ -236,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.1",
+  "version": "0.45.0",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [