ultra-builder-pro-cli 0.14.0 → 0.16.0

package/mcp-server/server.cjs

@@ -2,7 +2,7 @@
 
 // MCP server (stdio JSON-RPC) exposing task.* + session.* tools backed by
 // .ultra/state.db. Uses the low-level Server API from
-// @modelcontextprotocol/sdk so we can pass raw JSON Schema (Draft 2020-12)
+// @modelcontextprotocol/server so we can pass raw JSON Schema (Draft 2020-12)
 // straight from spec/mcp-tools.yaml without translating to zod.
 
 const fs = require('node:fs');
@@ -12,12 +12,13 @@ const yaml = require('js-yaml');
 const Ajv = require('ajv/dist/2020');
 const addFormats = require('ajv-formats');
 
-const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
-const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
-const { ListToolsRequestSchema, CallToolRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
+const { Server } = require('@modelcontextprotocol/server');
+const { StdioServerTransport } = require('@modelcontextprotocol/server/stdio');
 const { version: PACKAGE_VERSION } = require('../package.json');
 
-const { initStateDb, closeStateDb } = require('./lib/state-db.cjs');
+const {
+  initStateDb, closeStateDb, openStateDb, ensureSchemaVersion,
+} = require('./lib/state-db.cjs');
 const { assertStateAuthority } = require('./lib/state-authority.cjs');
 const ops = require('./lib/state-ops.cjs');
 const projector = require('./lib/projector.cjs');
@@ -30,6 +31,8 @@ const { initProject } = require('./lib/init-project.cjs');
 const baselines = require('./lib/baseline-workflow.cjs');
 const changes = require('./lib/change-workflow.cjs');
 const runtimeState = require('./lib/runtime-state.cjs');
+const workflows = require('./lib/workflow-state.cjs');
+const decisions = require('./lib/decision-dialogue.cjs');
 const doctor = require('./lib/doctor.cjs');
 const {
   readProjectBreadcrumb,
@@ -91,12 +94,34 @@ const CHANGE_TOOLS = Object.freeze([
   'change.archive',
 ]);
 
+const WORKFLOW_TOOLS = Object.freeze([
+  'workflow.start',
+  'workflow.get',
+  'workflow.list',
+  'workflow.step',
+  'workflow.complete',
+]);
+
+const DECISION_TOOLS = Object.freeze([
+  'decision.thread_start',
+  'decision.get',
+  'decision.list',
+  'decision.open',
+  'decision.resolve',
+  'decision.delegate',
+  'decision.defer',
+  'decision.supersede',
+  'decision.checkpoint',
+]);
+
 const SYSTEM_TOOLS = Object.freeze([
   'system.doctor',
 ]);
 
 const REGISTERED_TOOLS = Object.freeze([
   ...TASK_TOOLS, ...SESSION_TOOLS, ...PLAN_TOOLS, ...BASELINE_TOOLS, ...CHANGE_TOOLS,
+  ...DECISION_TOOLS,
+  ...WORKFLOW_TOOLS,
   ...SYSTEM_TOOLS,
 ]);
 
@@ -112,6 +137,9 @@ const MUTATING_TOOLS = new Set([
   'baseline.start', 'baseline.record', 'baseline.converge',
   'change.create', 'change.update', 'change.context', 'change.converge', 'change.archive',
   'change.learning_propose', 'change.learning_resolve',
+  'decision.thread_start', 'decision.open', 'decision.resolve', 'decision.delegate',
+  'decision.defer', 'decision.supersede', 'decision.checkpoint',
+  'workflow.start', 'workflow.step', 'workflow.complete',
 ]);
 
 function loadRegisteredTools() {
@@ -252,10 +280,33 @@ async function dispatchTool(name, input, db, ctx = {}) {
       return ops.switchTaskTag(db, input.id, input.tag);
     }
     case 'task.dependency_topo': {
-      const requested = Array.isArray(input && input.task_ids) ? input.task_ids : null;
-      const rows = requested
-        ? requested.map((id) => ops.readTask(db, id)).filter(Boolean)
-        : ops.listTasks(db, {});
+      const hasTaskIds = Array.isArray(input && input.task_ids);
+      const hasChangeId = typeof input?.change_id === 'string' && input.change_id.trim() !== '';
+      if (hasTaskIds === hasChangeId) {
+        const err = new Error('provide exactly one of task_ids or change_id');
+        err.code = 'VALIDATION_ERROR';
+        throw err;
+      }
+      let rows;
+      if (hasTaskIds) {
+        rows = input.task_ids.map((id) => {
+          const task = ops.readTask(db, id);
+          if (!task) {
+            const err = new Error(`task ${id} not found`);
+            err.code = 'TASK_NOT_FOUND';
+            throw err;
+          }
+          return task;
+        });
+      } else {
+        const change = changes.readChange(db, input.change_id);
+        if (!change) {
+          const err = new Error(`change ${input.change_id} not found`);
+          err.code = 'CHANGE_NOT_FOUND';
+          throw err;
+        }
+        rows = ops.listTasks(db, { change_id: change.id });
+      }
       const graph = rows.map((t) => ({
         id: t.id,
         deps: Array.isArray(t.deps) ? t.deps : [],
@@ -272,6 +323,11 @@ async function dispatchTool(name, input, db, ctx = {}) {
     case 'task.parse_prd': {
       const dryRun = input.dry_run === true;
       const rootDir = ctx.rootDir || process.cwd();
+      if (!dryRun && !String(input.change_id || '').trim()) {
+        const err = new Error('persisting a parsed task graph requires change_id');
+        err.code = 'CHANGE_REQUIRED';
+        throw err;
+      }
       const creationAuthority = { change_id: input.change_id };
       if (!dryRun) changes.assertTaskCreationAllowed(db, creationAuthority, { rootDir });
       const parsed = parser.parsePrd(input.tasks, {
@@ -330,20 +386,34 @@ async function dispatchTool(name, input, db, ctx = {}) {
     }
     case 'plan.export': {
       const rootDir = ctx.rootDir || process.cwd();
+      const change = changes.readChange(db, input.change_id);
+      if (!change) {
+        const err = new Error(`change ${input.change_id} not found`);
+        err.code = 'CHANGE_NOT_FOUND';
+        throw err;
+      }
+      if (!['active', 'blocked'].includes(change.status)) {
+        const err = new Error(`change ${change.id} is ${change.status}`);
+        err.code = 'CHANGE_NOT_MUTABLE';
+        throw err;
+      }
       const abs = path.isAbsolute(input.out_path)
         ? input.out_path
         : path.join(rootDir, input.out_path);
-      const tasks = ops.listTasks(db, { tag: input.tag });
+      const tasks = ops.listTasks(db, { tag: input.tag, change_id: change.id });
       if (tasks.length === 0) {
         const err = new Error('no tasks to plan');
         err.code = 'NO_TASKS';
         throw err;
       }
-      const plan = planStore.buildPlan(tasks, {});
+      const plan = planStore.buildPlan(tasks, { changeId: change.id });
       const { plan_path } = planStore.savePlanArtifact(plan, abs, input.format || 'json');
       ops.appendEvent(db, {
-        type: 'plan_approved',
-        payload: { plan_path, wave_count: plan.waves.length, tag: input.tag || null },
+        type: 'plan_exported',
+        change_id: change.id,
+        payload: {
+          change_id: change.id, plan_path, wave_count: plan.waves.length, tag: input.tag || null,
+        },
       });
       return { plan_path, wave_count: plan.waves.length };
     }
@@ -355,6 +425,13 @@ async function dispatchTool(name, input, db, ctx = {}) {
         err.code = 'NO_PLAN';
         throw err;
       }
+      if (loaded.change_id !== input.change_id) {
+        const err = new Error(
+          `execution plan belongs to ${loaded.change_id || '(unbound)'}, not ${input.change_id}`,
+        );
+        err.code = 'PLAN_CHANGE_MISMATCH';
+        throw err;
+      }
       return { plan: planStore.selectSection(loaded, input.section) };
     }
     case 'baseline.start': {
@@ -456,6 +533,82 @@ async function dispatchTool(name, input, db, ctx = {}) {
     case 'change.archive': {
       return changes.archiveChange(db, input, { rootDir: ctx.rootDir || process.cwd() });
     }
+    case 'decision.thread_start': {
+      return { thread: decisions.startDecisionThread(db, input) };
+    }
+    case 'decision.get': {
+      const thread = decisions.readDecisionThread(db, input.id);
+      if (!thread) {
+        const error = new Error(`decision thread ${input.id} not found`);
+        error.code = 'DECISION_THREAD_NOT_FOUND';
+        throw error;
+      }
+      return { thread };
+    }
+    case 'decision.list': {
+      const threads = decisions.listDecisionThreads(db, input || {});
+      return { threads, count: threads.length };
+    }
+    case 'decision.open': {
+      return { thread: decisions.openDecision(db, input) };
+    }
+    case 'decision.resolve': {
+      return { thread: decisions.resolveDecision(db, input) };
+    }
+    case 'decision.delegate': {
+      return { thread: decisions.delegateDecision(db, input) };
+    }
+    case 'decision.defer': {
+      return { thread: decisions.deferDecision(db, input) };
+    }
+    case 'decision.supersede': {
+      return { thread: decisions.supersedeDecision(db, input) };
+    }
+    case 'decision.checkpoint': {
+      return {
+        thread: decisions.checkpointDecisionThread(
+          db, input, { rootDir: ctx.rootDir || process.cwd() },
+        ),
+      };
+    }
+    case 'workflow.start': {
+      return {
+        workflow: workflows.startWorkflow(
+          db, input, { rootDir: ctx.rootDir || process.cwd() },
+        ),
+      };
+    }
+    case 'workflow.get': {
+      const workflow = workflows.readWorkflow(
+        db, input.id, { rootDir: ctx.rootDir || process.cwd() },
+      );
+      if (!workflow) {
+        const error = new Error(`workflow ${input.id} not found`);
+        error.code = 'WORKFLOW_NOT_FOUND';
+        throw error;
+      }
+      return { workflow };
+    }
+    case 'workflow.list': {
+      const rows = workflows.listWorkflows(
+        db, input || {}, { rootDir: ctx.rootDir || process.cwd() },
+      );
+      return { workflows: rows, count: rows.length };
+    }
+    case 'workflow.step': {
+      return {
+        workflow: workflows.recordWorkflowStep(
+          db, input, { rootDir: ctx.rootDir || process.cwd() },
+        ),
+      };
+    }
+    case 'workflow.complete': {
+      return {
+        workflow: workflows.completeWorkflow(
+          db, input, { rootDir: ctx.rootDir || process.cwd() },
+        ),
+      };
+    }
     case 'system.doctor': {
       return doctor.runDoctor(db, {
         rootDir: ctx.rootDir || process.cwd(),
@@ -501,7 +654,7 @@ function startServer({ dbPath, rootDir, projectOnWrite = true, project = project
     { capabilities: { tools: {} } },
   );
 
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  server.setRequestHandler('tools/list', async () => ({
     tools: tools.map((t) => ({
       name: t.name,
       description: t.description,
@@ -509,7 +662,7 @@ function startServer({ dbPath, rootDir, projectOnWrite = true, project = project
     })),
   }));
 
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  server.setRequestHandler('tools/call', async (request) => {
     const { name, arguments: args = {} } = request.params;
     const toolStart = Date.now();
     let toolError = null;
@@ -623,6 +776,51 @@ async function main() {
   process.on('SIGINT', cleanup);
 }
 
+function hookMetadata(value, fallback = 'unknown', maxLength = 256) {
+  const normalized = typeof value === 'string' ? value.trim() : '';
+  return (normalized || fallback).slice(0, maxLength);
+}
+
+function appendHookLifecycleEvent({ rootDir, action, hookInput = {} } = {}) {
+  if (!['start', 'stop'].includes(action)) {
+    const error = new Error('hook lifecycle action must be start or stop');
+    error.code = 'VALIDATION_ERROR';
+    throw error;
+  }
+  const root = path.resolve(rootDir || process.cwd());
+  const dbPath = path.join(root, '.ultra', 'state.db');
+  if (!fs.existsSync(dbPath)) return { recorded: false, reason: 'STATE_DB_MISSING' };
+
+  const db = openStateDb(dbPath);
+  try {
+    ensureSchemaVersion(db);
+    const change = db.prepare(
+      `SELECT id FROM changes WHERE status IN ('active', 'blocked', 'ready')
+       ORDER BY updated_at DESC, rowid DESC LIMIT 1`,
+    ).get();
+    if (!change) return { recorded: false, reason: 'NO_ACTIVE_CHANGE' };
+    const task = db.prepare(
+      `SELECT id FROM tasks WHERE change_id = ? AND status IN ('in_progress', 'pending', 'blocked')
+       ORDER BY CASE status WHEN 'in_progress' THEN 0 WHEN 'blocked' THEN 1 ELSE 2 END,
+                updated_at DESC, rowid DESC LIMIT 1`,
+    ).get(change.id);
+    const payload = {
+      agent_id: hookMetadata(hookInput.agent_id),
+      agent_type: hookMetadata(hookInput.agent_type),
+      host_session_id: hookMetadata(hookInput.session_id, '', 256),
+    };
+    ops.appendEvent(db, {
+      type: action === 'start' ? 'subagent_started' : 'subagent_stopped',
+      change_id: change.id,
+      task_id: task?.id || null,
+      payload,
+    });
+    return { recorded: true, change_id: change.id, task_id: task?.id || null };
+  } finally {
+    closeStateDb(db);
+  }
+}
+
 if (require.main === module) {
   main().catch((err) => {
     process.stderr.write(`mcp-server fatal: ${err.message}\n`);
@@ -639,10 +837,12 @@ module.exports = {
   PLAN_TOOLS,
   BASELINE_TOOLS,
   CHANGE_TOOLS,
+  WORKFLOW_TOOLS,
   SYSTEM_TOOLS,
   REGISTERED_TOOLS,
   STATELESS_TOOLS,
   MUTATING_TOOLS,
+  appendHookLifecycleEvent,
   readProjectBreadcrumb,
   renderProjectBreadcrumb,
 };

package/orchestrator/daemon.cjs

@@ -16,7 +16,7 @@ const runtimeState = require('../mcp-server/lib/runtime-state.cjs');
 const projector = require('../mcp-server/lib/projector.cjs');
 const runner = require('./session-runner.cjs');
 const recovery = require('./recovery.cjs');
-const { evaluate, DEFAULT_RULES, ROUTE_PREFERENCES } = require('./dispatch-rules.cjs');
+const { evaluate, DEFAULT_RULES } = require('./dispatch-rules.cjs');
 
 // Phase 8B.1 — routeTask is now a thin wrapper over evaluate() so Phase 5.4
 // callers see identical behavior while the parallel orchestrator (8B.2) can
@@ -146,6 +146,5 @@ function runDaemon({
 module.exports = {
   runDaemon,
   routeTask,
-  ROUTE_PREFERENCES,
   maintainState,
 };

package/orchestrator/dispatch-rules.cjs

@@ -8,28 +8,13 @@
 //   • defer       — leave task pending, revisit next tick (deps/wave wait)
 //   • block       — terminal: don't spawn (breaker, no runtimes, etc.)
 //
-// Phase 5.4 ROUTE_PREFERENCES lives here now. daemon.cjs's `routeTask` is a
-// thin wrapper around evaluate() so Phase 5.4 tests stay green while the
-// parallel orchestrator (8B.2) gets a richer decision surface: wave state,
-// deps readiness, and custom rule injection.
+// Runtime order is caller-owned. The orchestrator does not infer model quality,
+// price, or capability from a host name because every host can be configured
+// with different models. The parallel orchestrator supplies richer dimensions:
+// wave state, dependency readiness, and explicit custom rules.
 
 const { isSupportedRuntime } = require('../adapters/_shared/runtime-assets.cjs');
 
-const ROUTE_PREFERENCES = Object.freeze({
-  haiku:  ['opencode', 'claude', 'codex'],
-  sonnet: ['claude', 'codex', 'opencode'],
-  opus:   ['claude', 'codex'],
-});
-
-function resolveByPreference(ctx) {
-  const hint = ctx.task && ctx.task.complexity_hint;
-  const pref = hint ? ROUTE_PREFERENCES[hint] : null;
-  if (pref) {
-    for (const r of pref) if (ctx.available_runtimes.includes(r)) return r;
-  }
-  return ctx.available_runtimes[0];
-}
-
 const DEFAULT_RULES = Object.freeze([
   {
     id: 'breaker-blocked',
@@ -56,17 +41,7 @@ const DEFAULT_RULES = Object.freeze([
     action: 'defer',
   },
   {
-    id: 'by-preference',
-    priority: 10,
-    when: (ctx) => {
-      const hint = ctx.task && ctx.task.complexity_hint;
-      return !!(hint && ROUTE_PREFERENCES[hint]);
-    },
-    action: 'spawn_agent',
-    resolve: resolveByPreference,
-  },
-  {
-    id: 'fallback-first-available',
+    id: 'first-authorized-runtime',
     priority: 0,
     when: () => true,
     action: 'spawn_agent',
@@ -100,5 +75,4 @@ function evaluate(ctx, rules = DEFAULT_RULES) {
 module.exports = {
   evaluate,
   DEFAULT_RULES,
-  ROUTE_PREFERENCES,
 };

package/orchestrator/planner/plan-builder.cjs

@@ -15,18 +15,22 @@ const DEFAULT_COMPLEXITY = 3;
 const TOKENS_PER_COMPLEXITY = Object.freeze({ input: 5000, output: 2000 });
 const DURATION_MIN_PER_COMPLEXITY = 5;
 
-function buildPlan(tasks, { runtime = 'claude', model = null } = {}) {
+function buildPlan(tasks, { runtime = null, model = null, changeId = null } = {}) {
   if (!Array.isArray(tasks)) {
     throw new TypeError('buildPlan: tasks must be an array');
   }
 
-  const graph = tasks.map((t) => ({
+  // Plan artifacts are durable and compared by digest. Keep their ordering
+  // independent from SQLite insertion order or caller enumeration order.
+  const orderedTasks = [...tasks].sort((left, right) => String(left.id).localeCompare(String(right.id)));
+
+  const graph = orderedTasks.map((t) => ({
     id: t.id,
     deps: Array.isArray(t.deps) ? t.deps : [],
   }));
   const { waves, cycles } = computeWaves(graph);
 
-  const byId = new Map(tasks.map((t) => [t.id, t]));
+  const byId = new Map(orderedTasks.map((t) => [t.id, t]));
 
   const conflict_surface = [];
   const wavePayload = waves.map((waveTasks, idx) => {
@@ -52,18 +56,21 @@ function buildPlan(tasks, { runtime = 'claude', model = null } = {}) {
   });
 
   const ownership_forecast = {};
-  for (const t of tasks) {
+  for (const t of orderedTasks) {
     ownership_forecast[t.id] = Array.isArray(t.files_modified) ? t.files_modified : [];
   }
 
-  const estimated_cost_usd = round4(
-    tasks.reduce((sum, t) => {
-      const complexity = Number(t.complexity || DEFAULT_COMPLEXITY);
-      const ti = complexity * TOKENS_PER_COMPLEXITY.input;
-      const to = complexity * TOKENS_PER_COMPLEXITY.output;
-      return sum + (computeCost(runtime, model, ti, to) || 0);
-    }, 0),
-  );
+  const taskCosts = orderedTasks.map((t) => {
+    const complexity = Number(t.complexity || DEFAULT_COMPLEXITY);
+    const ti = complexity * TOKENS_PER_COMPLEXITY.input;
+    const to = complexity * TOKENS_PER_COMPLEXITY.output;
+    return computeCost(runtime, model, ti, to);
+  });
+  const estimated_cost_usd = orderedTasks.length === 0
+    ? 0
+    : (taskCosts.some((cost) => cost === null)
+      ? null
+      : round4(taskCosts.reduce((sum, cost) => sum + cost, 0)));
 
   const estimated_duration_min = wavePayload.reduce((acc, wv) => {
     const complexities = wv.tasks.map(
@@ -76,6 +83,8 @@ function buildPlan(tasks, { runtime = 'claude', model = null } = {}) {
   }, 0);
 
   return {
+    schema_version: '1.0',
+    change_id: changeId,
     waves: wavePayload,
     ownership_forecast,
     conflict_surface,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Multi-runtime installer for the Ultra Builder Pro agent engineering system — deploys commands, agents, skills, hooks, and MCP server to Claude Code, OpenCode, Codex CLI, and Kimi Code.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",
@@ -49,13 +49,20 @@
     ".ultra-template",
     "docs/ROADMAP.md",
     "docs/ARCHITECTURE.md",
+    "docs/WORKFLOW-LIFECYCLE.md",
     "docs/AGENT-CONTEXT.md",
     "docs/SKILL-AUTHORING.md",
     "docs/COMMIT-HASH-BACKFILL.md",
     "docs/PLAN.zh-CN.md",
     "docs/STATE-DB-ACCESS-POLICY.md",
     "docs/USER-HANDBOOK-CONTRACT.md",
-    "docs/RUNTIME-COMPAT-MATRIX.md"
+    "docs/RUNTIME-COMPAT-MATRIX.md",
+    "!**/__pycache__/**",
+    "!**/*.pyc",
+    "!**/*.pyo",
+    "!**/*.test.cjs",
+    "!**/tests/**",
+    "!mcp-server/test-support/**"
   ],
   "keywords": [
     "claude-code",
@@ -98,11 +105,14 @@
     "install:all": "node bin/install.js --all --local"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/server": "2.0.0-beta.5",
     "@vercel/ncc": "0.38.4",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "better-sqlite3": "^11.5.0",
     "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.0.0-beta.5"
   }
 }