@wichayutdew/pi-workflows 3.5.0 → 3.6.0

package/dist/index.js

@@ -695,6 +695,7 @@ function parseWorkflowStep(value, stepId, path, errors) {
     "title",
     "prompt",
     "agent",
+    "maxToolCalls",
     "permissions",
     "requires",
     "transitions",
@@ -707,6 +708,10 @@ function parseWorkflowStep(value, stepId, path, errors) {
     pattern: AGENT_PROFILE_NAME_PATTERN
   });
   const agent = agentName ? { name: agentName } : undefined;
+  const maxToolCalls = value.maxToolCalls === undefined ? undefined : readInteger(value.maxToolCalls, 1, `${path}.maxToolCalls`, errors, {
+    min: 1,
+    max: 1e5
+  });
   const permissions = parsePermissions(value.permissions, `${path}.permissions`, errors);
   const requires = parseRequirements(value.requires, permissions, `${path}.requires`, errors);
   const transitions = parseTransitions(value.transitions, `${path}.transitions`, errors);
@@ -739,6 +744,7 @@ function parseWorkflowStep(value, stepId, path, errors) {
     title,
     prompt,
     ...agent ? { agent } : {},
+    ...maxToolCalls === undefined ? {} : { maxToolCalls },
     permissions,
     requires,
     transitions,
@@ -6393,6 +6399,9 @@ var POLICY_KEYS = new Set([
   "outcomes",
   "pauseOutcomes",
   "summaryMaxChars",
+  "maxToolCalls",
+  "handoffReserve",
+  "totalToolCalls",
   "gateSubmitOutcome",
   "workspace"
 ]);
@@ -6411,6 +6420,29 @@ var rejectUnknownProperties = (value) => {
     throw new Error(`child policy has unknown property "${unknownKey}"`);
   }
 };
+var parseToolBudget = (value) => {
+  const fields2 = [
+    value.maxToolCalls,
+    value.handoffReserve,
+    value.totalToolCalls
+  ];
+  if (fields2.every((field) => field === undefined))
+    return {};
+  if (fields2.some((field) => field === undefined)) {
+    throw new Error("child policy tool budget fields must be provided together");
+  }
+  const [maxToolCalls, handoffReserve, totalToolCalls] = fields2;
+  if (typeof maxToolCalls !== "number" || !Number.isInteger(maxToolCalls) || maxToolCalls < 1 || maxToolCalls > 1e5) {
+    throw new Error("child policy maxToolCalls is invalid");
+  }
+  if (handoffReserve !== 2) {
+    throw new Error("child policy handoffReserve is invalid");
+  }
+  if (typeof totalToolCalls !== "number" || !Number.isInteger(totalToolCalls) || totalToolCalls !== maxToolCalls + handoffReserve) {
+    throw new Error("child policy totalToolCalls is invalid");
+  }
+  return { maxToolCalls, handoffReserve, totalToolCalls };
+};
 var parseIdentityAndPaths = (value, environment) => {
   const requestId = requiredString(value, "requestId");
   const agent = requiredString(value, "agent");
@@ -6467,7 +6499,8 @@ var parseChildPolicy = (value, environment = DEFAULT_CHILD_POLICY_ENVIRONMENT) =
   rejectUnknownProperties(value);
   return {
     ...parseIdentityAndPaths(value, environment),
-    ...parseChildPolicySections(value)
+    ...parseChildPolicySections(value),
+    ...parseToolBudget(value)
   };
 };
 
@@ -6564,6 +6597,7 @@ var parseDelegatedStepResult = (value, policy) => {
   }
 };
 // src/harness/delegation-plan.ts
