@llblab/pi-kit 0.1.0

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

@@ -0,0 +1,111 @@
+/**
+ * Registry path helpers
+ * Zones: paths, registry config, temp directory
+ * Owns agent directory, tools config, recipe root, and actor run state root resolution
+ */
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function getAgentDir(
+  env: Record<string, string | undefined> = process.env,
+): string {
+  return env.PI_CODING_AGENT_DIR
+    ? resolve(env.PI_CODING_AGENT_DIR)
+    : join(homedir(), ".pi", "agent");
+}
+
+export function isAutomaticRecipeReviewEnabled(
+  env: Record<string, string | undefined> = process.env,
+): boolean {
+  const value = env.PI_ACTORS_AUTOMATIC_REVIEW?.trim().toLowerCase();
+  return value === undefined || !["0", "false", "off"].includes(value);
+}
+
+export interface ExtensionRuntimePaths {
+  configPath: string;
+  runStateRoot: string;
+  tempDir: string;
+}
+
+export function getConfigPath(agentDir = getAgentDir()): string {
+  return join(agentDir, "tool-registry.json");
+}
+
+export function getExtensionTmpDir(
+  agentDir = getAgentDir(),
+  extensionName = "pi-actors",
+): string {
+  return join(agentDir, "tmp", extensionName);
+}
+
+export function getRunStateRoot(agentDir = getAgentDir()): string {
+  return join(getExtensionTmpDir(agentDir), "runs");
+}
+
+export function getDraftSleepRoot(agentDir = getAgentDir()): string {
+  return join(getExtensionTmpDir(agentDir), "draft-sleep");
+}
+
+export function getDraftSleepStatePath(agentDir = getAgentDir()): string {
+  return join(getDraftSleepRoot(agentDir), "state.json");
+}
+
+export function getDraftSleepBatchDir(
+  batchId: string,
+  agentDir = getAgentDir(),
+): string {
+  if (!/^[a-f0-9-]{36}$/u.test(batchId)) {
+    throw new Error("Invalid draft sleep batch id.");
+  }
+  return join(getDraftSleepRoot(agentDir), "batches", batchId);
+}
+
+export function getToolReviewRoot(agentDir = getAgentDir()): string {
+  return join(getExtensionTmpDir(agentDir), "tool-review");
+}
+
+export function getToolReviewStatePath(agentDir = getAgentDir()): string {
+  return join(getToolReviewRoot(agentDir), "state.json");
+}
+
+export function getToolReviewBatchDir(
+  reviewId: string,
+  agentDir = getAgentDir(),
+): string {
+  if (!/^[a-f0-9-]{36}$/u.test(reviewId)) {
+    throw new Error("Invalid tool review id.");
+  }
+  return join(getToolReviewRoot(agentDir), "batches", reviewId);
+}
+
+export function getExtensionRuntimePaths(
+  agentDir = getAgentDir(),
+): ExtensionRuntimePaths {
+  return {
+    configPath: getConfigPath(agentDir),
+    runStateRoot: getRunStateRoot(agentDir),
+    tempDir: getExtensionTmpDir(agentDir),
+  };
+}
+
+export const EXTENSION_RUNTIME_PATHS = getExtensionRuntimePaths();
+
+export function getExtensionSkillsDir(extensionUrl: string): string {
+  return join(dirname(fileURLToPath(extensionUrl)), "skills");
+}
+
+export function getExistingExtensionSkillPaths(extensionUrl: string): string[] {
+  const skillsDir = getExtensionSkillsDir(extensionUrl);
+  return existsSync(skillsDir) ? [skillsDir] : [];
+}
+
+export function getRecipeRoot(agentDir = getAgentDir()): string {
+  return join(agentDir, "recipes");
+}
+
+export function getRecipeDraftRoot(agentDir = getAgentDir()): string {
+  return join(getRecipeRoot(agentDir), "drafts");
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Pi SDK adapter boundary.
+ * Zones: pi agent sdk boundary, extension host adapters
+ * Owns direct pi SDK imports and exposes narrow pi-actors-facing helpers/types for the composition root.
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+export type { ExtensionAPI, ExtensionContext };
+
+export interface PiNotificationSink {
+  notify(message: string, level: "info" | "warning" | "error"): void;
+  sendFollowUp(message: {
+    customType: string;
+    content: string;
+    display: false;
+    details: unknown;
+  }): void;
+}
+
+export function getSessionId(ctx: ExtensionContext): string {
+  return ctx.sessionManager.getSessionId();
+}
+
+export function createNotificationSink(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+): PiNotificationSink {
+  return {
+    notify: (message, level) => ctx.ui.notify(message, level),
+    sendFollowUp: (message) =>
+      pi.sendMessage(message, {
+        deliverAs: "followUp",
+        triggerTurn: true,
+      }),
+  };
+}
+
+export function registerToolDefinitions(
+  pi: ExtensionAPI,
+  definitions: Iterable<unknown>,
+): void {
+  for (const definition of definitions) pi.registerTool(definition as never);
+}

package/node_modules/@llblab/pi-actors/lib/preflight-diagnostics.ts

@@ -0,0 +1,132 @@
+/**
+ * Review preflight diagnostics
+ * Zones: recipe diagnostics, subagent launch policy
+ * Owns compact classification of failed review-pipeline preflight commands.
+ */
+
+export type ReviewPreflightErrorClass =
+  | "auth_or_key"
+  | "model_unavailable"
+  | "quota_or_balance"
+  | "rate_limited"
+  | "timeout"
+  | "transport"
+  | "unknown_provider_failure";
+
+export interface ReviewPreflightDiagnosticInput {
+  args: readonly string[];
+  code?: number;
+  killed?: boolean;
+  promptFile?: string;
+  promptText?: string;
+  stderr?: string;
+  stdout?: string;
+}
+
+export interface ReviewPreflightDiagnostic {
+  errorClass: ReviewPreflightErrorClass;
+  model?: string;
+  promptFile?: string;
+  stage: string;
+  suggestedOverrideArgs: string;
+  thinking?: string;
+}
+
+const PREFLIGHT_STAGE_PATTERN = /Preflight check for stage\s+([^\s.]+)\.?/i;
+
+function getFlagValue(args: readonly string[], flag: string): string | undefined {
+  const inlinePrefix = `${flag}=`;
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (value === flag) return args[index + 1];
+    if (value?.startsWith(inlinePrefix)) return value.slice(inlinePrefix.length);
+  }
+  return undefined;
+}
+
+function getToolPolicy(args: readonly string[]): string {
+  if (args.includes("--no-tools")) return "<tool-policy>";
+  return getFlagValue(args, "--tools") ?? "<tool-policy>";
+}
+
+export function extractReviewPreflightStage(
+  promptText: string | undefined,
+): string | undefined {
+  return promptText?.match(PREFLIGHT_STAGE_PATTERN)?.[1];
+}
+
+export function classifyReviewPreflightError(
+  text: string,
+  killed = false,
+): ReviewPreflightErrorClass {
+  if (killed) return "timeout";
+  const normalized = text.toLowerCase();
+  if (/insufficient[_ -]?quota|\bquota\b|balance|billing|credits?|payment/.test(normalized)) {
+    return "quota_or_balance";
+  }
+  if (/api[_ -]?key|unauthori[sz]ed|forbidden|permission|\b401\b|\b403\b|auth/.test(normalized)) {
+    return "auth_or_key";
+  }
+  if (/\b404\b|not found|unknown model|model .*not (exist|found)|invalid model|unsupported model/.test(normalized)) {
+    return "model_unavailable";
+  }
+  if (/rate limit|\b429\b|too many requests/.test(normalized)) {
+    return "rate_limited";
+  }
+  if (/network|econn|enotfound|etimedout|fetch failed|socket|\btls\b/.test(normalized)) {
+    return "transport";
+  }
+  return "unknown_provider_failure";
+}
+
+function getStageModelArg(stage: string): string {
+  if (
+    stage === "reviewer" ||
+    stage === "verifier" ||
+    stage === "merger" ||
+    stage === "judge"
+  ) {
+    return `${stage}_model`;
+  }
+  return "model";
+}
+
+function buildSuggestedOverrideArgs(stage: string, args: readonly string[]): string {
+  return `${getStageModelArg(stage)}=<working-model> thinking=<supported-level> tools=${getToolPolicy(args)}`;
+}
+
+export function buildReviewPreflightDiagnostic(
+  input: ReviewPreflightDiagnosticInput,
+): ReviewPreflightDiagnostic | undefined {
+  const stage = extractReviewPreflightStage(input.promptText);
+  if (!stage) return undefined;
+  return {
+    errorClass: classifyReviewPreflightError(
+      [input.stderr, input.stdout].filter(Boolean).join("\n"),
+      input.killed,
+    ),
+    ...(getFlagValue(input.args, "--model")
+      ? { model: getFlagValue(input.args, "--model") }
+      : {}),
+    ...(input.promptFile ? { promptFile: input.promptFile } : {}),
+    stage,
+    suggestedOverrideArgs: buildSuggestedOverrideArgs(stage, input.args),
+    ...(getFlagValue(input.args, "--thinking")
+      ? { thinking: getFlagValue(input.args, "--thinking") }
+      : {}),
+  };
+}
+
+export function formatReviewPreflightDiagnostic(
+  diagnostic: ReviewPreflightDiagnostic,
+): string {
+  return [
+    "ACTOR_PREFLIGHT_FAILED",
+    `stage=${diagnostic.stage}`,
+    ...(diagnostic.model ? [`model=${diagnostic.model}`] : []),
+    ...(diagnostic.thinking ? [`thinking=${diagnostic.thinking}`] : []),
+    `error_class=${diagnostic.errorClass}`,
+    ...(diagnostic.promptFile ? [`prompt_file=${diagnostic.promptFile}`] : []),
+    `suggested_override_args=\"${diagnostic.suggestedOverrideArgs}\"`,
+  ].join(" ");
+}

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

