@llblab/pi-actors 0.34.1 → 0.36.0

package/lib/command-templates.ts

@@ -67,6 +67,29 @@ export interface CommandTemplateExecResult {
   killed: boolean;
 }
 
+export type CommandTemplateRiskLabel =
+  | "risk.shell"
+  | "risk.eval"
+  | "risk.broad_fs_write"
+  | "risk.destructive_fs"
+  | "risk.network"
+  | "risk.external_side_effect"
+  | "risk.long_running"
+  | "risk.platform_specific"
+  | "risk.secret_touching";
+
+const COMMAND_TEMPLATE_RISK_LABEL_ORDER: CommandTemplateRiskLabel[] = [
+  "risk.shell",
+  "risk.eval",
+  "risk.destructive_fs",
+  "risk.broad_fs_write",
+  "risk.external_side_effect",
+  "risk.secret_touching",
+  "risk.network",
+  "risk.long_running",
+  "risk.platform_specific",
+];
+
 export type CommandTemplateExecCommand = (
   command: string,
   args: string[],
@@ -181,6 +204,97 @@ function hasRiskyPathArg(args: string[]): boolean {
   );
 }
 
+function sortRiskLabels(
+  labels: Iterable<CommandTemplateRiskLabel>,
+): CommandTemplateRiskLabel[] {
+  const unique = new Set(labels);
+  return COMMAND_TEMPLATE_RISK_LABEL_ORDER.filter((label) => unique.has(label));
+}
+
+function hasAnyArg(args: string[], values: string[]): boolean {
+  return args.some((arg) => values.includes(arg.toLowerCase()));
+}
+
+function hasSecretTouchingText(parts: string[]): boolean {
+  return parts.some((part) =>
+    /(^|[{}._\-\s/])(?:secret|token|password|passwd|credential|api[_-]?key|private[_-]?key|\.env|ssh[_-]?key)(?:[{}._\-\s/]|$)/i.test(
+      part,
+    ),
+  );
+}
+
+function getLeafCommandTemplateRiskLabels(
+  config: CommandTemplateLeafConfig,
+): CommandTemplateRiskLabel[] {
+  const parts = splitCommandTemplate(config.template);
+  const command = getExecutableName(parts[0]);
+  const args = parts.slice(1);
+  const labels = new Set<CommandTemplateRiskLabel>();
+  if (["bash", "sh", "zsh", "fish"].includes(command)) {
+    labels.add("risk.shell");
+    if (hasAnyFlag(args, ["-c"])) labels.add("risk.eval");
+  }
+  if (
+    ["node", "deno", "bun"].includes(command) &&
+    hasAnyFlag(args, ["-e", "--eval"])
+  ) {
+    labels.add("risk.eval");
+  }
+  if (
+    ["python", "python3", "perl", "ruby"].includes(command) &&
+    hasAnyFlag(args, ["-c", "-e"])
+  ) {
+    labels.add("risk.eval");
+  }
+  if (
+    command === "rm" &&
+    (args.some((arg) => /^-[^-]*r/.test(arg) || /^-[^-]*f/.test(arg)) ||
+      hasRiskyPathArg(args))
+  ) {
+    labels.add("risk.destructive_fs");
+  }
+  if (["mv", "cp", "rsync"].includes(command) && hasRiskyPathArg(args)) {
+    labels.add("risk.broad_fs_write");
+  }
+  if (
+    ["curl", "wget", "ssh", "scp", "sftp", "rsync", "nc", "ncat", "telnet", "ftp"].includes(
+      command,
+    ) ||
+    (command === "git" &&
+      hasAnyArg(args, ["clone", "fetch", "pull", "push", "ls-remote"])) ||
+    ["npm", "pnpm", "yarn", "pip", "cargo"].includes(command)
+  ) {
+    labels.add("risk.network");
+  }
+  if (
+    ["gh", "glab", "hub", "kubectl", "terraform"].includes(command) ||
+    (command === "git" && hasAnyArg(args, ["push"])) ||
+    (["npm", "pnpm", "yarn"].includes(command) &&
+      hasAnyArg(args, ["publish", "login", "logout", "deprecate"]))
+  ) {
+    labels.add("risk.external_side_effect");
+  }
+  if (
+    command === "sleep" ||
+    command === "watch" ||
+    (command === "tail" && hasAnyFlag(args, ["-f"])) ||
+    hasAnyArg(args, ["--watch", "--serve", "serve"])
+  ) {
+    labels.add("risk.long_running");
+  }
+  if (
+    ["systemctl", "launchctl", "osascript", "open", "xdg-open", "powershell", "pwsh", "cmd.exe", "apt", "apt-get", "dnf", "yum", "brew", "pacman", "apk", "xclip", "wl-copy"].includes(
+      command,
+    )
+  ) {
+    labels.add("risk.platform_specific");
+  }
+  if (["pass", "gpg", "ssh-add"].includes(command) || hasSecretTouchingText(parts)) {
+    labels.add("risk.secret_touching");
+  }
+  return sortRiskLabels(labels);
+}
+
 function getLeafCommandTemplateWarnings(
   config: CommandTemplateLeafConfig,
 ): string[] {
@@ -347,6 +461,16 @@ export function getCommandTemplateWarnings(
   ];
 }
 
