@llblab/pi-actors 0.37.1 → 0.38.1

package/dist/lib/model-context.js

@@ -0,0 +1,220 @@
+/**
+ * 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 const CURRENT_MODEL_VALUE_KEY = "current_model";
+export const CURRENT_THINKING_VALUE_KEY = "current_thinking";
+export function getCurrentModelPattern(ctx) {
+    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) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function getSessionThinkingLevel(ctx) {
+    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;
+        if (record.type !== "thinking_level_change")
+            continue;
+        const level = normalizeThinkingLevel(record.thinkingLevel);
+        if (level)
+            return level;
+    }
+    return undefined;
+}
+export function getCurrentThinkingLevel(ctx) {
+    return (normalizeThinkingLevel(ctx?.currentThinking) ??
+        normalizeThinkingLevel(ctx?.thinkingLevel) ??
+        normalizeThinkingLevel(ctx?.getThinkingLevel?.()) ??
+        getSessionThinkingLevel(ctx));
+}
+export function withCurrentModelValues(values, ctx) {
+    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) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function stringReferencesPlaceholder(value, placeholder) {
+    return new RegExp(`\\{\\s*${placeholder}\\s*\\}`).test(value);
+}
+function modelPolicyKeyMatches(key) {
+    return /(^|_)models?$/.test(key);
+}
+function thinkingPolicyKeyMatches(key) {
+    return /(^|_)(thinking|thinking_level)$/.test(key);
+}
+function argName(token) {
+    if (typeof token !== "string")
+        return undefined;
+    return token.split(":")[0]?.trim() || undefined;
+}
+function collectPolicyDefaults(value, placeholder, path = "template", keys = new Set()) {
+    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, placeholder, path = "template", refs = new Set()) {
+    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) {
+    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 = 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, placeholder) {
+    return items.reduce((keys, item) => collectPolicyDefaults(item, placeholder, "template", keys), new Set());
+}
+function collectPolicyDirectRefsAcross(items, placeholder) {
+    return items.reduce((refs, item) => collectPolicyDirectRefs(item, placeholder, "template", refs), new Set());
+}
+export function describeCurrentPolicyProvenance(input) {
+    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, matches) {
+    return Array.isArray(args)
+        ? args
+            .map(argName)
+            .filter((key) => Boolean(key && matches(key)))
+            .sort()
+        : [];
+}
+function nonEmptyAxisRecipeSummary(inheritedDefaults, publicArgs) {
+    if (inheritedDefaults.length === 0 && publicArgs.length === 0)
+        return undefined;
+    return {
+        ...(inheritedDefaults.length
+            ? { inherited_defaults: inheritedDefaults }
+            : {}),
+        ...(publicArgs.length ? { public_args: publicArgs } : {}),
+    };
+}
+export function describeRecipeCurrentPolicy(input) {
+    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/dist/lib/observability.d.ts

@@ -15,6 +15,7 @@ export interface RunObservation {
     ownerId?: string;
     artifacts?: Record<string, string>;
     launchSource?: AsyncRuns.AsyncRunLaunchSource;
+    modelPolicy?: Record<string, unknown>;
     recipeFile?: string;
     terminalHandled?: boolean;
     retireWhen?: string;
@@ -95,6 +96,7 @@ export interface RunTransition {
     stateDir?: string;
     artifacts?: Record<string, string>;
     launchSource?: AsyncRuns.AsyncRunLaunchSource;
+    modelPolicy?: Record<string, unknown>;
     recipeFile?: string;
     terminalHandled?: boolean;
     to: RunObservedStatus;

package/dist/lib/observability.js

@@ -185,6 +185,11 @@ function observeRun(stateDir) {
             ...(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 }
+                : {}),
             ...(typeof status.recipe_file === "string"
                 ? { recipeFile: status.recipe_file }
                 : {}),
@@ -496,6 +501,7 @@ export function detectRunTransitions(previous, summary) {
                 ...(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,
@@ -721,6 +727,25 @@ function formatRecipePersistenceSuggestion(transition) {
     }
     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) {
+    if (!transition.modelPolicy)
+        return "";
+    const axis = (key, label) => {
+        const value = transition.modelPolicy?.[key];
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return undefined;
+        const record = value;
+        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) => Boolean(line));
+    return lines.length ? `\nPolicy:\n- ${lines.join("\n- ")}` : "";
+}
 function formatTransitionNextActions(transition) {
     const actions = [
         `inspect target=run:${transition.run} view=status`,
@@ -735,16 +760,17 @@ export function formatRunTransitionMessage(transition) {
     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/dist/lib/preflight-diagnostics.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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;
+}
+export declare function extractReviewPreflightStage(promptText: string | undefined): string | undefined;
+export declare function classifyReviewPreflightError(text: string, killed?: boolean): ReviewPreflightErrorClass;
+export declare function buildReviewPreflightDiagnostic(input: ReviewPreflightDiagnosticInput): ReviewPreflightDiagnostic | undefined;
+export declare function formatReviewPreflightDiagnostic(diagnostic: ReviewPreflightDiagnostic): string;

package/dist/lib/preflight-diagnostics.js

@@ -0,0 +1,86 @@
+/**
+ * Review preflight diagnostics
+ * Zones: recipe diagnostics, subagent launch policy
+ * Owns compact classification of failed review-pipeline preflight commands.
+ */
+const PREFLIGHT_STAGE_PATTERN = /Preflight check for stage\s+([^\s.]+)\.?/i;
+function getFlagValue(args, flag) {
+    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) {
+    if (args.includes("--no-tools"))
+        return "<tool-policy>";
+    return getFlagValue(args, "--tools") ?? "<tool-policy>";
+}
+export function extractReviewPreflightStage(promptText) {
+    return promptText?.match(PREFLIGHT_STAGE_PATTERN)?.[1];
+}
+export function classifyReviewPreflightError(text, killed = false) {
+    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) {
+    if (stage === "reviewer" ||
+        stage === "verifier" ||
+        stage === "merger" ||
+        stage === "judge") {
+        return `${stage}_model`;
+    }
+    return "model";
+}
+function buildSuggestedOverrideArgs(stage, args) {
+    return `${getStageModelArg(stage)}=<working-model> thinking=<supported-level> tools=${getToolPolicy(args)}`;
+}
+export function buildReviewPreflightDiagnostic(input) {
+    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) {
+    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/dist/lib/prompts.d.ts

@@ -6,7 +6,7 @@
 export declare const REGISTER_TOOL_DESCRIPTION: string;
 export declare const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent command templates as agent-callable tools";
 export declare const REGISTER_TOOL_GUIDELINES: string[];
-export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, when, timeout, delay, retry, failure, recover, repeat, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- 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.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.\n- 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.\n- 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.\n- 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 declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- 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.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- 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.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.\n- 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.\n- 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.\n- 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 declare const REGISTER_TOOL_PARAM_DESCRIPTIONS: {
     readonly name: "Tool name in snake_case (e.g., 'transcribe')";
     readonly description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.";

package/dist/lib/prompts.js

@@ -16,7 +16,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.
@@ -25,7 +25,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 = {
     name: "Tool name in snake_case (e.g., 'transcribe')",

package/dist/lib/recipes-context.d.ts

@@ -9,7 +9,14 @@ export interface MarkedRecipeContextRecord extends TemplateRecipeContextRecord {
     you_are_here?: true;
     you_are_here_path?: string;
 }
+export declare function findPiPrintPromptIndex(args: string[]): number | undefined;
 export declare function markRecipeContextRecords(records: TemplateRecipeContextRecord[], context?: CommandTemplateActorRecipeContext): MarkedRecipeContextRecord[];
 export declare function formatRecipeContextJsonl(records: TemplateRecipeContextRecord[], context?: CommandTemplateActorRecipeContext): string;
 export declare function buildRecipeContextPromptBlock(records: TemplateRecipeContextRecord[], context?: CommandTemplateActorRecipeContext): string;
 export declare function appendRecipeContextToPiArgs(command: string, args: string[], records: TemplateRecipeContextRecord[] | undefined, context?: CommandTemplateActorRecipeContext): string[];
+export interface MaterializedPiPrintPromptArgs {
+    args: string[];
+    promptBytes?: number;
+    promptFile?: string;
+}
+export declare function materializePiPrintPromptArg(command: string, args: string[], promptFile: string | (() => string)): MaterializedPiPrintPromptArgs;

package/dist/lib/recipes-context.js

@@ -3,6 +3,7 @@
  * Zones: async runner prompt context, recipe provenance, LLM child launches
  * Owns compact actor recipe context records appended to child-agent prompts.
  */
+import { writeFileSync } from "node:fs";
 import { basename } from "node:path";
 function commandName(command) {
     return basename(command).toLowerCase();
@@ -46,7 +47,7 @@ function piOptionConsumesNextArg(arg) {
 function isPiFileArgument(arg) {
     return arg.startsWith("@") && arg.length > 1;
 }
-function findPrintPromptIndex(args) {
+export function findPiPrintPromptIndex(args) {
     let printMode = false;
     let positionalOnly = false;
     let promptIndex;
@@ -120,7 +121,7 @@ export function buildRecipeContextPromptBlock(records, context) {
 export function appendRecipeContextToPiArgs(command, args, records, context) {
     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);
@@ -130,3 +131,20 @@ export function appendRecipeContextToPiArgs(command, args, records, context) {
     next[promptIndex] = `${next[promptIndex]}\n\n${block}`;
     return next;
 }
+export function materializePiPrintPromptArg(command, args, promptFile) {
+    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,
+    };
+}

package/dist/lib/recipes-discovery.d.ts

@@ -45,6 +45,7 @@ export interface RecipesDiscoverySource {
     defaultTool?: boolean;
     mutableUsage?: boolean;
 }
+export declare function hasBroadWindowsWriteAcl(icaclsOutput: string): boolean;
 export declare function discoverRecipeSources(sources: RecipesDiscoverySource[]): RecipesDiscoveryResult;
 export declare function discoverRecipes(roots: string[]): RecipesDiscoveryResult;
 export declare function createRecipeIntegrityManifest(result: RecipesDiscoveryResult): RecipeIntegrityManifestEntry[];

package/dist/lib/recipes-discovery.js

@@ -3,10 +3,12 @@
  * Zones: recipe discovery, tool exposure, registry diagnostics
  * Owns filename identity discovery across prioritized recipe roots
  */
+import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import * as CommandTemplates from "./command-templates.js";
+import * as ModelContext from "./model-context.js";
 import * as RecipesReferences from "./recipes-references.js";
 import * as Schema from "./schema.js";
 function assertToolSafeRepeatConfig(config, argTypes, defaults) {
@@ -139,6 +141,50 @@ function filesForSource(source) {
         }))
         : [];
 }
+const WINDOWS_BROAD_WRITE_PRINCIPALS = [
+    "Everyone",
+    "BUILTIN\\Users",
+    "Authenticated Users",
+    "S-1-1-0",
+    "S-1-5-11",
+    "S-1-5-32-545",
+];
+const WINDOWS_WRITE_ACL_PATTERN = /\((?:[^)]*,)?(?:F|M|W|WD|AD|DC|GA|GW)(?:,[^)]*)?\)/i;
+export function hasBroadWindowsWriteAcl(icaclsOutput) {
+    return icaclsOutput
+        .split(/\r?\n/)
+        .some((line) => WINDOWS_BROAD_WRITE_PRINCIPALS.some((principal) => line.includes(principal)) && WINDOWS_WRITE_ACL_PATTERN.test(line));
+}
+function getWindowsRecipeRootDiagnostics(root) {
+    try {
+        const output = execFileSync("icacls", [root], {
+            encoding: "utf8",
+            windowsHide: true,
+            timeout: 5000,
+        });
+        if (!hasBroadWindowsWriteAcl(output))
+            return [];
+        return [
+            `Recipe root grants write access to broad Windows principals; review ACLs: ${root}`,
+        ];
+    }
+    catch (error) {
+        return [
+            `Failed to inspect Windows ACL for recipe root ${root}: ${error instanceof Error ? error.message : String(error)}`,
+        ];
+    }
+}
+function getPosixRecipeRootDiagnostics(root) {
+    const diagnostics = [];
+    const stat = statSync(root);
+    if ((stat.mode & 0o002) !== 0) {
+        diagnostics.push(`Recipe root is world-writable; review permissions: ${root}`);
+    }
+    if ((stat.mode & 0o020) !== 0) {
+        diagnostics.push(`Recipe root is group-writable; review ownership and permissions: ${root}`);
+    }
+    return diagnostics;
+}
 function getRecipeRootDiagnostics(sources) {
     const diagnostics = [];
     const roots = new Set(sources
@@ -148,13 +194,9 @@ function getRecipeRootDiagnostics(sources) {
         try {
             if (!existsSync(root))
                 continue;
-            const stat = statSync(root);
-            if ((stat.mode & 0o002) !== 0) {
-                diagnostics.push(`Recipe root is world-writable; review permissions: ${root}`);
-            }
-            if ((stat.mode & 0o020) !== 0) {
-                diagnostics.push(`Recipe root is group-writable; review ownership and permissions: ${root}`);
-            }
+            diagnostics.push(...(process.platform === "win32"
+                ? getWindowsRecipeRootDiagnostics(root)
+                : getPosixRecipeRootDiagnostics(root)));
         }
         catch (error) {
             diagnostics.push(`Failed to inspect recipe root ${root}: ${error instanceof Error ? error.message : String(error)}`);
@@ -524,6 +566,20 @@ export function summarizeDiscovery(result) {
             invalid: entry.invalid,
             shadows: entry.shadows,
             ...(entry.riskLabels.length ? { risk_labels: entry.riskLabels } : {}),
+            ...(entry.config &&
+                ModelContext.describeRecipeCurrentPolicy({
+                    args: entry.config.args,
+                    defaults: entry.config.defaults,
+                    template: entry.config.template,
+                })
+                ? {
+                    current_policy: ModelContext.describeRecipeCurrentPolicy({
+                        args: entry.config.args,
+                        defaults: entry.config.defaults,
+                        template: entry.config.template,
+                    }),
+                }
+                : {}),
             ...(entry.config?.imports ? { imports: entry.config.imports } : {}),
             ...(recipeUsage(entry.config)
                 ? { usage: recipeUsage(entry.config) }

package/dist/lib/recipes-references.d.ts

@@ -33,6 +33,8 @@ export interface TemplateRecipeDefinition {
     args?: string[];
     defaults?: Record<string, unknown>;
     parallel?: boolean;
+    concurrency?: number | string;
+    min_successful?: number | string;
     label?: string;
     when?: boolean | string;
     timeout?: number | string;

package/dist/lib/recipes-references.js

@@ -135,6 +135,8 @@ function getRecipeCommandTemplate(raw) {
         "args",
         "defaults",
         "parallel",
+        "concurrency",
+        "min_successful",
         "label",
         "when",
         "timeout",
@@ -711,6 +713,14 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
         ...(typeof substituted.parallel === "boolean"
             ? { parallel: substituted.parallel }
             : {}),
+        ...(typeof substituted.concurrency === "number" ||
+            typeof substituted.concurrency === "string"
+            ? { concurrency: substituted.concurrency }
+            : {}),
+        ...(typeof substituted.min_successful === "number" ||
+            typeof substituted.min_successful === "string"
+            ? { min_successful: substituted.min_successful }
+            : {}),
         ...(typeof substituted.label === "string"
             ? { label: substituted.label }
             : {}),