cognitive-core 0.1.0 → 0.1.2

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/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,

package/src/runtime/manager.ts

@@ -16,7 +16,10 @@ import type {
   AgentObserverCallbacks,
   KnowledgeInjector,
   TrajectoryExtractor,
+  AgentDelegate,
 } from './types.js';
+import type { ComputeProvider, ComputeSource } from './compute-provider.js';
+import { DefaultComputeProvider } from './compute-provider.js';
 
 /**
  * Default knowledge injector - formats memory for context injection
@@ -223,29 +226,47 @@ export class DefaultTrajectoryExtractor implements TrajectoryExtractor {
  */
 export class AgentManager {
   private backends: Map<string, AgentBackend> = new Map();
+  private computeProvider: ComputeProvider;
   private memory: MemorySystem;
   private injector: KnowledgeInjector;
   private extractor: TrajectoryExtractor;
   private observers: AgentObserverCallbacks[] = [];
   private activeSessions: Map<string, AgentSession> = new Map();
+  private delegate?: AgentDelegate;
 
   constructor(
     memory: MemorySystem,
     options?: {
       injector?: KnowledgeInjector;
       extractor?: TrajectoryExtractor;
+      computeProvider?: ComputeProvider;
+      delegate?: AgentDelegate;
     }
   ) {
     this.memory = memory;
     this.injector = options?.injector ?? new DefaultKnowledgeInjector();
     this.extractor = options?.extractor ?? new DefaultTrajectoryExtractor();
+    this.computeProvider = options?.computeProvider ?? new DefaultComputeProvider();
+    this.delegate = options?.delegate;
   }
 
   /**
-   * Register an agent backend
+   * Register an agent backend.
+   * Also registers it as a compute source with the ComputeProvider.
    */
-  registerBackend(backend: AgentBackend): void {
+  registerBackend(backend: AgentBackend, sourceOptions?: {
+    costTier?: ComputeSource['costTier'];
+    location?: ComputeSource['location'];
+    priority?: number;
+  }): void {
     this.backends.set(backend.name, backend);
+    this.computeProvider.register({
+      name: backend.name,
+      backend,
+      costTier: sourceOptions?.costTier ?? 'low',
+      location: sourceOptions?.location ?? 'local',
+      priority: sourceOptions?.priority ?? 10,
+    });
   }
 
   /**
@@ -262,6 +283,13 @@ export class AgentManager {
     return Array.from(this.backends.keys());
   }
 
+  /**
+   * Get the compute provider for advanced configuration
+   */
+  getComputeProvider(): ComputeProvider {
+    return this.computeProvider;
+  }
+
   /**
    * Add an observer for agent events
    */
@@ -279,18 +307,48 @@ export class AgentManager {
     }
   }
 
+  /**
+   * Set a delegate for caller-provided agent execution.
+   * When set, all spawn() calls bypass backend resolution and use the delegate.
+   */
+  setDelegate(delegate: AgentDelegate): void {
+    this.delegate = delegate;
+  }
+
+  /**
+   * Clear the delegate, reverting to normal backend resolution.
+   */
+  clearDelegate(): void {
+    this.delegate = undefined;
+  }
+
+  /**
+   * Get the current delegate, if any.
+   */
+  getDelegate(): AgentDelegate | undefined {
+    return this.delegate;
+  }
+
   /**
    * Spawn an agent to execute a task
    * This is the main entry point for running agents
    */
   async spawn(config: AgentSpawnConfig): Promise<AgentResult> {
-    // Find appropriate backend
-    const backend = this.findBackend(config.agentType);
-    if (!backend) {
-      throw new Error(
-        `No backend found for agent type: ${config.agentType}. ` +
-          `Available backends: ${this.listBackends().join(', ')}`
-      );
+    // Use delegate if available (bypasses backend resolution)
+    if (this.delegate) {
+      return this.spawnViaDelegate(config);
+    }
+
+    // Resolve compute target via provider
+    const target = await this.computeProvider.resolve(
+      config.agentType,
+      config.computeRequirements,
+    );
+    const backend = target.backend;
+
+    // Merge any overrides from compute resolution
+    if (target.overrides) {
+      config = { ...config, ...target.overrides };
     }
 
     // Query memory for relevant knowledge if not provided
@@ -360,6 +418,96 @@ export class AgentManager {
     };
   }
 
+  /**
+   * Spawn via caller-provided delegate.
+   * Handles knowledge injection, builds trajectory, notifies observers.
+   */
+  private async spawnViaDelegate(config: AgentSpawnConfig): Promise<AgentResult> {
+    const startTime = new Date();
+
+    // Query memory for relevant knowledge if not provided
+    let knowledge = config.injectedKnowledge;
+    if (!knowledge) {
+      knowledge = await this.memory.queryV2(config.task.description, {
+        domains: config.task.domain ? [config.task.domain] : undefined,
+      });
+    }
+
+    // Format knowledge for injection
+    const formattedKnowledge = this.injector.format(knowledge, 'delegate');
+
+    // Build system context from prompt additions + formatted knowledge
+    const systemContext = [
+      config.systemPromptAdditions,
+      formattedKnowledge
+        ? `\n## Atlas Knowledge\n${formattedKnowledge}`
+        : undefined,
+    ]
+      .filter(Boolean)
+      .join('\n\n') || undefined;
+
+    // Call the delegate
+    const result = await this.delegate!.execute(config.task.description, {
+      cwd: config.cwd ?? process.cwd(),
+      systemContext,
+      timeoutMs: config.timeout,
+    });
+
+    const endTime = new Date();
+
+    // Build trajectory — use delegate's if provided, otherwise build minimal
+    const trajectory = result.trajectory ?? createTrajectory({
+      task: config.task,
+      steps: [
+        createStep({
+          action: 'delegate_execution',
+          observation: result.output,
+        }),
+      ],
+      outcome: result.success
+        ? successOutcome(result.structured ?? result.output)
+        : failureOutcome(result.output),
+      agentId: 'delegate',
+      wallTimeSeconds: (endTime.getTime() - startTime.getTime()) / 1000,
+    });
+
+    // Build session for observer compatibility
+    const session: AgentSession = {
+      id: crypto.randomUUID(),
+      agentType: 'delegate',
+      task: config.task,
+      state: result.success ? 'completed' : 'failed',
+      messages: [
+        {
+          role: 'assistant',
+          content: result.output,
+          timestamp: endTime,
+        },
+      ],
+      toolCalls: [],
+      startTime,
+      endTime,
+      result: result.structured ?? result.output,
+      error: result.success ? undefined : result.output,
+      metadata: {},
+    };
+
+    // Notify observers
+    this.notifySessionStart(session);
+    this.notifySessionEnd(session, trajectory);
+
+    return {
+      session,
+      trajectory,
+      success: result.success,
+      metrics: {
+        totalTime: endTime.getTime() - startTime.getTime(),
+        toolCallCount: 0,
+        messageCount: 1,
+      },
+    };
+  }
+
   /**
    * Spawn an agent WITHOUT knowledge injection (for baseline/control)
    */
@@ -435,9 +583,14 @@ export class AgentManager {
     const session = this.activeSessions.get(sessionId);
     if (!session) return;
 
-    const backend = this.findBackend(session.agentType);
-    if (backend?.terminate) {
-      await backend.terminate(sessionId);
+    // Resolve backend for this agent type (best-effort, ignore errors)
+    try {
+      const target = await this.computeProvider.resolve(session.agentType);
+      if (target.backend.terminate) {
+        await target.backend.terminate(sessionId);
+      }
+    } catch {
+      // Backend may no longer be registered; still clean up session
     }
 
     this.activeSessions.delete(sessionId);
@@ -468,17 +621,6 @@ export class AgentManager {
 
   // Private helpers
 
-  private findBackend(agentType: string): AgentBackend | undefined {
-    // First try exact match
-    for (const backend of this.backends.values()) {
-      if (backend.supportedTypes.includes(agentType)) {
-        return backend;
-      }
-    }
-    // Then try by backend name
-    return this.backends.get(agentType);
-  }
-
   private async waitForCompletion(
     backend: AgentBackend,
     sessionId: string
@@ -535,6 +677,8 @@ export function createAgentManager(
   options?: {
     injector?: KnowledgeInjector;
     extractor?: TrajectoryExtractor;
+    computeProvider?: ComputeProvider;
+    delegate?: AgentDelegate;
   }
 ): AgentManager {
   return new AgentManager(memory, options);