+export function getCommandTemplateRiskLabels(
+  config: CommandTemplateConfig,
+): CommandTemplateRiskLabel[] {
+  return sortRiskLabels(
+    expandCommandTemplateConfigs(config).flatMap((leaf) =>
+      getLeafCommandTemplateRiskLabels(leaf),
+    ),
+  );
+}
+
 function parseCommandTemplateArgToken(value: string): {
   name: string;
   defaultValue?: string;

package/lib/prompts.ts

@@ -38,6 +38,8 @@ export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
   name: "Tool name in snake_case (e.g., 'transcribe')",
   description:
     "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.",
+  draft:
+    "Promote a draft recipe path from ~/.pi/agent/recipes/drafts into an active named recipe under ~/.pi/agent/recipes. Requires name; use update=true to overwrite.",
   async:
     "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.",
   state_dir:

package/lib/recipes-discovery.ts

@@ -27,6 +27,7 @@ export interface DiscoveredRecipe {
   tool: boolean;
   mutableUsage: boolean;
   diagnostics: string[];
+  riskLabels: CommandTemplates.CommandTemplateRiskLabel[];
   shadows: string[];
 }
 
@@ -110,6 +111,14 @@ function listRecipeFiles(root: string): string[] {
     );
 }
 
+function getRecipeCommandTemplateConfig(
+  config: TemplateRecipeConfig,
+): CommandTemplates.CommandTemplateConfig {
+  return (typeof config.template === "object" && config.template !== null
+    ? config.template
+    : config) as CommandTemplates.CommandTemplateConfig;
+}
+
 function getRecipeConfigDiagnostics(
   file: string,
   config: TemplateRecipeConfig | undefined,
@@ -118,15 +127,36 @@ function getRecipeConfigDiagnostics(
     const reason = RecipesReferences.diagnoseRawRecipeConfigFailure(file);
     return [`Invalid recipe: ${file}${reason ? `: ${reason}` : ""}`];
   }
-  const commandTemplateConfig =
-    typeof config.template === "object" && config.template !== null
-      ? config.template
-      : config;
   return CommandTemplates.getCommandTemplateWarnings(
-    commandTemplateConfig as CommandTemplates.CommandTemplateConfig,
+    getRecipeCommandTemplateConfig(config),
   ).map((warning) => `Recipe ${file}: ${warning}`);
 }
 