+var HANDOFF_RESERVE = 2;
 function createDelegationPlan(input, dependencies) {
   const { workflow, run, step, latestContext } = input;
   const agent = step.agent?.name;
@@ -6658,6 +6692,11 @@ function createDelegationPlan(input, dependencies) {
   const workspace = dependencies.createDelegationWorkspace();
   const outcomes = allowedOutcomes(workflow, run);
   const outcomeSet = new Set(outcomes);
+  const toolBudget = step.maxToolCalls === undefined ? {} : {
+    maxToolCalls: step.maxToolCalls,
+    handoffReserve: HANDOFF_RESERVE,
+    totalToolCalls: step.maxToolCalls + HANDOFF_RESERVE
+  };
   const policyDigest = digest({
     version: 1,
     requestId,
@@ -6670,6 +6709,7 @@ function createDelegationPlan(input, dependencies) {
     resultPath: workspace.resultPath,
     permissions: step.permissions,
     outcomes,
+    ...toolBudget,
     ...step.workspace ? { workspace: step.workspace } : {}
   });
   const policy = {
@@ -6689,6 +6729,7 @@ function createDelegationPlan(input, dependencies) {
     outcomes,
     pauseOutcomes: Object.entries(step.transitions).filter(([outcome, target]) => target === "$pause" && outcomeSet.has(outcome)).map(([outcome]) => outcome),
     summaryMaxChars: workflow.definition.summaryMaxChars,
+    ...toolBudget,
     ...step.gate ? { gateSubmitOutcome: step.gate.submitOutcome } : {},
     ...step.workspace ? { workspace: structuredClone(step.workspace) } : {}
   };
@@ -7951,6 +7992,24 @@ var COMPLETION_REPAIR_PROMPT = [
   "Call `structured_output` exactly once, alone, with one configured outcome and the required summary, artifact, and workspace fields."
 ].join(`
 `);
+var toolBudgetWarningPrompt = ({
+  productiveCalls,
+  productiveRemaining,
+  handoffReserve
+}) => [
+  "Tool-call budget warning.",
+  `Productive calls used: ${productiveCalls}.`,
+  `Productive calls remaining: ${productiveRemaining}.`,
+  `Handoff reserve: ${handoffReserve} calls.`,
+  "Begin preparing a compact handoff now."
+].join(`
+`);
+var TOOL_BUDGET_HANDOFF_PROMPT = [
+  "The productive tool-call budget is exhausted.",
+  "Work tools are locked; do not execute further work.",
+  "Call `structured_output` exactly once, alone, with one configured outcome and a compact handoff."
+].join(`
+`);
 var needsCompletionRepair = ({
   policy,
   dependencies
@@ -8040,6 +8099,16 @@ var childSystemPrompt = (policy) => {
     `Valid outcomes: ${policy.outcomes.join(", ")}`,
     `Pause outcomes: ${policy.pauseOutcomes.join(", ") || "(none)"}`,
     `Summary limit: ${policy.summaryMaxChars} characters`,
+    ...policy.maxToolCalls === undefined ? [] : [
+      "",
+      "## Tool-call budget",
+      `Productive tool-call budget: ${policy.maxToolCalls} calls.`,
+      `Handoff reserve: ${policy.handoffReserve} calls.`,
+      `Total tool-call budget: ${policy.totalToolCalls} calls.`,
+      "At 2 productive calls remaining, begin handoff.",
+      "Work tools are locked when the productive budget is exhausted.",
+      "Continue with `handoff` using the reserved calls."
+    ],
     ...policy.gateSubmitOutcome ? [
       `Outcome "${policy.gateSubmitOutcome}" requires the complete gate artifact.`
     ] : [],
@@ -8060,7 +8129,9 @@ var INITIAL_STATE = {
   policyError: undefined,
   invalidCompletionCalls: new Set,
   effectiveTools: new Set,
-  repairRequested: false
+  productiveToolCallIds: new Set,
+  repairRequested: false,
+  runtimeMode: "working"
 };
 var errorMessage2 = (error) => error instanceof Error ? error.message : String(error);
 var invalidPolicyInput = (pi, policyError, images) => {
@@ -8127,7 +8198,9 @@ var registerSubagentChildRuntime = (pi, options = {}) => {
         activePolicy: extracted.policy,
         policyError: undefined,
         effectiveTools,
-        repairRequested: false
+        productiveToolCallIds: new Set,
+        repairRequested: false,
+        runtimeMode: "working"
       };
     } catch (error) {
       const policyError = errorMessage2(error);
@@ -8160,6 +8233,38 @@ ${childSystemPrompt(state.activePolicy)}`
   pi.on("turn_start", () => {
     state = { ...state, invalidCompletionCalls: new Set };
   });
+  pi.on("tool_execution_end", (event) => {
+    const policy = state.activePolicy;
+    const handoffReserve = policy?.handoffReserve;
+    if (!policy || policy.maxToolCalls === undefined || handoffReserve === undefined || event.toolName === CHILD_COMPLETION_TOOL || state.runtimeMode === "handoff" || state.productiveToolCallIds.has(event.toolCallId)) {
+      return;
+    }
+    const productiveToolCallIds = new Set(state.productiveToolCallIds);
+    productiveToolCallIds.add(event.toolCallId);
+    const productiveCalls = productiveToolCallIds.size;
+    if (productiveCalls >= policy.maxToolCalls) {
+      state = {
+        ...state,
+        effectiveTools: new Set([CHILD_COMPLETION_TOOL]),
+        productiveToolCallIds,
+        runtimeMode: "handoff"
+      };
+      pi.setActiveTools([CHILD_COMPLETION_TOOL]);
+      pi.sendUserMessage(TOOL_BUDGET_HANDOFF_PROMPT, {
+        deliverAs: "followUp"
+      });
+      return;
+    }
+    state = { ...state, productiveToolCallIds };
+    const productiveRemaining = policy.maxToolCalls - productiveCalls;
+    if (productiveRemaining <= handoffReserve) {
+      pi.sendUserMessage(toolBudgetWarningPrompt({
+        productiveCalls,
+        productiveRemaining,
+        handoffReserve
+      }), { deliverAs: "followUp" });
+    }
+  });
   pi.on("agent_settled", () => {
     const policy = state.activePolicy;
     if (!policy || state.repairRequested || !needsCompletionRepair({ policy, dependencies })) {
@@ -8223,6 +8328,12 @@ ${childSystemPrompt(state.activePolicy)}`
         };
       }
     }
+    if (state.runtimeMode === "handoff") {
+      return {
+        block: true,
+        reason: "Productive tool-call budget is exhausted; only structured_output is available for handoff"
+      };
+    }
     if (CHILD_COORDINATION_TOOLS.has(event.toolName)) {
       return {
         block: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wichayutdew/pi-workflows",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "A declarative, pauseable workflow harness for Pi",
   "license": "MIT",
   "repository": {

package/schemas/workflow.schema.json

@@ -669,6 +669,11 @@
         "agent": {
           "$ref": "#/$defs/subagentRuntimeName"
         },
+        "maxToolCalls": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100000
+        },
         "permissions": {
           "$ref": "#/$defs/permissions"
         },

package/src/config/types.ts

@@ -87,6 +87,7 @@ export type WorkflowStep = {
   readonly prompt: PromptSpec;
   /** Optional workflow-owned role prompt for this main-agent step. */
   readonly agent?: StepAgent;
+  readonly maxToolCalls?: number;
   readonly permissions: StepPermissions;
   readonly requires: StepRequirements;
   readonly transitions: Readonly<Record<string, StepTarget>>;

package/src/config/validation/step.ts

@@ -358,6 +358,7 @@ export function parseWorkflowStep(
       'title',
       'prompt',
       'agent',
+      'maxToolCalls',
       'permissions',
       'requires',
       'transitions',
@@ -382,6 +383,13 @@ export function parseWorkflowStep(
   const agent: StepAgent | undefined = agentName
     ? { name: agentName }
     : undefined;
+  const maxToolCalls =
+    value.maxToolCalls === undefined
+      ? undefined
+      : readInteger(value.maxToolCalls, 1, `${path}.maxToolCalls`, errors, {
+          min: 1,
+          max: 100_000,
+        });
   const permissions = parsePermissions(
     value.permissions,
     `${path}.permissions`,
@@ -445,6 +453,7 @@ export function parseWorkflowStep(
     title,
     prompt,
     ...(agent ? { agent } : {}),
+    ...(maxToolCalls === undefined ? {} : { maxToolCalls }),
     permissions,
     requires,
     transitions,

package/src/harness/delegation-plan.ts

@@ -13,6 +13,8 @@ import { buildDelegatedStepTask } from '../prompt.ts';
 import type { WorkflowHarnessDependencies } from './dependencies.ts';
 import type { ActiveDelegation } from './types.ts';
 
+const HANDOFF_RESERVE = 2;
+
 type DelegationPlanInput = {
   workflow: LoadedWorkflow;
   run: WorkflowRun;
@@ -156,6 +158,14 @@ export function createDelegationPlan(
   const workspace = dependencies.createDelegationWorkspace();
   const outcomes = allowedOutcomes(workflow, run);
   const outcomeSet = new Set(outcomes);
+  const toolBudget =
+    step.maxToolCalls === undefined
+      ? {}
+      : {
+          maxToolCalls: step.maxToolCalls,
+          handoffReserve: HANDOFF_RESERVE,
+          totalToolCalls: step.maxToolCalls + HANDOFF_RESERVE,
+        };
   const policyDigest = digest({
     version: 1,
     requestId,
@@ -168,6 +178,7 @@ export function createDelegationPlan(
     resultPath: workspace.resultPath,
     permissions: step.permissions,
     outcomes,
+    ...toolBudget,
     ...(step.workspace ? { workspace: step.workspace } : {}),
   });
   const policy: ChildStepPolicy = {
@@ -191,6 +202,7 @@ export function createDelegationPlan(
       )
       .map(([outcome]) => outcome),
     summaryMaxChars: workflow.definition.summaryMaxChars,
+    ...toolBudget,
     ...(step.gate ? { gateSubmitOutcome: step.gate.submitOutcome } : {}),
     ...(step.workspace ? { workspace: structuredClone(step.workspace) } : {}),
   };

package/src/integrations/subagents/child-policy-types.ts

@@ -22,6 +22,12 @@ export type ChildStepPolicy = {
   /** Outcomes that pause instead of advancing to another workflow step. */
   readonly pauseOutcomes: ReadonlyArray<string>;
   readonly summaryMaxChars: number;
+  /** Productive calls available before the mandatory handoff reserve. */
+  readonly maxToolCalls?: number;
+  /** Calls reserved for the child to hand off after productive work. */
+  readonly handoffReserve?: number;
+  /** Productive calls plus the mandatory handoff reserve. */
+  readonly totalToolCalls?: number;
   readonly gateSubmitOutcome?: string;
   readonly workspace?: StepWorkspaceBinding;
 };

package/src/integrations/subagents/child-policy-validation.ts

@@ -28,6 +28,9 @@ const POLICY_KEYS: ReadonlySet<string> = new Set([
   'outcomes',
   'pauseOutcomes',
   'summaryMaxChars',
+  'maxToolCalls',
+  'handoffReserve',
+  'totalToolCalls',
   'gateSubmitOutcome',
   'workspace',
 ]);
@@ -75,6 +78,48 @@ const rejectUnknownProperties = (
   }
 };
 
+type ToolBudget = Pick<
+  ChildStepPolicy,
+  'maxToolCalls' | 'handoffReserve' | 'totalToolCalls'
+>;
+
+const parseToolBudget = (
+  value: Readonly<Record<string, unknown>>,
+): ToolBudget => {
+  const fields = [
+    value.maxToolCalls,
+    value.handoffReserve,
+    value.totalToolCalls,
+  ];
+  if (fields.every((field) => field === undefined)) return {};
+  if (fields.some((field) => field === undefined)) {
+    throw new Error(
+      'child policy tool budget fields must be provided together',
+    );
+  }
+
+  const [maxToolCalls, handoffReserve, totalToolCalls] = fields;
+  if (
+    typeof maxToolCalls !== 'number' ||
+    !Number.isInteger(maxToolCalls) ||
+    maxToolCalls < 1 ||
+    maxToolCalls > 100_000
+  ) {
+    throw new Error('child policy maxToolCalls is invalid');
+  }
+  if (handoffReserve !== 2) {
+    throw new Error('child policy handoffReserve is invalid');
+  }
+  if (
+    typeof totalToolCalls !== 'number' ||
+    !Number.isInteger(totalToolCalls) ||
+    totalToolCalls !== maxToolCalls + handoffReserve
+  ) {
+    throw new Error('child policy totalToolCalls is invalid');
+  }
+  return { maxToolCalls, handoffReserve, totalToolCalls };
+};
+
 type IdentityAndPaths = Pick<
   ChildStepPolicy,
   | 'version'
@@ -164,5 +209,6 @@ export const parseChildPolicy = (
   return {
     ...parseIdentityAndPaths(value, environment),
     ...parseChildPolicySections(value),
+    ...parseToolBudget(value),
   };
 };

package/src/integrations/subagents/child-runtime-policy.ts

@@ -34,6 +34,18 @@ export const childSystemPrompt = (policy: ChildStepPolicy): string => {
     `Valid outcomes: ${policy.outcomes.join(', ')}`,
     `Pause outcomes: ${policy.pauseOutcomes.join(', ') || '(none)'}`,
     `Summary limit: ${policy.summaryMaxChars} characters`,
+    ...(policy.maxToolCalls === undefined
+      ? []
+      : [
+          '',
+          '## Tool-call budget',
+          `Productive tool-call budget: ${policy.maxToolCalls} calls.`,
+          `Handoff reserve: ${policy.handoffReserve} calls.`,
+          `Total tool-call budget: ${policy.totalToolCalls} calls.`,
+          'At 2 productive calls remaining, begin handoff.',
+          'Work tools are locked when the productive budget is exhausted.',
+          'Continue with `handoff` using the reserved calls.',
+        ]),
     ...(policy.gateSubmitOutcome
       ? [
           `Outcome "${policy.gateSubmitOutcome}" requires the complete gate artifact.`,

package/src/integrations/subagents/child-runtime-repair.ts

@@ -7,6 +7,29 @@ export const COMPLETION_REPAIR_PROMPT = [
   'Call `structured_output` exactly once, alone, with one configured outcome and the required summary, artifact, and workspace fields.',
 ].join('\n');
 
+export const toolBudgetWarningPrompt = ({
+  productiveCalls,
+  productiveRemaining,
+  handoffReserve,
+}: {
+  readonly productiveCalls: number;
+  readonly productiveRemaining: number;
+  readonly handoffReserve: number;
+}): string =>
+  [
+    'Tool-call budget warning.',
+    `Productive calls used: ${productiveCalls}.`,
+    `Productive calls remaining: ${productiveRemaining}.`,
+    `Handoff reserve: ${handoffReserve} calls.`,
+    'Begin preparing a compact handoff now.',
+  ].join('\n');
+
+export const TOOL_BUDGET_HANDOFF_PROMPT = [
+  'The productive tool-call budget is exhausted.',
+  'Work tools are locked; do not execute further work.',
+  'Call `structured_output` exactly once, alone, with one configured outcome and a compact handoff.',
+].join('\n');
+
 /** Returns whether a same-child completion repair may be requested safely. */
 export const needsCompletionRepair = ({
   policy,

package/src/integrations/subagents/child-runtime.ts

@@ -16,6 +16,8 @@ import { DEFAULT_CHILD_RUNTIME_DEPENDENCIES } from './child-runtime-dependencies
 import {
   COMPLETION_REPAIR_PROMPT,
   needsCompletionRepair,
+  TOOL_BUDGET_HANDOFF_PROMPT,
+  toolBudgetWarningPrompt,
 } from './child-runtime-repair.ts';
 import {
   verifyChildCapability,
@@ -43,7 +45,9 @@ type ChildRuntimeState = {
   readonly policyError: string | undefined;
   readonly invalidCompletionCalls: ReadonlySet<string>;
   readonly effectiveTools: ReadonlySet<string>;
+  readonly productiveToolCallIds: ReadonlySet<string>;
   readonly repairRequested: boolean;
+  readonly runtimeMode: 'working' | 'handoff';
 };
 
 const INITIAL_STATE: ChildRuntimeState = {
@@ -51,7 +55,9 @@ const INITIAL_STATE: ChildRuntimeState = {
   policyError: undefined,
   invalidCompletionCalls: new Set(),
   effectiveTools: new Set(),
+  productiveToolCallIds: new Set(),
   repairRequested: false,
+  runtimeMode: 'working',
 };
 
 const errorMessage = (error: unknown): string =>
@@ -148,7 +154,9 @@ export const registerSubagentChildRuntime = (
         activePolicy: extracted.policy,
         policyError: undefined,
         effectiveTools,
+        productiveToolCallIds: new Set(),
         repairRequested: false,
+        runtimeMode: 'working',
       };
     } catch (error) {
       const policyError = errorMessage(error);
@@ -182,6 +190,51 @@ export const registerSubagentChildRuntime = (
     state = { ...state, invalidCompletionCalls: new Set() };
   });
 
+  pi.on('tool_execution_end', (event) => {
+    const policy = state.activePolicy;
+    const handoffReserve = policy?.handoffReserve;
+    if (
+      !policy ||
+      policy.maxToolCalls === undefined ||
+      handoffReserve === undefined ||
+      event.toolName === CHILD_COMPLETION_TOOL ||
+      state.runtimeMode === 'handoff' ||
+      state.productiveToolCallIds.has(event.toolCallId)
+    ) {
+      return;
+    }
+
+    const productiveToolCallIds = new Set(state.productiveToolCallIds);
+    productiveToolCallIds.add(event.toolCallId);
+    const productiveCalls = productiveToolCallIds.size;
+    if (productiveCalls >= policy.maxToolCalls) {
+      state = {
+        ...state,
+        effectiveTools: new Set([CHILD_COMPLETION_TOOL]),
+        productiveToolCallIds,
+        runtimeMode: 'handoff',
+      };
+      pi.setActiveTools([CHILD_COMPLETION_TOOL]);
+      pi.sendUserMessage(TOOL_BUDGET_HANDOFF_PROMPT, {
+        deliverAs: 'followUp',
+      });
+      return;
+    }
+
+    state = { ...state, productiveToolCallIds };
+    const productiveRemaining = policy.maxToolCalls - productiveCalls;
+    if (productiveRemaining <= handoffReserve) {
+      pi.sendUserMessage(
+        toolBudgetWarningPrompt({
+          productiveCalls,
+          productiveRemaining,
+          handoffReserve,
+        }),
+        { deliverAs: 'followUp' },
+      );
+    }
+  });
+
   pi.on('agent_settled', () => {
     const policy = state.activePolicy;
     if (
@@ -252,6 +305,13 @@ export const registerSubagentChildRuntime = (
         };
       }
     }
+    if (state.runtimeMode === 'handoff') {
+      return {
+        block: true,
+        reason:
+          'Productive tool-call budget is exhausted; only structured_output is available for handoff',
+      };
+    }
     if (CHILD_COORDINATION_TOOLS.has(event.toolName)) {
       return {
         block: true,