v0.2.0 orchestration + memory subsystem

[unifiedh]

• Implements full v0.2.0 architecture: orchestration engine (task graph, planner, health monitor, messaging, plan mode), memory subsystem (context manager, compression engine, event stream, knowledge store, enhanced retriever, agent context aggregator), and unified inference client with provider registry

  • Applies 5 architect-noted fixes from post-implementation review: dedup normalizeTaskResult, rename FundingProtocol params, add role column to children table, wire plan review to reviewPlan(), and adds 10 new test files (186 tests)
  • Includes auto-topup credits from USDC mid-loop to prevent runtime death

  Changes

  Orchestration Engine (new)

  • Task Graph (src/orchestration/task-graph.ts): DAG-based task decomposition with dependency resolution, cycle detection, retry logic, and goal progress tracking
  • Orchestrator (src/orchestration/orchestrator.ts): State-machine tick loop (idle → classifying → planning → plan_review → executing → complete/failed) with agent matching, funding, and replanning
  • Planner (src/orchestration/planner.ts): LLM-powered goal decomposition with custom role definitions, cost estimation, and dependency validation
  • Plan Mode (src/orchestration/plan-mode.ts): Execution state controller with phase transitions, plan persistence/review, and replan triggers
  • Health Monitor (src/orchestration/health-monitor.ts): Agent health checks (heartbeat staleness, stuck tasks, error loops, credit depletion) with auto-heal actions
  • Messaging (src/orchestration/messaging.ts): Typed inter-agent messaging with priority routing, retry backoff, and pluggable transport
  • Simple Tracker (src/orchestration/simple-tracker.ts): Agent tracker and funding protocol implementations
  • Types (src/orchestration/types.ts): Shared interfaces for AgentTracker, FundingProtocol, OrchestratorTickResult

  Memory Subsystem (new)

  • Context Manager (src/memory/context-manager.ts): Model-aware context assembly with token-budget enforcement
  • Compression Engine (src/memory/compression-engine.ts): 5-stage progressive compression cascade (compact → compress → summarize → checkpoint → emergency truncate)
  • Event Stream (src/memory/event-stream.ts): Append-only event log with compaction and pruning
  • Knowledge Store (src/memory/knowledge-store.ts): Cross-agent knowledge base with category-based retrieval
  • Enhanced Retriever (src/memory/enhanced-retriever.ts): Metadata-based relevance scoring with dynamic budget, feedback tracking, and query enhancement
  • Agent Context Aggregator (src/memory/agent-context-aggregator.ts): Triage-based child update aggregation to prevent parent context explosion

  Inference (new)

  • Unified Inference Client (src/inference/inference-client.ts): Multi-provider client with tier routing, retry/failover, circuit breaker, and survival mode
  • Provider Registry (src/inference/provider-registry.ts): Model configuration registry with tier resolution and provider management

  Architect Fixes (5)

  1. Fix 1: Extracted duplicate normalizeTaskResult — now single export from task-graph.ts, imported in orchestrator.ts
  2. Fix 2: Renamed FundingProtocol params addr → childAddress in types.ts and simple-tracker.ts
  3. Fix 3: Added role column to children table via MIGRATION_V9_ALTER_CHILDREN_ROLE in schema.ts; SimpleAgentTracker.getIdle() now reads role from DB
  4. Fix 4: Wired handlePlanReviewPhase to call reviewPlan() — loads plan from KV, handles auto/supervised/consensus modes
  5. Fix 5: 10 new test files (186 tests) — see below

  Modified Files

  • src/state/schema.ts: Added MIGRATION_V9_ALTER_CHILDREN_ROLE
  • src/state/database.ts: Wired V9 role migration, added orchestration/memory DB helpers
  • src/agent/loop.ts: Integrated orchestrator tick and auto-topup
  • src/agent/context.ts: Added memory budget exports
  • src/agent/system-prompt.ts: Added orchestration context injection
  • src/heartbeat/tasks.ts: Added orchestration heartbeat tasks
  • src/memory/ingestion.ts: Enhanced memory ingestion pipeline

  Test Coverage (186 new tests)

  Unit Tests (5 files, 114 tests)

  File	Tests	Coverage
  orchestrator.test.ts	26	tick phases, matchTaskToAgent, funding, collectResults, handleFailure, planReview
  planner.test.ts	26	validatePlannerOutput, buildPlannerPrompt, planGoal, replanAfterFailure, custom roles
  simple-tracker.test.ts	18	getIdle, getBestForTask, updateStatus, register, SimpleFundingProtocol
  health-monitor.test.ts	22	checkAll (healthy/unhealthy/dead/stuck/error loop), autoHeal (fund/restart/reassign/stop)
  agent-context-aggregator.test.ts	22	triageUpdate (error/financial/blocked/completed/heartbeat), aggregateChildUpdates

  Integration Tests (5 files, 72 tests)

  File	Tests	Coverage
  plan-execute-flow.test.ts	14	Full lifecycle, replan on failure, plan rejection, edge cases
  multi-agent-coordination.test.ts	12	Parallel assignment, result collection, dependency chains, failure propagation
  compression-cascade.test.ts	12	Threshold triggers, stage execution, stage 3→4 fallthrough, metrics
  inference-failover.test.ts	17	Provider resolution, 429/503 failover, circuit breaker, survival mode
  memory-retrieval.test.ts	17	Scored retrieval, dynamic budget, feedback tracking, query enhancement

  Test plan

  • pnpm exec tsc --noEmit — zero type errors
  • pnpm vitest run — all tests pass (existing + 186 new)
  • Verify normalizeTaskResult exported once from task-graph.ts
  • Verify addr: removed from types.ts (now childAddress)
  • Verify role column migration in schema.ts V9
  • Verify handlePlanReviewPhase calls reviewPlan()

