@llblab/pi-actors 0.33.0 → 0.34.0

package/dist/lib/tools-response.js

@@ -0,0 +1,219 @@
+/**
+ * Public tool response formatting
+ * Zones: compact text summaries, verbose JSON switching, next-action rendering
+ * Owns model-facing response helpers shared by public tool execution paths
+ */
+import * as Limits from "./limits.js";
+import * as ToolsMailbox from "./tools-mailbox.js";
+export function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+export function jsonText(value) {
+    return `\n${JSON.stringify(value, null, 2)}`;
+}
+export 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;
+}
+export function compactNextActions(actions) {
+    return actions.length
+        ? ` next=${actions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`
+        : "";
+}
+function formatFailureCount(value) {
+    return Array.isArray(value) ? value.length : undefined;
+}
+export 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>`,
+    ];
+}
+export 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(" ")}`;
+}
+export 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")}`;
+}
+export function compactBranchInbox(messages) {
+    return compactInboxMessages(messages, "branch inbox");
+}
+export function compactRunMailbox(run, mailbox, messages) {
+    const normalized = ToolsMailbox.normalizeMailboxContracts(mailbox);
+    return `\nrun=${run} accepts=${ToolsMailbox.mailboxTypes(normalized.accepts).join(",")} emits=${ToolsMailbox.mailboxTypes(normalized.emits).join(",")}${compactInboxMessages(messages, "run inbox")}`;
+}
+export 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`,
+    ];
+}
+export function maybeJsonText(value, verbose, compact) {
+    return verbose ? jsonText(value) : compact;
+}
+export 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)";
+}
+export 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")}`;
+}
+export 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);
+}
+export 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)}`;
+}
+export const DEFAULT_INSPECT_LINES = Limits.DEFAULT_INSPECT_LINES;

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

@@ -0,0 +1,12 @@
+/**
+ * Public spawn tool behavior
+ * Zones: actor launch, draft recipe capture, launch diagnostics
+ * Owns the public spawn execution path for run-backed actors
+ */
+export interface SpawnToolContext {
+    cwd: string;
+    sessionManager?: {
+        getSessionId?: () => string;
+    };
+}
+export declare function createSpawnToolDefinition<TContext extends SpawnToolContext>(): any;

package/dist/lib/tools-spawn.js

@@ -0,0 +1,159 @@
+/**
+ * Public spawn tool behavior
+ * Zones: actor launch, draft recipe capture, launch diagnostics
+ * Owns the public spawn execution path for run-backed actors
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import * as AsyncRuns from "./async-runs.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 ToolsResponse from "./tools-response.js";
+const asRecord = ToolsResponse.asRecord;
+const maybeJsonText = ToolsResponse.maybeJsonText;
+function getRunOwnerId(ctx) {
+    return ctx.sessionManager?.getSessionId?.();
+}
+function shadowedRecipeLaunchDiagnostic(recipe) {
+    if (typeof recipe !== "string" ||
+        recipe.includes("/") ||
+        recipe.includes("~"))
+        return undefined;
+    const discovery = RecipesDiscovery.discoverRecipeSources([
+        { root: Paths.getRecipeRoot(), defaultTool: true, mutableUsage: true },
+        { root: Paths.getPackagedRecipeRoot(), defaultTool: false },
+    ]);
+    return RecipesDiscovery.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 = Messages.parseActorAddress(address);
+    if (parsed.kind !== "run" || !parsed.value) {
+        throw new Error(`Expected run:<id> actor address, received: ${address}`);
+    }
+    return parsed.value;
+}
+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: Schema.objectSchema({
+            artifacts: Schema.looseObjectSchema("Optional named artifact paths for the spawned actor."),
+            as: Schema.stringSchema("Optional actor address for the spawned run, e.g. run:<id>."),
+            file: Schema.stringSchema("Optional template recipe JSON file. Bare names resolve under ~/.pi/agent/recipes."),
+            recipe: Schema.stringSchema("Alias for file; template recipe JSON file/name to spawn."),
+            state_dir: Schema.stringSchema("Optional explicit run state directory."),
+            template: Schema.unionSchema([
+                Schema.stringSchema("Inline command template string"),
+                Schema.arraySchema("Inline command-template sequence or parallel tree"),
+                Schema.looseObjectSchema("Inline command-template object with flags such as parallel, repeat, retry, failure, and nested template."),
+            ]),
+            values: Schema.looseObjectSchema("Runtime placeholder values passed to the actor."),
+            verbose: Schema.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 = ToolsResponse.actorRunNextActions(meta.run);
+            const details = {
+                ...meta,
+                ...(draftRecipe ? { draft_recipe: draftRecipe } : {}),
+                next_actions: nextActions,
+            };
+            Rooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
+            Rooms.writeCommunicationSnapshot(meta.state_dir, String(meta.run));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: maybeJsonText(details, input.verbose === true, ToolsResponse.compactAsyncRunStatus(details)),
+                    },
+                ],
+                details,
+            };
+        },
+    };
+}

package/dist/lib/tools.d.ts

@@ -1,19 +1,17 @@
 /**
- * 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 type { RegisteredTool } from "./config.ts";
-import * as Execution from "./execution.ts";
-import * as Registry from "./registry.ts";
-export type RegisterToolInput = Registry.RegisterToolInput;
-export type RegisterToolRuntimeDeps<TContext> = Registry.RegisterToolRuntimeDeps<TContext>;
+import type { RuntimeToolContext } from "./tools-local.ts";
+import * as ToolsRegister from "./tools-register.ts";
+export type RegisterToolRuntimeDeps<TContext> = ToolsRegister.RegisterToolRuntimeDeps<TContext>;
 export interface ActorToolDefinition {
     name: string;
     execute?: (...args: never[]) => unknown;
     [key: string]: unknown;
 }
-export interface CoreActorToolDefinitionDeps<TContext extends AsyncRunToolContext> {
+export interface CoreActorToolDefinitionDeps<TContext extends RuntimeToolContext> {
     configPath: string;
     getActiveTools: () => string[];
     getRuntimeTool: (name: string) => unknown;
@@ -21,33 +19,4 @@ export interface CoreActorToolDefinitionDeps<TContext extends AsyncRunToolContex
     setActiveTools: (toolNames: string[]) => void;
 }
 export declare const RESERVED_TOOL_NAMES: Set<string>;
-type JsonSchema = Record<string, unknown>;
-export declare function createRegisterToolDefinition<TContext>(deps: RegisterToolRuntimeDeps<TContext>): {
-    name: string;
-    label: string;
-    description: string;
-    promptSnippet: string;
-    promptGuidelines: string[];
-    parameters: JsonSchema;
-    execute: (_toolCallId: string, params: unknown, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: TContext) => Promise<Registry.RegisterToolResult>;
-};
-export interface AsyncRunToolContext {
-    cwd: string;
-    sessionManager?: {
-        getSessionId?: () => string;
-    };
-}
-export declare function createSpawnToolDefinition<TContext extends AsyncRunToolContext>(): any;
-export interface InspectToolDeps<TContext = unknown> {
-    getTool?: (name: string) => any | undefined;
-    packagedRecipeRoot?: string;
-    recipeRoot?: string;
-}
-export declare function createInspectToolDefinition<TContext = unknown>(deps?: InspectToolDeps<TContext>): any;
-export interface ActorMessageToolDeps<TContext = unknown> {
-    getTool?: (name: string) => any | undefined;
-}
-export declare function createActorMessageToolDefinition<TContext = unknown>(deps?: ActorMessageToolDeps<TContext>): any;
-export declare function createCoreActorToolDefinitions<TContext extends AsyncRunToolContext>(deps: CoreActorToolDefinitionDeps<TContext>): ActorToolDefinition[];
-export declare function createRuntimeToolDefinition(cfg: RegisteredTool, exec: Execution.RegisteredToolExec): any;
-export {};
+export declare function createCoreActorToolDefinitions<TContext extends RuntimeToolContext>(deps: CoreActorToolDefinitionDeps<TContext>): ActorToolDefinition[];