sf-agent-framework/docs/17-advanced-features/README.md

AI Agent Orchestration Framework for Salesforce Development - Two-phase architecture with 70% context reduction

# Advanced Features Documentation

## Overview

SF-Agent Framework's advanced features enable enterprise-scale Salesforce development with sophisticated context management, intelligent document processing, and automated story generation. These features work together to maximize efficiency and quality.

## Story Management System

### Story-Based Context Engineering

Story-based development is the cornerstone of the framework's context optimization strategy. Each story is a self-contained unit with complete implementation context.

```javascript
// Story Structure
const story = {
  id: 'STORY-001',
  epic: 'Customer Portal',
  title: 'Implement secure user authentication',
  points: 5,
  priority: 'high',

  // Complete context for implementation
  context: {
    businessContext: {
      requirement: 'Users must be able to securely log in to the customer portal',
      acceptanceCriteria: [
        'Users can login with email/password',
        'Password reset functionality available',
        'Session expires after 2 hours of inactivity',
        'Failed login attempts are tracked',
      ],
      stakeholders: ['Product Owner', 'Security Team', 'UX Team'],
    },

    technicalContext: {
      architecture: 'OAuth 2.0 with JWT tokens',
      components: [
        { type: 'apex', name: 'AuthenticationService' },
        { type: 'lwc', name: 'loginForm' },
        { type: 'flow', name: 'passwordResetFlow' },
      ],
      dependencies: ['UserObject', 'SessionManagement', 'EmailService'],
      constraints: ['GDPR compliance', 'Mobile responsive', 'Sub-2s response'],
    },

    implementationGuidance: {
      patterns: ['Singleton for AuthService', 'Builder for JWT tokens'],
      security: ['Hash passwords with bcrypt', 'Implement CSRF protection'],
      testing: ['Unit tests for all paths', 'Integration test for flow'],
      documentation: ['API documentation', 'User guide'],
    },
  },

  // References to external resources
  references: {
    architectureDiagram: 'docs/auth-architecture.png',
    apiSpecification: 'docs/auth-api.yaml',
    mockups: 'designs/login-screens.fig',
    standards: 'standards/security-standards.md',
  },

  // Validation criteria
  validation: {
    coverage: 90,
    performance: { loginTime: '<2s', tokenGeneration: '<500ms' },
    security: ['OWASP Top 10 compliance', 'Penetration tested'],
    accessibility: 'WCAG 2.1 AA',
  },
};
```

### Story Queue Management

```javascript
class StoryQueue {
  constructor() {
    this.queue = [];
    this.inProgress = new Map();
    this.completed = new Set();
  }

  // Intelligent story prioritization
  prioritize() {
    this.queue.sort((a, b) => {
      // Consider multiple factors
      const factors = {
        priority: this.getPriorityScore(a) - this.getPriorityScore(b),
        dependencies: this.getDependencyScore(a) - this.getDependencyScore(b),
        risk: this.getRiskScore(b) - this.getRiskScore(a), // Higher risk first
        value: this.getBusinessValue(b) - this.getBusinessValue(a),
      };

      // Weighted combination
      return factors.priority * 0.3 + factors.dependencies * 0.3 + factors.risk * 0.2 + factors.value * 0.2;
    });
  }

  // Get next story with context preloading
  async getNext() {
    const story = this.queue.shift();

    if (story) {
      // Preload context
      await this.preloadContext(story);

      // Mark as in progress
      this.inProgress.set(story.id, {
        story,
        startTime: Date.now(),
        agent: getCurrentAgent(),
      });
    }

    return story;
  }

  // Parallel story execution
  async executeParallel(maxConcurrent = 4) {
    const executing = [];

    while (this.queue.length > 0 || executing.length > 0) {
      // Start new executions up to limit
      while (executing.length < maxConcurrent && this.queue.length > 0) {
        const story = await this.getNext();
        executing.push(this.executeStory(story));
      }

      // Wait for one to complete
      if (executing.length > 0) {
        const completed = await Promise.race(executing);
        executing.splice(executing.indexOf(completed), 1);
      }
    }
  }
}
```

