Agent A ──▶ Agent B ──▶ Agent C ──▶ Result

         ┌──▶ Agent A ──┐
Input ───┼──▶ Agent B ──┼──▶ Merge ──▶ Result
         └──▶ Agent C ──┘

                 Supervisor
                     │
        ┌────────────┼────────────┐
        ▼            ▼            ▼
    Agent A      Agent B      Agent C
        │            │            │
        └────────────┴────────────┘
                     │
                  Supervisor
                     │
                  Result

    Agent A ◀─────────▶ Agent B
        │      debate      │
        └────────┬─────────┘
                 ▼
             Arbiter
                 │
              Result

// From src/core/agents/orchestration/
interface OrchestrationConfig {
  strategy: 'sequential' | 'parallel' | 'hierarchical' | 'debate';
  agents: AgentConfig[];
  timeout: number;
  budgetLimit: TokenBudget;
  checkpointInterval: number;
}

// Execute with strategy
const result = await agentOrchestrator.execute({
  strategy: 'hierarchical',
  agents: [
    { name: 'requirements-compiler', role: 'worker' },
    { name: 'architecture-compiler', role: 'worker' },
    { name: 'completion-audit', role: 'supervisor' }
  ],
  timeout: 300000, // 5 minutes
  budgetLimit: { maxTokens: 100000, maxCost: 5.00 }
});

┌─────────────────────────────────────────────────────────────────┐
│                     MODEL ROUTING TIERS                         │
│                                                                 │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐     │
│  │  CACHE  │───▶│  RULES  │───▶│ TIER-1  │───▶│ TIER-2  │     │
│  │         │    │ ENGINE  │    │  FAST   │    │ POWERFUL│     │
│  │  FREE   │    │  FREE   │    │  CHEAP  │    │EXPENSIVE│     │
│  └─────────┘    └─────────┘    └─────────┘    └─────────┘     │
│       │              │              │              │           │
│   Hit: Use      Match: Use     Simple:       Complex:         │
│   cached        rule-based     GPT-3.5/      GPT-4/           │
│   response      response       Haiku         Claude           │
└─────────────────────────────────────────────────────────────────┘

// Simplified routing decision
function selectModel(task: AgentTask): ModelConfig {
  // 1. Check cache
  const cached = await cache.get(task.cacheKey);
  if (cached) return { type: 'cache', result: cached };

  // 2. Check rules engine
  const rule = rules.match(task);
  if (rule) return { type: 'rules', result: rule.apply(task) };

  // 3. Classify complexity
  const complexity = classifyComplexity(task);

  if (complexity === 'simple') {
    return { model: 'gpt-3.5-turbo', tier: 1 };
  }

  return { model: 'gpt-4-turbo', tier: 2 };
}

┌─────────────────────────────────────────────────────────────────┐
│                      AGENT MEMORY                               │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                  PostgreSQL Storage                       │  │
│  │                   (agent_memory table)                    │  │
│  │                                                          │  │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────────────┐ │  │
│  │  │  Session   │  │  Tenant    │  │    Conversation    │ │  │
│  │  │  Context   │  │  Context   │  │      History       │ │  │
│  │  │            │  │            │  │                    │ │  │
│  │  │ - user_id  │  │ - tenant   │  │ - messages[]       │ │  │
│  │  │ - project  │  │ - settings │  │ - summaries[]      │ │  │
│  │  │ - phase    │  │ - patterns │  │ - tokens_used      │ │  │
│  │  └────────────┘  └────────────┘  └────────────────────┘ │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                   Token Management                        │  │
│  │                                                          │  │
│  │  TokenLimiter: 120,000 tokens max                        │  │
│  │  lastMessages: 100 (rolling window)                      │  │
│  │  semanticRecall: disabled (PostgreSQL-based)             │  │
│  └──────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

CREATE TABLE agent_memory (
  id UUID PRIMARY KEY,
  tenant_id UUID REFERENCES tenants(id),
  session_id UUID,
  agent_name VARCHAR(100),
  message_role VARCHAR(20), -- 'user', 'assistant', 'system'
  message_content TEXT,
  tokens_used INTEGER,
  created_at TIMESTAMP DEFAULT NOW(),
  metadata JSONB
);

-- Session isolation
CREATE INDEX idx_agent_memory_session ON agent_memory(session_id);
CREATE INDEX idx_agent_memory_tenant ON agent_memory(tenant_id);

// Memory configuration from mastra.config.ts
const memoryConfig = {
  storage: new PostgresStore({ connectionString: DATABASE_URL }),
  options: {
    lastMessages: 100,           // Keep last 100 messages
    semanticRecall: false,       // Use PostgreSQL, not vector DB
    tokenLimiter: new TokenLimiter({
      maxTokens: 120000,         // 120K token limit
      strategy: 'summarize'      // Summarize when approaching limit
    })
  }
};

// Background cleanup (runs every 30 minutes)
async function cleanupStaleSessions() {
  const cutoff = new Date(Date.now() - 30 * 60 * 1000);
  await db.query(`
    DELETE FROM agent_memory
    WHERE created_at < $1
    AND session_id NOT IN (
      SELECT DISTINCT session_id FROM active_sessions
    )
  `, [cutoff]);
}

