@llblab/pi-actors 0.22.5 → 0.23.0

package/dist/lib/actor-rooms.js

@@ -6,6 +6,7 @@
 import * as fs from "node:fs";
 import { randomUUID } from "node:crypto";
 import * as path from "node:path";
+import * as Limits from "./limits.js";
 import { notifyRuntimeWake } from "./runtime-notifier.js";
 const STATE_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
 const STATE_LOCK_TIMEOUT_MS = 5000;
@@ -128,8 +129,23 @@ function compactRoomMessages(stateDir, room) {
         return;
     const kept = lines.slice(-maxMessages);
     fs.writeFileSync(file, `${kept.join("\n")}\n`);
+    const keptMessages = kept.flatMap((line) => {
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        }
+    });
     writeJsonFile(path.join(roomDir(stateDir, room), "compaction.json"), {
         compacted_at: new Date().toISOString(),
+        dropped_count: lines.length - kept.length,
+        ...(keptMessages[0]?.received_at
+            ? { first_kept_at: keptMessages[0].received_at }
+            : {}),
+        ...(keptMessages.at(-1)?.received_at
+            ? { last_kept_at: keptMessages.at(-1)?.received_at }
+            : {}),
         max_messages: maxMessages,
     });
 }
@@ -250,20 +266,44 @@ function updateRosterForMessage(stateDir, room, message, receivedAt) {
             last_seen: receivedAt,
             ...(current?.caps !== undefined ? { caps: current.caps } : {}),
             ...(current?.claim !== undefined ? { claim: current.claim } : {}),
-            ...(current?.display !== undefined ? { display: current.display } : {}),
+            ...(current?.display !== undefined
+                ? { display: current.display }
+                : {}),
             ...(current?.parent !== undefined ? { parent: current.parent } : {}),
-            ...(current?.role !== undefined ? { role: current.role } : { role: "actor" }),
+            ...(current?.role !== undefined
+                ? { role: current.role }
+                : { role: "actor" }),
             status: String(body.status ?? "left"),
         }
         : {
             address: message.from,
             joined_at: current?.joined_at ?? receivedAt,
             last_seen: receivedAt,
-            ...(body.caps !== undefined ? { caps: body.caps } : current?.caps !== undefined ? { caps: current.caps } : {}),
-            ...(body.claim !== undefined ? { claim: body.claim } : current?.claim !== undefined ? { claim: current.claim } : {}),
-            ...(body.display !== undefined ? { display: body.display } : current?.display !== undefined ? { display: current.display } : {}),
-            ...(body.parent !== undefined ? { parent: body.parent } : current?.parent !== undefined ? { parent: current.parent } : {}),
-            ...(body.role !== undefined ? { role: body.role } : current?.role !== undefined ? { role: current.role } : { role: "actor" }),
+            ...(body.caps !== undefined
+                ? { caps: body.caps }
+                : current?.caps !== undefined
+                    ? { caps: current.caps }
+                    : {}),
+            ...(body.claim !== undefined
+                ? { claim: body.claim }
+                : current?.claim !== undefined
+                    ? { claim: current.claim }
+                    : {}),
+            ...(body.display !== undefined
+                ? { display: body.display }
+                : current?.display !== undefined
+                    ? { display: current.display }
+                    : {}),
+            ...(body.parent !== undefined
+                ? { parent: body.parent }
+                : current?.parent !== undefined
+                    ? { parent: current.parent }
+                    : {}),
+            ...(body.role !== undefined
+                ? { role: body.role }
+                : current?.role !== undefined
+                    ? { role: current.role }
+                    : { role: "actor" }),
             status: String(body.status ?? current?.status ?? "present"),
         };
     roster[message.from] = next;
@@ -368,7 +408,14 @@ export function updateBranchInboxMessageStatus(stateDir, run, address, id, statu
             if (!("message" in record) || record.message.id !== id)
                 return record;
             changed = true;
-            return { message: { ...record.message, ...metadata, [timestampKey]: new Date().toISOString(), status } };
+            return {
+                message: {
+                    ...record.message,
+                    ...metadata,
+                    [timestampKey]: new Date().toISOString(),
+                    status,
+                },
+            };
         });
         if (!changed)
             return false;
@@ -430,7 +477,7 @@ export function readRoomMessages(stateDir, room, limit = 40) {
         throw error;
     }
 }
