pi-workflow-engine 1.0.0 → 1.2.0

package/.pi/extensions/pi-workflow-engine/src/agent-runner-types.ts

@@ -1,4 +1,4 @@
-import type { Api, Model } from "@earendil-works/pi-ai";
+import type { Api, ClassifierApi, ClassifierModel, Model } from "@earendil-works/pi-ai";
 import type {
   AgentSession,
   CreateAgentSessionOptions,
@@ -8,6 +8,7 @@ import type { WorkflowBudget } from "./budget.ts";
 import type { Semaphore } from "./concurrency.ts";
 import type { WorkflowAgentLimiter } from "./agent-limits.ts";
 import type { AgentRetryScheduler } from "./agent-retry.ts";
+import type { HostToolBridge } from "./host-tools.ts";
 import type { ResolvedWorkflowModelProfiles } from "./model-profiles.ts";
 import type { WorkflowJournal } from "./journal.ts";
 import type { PerfSink } from "./perf.ts";
@@ -37,10 +38,12 @@ export type CreateAgentSession = (options: CreateAgentSessionOptions) => Promise
 /** Every row update after `agentQueued` addresses that row by its id; labels are display text, not unique keys. */
 export interface AgentProgress {
   agentQueued(phase: string | undefined, label: string): number;
-  agentStart(id: number): void;
+  /** `skip` aborts the row's live agent; the tracker offers it to the inspector only while the row runs. */
+  agentStart(id: number, skip?: () => void): void;
   agentTool(id: number, tool: string): void;
   agentDone(id: number): void;
   agentFailed(id: number, error: unknown): void;
+  agentSkipped(id: number): void;
   event(event: WorkflowProgressEvent): void;
   log(message: string): void;
 }
@@ -63,6 +66,10 @@ interface RunContextBase {
   budget: WorkflowBudget;
   journal: WorkflowJournal;
   worktrees: WorktreeRegistry;
+  /** Host MCP tools subagents may call; set only for a synchronous `workflow` tool run. */
+  hostTools?: HostToolBridge;
+  /** Classifier routes resolved this run, so repeated `api.classify()` calls skip the credential lookup. */
+  classifierRoutes?: Map<string, Promise<ClassifierModel<ClassifierApi>>>;
 }
 
 /** Shared per-run context threaded into every agent() call. */
@@ -74,7 +81,7 @@ export type RunContext = RunContextBase & (
     }
   | {
       /** Injected test sessions bypass Pi's resource loader and therefore do not resolve skills. */
-      modelRegistry: Pick<ModelRegistry, "find">;
+      modelRegistry: Pick<ModelRegistry, "find" | "classify" | "getAvailableOfType" | "getModelOfType">;
       createSession: CreateAgentSession;
     }
 );

package/.pi/extensions/pi-workflow-engine/src/agent-runner.ts

@@ -1,6 +1,6 @@
 import { assertWorkflowBudgetAvailable } from "./budget.ts";
 import { WorkflowAgentTimeoutError } from "./agent-limits.ts";
