@fyeeme/pi-dynamic-workflows 2.0.1 → 2.0.2

package/README.md

@@ -180,6 +180,9 @@ defineWorkflow({
 // results: { candidates, winner, judges: [{winner, reason}] }
 
 // Classify input, then run the matching route's sub-steps.
+// On pi 0.99+ hosts with a classifier model, the category comes from
+// ModelRuntime.classify() (no classification subprocess); without one, an
+// agent answers the classification. The step result records which path ran.
 defineWorkflow({
 	name: "route",
 	steps: [
@@ -195,7 +198,7 @@ defineWorkflow({
 		},
 	],
 });
-// results: { category, matched, route: StepResult[], routeStatus }
+// results: { category, matched, route: StepResult[], routeStatus, path }
 ```
 
 Judge/classifier JSON is parsed leniently (LLMs return `"true"`/`"0"` as strings); route nesting is depth-capped to catch cycles.
@@ -314,7 +317,7 @@ const result = await runWorkflow({ workflow: wf, cwd: tempDir, now: 1000, dispat
 | `loop_until` | `prompt(ctx,i)`, `until(ctx,i)`, `maxIterations?` | array of per-iteration outputs |
 | `adversarial` | `produce`, `rubric[]`, `judges?`, `minPass?` | `{ candidate, passed, passCount, judges }` |
 | `tournament` | `candidates`, `judges`, `produce` | `{ candidates, winner, judges }` |
-| `classify_route` | `classifier`, `routes: Record<cat, Step[]>`, `fallback?` | `{ category, matched, route, routeStatus }` |
+| `classify_route` | `classifier`, `routes: Record<cat, Step[]>`, `fallback?` | `{ category, matched, route, routeStatus, path }` |
 | `sub_workflow` | `workflow: WorkflowDefinition`, `input?`, `inheritBudget?` | `{ steps, status, workflowName, error }` |
 | `loop_until_dry` | `agent(item, i)`, `keyOf?`, `merge?`, `maxRounds?`, `dryThreshold?` | array of discovered items |
 

package/README.zh-CN.md

@@ -185,7 +185,7 @@ defineWorkflow({
 		},
 	],
 });
-// results: { category, matched, route: StepResult[], routeStatus }
+// results: { category, matched, route: StepResult[], routeStatus, path }
 ```
 
 评判/分类的 JSON 采用宽松解析（LLM 常把 `"true"`/`"0"` 当字符串返回）；路由嵌套有深度上限以防循环。

package/index.ts

@@ -20,6 +20,7 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import piSubagents from "@fyeeme/pi-subagents";
 import { defineWorkflow, runWorkflow } from "./src/index.ts";
+import { createClassifyHook } from "./src/classifier-hook.ts";
 import type { Budget, StepContext, StepDefinition, WorkflowDefinition } from "./src/types.ts";
 import { WorkflowError } from "./src/errors.ts";
 import { discoverWorkflowLibrary, loadLibraryWorkflow } from "./src/library.ts";
@@ -80,7 +81,7 @@ const StepSchema = Type.Union([
 	Type.Object({
 		id: Type.String(),
 		type: Type.Literal("classify_route"),
-		prompt: Type.String({ description: "Classifier prompt; agent should reply {category: \"...\"}" }),
+		prompt: Type.String({ description: "Classification prompt; routing runs on a classifier model when the host has one (pi 0.99), otherwise an agent replies with JSON {category: \"...\"}" }),
 		routes: Type.Record(
 			Type.String(),
 			Type.Array(Type.Object({ id: Type.String(), prompt: Type.String(), model: Type.Optional(Type.String()) })),
@@ -413,6 +414,9 @@ export default function (pi: ExtensionAPI): void {
 					cwd: params.cwd ?? ctx.cwd,
 					now: params.now ?? Date.now(),
 					signal,
+					// pi 0.99 classifier routing: classify_route prefers ModelRuntime.classify()
+					// when a classifier model is available; otherwise the agent path runs.
+					classify: createClassifyHook(ctx.modelRegistry),
 				});
 
 				const lines = [

package/package.json

@@ -1,67 +1,68 @@
 {
-  "name": "@fyeeme/pi-dynamic-workflows",
-  "version": "2.0.1",
-  "description": "Deterministic TypeScript workflow orchestration for pi. Fuses the pi-dynamic-workflows design (declarative graph, 10 step primitives, heuristic planner, outcome collectors) with Claude Code's workflow engine coordination mechanisms (deterministic sandbox, cache-key resume, per-agent abort map, dynamic budget, runaway caps).",
-  "type": "module",
-  "license": "MIT",
-  "author": "fyeeme",
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "pi-package",
-    "pi",
-    "dynamic-workflow",
-    "workflow",
-    "orchestration",
-    "fan-out",
-    "pipeline",
-    "multi-agent"
-  ],
-  "files": [
-    "*.ts",
-    "src/**/*.ts",
-    "sessions/**/*.ts",
-    "workflows/**/*.ts",
-    "skills/**/*.md",
-    "prompts/**/*.md",
-    "README.md",
-    "README.zh-CN.md",
-    "LICENSE"
-  ],
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ],
-    "skills": [
-      "skills/workflow-author"
-    ],
-    "prompts": [
-      "prompts"
-    ]
-  },
-  "scripts": {
-    "test": "vitest --run",
-    "typecheck": "tsc"
-  },
-  "dependencies": {
-    "@fyeeme/pi-subagents": "2.1.1"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.84.4",
-    "@earendil-works/pi-coding-agent": ">=0.84.4",
-    "@earendil-works/pi-tui": ">=0.84.4",
-    "jiti": ">=2.0.0",
-    "typebox": ">=1.0.0",
-    "typescript": ">=5.0.0"
-  },
-  "devDependencies": {
-    "@earendil-works/pi-ai": "0.84.4",
-    "@earendil-works/pi-coding-agent": "0.84.4",
-    "@earendil-works/pi-tui": "0.84.4",
-    "@types/node": "22.19.19",
-    "jiti": "2.7.0",
-    "typebox": "1.1.38",
-    "typescript": "5.9.3"
-  }
+	"name": "@fyeeme/pi-dynamic-workflows",
+	"version": "2.0.2",
+	"description": "Deterministic TypeScript workflow orchestration for pi. Fuses the pi-dynamic-workflows design (declarative graph, 10 step primitives, heuristic planner, outcome collectors) with Claude Code's workflow engine coordination mechanisms (deterministic sandbox, cache-key resume, per-agent abort map, dynamic budget, runaway caps).",
+	"type": "module",
+	"license": "MIT",
+	"author": "fyeeme",
+	"engines": {
+		"node": ">=18"
+	},
+	"keywords": [
+		"pi-package",
+		"pi",
+		"dynamic-workflow",
+		"workflow",
+		"orchestration",
+		"fan-out",
+		"pipeline",
+		"multi-agent"
+	],
+	"files": [
+		"*.ts",
+		"src/**/*.ts",
+		"sessions/**/*.ts",
+		"workflows/**/*.ts",
+		"skills/**/*.md",
+		"prompts/**/*.md",
+		"README.md",
+		"README.zh-CN.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		],
+		"skills": [
+			"skills/workflow-author"
+		],
+		"prompts": [
+			"prompts"
+		]
+	},
+	"scripts": {
+		"test": "vitest --run",
+		"typecheck": "tsc"
+	},
+	"dependencies": {
+		"@fyeeme/pi-subagents": "2.1.1"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": ">=0.99.0",
+		"@earendil-works/pi-coding-agent": ">=0.99.0",
+		"@earendil-works/pi-tui": ">=0.99.0",
+		"jiti": ">=2.0.0",
+		"typebox": ">=1.0.0",
+		"typescript": ">=5.0.0"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-ai": "0.99.2",
+		"@earendil-works/pi-coding-agent": "0.99.2",
+		"@earendil-works/pi-agent-core": "0.99.2",
+		"@earendil-works/pi-tui": "0.99.2",
+		"@types/node": "22.19.19",
+		"jiti": "2.7.0",
+		"typebox": "1.1.38",
+		"typescript": "5.9.3"
+	}
 }

package/src/classifier-hook.ts

@@ -0,0 +1,56 @@
+/**
+ * classify_route classifier hook — pi 0.99 `ModelRuntime.classify()` path.
+ *
+ * Model discovery (design D3): a step-declared `model` is honored only when it
+ * resolves to a classifier-type model with working credentials; otherwise the
+ * first available classifier on the host. None → `undefined` (the runner falls
+ * back to the agent path). The choice question's criteria are the route names;
+ * the answer is returned verbatim so undeclared categories resolve through
+ * fallback sub-steps exactly like the agent path (Routing equivalence).
+ */
+import type { ClassifierApi, ClassifierContext, ClassifierModel, ClassifierResult } from "@earendil-works/pi-ai";
+import type { ClassifyHook } from "./types.ts";
+
+/** The registry surface the hook needs — satisfied by the extension context's
+ *  ModelRegistry (pi 0.99+); tests mock this narrow slice. */
+export interface ClassifierRegistrySlice {
+	getAvailableOfType(type: "classifier"): Promise<readonly ClassifierModel<ClassifierApi>[]>;
+	classify(model: ClassifierModel<ClassifierApi>, context: ClassifierContext): Promise<ClassifierResult>;
+}
+
+export function createClassifyHook(registry: ClassifierRegistrySlice): ClassifyHook {
+	return async (prompt, routeNames, model) => {
+		const available = await registry.getAvailableOfType("classifier");
+		if (available.length === 0) return undefined;
+		const chosen = (model ? available.find((m) => m.id === model) : undefined) ?? available[0]!;
+
+		const result = await registry.classify(chosen, {
+			state: { prompt, routes: [...routeNames] },
+			questions: {
+				route: {
+					type: "choice",
+					instructions: prompt,
+					criteria: Object.fromEntries(routeNames.map((name) => [name, name])),
+				},
+			},
+		});
+		if (result.stopReason !== "stop") return undefined;
+		const answer = result.answers.route;
+		if (answer?.type !== "choice") return undefined;
+
+		const u = result.usage;
+		return {
+			category: answer.choice,
+			usage: u
+				? {
+						input: u.input ?? 0,
+						output: u.output ?? 0,
+						cacheRead: u.cacheRead ?? 0,
+						cacheWrite: u.cacheWrite ?? 0,
+						totalTokens: u.totalTokens ?? (u.input ?? 0) + (u.output ?? 0),
+						cost: u.cost?.total ?? 0,
+					}
+				: undefined,
+		};
+	};
+}

package/src/runner/index.ts

@@ -19,7 +19,7 @@ import { BudgetPool } from "../budget/index.ts";
 import { Journal, type RunManifest } from "../cache/index.ts";
 import type { AgentLifecycleListeners } from "../lifecycle.ts";
 import { generateRunId } from "../state/index.ts";
-import type { Budget, RunResult, WorkflowDefinition } from "../types.ts";
+import type { Budget, ClassifyHook, RunResult, WorkflowDefinition } from "../types.ts";
 import {
 	createSpawnRegistry,
 	spawnAgent,
@@ -73,6 +73,11 @@ export interface RunWorkflowOptions {
 	/** A6: policy gate invoked before the first dispatch. Return { allow: false,
 	 *  reason } to deny the run with a policy-gate error. */
 	readonly policyGate?: (workflow: WorkflowDefinition) => { readonly allow: boolean; readonly reason?: string } | Promise<{ readonly allow: boolean; readonly reason?: string }>;
+	/** pi 0.99 classifier hook for classify_route steps: when provided and a
+	 *  classifier model is available, route categories come from
+	 *  ModelRuntime.classify() instead of a spawned classification agent;
+	 *  unavailability and failures fall back to the agent path. */
+	readonly classify?: ClassifyHook;
 }
 
 export async function runWorkflow(opts: RunWorkflowOptions): Promise<RunResult> {
@@ -136,6 +141,7 @@ export async function runWorkflow(opts: RunWorkflowOptions): Promise<RunResult>
 		maxPromptBytes: opts.maxPromptBytes ?? DEFAULT_MAX_PROMPT_BYTES,
 		degradedStepIds: new Set(),
 		allowChildRecursion: opts.allowChildRecursion ?? false,
+		classify: opts.classify,
 		dispatched: 0,
 	};
 

package/src/runner/stage-executor.ts

@@ -35,6 +35,7 @@ import type {
 	AgentCallSpec,
 	AgentOpts,
 	AgentStep,
+	ClassifyHook,
 	ClassifyRouteStep,
 	CodeStep,
 	LoopUntilDryStep,
@@ -81,6 +82,9 @@ export interface StepExecContext {
 	budgetPolicy: "throw" | "null";
 	/** A6: max resolved-prompt byte size; oversize throws a size-limit error. */
 	maxPromptBytes: number;
+	/** pi 0.99 classifier hook for classify_route (undefined → agent path only).
+	 *  See ClassifyHook / spec workflow-classifier-routing. */
+	readonly classify?: ClassifyHook;
 	/** A3: step ids that degraded to null under the "null" policy this run. */
 	degradedStepIds: Set<string>;
 	/** Recursion opt-in propagated to every spawned workflow sub-agent: when
@@ -555,28 +559,63 @@ async function execTournament(step: TournamentStep, ctx: StepContext, exec: Step
 async function execClassifyRoute(step: ClassifyRouteStep, ctx: StepContext, exec: StepExecContext): Promise<StepResult> {
 	const start = Date.now();
 	const classifyPrompt = await resolvePrompt(step.classifier, ctx);
-	const classify = await dispatchAgentCall(`${step.id}#classify`, classifyPrompt, step.classifier, exec);
-	if (!classify.ok) {
-		return stepResult(
-			step.id,
-			"classify_route",
-			classify.aborted ? "skipped" : "failed",
-			undefined,
-			withDuration(classify.stats, start),
-			undefined,
-			classify.aborted ? undefined : "dispatch-error",
-		);
+
+	// pi 0.99 classifier path first (spec: workflow-classifier-routing): when a
+	// classifier hook is available and answers, the category comes from its
+	// ranked choice and no classification subprocess is spawned. Unavailable or
+	// failing hook → the original agent path, unchanged (fallback contract).
+	let classifyPath: "classifier" | "agent" = "agent";
+	let category = "";
+	let classifyStats: StepStats = zeroStats;
+	if (exec.classify) {
+		try {
+			const hookResult = await exec.classify(classifyPrompt, Object.keys(step.routes), step.classifier.model);
+			if (hookResult) {
+				classifyPath = "classifier";
+				category = parseCategoryStr(hookResult.category);
+				const u = hookResult.usage;
+				classifyStats = {
+					tokens: u ? u.totalTokens : 0,
+					cost: u ? u.cost : 0,
+					durationMs: 0,
+					agents: 0,
+					failures: 0,
+					usage: u
+						? { input: u.input, output: u.output, cacheRead: u.cacheRead, cacheWrite: u.cacheWrite }
+						: undefined,
+				};
+			}
+		} catch {
+			// classifier call failed → agent fallback (spec: Fallback to the agent path)
+		}
 	}
 
-	// A3: a degraded classifier (budget exhausted under the "null" policy)
-	// returns value null — the step degrades to a null result per the README
-	// contract; do not fabricate a route run from an empty category.
-	if (classify.value === null) {
-		return stepResult(step.id, "classify_route", "done", null, withDuration(classify.stats, start));
+	if (classifyPath === "agent") {
+		const classify = await dispatchAgentCall(`${step.id}#classify`, classifyPrompt, step.classifier, exec);
+		if (!classify.ok) {
+			return stepResult(
+				step.id,
+				"classify_route",
+				classify.aborted ? "skipped" : "failed",
+				undefined,
+				withDuration(classify.stats, start),
+				undefined,
+				classify.aborted ? undefined : "dispatch-error",
+			);
+		}
+
+		// A3: a degraded classifier (budget exhausted under the "null" policy)
+		// returns value null — the step degrades to a null result per the README
+		// contract; do not fabricate a route run from an empty category.
+		if (classify.value === null) {
+			return stepResult(step.id, "classify_route", "done", null, withDuration(classify.stats, start));
+		}
+
+		const parsed = parseFirstJson(classify.value ?? "") as { category?: unknown } | undefined;
+		category = parseCategoryStr(parsed?.category);
+		classifyStats = classify.stats;
 	}
 
-	const parsed = parseFirstJson(classify.value ?? "") as { category?: unknown } | undefined;
-	const category = parseCategoryStr(parsed?.category);
 	const routeSteps = step.routes[category] ?? step.fallback ?? [];
 
 	exec.depth++;
@@ -592,8 +631,8 @@ async function execClassifyRoute(step: ClassifyRouteStep, ctx: StepContext, exec
 		step.id,
 		"classify_route",
 		status,
-		{ category, matched: category in step.routes, route: sub.steps, routeStatus: sub.status },
-		withDuration(addStats(classify.stats, aggregateStats(sub.steps.map((s) => s.stats), 0)), start),
+		{ category, matched: category in step.routes, route: sub.steps, routeStatus: sub.status, path: classifyPath },
+		withDuration(addStats(classifyStats, aggregateStats(sub.steps.map((s) => s.stats), 0)), start),
 		undefined,
 		sub.errorCategory,
 	);

package/src/types.ts

@@ -49,6 +49,36 @@ export interface Budget {
 // Step statistics + result
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// classify_route classifier hook (pi 0.99 ModelRuntime.classify)
+// ---------------------------------------------------------------------------
+
+/** Result of a successful classifier-path classification for classify_route.
+ *  `category` is the classifier's chosen route name (may be undeclared — the
+ *  runner resolves it through fallback sub-steps exactly like the agent path). */
+export interface ClassifyHookResult {
+	readonly category: string;
+	/** Classifier token usage for truthful step stats; omit when unknown. */
+	readonly usage?: {
+		readonly input: number;
+		readonly output: number;
+		readonly cacheRead: number;
+		readonly cacheWrite: number;
+		readonly totalTokens: number;
+		readonly cost: number;
+	};
+}
+
+/** Optional classifier hook injected by the extension entry (spec:
+ *  workflow-classifier-routing). Returns undefined when no classifier model is
+ *  available; a throw also falls back to the agent path. Route sub-steps still
+ *  run as agent dispatches either way. */
+export type ClassifyHook = (
+	prompt: string,
+	routeNames: readonly string[],
+	model?: string,
+) => Promise<ClassifyHookResult | undefined>;
+
 export interface StepStats {
 	readonly tokens: number;
 	readonly cost: number;