@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-actors/lib/tools-response.ts

@@ -0,0 +1,285 @@
+/**
+ * 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";
+
+export function withLeadingLineBreak(text: string): string {
+  return `\n${text.replace(/^\n+/, "")}`;
+}
+
+export function spaceToolResult<T>(result: T): T {
+  if (!result || typeof result !== "object") return result;
+  const content = (result as { content?: unknown }).content;
+  if (!Array.isArray(content)) return result;
+  return {
+    ...result,
+    content: content.map((item) =>
+      item &&
+      typeof item === "object" &&
+      (item as { type?: unknown }).type === "text" &&
+      typeof (item as { text?: unknown }).text === "string"
+        ? {
+            ...item,
+            text: withLeadingLineBreak((item as { text: string }).text),
+          }
+        : item,
+    ),
+  };
+}
+
+export function spaceToolError(error: unknown): unknown {
+  if (error instanceof Error) {
+    error.message = withLeadingLineBreak(error.message);
+    return error;
+  }
+  return new Error(withLeadingLineBreak(String(error)));
+}
+
+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;
+}
+
+function compactPolicyAxis(label: string, value: unknown): string | undefined {
+  const axis = asRecord(value);
+  const source = typeof axis.source === "string" ? axis.source : undefined;
+  if (!source || source === "unused") return undefined;
+  const renderedValue =
+    typeof axis.value === "string" && axis.value.trim()
+      ? `:${axis.value.trim()}`
+      : "";
+  return `${label}=${source}${renderedValue}`;
+}
+
+function compactModelPolicy(value: unknown): string[] {
+  const policy = asRecord(value);
+  return [
+    compactPolicyAxis("model", policy.model),
+    compactPolicyAxis("thinking", policy.thinking),
+  ].filter((token): token is string => Boolean(token));
+}
+
+export function runNextActions(run: unknown): string[] {
+  const id = String(run ?? "").trim();
+  if (!id) return [];
+  return [
+    `inspect target=run:${id} view=recipe`,
+    `inspect target=run:${id} view=trace`,
+    `inspect target=run:${id} view=control`,
+  ];
+}
+
+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.launch_kind)
+    tokens.push(`launch_kind=${String(status.launch_kind)}`);
+  tokens.push(...compactModelPolicy(status.model_policy ?? progress.model_policy));
+  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 = runNextActions(run);
+  if (nextActions.length > 0)
+    tokens.push(
+      `next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`,
+    );
+  return `\n${tokens.join(" ")}`;
+}
+
+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 riskSummary = Array.isArray(summary.risk_summary)
+    ? (summary.risk_summary 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 riskCount = riskSummary.reduce(
+    (total, item) => total + Number(item.count ?? 0),
+    0,
+  );
+  const topRisks = riskSummary
+    .slice(0, 4)
+    .map((item) => `${String(item.label)}:${String(item.count ?? 0)}`)
+    .join(",");
+  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} risks=${riskCount}${topRisks ? ` top_risks=${topRisks}` : ""}`,
+  ];
+  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)}`
+      : "";
+    const labels = Array.isArray(item.risk_labels)
+      ? ` labels=${(item.risk_labels as unknown[]).map(String).slice(0, 4).join(",")}`
+      : "";
+    lines.push(
+      `${String(item.severity ?? "info")} kind=${String(item.kind ?? "inspect")} id=${String(item.id ?? "root")}${blocked}${labels} 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 (summary.skill_recipe_catalog_partial === true) {
+    actions.push("inspect target=recipes view=imports verbose=true");
+  }
+  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 skillCatalogPartial = summary.skill_recipe_catalog_partial === true;
+  const currentPolicy = Array.isArray(summary.active)
+    ? (summary.active as Array<Record<string, unknown>>).filter(
+        (entry) => entry.current_policy,
+      ).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} current_policy=${currentPolicy} skill_catalog_partial=${skillCatalogPartial} recommendations=${recommendations} diagnostics=${diagnostics}${compactNextActions(nextActions)}`;
+}
+
+export const DEFAULT_INSPECT_LINES = Limits.DEFAULT_INSPECT_LINES;

package/node_modules/@llblab/pi-actors/lib/tools-spawn.ts

@@ -0,0 +1,212 @@
+/**
+ * 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 { withFileMutationLock } from "./file-state.ts";
+import * as ModelContext from "./model-context.ts";
+import * as Paths from "./paths.ts";
+import type * as RecipeResolution from "./recipes-context.ts";
+import * as RecipesReferences from "./recipes-references.ts";
+import * as RecipesUsage from "./recipes-usage.ts";
+import * as Schema from "./schema.ts";
+import * as ToolsResponse from "./tools-response.ts";
+
+export interface SpawnToolContext extends ModelContext.CurrentModelContext {
+  recipeResolutionContext?: RecipeResolution.RecipeResolutionContext;
+  cwd: string;
+  sessionManager?: { getSessionId?: () => string };
+}
+
+const asRecord = ToolsResponse.asRecord;
+const maybeJsonText = ToolsResponse.maybeJsonText;
+
+function getRunOwnerId(ctx: SpawnToolContext): string | undefined {
+  return ctx.sessionManager?.getSessionId?.();
+}
+
+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(["run_id", "state_dir", "trace_file"]);
+  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,
+  };
+  withFileMutationLock(root, () =>
+    withFileMutationLock(path, () =>
+      writeFileSync(path, `${JSON.stringify(recipe, null, 2)}\n`, { flag: "wx" }),
+    ),
+  );
+  RecipesUsage.recordRecipeLaunch(path, new Date(), "spawn", Paths.getRecipeRoot());
+  return path;
+}
+
+function runIdFromTarget(target: string | undefined): string | undefined {
+  if (!target) return undefined;
+  if (!target.startsWith("run:")) {
+    throw new Error(`spawn.as accepts only run:<id>; received: ${target}`);
+  }
+  const run = target.slice(4);
+  if (!run || !/^[A-Za-z0-9_.-]+$/.test(run)) {
+    throw new Error(`invalid spawn Run target: ${target}`);
+  }
+  return run;
+}
+
+export function createSpawnToolDefinition<
+  TContext extends SpawnToolContext,
+>(): any {
+  return {
+    name: "spawn",
+    label: "Spawn",
+    description:
+      "Create one controllable Run from a Recipe file or inline command template.",
+    parameters: Schema.objectSchema(
+      {
+        artifacts: Schema.looseObjectSchema(
+          "Optional named artifact paths for the spawned Run.",
+        ),
+        as: Schema.stringSchema(
+          "Optional Run identity in exact run:<id> form.",
+        ),
+        file: Schema.stringSchema(
+          "Optional Recipe reference as <skill>/<recipe> or an explicit .json/.md file path.",
+        ),
+        recipe: Schema.stringSchema("Alias for file."),
+        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.",
+        ),
+        transport_context: Schema.looseObjectSchema(
+          "Optional originating transport route preserved for detached terminal follow-up, e.g. Telegram chat_id and thread_id.",
+        ),
+        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);
+      if (input.state_dir !== undefined) {
+        throw new Error(
+          "spawn.state_dir is not supported; run state is runtime-owned so run:<id> remains addressable and retention-safe.",
+        );
+      }
+      const runId = runIdFromTarget(
+        typeof input.as === "string" ? input.as : undefined,
+      );
+      const recipe =
+        typeof input.file === "string"
+          ? input.file
+          : typeof input.recipe === "string"
+            ? input.recipe
+            : undefined;
+      const meta = AsyncRuns.startRun(
+        {
+          file: recipe,
+          launch_source: "spawn",
+          launch_correlation: { tool_call_id: toolCallId },
+          ownerId: getRunOwnerId(ctx),
+          ...(input.transport_context
+            ? { transport_context: asRecord(input.transport_context) } : {}),
+          run_id: runId,
+          ...(input.template !== undefined
+            ? {
+                template:
+                  input.template as AsyncRuns.AsyncRunStartParams["template"],
+              }
+            : {}),
+          values: ModelContext.withCurrentModelValues(
+            asRecord(input.values),
+            ctx,
+          ),
+          ...(input.artifacts &&
+          typeof input.artifacts === "object" &&
+          !Array.isArray(input.artifacts)
+            ? {
+                artifacts: input.artifacts as Record<
+                  string,
+                  AsyncRuns.RunArtifactDeclaration
+                >,
+              }
+            : {}),
+        },
+        ctx.cwd,
+        { skillContext: ctx.recipeResolutionContext?.activeSkills },
+      );
+      const draftRecipe = writeSpawnDraftRecipe(input, meta);
+      const nextActions = ToolsResponse.runNextActions(meta.run);
+      const details = {
+        ...meta,
+        ...(draftRecipe ? { draft_recipe: draftRecipe } : {}),
+        next_actions: nextActions,
+      };
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: maybeJsonText(
+              details,
+              input.verbose === true,
+              ToolsResponse.compactAsyncRunStatus(details),
+            ),
+          },
+        ],
+        details,
+      };
+    },
+  };
+}

package/node_modules/@llblab/pi-actors/lib/tools.ts

@@ -0,0 +1,88 @@
+/**
+ * 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 * as ToolsInspect from "./tools-inspect.ts";
+import type { RuntimeToolContext } from "./tools-local.ts";
+import * as ToolsMessage from "./tools-message.ts";
+import * as ToolsRegister from "./tools-register.ts";
+import * as ToolsSpawn from "./tools-spawn.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 RuntimeToolContext,
+> {
+  configPath: string;
+  getActiveTools: () => string[];
+  getRecipeResolutionContext: () => import("./recipes-context.ts").RecipeResolutionContext | undefined;
+  getRuntimeTool: (name: string) => unknown;
+  getRuntimeToolStatus: (name: string) => Record<string, unknown> | undefined;
+  handleRuntimeControl?: (
+    action: string,
+    input: unknown,
+  ) => Record<string, unknown>;
+  registryRuntime: Pick<
+    RegisterToolRuntimeDeps<TContext>,
+    "getToolNameBlocker" | "getTools" | "notify" | "registerRuntimeTool"
+  > & { getStatus(): import("./runtime.ts").RecipeRegistryStatus };
+  setActiveTools: (toolNames: string[]) => void;
+}
+
+export function resolveActiveRuntimeTool(
+  name: string,
+  activeTools: Pick<Map<string, unknown>, "has">,
+  getDefinition: (name: string) => unknown,
+): unknown {
+  return activeTools.has(name) ? getDefinition(name) : undefined;
+}
+
+export const RESERVED_TOOL_NAMES = new Set([
+  "read",
+  "write",
+  "edit",
+  "bash",
+  "find",
+  "grep",
+  "ls",
+  "register_tool",
+  "message",
+  "spawn",
+  "inspect",
+]);
+
+export function createCoreActorToolDefinitions<
+  TContext extends RuntimeToolContext,
+>(deps: CoreActorToolDefinitionDeps<TContext>): ActorToolDefinition[] {
+  return [
+    ToolsRegister.createRegisterToolDefinition<TContext>({
+      configPath: deps.configPath,
+      getActiveTools: deps.getActiveTools,
+      getToolNameBlocker: deps.registryRuntime.getToolNameBlocker,
+      getTools: deps.registryRuntime.getTools,
+      getRecipeResolutionContext: deps.getRecipeResolutionContext,
+      notify: deps.registryRuntime.notify,
+      registerRuntimeTool: deps.registryRuntime.registerRuntimeTool,
+      reservedToolNames: RESERVED_TOOL_NAMES,
+      setActiveTools: deps.setActiveTools,
+    }),
+    ToolsSpawn.createSpawnToolDefinition<TContext>(),
+    ToolsMessage.createControlToolDefinition<TContext>({
+      handleRuntimeControl: deps.handleRuntimeControl,
+    }),
+    ToolsInspect.createInspectToolDefinition<TContext>({
+      getTool: (name) => deps.getRuntimeTool(name),
+      getToolStatus: deps.getRuntimeToolStatus,
+      registryStatus: deps.registryRuntime.getStatus,
+    }),
+  ];
+}