### Story Generation from Requirements

```javascript
class StoryGenerator {
  async generateFromRequirements(requirements) {
    const stories = [];

    // Parse requirements
    const parsed = await this.parseRequirements(requirements);

    // Break down into epics
    const epics = this.identifyEpics(parsed);

    // Generate stories for each epic
    for (const epic of epics) {
      const epicStories = await this.generateEpicStories(epic);

      // Add technical stories
      epicStories.push(...this.generateTechnicalStories(epic));

      // Add validation stories
      epicStories.push(...this.generateValidationStories(epic));

      stories.push(...epicStories);
    }

    // Sequence and prioritize
    return this.sequenceStories(stories);
  }

  generateEpicStories(epic) {
    const stories = [];

    // User-facing stories
    epic.features.forEach((feature) => {
      stories.push({
        id: generateId(),
        type: 'feature',
        title: `Implement ${feature.name}`,
        epic: epic.name,
        context: this.buildFeatureContext(feature),
        estimate: this.estimateComplexity(feature),
      });
    });

    return stories;
  }

  generateTechnicalStories(epic) {
    const stories = [];

    // Data model stories
    if (epic.requiresDataModel) {
      stories.push({
        type: 'technical',
        title: `Design data model for ${epic.name}`,
        tasks: ['Create ERD', 'Define objects', 'Setup relationships'],
      });
    }

    // Integration stories
    if (epic.integrations?.length > 0) {
      epic.integrations.forEach((integration) => {
        stories.push({
          type: 'integration',
          title: `Integrate with ${integration.system}`,
          context: this.buildIntegrationContext(integration),
        });
      });
    }

    return stories;
  }
}
```

## Document Sharding System

### Intelligent Document Sharding

Document sharding breaks large documents into story-sized pieces that fit within development phase context limits.

```javascript
class DocumentSharder {
  constructor(options = {}) {
    this.maxTokens = options.maxTokens || 8000;
    this.overlap = options.overlap || 500;
    this.strategy = options.strategy || 'semantic';
  }

  async shardDocument(document) {
    const shards = [];

    switch (this.strategy) {
      case 'semantic':
        shards.push(...(await this.semanticSharding(document)));
        break;

      case 'structural':
        shards.push(...(await this.structuralSharding(document)));
        break;

      case 'size':
        shards.push(...(await this.sizeBasedSharding(document)));
        break;

      case 'hybrid':
        shards.push(...(await this.hybridSharding(document)));
        break;
    }

    return this.addMetadata(shards);
  }

  async semanticSharding(document) {
    const shards = [];
    const sections = await this.identifySemanticSections(document);

    for (const section of sections) {
      if (this.getTokenCount(section) <= this.maxTokens) {
        shards.push(section);
      } else {
        // Recursively shard large sections
        shards.push(...(await this.shardLargeSection(section)));
      }
    }

    return shards;
  }

  async structuralSharding(document) {
    // Shard based on document structure (headings, sections)
    const structure = this.parseStructure(document);
    const shards = [];

    structure.sections.forEach((section) => {
      const shard = {
        id: generateId(),
        title: section.title,
        content: section.content,
        level: section.level,
        parent: section.parent,
        children: section.children,
      };

      // Include context from parent/siblings
      shard.context = this.gatherContext(section, structure);

      shards.push(shard);
    });

    return shards;
  }

  addMetadata(shards) {
    return shards.map((shard, index) => ({
      ...shard,
      metadata: {
        index,
        total: shards.length,
        previous: index > 0 ? shards[index - 1].id : null,
        next: index < shards.length - 1 ? shards[index + 1].id : null,
        tokens: this.getTokenCount(shard.content),
        checksum: this.calculateChecksum(shard.content),
        created: new Date().toISOString(),
      },
    }));
  }
}
```

### Shard Optimization