-import { abortReason, linkAbortSignal, throwIfAborted } from "./cancellation.ts";
+import { abortReason, linkAbortSignal, throwIfAborted, WorkflowAgentSkippedError } from "./cancellation.ts";
 import { executeAgentAttempt } from "./agent-attempt.ts";
 import {
   createAgentReplayPlan,
@@ -66,7 +66,7 @@ export async function runAgent(
           const agentRc: RunContext = { ...rc, signal: liveScope.signal };
           throwIfAborted(agentRc.signal);
           if (!isReplayEnabled(replay)) assertWorkflowBudgetAvailable(agentRc.budget);
-          rc.progress.agentStart(rowId);
+          rc.progress.agentStart(rowId, liveScope.skip);
           if (replay.kind === "disabled") {
             rc.progress.log(`${label}: resume disabled for this call (${replay.reason})`);
           }
@@ -107,6 +107,8 @@ export async function runAgent(
               await agentRc.retryScheduler.sleep(delayMs, agentRc.signal);
               continue;
             }
+            // A skip that lands as the attempt finishes still wins, so its result is neither returned nor journaled.
+            liveScope.throwIfSkipped();
             const settlement = await settleAgentAttempt({ rc: agentRc, label, outcome });
             if (settlement.kind === "retry-live") {
               attemptPlan = { kind: "off" };
@@ -125,8 +127,13 @@ export async function runAgent(
       let failure = error;
       if (liveScope.signal.aborted) failure = abortReason(liveScope.signal);
       if (rc.signal?.aborted) failure = abortReason(rc.signal);
-      rc.progress.agentFailed(rowId, failure);
-      rc.progress.log(`${label} failed: ${unknownErrorMessage(failure)}`);
+      if (failure instanceof WorkflowAgentSkippedError) {
+        rc.progress.agentSkipped(rowId);
+        rc.progress.log(`${label} skipped`);
+      } else {
+        rc.progress.agentFailed(rowId, failure);
+        rc.progress.log(`${label} failed: ${unknownErrorMessage(failure)}`);
+      }
       throw failure;
     } finally {
       liveScope.dispose();
@@ -151,6 +158,13 @@ function createAgentLiveScope(rc: RunContext, label: string) {
         rc.agentTimeoutMs,
       );
     },
+    /** Aborts only this agent; the run and its siblings carry on. */
+    skip() {
+      controller.abort(new WorkflowAgentSkippedError(label));
+    },
+    throwIfSkipped() {
+      if (controller.signal.reason instanceof WorkflowAgentSkippedError) throw controller.signal.reason;
+    },
     dispose() {
       if (timer) clearTimeout(timer);
       unlink();

package/.pi/extensions/pi-workflow-engine/src/agent-session.ts

@@ -2,14 +2,17 @@ import type { Api, AssistantMessage, Model } from "@earendil-works/pi-ai";
 import {
   createAgentSessionFromServices,
   createAgentSessionServices,
+  createCodemodeExtension,
   defineTool,
   SessionManager,
   type CreateAgentSessionOptions,
+  type CreateAgentSessionServicesOptions,
   type ModelRegistry,
   type Skill,
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { prepareAgentSkillResources } from "./agent-skills.ts";
+import { createCodemodeSlotExtension, runToolCallsSequentially } from "./codemode-slots.ts";
 import type {
   AgentExecutionOptions,
   AgentProgress,
@@ -23,12 +26,26 @@ import {
 } from "./structured-output.ts";
 import { providerErrorFromMessages } from "./agent-retry.ts";
 import { synchronizeWorkflowModelRuntime } from "./agent-session-providers.ts";
+import { hostToolProxy, isMcpToolName, WorkflowHostToolUnavailableError, type HostToolBridge } from "./host-tools.ts";
 import { matchesAgentToolHint, WorkflowToolHintUnavailableError } from "./tool-capabilities.ts";
+import { parseAgentModelRef } from "./model-ref.ts";
 import { truncateText } from "./text.ts";
 import { WORKFLOW_TOOL_NAME, type AgentToolHint } from "./types.ts";
 
 export const FINAL_TOOL = "final_answer";
+/** pi's codemode tool; SDK sessions only have it when their resource loader registers the extension. */
+export const CODEMODE_TOOL = "codemode";
 
+/** pi's stock prompt frames a chat with a person; a subagent's last message is program data instead. */
+const RETURN_VALUE_FRAMING =
+  "Your final message is returned verbatim to the workflow program that started you, as data. " +
+  "It is not shown to a person as a chat reply. Make it exactly the output your task asks for, in the format it asks for, " +
+  "with no greeting, preamble, narration of your process, or offer of further help.";
+/** A schema agent returns its final_answer arguments, not its last message. */
+const STRUCTURED_RETURN_VALUE_FRAMING =
+  `Your ${FINAL_TOOL} arguments are returned to the workflow program that started you, as data. ` +
+  "They are not shown to a person as a chat reply. Fill each field with exactly the content it asks for, " +
+  "with no greeting, preamble, narration of your process, or offer of further help.";
 const SCHEMA_REPROMPT =
   `You ended your turn without calling the ${FINAL_TOOL} tool, so no result was recorded. ` +
   `Call ${FINAL_TOOL} now with your final answer as its arguments. Do not reply with plain text.`;
@@ -76,6 +93,8 @@ export async function openAgentSession(input: {
           description:
             "Return your final structured answer. This MUST be your last action — do not write a normal reply after calling it.",
           parameters: opts.schema,
+          // The agent's own terminal action: a codemode script must not answer on its behalf.
+          exposure: "model-only",
           async execute(_toolCallId, params) {
             captured = true;
             structuredResult = params;
@@ -84,6 +103,7 @@ export async function openAgentSession(input: {
         }),
       ]
     : [];
+  customTools.push(...requestedHostTools(opts, rc.hostTools));
   let session: AgentRunnerSession | undefined;
   try {
     throwIfAborted(rc.signal);
@@ -105,7 +125,7 @@ export async function openAgentSession(input: {
     if (!opts.tools?.includes(WORKFLOW_TOOL_NAME)) withholdWorkflowTool(session);
     if (opts.requireToolHints) {
       const missing = toolSelection.toolHints.filter((hint) => !matchedToolHints.has(hint));
-      if (missing.length > 0) throw new WorkflowToolHintUnavailableError(missing);
+      if (missing.length > 0) throw new WorkflowToolHintUnavailableError(missing, { hostToolsReachable: rc.hostTools !== undefined });
     }
     throwIfAborted(rc.signal);
     return {
@@ -200,24 +220,6 @@ export async function promptAgentSession(input: {
   }
 }
 
-function parseAgentModelRef(modelRef: string): { readonly provider: string; readonly id: string } {
-  const normalized = modelRef.trim();
-  if (normalized.length === 0) {
-    throw new Error('Invalid agent model ref: expected a bare model id or "provider/id".');
-  }
-  if (normalized !== modelRef) {
-    throw new Error(`Invalid agent model ref "${modelRef}": remove leading or trailing whitespace.`);
-  }
-
-  const slash = modelRef.indexOf("/");
-  if (slash === -1) return { provider: "anthropic", id: modelRef };
-  const provider = modelRef.slice(0, slash);
-  const id = modelRef.slice(slash + 1);
-  if (provider.length === 0 || id.length === 0 || id.startsWith("/")) {
-    throw new Error(`Invalid agent model ref "${modelRef}": expected "provider/id".`);
-  }
-  return { provider, id };
-}
 
 interface AgentSessionResources {
   readonly selectedSkills: readonly Skill[];
@@ -243,6 +245,7 @@ async function prepareAgentSessionResources(input: {
     sessionManager: SessionManager.inMemory(cwd),
   });
   const createSession = rc.createSession;
+  // Injected test sessions build no resource loader, so they get neither skills nor the return-value framing.
   if (createSession) {
     return {
       selectedSkills: [],
@@ -260,9 +263,15 @@ async function prepareAgentSessionResources(input: {
     log: (message: string) => rc.progress.log(`${label}: ${message}`),
   };
   const preparedSkills = prepareAgentSkillResources(skillOptions);
+  const codemode = opts.tools?.includes(CODEMODE_TOOL) ?? false;
   const services = await createAgentSessionServices({
     cwd,
-    resourceLoaderOptions: preparedSkills.resourceLoaderOptions,
+    resourceLoaderOptions: {
+      ...preparedSkills.resourceLoaderOptions,
+      ...(codemode ? codemodeExtensions() : {}),
+      // An override, not `appendSystemPrompt`: passing that replaces pi's discovery of the user's APPEND_SYSTEM.md.
+      appendSystemPromptOverride: (base) => [...base, opts.schema ? STRUCTURED_RETURN_VALUE_FRAMING : RETURN_VALUE_FRAMING],
+    },
   });
   await synchronizeWorkflowModelRuntime({
     host: rc.modelRegistry,
@@ -281,14 +290,53 @@ async function prepareAgentSessionResources(input: {
   const selectedSkills = preparedSkills.resolve(services.resourceLoader);
   return {
     selectedSkills,
-    createSession: (sessionOptions) =>
-      createAgentSessionFromServices({
+    createSession: async (sessionOptions) => {
+      const created = await createAgentSessionFromServices({
         services,
         ...commonSessionOptions(sessionOptions),
-      }),
+      });
+      if (codemode) runToolCallsSequentially(created.session);
+      return created;
+    },
+  };
+}
+
+/**
+ * SDK sessions load none of pi's built-in extensions, so codemode is registered only for agents whose
+ * allowlist names it. Scripts can call just the agent's other allowed tools. Mode "on" keeps those
+ * tools declared whatever the user's `codemode.mode`, so the author's allowlist stays what the model sees.
+ * Its calls queue for the process-wide codemode slots instead of failing at pi's worker limit, so the
+ * session runs its tool calls one at a time.
+ */
+function codemodeExtensions(): Pick<SessionResourceLoaderOptions, "extensionFactories"> {
+  return {
+    extensionFactories: [
+      { name: CODEMODE_TOOL, factory: createCodemodeExtension({ mode: "on" }), replaceable: true },
+      { name: "workflow-codemode-slots", factory: createCodemodeSlotExtension(CODEMODE_TOOL), hidden: true },
+    ],
   };
 }
 
+type SessionResourceLoaderOptions = NonNullable<CreateAgentSessionServicesOptions["resourceLoaderOptions"]>;
+
+/**
+ * Proxies for the host MCP tools this agent asked for: those named in its allowlist, and open-world
+ * research tools when it hints `external-search`. Local `search` hints never bridge, because host tools
+ * run in the host session's working directory, not the agent's (an isolated worktree, for example).
+ * A named tool the run cannot reach fails the agent, like `requireToolHints`, rather than letting it
+ * work without a tool its prompt may rely on.
+ */
+function requestedHostTools(opts: AgentExecutionOptions, bridge: HostToolBridge | undefined): ToolDefinition[] {
+  const named = new Set((opts.tools ?? []).filter(isMcpToolName));
+  const externalSearch = opts.toolHints?.includes("external-search") ?? false;
+  if (named.size === 0 && !externalSearch) return [];
+  const available = bridge?.tools() ?? [];
+  const selected = available.filter((tool) => named.has(tool.name) || (externalSearch && matchesAgentToolHint(tool, "external-search")));
+  const missing = [...named].filter((name) => !selected.some((tool) => tool.name === name));
+  if (missing.length > 0) throw new WorkflowHostToolUnavailableError(missing, bridge !== undefined);
+  return bridge ? selected.map((tool) => hostToolProxy(tool, bridge)) : [];
+}
+
 function linkSessionAbort(signal: AbortSignal | undefined, session: AgentRunnerSession): () => void {
   if (!signal) return () => {};
   const onAbort = () => {

package/.pi/extensions/pi-workflow-engine/src/background-workflow-tool.ts

@@ -1,12 +1,15 @@
+import { join } from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { BackgroundWorkflowCoordinator, backgroundOrigin } from "./background-workflows.ts";
-import { createWorkflowRunId } from "./journal.ts";
+import { createWorkflowRunId, WORKFLOW_RUNS_DIR } from "./journal.ts";
 import type { ResolvedWorkflowRunOptions } from "./options.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
+import { workflowRunScriptFile } from "./workflow-run-record.ts";
 
 export interface BackgroundWorkflowToolResult {
   readonly content: Array<{ readonly type: "text"; readonly text: string }>;
   readonly details: Readonly<Record<string, unknown>>;
+  readonly isError?: true;
 }
 
 export interface BackgroundWorkflowToolStartInput {
@@ -14,6 +17,8 @@ export interface BackgroundWorkflowToolStartInput {
   readonly ctx: ExtensionContext;
   readonly name: string;
   readonly options: ResolvedWorkflowRunOptions;
+  /** Deliver the completion with a new agent turn instead of silently. */
+  readonly wakeOnComplete?: boolean;
   readonly execute: (ctx: ExtensionContext, options: ResolvedWorkflowRunOptions) => Promise<void>;
 }
 
@@ -25,6 +30,7 @@ export function backgroundUnavailableResult(mode: ExtensionContext["mode"]): Bac
       text: `Background workflows are unavailable in ${mode} mode because pi exits after the prompt. Run synchronously or use TUI/RPC mode.`,
     }],
     details: { error: "background_unavailable", mode },
+    isError: true,
   };
 }
 
@@ -37,8 +43,9 @@ export async function startBackgroundWorkflowTool(
     inspect: false,
     resultViewer: "skip",
     runId,
-    background: backgroundOrigin(input.ctx),
+    background: backgroundOrigin(input.ctx, Date.now(), input.wakeOnComplete),
   };
+  let scriptPersisted = false;
   try {
     await input.coordinator.start({
       ctx: input.ctx,
@@ -51,6 +58,7 @@ export async function startBackgroundWorkflowTool(
             ...backgroundOptions,
             signal,
             onRunMetadata(metadata) {
+              scriptPersisted = metadata.scriptPath !== undefined;
               onStarted();
               return backgroundOptions.onRunMetadata?.(metadata);
             },
@@ -63,12 +71,13 @@ export async function startBackgroundWorkflowTool(
     return {
       content: [{ type: "text", text: `Background workflow did not start: ${message}` }],
       details: { error: "background_start_failed", message, runId },
+      isError: true,
     };
   }
   return {
     content: [{
       type: "text",
-      text: `Background workflow "${input.name}" started.\nRun ID: ${runId}\nDurable record: .pi/.workflow-runs/${runId}.run.json`,
+      text: `Background workflow "${input.name}" started.\nRun ID: ${runId}\nDurable record: .pi/.workflow-runs/${runId}.run.json${scriptPersisted ? `\nScript: ${join(WORKFLOW_RUNS_DIR, workflowRunScriptFile(runId))}` : ""}`,
     }],
     details: { background: true, state: "running", name: input.name, runId },
   };

package/.pi/extensions/pi-workflow-engine/src/background-workflows.ts

@@ -1,6 +1,8 @@
+import { join } from "node:path";
 import { SessionManager, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { WorkflowAbortError, WorkflowPauseError } from "./cancellation.ts";
 import { isRecord } from "./guards.ts";
+import { WORKFLOW_RUNS_DIR } from "./journal.ts";
 import type { WorkflowBackgroundOrigin } from "./types.ts";
 import {
   stopWorkflowRunRecord,
@@ -9,9 +11,11 @@ import {
   type WorkflowRunState,
 } from "./workflow-run-record.ts";
 import { updateWorkflowRunDelivery, type WorkflowRunDelivery } from "./workflow-run-background.ts";
-import { ProjectWorkflowRunStore, type WorkflowRunStore } from "./workflow-run-store.ts";
+import { ProjectWorkflowRunStore, WORKFLOW_RUN_RECORD_SUFFIX, type WorkflowRunStore } from "./workflow-run-store.ts";
 import { truncateText } from "./text.ts";
+import { formatWorkflowUsageLine } from "./usage.ts";
 import { workflowResultSummary } from "./workflow-execution.ts";
+import { formatResultForContext, formatWorkflowRunFileLines } from "./workflow-result-context.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 
 const BACKGROUND_DELIVERY_CUSTOM_TYPE = "workflow-result";
@@ -294,11 +298,12 @@ export class BackgroundWorkflowCoordinator {
       this.pi.sendMessage(
         {
           customType: BACKGROUND_DELIVERY_CUSTOM_TYPE,
-          content: formatBackgroundDelivery(details),
+          content: formatBackgroundDelivery(record, details),
           display: true,
           details,
         },
-        { triggerTurn: false },
+        // Delivery waits for an idle session, and pi steers a message sent while a run starts into that run.
+        { triggerTurn: wakesAgent(record) },
       );
     }
     await markDelivery(store, runId, { state: "delivered", deliveredAt: Date.now() });
@@ -306,8 +311,13 @@ export class BackgroundWorkflowCoordinator {
   }
 }
 
-export function backgroundOrigin(ctx: Pick<ExtensionContext, "sessionManager">, requestedAt = Date.now()): WorkflowBackgroundOrigin {
-  return { sessionId: ctx.sessionManager.getSessionId(), requestedAt };
+export function backgroundOrigin(
+  ctx: Pick<ExtensionContext, "sessionManager">,
+  requestedAt = Date.now(),
+  wakeOnComplete = false,
+): WorkflowBackgroundOrigin {
+  const origin = { sessionId: ctx.sessionManager.getSessionId(), requestedAt };
+  return wakeOnComplete ? { ...origin, wakeOnComplete } : origin;
 }
 
 export function backgroundResultDetails(record: WorkflowRunRecord): BackgroundWorkflowResultDetails {
@@ -336,17 +346,41 @@ function backgroundSummary(record: WorkflowRunRecord): string {
   return summary === undefined ? "Workflow completed. Open run history for the retained result." : truncateText(summary, SUMMARY_LIMIT);
 }
 
-function formatBackgroundDelivery(details: BackgroundWorkflowResultDetails): string {
+/**
+ * The host model only sees this text, never `details`. A woken agent acts on it at once, so it gets the
+ * result as the synchronous tool path renders it; a silent delivery keeps the summary. Both name the run's
+ * files so a later turn can read the retained result.
+ */
+function formatBackgroundDelivery(record: WorkflowRunRecord, details: BackgroundWorkflowResultDetails): string {
+  const woken = record.background?.origin.wakeOnComplete === true;
+  const usage = woken && record.state === "completed" ? formatWorkflowUsageLine(record.usage) : undefined;
   return [
     `## Background workflow: ${details.name}`,
     "",
-    `Run ID: ${details.runId}`,
+    // A resume, including an automatic one, has a new run id; name the run the agent started.
+    details.resumedFromRunId ? `Run ID: ${details.runId} (resumed from ${details.resumedFromRunId})` : `Run ID: ${details.runId}`,
     `State: ${details.status}`,
     "",
-    details.summary,
+    woken ? wokenDeliveryBody(record, details.summary) : details.summary,
+    "",
+    ...backgroundRunFileLines(record),
+    ...(usage === undefined ? [] : [usage]),
   ].join("\n");
 }
 
+function wokenDeliveryBody(record: WorkflowRunRecord, summary: string): string {
+  if (record.state !== "completed") return `Workflow ${record.state}: ${record.message}`;
+  return record.result.kind === "value" ? formatResultForContext(record.result.value) : summary;
+}
+
+/** The retained record, script and journal, relative to the workflow cwd like the synchronous result's lines. */
+function backgroundRunFileLines(record: WorkflowRunRecord): string[] {
+  return [
+    `Record: ${join(WORKFLOW_RUNS_DIR, `${record.runId}${WORKFLOW_RUN_RECORD_SUFFIX}`)}`,
+    ...formatWorkflowRunFileLines(record.runId, record.scriptFile !== undefined),
+  ];
+}
+
 function sessionHasBackgroundDelivery(ctx: ExtensionContext, runId: string): boolean {
   for (const entry of ctx.sessionManager.getEntries()) {
     if (entry.type !== "message" || entry.message.role !== "custom") continue;
@@ -361,6 +395,15 @@ function isPendingBackgroundOutcome(record: WorkflowRunRecord): record is Workfl
   return record.background?.delivery.state === "pending" && isDeliverableState(record.state);
 }
 
+/**
+ * A run started under Dynamax wakes the agent to act on its result; others arrive silently. So does a run
+ * the user stopped, or one paused with a resume already scheduled, whose successor wakes it instead.
+ */
+function wakesAgent(record: WorkflowRunRecord): boolean {
+  if (record.background?.origin.wakeOnComplete !== true || record.state === "stopped") return false;
+  return !(record.state === "paused" && record.pause?.autoResume === true);
+}
+
 function isDeliverableState(state: WorkflowRunState): state is "completed" | "failed" | "stopped" | "paused" {
   return state === "completed" || state === "failed" || state === "stopped" || state === "paused";
 }

package/.pi/extensions/pi-workflow-engine/src/cancellation.ts

@@ -13,6 +13,20 @@ export class WorkflowPauseError extends WorkflowAbortError {
   }
 }
 
+/**
+ * Abort reason for one agent the user skipped from the inspector. It deliberately does not extend
+ * WorkflowAbortError: the run carries on, so `parallel()`/`pipeline()` turn the skipped branch into a
+ * `null` slot while a direct `await agent()` sees this error.
+ */
+export class WorkflowAgentSkippedError extends Error {
+  override readonly name = "WorkflowAgentSkippedError";
+  readonly code = "WORKFLOW_AGENT_SKIPPED";
+
+  constructor(readonly label: string) {
+    super(`Workflow agent "${label}" was skipped by the user.`);
+  }
+}
+
 export function abortReason(signal: AbortSignal | undefined): Error {
   const reason = signal?.reason;
   if (safeInstanceOf(reason, Error)) return reason;

package/.pi/extensions/pi-workflow-engine/src/classify.ts

@@ -0,0 +1,107 @@
+import type { ClassifierAnswer, ClassifierApi, ClassifierContext, ClassifierModel } from "@earendil-works/pi-ai";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import type { RunContext } from "./agent-runner-types.ts";
+import { parseAgentModelRef } from "./model-ref.ts";
+import { assertWorkflowBudgetAvailable } from "./budget.ts";
+import { throwIfAborted } from "./cancellation.ts";
+import type { ClassifyOptions } from "./types.ts";
+
+type ClassifierRegistry = Pick<ModelRegistry, "classify" | "getAvailableOfType" | "getModelOfType">;
+
+/** No classifier model is configured, or the requested one is unknown. Recoverable inside `parallel`. */
+export class WorkflowClassifierUnavailableError extends Error {
+  readonly code = "WORKFLOW_CLASSIFIER_UNAVAILABLE";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "WorkflowClassifierUnavailableError";
+  }
+}
+
+/** The classifier answered with an error or no answer. Recoverable inside `parallel`. */
+export class WorkflowClassifierError extends Error {
+  readonly code = "WORKFLOW_CLASSIFIER_FAILED";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "WorkflowClassifierError";
+  }
+}
+
+/**
+ * `api.classify()`: answer typed questions about JSON state with a classifier model through the host's
+ * credentials, without a chat session. It shares the run's concurrency cap, budget, and per-agent timeout,
+ * records usage like an agent, and is not journaled, so a resumed run asks again.
+ */
+export async function runClassifier(
+  rc: RunContext,
+  context: ClassifierContext,
+  opts: ClassifyOptions = {},
+): Promise<Record<string, ClassifierAnswer>> {
+  const registry = rc.modelRegistry;
+  return await rc.semaphore.run(async () => {
+    assertWorkflowBudgetAvailable(rc.budget);
+    const model = await cachedClassifierModel(rc, registry, opts.model);
+    const label = opts.label ?? `classify:${model.provider}/${model.id}`;
+    // A stalled classifier must not hold a concurrency slot past the limit agents get.
+    const timeout = AbortSignal.timeout(rc.agentTimeoutMs);
+    const result = await registry.classify(model, context, { signal: rc.signal ? AbortSignal.any([rc.signal, timeout]) : timeout });
+    // One classifier response is one model response: recording it like one keeps per-model usage and the budget
+    // whole. Record before the abort check, since the provider charged for a call that returned as the run stopped.
+    rc.usage.recordAgentSession({
+      label,
+      phase: opts.phase,
+      messages: [{ role: "assistant", provider: result.provider, model: result.model, usage: result.usage }],
+    });
+    throwIfAborted(rc.signal);
+    if (result.stopReason !== "stop" && timeout.aborted) {
+      throw new WorkflowClassifierError(`${label}: classifier timed out after ${rc.agentTimeoutMs}ms`);
+    }
+    if (result.stopReason !== "stop") {
+      throw new WorkflowClassifierError(`${label}: classifier ${result.stopReason}${result.errorMessage ? `: ${result.errorMessage}` : ""}`);
+    }
+    return result.answers;
+  }, { signal: rc.signal });
+}
+
+/** One credential lookup per route and run; a route that failed to resolve keeps failing for the run. */
+function cachedClassifierModel(
+  rc: RunContext,
+  registry: ClassifierRegistry,
+  ref: string | readonly string[] | undefined,
+): Promise<ClassifierModel<ClassifierApi>> {
+  const key = JSON.stringify(ref ?? null);
+  const cached = rc.classifierRoutes?.get(key);
+  if (cached) return cached;
+  const resolved = resolveClassifierModel(registry, ref);
+  rc.classifierRoutes?.set(key, resolved);
+  return resolved;
+}
+
+async function resolveClassifierModel(
+  registry: ClassifierRegistry,
+  ref: string | readonly string[] | undefined,
+): Promise<ClassifierModel<ClassifierApi>> {
+  if (ref !== undefined && typeof ref !== "string") {
+    const available = await registry.getAvailableOfType("classifier");
+    const preferred = ref.map((candidate) => parseAgentModelRef(candidate))
+      .map(({ provider, id }) => available.find((model) => model.provider === provider && model.id === id))
+      .find((model) => model !== undefined);
+    if (!preferred) throw new WorkflowClassifierUnavailableError(`None of the classifier models ${ref.join(", ")} has working credentials.`);
+    return preferred;
+  }
+  if (ref === undefined) {
+    const [available] = await registry.getAvailableOfType("classifier");
+    if (!available) {
+      throw new WorkflowClassifierUnavailableError(
+        "No classifier model has working credentials. Configure one (for example TypeSafe Jev via OpenRouter) or pass { model: \"provider/id\" }.",
+      );
+    }
+    return available;
+  }
+  // Same ref rules as agent({ model }): malformed refs throw, bare ids mean Anthropic.
+  const { provider, id } = parseAgentModelRef(ref);
+  const model = registry.getModelOfType("classifier", provider, id);
+  if (!model) throw new WorkflowClassifierUnavailableError(`Classifier model "${ref}" not found (resolved as ${provider}/${id}).`);
+  return model;
+}

package/.pi/extensions/pi-workflow-engine/src/codemode-slots.ts

@@ -0,0 +1,73 @@
+import type { AgentSession, ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { Semaphore } from "./concurrency.ts";
+
+/**
+ * pi runs at most this many codemode scripts per process, and rejects one more with "Codemode worker
+ * limit reached" instead of waiting (pi 1.3 `extensions/codemode/execute.js`). Every subagent shares
+ * that limit with the others and with the host, so a fan-out of codemode agents would fail calls.
+ */
+export const CODEMODE_WORKER_SLOTS = 2;
+
+const processSlots = new Semaphore(CODEMODE_WORKER_SLOTS);
+
+/**
+ * Queue a subagent's top-level calls to `toolName` for one of the process-wide codemode slots, so a
+ * call waits for a running script instead of failing. pi frees its own slot only once the worker has
+ * exited, which can lag the result on Bun, so a call can still meet pi's limit now and then. The host's
+ * own codemode calls are not queued. A session using it must run its tool calls one at a time
+ * ({@link runToolCallsSequentially}).
+ */
+export function createCodemodeSlotExtension(toolName: string, slots: Semaphore = processSlots): ExtensionFactory {
+  return (pi) => {
+    const held = new Map<string, () => void>();
+    const release = (toolCallId: string): void => {
+      held.get(toolCallId)?.();
+      held.delete(toolCallId);
+    };
+    // A call another handler blocks after this one took a slot never runs, so the turn's end frees it.
+    const releaseAll = (): void => {
+      for (const toolCallId of [...held.keys()]) release(toolCallId);
+    };
+
+    pi.on("tool_call", async (event, ctx) => {
+      // A script's nested calls run inside the slot its own call holds.
+      if (event.toolName !== toolName || event.parentToolCallId !== undefined) return undefined;
+      // Rejects while queued once the agent is aborted; pi then blocks the call.
+      await new Promise<void>((acquired, failed) => {
+        slots
+          .run(
+            () =>
+              new Promise<void>((done) => {
+                held.set(event.toolCallId, done);
+                acquired();
+              }),
+            { signal: ctx.signal },
+          )
+          .catch(failed);
+      });
+      return undefined;
+    });
+    pi.on("tool_execution_end", (event) => release(event.toolCallId));
+    pi.on("tool_result", (event) => {
+      release(event.toolCallId);
+      return undefined;
+    });
+    pi.on("turn_end", () => {
+      releaseAll();
+      return undefined;
+    });
+    pi.on("session_shutdown", releaseAll);
+  };
+}
+
+/**
+ * Run a codemode session's tool calls one at a time. pi's default "parallel" execution runs every call's
+ * `tool_call` hook before it executes any (pi-agent-core `executeToolCallsParallel`), so a message with
+ * more codemode calls than free slots would leave the calls holding slots waiting on the one queued
+ * behind them until the agent timed out, and starve every other codemode agent. In order, each call
+ * has freed its slot before the next call asks for one. pi then also runs the calls a script makes one
+ * at a time (`NestedToolCallRunner`).
+ */
+export function runToolCallsSequentially(session: Pick<AgentSession, "agent">): void {
+  session.agent.toolExecution = "sequential";
+}