+function getRecipeRiskLabels(
+  config: TemplateRecipeConfig | undefined,
+): CommandTemplates.CommandTemplateRiskLabel[] {
+  if (!config) return [];
+  const labels = new Set(
+    CommandTemplates.getCommandTemplateRiskLabels(
+      getRecipeCommandTemplateConfig(config),
+    ),
+  );
+  if (config.async === true) labels.add("risk.long_running");
+  return [
+    "risk.shell",
+    "risk.eval",
+    "risk.destructive_fs",
+    "risk.broad_fs_write",
+    "risk.external_side_effect",
+    "risk.secret_touching",
+    "risk.network",
+    "risk.long_running",
+    "risk.platform_specific",
+  ].filter((label): label is CommandTemplates.CommandTemplateRiskLabel =>
+    labels.has(label as CommandTemplates.CommandTemplateRiskLabel),
+  );
+}
+
 function readDiscoveredRecipe(
   root: string,
   file: string,
@@ -152,6 +182,7 @@ function readDiscoveredRecipe(
       tool: defaultTool && !disabled && !invalid,
       mutableUsage,
       diagnostics: getRecipeConfigDiagnostics(file, config),
+      riskLabels: getRecipeRiskLabels(config),
       shadows: [],
     };
   } catch (error) {
@@ -169,6 +200,7 @@ function readDiscoveredRecipe(
       diagnostics: [
         `Failed to load recipe ${file}: ${error instanceof Error ? error.message : String(error)}`,
       ],
+      riskLabels: [],
       shadows: [],
     };
   }