---

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 12 additional findings in Devin Review.

[devin-ai-integration]

🔴 Plan review skipped after replan due to mismatched KV key

After a replan, the plan is stored under the wrong KV key, causing handlePlanReviewPhase to skip the review and proceed directly to executing.

Root Cause: KV key mismatch between persist and lookup

persistPlannerOutput at src/orchestration/orchestrator.ts:820 computes the KV key as orchestrator.${mode}.${goalId}. When called from handleReplanningPhase at line 625, the mode is "replan", so the key becomes orchestrator.replan.${goalId}.

However, handlePlanReviewPhase at src/orchestration/orchestrator.ts:407 always looks up orchestrator.plan.${state.goalId} — using the hardcoded "plan" prefix.

After a replan:

1. handleReplanningPhase calls this.persistPlannerOutput(goal.id, output, "replan") → stores under orchestrator.replan.<goalId>
2. State transitions to plan_review
3. handlePlanReviewPhase looks up orchestrator.plan.<goalId> → not found
4. Because planRow is undefined, the method returns { ...state, phase: "executing" } immediately — skipping review entirely

Impact: Replanned task graphs are never reviewed before execution. This bypasses the plan review safety mechanism (auto-approve budget checks, supervised mode, consensus mode) for all replans. In supervised mode, this means a human-approval gate is silently skipped after failures.

Suggested change

	private persistPlannerOutput(goalId: string, output: PlannerOutput, mode: "plan" | "replan"): void {
	const key = `orchestrator.${mode}.${goalId}`;
	this.params.db.prepare(
	"INSERT OR REPLACE INTO kv (key, value, updated_at) VALUES (?, ?, datetime('now'))",
	).run(key, JSON.stringify(output));
	private persistPlannerOutput(goalId: string, output: PlannerOutput, mode: "plan" | "replan"): void {
	const key = `orchestrator.plan.${goalId}`;
	this.params.db.prepare(
	"INSERT OR REPLACE INTO kv (key, value, updated_at) VALUES (?, ?, datetime('now'))",
	).run(key, JSON.stringify(output));
	}

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 14 additional findings in Devin Review.

[devin-ai-integration]

🔴 handleReplanningPhase resets old tasks to pending without cancelling them, causing duplicate task execution

When the orchestrator replans after a task failure, old failed/blocked tasks are reset to pending and new replan tasks are added, resulting in both old and new tasks competing for agent assignment.

Detailed Explanation

In handleReplanningPhase at src/orchestration/orchestrator.ts:611-624, three operations happen sequentially:

1. Reset old tasks (line 611-620):

UPDATE task_graph SET status = 'pending', ... WHERE goal_id = ? AND status IN ('failed', 'blocked')

2. Set goal active (line 622):

updateGoalStatus(this.params.db, goal.id, "active");

3. Add new replan tasks (line 624):

decomposeGoal(this.params.db, goal.id, plannerOutputToTasks(goal.id, output));

The problem is that step 1 resets previously failed/blocked tasks to pending instead of cancelled. Step 3 then adds entirely new tasks from the replan. Both the old reset-to-pending tasks and new replan tasks coexist in task_graph for the same goal.

In the next handleExecutingPhase tick, getReadyTasks(db).filter(t => t.goalId === goal.id) returns both the old (reset) tasks and new replan tasks. The orchestrator assigns agents to all of them, causing:

• Duplicate work: Old tasks (which previously failed) are re-executed alongside the new approach
• Wasted credits: Agents are funded for redundant task execution
• Potential conflicts: Old and new tasks may modify the same resources or produce contradictory outputs

Additionally, these three operations are not wrapped in a single transaction. If decomposeGoal throws (e.g., validation error), the old tasks have already been reset to pending but no new tasks exist, leaving the orchestrator in a broken state where it re-executes the failed plan.

Prompt for agents

In src/orchestration/orchestrator.ts, the handleReplanningPhase method (around lines 611-624) needs to cancel old tasks instead of resetting them to pending before adding new replan tasks. The fix involves two changes:

1. Change the UPDATE statement at line 611-620 to set status to 'cancelled' instead of 'pending' for failed/blocked tasks. Also cancel any remaining pending/assigned tasks for the same goal that haven't completed:

   UPDATE task_graph
   SET status = 'cancelled', assigned_to = NULL, started_at = NULL, completed_at = NULL
   WHERE goal_id = ? AND status IN ('failed', 'blocked', 'pending', 'assigned')

2. Wrap the three operations (cancel old tasks, update goal status, decompose new tasks) in a single withTransaction call from src/state/database.ts to ensure atomicity. If decomposeGoal throws, the old task cancellation should also be rolled back.

The withTransaction import already exists at the top of the file (imported from task-graph.ts which re-exports it). You can use it directly or import from src/state/database.ts.

---

Was this helpful? React with 👍 or 👎 to provide feedback.