@llblab/pi-actors 0.42.3 → 0.43.0

package/dist/lib/tools-inspect.js

@@ -1,763 +1,258 @@
 /**
- * Public inspect tool behavior
- * Zones: actor observation, recipe registry inspection, room/session/tool/run views
- * Owns the public inspect execution path and compact observation responses
+ * Public inspect tool behavior.
+ * Zones: Run Recipe/Trace/Control views and runtime/recipe/tool diagnostics
+ * Owns exact inspect target/view dispatch; source projection stays in domain modules.
  */
-import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join } from "node:path";
 import * as AsyncRuns from "./async-runs.js";
+import * as Inspector from "./inspector.js";
 import * as Limits from "./limits.js";
-import * as Messages from "./messages.js";
 import * as Paths from "./paths.js";
 import * as RecipesDiscovery from "./recipes-discovery.js";
 import * as ReviewDiagnostics from "./review-diagnostics.js";
-import * as Rooms from "./rooms.js";
+import * as RunsControls from "./runs-controls.js";
+import * as RunControlDelivery from "./runs-control-delivery.js";
+import * as RunsTrace from "./runs-trace.js";
 import * as Schema from "./schema.js";
 import * as ToolsAccess from "./tools-access.js";
-import * as ToolsMailbox from "./tools-mailbox.js";
 import * as ToolsResponse from "./tools-response.js";
+import * as TraceProjection from "./trace-projection.js";
 const asRecord = ToolsResponse.asRecord;
 const maybeJsonText = ToolsResponse.maybeJsonText;