```javascript
class ShardOptimizer {
  optimize(shards, targetContext) {
    // Remove redundancy
    shards = this.deduplicateContent(shards);

    // Compress content
    shards = this.compressShards(shards);

    // Rebalance sizes
    shards = this.rebalanceShards(shards, targetContext);

    // Add cross-references
    shards = this.addCrossReferences(shards);

    return shards;
  }

  deduplicateContent(shards) {
    const seen = new Set();

    return shards.map((shard) => {
      const unique = [];

      shard.content.split('\n').forEach((line) => {
        const hash = this.hashLine(line);
        if (!seen.has(hash)) {
          seen.add(hash);
          unique.push(line);
        }
      });

      return {
        ...shard,
        content: unique.join('\n'),
      };
    });
  }

  compressShards(shards) {
    return shards.map((shard) => ({
      ...shard,
      content: this.compress(shard.content),
      compressed: true,
    }));
  }

  rebalanceShards(shards, targetSize) {
    const rebalanced = [];
    let current = null;

    for (const shard of shards) {
      if (!current) {
        current = shard;
      } else if (this.canMerge(current, shard, targetSize)) {
        current = this.mergeShards(current, shard);
      } else {
        rebalanced.push(current);
        current = shard;
      }
    }

    if (current) {
      rebalanced.push(current);
    }

    return rebalanced;
  }
}
```

## Context Management System

### Intelligent Context Loading

```javascript
class ContextManager {
  constructor(limit = 32000) {
    this.limit = limit;
    this.loaded = new Map();
    this.usage = 0;
    this.cache = new LRUCache(100);
  }

  async loadForTask(task) {
    // Clear previous context
    this.clear();

    // Determine required context
    const required = await this.analyzeRequirements(task);

    // Load in priority order
    for (const item of required) {
      if (this.canLoad(item)) {
        await this.load(item);
      } else {
        // Try compression
        const compressed = await this.compress(item);
        if (this.canLoad(compressed)) {
          await this.load(compressed);
        } else {
          console.warn(`Skipping ${item.name}: insufficient space`);
        }
      }
    }

    return this.getLoadedContext();
  }

  async analyzeRequirements(task) {
    const requirements = [];

    // Always needed
    requirements.push({
      name: 'task-definition',
      content: task.definition,
      priority: 1,
      size: this.estimateSize(task.definition),
    });

    // Task-specific requirements
    if (task.type === 'implementation') {
      requirements.push(
        { name: 'coding-standards', priority: 2 },
        { name: 'api-reference', priority: 3 },
        { name: 'examples', priority: 4 }
      );
    } else if (task.type === 'architecture') {
      requirements.push(
        { name: 'patterns', priority: 2 },
        { name: 'constraints', priority: 3 },
        { name: 'best-practices', priority: 4 }
      );
    }

    // Sort by priority
    return requirements.sort((a, b) => a.priority - b.priority);
  }

  async load(item) {
    // Check cache first
    let content = this.cache.get(item.name);

    if (!content) {
      content = await this.fetchContent(item.name);
      this.cache.set(item.name, content);
    }

    this.loaded.set(item.name, content);
    this.usage += item.size;

    return content;
  }

  canLoad(item) {
    return this.usage + item.size <= this.limit;
  }

  async compress(item) {
    const strategies = [this.removeComments, this.removeWhitespace, this.summarize, this.extractEssential];

    let compressed = { ...item };

    for (const strategy of strategies) {
      compressed = await strategy(compressed);
      if (this.canLoad(compressed)) {
        break;
      }
    }

    return compressed;
  }
}
```

### Context Optimization Strategies

