@llblab/pi-actors 0.33.0 → 0.34.0

package/dist/lib/tools-inspect.js

@@ -0,0 +1,534 @@
+/**
+ * Public inspect tool behavior
+ * Zones: actor observation, recipe registry inspection, room/session/tool/run views
+ * Owns the public inspect execution path and compact observation responses
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import * as AsyncRuns from "./async-runs.js";
+import * as Limits from "./limits.js";
+import * as Messages from "./messages.js";
+import * as Paths from "./paths.js";
+import * as RecipesDiscovery from "./recipes-discovery.js";
+import * as Rooms from "./rooms.js";
+import * as Schema from "./schema.js";
+import * as ToolsAccess from "./tools-access.js";
+import * as ToolsMailbox from "./tools-mailbox.js";
+import * as ToolsResponse from "./tools-response.js";
+const asRecord = ToolsResponse.asRecord;
+const maybeJsonText = ToolsResponse.maybeJsonText;
+function compactRunMessages(messages) {
+    if (messages.length === 0)
+        return "\n(no actor messages)";
+    return `\n${messages
+        .map((message) => [
+        `run=${message.run}`,
+        `type=${message.event}`,
+        `level=${message.level}`,
+        `summary=${message.summary.replaceAll(/\s+/g, "_")}`,
+    ].join(" "))
+        .join("\n")}`;
+}
+function compactRoomPreviews(previews) {
+    if (previews.length === 0)
+        return "\n(no room message previews)";
+    return `\n${previews
+        .map((preview) => [
+        `ts=${preview.timestamp}`,
+        preview.from ? `from=${preview.from}` : "",
+        `to=${preview.to}`,
+        `type=${preview.type}`,
+        preview.summary
+            ? `summary=${ToolsResponse.compactPreview(preview.summary)}`
+            : "",
+        preview.body_preview
+            ? `body=${ToolsResponse.compactPreview(preview.body_preview)}`
+            : "",
+    ]
+        .filter(Boolean)
+        .join(" "))
+        .join("\n")}`;
+}
+function compactRoomMessages(messages) {
+    if (messages.length === 0)
+        return "\n(no room messages)";
+    return `\n${messages
+        .map((message) => [
+        `ts=${message.received_at}`,
+        `from=${String(message.from ?? "<unknown>")}`,
+        `to=${message.to}`,
+        `type=${message.type}`,
+        `summary=${String(message.summary ?? "").replaceAll(/\s+/g, "_")}`,
+        ToolsResponse.compactPreview(message.body)
+            ? `body=${ToolsResponse.compactPreview(message.body)}`
+            : "",
+    ]
+        .filter(Boolean)
+        .join(" "))
+        .join("\n")}`;
+}
+function compactRoomContacts(contacts) {
+    if (contacts.length === 0)
+        return "\n(no room contacts)";
+    return `\n${contacts
+        .map((contact) => [
+        `address=${contact.address}`,
+        contact.role !== undefined ? `role=${String(contact.role)}` : "",
+        contact.parent !== undefined ? `parent=${String(contact.parent)}` : "",
+        contact.caps !== undefined
+            ? `caps=${Array.isArray(contact.caps) ? contact.caps.join(",") : String(contact.caps)}`
+            : "",
+        contact.claim !== undefined
+            ? `claim=${String(contact.claim).replaceAll(/\s+/g, "_")}`
+            : "",
+        contact.status !== undefined ? `status=${String(contact.status)}` : "",
+    ]
+        .filter(Boolean)
+        .join(" "))
+        .join("\n")}`;
+}
+function compactRoomRoster(roster) {
+    const members = Object.values(roster);
+    if (members.length === 0)
+        return "\n(no room members)";
+    return `\n${members
+        .map((member) => [
+        `address=${member.address}`,
+        `role=${String(member.role ?? "")}`,
+        member.parent !== undefined ? `parent=${String(member.parent)}` : "",
+        member.caps !== undefined
+            ? `caps=${Array.isArray(member.caps) ? member.caps.join(",") : String(member.caps)}`
+            : "",
+        member.claim !== undefined
+            ? `claim=${String(member.claim).replaceAll(/\s+/g, "_")}`
+            : "",
+        `status=${String(member.status ?? "")}`,
+        `last_seen=${member.last_seen}`,
+    ].join(" "))
+        .join("\n")}`;
+}
+function compactRoomStatus(status) {
+    return `\nroom=${status.room} messages=${status.message_count} roster=${status.roster_count}${status.diagnostics_count ? ` diagnostics=${status.diagnostics_count}` : ""}${status.last_message_at ? ` last_message_at=${status.last_message_at}` : ""}${status.last_message_from ? ` last_from=${status.last_message_from}` : ""}${status.last_message_type ? ` last_type=${status.last_message_type}` : ""}${status.last_message_summary ? ` last_summary=${ToolsResponse.compactPreview(status.last_message_summary)}` : ""}`;
+}
+function compactCommunicationSnapshot(snapshot) {
+    if (!snapshot)
+        return "\n(no communication snapshot)";
+    return `\nself=${snapshot.self} root=${snapshot.root} rooms=${snapshot.rooms.length} updated_at=${snapshot.updated_at}`;
+}
+function compactArtifactPath(value) {
+    if (typeof value === "string")
+        return value;
+    const record = asRecord(value);
+    return String(record.path ?? "<missing>");
+}
+function 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 = ToolsResponse.artifactNextActions(run, artifacts);
+    const nextText = nextActions.length
+        ? ` next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`
+        : "";
+    return `\nrun=${run}${artifactText}${files.length ? ` files=${files.join(",")}` : ""}${nextText}`;
+}
+function summarizeOtherSessions(currentSession, allRuns) {
+    const otherRuns = allRuns.filter((run) => run.ownerId && run.ownerId !== currentSession);
+    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}`;
+}
+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: Schema.objectSchema({
+            lines: Schema.stringSchema("Line count for tail/messages views. Default 40."),
+            status: Schema.stringSchema("Optional session run filter: all, running, active, terminal, done, failed, cancelled, killed, or exited."),
+            target: Schema.stringSchema("Actor address to inspect, e.g. run:<id> or tool:<name>; advanced: branch:<run>/<branch>, room:<run>, coordinator, session:<id>, session:all."),
+            verbose: Schema.booleanSchema("Return full JSON instead of compact text where available."),
+            view: Schema.stringSchema("Inspection view. Core run views: status, tail, messages, artifacts, files, mailbox. Advanced views include communication, roster, and contacts."),
+        }, ["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 = RecipesDiscovery.discoverRecipeSources([
+                    {
+                        root: deps.recipeRoot ?? Paths.getRecipeRoot(),
+                        defaultTool: true,
+                        mutableUsage: true,
+                    },
+                    { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
+                ]);
+                const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
+                const summaryBase = {
+                    ...RecipesDiscovery.summarizeDiscovery(discovered),
+                    drafts: RecipesDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
+                };
+                const summary = {
+                    ...summaryBase,
+                    next_actions: ToolsResponse.recipeRegistryNextActions(summaryBase, view),
+                };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: maybeJsonText(summary, input.verbose === true, view === "doctor"
+                                ? ToolsResponse.compactRecipeDoctor(summary)
+                                : view === "imports"
+                                    ? ToolsResponse.compactRecipeImports(summary)
+                                    : ToolsResponse.compactRecipeRegistry(summary)),
+                        },
+                    ],
+                    details: summary,
+                };
+            }
+            const address = Messages.parseActorAddress(target);
+            if (address.kind === "coordinator") {
+                if (view !== "status" && view !== "runs") {
+                    throw new Error("inspect coordinator supports view=status or view=runs.");
+                }
+                const session = ToolsAccess.requireContextSessionId(ctx, "inspect coordinator");
+                const allRuns = AsyncRuns.listRuns(undefined, typeof input.status === "string" ? input.status : undefined).map((run) => AsyncRuns.getRunStatus(String(run.state_dir)));
+                const runs = allRuns.filter((run) => run.ownerId === session);
+                const sessionSummary = summarizeOtherSessions(session, allRuns);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: maybeJsonText({ session, runs, ...sessionSummary }, input.verbose === true, compactSessionRuns(session, runs, sessionSummary)),
+                        },
+                    ],
+                    details: { session, runs, ...sessionSummary },
+                };
+            }
+            if (address.kind === "session") {
+                if (view !== "status" && view !== "runs") {
+                    throw new Error("inspect session:<id> supports view=status or view=runs.");
+                }
+                const allRuns = AsyncRuns.listRuns(undefined, typeof input.status === "string" ? input.status : undefined).map((run) => AsyncRuns.getRunStatus(String(run.state_dir)));
+                const runs = allRuns.filter((run) => address.value === "all" || run.ownerId === address.value);
+                const sessionSummary = address.value === "all"
+                    ? {}
+                    : summarizeOtherSessions(address.value || "", allRuns);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: maybeJsonText({ session: address.value, runs, ...sessionSummary }, input.verbose === true, compactSessionRuns(address.value || "", runs, sessionSummary)),
+                        },
+                    ],
+                    details: { session: address.value, runs, ...sessionSummary },
+                };
+            }
+            if (address.kind === "tool" && address.value) {
+                if (address.value === "pi-actors") {
+                    if (view !== "status") {
+                        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 = ToolsAccess.assertRunAccessibleToContext(address.value, ctx);
+                const stateDir = String(status.state_dir ?? "");
+                if (!stateDir)
+                    throw new Error(`room:${address.value} has no run state directory.`);
+                if (view === "status") {
+                    const status = Rooms.getRoomStatus(stateDir, address.room);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: maybeJsonText(status, input.verbose === true, compactRoomStatus(status)),
+                            },
+                        ],
+                        details: status,
+                    };
+                }
+                if (view === "previews") {
+                    const previews = Rooms.readRoomMessagePreviews(stateDir, address.room, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: maybeJsonText(previews, input.verbose === true, compactRoomPreviews(previews)),
+                            },
+                        ],
+                        details: { previews },
+                    };
+                }
+                if (view === "messages") {
+                    const messages = Rooms.readRoomMessages(stateDir, address.room, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: maybeJsonText(messages, input.verbose === true, compactRoomMessages(messages)),
+                            },
+                        ],
+                        details: { messages },
+                    };
+                }
+                if (view === "contacts") {
+                    const contacts = Rooms.readRoomContacts(stateDir, address.room);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: maybeJsonText(contacts, input.verbose === true, compactRoomContacts(contacts)),
+                            },
+                        ],
+                        details: { contacts },
+                    };
+                }
+                if (view === "roster") {
+                    const roster = Rooms.readRoomRoster(stateDir, address.room);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: maybeJsonText(roster, input.verbose === true, compactRoomRoster(roster)),
+                            },
+                        ],
+                        details: { roster },
+                    };
+                }
+                throw new Error("inspect room:<run> supports view=status, view=messages, view=previews, view=roster, or view=contacts.");
+            }
+            const runId = address.kind === "run" || address.kind === "branch"
+                ? address.value
+                : undefined;
+            if (!runId)
+                throw new Error("inspect target must be run:<id>, branch:<run>/<branch>, coordinator, session:<id>, or tool:<name>.");
+            if (address.kind === "branch") {
+                if (view !== "mailbox")
+                    throw new Error("inspect branch:<run>/<branch> supports view=mailbox.");
+                const status = ToolsAccess.assertRunAccessibleToContext(runId, ctx);
+                const branchInbox = Rooms.readBranchInboxDiagnostics(String(status.state_dir ?? ""), runId, target, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
+                const messages = branchInbox.messages;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: maybeJsonText(input.verbose === true ? branchInbox : messages, input.verbose === true, `${ToolsResponse.compactBranchInbox(messages.map((message) => ({ ...message })))}${branchInbox.corrupted > 0 ? `\ncorrupted=${branchInbox.corrupted}` : ""}`),
+                        },
+                    ],
+                    details: { corrupted: branchInbox.corrupted, messages },
+                };
+            }
+            switch (view) {
+                case "status": {
+                    const status = ToolsAccess.assertRunAccessibleToContext(runId, ctx);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: maybeJsonText(status, input.verbose === true, ToolsResponse.compactAsyncRunStatus(status)),
+                            },
+                        ],
+                        details: status,
+                    };
+                }
+                case "tail": {
+                    ToolsAccess.assertRunAccessibleToContext(runId, ctx);
+                    const text = AsyncRuns.tailRun(runId, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
+                    return {
+                        content: [{ type: "text", text: `\n${text}` }],
+                        details: {},
+                    };
+                }
+                case "messages": {
+                    ToolsAccess.assertRunAccessibleToContext(runId, ctx);
+                    const messages = AsyncRuns.readRunEvents(runId, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: maybeJsonText(messages, input.verbose === true, compactRunMessages(messages)),
+                            },
+                        ],
+                        details: { messages },
+                    };
+                }
+                case "artifacts":
+                case "files": {
+                    const status = ToolsAccess.assertRunAccessibleToContext(runId, ctx);
+                    const artifactManifest = AsyncRuns.resolveArtifactManifest(status.artifacts);
+                    const details = artifactManifest
+                        ? {
+                            ...status,
+                            artifact_manifest: artifactManifest,
+                            next_actions: ToolsResponse.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 = ToolsAccess.assertRunAccessibleToContext(runId, ctx);
+                    const mailbox = asRecord(status.mailbox);
+                    const normalizedMailbox = ToolsMailbox.normalizeMailboxContracts(mailbox);
+                    const messages = AsyncRuns.readRunInboxMessages(runId, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
+                    const details = {
+                        mailbox,
+                        normalized_mailbox: normalizedMailbox,
+                        messages,
+                    };
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: maybeJsonText(details, input.verbose === true, ToolsResponse.compactRunMailbox(String(status.run ?? runId), mailbox, messages)),
+                            },
+                        ],
+                        details,
+                    };
+                }
+                case "communication": {
+                    const status = ToolsAccess.assertRunAccessibleToContext(runId, ctx);
+                    const snapshot = Rooms.readCommunicationSnapshot(String(status.state_dir ?? ""));
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: maybeJsonText(snapshot ?? {}, input.verbose === true, compactCommunicationSnapshot(snapshot)),
+                            },
+                        ],
+                        details: { communication: snapshot },
+                    };
+                }
+                default:
+                    throw new Error("inspect view must be one of: status, tail, messages, artifacts, files, mailbox, communication; branch targets support mailbox.");
+            }
+        },
+    };
+}

package/dist/lib/tools-local.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Local tool definition behavior
+ * Zones: user recipe tools, generated schemas, async recipe launch
+ * Owns wrapping saved local capabilities as executable pi tools
+ */
+import type { RegisteredTool } from "./config.ts";
+import * as Execution from "./execution.ts";
+export interface RuntimeToolContext {
+    cwd: string;
+    sessionManager?: {
+        getSessionId?: () => string;
+    };
+}
+export declare function createRuntimeToolDefinition(cfg: RegisteredTool, exec: Execution.RegisteredToolExec): any;