0xray 3.2.0 → 3.3.1

package/src/mcps/knowledge-skills/storyteller.server.ts

@@ -0,0 +1,206 @@
+/**
+ * Storyteller MCP Server
+ *
+ * Returns storyteller SKILL.md guidance plus a session-aware writing prompt.
+ * The host LLM writes the story; this server supplies the contract.
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { XrayKnowledgeSkillBase } from '../shared/knowledge-skill-base.js';
+
+const STORY_TYPES = ['reflection', 'saga', 'journey', 'narrative'] as const;
+type StoryType = (typeof STORY_TYPES)[number];
+
+interface WriteStoryArgs {
+  title?: string;
+  context?: Record<string, unknown>;
+  framework?: string;
+  output?: string;
+}
+
+function resolveSkillMd(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join(here, '../../../skills/storyteller/SKILL.md'),
+    join(here, '../../skills/storyteller/SKILL.md'),
+    join(process.cwd(), 'node_modules/0xray/dist/skills/storyteller/SKILL.md'),
+    join(process.cwd(), 'node_modules/xray/dist/skills/storyteller/SKILL.md'),
+  ];
+
+  for (const path of candidates) {
+    if (existsSync(path)) {
+      return readFileSync(path, 'utf-8');
+    }
+  }
+
+  return '# Storyteller\n\nWrite warmly candid technical reflections with scene-first openings.';
+}
+
+function getStoryMeta(storyType: StoryType) {
+  const defaults: Record<
+    StoryType,
+    { location: string; min_words: number; ideal_words: number; framework: string }
+  > = {
+    reflection: {
+      location: 'docs/reflections/',
+      min_words: 2000,
+      ideal_words: 5000,
+      framework: 'three_act_structure',
+    },
+    saga: {
+      location: 'docs/reflections/deep/',
+      min_words: 5000,
+      ideal_words: 15000,
+      framework: 'hero_journey',
+    },
+    journey: {
+      location: 'docs/reflections/deep/',
+      min_words: 1500,
+      ideal_words: 4000,
+      framework: 'three_act_structure',
+    },
+    narrative: {
+      location: 'docs/reflections/',
+      min_words: 1000,
+      ideal_words: 3000,
+      framework: 'three_act_structure',
+    },
+  };
+  return defaults[storyType];
+}
+
+function gitContext(): string {
+  try {
+    const commits = execSync('git log --oneline -20 2>/dev/null', { encoding: 'utf-8' });
+    const files = execSync(
+      'git diff --name-only HEAD~10 2>/dev/null || git ls-files 2>/dev/null | head -50',
+      { encoding: 'utf-8' },
+    );
+    return `Recent commits:\n${commits}\n\nRecent files:\n${files}`;
+  } catch {
+    return 'No git context available in this workspace.';
+  }
+}
+
+function buildPrompt(
+  storyType: StoryType,
+  title: string,
+  meta: ReturnType<typeof getStoryMeta>,
+  extraContext?: Record<string, unknown>,
+): string {
+  const contextBlock = extraContext
+    ? `\n## Provided context\n${JSON.stringify(extraContext, null, 2)}\n`
+    : '';
+
+  return `Write a ${storyType} titled "${title}".
+
+## Requirements
+- Framework: ${meta.framework}
+- Target length: ${meta.ideal_words} words (minimum: ${meta.min_words})
+- Save to: ${meta.location}
+- Follow storyteller SKILL.md voice (warmly candid, scene-first, no executive summary)
+- Include Key Takeaways and What Next sections
+
+## Session / repo context
+${gitContext()}
+${contextBlock}
+
+Write the complete ${storyType} now.`;
+}
+
+function writeStoryTool(storyType: StoryType, args: WriteStoryArgs) {
+  const meta = getStoryMeta(storyType);
+  if (args.framework) meta.framework = args.framework;
+
+  const title =
+    args.title ??
+    `${storyType.charAt(0).toUpperCase() + storyType.slice(1)} - ${new Date().toISOString().split('T')[0]}`;
+  const skillMd = resolveSkillMd();
+  const prompt = buildPrompt(storyType, title, meta, args.context);
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+  const filename = `${storyType}-${slug}-${new Date().toISOString().split('T')[0]}.md`;
+  const outputPath = args.output ?? join(meta.location, filename);
+
+  const outputDir = join(process.cwd(), dirname(outputPath));
+  if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
+
+  const fullPath = join(process.cwd(), outputPath);
+  const frontmatter = `---
+story_type: ${storyType}
+title: "${title}"
+framework: ${meta.framework}
+target_words: ${meta.ideal_words}
+---
+
+`;
+
+  writeFileSync(fullPath, `${frontmatter}\n${prompt}\n`, 'utf-8');
+
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: [
+          `Storyteller ${storyType} brief prepared.`,
+          `Output template: ${outputPath}`,
+          '',
+          '--- SKILL (excerpt) ---',
+          skillMd.slice(0, 4000),
+          skillMd.length > 4000 ? '\n...(truncated; full SKILL.md on disk)' : '',
+          '',
+          '--- WRITING PROMPT ---',
+          prompt,
+          '',
+          'Host LLM: write the full story into the output path using the prompt above.',
+        ].join('\n'),
+      },
+    ],
+  };
+}
+
+class StorytellerServer extends XrayKnowledgeSkillBase {
+  constructor() {
+    super('storyteller', '1.0.0');
+
+    const writeSchema = {
+      type: 'object' as const,
+      properties: {
+        title: { type: 'string', description: 'Story title' },
+        context: { type: 'object', description: 'Session context (commits, changes, notes)' },
+        framework: { type: 'string', description: 'Storytelling framework override' },
+        output: { type: 'string', description: 'Relative output path' },
+      },
+    };
+
+    this.tools = STORY_TYPES.map((storyType) => ({
+      name: `write_${storyType}`,
+      description: `Prepare ${storyType} story brief using storyteller SKILL.md`,
+      inputSchema: writeSchema,
+    }));
+
+    this.handlers = {
+      write_reflection: async (args) => writeStoryTool('reflection', args as WriteStoryArgs),
+      write_saga: async (args) => writeStoryTool('saga', args as WriteStoryArgs),
+      write_journey: async (args) => writeStoryTool('journey', args as WriteStoryArgs),
+      write_narrative: async (args) => writeStoryTool('narrative', args as WriteStoryArgs),
+    };
+
+    this.setupToolHandlers();
+  }
+}
+
+if (import.meta.url === `file://${fileURLToPath(import.meta.url)}`) {
+  const server = new StorytellerServer();
+  server.run().catch((error) => {
+    process.stderr.write(`FATAL: ${String(error)}\n`);
+    process.exit(1);
+  });
+}
+
+export { StorytellerServer };

package/src/mcps/orchestrator/config/agent-capabilities.ts

@@ -1,11 +1,18 @@
 /**
  * Agent Capabilities Configuration
- * 
- * Centralized agent capability definitions for orchestration decisions
+ *
+ * Centralized agent capability definitions for orchestration decisions.
+ * Enriched at runtime by the active MemoryRoutingProvider (Repertoire, etc.).
  */
 
 import type { AgentCapability } from '../types.js';
 import { AGENT_REGISTRY } from "../../../agents/registry.js";