-function previewValue(value, maxLength = 120) {
+function previewValue(value, maxLength = Limits.ROOM_MESSAGE_PREVIEW_CHARS) {
     if (value === undefined)
         return undefined;
     const text = typeof value === "string" ? value : JSON.stringify(value);
@@ -443,7 +490,9 @@ function previewValue(value, maxLength = 120) {
 }
 export function readRoomMessagePreviews(stateDir, room, limit = 40) {
     return readRoomMessages(stateDir, room, limit).map((message) => ({
-        ...(previewValue(message.body) ? { body_preview: previewValue(message.body) } : {}),
+        ...(previewValue(message.body)
+            ? { body_preview: previewValue(message.body) }
+            : {}),
         ...(message.from ? { from: message.from } : {}),
         ...(message.summary ? { summary: message.summary } : {}),
         timestamp: message.received_at,
@@ -454,6 +503,7 @@ export function readRoomMessagePreviews(stateDir, room, limit = 40) {
 export function getRoomStatus(stateDir, room) {
     const messageCount = readRoomMessageCount(stateDir, room);
     const [last] = readRoomMessages(stateDir, room, 1);
+    const compaction = readJsonFile(path.join(roomDir(stateDir, room), "compaction.json"), undefined);
     return {
         ...(last
             ? {
@@ -463,6 +513,7 @@ export function getRoomStatus(stateDir, room) {
                 last_message_type: last.type,
             }
             : {}),
+        ...(compaction ? { compaction } : {}),
         message_count: messageCount,
         room,
         roster_count: Object.keys(readRoomRoster(stateDir, room)).length,

package/dist/lib/async-runs.d.ts

@@ -29,7 +29,7 @@ export interface AsyncRunStartParams {
     timeout?: number | string;
     delay?: number | string;
     output?: string;
-    artifacts?: Record<string, string>;
+    artifacts?: Record<string, RunArtifactDeclaration>;
     mailbox?: RecipeReferences.TemplateRecipeMailbox;
     retire_when?: "children_terminal";
     retry?: number | string;
@@ -76,15 +76,43 @@ export interface AsyncRunMeta {
     tool?: string;
     template: CommandTemplateValue;
     values: Record<string, unknown>;
-    artifacts?: Record<string, string>;
+    artifacts?: Record<string, RunArtifactDeclaration>;
     control?: AsyncRunControlEndpoint;
     mailbox?: RecipeReferences.TemplateRecipeMailbox;
     recipe_context_records?: RecipeReferences.TemplateRecipeContextRecord[];
     retire_when?: "children_terminal";
 }
+export type RunArtifactDeclaration = string | {
+    path: string;
+    kind?: string;
+    media_type?: string;
+    required?: boolean;
+};
+export interface RunArtifactManifestEntry {
+    exists: boolean;
+    kind?: string;
+    media_type?: string;
+    path: string;
+    required?: boolean;
+    sha256?: string;
+    size?: number;
+}
+export declare function resolveArtifactManifest(artifacts: Record<string, RunArtifactDeclaration> | undefined): Record<string, RunArtifactManifestEntry> | undefined;
 export declare function startRun(params: AsyncRunStartParams, cwd: string): AsyncRunMeta;
 export declare function parseRunOutboxEventLine(line: string, run: string, stateDir: string, index: number): RunOutboxEvent | undefined;
 export declare function getRunStatus(runOrDir: string): Record<string, unknown>;
+export interface RunStateIndexEntry {
+    ownerId?: string;
+    recipe?: string;
+    run: string;
+    state_dir: string;
+    status: AsyncRunStatus;
+    tool?: string;
+    updated_at?: string;
+}
+export declare function listRunStateDirs(stateRoot?: string, depth?: number, seen?: Set<string>): string[];
+export declare function rebuildRunStateIndex(stateRoot?: string): RunStateIndexEntry[];
+export declare function readRunStateIndex(stateRoot?: string): RunStateIndexEntry[] | undefined;
 export declare function listRuns(stateRoot?: string, statusFilter?: string): Array<Record<string, unknown>>;
 export declare function tailRun(runOrDir: string, lines?: number): string;
 export declare function readRunEvents(runOrDir: string, lines?: number): RunOutboxEvent[];
@@ -132,4 +160,8 @@ export interface RunProcessSignalPlan {
 }
 export declare function getRunProcessSignalPlan(pid: number, signal: NodeJS.Signals, runtimePlatform?: NodeJS.Platform): RunProcessSignalPlan;
 export declare function cancelRun(runOrDir: string): Record<string, unknown>;
+export declare function archiveRun(runOrDir: string): Record<string, unknown>;
+export declare function pruneRun(runOrDir: string, options?: {
+    preserveArtifacts?: boolean;
+}): Record<string, unknown>;
 export declare function killRun(runOrDir: string): Record<string, unknown>;

package/dist/lib/async-runs.js

@@ -4,8 +4,8 @@
  * Owns detached run state, observation, log tailing, listing, and cancellation safety
  */
 import { spawn, spawnSync } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { closeSync, constants, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, writeFileSync, writeSync, } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, constants, existsSync, mkdirSync, openSync, readdirSync, readFileSync, cpSync, readlinkSync, renameSync, rmSync, statSync, writeFileSync, writeSync, } from "node:fs";
 import { createConnection } from "node:net";
 import { platform } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
@@ -48,10 +48,60 @@ function resolveArtifactPaths(artifacts, values) {
     for (const [key, value] of Object.entries(artifacts)) {
         if (!key.trim())
             continue;
-        resolved[key] = substituteCommandTemplateToken(value, values, `recipe artifacts.${key}`);
+        if (typeof value === "string") {
+            resolved[key] = substituteCommandTemplateToken(value, values, `recipe artifacts.${key}`);
+        }
+        else if (value &&
+            typeof value === "object" &&
+            typeof value.path === "string") {
+            resolved[key] = {
+                ...value,
+                path: substituteCommandTemplateToken(value.path, values, `recipe artifacts.${key}.path`),
+            };
+        }
     }
     return Object.keys(resolved).length > 0 ? resolved : undefined;
 }
+export function resolveArtifactManifest(artifacts) {
+    if (!artifacts)
+        return undefined;
+    const manifest = {};
+    for (const [name, artifact] of Object.entries(artifacts)) {
+        const declaration = typeof artifact === "string" ? { path: artifact } : artifact;
+        if (!declaration?.path)
+            continue;
+        try {
+            const content = readFileSync(declaration.path);
+            manifest[name] = {
+                exists: true,
+                ...(declaration.kind ? { kind: declaration.kind } : {}),
+                ...(declaration.media_type
+                    ? { media_type: declaration.media_type }
+                    : {}),
+                path: declaration.path,
+                ...(declaration.required !== undefined
+                    ? { required: declaration.required }
+                    : {}),
+                sha256: createHash("sha256").update(content).digest("hex"),
+                size: content.byteLength,
+            };
+        }
+        catch {
+            manifest[name] = {
+                exists: false,
+                ...(declaration.kind ? { kind: declaration.kind } : {}),
+                ...(declaration.media_type
+                    ? { media_type: declaration.media_type }
+                    : {}),
+                path: declaration.path,
+                ...(declaration.required !== undefined
+                    ? { required: declaration.required }
+                    : {}),
+            };
+        }
+    }
+    return Object.keys(manifest).length > 0 ? manifest : undefined;
+}
 function resolveRunTemplate(params) {
     if (!params.template)
         throw new Error("spawn requires file or template.");
@@ -270,7 +320,7 @@ export function startRun(params, cwd) {
             ? RecipeReferences.buildRecipeContextRecords(recipeFile)
             : undefined;
         if (recipeFile && isMutableUsageRecipeFile(recipeFile)) {
-            RecipeUsage.recordRecipeLaunch(recipeFile);
+            RecipeUsage.recordRecipeLaunch(recipeFile, new Date(), startParams.launch_source === "tool" ? "tool" : "spawn");
         }
         const outFd = openSync(stdout, "a");
         const errFd = openSync(stderr, "a");
@@ -440,31 +490,111 @@ function matchesStatusFilter(status, filter) {
         return status !== "running";
     return status === filter;
 }
-export function listRuns(stateRoot = DEFAULT_STATE_ROOT, statusFilter) {
-    if (!existsSync(stateRoot))
+export function listRunStateDirs(stateRoot = DEFAULT_STATE_ROOT, depth = 0, seen = new Set()) {
+    if (!existsSync(stateRoot) || seen.has(resolve(stateRoot)))
+        return [];
+    seen.add(resolve(stateRoot));
+    let entries;
+    try {
+        entries = readdirSync(stateRoot, { withFileTypes: true });
+    }
+    catch {
         return [];
-    const runs = [];
-    for (const entry of readdirSync(stateRoot, { withFileTypes: true })) {
+    }
+    const result = [];
+    for (const entry of entries) {
         if (!entry.isDirectory())
             continue;
+        const child = join(stateRoot, entry.name);
+        if (existsSync(join(child, "run.json")))
+            result.push(child);
+        if (depth + 1 < 8)
+            result.push(...listRunStateDirs(child, depth + 1, seen));
+    }
+    return result;
+}
+function runIndexPath(stateRoot) {
+    return join(stateRoot, "index.json");
+}
+function indexEntryFromStatus(status) {
+    const progress = status.progress && typeof status.progress === "object"
+        ? status.progress
+        : {};
+    return {
+        ...(typeof status.ownerId === "string" ? { ownerId: status.ownerId } : {}),
+        ...(typeof status.recipe === "string" ? { recipe: status.recipe } : {}),
+        run: String(status.run),
+        state_dir: String(status.state_dir),
+        status: status.status,
+        ...(typeof status.tool === "string" ? { tool: status.tool } : {}),
+        updated_at: typeof progress.updatedAt === "string"
+            ? progress.updatedAt
+            : typeof status.createdAt === "string"
+                ? status.createdAt
+                : new Date(0).toISOString(),
+    };
+}
+export function rebuildRunStateIndex(stateRoot = DEFAULT_STATE_ROOT) {
+    mkdirSync(stateRoot, { recursive: true });
+    const entries = listRunStateDirs(stateRoot)
+        .flatMap((stateDir) => {
         try {
-            const stateDir = join(stateRoot, entry.name);
-            const status = getRunStatus(stateDir);
-            if (!matchesStatusFilter(status.status, statusFilter))
-                continue;
-            runs.push({
-                run: status.run,
-                state_dir: stateDir,
-                status: status.status,
-                ...(typeof status.tool === "string" ? { tool: status.tool } : {}),
-                ...(typeof status.recipe === "string" ? { recipe: status.recipe } : {}),
-            });
+            return [indexEntryFromStatus(getRunStatus(stateDir))];
         }
         catch {
-            // Ignore malformed run dirs.
+            return [];
         }
+    })
+        .sort((a, b) => (b.updated_at ?? "").localeCompare(a.updated_at ?? ""));
+    writeJsonAtomic(runIndexPath(stateRoot), {
+        entries,
+        rebuilt_at: new Date().toISOString(),
+    });
+    return entries;
+}
+export function readRunStateIndex(stateRoot = DEFAULT_STATE_ROOT) {
+    const index = readJson(runIndexPath(stateRoot));
+    if (!index || typeof index !== "object")
+        return undefined;
+    const entries = index.entries;
+    if (!Array.isArray(entries))
+        return undefined;
+    const valid = entries.filter((entry) => {
+        const record = entry && typeof entry === "object"
+            ? entry
+            : {};
+        return (typeof record.run === "string" &&
+            typeof record.state_dir === "string" &&
+            typeof record.status === "string");
+    });
+    if (valid.some((entry) => !existsSync(join(entry.state_dir, "run.json"))))
+        return undefined;
+    return valid;
+}
+export function listRuns(stateRoot = DEFAULT_STATE_ROOT, statusFilter) {
+    if (!existsSync(stateRoot))
+        return [];
+    const indexed = readRunStateIndex(stateRoot);
+    if (indexed) {
+        return indexed
+            .filter((entry) => matchesStatusFilter(entry.status, statusFilter))
+            .map((entry) => ({
+            run: entry.run,
+            state_dir: entry.state_dir,
+            status: entry.status,
+            ...(entry.tool ? { tool: entry.tool } : {}),
+            ...(entry.recipe ? { recipe: entry.recipe } : {}),
+        }));
     }
-    return runs;
+    return rebuildRunStateIndex(stateRoot)
+        .filter((entry) => matchesStatusFilter(entry.status, statusFilter))
+        .map((entry) => ({
+        run: entry.run,
+        state_dir: entry.state_dir,
+        status: entry.status,
+        ...(entry.tool ? { tool: entry.tool } : {}),
+        ...(entry.recipe ? { recipe: entry.recipe } : {}),
+    }));
 }
 export function tailRun(runOrDir, lines = 40) {
     const status = getRunStatus(runOrDir);
@@ -630,11 +760,18 @@ export function appendRunOutboxEvent(runOrDir, event) {
     const run = String(status.run ?? runOrDir);
     const type = event.type || event.event || "run.message";
     const to = event.to || "coordinator";
+    const metadata = event.metadata ?? {};
+    const requiresResponse = metadata.requires_response === true;
     const payload = {
         ...(event.body !== undefined ? { body: event.body } : {}),
         ...(event.correlation_id ? { correlation_id: event.correlation_id } : {}),
         ...(event.data !== undefined ? { data: event.data } : {}),
-        delivery: normalizeRunOutboxDelivery(event.delivery ?? (to === "coordinator" ? "followup" : "log")),
+        delivery: normalizeRunOutboxDelivery(event.delivery ??
+            (requiresResponse
+                ? "followup"
+                : to === "coordinator"
+                    ? "notify"
+                    : "log")),
         event: type,
         from: event.from || `run:${run}`,
         level: normalizeRunOutboxLevel(event.level),
@@ -905,6 +1042,62 @@ export function cancelRun(runOrDir) {
         ? { cancelled: result.stopped, ...result }
         : result;
 }
+function assertTerminalRun(runOrDir) {
+    const status = getRunStatus(runOrDir);
+    if (status.status === "running") {
+        throw new Error("Only terminal runs can be archived or pruned.");
+    }
+    return status;
+}
+function archivePathFor(run, stateDir) {
+    const archiveRoot = join(dirname(stateDir), "archived");
+    mkdirSync(archiveRoot, { recursive: true });
+    return join(archiveRoot, `${safeRunId(run)}-${new Date().toISOString().replace(/[:.]/g, "-")}`);
+}
+export function archiveRun(runOrDir) {
+    const status = assertTerminalRun(runOrDir);
+    const stateDir = String(status.state_dir);
+    const run = String(status.run ?? basename(stateDir));
+    const archiveDir = archivePathFor(run, stateDir);
+    renameSync(stateDir, archiveDir);
+    mkdirSync(stateDir, { recursive: true });
+    const tombstone = {
+        archived: true,
+        archive_dir: archiveDir,
+        original_state_dir: stateDir,
+        run,
+        status: status.status,
+        ts: new Date().toISOString(),
+    };
+    writeJsonAtomic(join(stateDir, "archive-tombstone.json"), tombstone);
+    return tombstone;
+}
+export function pruneRun(runOrDir, options = {}) {
+    const status = assertTerminalRun(runOrDir);
+    const stateDir = String(status.state_dir);
+    const run = String(status.run ?? basename(stateDir));
+    const manifest = resolveArtifactManifest(status.artifacts);
+    const preserved = {};
+    if (options.preserveArtifacts && manifest) {
+        const preserveRoot = join(dirname(stateDir), "preserved-artifacts", safeRunId(run));
+        mkdirSync(preserveRoot, { recursive: true });
+        for (const [name, artifact] of Object.entries(manifest)) {
+            if (!artifact.exists)
+                continue;
+            const target = join(preserveRoot, basename(artifact.path));
+            cpSync(artifact.path, target, { force: true });
+            preserved[name] = target;
+        }
+    }
+    rmSync(stateDir, { recursive: true, force: true });
+    return {
+        pruned: true,
+        preserved_artifacts: preserved,
+        run,
+        state_dir: stateDir,
+        ts: new Date().toISOString(),
+    };
+}
 export function killRun(runOrDir) {
     const result = stopRun(runOrDir, "SIGKILL", "run.kill");
     return Object.hasOwn(result, "stopped")

package/dist/lib/command-templates.js

@@ -102,23 +102,23 @@ function getLeafCommandTemplateWarnings(config) {
         const shellContent = hasAnyFlag(args, ["-c"])
             ? "shell command strings"
             : "shell scripts";
-        warnings.push(`${config.label ?? command}: invokes ${command}; ${shellContent} are trusted executable content and are not sandboxed by command-template argv splitting.`);
+        warnings.push(`${config.label ?? command}: invokes ${command}; ${shellContent} are trusted executable content and are not sandboxed by command-template argv splitting. Mitigation: keep scripts local, reviewed, and parameterized with explicit placeholders.`);
     }
     if (["node", "deno", "bun"].includes(command) &&
         hasAnyFlag(args, ["-e", "--eval"])) {
-        warnings.push(`${config.label ?? command}: invokes ${command} eval mode; code strings are trusted executable content and are not sandboxed.`);
+        warnings.push(`${config.label ?? command}: invokes ${command} eval mode; code strings are trusted executable content and are not sandboxed. Mitigation: prefer a checked-in script file or keep eval input fixed and reviewed.`);
     }
     if (["python", "python3", "perl", "ruby"].includes(command) &&
         hasAnyFlag(args, ["-c", "-e"])) {
-        warnings.push(`${config.label ?? command}: invokes ${command} code-eval mode; code strings are trusted executable content and are not sandboxed.`);
+        warnings.push(`${config.label ?? command}: invokes ${command} code-eval mode; code strings are trusted executable content and are not sandboxed. Mitigation: prefer a checked-in script file or keep eval input fixed and reviewed.`);
     }
     if (command === "rm" &&
         (args.some((arg) => /^-[^-]*r/.test(arg) || /^-[^-]*f/.test(arg)) ||
             hasRiskyPathArg(args))) {
-        warnings.push(`${config.label ?? command}: removes filesystem paths; verify placeholders and paths before running trusted destructive commands.`);
+        warnings.push(`${config.label ?? command}: removes filesystem paths; verify placeholders and paths before running trusted destructive commands. Mitigation: constrain path placeholders and consider dry-run or explicit confirmation.`);
     }
     if (["mv", "cp", "rsync"].includes(command) && hasRiskyPathArg(args)) {
-        warnings.push(`${config.label ?? command}: mutates broad filesystem paths; verify placeholders and paths before running trusted commands.`);
+        warnings.push(`${config.label ?? command}: mutates broad filesystem paths; verify placeholders and paths before running trusted commands. Mitigation: constrain path placeholders and prefer narrow source/destination paths.`);
     }
     return warnings;
 }

package/dist/lib/limits.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared output and preview size limits.
+ * Zones: output governance, actor-message previews, inspect defaults
+ */
+export declare const DEFAULT_INSPECT_LINES = 40;
+export declare const TOOL_OUTPUT_MAX_BYTES: number;
+export declare const TOOL_OUTPUT_MAX_LINES = 2000;
+export declare const COMPACT_PREVIEW_CHARS = 160;
+export declare const INSPECTOR_BODY_PREVIEW_CHARS = 320;
+export declare const ROOM_MESSAGE_PREVIEW_CHARS = 320;
+export declare const DOCTOR_ACTION_PREVIEW_CHARS = 72;

package/dist/lib/limits.js

@@ -0,0 +1,11 @@
+/**
+ * Shared output and preview size limits.
+ * Zones: output governance, actor-message previews, inspect defaults
+ */
+export const DEFAULT_INSPECT_LINES = 40;
+export const TOOL_OUTPUT_MAX_BYTES = 50 * 1024;
+export const TOOL_OUTPUT_MAX_LINES = 2_000;
+export const COMPACT_PREVIEW_CHARS = 160;
+export const INSPECTOR_BODY_PREVIEW_CHARS = 320;
+export const ROOM_MESSAGE_PREVIEW_CHARS = 320;
+export const DOCTOR_ACTION_PREVIEW_CHARS = 72;

package/dist/lib/observability.js

@@ -35,7 +35,7 @@ function getUpdatedAt(status) {
             ? status.createdAt
             : undefined;
 }
-function listRunStateDirs(stateRoot, depth = 0, seen = new Set()) {
+function scanRunStateDirs(stateRoot, depth = 0, seen = new Set()) {
     if (!existsSync(stateRoot) || seen.has(stateRoot))
         return [];
     seen.add(stateRoot);
@@ -54,7 +54,7 @@ function listRunStateDirs(stateRoot, depth = 0, seen = new Set()) {
         if (existsSync(join(child, "run.json")))
             result.push(child);
         if (depth + 1 < RUN_STATE_DISCOVERY_MAX_DEPTH)
-            result.push(...listRunStateDirs(child, depth + 1, seen));
+            result.push(...scanRunStateDirs(child, depth + 1, seen));
     }
     return result;
 }
@@ -114,7 +114,8 @@ export function summarizeRuns(stateRoot = Paths.getRunStateRoot(), ownerId) {
             total: 0,
         };
     }
-    const runs = listRunStateDirs(stateRoot)
+    const runs = (AsyncRuns.readRunStateIndex(stateRoot)?.map((entry) => entry.state_dir) ??
+        scanRunStateDirs(stateRoot))
         .map((stateDir) => observeRun(stateDir))
         .filter((run) => Boolean(run))
         .filter((run) => ownerId === undefined || run.ownerId === ownerId)
@@ -190,7 +191,8 @@ function summarizeRunsWithoutSubagents(stateRoot, ownerId) {
             runs: [],
             total: 0,
         };
-    const runs = listRunStateDirs(stateRoot)
+    const runs = (AsyncRuns.readRunStateIndex(stateRoot)?.map((entry) => entry.state_dir) ??
+        scanRunStateDirs(stateRoot))
         .map((stateDir) => observeRun(stateDir))
         .filter((run) => Boolean(run))
         .filter((run) => ownerId === undefined || run.ownerId === ownerId)

package/dist/lib/output.js

@@ -6,9 +6,8 @@
 import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { sanitizeFilePart } from "./identity.js";
+import * as Limits from "./limits.js";
 import * as Paths from "./paths.js";
-const MAX_OUTPUT_BYTES = 50 * 1024;
-const MAX_OUTPUT_LINES = 2_000;
 export function writeFullOutput(toolName, stream, content) {
     try {
         const outputRoot = join(Paths.getExtensionTmpDir(), "outputs");
@@ -45,10 +44,10 @@ export function truncateTailContent(content) {
     const totalBytes = byteLength(content);
     const lines = content.split("\n");
     const totalLines = lines.length;
-    let output = totalLines > MAX_OUTPUT_LINES
-        ? lines.slice(-MAX_OUTPUT_LINES).join("\n")
+    let output = totalLines > Limits.TOOL_OUTPUT_MAX_LINES
+        ? lines.slice(-Limits.TOOL_OUTPUT_MAX_LINES).join("\n")
         : content;
-    output = trimToTailBytes(output, MAX_OUTPUT_BYTES);
+    output = trimToTailBytes(output, Limits.TOOL_OUTPUT_MAX_BYTES);
     const outputBytes = byteLength(output);
     const outputLines = output ? output.split("\n").length : 0;
     return {

package/dist/lib/recipe-discovery.js

@@ -351,6 +351,7 @@ export function summarizeDiscovery(result) {
             disabled: entry.disabled,
             invalid: entry.invalid,
             shadows: entry.shadows,
+            ...(entry.config?.imports ? { imports: entry.config.imports } : {}),
             ...(recipeUsage(entry.config)
                 ? { usage: recipeUsage(entry.config) }
                 : {}),

package/dist/lib/recipe-references.d.ts

@@ -11,9 +11,18 @@ export interface TemplateRecipeImportBinding {
     values?: Record<string, unknown>;
 }
 export type TemplateRecipeImport = string | TemplateRecipeImportBinding;
+export type TemplateRecipeMailboxEntry = string | {
+    type: string;
+    body_schema?: unknown;
+    ack?: boolean | string;
+    idempotency?: string;
+    requires_response?: boolean;
+    level?: string;
+    summary?: string;
+};
 export interface TemplateRecipeMailbox {
-    accepts?: string[];
-    emits?: string[];
+    accepts?: TemplateRecipeMailboxEntry[];
+    emits?: TemplateRecipeMailboxEntry[];
 }
 export interface TemplateRecipeDefinition {
     name?: string;

package/dist/lib/recipe-references.js

@@ -630,12 +630,14 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
                 mailbox: {
                     ...(Array.isArray(substituted.mailbox.accepts)
                         ? {
-                            accepts: substituted.mailbox.accepts.filter((value) => typeof value === "string"),
+                            accepts: substituted.mailbox.accepts.filter((value) => typeof value === "string" ||
+                                (isRecord(value) && typeof value.type === "string")),
                         }
                         : {}),
                     ...(Array.isArray(substituted.mailbox.emits)
                         ? {
-                            emits: substituted.mailbox.emits.filter((value) => typeof value === "string"),
+                            emits: substituted.mailbox.emits.filter((value) => typeof value === "string" ||
+                                (isRecord(value) && typeof value.type === "string")),
                         }
                         : {}),
                 },

package/dist/lib/recipe-usage.d.ts

@@ -3,4 +3,5 @@
  * Zones: recipe telemetry, muscle-memory cleanup evidence
  * Owns lightweight launch counters for user-owned recipe files
  */
-export declare function recordRecipeLaunch(path: string, now?: Date): boolean;
+export type RecipeLaunchKind = "direct" | "spawn" | "tool";
+export declare function recordRecipeLaunch(path: string, now?: Date, kind?: RecipeLaunchKind): boolean;