agent-forge-sdk: Instructions file for Claude Code

@minns/agent-forge — Project Directive

Overview

TypeScript agent framework SDK. ESM-only, strict TypeScript, no default exports. Powered by minns-sdk (^0.8.6) 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)
    turn-safety.ts      : judgeTurn: a turn ending in refusal or max_tokens never runs its (possibly partial) tool
                          calls, and a refusal is never reported as success. Both native loops consult it first
    resilience.ts       : retries. A provider with no `resilience` config retries 429, 529 and 5xx up to 3 times and
                          honours Retry-After (DEFAULT_PROVIDER_RETRY); `false` turns it off
    model-caps.ts       : which models accept temperature/top_p/top_k. Claude defaults to NO: only the older
                          models listed there accept them, so a new release omits them instead of 400ing
    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)
    simple-client.ts    : MinnsSimpleClient for a memory store (minns-simple: scoped, time-aware facts; each store
                          the customer's own). Sends the store's secret + the agent's token. Filters: omitted =
                          all, value or list = any of, null = untagged, metadata operators as mem0

  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)
    result-store.ts     : large answers. Once run_code is attached (enableResultHandles), an answer over the model's
                          budget (24 KB) is kept whole per run under a handle and the model gets previewOf (same
                          shape, lists cut first, valid JSON) plus the handle; a program's own calls (fromProgram)
                          get the whole answer up to 8 MB, and tools.read_result({ ref }) reads a kept one. Bounded:
                          16 per run, 64 MB, an hour
    sandbox/
      protocol.ts       — SandboxBackend: where a shell command runs (exec → stdout/stderr/exit/timedOut)
      local-sandbox.ts  — LocalSandbox: /bin/sh inside one directory, own process group, time + output caps, no host secrets
      http-sandbox.ts   — HttpSandbox: a remote workspace as BOTH halves the agent needs (SandboxBackend + BackendProtocol)
                          over one base URL and token; streams /exec output, POSTs /fs/* for files
    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

  middleware/
    backend/search.ts   : what every backend's grep and glob share: regex with a literal fallback, ignore case,
                          node_modules and .git skipped unless searched from inside, binary files skipped, a match
                          cap, newest-first ordering
    builtin/
      filesystem.ts     — FilesystemMiddleware: ls/glob/grep/read_file/write_file/edit_file over a BackendProtocol;
                          read-before-edit via tools/safe-edit, large tool results offloaded to /.agent/results
      shell.ts          — ShellMiddleware: `execute` over a SandboxBackend; shell-safety verdicts, destructive → ask,
                          exit codes via command-semantics
      workspace.ts      — createWorkspace(): FilesystemMiddleware + ShellMiddleware over ONE HttpSandbox, from the
                          MINNS_SANDBOX_URL/TOKEN rails by default (readWorkspaceEnv in runtime/env.ts); null without a box.
                          A host that registers (and wraps) the tools itself passes `behaviour` (withoutTools) to
                          AgentForge: the prompt, the result offload and the per-run reads, without the tools twice
      simple-memory.ts  : SimpleMemoryMiddleware: recalls the run's memories into the prompt (inside <minns-memories>,
                          which minns-simple leaves out when it extracts), remember/recall/forget tools in the run's
                          scope, and in auto mode sends each finished exchange for background extraction. Every
                          fact carries the host's metadataFor (where it was learned: the run or conversation)
      code-mode.ts      — CodeModeMiddleware: programmatic tool calling. `run_code` runs a JavaScript program in a
                          QuickJS sandbox (no host access) where tools.<name>(args) calls a disclosed tool through
                          ToolRegistry.execute (validate/authorize/approval/cap all apply); synchronous from the
                          script's side (asyncify), await/async stripped; deadline, memory cap, call budget, output
                          cap; one runtime per middleware, a context per script (freeing a runtime that holds
                          asyncified host refs crashes). quickjs-emscripten is an optional peer, loaded on first use
      (todo-list, skills, subagents, summarization, eviction, HITL, prompt-cache, telemetry, minns-power, ...)

  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;
                          readWorkspaceEnv(): MINNS_SANDBOX_URL/TOKEN
    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). A caller that
                          accepts application/x-ndjson gets {"type":"delta"} lines as the reply is written,
                          then one {"type":"result"}; a caller hanging up aborts the run (StepContext.signal),
                          except a keyed one (idempotency_key): a retry of it gets the same turn, in flight or finished
    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)
    sandbox-contract.ts — the remote-workspace wire contract: /healthz, /exec (NDJSON stream of ExecEvent), /fs/*
    sandbox-server.ts   — serveSandbox(): LocalSandbox + FilesystemBackend over one root behind HTTP; bearer in
                          constant time, one command at a time (bounded queue), kill on client disconnect, body cap

  scan/                 — scan-to-register. scanner.ts (pure): OpenAPI JSON, Express/Hono/Fastify and
    scanner.ts            FastAPI/Flask route literals, package.json scripts, Makefile targets -> ToolCandidate[]
    codegen.ts            (name, schema, where from), deduplicated. codegen.ts: a candidate -> the raw body the
                          control plane's tool factory runs (`async (input, secrets)`): an HTTP tool calls
                          BASE_URL (+ API_KEY) with that host as its only egress; a script tool runs the command
                          in the owner's workspace through the gateway with the box's credential as secrets.
                          `minns tools scan [dir] --register` drives it.

  cli/                  — the `minns` command (package bin). Everything it does is a bearer request to the
    config.ts             control plane's /control routes with a personal API token (mpt_..., Account > API
    client.ts             tokens). config: ~/.minns/config.json, owner-only, MINNS_TOKEN/MINNS_URL override.
    commands.ts           client: JSON + SSE (`data:` frames). commands: login/logout/whoami, agents, apps,
    main.ts               workspaces, tools list/scan, tokens list, usage; pure parseArgs; run(argv, io) returns an exit code
                          (0 ok, 1 not passed, 2 error, 3 not signed in) so tests drive it without a process

  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