```javascript
class ContextOptimizer {
  constructor() {
    this.strategies = new Map();
    this.metrics = new MetricsCollector();
  }

  registerStrategy(name, strategy) {
    this.strategies.set(name, strategy);
  }

  async optimize(context, target) {
    const startSize = this.getSize(context);
    let optimized = context;

    // Try strategies in order of effectiveness
    const strategies = this.rankStrategies();

    for (const strategy of strategies) {
      optimized = await strategy.apply(optimized);

      if (this.getSize(optimized) <= target) {
        break;
      }
    }

    // Record metrics
    this.metrics.record({
      original: startSize,
      optimized: this.getSize(optimized),
      reduction: (startSize - this.getSize(optimized)) / startSize,
      strategies: strategies.map((s) => s.name),
    });

    return optimized;
  }

  rankStrategies() {
    // Rank based on historical effectiveness
    return Array.from(this.strategies.values()).sort((a, b) => {
      const aScore = this.metrics.getEffectiveness(a.name);
      const bScore = this.metrics.getEffectiveness(b.name);
      return bScore - aScore;
    });
  }
}

// Optimization strategies
const optimizationStrategies = {
  deduplication: {
    name: 'deduplication',
    apply: async (context) => {
      // Remove duplicate content
      const seen = new Set();
      return context.filter((item) => {
        const hash = hash(item);
        if (seen.has(hash)) return false;
        seen.add(hash);
        return true;
      });
    },
  },

  summarization: {
    name: 'summarization',
    apply: async (context) => {
      // Use LLM to summarize verbose content
      const summarized = [];
      for (const item of context) {
        if (item.content.length > 1000) {
          item.content = await summarize(item.content, 300);
        }
        summarized.push(item);
      }
      return summarized;
    },
  },

  compression: {
    name: 'compression',
    apply: async (context) => {
      // Compress using various techniques
      return context.map((item) => ({
        ...item,
        content: compress(item.content),
      }));
    },
  },

  pruning: {
    name: 'pruning',
    apply: async (context) => {
      // Remove low-priority content
      return context.filter((item) => item.priority <= 3);
    },
  },
};
```

## Agent Handoff Protocol

### Formal Handoff System

```javascript
class HandoffProtocol {
  constructor() {
    this.handoffs = new Map();
    this.queue = [];
  }

  async createHandoff(config) {
    const handoff = {
      id: generateHandoffId(),
      from: config.from,
      to: config.to,
      created: new Date().toISOString(),
      status: 'pending',

      artifacts: await this.packageArtifacts(config.artifacts),

      context: {
        summary: config.summary,
        objectives: config.objectives,
        constraints: config.constraints,
        dependencies: config.dependencies,
      },

      instructions: {
        tasks: config.tasks,
        priority: config.priority || 'normal',
        deadline: config.deadline,
        validation: config.validation,
      },

      metadata: {
        tokens: this.calculateTokens(config),
        complexity: this.estimateComplexity(config),
        estimatedDuration: this.estimateDuration(config),
      },
    };

    // Validate handoff
    await this.validateHandoff(handoff);

    // Store and queue
    this.handoffs.set(handoff.id, handoff);
    this.queue.push(handoff);

    // Notify target agent
    await this.notifyAgent(handoff.to, handoff);

    return handoff;
  }

  async packageArtifacts(artifacts) {
    const packaged = [];

    for (const artifact of artifacts) {
      const pkg = {
        id: artifact.id,
        type: artifact.type,
        path: artifact.path,
        content: await this.loadArtifact(artifact),
        checksum: await this.calculateChecksum(artifact),
        metadata: {
          size: artifact.size,
          created: artifact.created,
          modified: artifact.modified,
          author: artifact.author,
        },
      };

      // Compress large artifacts
      if (pkg.content.length > 10000) {
        pkg.content = await this.compress(pkg.content);
        pkg.compressed = true;
      }

      packaged.push(pkg);
    }

    return packaged;
  }

  async acceptHandoff(handoffId, agent) {
    const handoff = this.handoffs.get(handoffId);

    if (!handoff) {
      throw new Error(`Handoff ${handoffId} not found`);
    }

    if (handoff.to !== agent.id) {
      throw new Error(`Handoff ${handoffId} is not for agent ${agent.id}`);
    }

    // Update status
    handoff.status = 'accepted';
    handoff.acceptedAt = new Date().toISOString();
    handoff.acceptedBy = agent.id;

    // Load artifacts into agent context
    await agent.loadArtifacts(handoff.artifacts);

    // Start processing
    const result = await agent.processHandoff(handoff);

    // Update handoff with results
    handoff.status = 'completed';
    handoff.completedAt = new Date().toISOString();
    handoff.results = result;

    return result;
  }
}
```