-function compactAutomaticReviewDiagnostics(diagnostics) {
-    const draft = asRecord(diagnostics.draft_review);
-    const tool = asRecord(diagnostics.tool_review);
-    return [
-        `automatic_reviews draft=${String(draft.phase ?? "idle")} tool=${String(tool.phase ?? "idle")}`,
-        `lineages=${String(diagnostics.lineage_count ?? 0)} revision_snapshots=${String(diagnostics.revision_snapshots ?? 0)}`,
-    ].join("\n");
-}
-function compactRunMessages(messages) {
-    if (messages.length === 0)
-        return "\n(no actor messages)";
-    return `\n${messages
-        .map((message) => [
-        `run=${message.run}`,
-        `type=${message.event}`,
-        `level=${message.level}`,
-        `summary=${message.summary.replaceAll(/\s+/g, "_")}`,
-    ].join(" "))
-        .join("\n")}`;
-}
-function compactRoomPreviews(previews) {
-    if (previews.length === 0)
-        return "\n(no room message previews)";
-    return `\n${previews
-        .map((preview) => [
-        `ts=${preview.timestamp}`,
-        preview.from ? `from=${preview.from}` : "",
-        `to=${preview.to}`,
-        `type=${preview.type}`,
-        preview.summary
-            ? `summary=${ToolsResponse.compactPreview(preview.summary)}`
-            : "",
-        preview.body_preview
-            ? `body=${ToolsResponse.compactPreview(preview.body_preview)}`
-            : "",
-    ]
-        .filter(Boolean)
-        .join(" "))
-        .join("\n")}`;
-}
-function compactRoomMessages(messages) {
-    if (messages.length === 0)
-        return "\n(no room messages)";
-    return `\n${messages
-        .map((message) => [
-        `ts=${message.received_at}`,
-        `from=${String(message.from ?? "<unknown>")}`,
-        `to=${message.to}`,
-        `type=${message.type}`,
-        `summary=${String(message.summary ?? "").replaceAll(/\s+/g, "_")}`,
-        ToolsResponse.compactPreview(message.body)
-            ? `body=${ToolsResponse.compactPreview(message.body)}`
-            : "",
-    ]
-        .filter(Boolean)
-        .join(" "))
-        .join("\n")}`;
-}
-function compactRoomContacts(contacts) {
-    if (contacts.length === 0)
-        return "\n(no room contacts)";
-    return `\n${contacts
-        .map((contact) => [
-        `address=${contact.address}`,
-        contact.role !== undefined ? `role=${String(contact.role)}` : "",
-        contact.parent !== undefined ? `parent=${String(contact.parent)}` : "",
-        contact.caps !== undefined
-            ? `caps=${Array.isArray(contact.caps) ? contact.caps.join(",") : String(contact.caps)}`
-            : "",
-        contact.claim !== undefined
-            ? `claim=${String(contact.claim).replaceAll(/\s+/g, "_")}`
-            : "",
-        contact.status !== undefined ? `status=${String(contact.status)}` : "",
-    ]
-        .filter(Boolean)
-        .join(" "))
-        .join("\n")}`;
-}
-function compactRoomRoster(roster) {
-    const members = Object.values(roster);
-    if (members.length === 0)
-        return "\n(no room members)";
-    return `\n${members
-        .map((member) => [
-        `address=${member.address}`,
-        `role=${String(member.role ?? "")}`,
-        member.parent !== undefined ? `parent=${String(member.parent)}` : "",
-        member.caps !== undefined
-            ? `caps=${Array.isArray(member.caps) ? member.caps.join(",") : String(member.caps)}`
-            : "",
-        member.claim !== undefined
-            ? `claim=${String(member.claim).replaceAll(/\s+/g, "_")}`
-            : "",
-        `status=${String(member.status ?? "")}`,
-        `last_seen=${member.last_seen}`,
-    ].join(" "))
-        .join("\n")}`;
-}
-function compactRoomStatus(status) {
-    return `\nroom=${status.room} messages=${status.message_count} roster=${status.roster_count}${status.diagnostics_count ? ` diagnostics=${status.diagnostics_count}` : ""}${status.last_message_at ? ` last_message_at=${status.last_message_at}` : ""}${status.last_message_from ? ` last_from=${status.last_message_from}` : ""}${status.last_message_type ? ` last_type=${status.last_message_type}` : ""}${status.last_message_summary ? ` last_summary=${ToolsResponse.compactPreview(status.last_message_summary)}` : ""}`;
-}
-function compactCommunicationSnapshot(snapshot) {
-    if (!snapshot)
-        return "\n(no communication snapshot)";
-    return `\nself=${snapshot.self} root=${snapshot.root} rooms=${snapshot.rooms.length} updated_at=${snapshot.updated_at}`;
-}
-function compactArtifactPath(value) {
-    if (typeof value === "string")
-        return value;
-    const record = asRecord(value);
-    return String(record.path ?? "<missing>");
-}
-function readBoundedReviewEvidence(status, limit) {
-    const evidenceFile = status.evidenceFile;
-    if (typeof evidenceFile !== "string" || !existsSync(evidenceFile))
-        return undefined;
-    try {
-        const manifest = asRecord(JSON.parse(readFileSync(evidenceFile, "utf8")));
-        const commands = Array.isArray(manifest.commands) ? manifest.commands : [];
-        const bounded = commands.slice(-Math.max(1, limit));
-        return {
-            ...manifest,
-            commands: bounded,
-            commands_total: commands.length,
-            ...(bounded.length < commands.length ? { commands_truncated: true } : {}),
-        };
-    }
-    catch {
-        return {
-            status: "invalid",
-            error: "review evidence manifest is unreadable",
-        };
-    }
-}
-function compactActorFiles(status) {
-    const run = String(status.run ?? "<unknown>");
-    const artifacts = asRecord(status.artifacts);
-    const files = [
-        status.stdoutLog,
-        status.stderrLog,
-        status.eventsFile,
-        status.outboxFile,
-        status.evidenceFile,
-        status.state_dir
-            ? `${String(status.state_dir)}/communication.json`
-            : undefined,
-        status.state_dir ? `${String(status.state_dir)}/result.json` : undefined,
-    ].filter((file) => typeof file === "string");
-    const artifactText = Object.keys(artifacts).length
-        ? ` artifacts=${Object.entries(artifacts)
-            .map(([key, value]) => `${key}:${compactArtifactPath(value)}`)
-            .join(",")}`
-        : "";
-    const nextActions = ToolsResponse.artifactNextActions(run, artifacts);
-    const nextText = nextActions.length
-        ? ` next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`
-        : "";
-    return `\nrun=${run}${artifactText}${files.length ? ` files=${files.join(",")}` : ""}${nextText}`;
-}
-function summarizeOtherSessions(currentSession, allRuns) {
-    const otherRuns = allRuns.filter((run) => run.ownerId && run.ownerId !== currentSession);
+function runtimeStatus() {
     return {
-        other_runs: otherRuns.length,
-        other_sessions: new Set(otherRuns.map((run) => run.ownerId)).size,
+        automatic_review: process.env.PI_ACTORS_AUTOMATIC_REVIEW !== "off",
+        run_root: Paths.getRunStateRoot(),
+        version: process.env.npm_package_version ?? "unknown",
     };
 }
-function compactSessionRuns(session, runs, summary = {}) {
-    const suffix = [
-        summary.other_sessions !== undefined
-            ? `other_sessions=${String(summary.other_sessions)}`
-            : "",
-        summary.other_runs !== undefined
-            ? `other_runs=${String(summary.other_runs)}`
-            : "",
-    ]
-        .filter(Boolean)
-        .join(" ");
-    if (runs.length === 0)
-        return `\nsession=${session} runs=0${suffix ? ` ${suffix}` : ""}`;
-    return `\nsession=${session} runs=${runs.length}${suffix ? ` ${suffix}` : ""}\n${runs
+function runtimeRuns(ctx, deps, status) {
+    const session = ToolsAccess.getContextSessionId(ctx);
+    const listed = deps.listRuns
+        ? deps.listRuns()
+        : AsyncRuns.listRuns(undefined, status);
+    const runs = listed
         .map((run) => {
-        const tokens = [
-            `run=${String(run.run ?? "")}`,
-            `status=${String(run.status ?? "")}`,
-        ];
-        if (run.recipe)
-            tokens.push(`recipe=${String(run.recipe)}`);
-        if (run.retire_when)
-            tokens.push(`retire_when=${String(run.retire_when)}`);
-        return tokens.join(" ");
+        try {
+            return deps.getRunStatus
+                ? deps.getRunStatus(String(run.state_dir ?? run.run))
+                : AsyncRuns.getRunStatus(String(run.state_dir ?? run.run));
+        }
+        catch {
+            return run;
+        }
     })
-        .join("\n")}`;
+        .filter((run) => !session || !run.ownerId || run.ownerId === session);
+    return { ...(session ? { owner_session: session } : {}), runs };
 }
-function getPiActorsRuntimeStatus() {
-    const packagedRecipeRoot = Paths.getPackagedRecipeRoot();
-    const packageRoot = dirname(packagedRecipeRoot);
-    const packageJsonPath = join(packageRoot, "package.json");
-    const packageJson = existsSync(packageJsonPath)
-        ? JSON.parse(readFileSync(packageJsonPath, "utf8"))
-        : {};
-    let git_commit;
-    try {
-        git_commit = execFileSync("git", ["-C", packageRoot, "rev-parse", "--short", "HEAD"], {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-        }).trim();
-    }
-    catch {
-        git_commit = undefined;
-    }
-    const entrypoint = fileURLToPath(import.meta.url);
+function runtimeTriage(ctx, deps) {
+    const inventory = runtimeRuns(ctx, deps, undefined);
+    const runs = inventory.runs;
+    const failed = runs.filter((run) => run.status === "failed");
+    const staleControls = runs.flatMap((run) => {
+        const stateDir = typeof run.state_dir === "string" ? run.state_dir : undefined;
+        if (!stateDir)
+            return [];
+        return RunsControls.readRunControlsFromStateDir(stateDir)
+            .filter((control) => control.status === "queued" || control.status === "claimed")
+            .map((control) => ({ run: run.run, control }));
+    });
+    const attentionEvents = runs.flatMap((run) => {
+        const stateDir = typeof run.state_dir === "string" ? run.state_dir : undefined;
+        if (!stateDir)
+            return [];
+        return RunsTrace.readRunTraceEvents(stateDir)
+            .filter((event) => event.attention === "notify" || event.attention === "followup")
+            .map((event) => ({
+            run: run.run,
+            id: event.id,
+            kind: event.kind,
+            attention: event.attention,
+            summary: event.summary,
+            ts: event.ts,
+        }));
+    });
     return {
-        automatic_recipe_review: Paths.isAutomaticRecipeReviewEnabled(),
-        entrypoint,
-        git_commit,
-        mode: entrypoint.includes("/dist/") ? "dist" : "source",
-        package_name: packageJson.name ?? "@llblab/pi-actors",
-        package_root: packageRoot,
-        recipe_root: Paths.getRecipeRoot(),
-        packaged_recipe_root: packagedRecipeRoot,
-        version: packageJson.version ?? "unknown",
+        ...inventory,
+        failed_runs: failed,
+        stale_controls: staleControls.slice(0, 40),
+        attention_events: attentionEvents.slice(-40).reverse(),
+        next_actions: [
+            ...(failed.length ? ["inspect target=runtime view=runs status=failed"] : []),
+            ...(staleControls.length
+                ? staleControls.slice(0, 3).map((entry) => `inspect target=run:${String(entry.run)} view=control`)
+                : []),
+            ...(attentionEvents.length
+                ? attentionEvents.slice(-3).map((entry) => `inspect target=run:${String(entry.run)} view=trace source=runtime`)
+                : []),
+        ],
     };
 }
-function compactPiActorsRuntimeStatus(status) {
-    return `\npi-actors version=${String(status.version)} mode=${String(status.mode)} automatic_review=${String(status.automatic_recipe_review)} path=${String(status.package_root)} entrypoint=${String(status.entrypoint)}${status.git_commit ? ` git=${String(status.git_commit)}` : ""}`;
-}
-function isStaleClaim(message, now) {
-    if (message.status !== "claimed")
-        return false;
-    const claimedAt = Date.parse(String(message.claimed_at ?? ""));
-    return Number.isFinite(claimedAt) && now - claimedAt > 5 * 60 * 1000;
-}
-function getRunTriageSignals(runs) {
-    const now = Date.now();
-    const staleClaims = [];
-    const attentionMessages = [];
-    for (const run of runs) {
-        const stateDir = String(run.state_dir ?? "");
-        const runId = String(run.run ?? "");
-        if (!stateDir)
-            continue;
-        try {
-            for (const message of AsyncRuns.readRunInboxMessages(stateDir, 200)) {
-                if (!isStaleClaim(message, now))
-                    continue;
-                staleClaims.push({
-                    run: runId,
-                    id: message.id,
-                    claimed_at: message.claimed_at,
-                    claimed_by: message.claimed_by,
-                    type: message.type,
-                });
-            }
-        }
-        catch { }
-        try {
-            for (const event of AsyncRuns.readRunEvents(stateDir, 80)) {
-                if (event.metadata?.requires_response !== true)
-                    continue;
-                attentionMessages.push({
-                    run: runId,
-                    id: event.id,
-                    summary: event.summary,
-                    type: event.type ?? event.event,
-                });
-            }
-        }
-        catch { }
+function compactRuntime(view, details) {
+    if (view === "runs") {
+        return `\nruntime runs=${details.runs?.length ?? 0}`;
+    }
+    if (view === "triage") {
+        return `\nruntime failed=${details.failed_runs?.length ?? 0} stale_controls=${details.stale_controls?.length ?? 0} attention=${details.attention_events?.length ?? 0}`;
     }
-    return { attention_messages: attentionMessages, stale_claims: staleClaims };
+    return `\nruntime version=${String(details.version ?? "unknown")} automatic_review=${String(details.automatic_review)}`;
 }
-function isTriageHighRiskRecipe(recipe) {
-    if (recipe.tool !== true)
-        return false;
-    const labels = Array.isArray(recipe.risk_labels)
-        ? recipe.risk_labels.map((label) => String(label))
-        : [];
-    return labels.some((label) => label !== "risk.long_running");
+function inspectRuntime(view, input, ctx, deps) {
+    if (view === "status")
+        return runtimeStatus();
+    if (view === "runs") {
+        return runtimeRuns(ctx, deps, typeof input.status === "string" ? input.status : undefined);
+    }
+    if (view === "triage")
+        return runtimeTriage(ctx, deps);
+    throw new Error("inspect runtime supports view=status, view=runs, or view=triage.");
 }
-function getPiActorsTriage(ctx, deps) {
-    const runtime = getPiActorsRuntimeStatus();
-    const currentSession = ToolsAccess.getContextSessionId(ctx);
-    const listRuns = deps.listRuns ?? AsyncRuns.listRuns;
-    const getRunStatus = deps.getRunStatus ?? AsyncRuns.getRunStatus;
-    const allRuns = listRuns().flatMap((run) => {
-        try {
-            return [getRunStatus(String(run.state_dir))];
-        }
-        catch {
-            return [];
-        }
-    });
-    const visibleRuns = currentSession
-        ? allRuns.filter((run) => !run.ownerId || run.ownerId === currentSession)
-        : allRuns;
-    const activeRuns = visibleRuns.filter((run) => run.status === "running");
-    const failedRuns = visibleRuns.filter((run) => run.status === "failed");
-    const otherRuns = currentSession
-        ? allRuns.filter((run) => run.ownerId && run.ownerId !== currentSession)
-        : [];
+function inspectRecipes(view, deps) {
+    if (view !== "status" &&
+        view !== "summary" &&
+        view !== "doctor" &&
+        view !== "imports" &&
+        view !== "reviews") {
+        throw new Error("inspect recipes supports view=status, view=summary, view=doctor, view=imports, or view=reviews.");
+    }
     const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
+    if (view === "reviews") {
+        return ReviewDiagnostics.readAutomaticReviewDiagnostics({ recipeRoot });
+    }
     const discovered = RecipesDiscovery.discoverRecipeSources([
         { root: recipeRoot, defaultTool: true, mutableUsage: true },
         { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
     ]);
-    const recipeSummary = {
+    const summary = {
         ...RecipesDiscovery.summarizeDiscovery(discovered),
         drafts: RecipesDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
     };
-    const activeRecipes = Array.isArray(recipeSummary.active)
-        ? recipeSummary.active
-        : [];
-    const highRiskRecipes = activeRecipes.filter(isTriageHighRiskRecipe);
-    const signals = getRunTriageSignals(visibleRuns);
-    const attentionMessages = signals.attention_messages;
-    const staleClaims = signals.stale_claims;
-    const invalidRecipes = Array.isArray(recipeSummary.invalid)
-        ? recipeSummary.invalid
-        : [];
-    const remediations = Array.isArray(recipeSummary.remediations)
-        ? recipeSummary.remediations
-        : [];
-    const drafts = Array.isArray(recipeSummary.drafts)
-        ? recipeSummary.drafts
-        : [];
-    const nextActions = [
-        invalidRecipes.length || remediations.length
-            ? "inspect target=recipes view=doctor"
-            : "",
-        drafts.length ? "inspect target=recipes view=summary verbose=true" : "",
-        failedRuns[0]?.run
-            ? `inspect target=run:${String(failedRuns[0].run)} view=tail lines=80`
-            : "",
-        attentionMessages[0]?.run
-            ? `inspect target=run:${String(attentionMessages[0].run)} view=messages`
-            : "",
-        activeRuns.length
-            ? "inspect target=session:all view=runs status=active"
-            : "",
-    ].filter(Boolean);
     return {
-        runtime,
-        current_session: currentSession ?? null,
-        active_runs: activeRuns.map((run) => ({
-            run: run.run,
-            ownerId: run.ownerId,
-            recipe: run.recipe,
-            status: run.status,
-        })),
-        other_session_runs: otherRuns.length,
-        invalid_recipes: invalidRecipes,
-        blocking_recipes: remediations.filter((item) => String(item.kind ?? "").startsWith("blocking_")),
-        high_risk_recipes: highRiskRecipes.map((recipe) => ({
-            id: recipe.id,
-            path: recipe.path,
-            risk_labels: recipe.risk_labels,
-        })),
-        draft_recipes: drafts,
-        stale_claims: staleClaims,
-        recent_failed_runs: failedRuns.slice(0, 5).map((run) => ({
-            run: run.run,
-            recipe: run.recipe,
-            status: run.status,
-        })),
-        attention_messages: attentionMessages.slice(-10),
-        next_actions: [...new Set(nextActions)].slice(0, 5),
+        ...summary,
+        next_actions: ToolsResponse.recipeRegistryNextActions(summary, view),
+    };
+}
+function parseRunTarget(target) {
+    if (!target.startsWith("run:"))
+        return undefined;
+    const run = target.slice(4);
+    return run && /^[A-Za-z0-9_.-]+$/.test(run) ? run : undefined;
+}
+function inspectRun(run, view, input, ctx, deps) {
+    if (view !== "recipe" && view !== "trace" && view !== "control") {
+        throw new Error("inspect run:<id> supports view=recipe, view=trace, or view=control.");
+    }
+    const status = deps.getRunStatus
+        ? deps.getRunStatus(run)
+        : ToolsAccess.assertRunAccessibleToContext(run, ctx);
+    const stateDir = String(status.state_dir);
+    if (view === "recipe") {
+        return Inspector.readActorInspectorRecipe(stateDir);
+    }
+    if (view === "trace") {
+        const source = typeof input.source === "string" ? input.source : "all";
+        if (source !== "all" &&
+            source !== "lifecycle" &&
+            source !== "control" &&
+            source !== "process" &&
+            source !== "agent" &&
+            source !== "artifact" &&
+            source !== "runtime") {
+            throw new Error(`unsupported Trace source: ${source}`);
+        }
+        return {
+            run,
+            source,
+            items: TraceProjection.projectRunTrace(stateDir, {
+                artifacts: status.artifacts,
+                limit: Number(input.lines || Limits.DEFAULT_INSPECT_LINES),
+                source,
+            }),
+        };
+    }
+    const runInstanceId = String(status.run_instance_id ?? "");
+    return {
+        run,
+        run_instance_id: runInstanceId,
+        status: status.status,
+        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(),
     };
 }
-function compactPiActorsTriage(summary) {
-    const runtime = asRecord(summary.runtime);
-    const activeRuns = Array.isArray(summary.active_runs)
-        ? summary.active_runs.length
-        : 0;
-    const invalidRecipes = Array.isArray(summary.invalid_recipes)
-        ? summary.invalid_recipes.length
-        : 0;
-    const blockingRecipes = Array.isArray(summary.blocking_recipes)
-        ? summary.blocking_recipes.length
-        : 0;
-    const highRiskRecipes = Array.isArray(summary.high_risk_recipes)
-        ? summary.high_risk_recipes.length
-        : 0;
-    const drafts = Array.isArray(summary.draft_recipes)
-        ? summary.draft_recipes.length
-        : 0;
-    const staleClaims = Array.isArray(summary.stale_claims)
-        ? summary.stale_claims.length
-        : 0;
-    const failedRuns = Array.isArray(summary.recent_failed_runs)
-        ? summary.recent_failed_runs.length
-        : 0;
-    const attention = Array.isArray(summary.attention_messages)
-        ? summary.attention_messages.length
-        : 0;
-    const nextActions = Array.isArray(summary.next_actions)
-        ? summary.next_actions
-        : [];
-    return `\ntriage version=${String(runtime.version ?? "unknown")} mode=${String(runtime.mode ?? "unknown")} active_runs=${activeRuns} other_runs=${String(summary.other_session_runs ?? 0)} invalid_recipes=${invalidRecipes} blocking_recipes=${blockingRecipes} high_risk_recipes=${highRiskRecipes} drafts=${drafts} stale_claims=${staleClaims} failed_runs=${failedRuns} attention=${attention}${ToolsResponse.compactNextActions(nextActions)}`;
+function inspectTool(name, view, deps) {
+    if (!name || !/^[A-Za-z0-9_.-]+$/.test(name)) {
+        throw new Error(`invalid tool target: tool:${name}`);
+    }
+    if (view !== "status" && view !== "schema") {
+        throw new Error("inspect tool:<name> supports view=status or view=schema.");
+    }
+    const tool = deps.getTool?.(name);
+    if (!tool)
+        throw new Error(`registered tool not found: ${name}`);
+    return {
+        name,
+        description: tool.description,
+        parameters: tool.parameters,
+        promptSnippet: tool.promptSnippet,
+    };
 }
-function compactToolActor(name, tool) {
-    const parameters = asRecord(tool.parameters);
-    const required = Array.isArray(parameters.required)
-        ? parameters.required.join(",")
-        : "";
-    const properties = asRecord(parameters.properties);
-    return `\ntool=${name} description=${String(tool.description ?? "").replaceAll(/\s+/g, "_")} args=${Object.keys(properties).join(",")} required=${required}`;
+function compactResult(target, view, details) {
+    if (target === "runtime")
+        return compactRuntime(view, details);
+    if (target === "recipes")
+        return ToolsResponse.compactRecipeRegistry(details);
+    if (target.startsWith("tool:"))
+        return `\ntool=${target.slice(5)} view=${view}`;
+    return `\nrun=${target.slice(4)} view=${view}`;
 }
 export function createInspectToolDefinition(deps = {}) {
     return {
         name: "inspect",
         label: "Inspect",
-        description: "Intentionally inspect actors at decision points, after follow-ups, or during diagnosis instead of polling. Core targets are run:<id> and tool:<name>; advanced targets include branch:<run>/<branch>, room:<run>, coordinator, session:<id>, and session:all.",
+        description: "Inspect a Run's Recipe, Trace, or Control evidence, or runtime/recipe/tool diagnostics.",
         parameters: Schema.objectSchema({
-            lines: Schema.stringSchema("Line count for tail/messages views. Default 40."),
-            status: Schema.stringSchema("Optional session run filter: all, running, active, terminal, done, failed, cancelled, killed, or exited."),
-            target: Schema.stringSchema("Actor address to inspect, e.g. run:<id> or tool:<name>; advanced: branch:<run>/<branch>, room:<run>, coordinator, session:<id>, session:all."),
-            verbose: Schema.booleanSchema("Return full JSON instead of compact text where available."),
-            view: Schema.stringSchema("Inspection view. Core run views: status, tail, messages, artifacts, files, mailbox. Advanced views include communication, roster, and contacts."),
+            lines: Schema.stringSchema("Bounded item count for Trace or recent Controls."),
+            source: Schema.stringSchema("Optional Trace source: all, lifecycle, control, process, agent, artifact, or runtime."),
+            status: Schema.stringSchema("Optional runtime Run status filter."),
+            target: Schema.stringSchema("Target: run:<id>, runtime, recipes, or tool:<name>."),
+            verbose: Schema.booleanSchema("Return full JSON instead of compact text."),
+            view: Schema.stringSchema("Run view recipe|trace|control, or target-specific management view."),
         }, ["target", "view"]),
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const input = asRecord(params);
             const target = String(input.target ?? "");
             const view = String(input.view ?? "");
-            if (target === "recipes" || target === "recipe-registry") {
-                if (view !== "status" &&
-                    view !== "summary" &&
-                    view !== "doctor" &&
-                    view !== "imports" &&
-                    view !== "reviews") {
-                    throw new Error("inspect recipes supports view=status, view=summary, view=doctor, view=imports, or view=reviews.");
-                }
-                if (view === "reviews") {
-                    const diagnostics = ReviewDiagnostics.readAutomaticReviewDiagnostics({
-                        recipeRoot: deps.recipeRoot ?? Paths.getRecipeRoot(),
-                    });
-                    return {
-                        content: [{
-                                type: "text",
-                                text: maybeJsonText(diagnostics, input.verbose === true, compactAutomaticReviewDiagnostics(diagnostics)),
-                            }],
-                        details: diagnostics,
-                    };
-                }
-                const discovered = RecipesDiscovery.discoverRecipeSources([
-                    {
-                        root: deps.recipeRoot ?? Paths.getRecipeRoot(),
-                        defaultTool: true,
-                        mutableUsage: true,
-                    },
-                    { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
-                ]);
-                const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
-                const summaryBase = {
-                    ...RecipesDiscovery.summarizeDiscovery(discovered),
-                    drafts: RecipesDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
-                };
-                const summary = {
-                    ...summaryBase,
-                    next_actions: ToolsResponse.recipeRegistryNextActions(summaryBase, view),
-                };
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: maybeJsonText(summary, input.verbose === true, view === "doctor"
-                                ? ToolsResponse.compactRecipeDoctor(summary)
-                                : view === "imports"
-                                    ? ToolsResponse.compactRecipeImports(summary)
-                                    : ToolsResponse.compactRecipeRegistry(summary)),
-                        },
-                    ],
-                    details: summary,
-                };
-            }
-            const address = Messages.parseActorAddress(target);
-            if (address.kind === "coordinator") {
-                if (view !== "status" && view !== "runs") {
-                    throw new Error("inspect coordinator supports view=status or view=runs.");
-                }
-                const session = ToolsAccess.requireContextSessionId(ctx, "inspect coordinator");
-                const allRuns = AsyncRuns.listRuns(undefined, typeof input.status === "string" ? input.status : undefined).map((run) => AsyncRuns.getRunStatus(String(run.state_dir)));
-                const runs = allRuns.filter((run) => run.ownerId === session);
-                const sessionSummary = summarizeOtherSessions(session, allRuns);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: maybeJsonText({ session, runs, ...sessionSummary }, input.verbose === true, compactSessionRuns(session, runs, sessionSummary)),
-                        },
-                    ],
-                    details: { session, runs, ...sessionSummary },
-                };
-            }
-            if (address.kind === "session") {
-                if (view !== "status" && view !== "runs") {
-                    throw new Error("inspect session:<id> supports view=status or view=runs.");
-                }
-                const allRuns = AsyncRuns.listRuns(undefined, typeof input.status === "string" ? input.status : undefined).map((run) => AsyncRuns.getRunStatus(String(run.state_dir)));
-                const runs = allRuns.filter((run) => address.value === "all" || run.ownerId === address.value);
-                const sessionSummary = address.value === "all"
-                    ? {}
-                    : summarizeOtherSessions(address.value || "", allRuns);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: maybeJsonText({ session: address.value, runs, ...sessionSummary }, input.verbose === true, compactSessionRuns(address.value || "", runs, sessionSummary)),
-                        },
-                    ],
-                    details: { session: address.value, runs, ...sessionSummary },
-                };
-            }
-            if (address.kind === "tool" && address.value) {
-                if (address.value === "pi-actors") {
-                    if (view !== "status" && view !== "triage") {
-                        throw new Error("inspect tool:pi-actors supports view=status or view=triage.");
-                    }
-                    const details = view === "triage"
-                        ? getPiActorsTriage(ctx, deps)
-                        : getPiActorsRuntimeStatus();
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: maybeJsonText(details, input.verbose === true, view === "triage"
-                                    ? compactPiActorsTriage(details)
-                                    : compactPiActorsRuntimeStatus(details)),
-                            },
-                        ],
-                        details,
-                    };
-                }
-                if (view !== "status" && view !== "schema") {
-                    throw new Error("inspect tool:<name> supports view=status or view=schema.");
-                }
-                const tool = deps.getTool?.(address.value);
-                if (!tool)
-                    throw new Error(`tool actor not found: ${address.value}`);
-                const details = {
-                    name: address.value,
-                    description: tool.description,
-                    parameters: tool.parameters,
-                    promptSnippet: tool.promptSnippet,
-                };
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: maybeJsonText(details, input.verbose === true || view === "schema", compactToolActor(address.value, details)),
-                        },
-                    ],
-                    details,
-                };
+            let details;
+            if (target === "runtime") {
+                details = inspectRuntime(view, input, ctx, deps);
             }
