open-multi-agent-kit 0.95.1 → 0.96.0

package/examples/extensions/subagent/README.md

@@ -5,8 +5,11 @@ Delegate tasks to specialized subagents with isolated context windows.
 ## Features
 
 - **Isolated context**: Each subagent runs in a separate `omk` process
+- **Session model inheritance**: Agents without `model` use the parent session's currently selected model; an explicit `model` pins the child
 - **Streaming output**: See tool calls and progress as they happen
 - **Parallel streaming**: All parallel tasks stream updates simultaneously
+- **Validated task graphs**: Dependency DAGs fail closed on duplicate/unknown/cyclic nodes and execute in deterministic parallel waves
+- **Explicit handoffs**: Graph nodes receive only declared dependency output and only when their task includes `{dependencies}`
 - **Markdown rendering**: Final output rendered with proper formatting (expanded view)
 - **Usage tracking**: Shows turns, tokens, cost, and context usage per agent
 - **Abort support**: Ctrl+C propagates to the entire detached subagent process tree
@@ -14,6 +17,7 @@ Delegate tasks to specialized subagents with isolated context windows.
 - **Checkpoint resume**: A cutoff resumes only the unfinished shard with bounded prior evidence
 - **Cutoff learning**: Completion/cutoff history is persisted per provider and model under the agent state directory
 - **Bounded cost**: At most 3 semantic shards and 1 resume across the whole logical task by default
+- **Ultra execution**: Removes task-count, concurrency, internal deadline, and outer tool-timeout caps; Ctrl+C cancellation still propagates
 
 ## Structure
 
@@ -49,7 +53,7 @@ mkdir -p ~/.omk/agent/extensions/subagent
 src="$(pwd)/packages/coding-agent/examples/extensions/subagent"
 for f in index.ts agents.ts agent-capability-router.ts capabilities.ts domain-profiles.ts \
   adaptive-agent-runtime.ts adaptive-result.ts checkpoint-runtime.ts deadline-budget.ts \
-  deadline-profile-store.ts managed-process.ts subagent-runtime-types.ts; do
+  deadline-profile-store.ts managed-process.ts subagent-runtime-types.ts workflow-graph.ts; do
   ln -sf "$src/$f" ~/.omk/agent/extensions/subagent/$f
 done
 
@@ -107,15 +111,18 @@ Use a chain: first have scout find the read tool, then have planner suggest impr
 | Mode | Parameter | Description |
 |------|-----------|-------------|
 | Single | `{ agent, task }` | One logical task; the runtime may split it into bounded semantic shards |
-| Parallel | `{ tasks: [...] }` | Multiple logical tasks run concurrently (max 8, 4 concurrent) |
+| Parallel | `{ tasks: [...] }` | Multiple logical tasks; non-Ultra allows max 8 and 4 concurrent, while Ultra starts all requested tasks concurrently |
 | Chain | `{ chain: [...] }` | Sequential with `{previous}` placeholder and a fair deadline share per remaining step |
+| Graph | `{ graph: [{ id, agent, task, dependsOn? }] }` | Validated dependency DAG; ready nodes run in parallel waves, and any failed wave blocks downstream nodes |
+
+Graph nodes opt in to dependency output by placing `{dependencies}` in `task`. The runtime injects only outputs named in that node's `dependsOn`; without the placeholder, no prior output is appended. Each dependency handoff is capped at 16 KiB. This keeps large or unrelated context from leaking across nodes.
 
 Optional execution controls:
 
 | Parameter | Default | Description |
 |-----------|---------|-------------|
-| `executionBudgetMs` | `840000` | Internal hard budget, leaving 60 seconds before a configured 900000 ms tool timeout |
-| `maxResumeAttempts` | `1` | Retries only the active unfinished shard; accepted range is 0-2 |
+| `executionBudgetMs` | `840000` | Non-Ultra internal hard budget; when explicitly supplied it also bounds Ultra execution, otherwise Ultra is unbounded |
+| `maxResumeAttempts` | `1` | Retries only the active unfinished shard; accepted range is 0-2 and ignored by unbounded Ultra execution |
 
 ## Output Display
 
@@ -152,12 +159,13 @@ Agents are markdown files with YAML frontmatter:
 name: my-agent
 description: What this agent does
 tools: read, grep, find, ls
