@llblab/pi-actors 0.37.1 → 0.38.1

package/lib/model-context.ts

@@ -0,0 +1,359 @@
+/**
+ * Current model/thinking propagation helpers
+ * Zones: pi session context, recipe inheritance
+ * Owns current model/thinking extraction from Pi tool contexts and implicit command-template values.
+ */
+
+export interface CurrentModelContext {
+  currentThinking?: unknown;
+  getThinkingLevel?: () => unknown;
+  model?: {
+    id?: unknown;
+    modelId?: unknown;
+    provider?: unknown;
+  };
+  sessionManager?: {
+    getBranch?: () => unknown[];
+    getSessionId?: () => string;
+  };
+  thinkingLevel?: unknown;
+}
+
+export const CURRENT_MODEL_VALUE_KEY = "current_model";
+export const CURRENT_THINKING_VALUE_KEY = "current_thinking";
+
+export type CurrentPolicySource =
+  | "explicit"
+  | "inherited"
+  | "mixed"
+  | "unresolved"
+  | "unused";
+
+export interface CurrentPolicyAxisProvenance {
+  explicit_keys?: string[];
+  inherited_keys?: string[];
+  source: CurrentPolicySource;
+  unresolved_keys?: string[];
+  value?: string;
+}
+
+export interface CurrentPolicyProvenance {
+  model: CurrentPolicyAxisProvenance;
+  thinking: CurrentPolicyAxisProvenance;
+}
+
+export interface CurrentPolicyRecipeSummary {
+  model?: {
+    inherited_defaults?: string[];
+    public_args?: string[];
+  };
+  thinking?: {
+    inherited_defaults?: string[];
+    public_args?: string[];
+  };
+}
+
+export function getCurrentModelPattern(
+  ctx: CurrentModelContext | undefined,
+): string | undefined {
+  const provider = ctx?.model?.provider;
+  const id = ctx?.model?.id ?? ctx?.model?.modelId;
+  if (typeof provider !== "string" || !provider.trim()) return undefined;
+  if (typeof id !== "string" || !id.trim()) return undefined;
+  return `${provider.trim()}/${id.trim()}`;
+}
+
+function normalizeThinkingLevel(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function getSessionThinkingLevel(
+  ctx: CurrentModelContext | undefined,
+): string | undefined {
+  const branch = ctx?.sessionManager?.getBranch?.();
+  if (!Array.isArray(branch)) return undefined;
+  for (const entry of [...branch].reverse()) {
+    if (!entry || typeof entry !== "object") continue;
+    const record = entry as Record<string, unknown>;
+    if (record.type !== "thinking_level_change") continue;
+    const level = normalizeThinkingLevel(record.thinkingLevel);
+    if (level) return level;
+  }
+  return undefined;
+}
+
+export function getCurrentThinkingLevel(
+  ctx: CurrentModelContext | undefined,
+): string | undefined {
+  return (
+    normalizeThinkingLevel(ctx?.currentThinking) ??
+    normalizeThinkingLevel(ctx?.thinkingLevel) ??
+    normalizeThinkingLevel(ctx?.getThinkingLevel?.()) ??
+    getSessionThinkingLevel(ctx)
+  );
+}
+
+export function withCurrentModelValues<T extends Record<string, unknown>>(
+  values: T,
+  ctx: CurrentModelContext | undefined,
+): T & Record<string, unknown> {
+  const currentModel = getCurrentModelPattern(ctx);
+  const currentThinking = getCurrentThinkingLevel(ctx);
+  if (!currentModel && !currentThinking) return values;
+  return {
+    ...values,
+    ...(currentModel ? { [CURRENT_MODEL_VALUE_KEY]: currentModel } : {}),
+    ...(currentThinking
+      ? { [CURRENT_THINKING_VALUE_KEY]: currentThinking }
+      : {}),
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function stringReferencesPlaceholder(
+  value: string,
+  placeholder: string,
+): boolean {
+  return new RegExp(`\\{\\s*${placeholder}\\s*\\}`).test(value);
+}
+
+function modelPolicyKeyMatches(key: string): boolean {
+  return /(^|_)models?$/.test(key);
+}
+
+function thinkingPolicyKeyMatches(key: string): boolean {
+  return /(^|_)(thinking|thinking_level)$/.test(key);
+}
+
+function argName(token: unknown): string | undefined {
+  if (typeof token !== "string") return undefined;
+  return token.split(":")[0]?.trim() || undefined;
+}
+
+function collectPolicyDefaults(
+  value: unknown,
+  placeholder: string,
+  path = "template",
+  keys = new Set<string>(),
+): Set<string> {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) =>
+      collectPolicyDefaults(item, placeholder, `${path}[${index}]`, keys),
+    );
+    return keys;
+  }
+  if (!isRecord(value)) return keys;
+  for (const [key, child] of Object.entries(value)) {
+    if (key === "defaults" && isRecord(child)) {
+      for (const [defaultKey, defaultValue] of Object.entries(child)) {
+        if (
+          typeof defaultValue === "string" &&
+          stringReferencesPlaceholder(defaultValue, placeholder)
+        ) {
+          keys.add(defaultKey);
+        }
+      }
+      continue;
+    }
+    collectPolicyDefaults(child, placeholder, `${path}.${key}`, keys);
+  }
+  return keys;
+}
+
+function collectPolicyDirectRefs(
+  value: unknown,
+  placeholder: string,
+  path = "template",
+  refs = new Set<string>(),
+): Set<string> {
+  if (typeof value === "string") {
+    if (stringReferencesPlaceholder(value, placeholder)) refs.add(path);
+    return refs;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) =>
+      collectPolicyDirectRefs(item, placeholder, `${path}[${index}]`, refs),
+    );
+    return refs;
+  }
+  if (!isRecord(value)) return refs;
+  for (const [key, child] of Object.entries(value)) {
+    if (key === "defaults") continue;
+    collectPolicyDirectRefs(child, placeholder, `${path}.${key}`, refs);
+  }
+  return refs;
+}
+
+function summarizePolicyAxis(input: {
+  currentValue?: string;
+  directRefKey: string;
+  explicitKeyMatches: (key: string) => boolean;
+  explicitValues: Record<string, unknown>;
+  inheritedDefaultKeys: Set<string>;
+  directRefs: Set<string>;
+}): CurrentPolicyAxisProvenance {
+  const explicitKeys = Object.keys(input.explicitValues)
+    .filter(
+      (key) =>
+        key !== CURRENT_MODEL_VALUE_KEY &&
+        key !== CURRENT_THINKING_VALUE_KEY &&
+        input.explicitKeyMatches(key),
+    )
+    .sort();
+  const inheritedKeys = [...input.inheritedDefaultKeys]
+    .filter((key) => !Object.hasOwn(input.explicitValues, key))
+    .sort();
+  const directRefs = [...input.directRefs].length > 0 ? [input.directRefKey] : [];
+  const inheritedOrDirect = [...new Set([...inheritedKeys, ...directRefs])].sort();
+  const unresolvedKeys = input.currentValue ? [] : inheritedOrDirect;
+  const inheritedResolvedKeys = input.currentValue ? inheritedOrDirect : [];
+  const hasExplicit = explicitKeys.length > 0;
+  const hasInherited = inheritedResolvedKeys.length > 0;
+  const source: CurrentPolicySource = unresolvedKeys.length
+    ? "unresolved"
+    : hasExplicit && hasInherited
+      ? "mixed"
+      : hasExplicit
+        ? "explicit"
+        : hasInherited
+          ? "inherited"
+          : "unused";
+  const explicitValue = explicitKeys
+    .map((key) => input.explicitValues[key])
+    .find((value) => typeof value === "string" && value.trim());
+  const value = hasInherited
+    ? input.currentValue
+    : typeof explicitValue === "string"
+      ? explicitValue
+      : undefined;
+  return {
+    ...(explicitKeys.length ? { explicit_keys: explicitKeys } : {}),
+    ...(inheritedResolvedKeys.length
+      ? { inherited_keys: inheritedResolvedKeys }
+      : {}),
+    source,
+    ...(unresolvedKeys.length ? { unresolved_keys: unresolvedKeys } : {}),
+    ...(value ? { value } : {}),
+  };
+}
+
+function collectPolicyDefaultsAcross(
+  items: unknown[],
+  placeholder: string,
+): Set<string> {
+  return items.reduce<Set<string>>(
+    (keys, item) => collectPolicyDefaults(item, placeholder, "template", keys),
+    new Set<string>(),
+  );
+}
+
+function collectPolicyDirectRefsAcross(
+  items: unknown[],
+  placeholder: string,
+): Set<string> {
+  return items.reduce<Set<string>>(
+    (refs, item) => collectPolicyDirectRefs(item, placeholder, "template", refs),
+    new Set<string>(),
+  );
+}
+
+export function describeCurrentPolicyProvenance(input: {
+  defaults?: Record<string, unknown>;
+  template: unknown;
+  values?: Record<string, unknown>;
+}): CurrentPolicyProvenance {
+  const explicitValues = input.values ?? {};
+  const defaultsEnvelope = input.defaults ? { defaults: input.defaults } : {};
+  const templateAndDefaults = [defaultsEnvelope, input.template];
+  return {
+    model: summarizePolicyAxis({
+      currentValue:
+        typeof explicitValues[CURRENT_MODEL_VALUE_KEY] === "string"
+          ? String(explicitValues[CURRENT_MODEL_VALUE_KEY])
+          : undefined,
+      directRefKey: CURRENT_MODEL_VALUE_KEY,
+      directRefs: collectPolicyDirectRefsAcross(
+        templateAndDefaults,
+        "current_model",
+      ),
+      explicitKeyMatches: modelPolicyKeyMatches,
+      explicitValues,
+      inheritedDefaultKeys: collectPolicyDefaultsAcross(
+        templateAndDefaults,
+        "current_model",
+      ),
+    }),
+    thinking: summarizePolicyAxis({
+      currentValue:
+        typeof explicitValues[CURRENT_THINKING_VALUE_KEY] === "string"
+          ? String(explicitValues[CURRENT_THINKING_VALUE_KEY])
+          : undefined,
+      directRefKey: CURRENT_THINKING_VALUE_KEY,
+      directRefs: collectPolicyDirectRefsAcross(
+        templateAndDefaults,
+        "current_thinking",
+      ),
+      explicitKeyMatches: thinkingPolicyKeyMatches,
+      explicitValues,
+      inheritedDefaultKeys: collectPolicyDefaultsAcross(
+        templateAndDefaults,
+        "current_thinking",
+      ),
+    }),
+  };
+}
+
+function publicPolicyArgs(
+  args: unknown,
+  matches: (key: string) => boolean,
+): string[] {
+  return Array.isArray(args)
+    ? args
+        .map(argName)
+        .filter((key): key is string => Boolean(key && matches(key)))
+        .sort()
+    : [];
+}
+
+function nonEmptyAxisRecipeSummary(
+  inheritedDefaults: string[],
+  publicArgs: string[],
+): { inherited_defaults?: string[]; public_args?: string[] } | undefined {
+  if (inheritedDefaults.length === 0 && publicArgs.length === 0)
+    return undefined;
+  return {
+    ...(inheritedDefaults.length
+      ? { inherited_defaults: inheritedDefaults }
+      : {}),
+    ...(publicArgs.length ? { public_args: publicArgs } : {}),
+  };
+}
+
+export function describeRecipeCurrentPolicy(input: {
+  args?: unknown;
+  defaults?: Record<string, unknown>;
+  template: unknown;
+}): CurrentPolicyRecipeSummary | undefined {
+  const templateAndDefaults = [
+    input.defaults ? { defaults: input.defaults } : {},
+    input.template,
+  ];
+  const model = nonEmptyAxisRecipeSummary(
+    [...collectPolicyDefaultsAcross(templateAndDefaults, "current_model")].sort(),
+    publicPolicyArgs(input.args, modelPolicyKeyMatches),
+  );
+  const thinking = nonEmptyAxisRecipeSummary(
+    [
+      ...collectPolicyDefaultsAcross(templateAndDefaults, "current_thinking"),
+    ].sort(),
+    publicPolicyArgs(input.args, thinkingPolicyKeyMatches),
+  );
+  if (!model && !thinking) return undefined;
+  return {
+    ...(model ? { model } : {}),
+    ...(thinking ? { thinking } : {}),
+  };
+}

