agent-forge-sdk CLAUDE.md

@minns/agent-forge — Project Directive

Overview

TypeScript agent framework SDK. ESM-only, strict TypeScript, no default exports. Powered by minns-sdk (^0.7.2) as the optional memory layer. Ships an adaptive two-tier execution engine with reasoning engines, composable middleware, and a graph execution engine.

Architecture

src/
  index.ts              — Public API barrel export (all named exports)
  agent.ts              — AgentForge class (top-level API: run, stream, runWithEvents)
  types.ts              — All public type definitions
  errors.ts             — Error hierarchy (AgentForgeError, LLMError, ToolExecutionError, MemoryError, PipelinePhaseError)

  directive/
    directive.ts        — resolveDirective() merges defaults
    templates.ts        — buildAgentPrompt, buildPlanPrompt, buildNextActionPrompt, buildIntentParsePrompt

  llm/
    provider.ts         — LLMProvider interface
    openai-provider.ts  — OpenAI-compatible provider (fetch-based)
    anthropic-provider.ts — Anthropic native provider (lazy-loads @anthropic-ai/sdk)
    vcr.ts              — VCRProvider: record/replay wrapper for hermetic tests + eval oracle (InMemoryCassette, JSON persistence)
    types.ts            — LLM-specific types

  tasks/
    task.ts             — Task lifecycle: TaskStatus/TaskType, isTerminalTaskStatus guard, canTransition, generateTaskId (type-prefixed crypto ids), TaskTable (guarded mutations)

  coordinator/
    coordinator.ts      — Coordinator: fan-out/fan-in multi-agent (read-concurrent/write-serial, push-not-poll, self-contained workers, continue-vs-spawn, synthesize)

  memory/
    memory-manager.ts   — MemoryManager: searchClaims + query in parallel
    context-ranker.ts   — selectBestContext() ranks claims by confidence
    fact-extractor.ts   — extractFactsFromClaims (subject-predicate-object → key/value)

  session/
    session-store.ts    — SessionStore interface
    in-memory-store.ts  — InMemorySessionStore (LRU, default 10,000 entries)

  tools/
    tool.ts             — Capability layer: buildTool() (safe defaults), planToolBatches (concurrency), evaluatePolicy (allow/deny/ask), capResultSize
    tool-registry.ts    — ToolRegistry: register, disclose (loaded/deferred/search), authorize, safely execute tools (validate → authorize → execute → cap)
    builtin/
      search-memories.ts  — searchMemoriesTool (searchClaims + query)
      store-fact.ts       — storeFactTool (sendMessage)
      report-failure.ts   — reportFailureTool (sendMessage)

  pipeline/
    adaptive-runner.ts          — AdaptiveRunner: two-tier execution engine (agentic loop + graph pipeline)
    runner.ts                   — PipelineRunner (legacy, deprecated — use AdaptiveRunner)
    phases/
      intent-phase.ts           — LLM intent classification (used by legacy runner)
      semantic-write-phase.ts   — sendMessage for graph ingestion
      memory-retrieval-phase.ts — searchClaims + query in parallel
      plan-phase.ts             — LLM plan generation
      auto-store-phase.ts       — Auto-store facts for inform intents
      action-loop-phase.ts      — Flat tool loop or MCTS tree search
      reasoning-phase.ts        — Store reasoning steps (no-op, kept for compat)
      goal-check-phase.ts       — Run goalChecker, handle completion
      response-phase.ts         — LLM response generation
      finalize-phase.ts         — Store assistant message, update history

  reasoning/
    types.ts            — TreeNode, ComplexityAssessment, ReflexionConstraint, CritiqueResult, etc.
    meta-reasoner.ts    — MetaReasoner: classifies complexity, decides phase skipping
    reflexion.ts        — ReflexionEngine: extracts constraints from claims
    tree-search.ts      — TreeSearchEngine: MCTS (PUCT selection + value backpropagation)
    self-critique.ts    — SelfCritique: validates responses, rewrites if rejected
    world-model.ts      — WorldModel: simulates action outcomes, predicts risk

  subagent/
    sub-agent.ts        — SubAgentRunner: spawn + execute child agents
    types.ts            — SubAgentDefinition, SubAgentResult, SubAgentTask

  events/
    emitter.ts          — AgentEventEmitter: typed events, callback + async iterable

  runtime/              — minns control-plane contract (deploy-time bridge)
    contract.ts         — InvokeRequest/InvokeResponse wire types + AGENT_ID_RESOURCE_ATTR
    env.ts              — readMinnsEnv(): MINNS_TELEMETRY_URL/LOGS_URL/APPROVAL_URL/TOKEN/AGENT_ID
    otlp.ts             — TelemetryReporter: OTLP/JSON GenAI span exporter (light "observed" tier)
    logs.ts             — LogShipper: batched log shipping to MINNS_LOGS_URL
    approval.ts         — createHttpApprovalHandler: HITL → control-plane approval queue
    durable.ts          — createGraphStepHandler: maps invoke/checkpoint/interrupt → step contract
    serve.ts            — serveAgent(): HTTP harness exposing /v1/invoke + /healthz
                          (+ /v1/execute-candidate when onExecuteCandidate is supplied)
    prompt.ts           — fetchAgentPrompt / PromptProvider: the opto-optimised prompt, served back
    trace-attrs.ts      — span vocabulary (gen_ai.* / minns.* keys, span names) opto and the control plane read
    traced-provider.ts  — tracedProvider(): one llm.call span per provider call (messages, tools, output, tokens)

  utils/
    run-context.ts      — AsyncLocalStorage run identity (rollout id, per-run tool onion, counters)
    timer.ts            — PipelineTimer: phase timing
    json.ts             — safeJsonParse, canonicalizeJson
    fingerprint.ts      — computeContextFingerprint