-            if (address.kind === "room" && address.value && address.room) {
-                const status = ToolsAccess.assertRunAccessibleToContext(address.value, ctx);
-                const stateDir = String(status.state_dir ?? "");
-                if (!stateDir)
-                    throw new Error(`room:${address.value} has no run state directory.`);
-                if (view === "status") {
-                    const status = Rooms.getRoomStatus(stateDir, address.room);
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: maybeJsonText(status, input.verbose === true, compactRoomStatus(status)),
-                            },
-                        ],
-                        details: status,
-                    };
-                }
-                if (view === "previews") {
-                    const previews = Rooms.readRoomMessagePreviews(stateDir, address.room, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: maybeJsonText(previews, input.verbose === true, compactRoomPreviews(previews)),
-                            },
-                        ],
-                        details: { previews },
-                    };
-                }
-                if (view === "messages") {
-                    const messages = Rooms.readRoomMessages(stateDir, address.room, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: maybeJsonText(messages, input.verbose === true, compactRoomMessages(messages)),
-                            },
-                        ],
-                        details: { messages },
-                    };
-                }
-                if (view === "contacts") {
-                    const contacts = Rooms.readRoomContacts(stateDir, address.room);
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: maybeJsonText(contacts, input.verbose === true, compactRoomContacts(contacts)),
-                            },
-                        ],
-                        details: { contacts },
-                    };
-                }
-                if (view === "roster") {
-                    const roster = Rooms.readRoomRoster(stateDir, address.room);
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: maybeJsonText(roster, input.verbose === true, compactRoomRoster(roster)),
-                            },
-                        ],
-                        details: { roster },
-                    };
-                }
-                throw new Error("inspect room:<run> supports view=status, view=messages, view=previews, view=roster, or view=contacts.");
+            else if (target === "recipes") {
+                details = inspectRecipes(view, deps);
             }