@@ -392,7 +424,7 @@ function diagnosticSeverity(message: string): "info" | "warning" | "error" {
     return "error";
   }
   if (
-    /world-writable|group-writable|invokes bash|eval|destructive|unsafe/i.test(
+    /world-writable|group-writable|invokes bash|eval|destructive|broad filesystem|unsafe/i.test(
       message,
     )
   ) {
@@ -435,6 +467,7 @@ function diagnosticDetails(
     seen.add(key);
     details.push({
       ...(entry ? { id: entry.id, path: entry.path } : {}),
+      ...(entry?.riskLabels.length ? { risk_labels: entry.riskLabels } : {}),
       action: diagnosticSuggestedAction(message),
       message,
       severity: diagnosticSeverity(message),
@@ -496,6 +529,7 @@ function remediationForEntry(
       kind: "risky_shell_boundary",
       severity: "warning",
       path: entry.path,
+      ...(entry.riskLabels.length ? { risk_labels: entry.riskLabels } : {}),
       reason: riskyDiagnostics[0],
       action:
         "audit trusted command boundary; keep only if the recipe is local and intentional",
@@ -544,6 +578,31 @@ function discoveryRemediations(
     );
 }
 
+function summarizeRiskLabels(
+  entries: DiscoveredRecipe[],
+): Array<Record<string, unknown>> {
+  const counts = new Map<string, { count: number; ids: Set<string> }>();
+  for (const entry of entries) {
+    for (const label of entry.riskLabels) {
+      const current = counts.get(label) ?? { count: 0, ids: new Set<string>() };
+      current.count += 1;
+      current.ids.add(entry.id);
+      counts.set(label, current);
+    }
+  }
+  return [...counts.entries()]
+    .map(([label, value]) => ({
+      label,
+      count: value.count,
+      recipes: [...value.ids].sort(),
+    }))
+    .sort(
+      (a, b) =>
+        Number(b.count) - Number(a.count) ||
+        String(a.label).localeCompare(String(b.label)),
+    );
+}
+
 function recommendationForEntry(
   entry: DiscoveredRecipe,
   activePath: string | undefined,
@@ -574,14 +633,45 @@ export function getShadowedLaunchDiagnostic(
   };
 }
 
+function templatePreview(value: unknown): string | undefined {
+  const rendered =
+    typeof value === "string"
+      ? value
+      : value === undefined
+        ? undefined
+        : JSON.stringify(value);
+  return rendered && rendered.length > 120
+    ? `${rendered.slice(0, 117)}...`
+    : rendered;
+}
+
 export function listDraftRecipes(root: string): Array<Record<string, unknown>> {
   return listRecipeFiles(root).map((path) => {
     const id = RecipesReferences.getRecipeIdFromPath(path);
+    const bytes = readFileSync(path);
+    const stat = statSync(path);
     const config = RecipesReferences.readRawRecipeConfig(path);
+    const resolved = RecipesReferences.readResolvedRecipeConfig(path);
+    const diagnostics = getRecipeConfigDiagnostics(path, resolved);
+    const sourceRun = String(config?.description ?? "").match(
+      /spawn run ([^\s]+)/,
+    )?.[1];
+    const preview = templatePreview(config?.template);
+    const riskLabels = getRecipeRiskLabels(resolved);
     return {
       id,
       path,
+      sha256: createHash("sha256").update(bytes).digest("hex"),
+      size: bytes.byteLength,
+      created_at: stat.birthtime.toISOString(),
+      modified_at: stat.mtime.toISOString(),
+      valid: Boolean(resolved),
+      diagnostics,
+      ...(riskLabels.length ? { risk_labels: riskLabels } : {}),
       ...(config?.description ? { description: config.description } : {}),
+      ...(sourceRun ? { source_run: sourceRun } : {}),
+      ...(config?.async !== undefined ? { async: config.async } : {}),
+      ...(preview ? { template_preview: preview } : {}),
     };
   });
 }
@@ -610,6 +700,7 @@ export function summarizeDiscovery(
         disabled: entry.disabled,
         invalid: entry.invalid,
         shadows: entry.shadows,
+        ...(entry.riskLabels.length ? { risk_labels: entry.riskLabels } : {}),
         ...(entry.config?.imports ? { imports: entry.config.imports } : {}),
         ...(recipeUsage(entry.config)
           ? { usage: recipeUsage(entry.config) }
@@ -636,6 +727,7 @@ export function summarizeDiscovery(
       .filter((entry) => entry.disabled)
       .map((entry) => ({ id: entry.id, path: entry.path }))
       .sort((a, b) => a.id.localeCompare(b.id)),
+    risk_summary: summarizeRiskLabels(result.entries),
     recommendations,
     remediations,
     top_action: remediations[0],

package/lib/registry.ts

@@ -5,7 +5,7 @@
  */
 
 import { existsSync, mkdirSync, unlinkSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 
 import * as CommandTemplates from "./command-templates.ts";
 import * as Config from "./config.ts";
@@ -22,6 +22,7 @@ export interface RegisterToolInput {
   async?: boolean;
   state_dir?: string;
   template?: CommandTemplates.CommandTemplateValue | null;
+  draft?: string;
   args?: string;
   update?: boolean;
   values?: Record<string, unknown>;
@@ -32,6 +33,8 @@ export interface RegisterToolResultDetails {
   async?: boolean;
   config?: string;
   defaults?: Record<string, string>;
+  draft?: string;
+  promoted?: boolean;
   recipeName?: string;
   state_dir?: string;
   template?: CommandTemplates.CommandTemplateValue;
@@ -95,6 +98,93 @@ function getToolRecipePath<TContext>(
   return join(getRecipeRoot(deps), `${name}.json`);
 }
 
+function assertDraftPath<TContext>(
+  deps: RegisterToolRuntimeDeps<TContext>,
+  draft: string,
+): string {
+  const draftRoot = resolve(getRecipeRoot(deps), "drafts");
+  const path = resolve(draft);
+  const relation = relative(draftRoot, path);
+  if (
+    relation === "" ||
+    relation.startsWith("..") ||
+    resolve(relation) === relation
+  ) {
+    throw new Error(
+      ExecutionOutput.formatToolText(
+        `Draft must be under ${draftRoot}. Use inspect target=recipes view=summary to list drafts.`,
+      ),
+    );
+  }
+  if (!existsSync(path)) {
+    throw new Error(ExecutionOutput.formatToolText(`Draft not found: ${path}`));
+  }
+  return path;
+}
+
+function promoteDraftRecipe<TContext>(
+  name: string,
+  input: RegisterToolInput,
+  ctx: TContext,
+  deps: RegisterToolRuntimeDeps<TContext>,
+): RegisterToolResult {
+  const draftPath = assertDraftPath(deps, String(input.draft ?? ""));
+  const targetPath = getToolRecipePath(deps, name);
+  const tools = deps.getTools();
+  const existing = tools.get(name);
+  const conflict = deps.getExternalToolConflict(name);
+  if (conflict) throw new Error(ExecutionOutput.formatToolText(conflict));
+  if ((existing || existsSync(targetPath)) && !input.update) {
+    throw new Error(
+      ExecutionOutput.formatToolText(
+        `Tool "${name}" already registered. Use update=true to overwrite.`,
+      ),
+    );
+  }
+  const config = RecipesReferences.readResolvedRecipeConfig(draftPath);
+  if (!config) {
+    const reason = RecipesReferences.diagnoseRawRecipeConfigFailure(draftPath);
+    throw new Error(
+      ExecutionOutput.formatToolText(
+        `Draft recipe is invalid${reason ? `: ${reason}` : "."}`,
+      ),
+    );
+  }
+  const promoted = buildConfig(
+    name,
+    {
+      ...input,
+      description: input.description ?? config.description,
+      template: draftPath,
+    },
+    existing,
+  );
+  const raw = RecipesReferences.readRawRecipeConfig(draftPath)!;
+  mkdirSync(dirname(targetPath), { recursive: true });
+  writeJsonAtomic(targetPath, raw);
+  promoted.template = targetPath;
+  promoted.sourcePath = targetPath;
+  tools.set(name, promoted);
+  deps.registerRuntimeTool(promoted);
+  deps.notify(ctx, `Promoted draft recipe: ${name}`, "info");
+  return {
+    content: [
+      textContent(
+        ExecutionOutput.formatToolText(
+          `${existing ? "Updated" : "Registered"} tool "${name}" from draft recipe.`,
+        ),
+      ),
+    ],
+    details: {
+      args: promoted.args,
+      config: targetPath,
+      draft: draftPath,
+      promoted: true,
+      tool: name,
+    } as RegisterToolResultDetails & Record<string, unknown>,
+  };
+}
+
 function persistToolRecipe<TContext>(
   deps: RegisterToolRuntimeDeps<TContext>,
   cfg: Config.RegisteredTool,
@@ -284,6 +374,9 @@ export async function executeRegisterTool<TContext>(
       ExecutionOutput.formatToolText(`Reserved tool name: ${name}`),
     );
   }
+  if (typeof input.draft === "string" && input.draft.trim()) {
+    return promoteDraftRecipe(name, input, ctx, deps);
+  }
   const templateProvided = Object.hasOwn(input, "template");
   const template = getInputTemplate(input.template);
   if (templateProvided && (template === null || template === ""))

package/lib/runtime-notifier.ts

@@ -147,6 +147,7 @@ export function createFileRuntimeNotifier(
       mkdirSync(dirname(file), { recursive: true });
       let position =
         options.replay || !existsSync(file) ? 0 : statSync(file).size;
+      let pending = "";
       let closed = false;
       const reconcile = (reason: RuntimeReconcileReason): void => {
         if (closed) return;
@@ -160,10 +161,15 @@ export function createFileRuntimeNotifier(
       const drain = (): void => {
         if (closed || !existsSync(file)) return;
         const buffer = readFileSync(file);
-        if (position > buffer.length) position = 0;
-        const chunk = buffer.subarray(position).toString("utf8");
+        if (position > buffer.length) {
+          position = 0;
+          pending = "";
+        }
+        const chunk = pending + buffer.subarray(position).toString("utf8");
         position = buffer.length;
-        for (const line of chunk.split("\n")) {
+        const lines = chunk.split("\n");
+        pending = chunk.endsWith("\n") ? "" : (lines.pop() ?? "");
+        for (const line of lines) {
           if (!line.trim()) continue;
           const event = parseRuntimeWakeEventLine(line);
           if (event && event.actor === actor) {