### Handoff Validation

```javascript
class HandoffValidator {
  async validate(handoff) {
    const validations = [
      this.validateCompleteness,
      this.validateCompatibility,
      this.validateDependencies,
      this.validateSecurity,
      this.validateSize,
    ];

    const results = [];

    for (const validation of validations) {
      const result = await validation(handoff);
      results.push(result);

      if (!result.passed && result.critical) {
        throw new Error(`Critical validation failed: ${result.message}`);
      }
    }

    return {
      passed: results.every((r) => r.passed),
      results,
      warnings: results.filter((r) => !r.passed && !r.critical),
    };
  }

  async validateCompleteness(handoff) {
    const required = ['artifacts', 'context', 'instructions'];
    const missing = required.filter((field) => !handoff[field]);

    return {
      passed: missing.length === 0,
      critical: true,
      message: missing.length > 0 ? `Missing required fields: ${missing}` : 'Complete',
    };
  }

  async validateCompatibility(handoff) {
    // Check if target agent can handle the handoff
    const targetAgent = await getAgent(handoff.to);
    const capabilities = targetAgent.capabilities;

    const required = handoff.instructions.tasks.map((task) => task.type);
    const unsupported = required.filter((r) => !capabilities.includes(r));

    return {
      passed: unsupported.length === 0,
      critical: true,
      message: unsupported.length > 0 ? `Target agent doesn't support: ${unsupported}` : 'Compatible',
    };
  }
}
```

## Interactive Workflow Planning

### User Choice Integration

```javascript
class InteractiveWorkflowPlanner {
  constructor() {
    this.currentWorkflow = null;
    this.choiceHistory = [];
    this.state = {};
  }

  async startInteractive(workflowId) {
    this.currentWorkflow = await this.loadWorkflow(workflowId);

    // Initialize state
    this.state = {
      phase: 'initialization',
      choices: [],
      artifacts: [],
      context: {},
    };

    // Execute interactive flow
    return await this.executeInteractive();
  }

  async executeInteractive() {
    for (const phase of this.currentWorkflow.phases) {
      if (phase.interactive) {
        await this.executeInteractivePhase(phase);
      } else {
        await this.executeAutomatedPhase(phase);
      }

      // Validation gate
      if (phase.validationGate) {
        const approved = await this.validationGate(phase);
        if (!approved) {
          await this.handleRejection(phase);
        }
      }
    }

    return this.state;
  }

  async executeInteractivePhase(phase) {
    for (const step of phase.steps) {
      if (step.userChoice) {
        const choice = await this.presentUserChoice(step);
        this.choiceHistory.push({
          step: step.id,
          choice,
          timestamp: Date.now(),
        });

        // Branch based on choice
        const branch = step.branches[choice];
        if (branch) {
          await this.executeBranch(branch);
        }
      } else {
        await this.executeStep(step);
      }
    }
  }

  async presentUserChoice(step) {
    const prompt = {
      question: step.question,
      options: step.options.map((opt) => ({
        id: opt.id,
        label: opt.label,
        description: opt.description,
        impact: opt.impact,
      })),
      context: this.gatherContext(step),
      recommendation: await this.getRecommendation(step),
    };

    // Present to user (implementation depends on interface)
    return await this.getUserInput(prompt);
  }

  async getRecommendation(step) {
    // AI-powered recommendation based on context
    const factors = {
      projectType: this.state.context.projectType,
      timeline: this.state.context.timeline,
      resources: this.state.context.resources,
      risk: this.state.context.riskTolerance,
    };

    // Analyze options
    const scores = step.options.map((option) => ({
      option,
      score: this.scoreOption(option, factors),
    }));

    // Return best option
    const best = scores.sort((a, b) => b.score - a.score)[0];

    return {
      recommended: best.option.id,
      reason: this.explainRecommendation(best, factors),
    };
  }
}
```

### Workflow Branching Logic

```javascript
class WorkflowBranching {
  constructor(workflow) {
    this.workflow = workflow;
    this.branches = new Map();
    this.conditions = new Map();
  }

