cognitive-core 0.1.0 → 0.2.0

package/src/runtime/backends/macro-agent.ts

@@ -0,0 +1,177 @@
+/**
+ * macro-agent backend adapter.
+ *
+ * Wraps macro-agent's MacroAgentBackend as a cognitive-core AgentBackend
+ * using structural typing — cognitive-core does not import macro-agent.
+ *
+ * Usage:
+ * ```typescript
+ * import { MacroAgentBackend } from 'macro-agent';
+ * import { adaptMacroBackend, createMacroAgentSource } from 'cognitive-core';
+ *
+ * const macroBackend = new MacroAgentBackend(agentManager);
+ * const backend = adaptMacroBackend(macroBackend);
+ * atlas.setAgentManager([backend]);
+ *
+ * // Or register as a ComputeSource:
+ * const source = createMacroAgentSource(macroBackend, { costTier: 'medium' });
+ * computeProvider.register(source);
+ * ```
+ */
+
+import type {
+  AgentBackend,
+  AgentSpawnConfig,
+  AgentSession,
+  AgentMessage,
+  ToolCall,
+} from '../types.js';
+import type { ComputeSource, CostTier } from '../compute-provider.js';
+import type { Task } from '../../types/index.js';
+
+// ── Structural interface ──────────────────────────────────────
+
+/**
+ * Structural contract for macro-agent's MacroAgentBackend.
+ *
+ * Any object matching this shape can be adapted — no import from
+ * macro-agent is needed. macro-agent's bridge types (CognitiveAgentSession,
+ * CognitiveAgentMessage, CognitiveToolCall) are structurally identical
+ * to cognitive-core's canonical types.
+ */
+export interface MacroAgentBackendLike {
+  readonly name: string;
+  readonly supportedTypes: readonly string[];
+  isAvailable(): Promise<boolean>;
+  spawn(config: {
+    agentType: string;
+    task: { description: string };
+  }): Promise<MacroSessionLike>;
+  getSession(sessionId: string): Promise<MacroSessionLike | undefined>;
+  terminate(sessionId: string): Promise<void>;
+  listSessions(): Promise<MacroSessionLike[]>;
+}
+
+/**
+ * Structural contract for macro-agent's CognitiveAgentSession.
+ */
+export interface MacroSessionLike {
+  id: string;
+  agentType: string;
+  task: { description: string };
+  state: string;
+  messages: AgentMessage[];
+  toolCalls: ToolCall[];
+  startTime: Date;
+  endTime?: Date;
+  result?: unknown;
+  error?: string;
+  metadata: Record<string, unknown>;
+}
+
+// ── Adapter ───────────────────────────────────────────────────
+
+/**
+ * Adapter that wraps a macro-agent-compatible backend as a cognitive-core
+ * AgentBackend.
+ *
+ * Handles the type gap between macro-agent's CognitiveTask (description-only
+ * subset) and cognitive-core's Task (full schema with id, domain, etc.).
+ * Since cognitive-core always passes full Task objects through spawn(),
+ * the adapter caches them and re-attaches on session retrieval.
+ */
+export class MacroAgentBackendAdapter implements AgentBackend {
+  readonly name: string;
+  readonly supportedTypes: string[];
+
+  private readonly inner: MacroAgentBackendLike;
+  private readonly taskCache = new Map<string, Task>();
+
+  constructor(backend: MacroAgentBackendLike) {
+    this.inner = backend;
+    this.name = backend.name;
+    this.supportedTypes = [...backend.supportedTypes];
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return this.inner.isAvailable();
+  }
+
+  async spawn(config: AgentSpawnConfig): Promise<AgentSession> {
+    const session = await this.inner.spawn(config);
+    this.taskCache.set(session.id, config.task);
+    return this.toAgentSession(session);
+  }
+
+  async getSession(sessionId: string): Promise<AgentSession | undefined> {
+    const session = await this.inner.getSession(sessionId);
+    if (!session) return undefined;
+    return this.toAgentSession(session);
+  }
+
+  async terminate(sessionId: string): Promise<void> {
+    return this.inner.terminate(sessionId);
+  }
+
+  async listSessions(): Promise<AgentSession[]> {
+    const sessions = await this.inner.listSessions();
+    return sessions.map(s => this.toAgentSession(s));
+  }
+
+  private toAgentSession(session: MacroSessionLike): AgentSession {
+    const task = this.taskCache.get(session.id);
+    return {
+      id: session.id,
+      agentType: session.agentType,
+      // Prefer the cached full Task; fall back to runtime object (which IS
+      // a full Task when cognitive-core is the caller, just typed narrowly).
+      task: task ?? (session.task as Task),
+      state: session.state as AgentSession['state'],
+      messages: session.messages,
+      toolCalls: session.toolCalls,
+      startTime: session.startTime,
+      endTime: session.endTime,
+      result: session.result,
+      error: session.error,
+      metadata: session.metadata,
+    };
+  }
+}
+
+// ── Factory helpers ───────────────────────────────────────────
+
+/**
+ * Adapt a macro-agent MacroAgentBackend for use with cognitive-core.
+ *
+ * @param backend - Any object matching the MacroAgentBackendLike shape
+ * @returns An AgentBackend usable with Atlas.setAgentManager()
+ */
+export function adaptMacroBackend(
+  backend: MacroAgentBackendLike,
+): AgentBackend {
+  return new MacroAgentBackendAdapter(backend);
+}
+
+/**
+ * Create a ComputeSource for macro-agent backend registration
+ * with DefaultComputeProvider.
+ *
+ * @param backend - Any object matching the MacroAgentBackendLike shape
+ * @param options - Cost tier, location, and priority for compute resolution
+ */
+export function createMacroAgentSource(
+  backend: MacroAgentBackendLike,
+  options?: {
+    costTier?: CostTier;
+    location?: 'local' | 'remote';
+    priority?: number;
+  },
+): ComputeSource {
+  return {
+    name: backend.name,
+    backend: adaptMacroBackend(backend),
+    costTier: options?.costTier ?? 'medium',
+    location: options?.location ?? 'local',
+    priority: options?.priority ?? 50,
+  };
+}