┌─────────────────────────────────────────────────────────────────┐
│                   EXECUTION LOOP                                │
│                                                                 │
│  ┌─────────┐                                                   │
│  │  START  │                                                   │
│  └────┬────┘                                                   │
│       │                                                        │
│       ▼                                                        │
│  ┌─────────────────────────────────────────────┐              │
│  │             CHECK BUDGET                     │              │
│  │  tokens_used < budget_limit?                 │              │
│  │  cost_incurred < cost_limit?                 │              │
│  └──────────────────┬──────────────────────────┘              │
│                     │                                          │
│          ┌─────────┴─────────┐                                │
│          │                   │                                │
│       budget OK          budget exceeded                      │
│          │                   │                                │
│          ▼                   ▼                                │
│  ┌─────────────┐     ┌─────────────┐                         │
│  │   EXECUTE   │     │    PAUSE    │                         │
│  │    STEP     │     │   REQUEST   │                         │
│  │             │     │   APPROVAL  │                         │
│  └──────┬──────┘     └─────────────┘                         │
│         │                                                     │
│         ▼                                                     │
│  ┌─────────────────────────────────────────────┐              │
│  │           CREATE CHECKPOINT                  │              │
│  │  - Save current state                        │              │
│  │  - Record progress                           │              │
│  │  - Enable resume                             │              │
│  └──────────────────┬──────────────────────────┘              │
│                     │                                          │
│          ┌─────────┴─────────┐                                │
│          │                   │                                │
│       more steps         all done                             │
│          │                   │                                │
│          │                   ▼                                │
│          │           ┌─────────────┐                          │
│          └──────────▶│   COMPLETE  │                          │
│                      └─────────────┘                          │
└─────────────────────────────────────────────────────────────────┘

interface Checkpoint {
  id: string;
  execution_id: string;
  step_index: number;
  state: {
    completedSteps: string[];
    pendingSteps: string[];
    intermediateResults: Record<string, any>;
    tokensUsed: number;
    costIncurred: number;
  };
  created_at: Date;
  expires_at: Date;
}

// Create checkpoint after each step
async function createCheckpoint(execution: Execution) {
  await db.query(`
    INSERT INTO checkpoint_snapshots (
      execution_id, step_index, state, created_at, expires_at
    ) VALUES ($1, $2, $3, NOW(), NOW() + INTERVAL '24 hours')
  `, [execution.id, execution.currentStep, execution.state]);
}

// Resume from checkpoint
async function resumeFromCheckpoint(executionId: string) {
  const checkpoint = await db.query(`
    SELECT * FROM checkpoint_snapshots
    WHERE execution_id = $1
    ORDER BY step_index DESC
    LIMIT 1
  `, [executionId]);

  return continueExecution(checkpoint.state);
}

interface BudgetLimit {
  maxTokens: number;
  maxCost: number;
  warningThreshold: number; // e.g., 0.8 = warn at 80%
}

// Budget check before each step
async function checkBudget(execution: Execution): Promise<BudgetStatus> {
  const budget = await getBudgetLimit(execution.project_id);
  const usage = await getUsage(execution.id);

  if (usage.tokens >= budget.maxTokens || usage.cost >= budget.maxCost) {
    return { status: 'exceeded', requiresApproval: true };
  }

  if (usage.tokens >= budget.maxTokens * budget.warningThreshold) {
    return { status: 'warning', message: 'Approaching budget limit' };
  }

  return { status: 'ok' };
}

interface AgentHandoff {
  from: string;      // Source agent
  to: string;        // Target agent
  reason: string;    // Why handoff needed
  context: {
    task: string;
    progress: any;
    requirements: any;
  };
}

// Handoff example
const handoff: AgentHandoff = {
  from: 'requirements-compiler',
  to: 'architecture-compiler',
  reason: 'Requirements complete, need architecture decisions',
  context: {
    task: 'compile-architecture',
    progress: { requirementsComplete: true },
    requirements: compiledRequirements
  }
};

// mastra.config.ts
import { Mastra } from '@mastra/core';
import { PostgresStore } from '@mastra/pg';

export const mastra = new Mastra({
  agents: {
    'conversation-agent': conversationAgent,
    'discovery-orchestrator': discoveryOrchestratorAgent,
    'pattern-selector': patternSelectorAgent,
    'dod-compiler': dodCompilerAgent,
    // ... all 18 agents
  },
  workflows: {
    'variant-builder': variantBuilderWorkflow,
    'compile-spec': compileSpecWorkflow,
    'multi-agent-spec': multiAgentSpecWorkflow,
    // ... all 10 workflows
  },
  storage: new PostgresStore({
    connectionString: process.env.DATABASE_URL
  }),
  memory: {
    lastMessages: 100,
    semanticRecall: false,
    tokenLimiter: new TokenLimiter({ maxTokens: 120000 })
  }
});

// Example workflow definition
const compileSpecWorkflow = createWorkflow({
  name: 'compile-spec',
  description: 'Compile full specification from project data',
  steps: [
    createStep({
      name: 'gather-inputs',
      execute: async ({ context }) => {
        // Gather discovery output, plan answers, features
        return { inputs: gatheredInputs };
      }
    }),
    createStep({
      name: 'extract-entities',
      execute: async ({ context, inputs }) => {
        // Extract entities using ontology
        return { entities: extractedEntities };
      }
    }),
    createStep({
      name: 'compile-sections',
      execute: async ({ context, entities }) => {
        // Compile each spec section
        return { sections: compiledSections };
      }
    }),
    createStep({
      name: 'validate-spec',
      execute: async ({ context, sections }) => {
        // Run validation agents
        return { spec: validatedSpec };
      }
    })
  ]
});

// Research tools available to agents
const researchTools = {
  webSearch: createTool({
    name: 'web-search',
    description: 'Search the web for information',
    execute: async ({ query }) => {
      return await searchProvider.search(query);
    }
  }),
  competitorAnalysis: createTool({
    name: 'competitor-analysis',
    description: 'Analyze competitor products',
    execute: async ({ competitors }) => {
      return await analyzeCompetitors(competitors);
    }
  })
};

// Attach tools to agent
const marketResearchAgent = createAgent({
  name: 'market-research',
  tools: [researchTools.webSearch, researchTools.competitorAnalysis],
  // ...
});