@oisincoveney/pipeline 2.3.1 → 2.4.0

package/defaults/pipeline.yaml

@@ -2,6 +2,13 @@ version: 1
 default_workflow: inspect
 orchestrator:
   profile: moka-orchestrator
+token_budget:
+  default_context_window: 200000
+  max_context_pct: 50
+  fan_out_width:
+    default: 4
+    by_category:
+      green: 2
 entrypoints:
   quick:
     schedule: quick-schedule

package/dist/config/load.js

@@ -51,6 +51,7 @@ function parsePipelineConfigParts(sources, projectRoot, sourcePaths = {
 		schedules: pipeline.schedules,
 		skills: profiles.skills,
 		...pipeline.task_context ? { task_context: pipeline.task_context } : {},
+		token_budget: pipeline.token_budget,
 		version: 1,
 		workflows: pipeline.workflows
 	}, projectRoot, options);

package/dist/config/schemas.d.ts

@@ -116,6 +116,7 @@ declare const workflowNodeBaseSchema: z.ZodObject<{
 }, z.core.$strip>;
 type WorkflowNodeBase = z.infer<typeof workflowNodeBaseSchema>;
 type AgentWorkflowNode = WorkflowNodeBase & {
+  category?: string;
   kind: "agent";
   profile: string;
 };