package/src/runtime/compute-provider.ts

@@ -0,0 +1,206 @@
+import type { AgentBackend, AgentSpawnConfig } from './types.js';
+import type { AnalysisComplexity } from '../workspace/types.js';
+
+// ============================================================
+// Compute Requirements
+// ============================================================
+
+/**
+ * Requirements for compute resolution.
+ * Templates express preferences; the provider resolves them to concrete backends.
+ */
+export interface ComputeRequirements {
+  /** Preferred execution location */
+  mode?: 'local' | 'remote' | 'any';
+  /** Maximum cost budget in cents (for cost-aware routing) */
+  maxCostCents?: number;
+  /** Required agent capabilities */
+  capabilities?: string[];
+  /** Timeout hint (provider may select faster backends for short timeouts) */
+  timeout?: number;
+  /** Complexity hint from template */
+  complexity?: AnalysisComplexity;
+}
+
+// ============================================================
+// Compute Target
+// ============================================================
+
+/**
+ * Resolution result: which backend to use and any config overrides.
+ */
+export interface ComputeTarget {
+  /** The resolved backend */
+  backend: AgentBackend;
+  /** Config overrides for this resolution (e.g., different timeout, env vars) */
+  overrides?: Partial<AgentSpawnConfig>;
+  /** Source identifier for logging/metrics */
+  source: string;
+}
+
+// ============================================================
+// Compute Source
+// ============================================================
+
+/** Cost tier for routing decisions */
+export type CostTier = 'free' | 'low' | 'medium' | 'high';
+
+/**
+ * Registered compute source with metadata.
+ */
+export interface ComputeSource {
+  /** Unique name for this source */
+  name: string;
+  /** Underlying backend */
+  backend: AgentBackend;
+  /** Cost tier for routing decisions */
+  costTier: CostTier;
+  /** Execution location */
+  location: 'local' | 'remote';
+  /** Priority (lower = preferred, for tie-breaking) */
+  priority: number;
+}
+
+// ============================================================
+// ComputeProvider Interface
+// ============================================================
+
+/**
+ * Resolves agent type + requirements to a concrete compute target.
+ *
+ * Sits between AgentManager and the raw backend registry.
+ * Separates "what agent to run" from "where to run it".
+ */
+export interface ComputeProvider {
+  /** Resolve an agent execution request to a backend */
+  resolve(
+    agentType: string,
+    requirements?: ComputeRequirements
+  ): Promise<ComputeTarget>;
+
+  /** Register a compute source */
+  register(source: ComputeSource): void;
+
+  /** Remove a compute source */
+  unregister(name: string): void;
+
+  /** List available compute sources */
+  listSources(): ComputeSource[];
+
+  /** Check if any source supports the given agent type */
+  supports(agentType: string): boolean;
+}
+
+// ============================================================
+// Default Implementation
+// ============================================================
+
+const COST_ORDER: Record<CostTier, number> = {
+  free: 0,
+  low: 1,
+  medium: 5,
+  high: 20,
+};
+
+/**
+ * Default compute provider.
+ *
+ * Resolution strategy:
+ * 1. Filter to sources that support the requested agent type
+ * 2. Apply mode preference (local/remote) if specified
+ * 3. Apply cost budget if specified
+ * 4. Check availability in priority order
+ * 5. Return first available (or first candidate as fallback)
+ */
+export class DefaultComputeProvider implements ComputeProvider {
+  private sources: ComputeSource[] = [];
+
+  register(source: ComputeSource): void {
+    // Remove existing source with same name (re-registration)
+    this.sources = this.sources.filter(s => s.name !== source.name);
+    this.sources.push(source);
+    // Keep sorted by priority (lower = preferred)
+    this.sources.sort((a, b) => a.priority - b.priority);
+  }
+
+  unregister(name: string): void {
+    this.sources = this.sources.filter(s => s.name !== name);
+  }
+
+  listSources(): ComputeSource[] {
+    return [...this.sources];
+  }
+
+  supports(agentType: string): boolean {
+    return this.sources.some(
+      s => s.backend.supportedTypes.includes(agentType)
+    );
+  }
+
+  async resolve(
+    agentType: string,
+    requirements?: ComputeRequirements
+  ): Promise<ComputeTarget> {
+    // Step 1: Filter to sources that support this agent type
+    let candidates = this.sources.filter(
+      s => s.backend.supportedTypes.includes(agentType)
+    );
+
+    if (candidates.length === 0) {
+      // Fallback: try matching by backend name
+      candidates = this.sources.filter(s => s.name === agentType);
+    }
+
+    if (candidates.length === 0) {
+      throw new Error(
+        `No compute source supports agent type '${agentType}'. ` +
+        `Available sources: ${this.sources.map(s => `${s.name}[${s.backend.supportedTypes.join(',')}]`).join(', ') || 'none'}`
+      );
+    }
+
+    // Step 2: Apply mode preference
+    if (requirements?.mode && requirements.mode !== 'any') {
+      const locationFiltered = candidates.filter(
+        s => s.location === requirements.mode
+      );
+      if (locationFiltered.length > 0) {
+        candidates = locationFiltered;
+      }
+      // If no match for preferred mode, fall back to all candidates
+    }
+
+    // Step 3: Apply cost budget
+    if (requirements?.maxCostCents !== undefined) {
+      const budgetFiltered = candidates.filter(
+        s => COST_ORDER[s.costTier] <= requirements.maxCostCents!
+      );
+      if (budgetFiltered.length > 0) {
+        candidates = budgetFiltered;
+      }
+      // If no match within budget, fall back to all candidates
+    }
+
+    // Step 4: Check availability in priority order
+    for (const source of candidates) {
+      if (await source.backend.isAvailable()) {
+        return {
+          backend: source.backend,
+          source: source.name,
+        };
+      }
+    }
+
+    // Step 5: Fallback to first candidate regardless of availability
+    return {
+      backend: candidates[0].backend,
+      source: candidates[0].name,
+    };
+  }
+}
+
+/**
+ * Create a DefaultComputeProvider.
+ */
+export function createComputeProvider(): DefaultComputeProvider {
+  return new DefaultComputeProvider();
+}

