buildanything 1.8.0 → 2.1.1

package/src/orchestrator/hooks/context-header.ts

@@ -0,0 +1,119 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, existsSync } from 'node:fs';
+
+export interface ContextHeaderInput {
+  projectType: 'web' | 'ios';
+  phase: number;
+  iosFeatures?: Record<string, boolean>;
+  visualDnaPath?: string;  // path to DESIGN.md (repo root) — DNA lives in `## Overview > ### Brand DNA` block
+}
+
+export interface RenderedHeader {
+  content: string;
+  hash: string;
+}
+
+/** Cache: rendered header keyed by buildId + phase + input hash for automatic invalidation */
+let cachedHeader: RenderedHeader | null = null;
+let cachedBuildId: string | null = null;
+let cachedPhase: number | null = null;
+let cachedInputHash: string | null = null;
+
+/**
+ * Compute a hash of the variable inputs that affect the rendered header.
+ * Used to detect mid-phase mutations (e.g., ios_features changing within a phase).
+ */
+/**
+ * Extract the 7 DNA axis values from DESIGN.md `## Overview > ### Brand DNA` block.
+ * The block is a bullet list of 7 axes; we capture the bullets (one per axis)
+ * and join them with newlines. Falls back to first 5 non-frontmatter lines if
+ * the block is missing (legacy/partial files).
+ */
+function extractBrandDnaBlock(content: string): string {
+  const dnaMatch = content.match(/###\s+Brand DNA\s*\n([\s\S]*?)(?=\n###\s|\n##\s|$)/);
+  if (dnaMatch) return dnaMatch[1].trim().split('\n').slice(0, 7).join('\n');
+  const stripped = content.replace(/^---\n[\s\S]*?\n---\n/, '');
+  return stripped.split('\n').slice(0, 5).join('\n').trim();
+}
+
+function inputHash(input: ContextHeaderInput): string {
+  const key = JSON.stringify({
+    projectType: input.projectType,
+    phase: input.phase,
+    iosFeatures: input.iosFeatures ?? null,
+    visualDnaPath: input.visualDnaPath ?? null,
+  });
+  return createHash('sha256').update(key).digest('hex').slice(0, 16);
+}
+
+/**
+ * Render the CONTEXT header for a phase.
+ * Called once at phase boundary; result reused for all dispatches in that phase.
+ * Automatically invalidates if inputs change within the same phase
+ * (e.g., ios_features mutating mid-build per spec pass criteria).
+ */
+export function renderContextHeader(input: ContextHeaderInput, buildId: string): RenderedHeader {
+  const currentInputHash = inputHash(input);
+  // Return cached if same build, same phase, AND same inputs
+  if (
+    cachedBuildId === buildId &&
+    cachedPhase === input.phase &&
+    cachedInputHash === currentInputHash &&
+    cachedHeader
+  ) return cachedHeader;
+
+  const lines: string[] = ['CONTEXT:'];
+  lines.push(`  project_type: ${input.projectType}`);
+  lines.push(`  phase: ${input.phase}`);
+
+  // DNA: only for web, phase >= 4. Extract the 7 axis values from
+  // DESIGN.md `## Overview > ### Brand DNA` h3 block — NOT the full file.
+  // Falls back to first 5 lines if the block is absent (legacy/partial files).
+  if (input.projectType === 'web' && input.phase >= 4 && input.visualDnaPath) {
+    if (existsSync(input.visualDnaPath)) {
+      const content = readFileSync(input.visualDnaPath, 'utf-8');
+      const summary = extractBrandDnaBlock(content);
+      lines.push(`  dna: ${summary}`);
+    }
+  }
+
+  // iOS features: only for ios
+  if (input.projectType === 'ios' && input.iosFeatures) {
+    const enabled = Object.entries(input.iosFeatures)
+      .filter(([, v]) => v)
+      .map(([k]) => k);
+    if (enabled.length > 0) {
+      lines.push(`  ios_features: [${enabled.join(', ')}]`);
+    }
+  }
+
+  lines.push('');
+  lines.push('TASK:');
+
+  const content = lines.join('\n');
+  const hash = createHash('sha256').update(content).digest('hex').slice(0, 16);
+
+  cachedBuildId = buildId;
+  cachedHeader = { content, hash };
+  cachedPhase = input.phase;
+  cachedInputHash = currentInputHash;
+  return cachedHeader;
+}
+
+/**
+ * Invalidate the cache (call on phase boundary or state mutation).
+ */
+export function invalidateCache(): void {
+  cachedHeader = null;
+  cachedBuildId = null;
+  cachedPhase = null;
+  cachedInputHash = null;
+}
+
+/**
+ * Check if the cache is valid for a given build + phase.
+ */
+export function isCacheValid(phase: number, buildId?: string): boolean {
+  if (buildId !== undefined && cachedBuildId !== buildId) return false;
+  return cachedPhase === phase && cachedHeader !== null;
+}

package/src/orchestrator/hooks/token-accounting-emitter.ts

@@ -0,0 +1,77 @@
+/**
+ * Phase-boundary + Task-completion token accounting emitter (task 3.4.2).
+ *
+ * Subscribes to SDK assistant+result message `usage` fields.
+ * At every phase boundary and Task tool call completion, calls
+ * recordUsage() to append a cost line to docs/plans/build-log.md.
+ *
+ * Spec: MIGRATION-PLAN-FINAL.md §4 Stage 3 G3
+ * Depends on: src/orchestrator/hooks/token-accounting.ts (task 3.4.1)
+ */
+
+import { recordUsage, type TokenUsage, type AccountingEntry } from './token-accounting';
+
+const DEFAULT_BUILD_LOG = 'docs/plans/build-log.md';
+
+export interface SdkUsageMessage {
+  input_tokens?: number;
+  output_tokens?: number;
+  cache_creation_input_tokens?: number;
+  cache_read_input_tokens?: number;
+}
+
+export interface PhaseContext {
+  phase: number;
+  step: string;
+  buildLogPath?: string;
+}
+
+export interface TaskContext extends PhaseContext {
+  task: string;
+  subagent_type: string;
+}
+
+/**
+ * Extract TokenUsage from an SDK usage message.
+ * SDK field names differ slightly from our internal format.
+ */
+export function extractUsage(msg: SdkUsageMessage): TokenUsage {
+  return {
+    input_tokens: msg.input_tokens ?? 0,
+    output_tokens: msg.output_tokens ?? 0,
+    cache_read: msg.cache_read_input_tokens ?? 0,
+    cache_create: msg.cache_creation_input_tokens ?? 0,
+  };
+}
+
+/**
+ * Emit a cost line at a phase boundary.
+ * Called by the orchestrator after each phase completes.
+ */
+export function emitPhaseBoundary(
+  ctx: PhaseContext,
+  usage: SdkUsageMessage,
+): AccountingEntry {
+  return recordUsage(ctx.buildLogPath ?? DEFAULT_BUILD_LOG, {
+    phase: ctx.phase,
+    step: ctx.step,
+    usage: extractUsage(usage),
+  });
+}
+
+/**
+ * Emit a cost line at task completion.
+ * Called after each Task tool call returns from a subagent dispatch.
+ */
+export function emitTaskCompletion(
+  ctx: TaskContext,
+  usage: SdkUsageMessage,
+): AccountingEntry {
+  return recordUsage(ctx.buildLogPath ?? DEFAULT_BUILD_LOG, {
+    phase: ctx.phase,
+    step: ctx.step,
+    task: ctx.task,
+    subagent_type: ctx.subagent_type,
+    usage: extractUsage(usage),
+  });
+}

package/src/orchestrator/hooks/token-accounting.ts

@@ -0,0 +1,112 @@
+import { writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export interface TokenUsage {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read?: number;
+  cache_create?: number;
+}
+
+export interface AccountingEntry {
+  timestamp: string;
+  phase: number;
+  step: string;
+  task?: string;
+  subagent_type?: string;
+  model?: string;
+  usage: TokenUsage;
+  cost_usd: number;
+  cumulative_usd: number;
+}
+
+/** Running cumulative cost across the build */
+let cumulativeCost = 0;
+
+/** Per-model pricing per million tokens */
+export const PRICING_TABLE: Record<string, { input: number; output: number; cache_read: number; cache_create: number }> = {
+  'claude-sonnet-4-5':  { input: 3.0,  output: 15.0, cache_read: 0.30, cache_create: 3.75 },
+  'claude-haiku-3-5':   { input: 0.80, output: 4.0,  cache_read: 0.08, cache_create: 1.00 },
+  'claude-opus-4-5':    { input: 15.0, output: 75.0, cache_read: 1.50, cache_create: 18.75 },
+};
+const DEFAULT_PRICING = PRICING_TABLE['claude-sonnet-4-5'];
+
+/**
+ * Calculate cost from token usage.
+ * When `model` is omitted or unrecognised, Sonnet pricing is used.
+ */
+export function calculateCost(usage: TokenUsage, model?: string): number {
+  const pricing = (model ? PRICING_TABLE[model] : undefined) ?? DEFAULT_PRICING;
+  const inputCost       = (usage.input_tokens  / 1_000_000) * pricing.input;
+  const outputCost      = (usage.output_tokens / 1_000_000) * pricing.output;
+  const cacheReadCost   = ((usage.cache_read   ?? 0) / 1_000_000) * pricing.cache_read;
+  const cacheCreateCost = ((usage.cache_create ?? 0) / 1_000_000) * pricing.cache_create;
+  return Math.round((inputCost + outputCost + cacheReadCost + cacheCreateCost) * 10000) / 10000;
+}
+
+/**
+ * Record a token usage entry and append to build-log.md.
+ *
+ * @param startingCost — optional seed value so callers can restore
+ *   cumulative cost from a persisted build-log at build start.
+ *   Defaults to the current in-memory cumulative cost.
+ */
+export function recordUsage(
+  buildLogPath: string,
+  entry: Omit<AccountingEntry, 'cost_usd' | 'cumulative_usd' | 'timestamp'>,
+  startingCost = cumulativeCost,
+): AccountingEntry {
+  const cost = calculateCost(entry.usage, entry.model);
+  cumulativeCost = startingCost + cost;
+
+  const record: AccountingEntry = {
+    timestamp: new Date().toISOString(),
+    ...entry,
+    cost_usd: cost,
+    cumulative_usd: Math.round(cumulativeCost * 10000) / 10000,
+  };
+
+  const line = formatLogLine(record);
+  const dir = dirname(buildLogPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(buildLogPath, line + '\n', { flag: 'a' });
+
+  return record;
+}
+
+/**
+ * Format an accounting entry as a build-log line.
+ */
+export function formatLogLine(entry: AccountingEntry): string {
+  const meta = [`phase=${entry.phase}`, `step=${entry.step}`];
+  if (entry.task) meta.push(`task=${entry.task}`);
+  if (entry.subagent_type) meta.push(`subagent_type=${entry.subagent_type}`);
+  if (entry.model) meta.push(`model=${entry.model}`);
+
+  const tokens = [
+    `input_tokens=${entry.usage.input_tokens}`,
+    `output_tokens=${entry.usage.output_tokens}`,
+  ];
+  if (entry.usage.cache_read) tokens.push(`cache_read=${entry.usage.cache_read}`);
+  if (entry.usage.cache_create) tokens.push(`cache_create=${entry.usage.cache_create}`);
+  tokens.push(`cost_usd=${entry.cost_usd}`);
+  tokens.push(`cumulative_usd=${entry.cumulative_usd}`);
+
+  return `[${entry.timestamp}] ${meta.join(' ')}\n${tokens.join(' ')}`;
+}
+
+/**
+ * Get current cumulative cost.
+ */
+export function getCumulativeCost(): number {
+  return cumulativeCost;
+}
+
+/**
+ * Reset cumulative cost to zero.
+ * Call at build initialisation to prevent cross-build drift
+ * when the process is long-lived.
+ */
+export function reset(): void {
+  cumulativeCost = 0;
+}

package/src/orchestrator/mcp/cycle-counter.ts

@@ -0,0 +1,130 @@
+/**
+ * cycle_counter_check MCP handler (Stage 4, A6 semantic).
+ *
+ * Authoritative semantic: escalation fires when NEW counter value > max_cycles.
+ * max_cycles = 2 → first two attempts allow, third escalates.
+ *
+ * Dual counter: per-decision AND per-target-phase. Escalation when EITHER exceeds cap.
+ */
+
+import type { InFlightBackwardEdge, BackwardRoutingCounters } from '../schemas/backward-edge';
+import { STALE_EDGE_THRESHOLD_MS } from '../schemas/backward-edge';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface CycleCheckInput {
+  decision_id: string;
+  target_phase: string;
+}
+
+export interface CycleCheckResult {
+  action: 'allow' | 'escalate_to_user';
+  decision_count: number;
+  phase_count: number;
+}
+
+export interface CounterState extends BackwardRoutingCounters {}
+
+const DEFAULT_MAX_CYCLES = 2;
+
+// ---------------------------------------------------------------------------
+// Core handler (tasks 4.2.1, 4.2.2, 4.2.3)
+// ---------------------------------------------------------------------------
+
+/**
+ * Check and increment the cycle counter for a backward-routing edge.
+ * Returns allow for the first max_cycles attempts, escalate_to_user after.
+ *
+ * Mutates the state object in place — caller must persist via a single
+ * atomic state_save combining counter increment + in_flight_backward_edge
+ * write (A3 crash-seam protocol).
+ */
+export function cycleCounterCheck(
+  state: CounterState,
+  input: CycleCheckInput,
+  maxCycles: number = DEFAULT_MAX_CYCLES,
+): CycleCheckResult {
+  if (!input.decision_id) throw new Error('decision_id is required');
+  if (!input.target_phase) throw new Error('target_phase is required');
+
+  // Initialize counters if missing
+  state.backward_routing_count ??= {};
+  state.backward_routing_count_by_target_phase ??= {};
+
+  // Atomically increment both counters
+  const decisionCount = (state.backward_routing_count[input.decision_id] ?? 0) + 1;
+  const phaseCount = (state.backward_routing_count_by_target_phase[input.target_phase] ?? 0) + 1;
+
+  state.backward_routing_count[input.decision_id] = decisionCount;
+  state.backward_routing_count_by_target_phase[input.target_phase] = phaseCount;
+
+  // Write in_flight_backward_edge (A3 crash-seam) — single atomic state_save
+  state.in_flight_backward_edge = {
+    decision_id: input.decision_id,
+    target_phase: input.target_phase,
+    counter_value: decisionCount,
+    started_at: new Date().toISOString(),
+  };
+
+  // Escalation: EITHER counter exceeds cap → escalate
+  const action: CycleCheckResult['action'] =
+    (decisionCount > maxCycles || phaseCount > maxCycles)
+      ? 'escalate_to_user'
+      : 'allow';
+
+  return { action, decision_count: decisionCount, phase_count: phaseCount };
+}
+
+// ---------------------------------------------------------------------------
+// Edge lifecycle helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Clear the in-flight backward edge (called by target phase on re-entry).
+ * Caller must persist via state_save.
+ */
+export function clearInFlightEdge(state: CounterState): void {
+  delete state.in_flight_backward_edge;
+}
+
+/**
+ * Handle stale edge on --resume (A3 crash recovery).
+ * If edge is older than threshold, decrement both counters and clear the edge.
+ * Returns true if a stale edge was cleaned up.
+ */
+export function handleStaleEdge(state: CounterState, thresholdMs: number = STALE_EDGE_THRESHOLD_MS): boolean {
+  const edge = state.in_flight_backward_edge;
+  if (!edge) return false;
+
+  const age = Date.now() - new Date(edge.started_at).getTime();
+  if (age <= thresholdMs) return false; // edge is fresh, standard resume
+
+  // Edge never completed — decrement per-decision counter
+  const decCurrent = state.backward_routing_count[edge.decision_id] ?? 0;
+  if (decCurrent > 0) {
+    state.backward_routing_count[edge.decision_id] = decCurrent - 1;
+  }
+
+  // Decrement per-target-phase counter
+  const phaseCurrent = state.backward_routing_count_by_target_phase[edge.target_phase] ?? 0;
+  if (phaseCurrent > 0) {
+    state.backward_routing_count_by_target_phase[edge.target_phase] = phaseCurrent - 1;
+  }
+
+  delete state.in_flight_backward_edge;
+  return true; // stale edge handled
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+/** Create a fresh empty CounterState. For testing only. */
+export function createEmptyState(): CounterState {
+  return {
+    backward_routing_count: {},
+    backward_routing_count_by_target_phase: {},
+  };
+}