@llblab/pi-actors 0.19.10 → 0.20.0

package/dist/lib/tools.js

@@ -0,0 +1,982 @@
+/**
+ * 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
+ */
+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 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";
+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 compactAsyncRunStatus(value) {
+    const status = asRecord(value);
+    const progress = asRecord(status.progress);
+    const result = asRecord(status.result);
+    const tokens = [
+        `run=${String(status.run ?? "<unknown>")}`,
+        `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");
+    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 = 80) {
+    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.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 compactBranchInbox(messages) {
+    if (messages.length === 0)
+        return "\n(no branch inbox 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.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 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}:${String(value)}`)
+            .join(",")}`
+        : "";
+    return `\nrun=${run}${artifactText}${files.length ? ` files=${files.join(",")}` : ""}`;
+}
+function compactSessionRuns(session, runs) {
+    if (runs.length === 0)
+        return `\nsession=${session} runs=0`;
+    return `\nsession=${session} runs=${runs.length}\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 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 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 recommendations = Array.isArray(summary.recommendations)
+        ? summary.recommendations.length
+        : 0;
+    return `\nrecipes active=${active} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} recommendations=${recommendations} diagnostics=${diagnostics}`;
+}
+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.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");
+    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),
+                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 (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 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}.`);
+    }
+}
+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. 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 meta = AsyncRuns.startRun({
+                file: typeof input.file === "string"
+                    ? input.file
+                    : typeof input.recipe === "string"
+                        ? input.recipe
+                        : undefined,
+                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);
+            ActorRooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
+            ActorRooms.writeCommunicationSnapshot(meta.state_dir, String(meta.run));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: maybeJsonText(meta, input.verbose === true, compactAsyncRunStatus(meta)),
+                    },
+                ],
+                details: meta,
+            };
+        },
+    };
+}
+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 assertRunAccessibleToContext(runId, ctx) {
+    const status = AsyncRuns.getRunStatus(runId);
+    const sessionId = getContextSessionId(ctx);
+    if (sessionId && status.ownerId && status.ownerId !== sessionId) {
+        throw new Error(`run:${runId} is owned by session:${status.ownerId}; current session is ${sessionId}.`);
+    }
+    return status;
+}
+function assertRunExistsForActorMessage(runId) {
+    return AsyncRuns.getRunStatus(runId);
+}
+export function createInspectToolDefinition(deps = {}) {
+    return {
+        name: "inspect",
+        label: "Inspect",
+        description: "Intentionally inspect an actor. Supports run:<id> views: status, tail, messages, artifacts, files, mailbox, communication; room:<run> status/messages/previews/roster/contacts; coordinator/session status; and tool:<name> status/schema.",
+        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>, room:<run>, coordinator, session:<id>, session:all, or tool:<name>."),
+            verbose: booleanSchema("Return full JSON instead of compact text where available."),
+            view: stringSchema("Inspection view: status, tail, messages, artifacts, files, mailbox, communication, roster, or 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") {
+                    throw new Error("inspect recipes supports view=status or view=summary.");
+                }
+                const discovered = RecipeDiscovery.discoverRecipeSources([
+                    { root: deps.recipeRoot ?? Paths.getRecipeRoot(), defaultTool: true, mutableUsage: true },
+                    { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
+                ]);
+                const summary = RecipeDiscovery.summarizeDiscovery(discovered);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: maybeJsonText(summary, input.verbose === true, 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 runs = AsyncRuns.listRuns(undefined, typeof input.status === "string" ? input.status : undefined)
+                    .map((run) => AsyncRuns.getRunStatus(String(run.state_dir)))
+                    .filter((run) => run.ownerId === session);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: maybeJsonText({ session, runs }, input.verbose === true, compactSessionRuns(session, runs)),
+                        },
+                    ],
+                    details: { session, runs },
+                };
+            }
+            if (address.kind === "session") {
+                if (view !== "status" && view !== "runs") {
+                    throw new Error("inspect session:<id> supports view=status or view=runs.");
+                }
+                const runs = AsyncRuns.listRuns(undefined, typeof input.status === "string" ? input.status : undefined)
+                    .map((run) => AsyncRuns.getRunStatus(String(run.state_dir)))
+                    .filter((run) => address.value === "all" || run.ownerId === address.value);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: maybeJsonText({ session: address.value, runs }, input.verbose === true, compactSessionRuns(address.value || "", runs)),
+                        },
+                    ],
+                    details: { session: address.value, runs },
+                };
+            }
+            if (address.kind === "tool" && address.value) {
+                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 || 40));
+                    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 || 40));
+                    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 messages = ActorRooms.readBranchInboxMessages(String(status.state_dir ?? ""), runId, target, Number(input.lines || 40));
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: maybeJsonText(messages, input.verbose === true, compactBranchInbox(messages.map((message) => ({ ...message })))),
+                        },
+                    ],
+                    details: { 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 || 40));
+                    return {
+                        content: [{ type: "text", text: `\n${text}` }],
+                        details: {},
+                    };
+                }
+                case "messages": {
+                    assertRunAccessibleToContext(runId, ctx);
+                    const messages = AsyncRuns.readRunEvents(runId, Number(input.lines || 40));
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: maybeJsonText(messages, input.verbose === true, compactRunMessages(messages)),
+                            },
+                        ],
+                        details: { messages },
+                    };
+                }
+                case "artifacts":
+                case "files": {
+                    const status = assertRunAccessibleToContext(runId, ctx);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: maybeJsonText(status, input.verbose === true, compactActorFiles(status)),
+                            },
+                        ],
+                        details: status,
+                    };
+                }
+                case "mailbox": {
+                    const status = assertRunAccessibleToContext(runId, ctx);
+                    const mailbox = asRecord(status.mailbox);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: maybeJsonText(mailbox, input.verbose === true, `\nrun=${String(status.run ?? runId)} accepts=${Array.isArray(mailbox.accepts) ? mailbox.accepts.join(",") : ""} emits=${Array.isArray(mailbox.emits) ? mailbox.emits.join(",") : ""}`),
+                            },
+                        ],
+                        details: { mailbox },
+                    };
+                }
+                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. Routes to run:<id> mailboxes, branch:<run>/<branch> mailboxes, room:<run> timelines/rosters, tool:<name> calls, and coordinator/session-bound run messages.",
+        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>, branch:<run>/<branch>, room:<run>, coordinator, session:<id>, or tool:<name>."),
+            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) {
+                assertRunAccessibleToContext(address.value, ctx);
+                if (message.type === "control.stop" ||
+                    message.type === "control.cancel") {
+                    result = AsyncRuns.cancelRun(address.value);
+                }
+                else if (message.type === "control.kill") {
+                    result = AsyncRuns.killRun(address.value);
+                }
+                else {
+                    result = AsyncRuns.sendRunMessage(address.value, messageBodyToRunLine(message));
+                }
+            }
+            else if (address.kind === "branch" && address.value) {
+                const runId = address.value;
+                if (message.from)
+                    assertMessageSenderBelongsToRun(message, runId, `branch:${runId}/<branch>`);
+                const status = message.from
+                    ? assertRunExistsForActorMessage(runId)
+                    : 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);
+                    ActorRooms.appendBranchInboxMessage(stateDir, runId, message.to, message);
+                }
+                result = AsyncRuns.sendRunMessage(address.value, JSON.stringify(message));
+            }
+            else if (address.kind === "room" && address.value && address.room) {
+                const runId = address.value;
+                assertMessageSenderBelongsToRun(message, runId, `room:${runId}`);
+                const status = assertRunExistsForActorMessage(runId);
+                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);
+                const multicast = recipients.map((recipient) => AsyncRuns.sendRunMessage(runId, JSON.stringify({ ...message, to: recipient })));
+                result = {
+                    ...roomResult,
+                    ...(multicast.length > 0
+                        ? { multicast: recipients, multicast_count: multicast.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 toolResult = await tool.execute(`message:${message.type}`, messageBodyToToolParams(message), _signal, _onUpdate, ctx);
+                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 new Error(`message to session:${address.value} requires sender run owner ${address.value}; got no owner.`);
+                    }
+                    if (senderStatus.ownerId !== address.value) {
+                        throw new Error(`message to session:${address.value} requires sender run owner ${address.value}; got ${senderStatus.ownerId}.`);
+                    }
+                }
+                result = AsyncRuns.appendRunOutboxEvent(sender.value, {
+                    body: message.body,
+                    correlation_id: message.correlation_id,
+                    delivery: 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}`);
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: maybeJsonText({ message, result }, input.verbose === true, compactActorMessageResult(message, result)),
+                    },
+                ],
+                details: { message, result },
+            };
+        },
+    };
+}
+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);
+                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);
+            }
+        },
+    };
+}