@@ -491,6 +492,15 @@ declare const configSchema: z.ZodObject<{
   task_context: z.ZodOptional<z.ZodObject<{
     type: z.ZodString;
   }, z.core.$loose>>;
+  token_budget: z.ZodDefault<z.ZodObject<{
+    default_context_window: z.ZodDefault<z.ZodNumber>;
+    max_context_pct: z.ZodDefault<z.ZodNumber>;
+    model_context_windows: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    fan_out_width: z.ZodDefault<z.ZodObject<{
+      default: z.ZodDefault<z.ZodNumber>;
+      by_category: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>>;
   version: z.ZodLiteral<1>;
   workflows: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;

package/dist/config/schemas.js

@@ -380,6 +380,7 @@ const workflowNodeBaseSchema = z.object({
 });
 const workflowNodeSchema = z.lazy(() => z.discriminatedUnion("kind", [
 	workflowNodeBaseSchema.extend({
+		category: z.string().min(1).optional(),
 		kind: z.literal("agent"),
 		profile: z.string()
 	}).strict(),
@@ -438,6 +439,28 @@ const profilesFileSchema = z.object({
 	skills: strictRecord(pathRefSchema).default({}),
 	version: z.literal(1)
 }).strict();
+const fanOutWidthSchema = z.object({
+	default: z.number().int().positive().default(4),
+	by_category: strictRecord(z.number().int().positive()).default({})
+}).strict();
+const tokenBudgetSchema = z.object({
+	default_context_window: z.number().int().positive().default(2e5),
+	max_context_pct: z.number().positive().max(100).default(50),
+	model_context_windows: strictRecord(z.number().int().positive()).default({}),
+	fan_out_width: fanOutWidthSchema.default({
+		default: 4,
+		by_category: {}
+	})
+}).strict();
+const DEFAULT_TOKEN_BUDGET = {
+	default_context_window: 2e5,
+	max_context_pct: 50,
+	model_context_windows: {},
+	fan_out_width: {
+		default: 4,
+		by_category: {}
+	}
+};
 const pipelineFileSchema = z.object({
 	default_workflow: z.string(),
 	entrypoints: strictRecord(entrypointSchema).default({}),
@@ -459,6 +482,7 @@ const pipelineFileSchema = z.object({
 	}),
 	schedules: strictRecord(schedulePolicySchema).default({}),
 	task_context: taskContextResolverSchema.optional(),
+	token_budget: tokenBudgetSchema.default(DEFAULT_TOKEN_BUDGET),
 	workflows: strictRecord(workflowSchema).default({}),
 	version: z.literal(1)
 }).strict();
@@ -489,6 +513,7 @@ const configSchema = z.object({
 	schedules: strictRecord(schedulePolicySchema).default({}),
 	skills: strictRecord(pathRefSchema).default({}),
 	task_context: taskContextResolverSchema.optional(),
+	token_budget: tokenBudgetSchema.default(DEFAULT_TOKEN_BUDGET),
 	version: z.literal(1),
 	workflows: strictRecord(workflowSchema).default({})
 }).strict().superRefine(validateConfigReferences);

package/dist/config/validate.js

@@ -35,12 +35,28 @@ function validatePipelineConfig(rawConfig, projectRoot, options = {}) {
 		validateProfile(profileId, profile, runner, config, issues, projectRoot, options);
 	}
 	validateHookConfig(config, issues, projectRoot, options);
+	validateTokenBudget(config, issues);
 	for (const [ruleId, rule] of Object.entries(config.rules)) validatePath(`rules.${ruleId}.path`, rule, projectRoot, issues, options);
 	for (const [skillId, skill] of Object.entries(config.skills)) validatePath(`skills.${skillId}.path`, skill, projectRoot, issues, options);
 	for (const [workflowId, workflow] of Object.entries(config.workflows)) validateWorkflow(workflowId, workflow, config, issues, projectRoot, options);
 	if (issues.length > 0) throw validationError(issues);
 	return config;
 }
+function knownNodeCategories(config) {
+	const categories = /* @__PURE__ */ new Set();
+	for (const catalog of Object.values(config.scheduler.node_catalogs)) {
+		for (const category of catalog.required_categories) categories.add(category);
+		for (const node of Object.values(catalog.nodes)) categories.add(node.category);
+	}
+	return categories;
+}
+function validateTokenBudget(config, issues) {
+	const known = knownNodeCategories(config);
+	for (const category of Object.keys(config.token_budget.fan_out_width.by_category)) if (!known.has(category)) issues.push({
+		path: `token_budget.fan_out_width.by_category.${category}`,
+		message: `fan-out width cap references unknown node category '${category}'`
+	});
+}
 function validateRegistryIds(name, registry, issues) {
 	for (const id of Object.keys(registry)) if (!ID_RE.test(id)) issues.push({
 		path: `${name}.${id}`,

package/dist/model-resolver.js

@@ -1,21 +1,42 @@
 //#region src/model-resolver.ts
 const DISABLED_MODELS_ENV = "PIPELINE_DISABLED_MODELS";
-function selectNodeModel(node) {
-	return fallbackModelSelection(node.models ?? []);
+function selectNodeModel(node, options) {
+	return fallbackModelSelection(node.models ?? [], options);
 }
-function fallbackModelSelection(models) {
+function fallbackModelSelection(models, options) {
 	if (models.length === 0) return {
 		reason: "node declares no model fallback array",
 		skipped: []
 	};
-	return enabledModelSelection(models, disabledModels());
+	const disabled = disabledModels();
+	const enabled = models.filter((candidate) => !disabled.has(candidate));
+	const disabledSkipped = models.filter((candidate) => disabled.has(candidate));
+	if (!options) {
+		const model = enabled[0];
+		return {
+			model,
+			reason: selectionReason(model),
+			skipped: disabledSkipped
+		};
+	}
+	return sizedSelection(enabled, disabledSkipped, options);
 }
-function enabledModelSelection(models, disabled) {
-	const model = models.find((candidate) => !disabled.has(candidate));
+function sizedSelection(enabled, disabledSkipped, options) {
+	const { estimatedTokens, budget } = options;
+	const required = estimatedTokens / (budget.max_context_pct / 100);
+	const tooSmall = [];
+	for (const candidate of enabled) {
+		const window = budget.model_context_windows[candidate] ?? budget.default_context_window;
+		if (window >= required) return {
+			model: candidate,
+			reason: `selected '${candidate}' (window ${window}) — holds estimated ${estimatedTokens} tokens within the ${budget.max_context_pct}% context cap`,
+			skipped: [...disabledSkipped, ...tooSmall]
+		};
+		tooSmall.push(candidate);
+	}
 	return {
-		model,
-		reason: selectionReason(model),
-		skipped: models.filter((candidate) => disabled.has(candidate))
+		reason: `estimated context ${estimatedTokens} tokens exceeds ${budget.max_context_pct}% of every available model window`,
+		skipped: [...disabledSkipped, ...tooSmall]
 	};
 }
 function selectionReason(model) {

package/dist/planning/compile.d.ts

@@ -15,6 +15,7 @@ declare class WorkflowPlannerError extends Error {
 interface PlannedWorkflowNode {
   artifacts?: WorkflowNode["artifacts"];
   builtin?: string;
+  category?: string;
   children?: PlannedWorkflowNode[];
   command?: string[];
   dependents: string[];

package/dist/planning/compile.js

@@ -185,10 +185,14 @@ function createWorkflowGraph(nodes, nodeIds = new Set(nodes.map((node) => node.i
 function uniqueExistingNeeds(node, nodeIds) {
 	return uniqueStrings(node.needs.filter((need) => nodeIds.has(need)));
 }
+function agentNodeCategory(node) {
+	return node.kind === "agent" ? node.category : void 0;
+}
 function toPlannedNode(node, index) {
 	const planned = {
 		artifacts: node.artifacts,
 		builtin: "builtin" in node ? node.builtin : void 0,
+		category: agentNodeCategory(node),
 		command: "command" in node ? node.command : void 0,
 		children: node.kind === "parallel" ? node.nodes.map((child, childIndex) => toPlannedNode(child, childIndex)) : void 0,
 		dependents: [],

package/dist/planning/generate.d.ts

@@ -94,6 +94,7 @@ declare const scheduleArtifactSchema: z.ZodObject<{
       } | undefined;
       timeout_ms?: number | undefined;
     } & {
+      category?: string;
       kind: "agent";
       profile: string;
     }) | ({
@@ -478,6 +479,7 @@ declare const scheduleArtifactSchema: z.ZodObject<{
         } | undefined;
         timeout_ms?: number | undefined;
       } & {
+        category?: string;
         kind: "agent";
         profile: string;
       }) | ({
@@ -861,6 +863,7 @@ declare const scheduleArtifactSchema: z.ZodObject<{
       } | undefined;
       timeout_ms?: number | undefined;
     } & {
+      category?: string;
       kind: "agent";
       profile: string;
     }) | ({
@@ -1245,6 +1248,7 @@ declare const scheduleArtifactSchema: z.ZodObject<{
         } | undefined;
         timeout_ms?: number | undefined;
       } & {
+        category?: string;
         kind: "agent";
         profile: string;
       }) | ({

package/dist/runtime/agent-node/agent-node.js

@@ -8,6 +8,7 @@ import { emit, emitAgentFinish, emitAgentStart } from "../events/events.js";
 import "../events/index.js";
 import { gatewayServerForProfile } from "../../mcp/gateway.js";
 import { selectNodeModel } from "../../model-resolver.js";
+import { estimateTokens } from "../../token-estimator.js";
 import { readFileSync } from "node:fs";
 //#region src/runtime/agent-node/agent-node.ts
 async function executeAgentNode(node, context, attempt) {
@@ -17,7 +18,17 @@ async function executeAgentNode(node, context, attempt) {
 		output: ""
 	};
 	const prompt = renderAgentPrompt(node, context);
-	const modelSelection = selectNodeModel(node);
+	const decision = decideNodeModel(prompt, node, context.config.token_budget);
+	if (decision.overBudget) return {
+		evidence: [
+			`agent boundary node=${node.id} profile=${node.profile}`,
+			`over token budget: ${decision.selection.reason}`,
+			...decision.selection.skipped.length ? [`model fallbacks skipped: ${decision.selection.skipped.join(", ")}`] : []
+		],
+		exitCode: 1,
+		output: ""
+	};
+	const modelSelection = decision.selection;
 	const plan = createRunnerLaunchPlan(context.config, {
 		model: modelSelection.model,
 		nodeId: node.id,
@@ -55,6 +66,7 @@ async function executeAgentNode(node, context, attempt) {
 	return {
 		evidence: [
 			`agent boundary node=${node.id} profile=${node.profile} runner=${plan.runnerId}`,
+			`estimated context tokens: ${decision.estimatedTokens}`,
 			`model selection: ${modelSelection.model ?? "profile/default"} (${modelSelection.reason})`,
 			...modelSelection.skipped.length ? [`model fallbacks skipped: ${modelSelection.skipped.join(", ")}`] : [],
 			...finalized.evidence,
@@ -66,6 +78,30 @@ async function executeAgentNode(node, context, attempt) {
 		timedOut: result.timedOut
 	};
 }
+/**
+* Pure model-routing decision for a node: estimate the assembled prompt size and
+* pick the smallest fallback model whose window holds it within the context cap.
+* A node with no fallback array keeps the legacy (size-unaware) selection. A node
+* with a fallback array but no fitting model is `overBudget` — the caller fails
+* it fast rather than truncating.
+*/
+function decideNodeModel(prompt, node, budget) {
+	const estimatedTokens = estimateTokens(prompt);
+	if (!(budget && node.models?.length)) return {
+		estimatedTokens,
+		overBudget: false,
+		selection: selectNodeModel(node)
+	};
+	const selection = selectNodeModel(node, {
+		budget,
+		estimatedTokens
+	});
+	return {
+		estimatedTokens,
+		overBudget: !selection.model,
+		selection
+	};
+}
 async function finalizeAgentOutput(inputs) {
 	const { attempt, context, node, normalized, plan, result } = inputs;
 	const validStructuredOutput = selectValidStructuredOutput(context, node, normalized, plan, result.stdout);

package/dist/runtime/scheduler.js

@@ -15,10 +15,12 @@ var LocalScheduler = class {
 			emitWorkflowStarted: () => options.emitWorkflowStarted(context),
 			executeWorkflow: () => runWorkflowScheduler({
 				failFast: plan.execution.failFast,
+				fanOutWidth: context.config.token_budget?.fan_out_width,
 				isCancelled: () => options.isCancelled(context),
 				markNodeReady: (nodeId) => options.markNodeReady(nodeId, context),
 				maxParallelNodes: context.maxParallelNodes,
 				nodes: plan.topologicalOrder.map((node) => ({
+					category: node.category,
 					dependents: node.dependents,
 					id: node.id,
 					index: node.index,
@@ -38,6 +40,7 @@ async function runWorkflowScheduler(input) {
 		blocked: [],
 		completed: [],
 		failFast: input.failFast,
+		fanOutWidth: input.fanOutWidth,
 		maxParallelNodes: input.maxParallelNodes,
 		nodes: orderedNodes(input.nodes),
 		running: [],
@@ -107,7 +110,7 @@ function unstartedBlockingDescendants(nodeId, context) {
 function launchReadyNodes(input, state, running) {
 	const capacity = workflowNodeCapacity(state);
 	if (capacity <= 0) return;
-	for (const nodeId of readyNodeIds(state).slice(0, capacity)) {
+	for (const nodeId of selectLaunchableNodes(state, capacity)) {
 		input.markNodeReady(nodeId);
 		state.running = [...state.running, nodeId];
 		running.set(nodeId, {
@@ -116,6 +119,50 @@ function launchReadyNodes(input, state, running) {
 		});
 	}
 }
+/**
+* Choose which ready nodes to launch this tick within the global capacity and
+* the per-category fan-out caps. A category at its cap defers its remaining
+* ready nodes to a later tick (it does not drop them). Nodes without a category
+* are bounded only by the global capacity. Without a fanOutWidth (e.g. in tests
+* or configs with no token_budget), this is the prior `slice(0, capacity)`.
+*/
+function selectLaunchableNodes(state, capacity) {
+	const ready = readyNodeIds(state);
+	return state.fanOutWidth ? cappedSelection(ready, capacity, state, state.fanOutWidth) : ready.slice(0, capacity);
+}
+function cappedSelection(ready, capacity, state, fanOut) {
+	const categoryOf = new Map(state.nodes.map((node) => [node.id, node.category]));
+	const counts = categoryRunCounts(state.running, categoryOf);
+	const selected = [];
+	for (const nodeId of ready) {
+		if (selected.length >= capacity) break;
+		if (claimCategorySlot(categoryOf.get(nodeId), fanOut, counts)) selected.push(nodeId);
+	}
+	return selected;
+}
+function categoryCap(category, fanOut) {
+	return fanOut.by_category[category] ?? fanOut.default;
+}
+/**
+* Whether a node of the given category may launch now, consuming a slot from
+* `counts` when it can. Uncategorized nodes always may; a category at its cap
+* may not.
+*/
+function claimCategorySlot(category, fanOut, counts) {
+	if (!category) return true;
+	const current = counts.get(category) ?? 0;
+	if (current >= categoryCap(category, fanOut)) return false;
+	counts.set(category, current + 1);
+	return true;
+}
+function categoryRunCounts(running, categoryOf) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const nodeId of running) {
+		const category = categoryOf.get(nodeId);
+		if (category) counts.set(category, (counts.get(category) ?? 0) + 1);
+	}
+	return counts;
+}
 function dependencyPassed(nodeId, context) {
 	const result = (context.completed ?? []).find((item) => item.nodeId === nodeId);
 	return result ? context.shouldContinueAfterNodeResult?.(result) ?? result.status !== "failed" : false;

package/dist/schedule/passes/models.js

@@ -25,12 +25,16 @@ function applyNodeCatalogModelsToParallelNode(node, templates) {
 	};
 }
 function applyNodeCatalogModelsToAgentNode(node, templates) {
-	if (node.models?.length) return node;
 	const template = nodeCatalogTemplateFor(node, templates);
-	return template ? {
+	if (!template) return node;
+	return {
 		...node,
-		models: template.models
-	} : node;
+		category: node.category ?? template.category,
+		models: nodeModelsOrCatalog(node, template)
+	};
+}
+function nodeModelsOrCatalog(node, template) {
+	return node.models?.length ? node.models : template.models;
 }
 function nodeCatalogTemplateFor(node, templates) {
 	return templates[node.id] ?? Object.values(templates).find((candidate) => node.id.includes(candidate.category)) ?? Object.values(templates).find((candidate) => candidate.profile === node.profile);

package/dist/schedule/prompts.js

@@ -44,6 +44,9 @@ function plannerPrompt(entrypointId, task, baseline, config, planningContext) {
 		"Scheduler node catalog:",
 		schedulerCatalogPrompt(config, entrypointId),
 		"",
+		"Token budget:",
+		tokenBudgetPrompt(config),
+		"",
 		"Gate recipes:",
 		"- Prefer preserving valid gates from the baseline workflows instead of recreating them.",
 		"- RED/test coverage may use changed_files gates on test-writing nodes. A changed_files gate must include a changed_files object with allow and/or require_any glob arrays.",
@@ -84,6 +87,18 @@ function plannerRepairPrompt(inputs) {
 		stringify(inputs.baseline)
 	].join("\n");
 }
+function tokenBudgetPrompt(config) {
+	const budget = config.token_budget;
+	const windows = Object.entries(budget.model_context_windows);
+	const fanOut = Object.entries(budget.fan_out_width.by_category);
+	return [
+		`- Keep each node's assembled context under ${budget.max_context_pct}% of its model's context window; prefer the smallest-tier model whose window comfortably holds the node within that cap.`,
+		`- Assume ${budget.default_context_window} tokens of context window for a model with no declared window.`,
+		windows.length > 0 ? `- Known model context windows: ${windows.map(([id, size]) => `${id}=${size}`).join(", ")}.` : void 0,
+		`- Do not exceed the per-category fan-out width (max concurrent same-category nodes). Default width: ${budget.fan_out_width.default}.`,
+		fanOut.length > 0 ? `- Category fan-out caps: ${fanOut.map(([category, width]) => `${category}=${width}`).join(", ")}.` : void 0
+	].filter((line) => Boolean(line)).join("\n");
+}
 function allowedProfilePromptLine(config, id) {
 	const profile = config.profiles[id];
 	const runner = config.runners[profile.runner];

package/dist/token-estimator.js

@@ -0,0 +1,22 @@
+import { getEncoding } from "js-tiktoken";
+//#region src/token-estimator.ts
+/**
+* Token estimation for node sizing. Uses the `o200k_base` encoding (the GPT-5.5
+* family the MoKa agents run on).
+*
+* This is a cross-model ESTIMATE, not a billing-accurate count: the pipeline
+* routes nodes across OpenAI/Kimi/Qwen models whose tokenizers differ, so the
+* value is a sizing heuristic for budget/routing decisions. For exact counts on
+* Anthropic runners, use the Anthropic `count_tokens` API instead.
+*/
+let encoder;
+function encoding() {
+	encoder ??= getEncoding("o200k_base");
+	return encoder;
+}
+function estimateTokens(text) {
+	if (text.length === 0) return 0;
+	return encoding().encode(text).length;
+}
+//#endregion
+export { estimateTokens };

package/package.json

@@ -9,6 +9,7 @@
     "execa": "^9.5.2",
     "git-url-parse": "^16.1.0",
     "gray-matter": "^4.0.3",
+    "js-tiktoken": "^1.0.21",
     "jsonc-parser": "^3.3.1",
     "ky": "^2.0.2",
     "micromatch": "^4.0.8",
@@ -120,7 +121,7 @@
     "prepack": "bun run build:cli"
   },
   "type": "module",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "description": "Config-driven multi-agent pipeline runner for repository work",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",