@@ -0,0 +1,69 @@
+/**
+ * Prompt and schema copy helpers
+ * Zones: prompts, onboarding, tool schema copy
+ * Owns LLM-facing descriptions, prompt snippets, guidelines, and parameter descriptions
+ */
+
+export const REGISTER_TOOL_DESCRIPTION =
+  "Register a persistent custom tool from one maintained Recipe, command template, or captured draft. " +
+  "Use from for Recipe specialization, template for trusted commands, or draft for promotion. " +
+  "Definitions persist under ~/.pi/agent/recipes; activation is reported separately.";
+
+export const REGISTER_TOOL_PROMPT_SNIPPET =
+  "Register persistent Recipes or command templates as agent-callable tools";
+
+export const REGISTER_TOOL_GUIDELINES = [
+  "Use register_tool from=<skill>/<recipe> with defaults={...} to specialize a maintained Recipe without copying its contract.",
+  "Use register_tool template only for trusted command templates, and use register_tool draft only for captured draft promotion.",
+  "After register_tool succeeds, trust its callable_now and activation result; persistence alone is not callability.",
+  'Set template=null or template="" in register_tool to delete a persisted tool.',
+  "Set update=true in register_tool to overwrite an existing tool registration.",
+];
+
+export const ONBOARDING_SYSTEM_PROMPT = `pi-actors Skill routing:
+- Treat active bundled Skills as the operating authority.
+- For non-trivial pi-actors operation, diagnosis, or development, load and read the actors Skill before acting.
+- For work requiring multiple actors or subagents, additionally load and read the swarm Skill.
+- For capability-specific selection or constraints, load the owning capability Skill; actors owns generic mechanics and swarm owns multi-actor methodology.
+- Keep a Skill Recipe distinct from a registered tool and a Recipe spawn distinct from registered-tool invocation; actors owns the proof rules.
+- Treat persistence or registration as distinct from current callability; actors owns activation proof.
+- On failure or disagreement, preserve the logical Recipe identity, stop, and follow actors diagnosis; never bypass the owning Skills with copied contracts, helper paths, shell evaluation, or background-process workarounds.
+- If a capability Skill conflicts with actors about generic mechanics, follow actors and report the stale capability guidance.
+- README and docs are human-facing references, not the normal agent operating path.
+- AGENTS, source, and tests are implementation protocol and evidence; use them when changing or debugging the extension, not as substitutes for operating Skills.`;
+
+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.",
+  from:
+    "Recipe to specialize by canonical <skill>/<recipe> identity or explicit .json/.md path. Inherits async, args/types, source defaults, artifacts, Control, and runtime origins.",
+  defaults:
+    "Optional caller-owned defaults. Keys and values must satisfy the effective source or command-template argument contract.",
+  draft:
+    "Promote a captured draft Recipe path from ~/.pi/agent/recipes/drafts. This is a source mode; do not combine it with from or template.",
+  async:
+    "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.",
+  template:
+    "Trusted command template with {arg} or {arg=default} placeholders. To specialize a Recipe, use from instead. Omitted updates keep the old template; empty string deletes the tool.",
+  templateArray:
+    "Sequential command-template composition array. Leaves may be strings or objects with template/defaults/timeout/retry/failure/recover.",
+  templateNull: "Delete the tool when template is null.",
+  args: "Optional comma-separated placeholder declarations. Usually omit because args are derived from template placeholders. Interactive shorthand defaults are accepted and normalized. Example: file,lang,mode=fast",
+  update: "Set to true to overwrite an existing tool registration.",
+} as const;
+
+export function formatRegisteredToolPromptSnippet(template: unknown): string {
+  const rendered =
+    typeof template === "string" ? template : JSON.stringify(template);
+  return `Execute command template: ${rendered}`;
+}
+
+export function formatRecipeToolPromptSnippet(
+  recipe: string,
+  asyncRecipe: boolean,
+): string {
+  return asyncRecipe
+    ? `Start async template recipe: ${recipe}`
+    : `Execute template recipe: ${recipe}`;
+}