+import { initializeMemoryRouting } from '../../../memory-routing/index.js';
+import {
+  getProvider,
+  toMemoryCapabilityMap,
+  fromMemoryCapabilityMap,
+} from './memory-routing-bridge.js';
 
 const DEFAULT_AGENT_CAPABILITIES: Record<string, AgentCapability> = Object.fromEntries(
   Object.entries(AGENT_REGISTRY).map(([name, entry]) => [
@@ -18,18 +25,31 @@ const DEFAULT_AGENT_CAPABILITIES: Record<string, AgentCapability> = Object.fromE
   ]),
 );
 
+initializeMemoryRouting();
+
 /**
  * Agent Capabilities Manager
  * Manages agent capabilities for orchestration decisions
  */
 export class AgentCapabilitiesManager {
   private capabilities: Map<string, AgentCapability> = new Map();
+  private enriched = false;
 
   constructor() {
-    // Initialize with default capabilities
     Object.entries(DEFAULT_AGENT_CAPABILITIES).forEach(([agent, config]) => {
       this.capabilities.set(agent, config);
     });
+    this.applyMemoryRoutingEnrichment();
+  }
+
+  private applyMemoryRoutingEnrichment(): void {
+    const provider = getProvider();
+    if (provider.id === 'null') return;
+
+    const memoryCaps = toMemoryCapabilityMap(this.capabilities);
+    const enriched = provider.enhanceAgentCapabilities(memoryCaps);
+    this.capabilities = fromMemoryCapabilityMap(enriched);
+    this.enriched = true;
   }
 
   /**
@@ -43,6 +63,7 @@ export class AgentCapabilitiesManager {
    * Get all registered agent capabilities
    */
   getAllCapabilities(): Map<string, AgentCapability> {
+    if (!this.enriched) this.applyMemoryRoutingEnrichment();
     return new Map(this.capabilities);
   }
 
@@ -54,24 +75,35 @@ export class AgentCapabilitiesManager {
   }
 
   /**
-   * Select the best agent for a task based on complexity and capabilities
+   * Select the best agent for a task based on complexity, capabilities, and memory routing.
    */
-  selectAgentForTask(requiredCapabilities: string[], complexity: number): string | null {
+  selectAgentForTask(
+    requiredCapabilities: string[],
+    complexity: number,
+    operationDescription = '',
+  ): string | null {
+    const provider = getProvider();
+
+    if (provider.id !== 'null' && operationDescription) {
+      const memoryCaps = toMemoryCapabilityMap(this.getAllCapabilities());
+      return provider.selectAgent(
+        memoryCaps,
+        requiredCapabilities,
+        complexity,
+        operationDescription,
+      );
+    }
+
     let bestAgent: string | null = null;
     let bestScore = -1;
 
     for (const [agent, caps] of this.capabilities) {
-      // Check if agent can handle the complexity
-      if (complexity > caps.complexityThreshold) {
-        continue;
-      }
+      if (complexity > caps.complexityThreshold) continue;
 
-      // Calculate capability match score
-      const matchCount = requiredCapabilities.filter(cap =>
-        caps.capabilities.includes(cap)
+      const matchCount = requiredCapabilities.filter((cap) =>
+        caps.capabilities.includes(cap),
       ).length;
 
-      // Prefer agents with more concurrent tasks available
       const score = matchCount * 10 + caps.concurrentTasks;
 
       if (score > bestScore) {
@@ -97,7 +129,6 @@ export class AgentCapabilitiesManager {
   }
 }
 
-// Singleton instance
 let capabilitiesManagerInstance: AgentCapabilitiesManager | null = null;
 
 export function getAgentCapabilitiesManager(): AgentCapabilitiesManager {
@@ -106,3 +137,7 @@ export function getAgentCapabilitiesManager(): AgentCapabilitiesManager {
   }
   return capabilitiesManagerInstance;
 }
+
+export function resetAgentCapabilitiesManager(): void {
+  capabilitiesManagerInstance = null;
+}

package/src/mcps/orchestrator/config/memory-routing-bridge.ts

@@ -0,0 +1,80 @@
+/**
+ * Bridge between orchestrator types and the pluggable MemoryRoutingProvider.
+ */
+
+import {
+  getMemoryRoutingProviderSync,
+  type MemoryAgentCapability,
+  type MemoryOrchestrationTask,
+  type MemoryRoutingProvider,
+} from '../../../memory-routing/index.js';
+import type { AgentCapability, OrchestrationTask } from '../types.js';
+
+export function toMemoryCapability(caps: AgentCapability): MemoryAgentCapability {
+  const result: MemoryAgentCapability = {
+    capabilities: caps.capabilities,
+    complexityThreshold: caps.complexityThreshold,
+    concurrentTasks: caps.concurrentTasks,
+  };
+  if (caps.memorySignals) result.memorySignals = caps.memorySignals;
+  if (caps.memoryTags) result.memoryTags = caps.memoryTags;
+  return result;
+}
+
+export function fromMemoryCapability(caps: MemoryAgentCapability): AgentCapability {
+  const result: AgentCapability = {
+    capabilities: caps.capabilities,
+    complexityThreshold: caps.complexityThreshold,
+    concurrentTasks: caps.concurrentTasks,
+  };
+  if (caps.memorySignals) result.memorySignals = caps.memorySignals;
+  if (caps.memoryTags) result.memoryTags = caps.memoryTags;
+  return result;
+}
+
+export function toMemoryTask(task: OrchestrationTask): MemoryOrchestrationTask {
+  const result: MemoryOrchestrationTask = {
+    id: task.id,
+    description: task.description,
+    type: task.type,
+  };
+  if (task.priority) result.priority = task.priority;
+  if (task.dependencies) result.dependencies = task.dependencies;
+  if (task.estimatedComplexity !== undefined) result.estimatedComplexity = task.estimatedComplexity;
+  if (task.metadata) result.metadata = task.metadata as Record<string, unknown>;
+  return result;
+}
+
+export function fromMemoryTask(task: MemoryOrchestrationTask): OrchestrationTask {
+  const result: OrchestrationTask = {
+    id: task.id,
+    description: task.description,
+    type: task.type,
+  };
+  if (task.priority) result.priority = task.priority;
+  if (task.dependencies) result.dependencies = task.dependencies;
+  if (task.estimatedComplexity !== undefined) result.estimatedComplexity = task.estimatedComplexity;
+  const metadata = task.metadata as OrchestrationTask['metadata'];
+  if (metadata) result.metadata = metadata;
+  return result;
+}
+
+export function toMemoryCapabilityMap(
+  caps: Map<string, AgentCapability>,
+): Map<string, MemoryAgentCapability> {
+  return new Map(
+    Array.from(caps.entries()).map(([k, v]) => [k, toMemoryCapability(v)]),
+  );
+}
+
+export function fromMemoryCapabilityMap(
+  caps: Map<string, MemoryAgentCapability>,
+): Map<string, AgentCapability> {
+  return new Map(
+    Array.from(caps.entries()).map(([k, v]) => [k, fromMemoryCapability(v)]),
+  );
+}
+
+export function getProvider(): MemoryRoutingProvider {
+  return getMemoryRoutingProviderSync();
+}

package/src/mcps/orchestrator/execution/execution-planner.ts

@@ -11,6 +11,11 @@ import type {
   TaskValidation 
 } from '../types.js';
 import { getAgentCapabilitiesManager } from '../config/agent-capabilities.js';
+import {
+  getProvider,
+  toMemoryTask,
+  fromMemoryTask,
+} from '../config/memory-routing-bridge.js';
 
 /**
  * Execution Planner
@@ -67,29 +72,41 @@ export class ExecutionPlanner {
     tasks: OrchestrationTask[],
     executionMode: string
   ): Promise<ExecutionPlan> {
+    const provider = getProvider();
+    const memoryTasks = provider.enrichTasks(tasks.map(toMemoryTask));
+    const enrichedTasks = memoryTasks.map(fromMemoryTask);
+
     const agentAssignments = new Map<string, OrchestrationTask[]>();
 
     switch (executionMode) {
       case 'parallel':
-        this.createParallelPlan(tasks, agentAssignments);
+        this.createParallelPlan(enrichedTasks, agentAssignments);
         break;
       case 'sequential':
-        this.createSequentialPlan(tasks, agentAssignments);
+        this.createSequentialPlan(enrichedTasks, agentAssignments);
         break;
       case 'optimized':
       default:
-        await this.createOptimizedPlan(tasks, agentAssignments);
+        await this.createOptimizedPlan(enrichedTasks, agentAssignments);
         break;
     }
 
     const estimatedDuration = this.estimateExecutionDuration(agentAssignments);
 
-    return {
-      tasks,
+    const plan: ExecutionPlan = {
+      tasks: enrichedTasks,
       strategy: executionMode as 'parallel' | 'sequential' | 'optimized',
       agentAssignments,
       estimatedDuration,
     };
+
+    if (provider.id !== 'null') {
+      plan.memoryContext = {
+        ...provider.buildInheritedContext(memoryTasks),
+      } as Record<string, unknown>;
+    }
+
+    return plan;
   }
 
   /**
@@ -196,10 +213,18 @@ export class ExecutionPlanner {
     agentAssignments: Map<string, OrchestrationTask[]>
   ): void {
     for (const task of tasks) {
-      const complexity = task.estimatedComplexity || 30;
+      const complexity = this.calculateTaskComplexity(task);
+      const requiredCaps = [
+        task.type,
+        ...(task.metadata?.memorySignals ?? []),
+      ];
+      const operationDescription = task.metadata?.memoryHighConfidenceTrap
+        ? `${task.description} TYPE: ontological-trap`
+        : task.description;
       const agent = this.capabilitiesManager.selectAgentForTask(
-        [task.type],
-        complexity
+        requiredCaps,
+        complexity,
+        operationDescription,
       ) || 'orchestrator';
 
       if (!agentAssignments.has(agent)) {
@@ -247,9 +272,14 @@ export class ExecutionPlanner {
       });
 
       // Assign to agent
+      const requiredCaps = [
+        task.type,
+        ...(task.metadata?.memorySignals ?? []),
+      ];
       const agent = this.capabilitiesManager.selectAgentForTask(
-        [task.type],
-        complexity
+        requiredCaps,
+        complexity,
+        task.description,
       ) || 'orchestrator';
 
       if (!assignments.has(agent)) {
@@ -319,6 +349,15 @@ export class ExecutionPlanner {
       complexity += task.dependencies.length * 5;
     }
 
+    if (task.metadata?.memoryComplexityBoost !== undefined) {
+      complexity += task.metadata.memoryComplexityBoost;
+    } else {
+      const provider = getProvider();
+      if (provider.id !== 'null' && provider.getTaskConfidence) {
+        complexity += provider.getTaskConfidence(toMemoryTask(task)).complexityBoost;
+      }
+    }
+
     return Math.min(Math.max(Math.round(complexity), 1), 100);
   }
 

package/src/mcps/orchestrator/handlers/task-handler.ts

@@ -7,7 +7,8 @@
 import { frameworkLogger } from '../../../core/framework-logger.js';
 import { getExecutionPlanner } from '../execution/execution-planner.js';
 import { mcpClientManager } from '../../../mcps/mcp-client.js';
-import { addObservations, extractOrchestrationObservations } from '../aside-context.js';
+import { addObservations, extractOrchestrationObservations, spawnAside } from '../aside-context.js';
+import { getProvider } from '../config/memory-routing-bridge.js';
 import type { OrchestrationResult, OrchestrationTask } from '../types.js';
 
 export interface TaskHandlerDeps {
@@ -76,9 +77,43 @@ export class TaskHandler {
       // Analyze complexity and create execution plan
       const executionPlan = await this.planner.createExecutionPlan(tasks, executionMode);
 
+      const memoryProvider = getProvider();
+      if (memoryProvider.id !== 'null' && executionPlan.memoryContext) {
+        await spawnAside({
+          description: `Orchestrate: ${description}`,
+          sessionId,
+          inheritedContext: {
+            memoryRouting: executionPlan.memoryContext,
+          },
+        });
+      }
+
       // Execute orchestration (simulated for MCP server)
       const results = await this.executePlan(executionPlan, sessionId, timeout);
 
+      // Feed per-task outcomes back to memory provider (not aggregate session stats)
+      if (memoryProvider.ingestFeedback) {
+        const outcomeByKey = new Map(
+          results.taskOutcomes.map((o) => [`${o.agent}:${o.taskId}`, o]),
+        );
+
+        for (const [agent, assignedTasks] of executionPlan.agentAssignments) {
+          for (const task of assignedTasks) {
+            const outcome = outcomeByKey.get(`${agent}:${task.id}`);
+            memoryProvider.ingestFeedback({
+              timestamp: new Date().toISOString(),
+              sessionId,
+              taskId: task.id,
+              assignedAgent: agent,
+              memorySignals: task.metadata?.memorySignals ?? [],
+              complexity: task.estimatedComplexity ?? 30,
+              success: outcome?.success ?? false,
+              durationMs: outcome?.durationMs ?? 0,
+            });
+          }
+        }
+      }
+
       // Update result
       orchestrationResult.success = results.success;
       orchestrationResult.completedTasks = results.completedTasks;
@@ -136,11 +171,23 @@ export class TaskHandler {
     bottlenecks: string[];
     recommendations: string[];
     agentOutputs?: Record<string, string>;
+    taskOutcomes: Array<{
+      taskId: string;
+      agent: string;
+      success: boolean;
+      durationMs: number;
+    }>;
   }> {
     const agentUtilization: Record<string, number> = {};
     let completedTasks = 0;
     let failedTasks = 0;
     const agentOutputs: Record<string, string> = {};
+    const taskOutcomes: Array<{
+      taskId: string;
+      agent: string;
+      success: boolean;
+      durationMs: number;
+    }> = [];
 
     const skillServers = new Set([
       'code-review', 'code-reviewer',
@@ -158,6 +205,7 @@ export class TaskHandler {
 
       if (skillServers.has(agent)) {
         for (const task of tasks) {
+          const taskStart = Date.now();
           try {
             const toolName = this.mapAgentToTool(agent);
             const result = await mcpClientManager.callServerTool(agent, toolName, {
@@ -169,9 +217,21 @@ export class TaskHandler {
             const outputText = this.extractTextFromMcpResult(result);
             agentOutputs[`${agent}:${task.id}`] = outputText;
             completedTasks++;
+            taskOutcomes.push({
+              taskId: task.id,
+              agent,
+              success: true,
+              durationMs: Date.now() - taskStart,
+            });
           } catch (err) {
             failedTasks++;
             agentOutputs[`${agent}:${task.id}`] = `Error: ${err instanceof Error ? err.message : String(err)}`;
+            taskOutcomes.push({
+              taskId: task.id,
+              agent,
+              success: false,
+              durationMs: Date.now() - taskStart,
+            });
             frameworkLogger.log('orchestrator.task-handler', 'task-execution-failed', 'warning', {
               agent,
               taskId: task.id,
@@ -181,7 +241,15 @@ export class TaskHandler {
         }
       } else {
         // For non-MCP agents we still count them as "assigned" (they will be handled by the caller or legacy path)
-        completedTasks += tasks.length;
+        for (const task of tasks) {
+          completedTasks++;
+          taskOutcomes.push({
+            taskId: task.id,
+            agent,
+            success: true,
+            durationMs: 0,
+          });
+        }
       }
     }
 
@@ -205,6 +273,7 @@ export class TaskHandler {
       bottlenecks,
       recommendations,
       agentOutputs,
+      taskOutcomes,
     };
   }
 

package/src/mcps/orchestrator/types.ts

@@ -8,6 +8,21 @@ export interface AgentCapability {
   capabilities: string[];
   complexityThreshold: number;
   concurrentTasks: number;
+  /** Populated by active MemoryRoutingProvider (e.g. Repertoire) */
+  memorySignals?: string[];
+  memoryTags?: string[];
+}
+
+export interface OrchestrationTaskMetadata {
+  memorySignals?: string[];
+  matchedPrimitives?: string[];
+  synthesisContext?: string;
+  ontologicalTrapDetected?: boolean;
+  memoryProviderId?: string;
+  memorySignalConfidences?: Record<string, number>;
+  memoryAvgConfidence?: number;
+  memoryHighConfidenceTrap?: boolean;
+  memoryComplexityBoost?: number;
 }
 
 export interface OrchestrationTask {
@@ -17,6 +32,7 @@ export interface OrchestrationTask {
   priority?: 'critical' | 'high' | 'medium' | 'low';
   dependencies?: string[];
   estimatedComplexity?: number;
+  metadata?: OrchestrationTaskMetadata;
 }
 
 export interface ExecutionPlan {
@@ -24,6 +40,7 @@ export interface ExecutionPlan {
   strategy: 'parallel' | 'sequential' | 'optimized';
   agentAssignments: Map<string, OrchestrationTask[]>;
   estimatedDuration: number;
+  memoryContext?: Record<string, unknown>;
 }
 
 export interface OrchestrationResult {