-            const runId = address.kind === "run" || address.kind === "branch"
-                ? address.value
-                : undefined;
-            if (!runId)
-                throw new Error("inspect target must be run:<id>, branch:<run>/<branch>, coordinator, session:<id>, or tool:<name>.");
-            if (address.kind === "branch") {
-                if (view !== "mailbox")
-                    throw new Error("inspect branch:<run>/<branch> supports view=mailbox.");
-                const status = ToolsAccess.assertRunAccessibleToContext(runId, ctx);
-                const branchInbox = Rooms.readBranchInboxDiagnostics(String(status.state_dir ?? ""), runId, target, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
-                const messages = branchInbox.messages;
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: maybeJsonText(input.verbose === true ? branchInbox : messages, input.verbose === true, `${ToolsResponse.compactBranchInbox(messages.map((message) => ({ ...message })))}${branchInbox.corrupted > 0 ? `\ncorrupted=${branchInbox.corrupted}` : ""}`),
-                        },
-                    ],
-                    details: { corrupted: branchInbox.corrupted, messages },
-                };
-            }
-            switch (view) {
-                case "status": {
-                    const status = ToolsAccess.assertRunAccessibleToContext(runId, ctx);
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: maybeJsonText(status, input.verbose === true, ToolsResponse.compactAsyncRunStatus(status)),
-                            },
-                        ],
-                        details: status,
-                    };
-                }
-                case "tail": {
-                    ToolsAccess.assertRunAccessibleToContext(runId, ctx);
-                    const text = AsyncRuns.tailRun(runId, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
-                    return {
-                        content: [{ type: "text", text: `\n${text}` }],
-                        details: {},
-                    };
-                }
-                case "messages": {
-                    ToolsAccess.assertRunAccessibleToContext(runId, ctx);
-                    const messages = AsyncRuns.readRunEvents(runId, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: maybeJsonText(messages, input.verbose === true, compactRunMessages(messages)),
-                            },
-                        ],
-                        details: { messages },
-                    };
-                }
-                case "artifacts":
-                case "files": {
-                    const status = ToolsAccess.assertRunAccessibleToContext(runId, ctx);
-                    const artifactManifest = AsyncRuns.resolveArtifactManifest(status.artifacts);
-                    const reviewEvidence = readBoundedReviewEvidence(status, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
-                    const details = artifactManifest
-                        ? {
-                            ...status,
-                            ...(reviewEvidence ? { review_evidence: reviewEvidence } : {}),
-                            artifact_manifest: artifactManifest,
-                            next_actions: ToolsResponse.artifactNextActions(status.run ?? runId, asRecord(status.artifacts)),
-                        }
-                        : {
-                            ...status,
-                            ...(reviewEvidence ? { review_evidence: reviewEvidence } : {}),
-                        };
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: maybeJsonText(details, input.verbose === true, compactActorFiles(status)),
-                            },
-                        ],
-                        details,
-                    };
-                }
-                case "mailbox": {
-                    const status = ToolsAccess.assertRunAccessibleToContext(runId, ctx);
-                    const mailbox = asRecord(status.mailbox);
-                    const normalizedMailbox = ToolsMailbox.normalizeMailboxContracts(mailbox);
-                    const messages = AsyncRuns.readRunInboxMessages(runId, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
-                    const details = {
-                        mailbox,
-                        normalized_mailbox: normalizedMailbox,
-                        messages,
-                    };
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: maybeJsonText(details, input.verbose === true, ToolsResponse.compactRunMailbox(String(status.run ?? runId), mailbox, messages)),
-                            },
-                        ],
-                        details,
-                    };
+            else {
+                const run = parseRunTarget(target);
+                if (run)
+                    details = inspectRun(run, view, input, ctx, deps);
+                else if (target.startsWith("tool:")) {
+                    details = inspectTool(target.slice(5), view, deps);
                 }
-                case "communication": {
-                    const status = ToolsAccess.assertRunAccessibleToContext(runId, ctx);
-                    const snapshot = Rooms.readCommunicationSnapshot(String(status.state_dir ?? ""));
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: maybeJsonText(snapshot ?? {}, input.verbose === true, compactCommunicationSnapshot(snapshot)),
-                            },
-                        ],
-                        details: { communication: snapshot },
-                    };
+                else {
+                    throw new Error(`unsupported inspect target: ${target}; use run:<id>, runtime, recipes, or tool:<name>`);
                 }
-                default:
-                    throw new Error("inspect view must be one of: status, tail, messages, artifacts, files, mailbox, communication; branch targets support mailbox.");
             }
+            return {
+                content: [{
+                        type: "text",
+                        text: maybeJsonText(details, input.verbose === true || (target.startsWith("tool:") && view === "schema"), compactResult(target, view, details)),
+                    }],
+                details,
+            };
         },
     };
 }