package/src/runtime/flows/learning.ts

@@ -1,6 +1,10 @@
 import type { Task } from '../../types/index.js';
 import type { MemorySystem } from '../../memory/system.js';
-import type { LearningPipeline, ProcessResult, BatchResult } from '../../learning/index.js';
+import type {
+  UnifiedLearningPipeline,
+  ImmediateResult,
+  UnifiedBatchResult,
+} from '../../learning/unified-pipeline.js';
 import type { AgentManager } from '../manager.js';
 import type { AgentResult, AgentSession, AgentObserverCallbacks } from '../types.js';
 
@@ -10,9 +14,7 @@ import type { AgentResult, AgentSession, AgentObserverCallbacks } from '../types
 export interface LearningFlowConfig {
   /** Agent type to use for execution */
   agentType: string;
-  /** Minimum trajectories before running batch learning */
-  batchThreshold?: number;
-  /** Whether to auto-run batch learning when threshold is reached */
+  /** Whether to auto-run batch learning when energy threshold is reached */
   autoBatch?: boolean;
   /** Observer callbacks for real-time monitoring */
   observer?: AgentObserverCallbacks;
@@ -24,10 +26,10 @@ export interface LearningFlowConfig {
 export interface LearningFlowResult {
   /** The agent result */
   agentResult: AgentResult;
-  /** Processing result from learning pipeline */
-  processResult: ProcessResult;
-  /** Batch result if batch learning was triggered */
-  batchResult?: BatchResult;
+  /** Processing result from learning pipeline (immediate phase) */
+  immediateResult: ImmediateResult;
+  /** Batch result if batch learning was triggered (included in immediateResult) */
+  batchResult?: UnifiedBatchResult;
 }
 
 /**
@@ -41,19 +43,18 @@ export interface LearningFlowResult {
  */
 export class LearningFlow {
   private manager: AgentManager;
-  private pipeline: LearningPipeline;
+  private pipeline: UnifiedLearningPipeline;
   private config: LearningFlowConfig;
 
   constructor(
     manager: AgentManager,
-    pipeline: LearningPipeline,
+    pipeline: UnifiedLearningPipeline,
     _memory: MemorySystem,
     config: LearningFlowConfig
   ) {
     this.manager = manager;
     this.pipeline = pipeline;
     this.config = {
-      batchThreshold: 10,
       autoBatch: true,
       ...config,
     };
@@ -75,24 +76,15 @@ export class LearningFlow {
       captureToolCalls: true,
     });
 
-    // 2. Process trajectory through learning pipeline
-    const processResult = await this.pipeline.processTrajectory(
+    // 2. Process trajectory through unified pipeline (immediate + optional batch)
+    const immediateResult = await this.pipeline.processTrajectory(
       agentResult.trajectory
     );
 
-    // 3. Run batch learning if threshold reached
-    let batchResult: BatchResult | undefined;
-    if (
-      this.config.autoBatch &&
-      this.pipeline.getAccumulatedCount() >= (this.config.batchThreshold ?? 10)
-    ) {
-      batchResult = await this.pipeline.runBatchLearning();
-    }
-
     return {
       agentResult,
-      processResult,
-      batchResult,
+      immediateResult,
+      batchResult: immediateResult.batchResult,
     };
   }
 
@@ -119,17 +111,8 @@ export class LearningFlow {
     // Extract trajectory from session
     const trajectory = await this.manager.observeAndLearn(session, task);
 
-    // Process through learning pipeline
-    const processResult = await this.pipeline.processTrajectory(trajectory);
-
-    // Check for batch learning
-    let batchResult: BatchResult | undefined;
-    if (
-      this.config.autoBatch &&
-      this.pipeline.getAccumulatedCount() >= (this.config.batchThreshold ?? 10)
-    ) {
-      batchResult = await this.pipeline.runBatchLearning();
-    }
+    // Process through unified pipeline
+    const immediateResult = await this.pipeline.processTrajectory(trajectory);
 
     return {
       agentResult: {
@@ -144,16 +127,16 @@ export class LearningFlow {
           messageCount: session.messages.length,
         },
       },
-      processResult,
-      batchResult,
+      immediateResult,
+      batchResult: immediateResult.batchResult,
     };
   }
 
   /**
    * Force batch learning
    */
-  async runBatchLearning(): Promise<BatchResult> {
-    return this.pipeline.runBatchLearning();
+  async runBatchLearning(): Promise<UnifiedBatchResult> {
+    return this.pipeline.runBatch();
   }
 
   /**
@@ -161,11 +144,11 @@ export class LearningFlow {
    */
   getStats(): {
     pendingTrajectories: number;
-    batchThreshold: number;
+    pipelineStats: ReturnType<UnifiedLearningPipeline['getStats']>;
   } {
     return {
       pendingTrajectories: this.pipeline.getAccumulatedCount(),
-      batchThreshold: this.config.batchThreshold ?? 10,
+      pipelineStats: this.pipeline.getStats(),
     };
   }
 }
@@ -175,7 +158,7 @@ export class LearningFlow {
  */
 export function createLearningFlow(
   manager: AgentManager,
-  pipeline: LearningPipeline,
+  pipeline: UnifiedLearningPipeline,
   memory: MemorySystem,
   config: LearningFlowConfig
 ): LearningFlow {

package/src/runtime/index.ts

@@ -10,6 +10,9 @@ export type {
   KnowledgeInjector,
   TrajectoryExtractor,
   AgentObserverCallbacks,
+  AgentDelegate,
+  AgentDelegateOptions,
+  AgentDelegateResult,
 } from './types.js';
 
 // Manager
@@ -29,13 +32,32 @@ export {
   MockBackend,
   createMockBackend,
   type MockAgentBehavior,
+  LocalACPBackend,
   ACPBackend,
   createACPBackend,
   claudeCodeACPConfig,
   claudeCodeDirectConfig,
   type ACPAgentConfig,
+  ACPProtocolHandler,
+  type ACPSessionBase,
+  MacroAgentBackendAdapter,
+  adaptMacroBackend,
+  createMacroAgentSource,
+  type MacroAgentBackendLike,
+  type MacroSessionLike,
 } from './backends/index.js';
 
+// Compute Provider
+export {
+  DefaultComputeProvider,
+  createComputeProvider,
+  type ComputeProvider,
+  type ComputeRequirements,
+  type ComputeTarget,
+  type ComputeSource,
+  type CostTier,
+} from './compute-provider.js';
+
 // Flows
 export {
   LearningFlow,