package/node_modules/@llblab/pi-actors/lib/recipe-control.ts

@@ -0,0 +1,52 @@
+/**
+ * Recipe Control contract.
+ * Zones: actor-local action declarations, normalization, reserved-action fencing
+ * Owns pure Recipe control validation; Recipe loading and Run capture stay in recipe/run domains.
+ */
+
+import * as Control from "./control.ts";
+import * as Limits from "./limits.ts";
+
+const RUNTIME_RUN_ACTIONS = new Set(["archive", "kill", "prune"]);
+
+export function normalizeRecipeControl(value: unknown): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) {
+    throw new Error("recipe.control must be an array of action strings");
+  }
+  const actions: string[] = [];
+  const seen = new Set<string>();
+  for (const raw of value) {
+    if (typeof raw !== "string" || !raw.trim()) {
+      throw new Error("recipe.control actions must be non-empty strings");
+    }
+    const action = raw.trim();
+    if (!Control.isControlAction(action)) {
+      throw new Error(`invalid recipe.control action: ${action}`);
+    }
+    if (action.length > Limits.CONTROL_ACTION_MAX_LENGTH) {
+      throw new Error(
+        `recipe.control action exceeds ${Limits.CONTROL_ACTION_MAX_LENGTH} ASCII characters: ${action}`,
+      );
+    }
+    if (RUNTIME_RUN_ACTIONS.has(action)) {
+      throw new Error(
+        `recipe.control action is runtime-reserved and must not be declared: ${action}`,
+      );
+    }
+    if (seen.has(action)) {
+      throw new Error(`duplicate recipe.control action: ${action}`);
+    }
+    seen.add(action);
+    actions.push(action);
+  }
+  return actions;
+}
+
+export function assertRecipeHasNoMailbox(recipe: Record<string, unknown>): void {
+  if (Object.hasOwn(recipe, "mailbox")) {
+    throw new Error(
+      "recipe.mailbox was removed; replace it with control: [\"action\"] for actor-local inputs and emit Trace events for outputs",
+    );
+  }
+}

