@tranhoangnguyen0310/pi-flow-external 2.4.1-external.0 → 2.4.2-external.0

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to pi-flow external are documented here.
 
 ## Unreleased
 
+## [2.4.2-external.0] - 2026-09-23
+
+### Fixed
+
+- Simplified model-facing run supervision to one `runIds` selector, including singleton output/final inspection and cancellation. Legacy `runId` callers remain supported; conflicting cancellation selectors fail explicitly.
+- Workflow help accepts a supplied harness without blocking, explains its cross-harness scope, and accepts blank filters at the SDK schema boundary.
+- Blank Agent resume arguments no longer conflict with context sharing or trigger resume lookup. Real resume/context conflicts remain errors.
+- Added SDK argument-validation coverage alongside provider-payload tests. Audited workflow source selection: blank sources already normalize away; multiple real sources still fail. Downstream required-field promotion remains unverified, so #62 stays open.
+
 ## [2.4.1-external.0] - 2026-09-23
 
 ### Fixed

package/README.md

@@ -301,10 +301,10 @@ Agent({
 Use `external_runs` with these actions:
 
 - `list`: current session/project runs; use `cursor` for run pages and `workflowCursor` for workflow pages. `workflowRunId` filters children of one workflow. Rows carry a `timing` projection (`queueDelayMs`, `elapsedMs`, `activityAgeMs` when live, `processDurationMs`) plus `outputAvailable`/`finalAvailable`.
-- `inspect`: single `runId` with `view: "summary" | "output" | "diagnostics" | "final"`, and optional opaque `cursor`/`limitBytes` (max 64 KiB, same cap for every view). Follow `nextCursor` to avoid truncation. `summary` includes the same `timing` projection as `list`, plus `output.finalAvailable`. `final` returns only the verified canonical terminal answer — empty with `finalAvailable: false` until a successful terminal boundary exists; it never promotes partial/narration text. `output` stays the combined stream (assistant messages plus canonical result) and is unchanged.
-- `inspect` with `runIds` instead of `runId` (up to 20, deduplicated, order preserved): a single bounded batch of `summary`-only projections — one cheap request to see whether several selected background children are queued, running, or terminal, each with `outputRef`/`diagnosticsRef` for follow-up detail. Ownership of every requested ID is validated before any page is returned. Reuses the same `limitBytes` cap as single-run inspection; pages contain whole target entries and continue through `nextCursor`, without invalidation from ordinary live progress. If one compact entry cannot fit, an actionable error asks you to increase `limitBytes` or inspect that run individually; no target is silently dropped. `runId` and `runIds` are mutually exclusive, and batch `view` must stay `summary`.
-- `wait`: one `runId` or selected `runIds`, with `mode: "any" | "all"`. It returns terminal outcomes plus still-pending IDs; an unsuccessful workflow returns early even in `all` mode. It never chooses a winner or cancels pending work. While waiting, a bounded heartbeat (independent of any single target settling) reports live progress — watched targets, completed/pending counts, and recent activity — through the tool's update channel; it stops automatically on settlement, error, or interruption. Each settled outcome's `result` is spent from one shared byte budget (`limitBytes`, default 32768) across the whole response, in the requested `runId`/`runIds` order — never settlement race order, so the same targets and final states spend the budget identically regardless of which one happened to settle first: a result that fits is returned complete, one that does not is truncated with `resultTruncated: true` and the existing `outputRef`/`diagnosticsRef` to continue reading it — not a fixed-length teaser regardless of size. A target's evidence is never read from disk once the shared budget is already exhausted.
-- `cancel`: one `runId` and optional reason. Whole-workflow cancellation stops active children; targeted child cancellation remains a catchable workflow outcome. Cancellation does not roll back edits or other side effects.
+- `inspect`: single-entry `runIds` with `view: "summary" | "output" | "diagnostics" | "final"`, and optional opaque `cursor`/`limitBytes` (max 64 KiB, same cap for every view). Follow `nextCursor` to avoid truncation. `summary` includes the same `timing` projection as `list`, plus `output.finalAvailable`. `final` returns only the verified canonical terminal answer — empty with `finalAvailable: false` until a successful terminal boundary exists; it never promotes partial/narration text. `output` stays the combined stream (assistant messages plus canonical result) and is unchanged.
+- `inspect` with `runIds` (summary view) (up to 20, deduplicated, order preserved): a single bounded batch of `summary`-only projections — one cheap request to see whether several selected background children are queued, running, or terminal, each with `outputRef`/`diagnosticsRef` for follow-up detail. Ownership of every requested ID is validated before any page is returned. Reuses the same `limitBytes` cap as single-run inspection; pages contain whole target entries and continue through `nextCursor`, without invalidation from ordinary live progress. If one compact entry cannot fit, an actionable error asks you to increase `limitBytes` or inspect that run individually; no target is silently dropped. The legacy `runId` selector remains accepted by programmatic callers but is no longer advertised to models. A singleton list supports other views; multiple targets require `summary`.
+- `wait`: selected `runIds` (one or more), with `mode: "any" | "all"`. It returns terminal outcomes plus still-pending IDs; an unsuccessful workflow returns early even in `all` mode. It never chooses a winner or cancels pending work. While waiting, a bounded heartbeat (independent of any single target settling) reports live progress — watched targets, completed/pending counts, and recent activity — through the tool's update channel; it stops automatically on settlement, error, or interruption. Each settled outcome's `result` is spent from one shared byte budget (`limitBytes`, default 32768) across the whole response, in the requested `runId`/`runIds` order — never settlement race order, so the same targets and final states spend the budget identically regardless of which one happened to settle first: a result that fits is returned complete, one that does not is truncated with `resultTruncated: true` and the existing `outputRef`/`diagnosticsRef` to continue reading it — not a fixed-length teaser regardless of size. A target's evidence is never read from disk once the shared budget is already exhausted.
+- `cancel`: single-entry `runIds` and optional reason. Whole-workflow cancellation stops active children; targeted child cancellation remains a catchable workflow outcome. Cancellation does not roll back edits or other side effects.
 
 Interrupting a blocking `Agent`/`workflow` call cancels its work. Interrupting `external_runs wait` stops only that wait. Background work survives its launching tool return and ordinary parent turns, but not the owning session: orderly session shutdown requests cancellation and waits for bounded cleanup. This is not a daemon. After a host crash or unconfirmed shutdown, unfinished evidence is `interrupted_or_uncertain`; restart restores evidence access, never live ownership or guaranteed retrospective process termination. No routine activity wakes the parent, and live steering is not supported.
 
@@ -328,7 +328,7 @@ const two = Agent({ description: "Audit billing module", prompt: "Audit /absolut
 
 // Leave them running and come back later in the conversation (or after
 // further parent work) to collect final output once each is actually done:
-// external_runs({ action: "inspect", runId: one.runId, view: "final" })
+// external_runs({ action: "inspect", runIds: [one.runId], view: "final" })
 ```
 
 A task that sounds like a 30-second command can legitimately take substantially longer end-to-end once queueing and backend overhead are included — inspect and wait, do not assume.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tranhoangnguyen0310/pi-flow-external",
-  "version": "2.4.1-external.0",
+  "version": "2.4.2-external.0",
   "description": "External Claude Code, Codex CLI, Antigravity, Grok Build CLI, and Muse Code delegation for pi.",
   "type": "module",
   "main": "./index.ts",

package/src/core/parent-context.ts

@@ -45,7 +45,8 @@ export function prepareParentContext(
 ): { prompt: string; context?: ParentContextReceipt } {
   const context = parseParentContext(selection);
   if (!context || context.mode === "none") return { prompt };
-  if (resume !== undefined) throw new Error("context sharing cannot be combined with resume; continue the child or start a new one");
+  const resumeId = typeof resume === "string" && resume.trim() !== "" ? resume.trim() : undefined;
+  if (resumeId !== undefined) throw new Error("context sharing cannot be combined with resume; continue the child or start a new one");
   if (!messages) throw new Error("Parent context is unavailable; use context:none and a self-contained prompt");
   const compacted = messages.some((message) => message.role === "compactionSummary");
   let start = 0;

package/src/external-help.ts

@@ -22,8 +22,7 @@ const externalHelpParameters = Type.Object({
     description: "Help topic: role descriptions/configured profile availability, harness permissions, or workflow syntax and saved workflows.",
   }),
   harness: Type.Optional(Type.String({
-    minLength: 1,
-    description: "Optional harness filter for roles or permissions: agy, claude, codex, grok, muse, or a registered pi-* harness. Do not use with topic workflow.",
+    description: "Optional harness filter for roles or permissions: agy, claude, codex, grok, muse, or a registered pi-* harness. Workflows orchestrate across harnesses.",
   })),
 });
 
@@ -131,14 +130,18 @@ export function createExternalHelpTool(
     promptSnippet: EXTERNAL_HELP_PROMPT_SNIPPET,
     parameters: externalHelpParameters,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      if (params.topic === "workflow" && params.harness) {
-        throw new Error("external_help harness is only valid for roles or permissions.");
-      }
+      // A schema-conversion layer downstream of this tool's declaration may
+      // present `harness` as required (#62); treat a blank/whitespace
+      // placeholder as omitted. Furthermore, do not reject an explicit
+      // harness on topic "workflow": workflows orchestrate across all
+      // harnesses, so passing a harness filter gracefully returns workflow
+      // guidance without error.
+      const harness = params.harness?.trim() ? params.harness.trim() : undefined;
       let text: string;
       const { harnesses: harnessConfigs } = loadHarnessConfigs(getAgentDir());
       const configuredPiHarnesses = new Set(harnessConfigs.keys());
       if (params.topic !== "workflow") {
-        validateHarnessFilter(params.harness, configuredPiHarnesses);
+        validateHarnessFilter(harness, configuredPiHarnesses);
       }
       if (params.topic === "roles") {
         const profiles = mergeSynthesizedPiProfiles(
@@ -148,19 +151,22 @@ export function createExternalHelpTool(
           ),
           harnessConfigs,
         );
-        text = formatExternalRoleHelp(profiles, options.getDefaultHarness(ctx), params.harness);
+        text = formatExternalRoleHelp(profiles, options.getDefaultHarness(ctx), harness);
       } else if (params.topic === "permissions") {
-        text = permissionHelp(params.harness, configuredPiHarnesses);
+        text = permissionHelp(harness, configuredPiHarnesses);
       } else {
-        text = workflowHelp(options.workflowEnabled, listSavedWorkflows({
+        const wfText = workflowHelp(options.workflowEnabled, listSavedWorkflows({
           agentDir: getAgentDir(),
           cwd: ctx.cwd,
           projectTrusted: isProjectTrusted(ctx),
         }));
+        text = harness
+          ? `${wfText}\n\nNote: Workflows orchestrate across multiple harnesses (including "${harness}"); workflow syntax is uniform across backends.`
+          : wfText;
       }
       return {
         content: [{ type: "text" as const, text }],
-        details: { topic: params.topic, ...(params.harness ? { harness: params.harness } : {}) },
+        details: { topic: params.topic, ...(harness ? { harness } : {}) },
       };
     },
   });

package/src/external-runs.ts

@@ -28,13 +28,9 @@ const externalRunsParameters = Type.Object({
   action: StringEnum(["list", "inspect", "wait", "cancel"] as const, {
     description: "list: page runs/workflows; inspect: read one run; wait: block until selected terminal outcomes; cancel: stop one run.",
   }),
-  runId: Type.Optional(Type.String({
-    description: "Target run ID (run_... agent, wf_... workflow). Required for inspect/cancel/wait of a single run.",
-  })),
   runIds: Type.Optional(Type.Array(Type.String(), {
-    minItems: 1,
     maxItems: MAX_TARGETS,
-    description: "wait: target set for mode any|all, up to 100, deduplicated; already-terminal targets return immediately. inspect: batch summary target set, up to 20, deduplicated, order preserved; cannot combine with runId, and view must stay summary.",
+    description: "Target run IDs (run_... agent, wf_... workflow). For inspect: a single-entry list [\"run_...\"] inspects that run with any view (summary, output, diagnostics, final); multiple entries (1-20 targets) batch summary inspect. For cancel: a single-entry list [\"run_...\"]. For wait: any|all of up to 100 targets.",
   })),
   view: Type.Optional(StringEnum(["summary", "output", "diagnostics", "final"] as const, {
     description: "inspect view: summary (state/timing/freshness/refs, default), output (assistant text plus canonical result, partial or final), diagnostics (tool activity/errors), final (only the verified canonical terminal answer, empty until a successful terminal boundary exists). Batch inspect (runIds) only supports summary.",
@@ -67,7 +63,10 @@ const externalRunsParameters = Type.Object({
   })),
 });
 
-export type ExternalRunsParams = Static<typeof externalRunsParameters>;
+export type ExternalRunsParams = Static<typeof externalRunsParameters> & {
+  /** Legacy single-target selector; preserved for backwards-compatible programmatic/test callers. */
+  runId?: string;
+};
 type ExternalRunsDetails = Record<string, unknown>;
 
 export interface CreateExternalRunsToolOptions {
@@ -518,9 +517,12 @@ function renderExternalRunsCall(args: Record<string, unknown>, theme: Theme): Te
     const ids = Array.isArray(args.runIds) ? args.runIds : args.runId ? [args.runId] : [];
     detail = `waiting for ${ids.length} task(s) · mode ${typeof args.mode === "string" ? args.mode : "all"}`;
   } else if (action === "cancel") {
-    detail = `cancel ${String(args.runId ?? "")}`;
+    const target = Array.isArray(args.runIds) && args.runIds.length ? args.runIds[0] : String(args.runId ?? "");
+    detail = `cancel ${target}`;
   } else if (action === "inspect") {
-    const target = Array.isArray(args.runIds) ? `${args.runIds.length} run(s) (batch)` : String(args.runId ?? "");
+    const target = Array.isArray(args.runIds)
+      ? args.runIds.length === 1 ? args.runIds[0] : `${args.runIds.length} run(s) (batch)`
+      : String(args.runId ?? "");
     detail = `inspect ${target} · ${typeof args.view === "string" ? args.view : "summary"}`;
   } else {
     detail = `list${typeof args.workflowRunId === "string" ? ` · workflow ${args.workflowRunId}` : ""}`;
@@ -626,6 +628,33 @@ function renderExternalRunsResult(toolResult: { content: Array<{ type: string; t
   return new Text(textFromToolResult(toolResult), 0, 0);
 }
 
+/**
+ * Reconcile the `runId`/`runIds` selector pair for `inspect` only — the one
+ * action that already hard-rejects supplying both (`wait` treats a stray
+ * `runId` alongside `runIds` as a harmless one-element convenience, and
+ * `cancel` never reads `runIds` at all, so neither gets a new conflict
+ * check here). A schema-conversion layer downstream of this tool's
+ * declaration may present both mutually exclusive optional selectors as
+ * required (#62); a model forced to fill in the one it means to omit
+ * typically sends a blank string or an empty array. Neither can name an
+ * actual run, so treat that placeholder as omitted rather than a real
+ * conflict — this is narrower than guessing between two genuinely
+ * populated, disagreeing selectors, which still fails loudly exactly as
+ * before (including when both name the very same run: inspect has always
+ * rejected supplying the pair at all, on purpose).
+ */
+function normalizeInspectSelectors(params: ExternalRunsParams): ExternalRunsParams {
+  const runId = params.runId === undefined || params.runId.trim() === "" ? undefined : params.runId;
+  const runIds = runId !== undefined && (params.runIds === undefined || params.runIds.length === 0)
+    ? undefined
+    : params.runIds;
+  if (runId !== undefined && runIds !== undefined && runIds.length > 0) {
+    throw new Error("inspect accepts either runId or runIds, not both");
+  }
+  if (runId === params.runId && runIds === params.runIds) return params;
+  return { ...params, runId, runIds };
+}
+
 export function createExternalRunsTool(
   options: CreateExternalRunsToolOptions,
 ): ToolDefinition<typeof externalRunsParameters, ExternalRunsDetails> {
@@ -636,6 +665,12 @@ export function createExternalRunsTool(
     promptSnippet: EXTERNAL_RUNS_PROMPT_SNIPPET,
     parameters: externalRunsParameters,
     async execute(_toolCallId, params: ExternalRunsParams, signal, onUpdate, ctx) {
+      if (params.action === "inspect") {
+        params = normalizeInspectSelectors(params);
+        if (params.runId === undefined && params.runIds !== undefined && params.runIds.length === 1 && params.view !== undefined && params.view !== "summary") {
+          params = { ...params, runId: params.runIds[0], runIds: undefined };
+        }
+      }
       const { sessionId, project } = scope(ctx);
       const runsDirectory = options.runsDirectory();
 
@@ -670,7 +705,7 @@ export function createExternalRunsTool(
       }
 
       if (params.action === "inspect" && params.runIds !== undefined) {
-        if (params.runId !== undefined) throw new Error("inspect accepts either runId or runIds, not both");
+        // normalizeInspectSelectors already guarantees runId is unset here.
         if (params.view !== undefined && params.view !== "summary") throw new Error('Batch inspect (runIds) only supports view: "summary"');
         const runIds = [...new Set(params.runIds)];
         if (runIds.length === 0 || runIds.length > MAX_BATCH_INSPECT_TARGETS) {
@@ -812,26 +847,35 @@ export function createExternalRunsTool(
       }
 
       if (params.action === "cancel") {
-        assertRunId(params.runId);
-        const entry = options.registry.get(params.runId);
+        const rawRunIds = params.runIds;
+        if (rawRunIds?.length && params.runId?.trim()) {
+          throw new Error("cancel accepts either runId or runIds, not both");
+        }
+        if (rawRunIds && rawRunIds.length > 1) {
+          throw new Error("cancel targets one run at a time");
+        }
+        const targetRunId = (rawRunIds && rawRunIds.length === 1 ? rawRunIds[0] : undefined)
+          ?? (typeof params.runId === "string" && params.runId.trim() !== "" ? params.runId.trim() : undefined);
+        assertRunId(targetRunId);
+        const entry = options.registry.get(targetRunId);
         if (entry) {
           assertOwned(entry, sessionId, project);
-          const status = options.registry.cancel(params.runId, params.reason ?? "cancelled by external_runs");
-          return result(status === "requested" ? `Cancellation requested for ${params.runId}.` : `${params.runId} is already terminal.`, { runId: params.runId, status });
+          const status = options.registry.cancel(targetRunId, params.reason ?? "cancelled by external_runs");
+          return result(status === "requested" ? `Cancellation requested for ${targetRunId}.` : `${targetRunId} is already terminal.`, { runId: targetRunId, status });
         }
-        const isWorkflowId = WORKFLOW_ID.test(params.runId);
+        const isWorkflowId = WORKFLOW_ID.test(targetRunId);
         const workflowDir = getSessionWorkflowDir(ctx);
-        const historicalWorkflow = isWorkflowId && workflowDir ? await loadWorkflowJournal(workflowDir, params.runId) : undefined;
+        const historicalWorkflow = isWorkflowId && workflowDir ? await loadWorkflowJournal(workflowDir, targetRunId) : undefined;
         if (historicalWorkflow) {
           if (historicalWorkflow.project !== project) throw new Error("Run is unknown or unavailable in this session");
-          if (historicalWorkflow.status !== "running") return result(`${params.runId} is already terminal.`, { runId: params.runId, status: "terminal" });
+          if (historicalWorkflow.status !== "running") return result(`${targetRunId} is already terminal.`, { runId: targetRunId, status: "terminal" });
           throw new Error("Run is no longer live in this session; cancellation cannot be confirmed");
         }
         // An unresolved wf_... ID is unknown, not an unowned agent record.
         if (isWorkflowId) throw new Error("Run is unknown or unavailable in this session");
-        const durable = await getRunRecord(runsDirectory, params.runId);
+        const durable = await getRunRecord(runsDirectory, targetRunId);
         assertOwnedRecord(durable, sessionId, project);
-        if (terminalRecord(durable)) return result(`${params.runId} is already terminal.`, { runId: params.runId, status: "terminal" });
+        if (terminalRecord(durable)) return result(`${targetRunId} is already terminal.`, { runId: targetRunId, status: "terminal" });
         throw new Error("Run is no longer live in this session; cancellation cannot be confirmed");
       }
 

package/src/pi-subagent.ts

@@ -358,9 +358,10 @@ function createAgentTool(
     parameters: agentToolParameters,
     executionMode: "parallel",
     async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const resume = typeof params.resume === "string" && params.resume.trim() !== "" ? params.resume.trim() : undefined;
       const briefing = prepareParentContext(params.prompt, params.context,
         params.context && params.context.mode !== "none" ? captureParentContext(ctx.sessionManager) : undefined,
-        toolCallId, params.resume);
+        toolCallId, resume);
       const state = getState();
       const effectiveState: DelegationState = {
         ...state,
@@ -524,7 +525,7 @@ function createAgentTool(
           permission: params.permission,
           defaultPermission,
           maxBudgetUsd,
-          resumeRunId: params.resume,
+          resumeRunId: resume,
           executionStartedAt: run.progress.executionStartedAt,
           onProgress: (partial) => {
             const details = partial.details as SubagentToolDetails;