  registerBranch(id, branch) {
    this.branches.set(id, branch);
  }

  registerCondition(id, condition) {
    this.conditions.set(id, condition);
  }

  async evaluateBranch(context) {
    for (const [id, condition] of this.conditions) {
      if (await condition.evaluate(context)) {
        return this.branches.get(id);
      }
    }

    // Default branch
    return this.branches.get('default');
  }

  async executeBranch(branchId, context) {
    const branch = this.branches.get(branchId);

    if (!branch) {
      throw new Error(`Branch ${branchId} not found`);
    }

    const results = [];

    for (const step of branch.steps) {
      const result = await this.executeStep(step, context);
      results.push(result);

      // Check for early exit
      if (result.exit) {
        break;
      }

      // Check for nested branching
      if (result.branch) {
        const nestedResults = await this.executeBranch(result.branch, context);
        results.push(...nestedResults);
      }
    }

    return results;
  }
}
```

## Model Context Protocol (MCP) Integration

### MCP Server Implementation

```javascript
class MCPServer {
  constructor(config) {
    this.config = config;
    this.handlers = new Map();
    this.connections = new Map();
  }

  async start() {
    // Initialize server
    this.server = await this.createServer();

    // Register handlers
    this.registerHandlers();

    // Start listening
    await this.server.listen(this.config.port);

    console.log(`MCP Server started on port ${this.config.port}`);
  }

  registerHandlers() {
    // Context management
    this.handlers.set('context.load', async (params) => {
      return await this.loadContext(params);
    });

    this.handlers.set('context.query', async (params) => {
      return await this.queryContext(params);
    });

    // Agent communication
    this.handlers.set('agent.invoke', async (params) => {
      return await this.invokeAgent(params);
    });

    // Workflow execution
    this.handlers.set('workflow.execute', async (params) => {
      return await this.executeWorkflow(params);
    });
  }

  async handleRequest(request) {
    const { method, params, id } = request;

    const handler = this.handlers.get(method);

    if (!handler) {
      return {
        id,
        error: {
          code: -32601,
          message: `Method ${method} not found`,
        },
      };
    }

    try {
      const result = await handler(params);
      return { id, result };
    } catch (error) {
      return {
        id,
        error: {
          code: -32603,
          message: error.message,
        },
      };
    }
  }
}
```

### MCP Client Integration

```javascript
class MCPClient {
  constructor(serverUrl) {
    this.serverUrl = serverUrl;
    this.connected = false;
  }

  async connect() {
    this.connection = await this.establishConnection(this.serverUrl);
    this.connected = true;

    // Setup handlers
    this.setupHandlers();
  }

  async request(method, params) {
    if (!this.connected) {
      await this.connect();
    }

    const request = {
      jsonrpc: '2.0',
      id: generateId(),
      method,
      params,
    };

    const response = await this.sendRequest(request);

    if (response.error) {
      throw new Error(response.error.message);
    }

    return response.result;
  }

  // High-level methods
  async loadContext(files) {
    return await this.request('context.load', { files });
  }

  async invokeAgent(agentId, task) {
    return await this.request('agent.invoke', { agentId, task });
  }

  async executeWorkflow(workflowId, params) {
    return await this.request('workflow.execute', { workflowId, params });
  }
}
```

## Metrics and Analytics

### Performance Metrics Collection

```javascript
class MetricsCollector {
  constructor() {
    this.metrics = {
      performance: new Map(),
      usage: new Map(),
      quality: new Map(),
      cost: new Map(),
    };
  }

  track(category, metric, value) {
    if (!this.metrics[category].has(metric)) {
      this.metrics[category].set(metric, []);
    }

    this.metrics[category].get(metric).push({
      value,
      timestamp: Date.now(),
    });

    // Trigger alerts if needed
    this.checkAlerts(category, metric, value);
  }

