@llblab/pi-actors 0.33.0 → 0.34.0

package/dist/lib/tools.js

@@ -1,23 +1,12 @@
 /**
- * Pi-facing tool definition helpers
- * Zones: pi tools, registry tools, async run launchers
- * Owns generated runtime tool schemas and the register_tool management tool schema
+ * Public tool family composition
+ * Zones: tool set, reserved tool names, pi-facing tool wiring
+ * Owns public tool-family composition without owning individual tool behavior
  */
-import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import * as ActorMessages from "./actor-messages.js";
-import * as ActorRooms from "./actor-rooms.js";
-import * as AsyncRuns from "./async-runs.js";
-import * as Execution from "./execution.js";
-import * as Limits from "./limits.js";
-import * as Paths from "./paths.js";
-import * as Prompts from "./prompts.js";
-import * as RecipeDiscovery from "./recipe-discovery.js";
-import * as RecipeReferences from "./recipe-references.js";
-import * as RecipeUsage from "./recipe-usage.js";
-import * as Registry from "./registry.js";
-import * as Schema from "./schema.js";
+import * as ToolsInspect from "./tools-inspect.js";
+import * as ToolsMessage from "./tools-message.js";
+import * as ToolsRegister from "./tools-register.js";
+import * as ToolsSpawn from "./tools-spawn.js";
 export const RESERVED_TOOL_NAMES = new Set([
     "read",
     "write",
@@ -31,1394 +20,9 @@ export const RESERVED_TOOL_NAMES = new Set([
     "spawn",
     "inspect",
 ]);
-function stringSchema(description) {
-    return { description, type: "string" };
-}
-function typedArgSchema(arg, type) {
-    if (!type || type.kind === "string")
-        return stringSchema(`Argument: ${arg}`);
-    if (type.kind === "path")
-        return stringSchema(`Path argument: ${arg}`);
-    if (type.kind === "int")
-        return { description: `Integer argument: ${arg}`, type: "integer" };
-    if (type.kind === "number")
-        return { description: `Number argument: ${arg}`, type: "number" };
-    if (type.kind === "bool")
-        return { description: `Boolean argument: ${arg}`, type: "boolean" };
-    if (type.kind === "array")
-        return { description: `Array argument: ${arg}`, items: {}, type: "array" };
-    return {
-        description: `Enum argument: ${arg}`,
-        enum: type.values,
-        type: "string",
-    };
-}
-function booleanSchema(description) {
-    return { description, type: "boolean" };
-}
-function nullSchema(description) {
-    return { description, type: "null" };
-}
-function arraySchema(description) {
-    return { description, items: {}, type: "array" };
-}
-function unionSchema(anyOf) {
-    return { anyOf };
-}
-function objectSchema(properties, required) {
-    return { additionalProperties: false, properties, required, type: "object" };
-}
-function sampleValueForArg(arg, type, defaults) {
-    if (Object.hasOwn(defaults, arg))
-        return defaults[arg];
-    if (!type || type.kind === "string")
-        return `<${arg}>`;
-    if (type.kind === "path")
-        return `./${arg}`;
-    if (type.kind === "int")
-        return 1;
-    if (type.kind === "number")
-        return 1.5;
-    if (type.kind === "bool")
-        return true;
-    if (type.kind === "array")
-        return [`<${arg}>`];
-    return type.values[0] ?? `<${arg}>`;
-}
-function shouldAddRuntimeToolUsageHint(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return (/^Argument \S+ must /.test(message) || /^Missing .* value: /.test(message));
-}
-function formatRuntimeToolUsageHint(cfg, required, includeRunId) {
-    const optional = cfg.args.filter((arg) => !required.includes(arg));
-    const example = {};
-    for (const arg of required)
-        example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], cfg.defaults);
-    for (const arg of optional)
-        example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], cfg.defaults);
-    if (includeRunId)
-        example.run_id = `${cfg.name}-1`;
-    const lines = [
-        `Expected call shape for ${cfg.name}:`,
-        `${cfg.name}(${JSON.stringify(example, null, 2)})`,
-    ];
-    if (required.length)
-        lines.push(`Required: ${required.join(", ")}`);
-    if (optional.length || includeRunId)
-        lines.push(`Optional: ${[...optional, ...(includeRunId ? ["run_id"] : [])].join(", ")}`);
-    return lines.join("\n");
-}
-function formatRuntimeToolArgumentError(cfg, error, required, includeRunId) {
-    const message = error instanceof Error ? error.message : String(error);
-    if (!shouldAddRuntimeToolUsageHint(error))
-        return error instanceof Error ? error : new Error(message);
-    return new Error(`Invalid arguments for tool "${cfg.name}": ${message}\n\n${formatRuntimeToolUsageHint(cfg, required, includeRunId)}`);
-}
-function looseObjectSchema(description) {
-    return { additionalProperties: true, description, type: "object" };
-}
-function jsonText(value) {
-    return `\n${JSON.stringify(value, null, 2)}`;
-}
-function asRecord(value) {
-    return value && typeof value === "object" && !Array.isArray(value)
-        ? value
-        : {};
-}
-function formatFailureCount(value) {
-    return Array.isArray(value) ? value.length : undefined;
-}
-function actorRunNextActions(run) {
-    const id = String(run ?? "").trim();
-    if (!id)
-        return [];
-    return [
-        `inspect target=run:${id} view=status`,
-        `inspect target=run:${id} view=messages`,
-        `message to=run:${id} type=<actor.action>`,
-    ];
-}
-function compactAsyncRunStatus(value) {
-    const status = asRecord(value);
-    const progress = asRecord(status.progress);
-    const result = asRecord(status.result);
-    const run = String(status.run ?? "<unknown>");
-    const tokens = [
-        `run=${run}`,
-        `status=${String(status.status ?? "unknown")}`,
-    ];
-    if (status.tool)
-        tokens.push(`tool=${String(status.tool)}`);
-    if (status.recipe)
-        tokens.push(`recipe=${String(status.recipe)}`);
-    if (status.retire_when)
-        tokens.push(`retire_when=${String(status.retire_when)}`);
-    if (Number(status.pid) > 0)
-        tokens.push(`pid=${Number(status.pid)}`);
-    if (progress.phase && progress.phase !== status.status)
-        tokens.push(`phase=${String(progress.phase)}`);
-    if (Number(progress.activeSubagents) > 0)
-        tokens.push(`active=${Number(progress.activeSubagents)}`);
-    if (Number(progress.completed) > 0)
-        tokens.push(`completed=${Number(progress.completed)}`);
-    const failures = formatFailureCount(progress.failures);
-    if (failures !== undefined && failures > 0)
-        tokens.push(`failures=${failures}`);
-    if (result.code !== undefined)
-        tokens.push(`code=${String(result.code)}`);
-    if (result.killed === true)
-        tokens.push("killed=true");
-    const draftRecipe = status.draft_recipe;
-    if (draftRecipe)
-        tokens.push(`draft_recipe=${String(draftRecipe)}`);
-    const nextActions = actorRunNextActions(run);
-    if (nextActions.length > 0)
-        tokens.push(`next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`);
-    return `\n${tokens.join(" ")}`;
-}
-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 compactPreview(value, maxLength = Limits.COMPACT_PREVIEW_CHARS) {
-    if (value === undefined)
-        return undefined;
-    const text = typeof value === "string" ? value : JSON.stringify(value, undefined, 0);
-    const compact = text.replaceAll(/\s+/g, "_");
-    return compact.length > maxLength
-        ? `${compact.slice(0, Math.max(0, maxLength - 1))}…`
-        : compact;
-}
-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=${compactPreview(preview.summary)}` : "",
-        preview.body_preview
-            ? `body=${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, "_")}`,
-        compactPreview(message.body)
-            ? `body=${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=${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 compactInboxMessages(messages, emptyLabel) {
-    if (messages.length === 0)
-        return `\n(no ${emptyLabel} messages)`;
-    return `\n${messages
-        .map((message) => [
-        ...(message.id ? [`id=${String(message.id)}`] : []),
-        `status=${String(message.status ?? "")}`,
-        `type=${String(message.type ?? "")}`,
-        `from=${String(message.from ?? "")}`,
-        `to=${String(message.to ?? "")}`,
-        ...(message.queued_at
-            ? [`queued_at=${String(message.queued_at)}`]
-            : []),
-        ...(message.sent_at ? [`sent_at=${String(message.sent_at)}`] : []),
-        ...(message.claimed_at
-            ? [`claimed_at=${String(message.claimed_at)}`]
-            : []),
-        ...(message.handled_at
-            ? [`handled_at=${String(message.handled_at)}`]
-            : []),
-        ...(message.failed_at
-            ? [`failed_at=${String(message.failed_at)}`]
-            : []),
-    ].join(" "))
-        .join("\n")}`;
-}
-function compactBranchInbox(messages) {
-    return compactInboxMessages(messages, "branch inbox");
-}
-function normalizeMailboxEntry(value) {
-    if (typeof value === "string")
-        return { type: value };
-    const record = asRecord(value);
-    if (typeof record.type !== "string" || !record.type.trim())
-        return undefined;
-    return {
-        type: record.type.trim(),
-        ...(record.body_schema !== undefined
-            ? { body_schema: record.body_schema }
-            : {}),
-        ...(record.ack !== undefined ? { ack: record.ack } : {}),
-        ...(typeof record.idempotency === "string"
-            ? { idempotency: record.idempotency }
-            : {}),
-        ...(typeof record.level === "string" ? { level: record.level } : {}),
-        ...(record.requires_response === true ? { requires_response: true } : {}),
-        ...(typeof record.summary === "string" ? { summary: record.summary } : {}),
-    };
-}
-function normalizeMailboxContracts(mailbox) {
-    const accepts = Array.isArray(mailbox.accepts)
-        ? mailbox.accepts
-            .map(normalizeMailboxEntry)
-            .filter((entry) => Boolean(entry))
-        : [];
-    const emits = Array.isArray(mailbox.emits)
-        ? mailbox.emits
-            .map(normalizeMailboxEntry)
-            .filter((entry) => Boolean(entry))
-        : [];
-    return { accepts, emits };
-}
-function mailboxTypes(entries) {
-    return entries.flatMap((entry) => typeof asRecord(entry).type === "string"
-        ? [String(asRecord(entry).type)]
-        : []);
-}
-function compactRunMailbox(run, mailbox, messages) {
-    const normalized = normalizeMailboxContracts(mailbox);
-    return `\nrun=${run} accepts=${mailboxTypes(normalized.accepts).join(",")} emits=${mailboxTypes(normalized.emits).join(",")}${compactInboxMessages(messages, "run inbox")}`;
-}
-function compactArtifactPath(value) {
-    if (typeof value === "string")
-        return value;
-    const record = asRecord(value);
-    return String(record.path ?? "<missing>");
-}
-function artifactNextActions(run, artifacts) {
-    const id = String(run ?? "").trim();
-    if (!id || Object.keys(artifacts).length === 0)
-        return [];
-    return [
-        `inspect target=run:${id} view=artifacts verbose=true`,
-        `inspect target=run:${id} view=messages`,
-    ];
-}
-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.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 = 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);
-    return {
-        other_runs: otherRuns.length,
-        other_sessions: new Set(otherRuns.map((run) => run.ownerId)).size,
-    };
-}
-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
-        .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(" ");
-    })
-        .join("\n")}`;
-}
-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 = new URL(import.meta.url).pathname;
-    return {
-        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",
-    };
-}
-function compactPiActorsRuntimeStatus(status) {
-    return `\npi-actors version=${String(status.version)} mode=${String(status.mode)} path=${String(status.package_root)} entrypoint=${String(status.entrypoint)}${status.git_commit ? ` git=${String(status.git_commit)}` : ""}`;
-}
-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 compactRecipeImports(summary) {
-    const active = Array.isArray(summary.active)
-        ? summary.active
-        : [];
-    const lines = active.flatMap((entry) => {
-        const imports = asRecord(entry.imports);
-        return Object.entries(imports).map(([alias, value]) => {
-            const binding = typeof value === "string" ? { from: value } : asRecord(value);
-            return `recipe=${String(entry.id ?? "<unknown>")} alias=${alias} from=${String(binding.from ?? value)}`;
-        });
-    });
-    return lines.length ? `\n${lines.join("\n")}` : "\n(no recipe imports)";
-}
-function compactRecipeDoctor(summary) {
-    const details = Array.isArray(summary.diagnostic_details)
-        ? summary.diagnostic_details
-        : [];
-    const remediations = Array.isArray(summary.remediations)
-        ? summary.remediations
-        : [];
-    const recommendations = Array.isArray(summary.recommendations)
-        ? summary.recommendations
-        : [];
-    const counts = { error: 0, info: 0, warning: 0 };
-    for (const detail of details) {
-        const severity = String(detail.severity ?? "info");
-        if (severity === "error" || severity === "warning" || severity === "info")
-            counts[severity] += 1;
-    }
-    const topAction = asRecord(summary.top_action);
-    const lines = [
-        `recipes doctor errors=${counts.error} warnings=${counts.warning} info=${counts.info} actions=${remediations.length} recommendations=${recommendations.length}`,
-    ];
-    if (Object.keys(topAction).length > 0) {
-        const action = compactPreview(topAction.action, Limits.DOCTOR_ACTION_PREVIEW_CHARS);
-        lines.push(`top severity=${String(topAction.severity ?? "info")} kind=${String(topAction.kind ?? "inspect")} id=${String(topAction.id ?? "root")} action=${action ?? "inspect"}`);
-    }
-    for (const item of remediations.slice(0, 8)) {
-        const action = compactPreview(item.action, Limits.DOCTOR_ACTION_PREVIEW_CHARS);
-        const blocked = item.blocked_fallback
-            ? ` blocked=${compactPreview(item.blocked_fallback, Limits.DOCTOR_ACTION_PREVIEW_CHARS)}`
-            : "";
-        lines.push(`${String(item.severity ?? "info")} kind=${String(item.kind ?? "inspect")} id=${String(item.id ?? "root")}${blocked} action=${action ?? "inspect"}`);
-    }
-    const nextActions = Array.isArray(summary.next_actions)
-        ? summary.next_actions
-        : [];
-    if (nextActions.length > 0)
-        lines[0] = `${lines[0]}${compactNextActions(nextActions)}`;
-    return `\n${lines.join("\n")}`;
-}
-function recipeRegistryNextActions(summary, view) {
-    const actions = [];
-    const drafts = Array.isArray(summary.drafts)
-        ? summary.drafts
-        : [];
-    const invalid = Array.isArray(summary.invalid) ? summary.invalid.length : 0;
-    const diagnostics = Array.isArray(summary.diagnostics)
-        ? summary.diagnostics.length
-        : 0;
-    const topAction = asRecord(summary.top_action);
-    if (view !== "doctor" && (invalid > 0 || diagnostics > 0)) {
-        actions.push("inspect target=recipes view=doctor");
-    }
-    if (view === "doctor" && typeof topAction.action === "string") {
-        actions.push(String(topAction.action));
-    }
-    if (drafts.length > 0) {
-        actions.push("inspect target=recipes view=summary verbose=true");
-        const firstPath = typeof drafts[0]?.path === "string" ? drafts[0].path : undefined;
-        if (firstPath)
-            actions.push(`spawn file=${firstPath}`);
-    }
-    return [...new Set(actions)].slice(0, 4);
-}
-function compactNextActions(actions) {
-    return actions.length
-        ? ` next=${actions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`
-        : "";
-}
-function compactRecipeRegistry(summary) {
-    const active = Array.isArray(summary.active) ? summary.active.length : 0;
-    const shadowed = Array.isArray(summary.shadowed)
-        ? summary.shadowed.length
-        : 0;
-    const invalid = Array.isArray(summary.invalid) ? summary.invalid.length : 0;
-    const disabled = Array.isArray(summary.disabled)
-        ? summary.disabled.length
-        : 0;
-    const diagnostics = Array.isArray(summary.diagnostics)
-        ? summary.diagnostics.length
-        : 0;
-    const drafts = Array.isArray(summary.drafts) ? summary.drafts.length : 0;
-    const recommendations = Array.isArray(summary.recommendations)
-        ? summary.recommendations.length
-        : 0;
-    const nextActions = Array.isArray(summary.next_actions)
-        ? summary.next_actions
-        : [];
-    return `\nrecipes active=${active} drafts=${drafts} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} recommendations=${recommendations} diagnostics=${diagnostics}${compactNextActions(nextActions)}`;
-}
-function actorMessageNextActions(message, result) {
-    const actions = [];
-    const address = ActorMessages.parseActorAddress(message.to);
-    if (result.delivery_error || result.sent === false) {
-        if (address.kind === "run" && address.value) {
-            actions.push(`inspect target=run:${address.value} view=status`);
-            actions.push(`inspect target=run:${address.value} view=mailbox`);
-        }
-        else if (address.kind === "branch" && address.value) {
-            actions.push(`inspect target=branch:${address.value}/${address.branch ?? "main"} view=mailbox`);
-            actions.push(`inspect target=run:${address.value} view=status`);
-        }
-    }
-    if (result.queued === true) {
-        if (address.kind === "branch" && address.value) {
-            actions.push(`inspect target=branch:${address.value}/${address.branch ?? "main"} view=mailbox`);
-        }
-        else if (address.kind === "run" && address.value) {
-            actions.push(`inspect target=run:${address.value} view=mailbox`);
-        }
-    }
-    return [...new Set(actions)].slice(0, 3);
-}
-function compactActorMessageResult(message, result) {
-    const tokens = [
-        `to=${message.to}`,
-        `type=${message.type}`,
-        `message=${result.sent === true || result.stopped === true ? "sent" : "not_sent"}`,
-    ];
-    if (result.bytes !== undefined)
-        tokens.push(`bytes=${String(result.bytes)}`);
-    if (result.queued === true)
-        tokens.push("queued=true");
-    if (result.control)
-        tokens.push(`control=${String(result.control)}`);
-    if (result.outbox)
-        tokens.push(`messages=${String(result.outbox)}`);
-    if (result.message_count !== undefined)
-        tokens.push(`messages=${String(result.message_count)}`);
-    if (result.roster_count !== undefined)
-        tokens.push(`roster=${String(result.roster_count)}`);
-    if (result.room)
-        tokens.push(`room=${String(result.room)}`);
-    if (result.tool)
-        tokens.push(`tool=${String(result.tool)}`);
-    if (result.stopped === true)
-        tokens.push("stopped=true");
-    if (result.signal)
-        tokens.push(`signal=${String(result.signal)}`);
-    if (result.invoked === true)
-        tokens.push("invoked=true");
-    if (result.delivery_error) {
-        tokens.push(`delivery_error=${compactPreview(result.delivery_error, 96)}`);
-    }
-    const nextActions = Array.isArray(result.next_actions)
-        ? result.next_actions
-        : actorMessageNextActions(message, result);
-    if (nextActions.length > 0)
-        tokens.push(`next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`);
-    return `\n${tokens.join(" ")}`;
-}
-function maybeJsonText(value, verbose, compact) {
-    return verbose ? jsonText(value) : compact;
-}
-export function createRegisterToolDefinition(deps) {
-    return {
-        name: "register_tool",
-        label: "Register Tool",
-        description: Prompts.REGISTER_TOOL_DESCRIPTION,
-        promptSnippet: Prompts.REGISTER_TOOL_PROMPT_SNIPPET,
-        promptGuidelines: Prompts.REGISTER_TOOL_GUIDELINES,
-        parameters: objectSchema({
-            args: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.args),
-            async: booleanSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.async),
-            description: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.description),
-            name: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.name),
-            state_dir: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.state_dir),
-            template: unionSchema([
-                stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.template),
-                looseObjectSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.template),
-                arraySchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.templateArray),
-                nullSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.templateNull),
-            ]),
-            update: booleanSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.update),
-            values: looseObjectSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.values),
-        }, []),
-        execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => Registry.executeRegisterTool(params, ctx, deps),
-    };
-}
-function getRunOwnerId(ctx) {
-    return ctx.sessionManager?.getSessionId?.();
-}
-function messageBodyToRunLine(message) {
-    if (message.type !== "run.message")
-        return JSON.stringify(message);
-    if (typeof message.body === "string")
-        return message.body;
-    if (message.body === undefined)
-        return message.type;
-    return JSON.stringify(message.body);
-}
-function messageBodyToToolParams(message) {
-    if (message.body &&
-        typeof message.body === "object" &&
-        !Array.isArray(message.body)) {
-        return message.body;
-    }
-    if (message.body === undefined)
-        return {};
-    return { input: message.body };
-}
-function formatToolActorFailure(tool, message, params, error) {
-    const original = error instanceof Error ? error.message : String(error);
-    const paramsPreview = compactPreview(params, 240) ?? "{}";
-    return Object.assign(new Error(`tool actor ${tool} failed for message type ${message.type}: ${original}; params=${paramsPreview}`), {
-        message_type: message.type,
-        original_error: original,
-        params_preview: paramsPreview,
-        tool,
-    });
-}
-function shadowedRecipeLaunchDiagnostic(recipe) {
-    if (typeof recipe !== "string" ||
-        recipe.includes("/") ||
-        recipe.includes("~"))
-        return undefined;
-    const discovery = RecipeDiscovery.discoverRecipeSources([
-        { root: Paths.getRecipeRoot(), defaultTool: true, mutableUsage: true },
-        { root: Paths.getPackagedRecipeRoot(), defaultTool: false },
-    ]);
-    return RecipeDiscovery.getShadowedLaunchDiagnostic(discovery, recipe);
-}
-function draftRecipeName(run) {
-    return `${run.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "spawn"}.json`;
-}
-function draftRecipeDefaults(values) {
-    const ignored = new Set([
-        "actor_address",
-        "communication_file",
-        "default_room",
-        "run_id",
-        "state_dir",
-    ]);
-    const defaults = Object.fromEntries(Object.entries(values).filter(([key]) => !ignored.has(key)));
-    return Object.keys(defaults).length > 0 ? defaults : undefined;
-}
-function writeSpawnDraftRecipe(input, meta) {
-    if (process.env.NODE_TEST_CONTEXT &&
-        process.env.PI_ACTORS_ENABLE_SPAWN_DRAFTS_IN_TEST !== "1")
-        return undefined;
-    if (input.template === undefined ||
-        input.file !== undefined ||
-        input.recipe !== undefined)
-        return undefined;
-    const root = Paths.getRecipeDraftRoot();
-    mkdirSync(root, { recursive: true });
-    const path = join(root, draftRecipeName(String(meta.run)));
-    const defaults = draftRecipeDefaults(meta.values);
-    const recipe = {
-        async: true,
-        description: `Draft recipe captured from spawn run ${String(meta.run)}`,
-        ...(meta.artifacts ? { artifacts: meta.artifacts } : {}),
-        ...(defaults ? { defaults } : {}),
-        template: input.template,
-    };
-    writeFileSync(path, `${JSON.stringify(recipe, null, 2)}\n`, { flag: "wx" });
-    return path;
-}
-function enhanceSpawnRecipeError(error, recipe) {
-    const diagnostic = shadowedRecipeLaunchDiagnostic(recipe);
-    if (!diagnostic)
-        return error instanceof Error ? error : new Error(String(error));
-    const original = error instanceof Error ? error.message : String(error);
-    return Object.assign(new Error(`${original} reason=${diagnostic.reason} active_path=${diagnostic.active_path} blocked_fallback=${diagnostic.blocked_fallback} hint=${diagnostic.hint}`), {
-        ...diagnostic,
-        original_error: original,
-    });
-}
-function runIdFromActorAddress(address) {
-    if (!address)
-        return undefined;
-    const parsed = ActorMessages.parseActorAddress(address);
-    if (parsed.kind !== "run" || !parsed.value) {
-        throw new Error(`Expected run:<id> actor address, received: ${address}`);
-    }
-    return parsed.value;
-}
-function assertMessageSenderBelongsToRun(message, run, routeLabel) {
-    if (!message.from) {
-        throw new Error(`message to ${message.to} requires from=<actor address>.`);
-    }
-    const sender = ActorMessages.parseActorAddress(message.from);
-    if ((sender.kind !== "run" && sender.kind !== "branch") ||
-        sender.value !== run) {
-        throw new Error(`message to ${routeLabel} requires from=run:${run} or branch:${run}/<branch>; got ${message.from}.`);
-    }
-}
-async function routeBranchEnvelope(stateDir, runId, recipient, message, _options) {
-    const branchMessage = { ...message, to: recipient };
-    ActorRooms.appendBranchInboxMessage(stateDir, runId, recipient, branchMessage);
-    try {
-        return await AsyncRuns.sendRunMessage(runId, JSON.stringify(branchMessage));
-    }
-    catch (error) {
-        const record = error && typeof error === "object"
-            ? error
-            : {};
-        if (record.queued === true) {
-            return {
-                control_path: record.control_path,
-                control_type: record.control_type,
-                delivery_error: record.delivery_error ??
-                    (error instanceof Error ? error.message : String(error)),
-                inbox_id: record.inbox_id,
-                queued: true,
-                run: runId,
-                sent: false,
-                state_dir: stateDir,
-            };
-        }
-        throw error;
-    }
-}
-function getRoomMulticastRecipients(message, run) {
-    const raw = message.metadata?.recipients;
-    if (raw === undefined)
-        return [];
-    if (!Array.isArray(raw)) {
-        throw new Error("room multicast metadata.recipients must be an array.");
-    }
-    return raw.map((recipient) => {
-        if (typeof recipient !== "string") {
-            throw new Error("room multicast recipients must be actor addresses.");
-        }
-        const parsed = ActorMessages.parseActorAddress(recipient);
-        if (parsed.kind !== "branch" || parsed.value !== run) {
-            throw new Error(`room multicast recipient must be branch:${run}/<branch>; got ${recipient}.`);
-        }
-        return ActorMessages.formatActorAddress(parsed);
-    });
-}
-export function createSpawnToolDefinition() {
-    return {
-        name: "spawn",
-        label: "Spawn",
-        description: "Create an addressable actor from a recipe file or inline command template. Use instead of ad hoc shell backgrounding for work that may outlive this turn, needs steering/follow-up/artifacts, runs as a service, fans out, or should be inspected later. Currently spawns run:<id> actors backed by async runs.",
-        parameters: objectSchema({
-            artifacts: looseObjectSchema("Optional named artifact paths for the spawned actor."),
-            as: stringSchema("Optional actor address for the spawned run, e.g. run:<id>."),
-            file: stringSchema("Optional template recipe JSON file. Bare names resolve under ~/.pi/agent/recipes."),
-            recipe: stringSchema("Alias for file; template recipe JSON file/name to spawn."),
-            state_dir: stringSchema("Optional explicit run state directory."),
-            template: unionSchema([
-                stringSchema("Inline command template string"),
-                arraySchema("Inline command-template sequence or parallel tree"),
-                looseObjectSchema("Inline command-template object with flags such as parallel, repeat, retry, failure, and nested template."),
-            ]),
-            values: looseObjectSchema("Runtime placeholder values passed to the actor."),
-            verbose: booleanSchema("Return full JSON instead of compact text."),
-        }, []),
-        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-            const input = asRecord(params);
-            const runId = runIdFromActorAddress(typeof input.as === "string" ? input.as : undefined);
-            const recipe = typeof input.file === "string"
-                ? input.file
-                : typeof input.recipe === "string"
-                    ? input.recipe
-                    : undefined;
-            let meta;
-            try {
-                meta = AsyncRuns.startRun({
-                    file: recipe,
-                    launch_source: "spawn",
-                    ownerId: getRunOwnerId(ctx),
-                    run_id: runId,
-                    state_dir: typeof input.state_dir === "string" ? input.state_dir : undefined,
-                    ...(input.template !== undefined
-                        ? {
-                            template: input.template,
-                        }
-                        : {}),
-                    values: asRecord(input.values),
-                    ...(input.artifacts &&
-                        typeof input.artifacts === "object" &&
-                        !Array.isArray(input.artifacts)
-                        ? {
-                            artifacts: input.artifacts,
-                        }
-                        : {}),
-                }, ctx.cwd);
-            }
-            catch (error) {
-                throw enhanceSpawnRecipeError(error, recipe);
-            }
-            const draftRecipe = writeSpawnDraftRecipe(input, meta);
-            const nextActions = actorRunNextActions(meta.run);
-            const details = {
-                ...meta,
-                ...(draftRecipe ? { draft_recipe: draftRecipe } : {}),
-                next_actions: nextActions,
-            };
-            ActorRooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
-            ActorRooms.writeCommunicationSnapshot(meta.state_dir, String(meta.run));
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: maybeJsonText(details, input.verbose === true, compactAsyncRunStatus(details)),
-                    },
-                ],
-                details,
-            };
-        },
-    };
-}
-function getContextSessionId(ctx) {
-    return ctx?.sessionManager?.getSessionId?.();
-}
-function requireContextSessionId(ctx, actor) {
-    const sessionId = getContextSessionId(ctx);
-    if (!sessionId) {
-        throw new Error(`${actor} requires a current coordinator session; use session:<id> or session:all for explicit session inventory.`);
-    }
-    return sessionId;
-}
-function sessionMismatchError(input) {
-    const ownerSession = input.expectedSession ?? "none";
-    const currentSession = input.currentSession ?? "none";
-    const actor = input.run ? `run:${input.run}` : (input.target ?? "session");
-    const hintTarget = input.expectedSession
-        ? `session:${input.expectedSession}`
-        : "session:all";
-    return Object.assign(new Error(`${actor} reason=session_mismatch owner_session=${ownerSession} current_session=${currentSession} hint=inspect_session:${input.expectedSession ?? "all"}`), {
-        current_session: input.currentSession,
-        hint: `inspect target=${hintTarget} view=status`,
-        owner_session: input.expectedSession,
-        reason: "session_mismatch",
-        run: input.run,
-        target: input.target,
-    });
-}
-function assertRunAccessibleToContext(runId, ctx) {
-    const status = AsyncRuns.getRunStatus(runId);
-    const sessionId = getContextSessionId(ctx);
-    if (sessionId && status.ownerId && status.ownerId !== sessionId) {
-        throw sessionMismatchError({
-            currentSession: sessionId,
-            expectedSession: String(status.ownerId),
-            run: runId,
-        });
-    }
-    return status;
-}
-function assertRunExistsForActorMessage(runId) {
-    return AsyncRuns.getRunStatus(runId);
-}
-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.",
-        parameters: objectSchema({
-            lines: stringSchema("Line count for tail/messages views. Default 40."),
-            status: stringSchema("Optional session run filter: all, running, active, terminal, done, failed, cancelled, killed, or exited."),
-            target: stringSchema("Actor address to inspect, e.g. run:<id> or tool:<name>; advanced: branch:<run>/<branch>, room:<run>, coordinator, session:<id>, session:all."),
-            verbose: booleanSchema("Return full JSON instead of compact text where available."),
-            view: stringSchema("Inspection view. Core run views: status, tail, messages, artifacts, files, mailbox. Advanced views include communication, roster, and contacts."),
-        }, ["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") {
-                    throw new Error("inspect recipes supports view=status, view=summary, view=doctor, or view=imports.");
-                }
-                const discovered = RecipeDiscovery.discoverRecipeSources([
-                    {
-                        root: deps.recipeRoot ?? Paths.getRecipeRoot(),
-                        defaultTool: true,
-                        mutableUsage: true,
-                    },
-                    { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
-                ]);
-                const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
-                const summaryBase = {
-                    ...RecipeDiscovery.summarizeDiscovery(discovered),
-                    drafts: RecipeDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
-                };
-                const summary = {
-                    ...summaryBase,
-                    next_actions: recipeRegistryNextActions(summaryBase, view),
-                };
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: maybeJsonText(summary, input.verbose === true, view === "doctor"
-                                ? compactRecipeDoctor(summary)
-                                : view === "imports"
-                                    ? compactRecipeImports(summary)
-                                    : compactRecipeRegistry(summary)),
-                        },
-                    ],
-                    details: summary,
-                };
-            }
-            const address = ActorMessages.parseActorAddress(target);
-            if (address.kind === "coordinator") {
-                if (view !== "status" && view !== "runs") {
-                    throw new Error("inspect coordinator supports view=status or view=runs.");
-                }
-                const session = 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") {
-                        throw new Error("inspect tool:pi-actors supports view=status.");
-                    }
-                    const details = getPiActorsRuntimeStatus();
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: maybeJsonText(details, input.verbose === true, 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,
-                };
-            }
-            if (address.kind === "room" && address.value && address.room) {
-                const status = 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 = ActorRooms.getRoomStatus(stateDir, address.room);
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: maybeJsonText(status, input.verbose === true, compactRoomStatus(status)),
-                            },
-                        ],
-                        details: status,
-                    };
-                }
-                if (view === "previews") {
-                    const previews = ActorRooms.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 = ActorRooms.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 = ActorRooms.readRoomContacts(stateDir, address.room);
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: maybeJsonText(contacts, input.verbose === true, compactRoomContacts(contacts)),
-                            },
-                        ],
-                        details: { contacts },
-                    };
-                }
-                if (view === "roster") {
-                    const roster = ActorRooms.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.");
-            }
-            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 = assertRunAccessibleToContext(runId, ctx);
-                const branchInbox = ActorRooms.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, `${compactBranchInbox(messages.map((message) => ({ ...message })))}${branchInbox.corrupted > 0 ? `\ncorrupted=${branchInbox.corrupted}` : ""}`),
-                        },
-                    ],
-                    details: { corrupted: branchInbox.corrupted, messages },
-                };
-            }
-            switch (view) {
-                case "status": {
-                    const status = assertRunAccessibleToContext(runId, ctx);
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: maybeJsonText(status, input.verbose === true, compactAsyncRunStatus(status)),
-                            },
-                        ],
-                        details: status,
-                    };
-                }
-                case "tail": {
-                    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": {
-                    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 = assertRunAccessibleToContext(runId, ctx);
-                    const artifactManifest = AsyncRuns.resolveArtifactManifest(status.artifacts);
-                    const details = artifactManifest
-                        ? {
-                            ...status,
-                            artifact_manifest: artifactManifest,
-                            next_actions: artifactNextActions(status.run ?? runId, asRecord(status.artifacts)),
-                        }
-                        : status;
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: maybeJsonText(details, input.verbose === true, compactActorFiles(status)),
-                            },
-                        ],
-                        details,
-                    };
-                }
-                case "mailbox": {
-                    const status = assertRunAccessibleToContext(runId, ctx);
-                    const mailbox = asRecord(status.mailbox);
-                    const normalizedMailbox = 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, compactRunMailbox(String(status.run ?? runId), mailbox, messages)),
-                            },
-                        ],
-                        details,
-                    };
-                }
-                case "communication": {
-                    const status = assertRunAccessibleToContext(runId, ctx);
-                    const snapshot = ActorRooms.readCommunicationSnapshot(String(status.state_dir ?? ""));
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: maybeJsonText(snapshot ?? {}, input.verbose === true, compactCommunicationSnapshot(snapshot)),
-                            },
-                        ],
-                        details: { communication: snapshot },
-                    };
-                }
-                default:
-                    throw new Error("inspect view must be one of: status, tail, messages, artifacts, files, mailbox, communication; branch targets support mailbox.");
-            }
-        },
-    };
-}
-export function createActorMessageToolDefinition(deps = {}) {
-    return {
-        name: "message",
-        label: "Message",
-        description: "Send one typed addressed message to steer an existing actor instead of restarting it. Core routes are run:<id> and tool:<name>; advanced routes include branch:<run>/<branch>, room:<run> group timelines, coordinator, and session:<id>.",
-        parameters: objectSchema({
-            body: unionSchema([
-                stringSchema("Message body. For run:<id>, this is the run-local command line."),
-                looseObjectSchema("Structured JSON message body."),
-                arraySchema("Structured JSON message body array."),
-            ]),
-            correlation_id: stringSchema("Optional correlation id for workflow/task linkage."),
-            from: stringSchema("Optional sender address, such as coordinator or run:<id>."),
-            metadata: looseObjectSchema("Optional structured metadata for routing or domain hints."),
-            reply_to: stringSchema("Optional message id this message replies to."),
-            summary: stringSchema("Optional short human-facing summary."),
-            to: stringSchema("Destination actor address, e.g. run:<id> or tool:<name>; advanced: branch:<run>/<branch>, room:<run>, coordinator, session:<id>."),
-            type: stringSchema("Semantic message type, e.g. control.approve or checkpoint.needs_scope."),
-            verbose: booleanSchema("Return full JSON instead of compact text."),
-        }, ["to", "type"]),
-        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-            const input = asRecord(params);
-            const message = ActorMessages.normalizeActorMessage(input);
-            const address = ActorMessages.parseActorAddress(message.to);
-            let result;
-            if (address.kind === "run" && address.value) {
-                const status = assertRunAccessibleToContext(address.value, ctx);
-                const normalizedMailbox = normalizeMailboxContracts(asRecord(status.mailbox));
-                const acceptedTypes = new Set(mailboxTypes(normalizedMailbox.accepts));
-                const advisoryWarnings = acceptedTypes.size > 0 && !acceptedTypes.has(message.type)
-                    ? [
-                        `Message type ${message.type} is not declared in mailbox.accepts for run:${address.value}.`,
-                    ]
-                    : [];
-                if (message.type === "control.kill") {
-                    result = AsyncRuns.killRun(address.value);
-                }
-                else if (message.type === "control.archive") {
-                    result = AsyncRuns.archiveRun(address.value);
-                }
-                else if (message.type === "control.prune") {
-                    const body = asRecord(message.body);
-                    result = AsyncRuns.pruneRun(address.value, {
-                        preserveArtifacts: body.preserve_artifacts === true ||
-                            body.preserveArtifacts === true,
-                    });
-                }
-                else {
-                    result = await AsyncRuns.sendRunMessage(address.value, messageBodyToRunLine(message));
-                }
-                if (advisoryWarnings.length > 0)
-                    result = { ...result, warnings: advisoryWarnings };
-            }
-            else if (address.kind === "branch" && address.value) {
-                const runId = address.value;
-                if (message.from)
-                    assertMessageSenderBelongsToRun(message, runId, `branch:${runId}/<branch>`);
-                const status = assertRunAccessibleToContext(runId, ctx);
-                const stateDir = String(status.state_dir ?? "");
-                if (stateDir && address.branch) {
-                    const ensureBranchMember = (actorAddress) => {
-                        ActorRooms.ensureRoomMember(stateDir, runId, "main", actorAddress, {
-                            parent: `run:${runId}`,
-                            role: "branch",
-                            status: "present",
-                        }, "Branch joined default room");
-                        ActorRooms.writeBranchCommunicationSnapshot(stateDir, runId, actorAddress);
-                    };
-                    ensureBranchMember(message.to);
-                    if (message.from) {
-                        const sender = ActorMessages.parseActorAddress(message.from);
-                        if (sender.kind === "branch" && sender.value === runId) {
-                            ensureBranchMember(message.from);
-                        }
-                    }
-                    ActorRooms.writeCommunicationSnapshot(stateDir, runId);
-                }
-                result = await routeBranchEnvelope(stateDir, runId, message.to, message, {
-                    source: "direct",
-                });
-            }
-            else if (address.kind === "room" && address.value && address.room) {
-                const runId = address.value;
-                assertMessageSenderBelongsToRun(message, runId, `room:${runId}`);
-                const status = assertRunAccessibleToContext(runId, ctx);
-                const stateDir = String(status.state_dir ?? "");
-                if (!stateDir)
-                    throw new Error(`${message.to} has no run state directory.`);
-                const recipients = getRoomMulticastRecipients(message, runId);
-                const roomResult = ActorRooms.appendRoomMessage(stateDir, address.room, message);
-                await Promise.all(recipients.map((recipient) => routeBranchEnvelope(stateDir, runId, recipient, message, {
-                    source: "room-multicast",
-                })));
-                result = {
-                    ...roomResult,
-                    ...(recipients.length > 0
-                        ? { multicast: recipients, multicast_count: recipients.length }
-                        : {}),
-                };
-            }
-            else if (address.kind === "tool" && address.value) {
-                const tool = deps.getTool?.(address.value);
-                if (!tool || typeof tool.execute !== "function") {
-                    throw new Error(`tool actor not found or not executable: ${address.value}`);
-                }
-                const toolParams = messageBodyToToolParams(message);
-                let toolResult;
-                try {
-                    toolResult = await tool.execute(`message:${message.type}`, toolParams, _signal, _onUpdate, ctx);
-                }
-                catch (error) {
-                    throw formatToolActorFailure(address.value, message, toolParams, error);
-                }
-                result = {
-                    invoked: true,
-                    sent: true,
-                    tool: address.value,
-                    tool_result: toolResult,
-                };
-            }
-            else if (address.kind === "coordinator" || address.kind === "session") {
-                if (!message.from) {
-                    throw new Error(`message to ${address.kind} requires from=run:<id>.`);
-                }
-                const sender = ActorMessages.parseActorAddress(message.from);
-                if (sender.kind !== "run" || !sender.value) {
-                    throw new Error(`message to ${address.kind} currently requires from=run:<id>.`);
-                }
-                const senderStatus = assertRunAccessibleToContext(sender.value, ctx);
-                if (address.kind === "session") {
-                    if (!senderStatus.ownerId) {
-                        throw sessionMismatchError({
-                            currentSession: undefined,
-                            expectedSession: address.value,
-                            run: sender.value,
-                            target: `session:${address.value}`,
-                        });
-                    }
-                    if (senderStatus.ownerId !== address.value) {
-                        throw sessionMismatchError({
-                            currentSession: String(senderStatus.ownerId),
-                            expectedSession: address.value,
-                            run: sender.value,
-                            target: `session:${address.value}`,
-                        });
-                    }
-                }
-                result = AsyncRuns.appendRunOutboxEvent(sender.value, {
-                    body: message.body,
-                    correlation_id: message.correlation_id,
-                    delivery: message.metadata?.requires_response === true ||
-                        address.kind === "session"
-                        ? "followup"
-                        : undefined,
-                    event: message.type,
-                    from: message.from,
-                    metadata: message.metadata,
-                    reply_to: message.reply_to,
-                    summary: message.summary,
-                    to: message.to,
-                    type: message.type,
-                });
-            }
-            else {
-                throw new Error(`message currently supports run:<id>, branch:<run>/<branch>, room:<run>, tool:<name>, coordinator, and session:<id> destinations; unsupported destination: ${message.to}`);
-            }
-            const nextActions = actorMessageNextActions(message, result);
-            const resultWithNext = nextActions.length
-                ? { ...result, next_actions: nextActions }
-                : result;
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: maybeJsonText({ message, result: resultWithNext }, input.verbose === true, compactActorMessageResult(message, resultWithNext)),
-                    },
-                ],
-                details: { message, result: resultWithNext },
-            };
-        },
-    };
-}
 export function createCoreActorToolDefinitions(deps) {
     return [
-        createRegisterToolDefinition({
+        ToolsRegister.createRegisterToolDefinition({
             configPath: deps.configPath,
             getActiveTools: deps.getActiveTools,
             getExternalToolConflict: deps.registryRuntime.getExternalToolConflict,
@@ -1428,95 +32,12 @@ export function createCoreActorToolDefinitions(deps) {
             reservedToolNames: RESERVED_TOOL_NAMES,
             setActiveTools: deps.setActiveTools,
         }),
-        createSpawnToolDefinition(),
-        createActorMessageToolDefinition({
+        ToolsSpawn.createSpawnToolDefinition(),
+        ToolsMessage.createActorMessageToolDefinition({
             getTool: (name) => deps.getRuntimeTool(name),
         }),
-        createInspectToolDefinition({
+        ToolsInspect.createInspectToolDefinition({
             getTool: (name) => deps.getRuntimeTool(name),
         }),
     ];
 }
-export function createRuntimeToolDefinition(cfg, exec) {
-    const paramSchema = {};
-    const required = [];
-    const isRecipe = RecipeReferences.isRecipeTool(cfg.template, cfg.recipe);
-    const isAsyncRecipe = cfg.recipe?.async === true ||
-        RecipeReferences.isAsyncRecipeReference(cfg.template);
-    const recipeTemplate = cfg.recipe?.template ?? RecipeReferences.getRecipeTemplate(cfg.template);
-    const requiredTemplate = recipeTemplate ?? cfg.template;
-    const requiredTemplateConfig = typeof requiredTemplate === "object" && !Array.isArray(requiredTemplate)
-        ? {
-            ...requiredTemplate,
-            args: cfg.args,
-            defaults: { ...(requiredTemplate.defaults ?? {}), ...cfg.defaults },
-        }
-        : {
-            args: cfg.args,
-            defaults: cfg.defaults,
-            template: requiredTemplate,
-        };
-    const requiredArgs = isRecipe && cfg.storedArgs !== undefined
-        ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
-        : RecipeReferences.isRecipeReference(cfg.template) && !recipeTemplate
-            ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
-            : Schema.getRequiredToolArgNames(requiredTemplateConfig);
-    for (const arg of cfg.args) {
-        paramSchema[arg] = typedArgSchema(arg, cfg.argTypes?.[arg]);
-        if (requiredArgs.has(arg))
-            required.push(arg);
-    }
-    if (isAsyncRecipe)
-        paramSchema.run_id = stringSchema("Optional run id override for this async template recipe invocation.");
-    return {
-        name: cfg.name,
-        label: cfg.name,
-        description: cfg.description,
-        parameters: objectSchema(paramSchema, required),
-        promptSnippet: isRecipe
-            ? Prompts.formatRecipeToolPromptSnippet(cfg.recipe?.name ?? String(cfg.template), isAsyncRecipe)
-            : Prompts.formatRegisteredToolPromptSnippet(cfg.template),
-        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-            try {
-                if (cfg.sourcePath)
-                    RecipeUsage.recordRecipeLaunch(cfg.sourcePath, new Date(), "tool");
-                if (isAsyncRecipe) {
-                    const input = params;
-                    const { run_id, ...values } = input;
-                    const base = cfg.recipe ? cfg.recipe : { file: String(cfg.template) };
-                    const runId = typeof run_id === "string" && run_id.trim()
-                        ? run_id.trim()
-                        : `${cfg.name}-${Date.now()}`;
-                    const meta = AsyncRuns.startRun({
-                        ...base,
-                        launch_source: "tool",
-                        ownerId: getRunOwnerId(ctx),
-                        run_id: runId,
-                        tool: cfg.name,
-                        values: Schema.normalizeRuntimeValues({ ...(cfg.recipe?.values ?? {}), ...cfg.defaults, ...values }, cfg.argTypes),
-                    }, ctx.cwd);
-                    ActorRooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
-                    ActorRooms.writeCommunicationSnapshot(meta.state_dir, String(meta.run));
-                    return {
-                        content: [
-                            { type: "text", text: compactAsyncRunStatus(meta) },
-                        ],
-                        details: meta,
-                    };
-                }
-                if (isRecipe && recipeTemplate) {
-                    const paramsWithDefaults = {
-                        ...(cfg.recipe?.values ?? {}),
-                        ...cfg.defaults,
-                        ...params,
-                    };
-                    return await Execution.executeRegisteredTool({ ...cfg, template: recipeTemplate }, Schema.normalizeRuntimeValues(paramsWithDefaults, cfg.argTypes), exec, ctx.cwd, signal);
-                }
-                return await Execution.executeRegisteredTool(cfg, Schema.normalizeRuntimeValues(params, cfg.argTypes), exec, ctx.cwd, signal);
-            }
-            catch (error) {
-                throw formatRuntimeToolArgumentError(cfg, error, required, isAsyncRecipe);
-            }
-        },
-    };
-}