@burtson-labs/agent-core

Core reasoning and planning engine for the Bandit Agent Framework.

Owns the ToolUseLoop — the iteration controller that drives every Bandit agent run, parent or subagent, in both the VS Code extension and the CLI host.

Install

pnpm add @burtson-labs/agent-core

Quick start

agent-core is provider-agnostic — pair it with a provider client (@burtson-labs/agent-adapters-provider wraps Ollama, OpenAI-compatible endpoints, and the hosted Bandit gateway) and a host-side tool set (@burtson-labs/host-kit ships the extras the CLI and extension use). The minimal shape:

import { createAgentRuntime } from "@burtson-labs/agent-core";

const runtime = createAgentRuntime({
  providerClient,                    // satisfies ProviderClient
  systemPrompt: "You are a helpful coding agent.",
  tools: [/* built-ins + your own */]
});

const plan = await runtime.plan("Summarize this repo");
const result = await runtime.execute();
const report = await runtime.report();

The host wires up streaming + auth on the provider; the loop owns iteration, retry/fallback, compaction, output-budget serialization, and the detector contract.

Typical pairings

What's inside

Running tests

pnpm --filter @burtson-labs/agent-core test

The suite is split across synthetic contract tests (one file per detector cluster) and real-trace replay tests (turn logs from .bandit/turns/ replayed through a fresh loop):

Adding a regression fixture from a real failure trace

When you see a weird agent behavior in a real run, drop the turn-log fixture into the test suite so a future loop change can't silently regress it. See test/fixtures/turns/README.md for the full guide — replay-completeness limits, naming conventions, what to assert, and a copy-paste test template.

Conventions

• Every detector is one-shot per turn. Each tool_loop:*_nudge event fires at most once before the loop terminates or the model recovers. Adding a new detector means adding the gate flag + a contract test.
• Constructor options must flow through to runtime. ToolUseLoopOptions set at construction time apply to every runWithMessages call. The merge happens in runWithMessages — see effectiveOptions = { ...defaultOptions, ...perCall }. New options need a corresponding entry in test/constructorOptionsContract.test.ts (the file's exhaustiveness check fails build if you forget).
• Helpers go in test/_helpers.ts; the replay harness in test/_replay.ts. Both file names start with _ so they're excluded from vitest's test/**/*.test.ts glob.

Position in the framework

[host: VS Code extension or CLI]
              │
              ▼
       ┌──────────────┐
       │ ToolUseLoop  │  ← this package
       └──────┬───────┘
              │
        ┌─────┴─────┐
        ▼           ▼
 [tool registry]   [chat function]
        │              │
        ▼              ▼
  [host-kit tools]   [Ollama / Bandit cloud / etc.]

The loop is host-agnostic. Hosts wire up the chat function (with their own watchdogs / streaming / auth) and supply a tool registry; the loop owns iteration, retry/fallback policy, compaction, output-budget serialization, and the detector contract.

License

Apache License 2.0 — Copyright 2026 Burtson Labs.