anchor-ai-sdk 0.0.1 → 0.1.0

package/README.md

@@ -1,53 +1,71 @@
-# Anchor
-
-**Loop-first, sandbox-first agent framework.** An agent engine you can
-actually inspect: it composes its prompt, calls any OpenAI-compatible model,
-executes tools inside an isolated sandbox, journals every event, folds its own
-context, and stops honestly — a final response ends the turn, and nothing
-pretends a test passed.
-
-> **0.0.1 — early alpha.** This is a real, working build (engine, tools, LLM
-> client, three sandbox adapters, 193 tests), published to claim the name and
-> start the version history. The API will move before 1.0 — pin exact
-> versions. Repo: [github.com/hrithikkoduri/anchor-ai-sdk](https://github.com/hrithikkoduri/anchor-ai-sdk).
-> Docs: [anchor-sdk.dev](https://anchor-sdk.dev) (coming).
-
-## What's in the box
-
-- **The engine** (`runAgent`): budgets, guardrails on by default, compaction
-  derived from the model's real context window, trace sinks with one sequence
-  number, revival handoffs, and configurable run snapshots.
-- **A tool protocol** — `bash`, `read_file`, `edit_file`, `search`,
-  `run_tests` — with structured results. Test evidence is tied to the exact
-  tree it ran against (`run_tests` records the tree hash); "green" only counts
-  if the tree still matches.
-- **A provider-agnostic LLM client**: streaming by default, priced and
-  windowed from the provider catalog (`llmFromCatalog`).
-- **Sandbox providers behind one contract**, accepted by an executable
-  conformance suite (exec fidelity, kill deadlines, checkpoints,
-  retain/adopt, git identity, pushes).
-- **Durable memory**: `ThreadStore` for conversation, git-backed checkpoints
-  for the workspace, and a reserved notes file (`.anchor/notes.md`) that
-  rides checkpoints — the agent's own durable record across folds and
-  restarts.
-
-## Quickstart
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/hrithikkoduri/anchor-ai-sdk/main/assets/logo-dark.svg" />
+    <img src="https://raw.githubusercontent.com/hrithikkoduri/anchor-ai-sdk/main/assets/logo.svg" alt="Anchor" width="96" />
+  </picture>
+</p>
+
+<h1 align="center">Anchor</h1>
+
+<p align="center">
+  <strong>Loop-first, sandbox-first agent harness SDK.</strong><br />
+  Give it a task and a machine — it reasons, runs tools, checks its own work, and keeps the receipts.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/anchor-ai-sdk"><img src="https://img.shields.io/npm/v/anchor-ai-sdk?style=flat-square&color=0f1115" alt="npm" /></a>
+  <a href="https://github.com/hrithikkoduri/anchor-ai-sdk/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/hrithikkoduri/anchor-ai-sdk/ci.yml?style=flat-square&label=ci&color=0f1115" alt="CI" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/anchor-ai-sdk?style=flat-square&color=0f1115" alt="license" /></a>
+  <img src="https://img.shields.io/node/v/anchor-ai-sdk?style=flat-square&color=0f1115" alt="node" />
+</p>
+
+---
+
+Most agent harnesses give you a loop and leave the hard parts to you: a
+context that grows until it dies, a trace you can't replay, a "done" you can't
+trust. Anchor ships the hard parts.
+
+- **Evidence, never vibes.** Every tool result is recorded on
+  `AgentResult.evidence`; `run_tests` stamps the tree hash it ran against and
+  `latestEvidenceForTree` ties a green run to the *exact* bytes (fail-closed
+  when the tree can't be inspected). The engine carries evidence and never
+  reads success out of a confident sentence — what to gate on it is your
+  policy, not a hidden wall.
+- **Durable by construction.** Conversation, workspace, and the agent's own
+  notes survive folds, restarts, and budget deaths; the SDK ships the
+  resumption primitives (thread store, checkpoints, phase pauses, revival
+  planning), so resuming is wiring, not research.
+- **Sandbox-first.** The machine is part of the design, not an afterthought:
+  one provider contract, adapters accepted by an executable conformance
+  suite.
+
+## Out of the box
+
+| | |
+| --- | --- |
+| **Agent loop with dials** | Budgets (steps / tokens / USD), repeated-call detection, silent-tool advisories — guardrails on by default, each with an off switch. Phases describe the approach — never a second gated execution engine. |
+| **Streaming by default** | One wire path: every model call streams. Text and reasoning deltas, tool calls, compaction, checkpoints, and finishes all arrive as typed events. |
+| **Durable memory** | `ThreadStore` carries conversation across runs; compaction is derived from the model's *real* context window; reasoning is journaled but never re-sent. |
+| **Notes & spill storage** | A reserved `.anchor/notes.md` (git-excluded, checkpoint-carried) is the agent's durable memory across folds; oversized tool output spills to sandbox files and stays addressable instead of vanishing. |
+| **Revival** | A dying run leaves a handoff (`request_revival`); `planRevival` + `ThreadBudget` decide how to fund the next run — **same task, phase, and budget** — and when the thread's caps are spent, a human gets the note, quoting the agent's own words on what remains. |
+| **Snapshots & resume** | A pluggable snapshot hook (git-backed by default, push optional), phase-boundary pauses, heartbeats and cross-process cancel polling owned by the engine. |
+| **Traces you can replay** | One fanout: one sequence number, redaction applied before *every* sink — NDJSON file, database rows, and a live projector share the same ordering. |
+| **Sandbox plugins** | One `SandboxProvider` contract: Heyo microVMs, Docker, local. Capabilities are promises — the conformance suite holds adapters to them. Store-backed sessions give adopt-and-fallback continuity for free. |
+| **Typed handoffs** | `finish({ handoff })` is shaped by *your* JSON schema; the engine declares the parameter, carries the object, and never interprets it. |
+| **Priced & windowed models** | `llmFromCatalog` reads live prices and the genuine context window from the provider catalog — budgets and compaction configure themselves correctly. |
+
+## Ten lines to a working agent
 
 ```bash
 npm install anchor-ai-sdk
 ```
 
 ```ts
-import {
-  chatAgent,
-  createLLMClient,
-  llmFromCatalog,
-  runAgent,
-} from "anchor-ai-sdk";
+import { chatAgent, llmFromCatalog, runAgent } from "anchor-ai-sdk";
 
 const { llm } = await llmFromCatalog({
   baseUrl: "https://openrouter.ai/api/v1",
-  apiKey: process.env.OPENROUTER_KEY,
+  apiKey: process.env.OPENROUTER_KEY!,
   model: "z-ai/glm-5.3",
 });
 
@@ -58,14 +76,13 @@ const result = await runAgent(
 console.log(result.summary);
 ```
 
-With a sandbox — Docker shown; the `local` backend needs no daemon:
+## Give it a machine
 
 ```ts
-import { codingAgent, createLLMClient, runAgent } from "anchor-ai-sdk";
+import { codingAgent, runAgent } from "anchor-ai-sdk";
 import { docker } from "anchor-ai-sdk/sandbox/docker";
 
-const provider = docker();
-const sandbox = provider.create({
+const sandbox = docker().create({
   repoUrl: "https://github.com/you/your-repo",
   ref: "main",
 });
@@ -73,15 +90,9 @@ await sandbox.start();
 try {
   const result = await runAgent(
     { task: "Run the tests and fix the failing case" },
-    {
-      llm: createLLMClient({
-        /* … */
-      }),
-      agent: codingAgent,
-      sandbox,
-    },
+    { llm, agent: codingAgent, sandbox },
   );
-  console.log(result.summary);
+  console.log(result.summary, result.checkpointRef);
 } finally {
   await sandbox.destroy();
 }
@@ -89,28 +100,38 @@ try {
 
 ## Providers
 
-| subpath                        | backend                           | status                                    |
-| ------------------------------ | --------------------------------- | ----------------------------------------- |
-| `anchor-ai-sdk/sandbox/heyo`   | Heyo Cloud microVMs (Firecracker) | production path; conformance + live tests |
-| `anchor-ai-sdk/sandbox/docker` | containers on the local daemon    | conformance-tested                        |
-| `anchor-ai-sdk/sandbox/local`  | this host, **no isolation**       | dev / CI only                             |
-| —                              | E2B, Daytona                      | planned — not exported yet                |
+| subpath | backend | status |
+| --- | --- | --- |
+| `anchor-ai-sdk/sandbox/heyo` | Heyo Cloud microVMs (Firecracker) | production path; conformance + live tests |
+| `anchor-ai-sdk/sandbox/docker` | containers on the local daemon | conformance-tested in CI |
+| `anchor-ai-sdk/sandbox/local` | this host, **no isolation** | dev / CI only |
+| — | E2B, Daytona | planned |
 
 A backend is "done" when `runSandboxConformance(provider)` from
-`anchor-ai-sdk/testing` passes. The suite gates scenarios on declared
-capabilities; capabilities are promises, not vibes.
-
-## The philosophy, short
-
-Trust the reasoning; verify the claims. The engine carries _evidence_ instead
-of asserting success: a passing test run is a structured event tied to the
-exact tree; publication is an explicit tool call gated on that evidence; a
-worker death resumes from a checkpoint instead of re-deriving or pretending.
-The same discipline is being measured: Anchor vs mini-swe-agent on SWE-bench
-Lite, same container, same model, same grader — equal resolution at roughly
-one-third the cost. The comparison table ships with the first tagged release.
-
-## Status & links
+`anchor-ai-sdk/testing` passes — exec fidelity, kill deadlines, env secrets,
+checkpoints, retain/adopt, git identity, pushes, and `fork` where declared.
+See [`src/sandbox/README.md`](src/sandbox/README.md) for the provider guide.
+
+## Proof, not promises
+
+- **Tests:** the engine, tools, trace layer, and every provider scenario run
+  in CI — local conformance always, Docker conformance on a purpose-built
+  image. Live microVM conformance is opt-in with your own Heyo credentials
+  (the suite skips without them).
+- **Genericity guards:** executable rules keep the package consumer-neutral —
+  no product nouns, no env reads, SDKs behind subpaths. They run in the same
+  suite as everything else.
+- **Evaluation:** Anchor vs mini-swe-agent on SWE-bench Lite — same
+  container, same model, same official grader — resolved the same 7/10 at
+  roughly **one-third of the cost**
+  ([`evals/results/comparison.md`](evals/results/comparison.md)).
+
+## Status
+
+**Early alpha (0.x).** The API will move before 1.0 — pin exact versions. The
+[`DECISIONS.md`](DECISIONS.md) is the engineering log: every API has a written
+reason, and the reasons moved with the code when this repo was extracted from
+its monorepo.
 
 - Repo / issues: [github.com/hrithikkoduri/anchor-ai-sdk](https://github.com/hrithikkoduri/anchor-ai-sdk)
 - Docs: [anchor-sdk.dev](https://anchor-sdk.dev) (coming)

package/dist/agents/coding/index.d.ts

@@ -7,7 +7,7 @@ export { codingPhases } from "./phases.js";
 /**
  * The coding agent — strategy + toolbox. Pass `testCommand` when the repo's
  * canonical suite is known (CLI or repo config); otherwise run_tests detects
- * one and the evidence gates still apply.
+ * one; either way run_tests tags the run as the repo's full-suite evidence.
  */
 export declare function createCodingAgent(opts?: {
     testCommand?: string;

package/dist/agents/coding/index.js

@@ -7,7 +7,7 @@ export { codingPhases } from "./phases.js";
 /**
  * The coding agent — strategy + toolbox. Pass `testCommand` when the repo's
  * canonical suite is known (CLI or repo config); otherwise run_tests detects
- * one and the evidence gates still apply.
+ * one; either way run_tests tags the run as the repo's full-suite evidence.
  */
 export function createCodingAgent(opts = {}) {
     return {

package/dist/agents/coding/tools.d.ts

@@ -12,8 +12,7 @@ import type { Tool } from "../../tools/types.js";
 /**
  * The toolbox for one coding agent. `testCommand` — when the repo's canonical
  * suite is known from config/CLI — becomes run_tests' fallback and counts as
- * full-suite evidence (the strategy's evidence gates care about that
- * distinction).
+ * full-suite evidence (publication policies gate on that distinction).
  */
 export declare function createCodingTools(opts?: {
     testCommand?: string;

package/dist/agents/coding/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/agents/coding/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAOjD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,IAAI,EAAE,CAQ7E;AAED,wEAAwE;AACxE,eAAO,MAAM,WAAW,EAAE,IAAI,EAAwB,CAAC"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/agents/coding/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAOjD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,IAAI,EAAE,CAQ7E;AAED,wEAAwE;AACxE,eAAO,MAAM,WAAW,EAAE,IAAI,EAAwB,CAAC"}

package/dist/agents/coding/tools.js

@@ -6,8 +6,7 @@ import { searchTool } from "../../tools/search.js";
 /**
  * The toolbox for one coding agent. `testCommand` — when the repo's canonical
  * suite is known from config/CLI — becomes run_tests' fallback and counts as
- * full-suite evidence (the strategy's evidence gates care about that
- * distinction).
+ * full-suite evidence (publication policies gate on that distinction).
  */
 export function createCodingTools(opts = {}) {
     return [

package/dist/agents/coding/tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/agents/coding/tools.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAI,GAA6B,EAAE;IACnE,OAAO;QACL,QAAQ;QACR,YAAY;QACZ,YAAY;QACZ,UAAU;QACV,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3E,CAAC;AACJ,CAAC;AAED,wEAAwE;AACxE,MAAM,CAAC,MAAM,WAAW,GAAW,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/agents/coding/tools.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAI,GAA6B,EAAE;IACnE,OAAO;QACL,QAAQ;QACR,YAAY;QACZ,YAAY;QACZ,UAAU;QACV,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3E,CAAC;AACJ,CAAC;AAED,wEAAwE;AACxE,MAAM,CAAC,MAAM,WAAW,GAAW,iBAAiB,EAAE,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "anchor-ai-sdk",
-  "version": "0.0.1",
-  "description": "Loop-first, sandbox-first agent framework: engine, tools, LLM client, sandbox adapters.",
+  "version": "0.1.0",
+  "description": "Loop-first, sandbox-first agent harness SDK: engine, tools, LLM client, sandbox adapters.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -52,7 +52,8 @@
     "prepack": "npm run build",
     "prepublishOnly": "npm run build && node scripts/verify-dist-exports.mjs",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "prepare": "npm run build"
   },
   "peerDependencies": {
     "@heyocomputer/hws": ">=0.4",