  aggregate(category, metric, period) {
    const data = this.metrics[category].get(metric) || [];
    const now = Date.now();
    const periodMs = this.periodToMs(period);

    const relevant = data.filter((d) => now - d.timestamp <= periodMs);

    return {
      count: relevant.length,
      sum: relevant.reduce((sum, d) => sum + d.value, 0),
      avg: relevant.reduce((sum, d) => sum + d.value, 0) / relevant.length,
      min: Math.min(...relevant.map((d) => d.value)),
      max: Math.max(...relevant.map((d) => d.value)),
      p50: this.percentile(
        relevant.map((d) => d.value),
        50
      ),
      p95: this.percentile(
        relevant.map((d) => d.value),
        95
      ),
      p99: this.percentile(
        relevant.map((d) => d.value),
        99
      ),
    };
  }

  generateReport() {
    const report = {
      timestamp: new Date().toISOString(),
      summary: {},
      details: {},
    };

    // Performance metrics
    report.summary.performance = {
      avgResponseTime: this.aggregate('performance', 'responseTime', 'day').avg,
      throughput: this.aggregate('performance', 'requests', 'hour').count,
      errorRate:
        this.aggregate('performance', 'errors', 'day').count / this.aggregate('performance', 'requests', 'day').count,
    };

    // Usage metrics
    report.summary.usage = {
      activeUsers: this.aggregate('usage', 'users', 'day').count,
      tokensUsed: this.aggregate('usage', 'tokens', 'day').sum,
      storiesCompleted: this.aggregate('usage', 'stories', 'week').count,
    };

    // Cost metrics
    report.summary.cost = {
      tokenCost: this.aggregate('cost', 'tokens', 'month').sum,
      apiCost: this.aggregate('cost', 'api', 'month').sum,
      totalCost: this.aggregate('cost', 'total', 'month').sum,
    };

    return report;
  }
}
```

## Advanced Configuration

### Dynamic Configuration System

```javascript
class DynamicConfiguration {
  constructor() {
    this.config = new Map();
    this.watchers = new Map();
    this.validators = new Map();
  }

  set(path, value, options = {}) {
    // Validate value
    if (this.validators.has(path)) {
      const validator = this.validators.get(path);
      if (!validator(value)) {
        throw new Error(`Invalid value for ${path}`);
      }
    }

    // Store old value
    const oldValue = this.get(path);

    // Set new value
    this.setPath(path, value);

    // Notify watchers
    if (this.watchers.has(path)) {
      this.watchers.get(path).forEach((watcher) => {
        watcher({ path, oldValue, newValue: value });
      });
    }

    // Persist if needed
    if (options.persist) {
      this.persist();
    }
  }

  watch(path, callback) {
    if (!this.watchers.has(path)) {
      this.watchers.set(path, new Set());
    }
    this.watchers.get(path).add(callback);

    // Return unwatch function
    return () => {
      this.watchers.get(path).delete(callback);
    };
  }

  registerValidator(path, validator) {
    this.validators.set(path, validator);
  }

  // Feature flags
  isFeatureEnabled(feature) {
    return this.get(`features.${feature}.enabled`) || false;
  }

  // A/B testing
  getVariant(experiment) {
    const variants = this.get(`experiments.${experiment}.variants`) || [];
    const weights = this.get(`experiments.${experiment}.weights`) || [];

    // Select variant based on weights
    return this.selectWeighted(variants, weights);
  }
}
```

## Summary

Advanced features in SF-Agent Framework provide:

1. **Story Management**: Self-contained implementation units with complete context
2. **Document Sharding**: Intelligent breaking of large documents for lean context
3. **Context Optimization**: Smart loading and compression strategies
4. **Agent Handoffs**: Formal protocol for multi-agent collaboration
5. **Interactive Workflows**: User-guided execution with branching logic
6. **MCP Integration**: Standards-based model context protocol
7. **Metrics & Analytics**: Comprehensive performance tracking
8. **Dynamic Configuration**: Runtime configuration management

These features work together to enable enterprise-scale, AI-augmented Salesforce development with unprecedented efficiency and quality.

---

_Last Updated: 2025-08-11_
_Version: 4.0.0_