@llblab/pi-actors 0.33.0 → 0.34.0

package/lib/tools-response.ts

@@ -0,0 +1,267 @@
+/**
+ * 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.ts";
+import * as ToolsMailbox from "./tools-mailbox.ts";
+
+export function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+export function jsonText(value: unknown): string {
+  return `\n${JSON.stringify(value, null, 2)}`;
+}
+
+export function compactPreview(
+  value: unknown,
+  maxLength = Limits.COMPACT_PREVIEW_CHARS,
+): string | undefined {
+  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: string[]): string {
+  return actions.length
+    ? ` next=${actions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`
+    : "";
+}
+
+function formatFailureCount(value: unknown): number | undefined {
+  return Array.isArray(value) ? value.length : undefined;
+}
+
+export function actorRunNextActions(run: unknown): string[] {
+  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: unknown): string {
+  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: Array<Record<string, unknown>>,
+  emptyLabel: string,
+): string {
+  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: Array<Record<string, unknown>>,
+): string {
+  return compactInboxMessages(messages, "branch inbox");
+}
+
+export function compactRunMailbox(
+  run: string,
+  mailbox: Record<string, unknown>,
+  messages: Array<Record<string, unknown>>,
+): string {
+  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: unknown,
+  artifacts: Record<string, unknown>,
+): string[] {
+  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: unknown,
+  verbose: boolean | undefined,
+  compact: string,
+): string {
+  return verbose ? jsonText(value) : compact;
+}
+
+export function compactRecipeImports(summary: Record<string, unknown>): string {
+  const active = Array.isArray(summary.active)
+    ? (summary.active as Array<Record<string, unknown>>)
+    : [];
+  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: Record<string, unknown>): string {
+  const details = Array.isArray(summary.diagnostic_details)
+    ? (summary.diagnostic_details as Array<Record<string, unknown>>)
+    : [];
+  const remediations = Array.isArray(summary.remediations)
+    ? (summary.remediations as Array<Record<string, unknown>>)
+    : [];
+  const recommendations = Array.isArray(summary.recommendations)
+    ? (summary.recommendations as Array<Record<string, unknown>>)
+    : [];
+  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 as string[])
+    : [];
+  if (nextActions.length > 0)
+    lines[0] = `${lines[0]}${compactNextActions(nextActions)}`;
+  return `\n${lines.join("\n")}`;
+}
+
+export function recipeRegistryNextActions(
+  summary: Record<string, unknown>,
+  view: string,
+): string[] {
+  const actions: string[] = [];
+  const drafts = Array.isArray(summary.drafts)
+    ? (summary.drafts as Array<Record<string, unknown>>)
+    : [];
+  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: Record<string, unknown>,
+): string {
+  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 as string[])
+    : [];
+  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/lib/tools-spawn.ts

@@ -0,0 +1,240 @@
+/**
+ * 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.ts";
+import * as Messages from "./messages.ts";
+import * as Paths from "./paths.ts";
+import * as RecipesDiscovery from "./recipes-discovery.ts";
+import * as Rooms from "./rooms.ts";
+import * as Schema from "./schema.ts";
+import * as ToolsResponse from "./tools-response.ts";
+
+export interface SpawnToolContext {
+  cwd: string;
+  sessionManager?: { getSessionId?: () => string };
+}
+
+const asRecord = ToolsResponse.asRecord;
+const maybeJsonText = ToolsResponse.maybeJsonText;
+
+function getRunOwnerId(ctx: SpawnToolContext): string | undefined {
+  return ctx.sessionManager?.getSessionId?.();
+}
+
+function shadowedRecipeLaunchDiagnostic(
+  recipe: unknown,
+): Record<string, unknown> | undefined {
+  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: string): string {
+  return `${run.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "spawn"}.json`;
+}
+
+function draftRecipeDefaults(
+  values: Record<string, unknown>,
+): Record<string, unknown> | undefined {
+  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: Record<string, unknown>,
+  meta: AsyncRuns.AsyncRunMeta,
+): string | undefined {
+  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: unknown, recipe: unknown): Error {
+  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: string | undefined,
+): string | undefined {
+  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<
+  TContext extends SpawnToolContext,
+>(): any {
+  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: string,
+      params: unknown,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      ctx: TContext,
+    ) {
+      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: AsyncRuns.AsyncRunMeta;
+      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 as AsyncRuns.AsyncRunStartParams["template"],
+                }
+              : {}),
+            values: asRecord(input.values),
+            ...(input.artifacts &&
+            typeof input.artifacts === "object" &&
+            !Array.isArray(input.artifacts)
+              ? {
+                  artifacts: input.artifacts as Record<
+                    string,
+                    AsyncRuns.RunArtifactDeclaration
+                  >,
+                }
+              : {}),
+          },
+          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" as const,
+            text: maybeJsonText(
+              details,
+              input.verbose === true,
+              ToolsResponse.compactAsyncRunStatus(details),
+            ),
+          },
+        ],
+        details,
+      };
+    },
+  };
+}