![\"Burtson](\"https://cdn.burtson.ai/logos/burtson-labs-logo.png\"){kind=logo}
\n \n ![](\"https://icons.burtson.ai/svg-accent/download.svg\"){kind=icon}
Install\n\n```bash\npnpm add @burtson-labs/agent-core\n```\n\n## ![](\"https://icons.burtson.ai/svg-accent/zap.svg\"){kind=icon}
Quick start\n\n`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:\n\n```ts\nimport { createAgentRuntime } from \"@burtson-labs/agent-core\";\n\nconst runtime = createAgentRuntime({\n providerClient, // satisfies ProviderClient\n systemPrompt: \"You are a helpful coding agent.\",\n tools: [/* built-ins + your own */]\n});\n\nconst plan = await runtime.plan(\"Summarize this repo\");\nconst result = await runtime.execute();\nconst report = await runtime.report();\n```\n\nThe host wires up streaming + auth on the provider; the loop owns iteration, retry/fallback, compaction, output-budget serialization, and the detector contract.\n\n### Typical pairings\n\n| You need | Add |\n|---|---|\n| LLM provider (Ollama / OpenAI / cloud) | [`@burtson-labs/agent-adapters-provider`](https://www.npmjs.com/package/@burtson-labs/agent-adapters-provider) |\n| Run on Node (shell + filesystem) | [`@burtson-labs/agent-adapters-node`](https://www.npmjs.com/package/@burtson-labs/agent-adapters-node) |\n| Run in the browser | [`@burtson-labs/agent-adapters-web`](https://www.npmjs.com/package/@burtson-labs/agent-adapters-web) |\n| Run inside a VS Code extension | [`@burtson-labs/agent-adapters-vscode`](https://www.npmjs.com/package/@burtson-labs/agent-adapters-vscode) |\n| Run from a GitHub Action | [`@burtson-labs/agent-adapters-github`](https://www.npmjs.com/package/@burtson-labs/agent-adapters-github) |\n| Memory / hooks / `@`-mentions / extra tools | [`@burtson-labs/host-kit`](https://www.npmjs.com/package/@burtson-labs/host-kit) |\n| Pre-built runtime (CLI + extension parity) | [`@burtson-labs/stealth-core-runtime`](https://www.npmjs.com/package/@burtson-labs/stealth-core-runtime) |\n| React UI for plan / chat / diff / telemetry | [`@burtson-labs/agent-ui`](https://www.npmjs.com/package/@burtson-labs/agent-ui) |\n\n## ![](\"https://icons.burtson.ai/svg-accent/blocks.svg\"){kind=icon}
What's inside\n\n| Path | Purpose |\n|---|---|\n| `src/tools/tool-use-loop.ts` | The loop itself. Orchestrates LLM call → response parsing → detector pass → tool execution → repeat. |\n| `src/tools/tool-use-parser.ts` | Extracts `![](\"https://icons.burtson.ai/svg-accent/beaker.svg\"){kind=icon}
Running tests\n\n```bash\npnpm --filter @burtson-labs/agent-core test\n```\n\nThe 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):\n\n| Concern | File |\n|---|---|\n| Constructor options merged into runtime | [test/constructorOptionsContract.test.ts](test/constructorOptionsContract.test.ts) |\n| \"Claim without doing\" detectors (false-completion, partial-completion, announce-then-stall) | [test/claimWithoutDoingDetectors.test.ts](test/claimWithoutDoingDetectors.test.ts) |\n| \"Structured output instead of tool\" detectors (code-fence, JSON-todo auto-promote) | [test/structuredOutputDetectors.test.ts](test/structuredOutputDetectors.test.ts) |\n| Loop detectors (prose-loop, todo-churn) | [test/loopDetectors.test.ts](test/loopDetectors.test.ts) |\n| Malformed/empty recovery (empty-retry, thinking-off-recovery, parse-retry) | [test/malformedEmptyDetectors.test.ts](test/malformedEmptyDetectors.test.ts) |\n| Hallucinated `![](\"https://icons.burtson.ai/svg-accent/book-open.svg\"){kind=icon}
Conventions\n\n- **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.\n- **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](test/constructorOptionsContract.test.ts) (the file's exhaustiveness check fails build if you forget).\n- **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.\n\n## ![](\"https://icons.burtson.ai/svg-accent/network.svg\"){kind=icon}
Position in the framework\n\n```\n[host: VS Code extension or CLI]\n │\n ▼\n ┌──────────────┐\n │ ToolUseLoop │ ← this package\n └──────┬───────┘\n │\n ┌─────┴─────┐\n ▼ ▼\n [tool registry] [chat function]\n │ │\n ▼ ▼\n [host-kit tools] [Ollama / Bandit cloud / etc.]\n```\n\nThe 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.\n\n## License\n\n[Apache License 2.0](../../LICENSE) — Copyright 2026 Burtson Labs.\n","readmeFilename":"README.md"}