-model: claude-haiku-4-5
 ---
 
 System prompt for the agent goes here.
 ```
 
+`model` is optional. Omit it to inherit the model currently selected in the parent session; set it only when the agent must be pinned to a specific model.
+
 **Locations:**
 - `~/.omk/agent/agents/*.md` - User-level (always loaded)
 - `.omk/agents/*.md` - Project-level (only with `agentScope: "project"` or `"both"`)
@@ -168,10 +176,10 @@ Project agents override user agents with the same name when `agentScope: "both"`
 
 | Agent | Purpose | Model | Tools |
 |-------|---------|-------|-------|
-| `scout` | Fast codebase recon | Haiku | read, grep, find, ls, bash |
-| `planner` | Implementation plans | Sonnet | read, grep, find, ls |
-| `reviewer` | Code review | Sonnet | read, grep, find, ls, bash |
-| `worker` | General-purpose | Sonnet | (all default) |
+| `scout` | Fast codebase recon | Parent session | read, grep, find, ls, bash |
+| `planner` | Implementation plans | Parent session | read, grep, find, ls |
+| `reviewer` | Code review | Parent session | read, grep, find, ls, bash |
+| `worker` | General-purpose | Parent session | (all default) |
 
 ## Workflow Prompts
 
@@ -186,8 +194,10 @@ Project agents override user agents with the same name when `agentScope: "both"`
 - **Exit code != 0**: Tool returns error with stderr/output
 - **stopReason "error"**: LLM error propagated with error message
 - **stopReason "aborted"**: User abort (Ctrl+C) terminates and reaps the subprocess tree
-- **stopReason "deadline"**: Internal cutoff returns elapsed/deadline/checkpoint/resume metadata instead of reaching the outer tool timeout
+- **stopReason "deadline"**: Outside Ultra, an internal cutoff returns elapsed/deadline/checkpoint/resume metadata instead of reaching the outer tool timeout
+- **Ultra**: No scheduler or attempt deadline is armed; provider, network, OS, and explicit caller cancellation still apply
 - **Chain mode**: Stops at first failing step, reports which step failed, and preserves completed earlier steps
+- **Graph mode**: Rejects malformed graphs before spawn; a failed wave prevents all downstream starts and preserves completed node evidence
 - **Duplicate prevention**: A cutoff with no new checkpoint or streamed evidence is not retried
 
 ## Limitations
@@ -195,6 +205,6 @@ Project agents override user agents with the same name when `agentScope: "both"`
 - Output truncated to last 10 items in collapsed view (expand to see all)
 - Parallel model-visible output is capped at 50 KB per task; full results remain in tool details
 - Agents discovered fresh on each invocation (allows editing mid-session)
-- Parallel mode limited to 8 tasks, 4 concurrent
+- Outside Ultra, parallel mode is limited to 8 tasks and 4 concurrent processes; Ultra has no extension-imposed count or concurrency cap and can consume substantial host/provider resources
 - Automatic semantic pre-sharding requires an explicit numbered/checklist action list; indivisible prose is checkpointed and resumed as one shard
 - Checkpoints are best-effort child artifacts plus runtime-captured stream evidence; workspace side effects remain the source of truth after a cutoff

package/examples/extensions/subagent/adaptive-agent-runtime.ts

@@ -73,8 +73,8 @@ export async function runAdaptiveAgent(options: RunAdaptiveAgentOptions): Promis
 	const startedAtMs = Date.now();
 	let identity = parseProviderModel(options.model);
 	let profile = await options.profileStore.profileFor(identity.provider, identity.model);
-	const initialCutoff = cutoffFor(profile, options, remainingExecutionMs(options.budget));
 	const demand = estimateTaskDemand(options.logicalTask);
+	const initialCutoff = cutoffFor(profile, options, remainingExecutionMs(options.budget), demand.predictedMs);
 	const shards = planTaskShards(options.logicalTask, demand, {
 		attemptCutoffMs: initialCutoff,
 		maxTaskShards: options.budget.maxTaskShards,
@@ -109,7 +109,7 @@ export async function runAdaptiveAgent(options: RunAdaptiveAgentOptions): Promis
 			let checkpoint: typeof lastCheckpoint;
 			while (true) {
 				const pendingShards = shards.length - completedShardIds.length;
-				const recommended = cutoffFor(profile, options, remainingExecutionMs(taskBudget));
+				const recommended = cutoffFor(profile, options, remainingExecutionMs(taskBudget), demand.predictedMs);
 				const allocation = allocateAttemptBudget({
 					budget: taskBudget,
 					pendingSequentialTasks: 1,
@@ -231,10 +231,16 @@ export async function runAdaptiveAgent(options: RunAdaptiveAgentOptions): Promis
 	return aggregate;
 }
 
-function cutoffFor(profile: DeadlineProfile | undefined, options: RunAdaptiveAgentOptions, maximumMs: number): number {
+function cutoffFor(
+	profile: DeadlineProfile | undefined,
+	options: RunAdaptiveAgentOptions,
+	maximumMs: number,
+	predictedMs: number,
+): number {
 	return recommendAttemptCutoff(profile, {
 		fallbackMs: options.policy.fallbackAttemptMs,
 		minimumMs: Math.min(options.policy.minimumAttemptMs, maximumMs),
 		maximumMs: Math.max(1, maximumMs),
+		predictedMs,
 	});
 }

package/examples/extensions/subagent/agents/planner.md

@@ -1,8 +1,6 @@
 ---
 name: planner
 description: Creates implementation plans from context and requirements
-tools: read, grep, find, ls
-model: claude-sonnet-4-5
 ---
 
 You are a planning specialist. You receive context (from a scout) and requirements, then produce a clear implementation plan.

package/examples/extensions/subagent/agents/reviewer.md

@@ -1,8 +1,6 @@
 ---
 name: reviewer
 description: Code review specialist for quality and security analysis
-tools: read, grep, find, ls, bash
-model: claude-sonnet-4-5
 ---
 
 You are a senior code reviewer. Analyze code for quality, security, and maintainability.

package/examples/extensions/subagent/agents/scout.md

@@ -1,8 +1,6 @@
 ---
 name: scout
 description: Fast codebase recon that returns compressed context for handoff to other agents
-tools: read, grep, find, ls, bash
-model: claude-haiku-4-5
 ---
 
 You are a scout. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything.

package/examples/extensions/subagent/agents/worker.md

@@ -1,7 +1,6 @@
 ---
 name: worker
 description: General-purpose subagent with full capabilities, isolated context
-model: claude-sonnet-4-5
 ---
 
 You are a worker agent with full capabilities. You operate in an isolated context window to handle delegated tasks without polluting the main conversation.

package/examples/extensions/subagent/agents.test.ts

@@ -84,3 +84,12 @@ describe("parseEnforceFlag coercion (via discoverAgents)", () => {
 		}
 	});
 });
+
+describe("bundled agent model delegation", () => {
+	it("omits model pins so bundled agents inherit the parent session model", () => {
+		for (const name of ["scout", "planner", "reviewer", "worker"]) {
+			const source = fs.readFileSync(path.join(import.meta.dirname, "agents", `${name}.md`), "utf8");
+			expect(source, `${name} must not pin a model`).not.toMatch(/^model:/m);
+		}
+	});
+});

package/examples/extensions/subagent/agents.ts

@@ -78,10 +78,17 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 			continue;
 		}
 
-		const tools = frontmatter.tools
-			?.split(",")
-			.map((t: string) => t.trim())
-			.filter(Boolean);
+		const rawTools = frontmatter.tools as unknown;
+		// ponytail: frontmatter `tools:` is either a CSV string or a YAML map ({read: true}) — accept both
+		const tools =
+			typeof rawTools === "string"
+				? rawTools
+						.split(",")
+						.map((t: string) => t.trim())
+						.filter(Boolean)
+				: rawTools && typeof rawTools === "object"
+					? Object.keys(rawTools)
+					: undefined;
 
 		const capabilities = parseCapabilities(frontmatter);
 		const enforceCapabilities = parseEnforceFlag(frontmatter.enforceCapabilities);

package/examples/extensions/subagent/deadline-budget.test.ts

@@ -132,4 +132,36 @@ describe("provider/model deadline learning", () => {
 		expect(recommendAttemptCutoff(codex, { fallbackMs: 600_000, minimumMs: 1, maximumMs: 800_000 })).toBe(180_000);
 		expect(recommendAttemptCutoff(anthropic, { fallbackMs: 600_000, minimumMs: 1, maximumMs: 800_000 })).toBe(60_000);
 	});
+
+	it("does not let a short probe collapse a larger task to the minimum cutoff", () => {
+		const db = updateDeadlineProfiles(undefined, {
+			provider: "openai-codex",
+			model: "gpt-5.6",
+			outcome: "completed",
+			elapsedMs: 10_000,
+			estimatedTokens: 10,
+			workUnits: 1,
+		});
+		const profile = getDeadlineProfile(db, "openai-codex", "gpt-5.6");
+		const demand = estimateTaskDemand(
+			[
+				"Review the release candidate:",
+				"1. Inspect the manifest.",
+				"2. Verify fixture hashes.",
+				"3. Run formatter checks.",
+				"4. Run parity tests.",
+				"5. Review production diffs.",
+				"6. Report the verdict.",
+			].join("\n"),
+		);
+
+		expect(
+			recommendAttemptCutoff(profile, {
+				fallbackMs: 600_000,
+				minimumMs: 30_000,
+				maximumMs: 800_000,
+				predictedMs: demand.predictedMs,
+			}),
+		).toBe(demand.predictedMs);
+	});
 });

package/examples/extensions/subagent/deadline-budget.ts

@@ -1,5 +1,27 @@
 export type DeadlineSampleOutcome = "completed" | "cutoff" | "aborted" | "failed";
 
+export interface SubagentExecutionPolicy {
+	readonly unbounded: boolean;
+	readonly maxParallelTasks: number | undefined;
+	readonly concurrency: number;
+}
+
+export function resolveSubagentExecutionPolicy(
+	thinkingLevel: string | undefined,
+	parallelTaskCount: number,
+	executionBudgetExplicit = false,
+): SubagentExecutionPolicy {
+	const taskCount = Math.max(1, Math.floor(parallelTaskCount));
+	if (thinkingLevel === "ultra") {
+		return { unbounded: !executionBudgetExplicit, maxParallelTasks: undefined, concurrency: taskCount };
+	}
+	return { unbounded: false, maxParallelTasks: 8, concurrency: Math.min(4, taskCount) };
+}
+
+export function exceedsParallelTaskLimit(policy: SubagentExecutionPolicy, taskCount: number): boolean {
+	return policy.maxParallelTasks !== undefined && taskCount > policy.maxParallelTasks;
+}
+
 export interface TaskDemand {
 	readonly estimatedTokens: number;
 	readonly workUnits: number;
@@ -78,6 +100,7 @@ interface RecommendCutoffOptions {
 	readonly fallbackMs: number;
 	readonly minimumMs: number;
 	readonly maximumMs: number;
+	readonly predictedMs?: number;
 }
 
 const EXPLICIT_ACTION_LINE = /^\s*(?:\d+[.)]|\[[ xX]\])\s+(.+?)\s*$/;
@@ -216,7 +239,8 @@ export function recommendAttemptCutoff(profile: DeadlineProfile | undefined, opt
 	const candidates = [options.fallbackMs];
 	if (completed !== undefined) candidates.push(Math.round(completed * 1.5));
 	if (cutoff !== undefined) candidates.push(Math.round(cutoff * 0.75));
-	return Math.max(options.minimumMs, Math.min(options.maximumMs, ...candidates));
+	const recommendedMs = Math.max(options.predictedMs ?? 0, Math.min(...candidates));
+	return Math.max(options.minimumMs, Math.min(options.maximumMs, recommendedMs));
 }
 
 function extractActionUnit(line: string): string | undefined {

package/examples/extensions/subagent/fixtures/fake-omk-json.mjs

@@ -1,5 +1,15 @@
 #!/usr/bin/env node
 
+const expectedModel = process.env.OMK_EXPECTED_MODEL;
+if (expectedModel) {
+	const modelIndex = process.argv.indexOf("--model");
+	const actualModel = modelIndex === -1 ? undefined : process.argv[modelIndex + 1];
+	if (actualModel !== expectedModel) {
+		process.stderr.write(`expected --model ${expectedModel}, received ${actualModel ?? "none"}\n`);
+		process.exit(2);
+	}
+}
+
 process.stdout.write(
 	`${JSON.stringify({
 		type: "message_end",