package/node_modules/@llblab/pi-actors/lib/recipes-context.ts

@@ -0,0 +1,268 @@
+/**
+ * Recipe context contracts and prompt assembly.
+ * Zones: live session resolution, async runner prompt context, recipe provenance, LLM child launches
+ * Owns the immutable live Recipe environment and compact actor context appended to child-agent prompts.
+ */
+
+import { createHash } from "node:crypto";
+import { writeFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+
+import type { CommandTemplateActorRecipeContext } from "./command-templates.ts";
+import * as RecipesReferences from "./recipes-references.ts";
+import type { TemplateRecipeContextRecord } from "./recipes-references.ts";
+
+export interface RecipeResolutionContext {
+  readonly activeSkills: RecipesReferences.ActiveSkillRecipeContext;
+  readonly cwd: string;
+  readonly generation: string;
+  readonly sessionId: string;
+}
+
+export function createRecipeResolutionContext(
+  sessionId: string,
+  cwd: string,
+  activeSkills: RecipesReferences.ActiveSkillRecipeContext,
+): RecipeResolutionContext {
+  const normalizedSessionId = sessionId.trim();
+  if (!normalizedSessionId) throw new Error("Recipe resolution session id is required.");
+  const normalizedCwd = resolve(cwd);
+  const generation = createHash("sha256")
+    .update(
+      JSON.stringify({
+        activeSkills: RecipesReferences.getActiveSkillRecipeNamespaces(activeSkills),
+        cwd: normalizedCwd,
+        sessionId: normalizedSessionId,
+      }),
+    )
+    .digest("hex");
+  return Object.freeze({
+    activeSkills,
+    cwd: normalizedCwd,
+    generation,
+    sessionId: normalizedSessionId,
+  });
+}
+
+export function createEmptyRecipeResolutionContext(
+  sessionId: string,
+  cwd: string,
+): RecipeResolutionContext {
+  return createRecipeResolutionContext(
+    sessionId,
+    cwd,
+    RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT,
+  );
+}
+
+export interface MarkedRecipeContextRecord extends TemplateRecipeContextRecord {
+  you_are_here?: true;
+  you_are_here_path?: string;
+}
+
+function commandName(command: string): string {
+  return basename(command).toLowerCase();
+}
+
+function isPiCommand(command: string): boolean {
+  return commandName(command) === "pi";
+}
+
+const PI_PRINT_FLAGS = new Set(["-p", "--print"]);
+const PI_VALUE_OPTIONS = new Set([
+  "--api-key",
+  "--append-system-prompt",
+  "--exclude-tools",
+  "--extension",
+  "--fork",
+  "--mode",
+  "--model",
+  "--models",
+  "--name",
+  "--prompt-template",
+  "--provider",
+  "--session",
+  "--session-dir",
+  "--skill",
+  "--system-prompt",
+  "--theme",
+  "--thinking",
+  "--tools",
+]);
+const PI_SHORT_VALUE_OPTIONS = new Set(["-e", "-n", "-t", "-xt"]);
+
+function isPiPrintFlag(arg: string): boolean {
+  return PI_PRINT_FLAGS.has(arg);
+}
+
+function isPiOption(arg: string): boolean {
+  return arg.startsWith("-") && arg !== "-";
+}
+
+function piOptionConsumesNextArg(arg: string): boolean {
+  if (arg.includes("=")) return false;
+  return PI_VALUE_OPTIONS.has(arg) || PI_SHORT_VALUE_OPTIONS.has(arg);
+}
+
+function isPiFileArgument(arg: string): boolean {
+  return arg.startsWith("@") && arg.length > 1;
+}
+
+function findPiPrintPromptIndexes(args: string[]): number[] {
+  let printMode = false;
+  let positionalOnly = false;
+  const promptIndexes: number[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!positionalOnly && arg === "--") {
+      positionalOnly = true;
+      continue;
+    }
+    if (!positionalOnly && isPiPrintFlag(arg)) {
+      printMode = true;
+      continue;
+    }
+    if (!positionalOnly && isPiOption(arg)) {
+      if (piOptionConsumesNextArg(arg)) index += 1;
+      continue;
+    }
+    if (!printMode || isPiFileArgument(arg)) continue;
+    promptIndexes.push(index);
+  }
+  return promptIndexes;
+}
+
+export function findPiPrintPromptIndex(args: string[]): number | undefined {
+  return findPiPrintPromptIndexes(args).at(-1);
+}
+
+function matchesActorContext(
+  record: TemplateRecipeContextRecord,
+  context: CommandTemplateActorRecipeContext | undefined,
+): boolean {
+  if (!context) return record.role === "entry";
+  if (context.file && context.file === record.source_file) return true;
+  if (context.name && context.name === record.name) return true;
+  if (context.alias && context.alias === record.alias) return true;
+  return false;
+}
+
+function contextPath(
+  record: TemplateRecipeContextRecord,
+  context: CommandTemplateActorRecipeContext | undefined,
+): string {
+  return record.import_path.join(".") || context?.path || record.name;
+}
+
+export function markRecipeContextRecords(
+  records: TemplateRecipeContextRecord[],
+  context?: CommandTemplateActorRecipeContext,
+): MarkedRecipeContextRecord[] {
+  let marked = false;
+  const result = records.map((record) => {
+    if (marked || !matchesActorContext(record, context)) return record;
+    marked = true;
+    return {
+      ...record,
+      you_are_here: true as const,
+      you_are_here_path: contextPath(record, context),
+    };
+  });
+  return result;
+}
+
+export function formatRecipeContextJsonl(
+  records: TemplateRecipeContextRecord[],
+  context?: CommandTemplateActorRecipeContext,
+): string {
+  return markRecipeContextRecords(records, context)
+    .map(({ source_file: _sourceFile, ...record }) => JSON.stringify(record))
+    .join("\n");
+}
+
+export function buildRecipeContextPromptBlock(
+  records: TemplateRecipeContextRecord[],
+  context?: CommandTemplateActorRecipeContext,
+): string {
+  const jsonl = formatRecipeContextJsonl(records, context);
+  if (!jsonl) return "";
+  return [
+    "Actor recipe context bundle follows as JSONL.",
+    'Each line is one recipe/context record; `"you_are_here": true` marks the recipe node that launched this actor.',
+    "Use this as workflow/composition context, while the task prompt remains authoritative.",
+    "```jsonl",
+    jsonl,
+    "```",
+  ].join("\n");
+}
+
+export function appendRecipeContextToPiArgs(
+  command: string,
+  args: string[],
+  records: TemplateRecipeContextRecord[] | undefined,
+  context?: CommandTemplateActorRecipeContext,
+): string[] {
+  if (!records || records.length === 0 || !isPiCommand(command)) return args;
+  const promptIndex = findPiPrintPromptIndex(args);
+  if (promptIndex === undefined) return args;
+  const block = buildRecipeContextPromptBlock(records, context);
+  if (!block) return args;
+  const next = [...args];
+  next[promptIndex] = `${next[promptIndex]}\n\n${block}`;
+  return next;
+}
+
+export interface ManagedPiSessionArgs {
+  args: string[];
+  sessionDir?: string;
+}
+
+const PI_SESSION_POLICY_FLAGS = new Set([
+  "--fork",
+  "--no-session",
+  "--session",
+  "--session-dir",
+  "--session-id",
+]);
+
+export function attachPiSessionDir(
+  command: string,
+  args: string[],
+  sessionDir: string,
+): ManagedPiSessionArgs {
+  if (!isPiCommand(command) || findPiPrintPromptIndex(args) === undefined) {
+    return { args };
+  }
+  if (args.some((arg) => PI_SESSION_POLICY_FLAGS.has(arg))) return { args };
+  return { args: ["--session-dir", sessionDir, ...args], sessionDir };
+}
+
+export interface MaterializedPiPrintPromptArgs {
+  args: string[];
+  promptBytes?: number;
+  promptFile?: string;
+}
+
+export function materializePiPrintPromptArg(
+  command: string,
+  args: string[],
+  promptFile: string | (() => string),
+): MaterializedPiPrintPromptArgs {
+  if (!isPiCommand(command)) return { args };
+  const promptIndexes = findPiPrintPromptIndexes(args);
+  if (promptIndexes.length === 0) return { args };
+  const prompt = promptIndexes.map((index) => args[index]).join(" ");
+  const path = typeof promptFile === "function" ? promptFile() : promptFile;
+  writeFileSync(path, prompt, "utf8");
+  const promptIndexSet = new Set(promptIndexes);
+  const firstPromptIndex = promptIndexes[0];
+  const next = args.flatMap((arg, index) => {
+    if (index === firstPromptIndex) return [`@${path}`];
+    return promptIndexSet.has(index) ? [] : [arg];
+  });
+  return {
+    args: next,
+    promptBytes: Buffer.byteLength(prompt),
+    promptFile: path,
+  };
+}