package/lib/observability.ts

@@ -42,6 +42,7 @@ export interface RunObservation {
   ownerId?: string;
   artifacts?: Record<string, string>;
   launchSource?: AsyncRuns.AsyncRunLaunchSource;
+  modelPolicy?: Record<string, unknown>;
   recipeFile?: string;
   terminalHandled?: boolean;
   retireWhen?: string;
@@ -247,6 +248,7 @@ export interface RunTransition {
   stateDir?: string;
   artifacts?: Record<string, string>;
   launchSource?: AsyncRuns.AsyncRunLaunchSource;
+  modelPolicy?: Record<string, unknown>;
   recipeFile?: string;
   terminalHandled?: boolean;
   to: RunObservedStatus;
@@ -352,6 +354,11 @@ function observeRun(stateDir: string): RunObservation | undefined {
       ...(status.launch_source === "spawn" || status.launch_source === "tool"
         ? { launchSource: status.launch_source }
         : {}),
+      ...(status.model_policy &&
+      typeof status.model_policy === "object" &&
+      !Array.isArray(status.model_policy)
+        ? { modelPolicy: status.model_policy as Record<string, unknown> }
+        : {}),
       ...(typeof status.recipe_file === "string"
         ? { recipeFile: status.recipe_file }
         : {}),
@@ -747,6 +754,7 @@ export function detectRunTransitions(
         ...(run.stateDir ? { stateDir: run.stateDir } : {}),
         ...(run.artifacts ? { artifacts: run.artifacts } : {}),
         ...(run.launchSource ? { launchSource: run.launchSource } : {}),
+        ...(run.modelPolicy ? { modelPolicy: run.modelPolicy } : {}),
         ...(run.recipeFile ? { recipeFile: run.recipeFile } : {}),
         ...(run.terminalHandled ? { terminalHandled: true } : {}),
         to: run.status,
@@ -1021,6 +1029,26 @@ function formatRecipePersistenceSuggestion(transition: RunTransition): string {
   return `\nAgent note: this actor was spawned directly and completed successfully. If this pattern fits this machine's recurring workflow, ask the operator whether to save it as a durable recipe/tool under ~/.pi/agent/recipes with register_tool. Do not auto-save without confirmation.`;
 }
 
+function formatTransitionPolicy(transition: RunTransition): string {
+  if (!transition.modelPolicy) return "";
+  const axis = (key: "model" | "thinking", label: string): string | undefined => {
+    const value = transition.modelPolicy?.[key];
+    if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+    const record = value as Record<string, unknown>;
+    const source = typeof record.source === "string" ? record.source : "unused";
+    if (source === "unused") return undefined;
+    const renderedValue =
+      typeof record.value === "string" && record.value.trim()
+        ? ` (${record.value.trim()})`
+        : "";
+    return `${label}: ${source}${renderedValue}`;
+  };
+  const lines = [axis("model", "Model"), axis("thinking", "Thinking")].filter(
+    (line): line is string => Boolean(line),
+  );
+  return lines.length ? `\nPolicy:\n- ${lines.join("\n- ")}` : "";
+}
+
 function formatTransitionNextActions(transition: RunTransition): string {
   const actions = [
     `inspect target=run:${transition.run} view=status`,
@@ -1036,16 +1064,17 @@ export function formatRunTransitionMessage(transition: RunTransition): string {
   const artifacts = formatNamedArtifacts(transition.artifacts);
   const runFiles = formatRunFileList(getRunArtifacts(transition));
   const persistenceSuggestion = formatRecipePersistenceSuggestion(transition);
+  const policy = formatTransitionPolicy(transition);
   const nextActions = formatTransitionNextActions(transition);
   if (transition.to === "done")
-    return `Run ${transition.run} completed successfully.${artifacts}${runFiles}${nextActions}${persistenceSuggestion}`;
+    return `Run ${transition.run} completed successfully.${policy}${artifacts}${runFiles}${nextActions}${persistenceSuggestion}`;
   if (transition.to === "failed")
-    return `Run ${transition.run} failed.${artifacts}${runFiles}${nextActions}`;
+    return `Run ${transition.run} failed.${policy}${artifacts}${runFiles}${nextActions}`;
   if (transition.to === "cancelled")
-    return `Run ${transition.run} was cancelled.${nextActions}`;
+    return `Run ${transition.run} was cancelled.${policy}${nextActions}`;
   if (transition.to === "killed")
-    return `Run ${transition.run} was force-killed.${nextActions}`;
+    return `Run ${transition.run} was force-killed.${policy}${nextActions}`;
   if (transition.to === "exited")
-    return `Run ${transition.run} exited before writing a result.${nextActions}`;
-  return `Run ${transition.run} finished with status ${transition.to}.${nextActions}`;
+    return `Run ${transition.run} exited before writing a result.${policy}${nextActions}`;
+  return `Run ${transition.run} finished with status ${transition.to}.${policy}${nextActions}`;
 }

package/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/lib/prompts.ts

@@ -22,7 +22,7 @@ export const REGISTER_TOOL_GUIDELINES = [
 export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.
 - Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.
-- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, when, timeout, delay, retry, failure, recover, repeat, output.
+- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, output.
 - Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.
 - ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.
 - Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.
@@ -31,7 +31,7 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.
 - Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.
 - Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
-- Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; long fanout = parent async recipe wrapping template(parallel:true) and imports.
+- Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.
 - For any non-trivial actor use or pi-actors change, read the bundled actors skill first; for deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;
 
 export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {

package/lib/recipes-context.ts

@@ -4,6 +4,7 @@
  * Owns compact actor recipe context records appended to child-agent prompts.
  */
 
+import { writeFileSync } from "node:fs";
 import { basename } from "node:path";
 
 import type { CommandTemplateActorRecipeContext } from "./command-templates.ts";
@@ -62,7 +63,7 @@ function isPiFileArgument(arg: string): boolean {
   return arg.startsWith("@") && arg.length > 1;
 }
 
-function findPrintPromptIndex(args: string[]): number | undefined {
+export function findPiPrintPromptIndex(args: string[]): number | undefined {
   let printMode = false;
   let positionalOnly = false;
   let promptIndex: number | undefined;
@@ -153,7 +154,7 @@ export function appendRecipeContextToPiArgs(
   context?: CommandTemplateActorRecipeContext,
 ): string[] {
   if (!records || records.length === 0 || !isPiCommand(command)) return args;
-  const promptIndex = findPrintPromptIndex(args);
+  const promptIndex = findPiPrintPromptIndex(args);
   if (promptIndex === undefined) return args;
   const block = buildRecipeContextPromptBlock(records, context);
   if (!block) return args;
@@ -161,3 +162,29 @@ export function appendRecipeContextToPiArgs(
   next[promptIndex] = `${next[promptIndex]}\n\n${block}`;
   return next;
 }
+
+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 promptIndex = findPiPrintPromptIndex(args);
+  if (promptIndex === undefined) return { args };
+  const prompt = args[promptIndex];
+  const path = typeof promptFile === "function" ? promptFile() : promptFile;
+  writeFileSync(path, prompt, "utf8");
+  const next = [...args];
+  next[promptIndex] = `@${path}`;
+  return {
+    args: next,
+    promptBytes: Buffer.byteLength(prompt),
+    promptFile: path,
+  };
+}