feat(builder): open-source BitBadgesAgent — BYO Anthropic key

[trevormil]

Summary

• Adds BitBadgesAgent class at bitbadges/builder/agent so anyone can build BitBadges collections from a natural-language prompt using their own Anthropic API key. BitBadges never sees user keys.
• Three-tier consumption: /builder/agent (stable class), /builder/internals (unstable primitives for DIY loops / fine-tuning), existing MCP stdio bin unchanged.
• @anthropic-ai/sdk is an optional peerDependency — MCP/CLI consumers unaffected.
• Ports prompt assembly, agent loop, validation gate + fix loop from the indexer into the SDK. Prompt behavior byte-identical.

Key features

• Zero-config: new BitBadgesAgent({ anthropicKey }).build('create a subscription for $10/mo')
• Auth: API key, OAuth token, or pre-built Anthropic client. Auto-reads ANTHROPIC_API_KEY / ANTHROPIC_OAUTH_TOKEN / ANTHROPIC_AUTH_TOKEN from env.
• BitBadges API passthrough: bitbadgesApiKey option threads through every query tool (or auto-reads BITBADGES_API_KEY).
• Customization: model picker (haiku/sonnet/opus), validation: 'strict'|'lenient'|'off', skills filter, systemPromptAppend, tools.add/tools.remove, hooks (onTokenUsage, onToolCall, onStatusUpdate, onCompletion).
• Pluggable session store: MemoryStore + FileStore ship; consumers can BYO (the indexer will add a Redis adapter in the follow-up PR).
• QoL: typed errors (ValidationFailedError, QuotaExceededError, AnthropicAuthError, AbortedError, PeerDependencyError, SimulationError), parsed tool output, result.costUsd, result.toString(), agent.abort(), agent.healthCheck(), agent.validate(), substituteImages helper, debug mode.

Files

• src/builder/agent/ — 11 new modules.
• examples/builder-agent/ — zero-config, middle-tier, DIY internals scripts + README.
• package.json — exports map additions for ./builder/agent + ./builder/internals; peerDep.
• README.md — "three ways to build" section replacing the prior MCP-only block.
• src/builder/agent/BitBadgesAgent.spec.ts — 17 unit tests (all passing) covering zero-config, OAuth, env vars, tool filtering, image substitution, hooks, typed errors, end-to-end with mocked Anthropic.

Backwards compat

• No existing exports or bins are removed.
• Existing bitbadges/builder/* subpaths (registry, tools, resources, skills, session) unchanged.
• bitbadges-builder MCP stdio bin unchanged.

Follow-ups (separate PRs)

• Indexer PR (feat/consume-bitbadges-agent on bitbadges-indexer) consumes the agent via bun link, adds RedisSessionStore, shrinks aiBuildHandler.
• Frontend PR (feat/bitbadges-agent-ui) exposes the new customization knobs in AiGenerateWidget and embeds a one-liner in the landing-page AI agent card.
• Docs PR (feat/bitbadges-agent-docs) adds a gitbook page for the programmatic agent.

Backlog ticket: #0298.

Test plan

• npx jest src/builder/agent/BitBadgesAgent.spec.ts — 17/17 pass
• npx tsc --build tsconfig.build.json — clean (CJS)
• npx tsc --build tsconfig-esm.build.json — clean (ESM)
• Manual: run zero-config.ts with real ANTHROPIC_API_KEY against testnet before merge
• Manual: confirm existing MCP bin still boots (bitbadges-builder --help)

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR open-sources BitBadgesAgent — a self-contained, BYO-key AI agent that builds BitBadges collections from natural-language prompts. It ports the agent loop, prompt assembly, validation gate, and fix loop from the private indexer into the SDK, adds MemoryStore/FileStore session backends, a typed error hierarchy, image-placeholder helpers, and a full example suite. The agent is correctly gated behind an optional peerDependency on @anthropic-ai/sdk so existing MCP/CLI consumers are unaffected.

Key findings:

• P1 — loadAnthropicSdk swallows version errors (anthropicClient.ts:59): The outer catch block catches the PeerDependencyError thrown by assertSupportedVersion and replaces it with a generic "not installed" message. A consumer with an out-of-range SDK version will never see the helpful version-mismatch guidance.
• P2 — Misleading JSDoc on substituteImages (images.ts:17): The doc says "Only string fields named image are rewritten" but the implementation replaces IMAGE_N tokens in all string values throughout the transaction object.
• P2 — AnthropicAuthError hardcodes "ANTHROPIC_API_KEY" (errors.ts:63): The error message always directs users to check ANTHROPIC_API_KEY, even when the failure came from an OAuth token.
• All three previously flagged concerns (double handleGetTransaction call, shared abortController field, unenforced version range) are fully resolved in this revision.
• The 17-test suite covers the happy path, mocked end-to-end, typed errors, and environment-variable credential reading. The FileStore path sanitization correctly replaces path-separator characters, so no traversal risk is present.

Confidence Score: 4/5

Safe to merge after the one-line fix in anthropicClient.ts to re-throw PeerDependencyError before the generic catch.

The PR is architecturally sound and all three previously flagged issues are resolved. The P1 bug (version-check error swallowed) is a straightforward one-line fix and only affects the error message quality, not runtime correctness. The P2 items are documentation/UX polish. The agent loop, validation gate, session stores, tool adapter, and test suite are all in good shape.

packages/bitbadgesjs-sdk/src/builder/agent/anthropicClient.ts — the catch block on line 59 needs to re-throw PeerDependencyError before falling through to the generic handler.

Important Files Changed

Filename	Overview
packages/bitbadgesjs-sdk/src/builder/agent/anthropicClient.ts	Dynamic peer-dep loader with version check; P1 bug — the catch block swallows PeerDependencyError from assertSupportedVersion and replaces it with a misleading "not installed" message.
packages/bitbadgesjs-sdk/src/builder/agent/BitBadgesAgent.ts	Main agent class — well-structured with per-build AbortController set, lazy client init, fix-loop, and session persistence; previously flagged issues (double tx call, shared controller) are resolved.
packages/bitbadgesjs-sdk/src/builder/agent/loop.ts	Agent conversation loop — retry logic, token accounting, tool-result compression, and fire-and-forget hooks look correct and well-documented.
packages/bitbadgesjs-sdk/src/builder/agent/validation.ts	Validation gate runs three checks (review, structural validation, simulation) in a clear sequence; error classification and advisory note handling look correct.
packages/bitbadgesjs-sdk/src/builder/agent/images.ts	IMAGE_N substitution recursively walks entire transaction; JSDoc incorrectly states only image-named fields are rewritten when all string values are checked.
packages/bitbadgesjs-sdk/src/builder/agent/errors.ts	Typed error hierarchy with correct prototype chain restoration; AnthropicAuthError message hardcodes API key hint even for OAuth failures.
packages/bitbadgesjs-sdk/src/builder/agent/sessionStore.ts	MemoryStore (TTL-aware Map) and FileStore (JSON files, TTL) — path sanitization replaces slashes so no traversal risk; clean interface.
packages/bitbadgesjs-sdk/src/builder/agent/BitBadgesAgent.spec.ts	17 unit tests covering zero-config, OAuth, env vars, tool filtering, image substitution, hooks, typed errors, and end-to-end with a mocked Anthropic client; good coverage.

Sequence Diagram

sequenceDiagram
    participant Caller
    participant BitBadgesAgent
    participant AnthropicClient
    participant AgentLoop
    participant ToolRegistry
    participant ValidationGate
    participant SessionStore

    Caller->>BitBadgesAgent: build(prompt, options)
    BitBadgesAgent->>AnthropicClient: getAnthropicClient() [lazy, once]
    BitBadgesAgent->>SessionStore: get(sessionId) [load prior messages]
    BitBadgesAgent->>BitBadgesAgent: assemblePromptParts()

    loop Agent Loop (maxRounds)
        BitBadgesAgent->>AgentLoop: runAgentLoop(params)
        AgentLoop->>AnthropicClient: messages.create() [with retry]
        AnthropicClient-->>AgentLoop: response
        AgentLoop->>AgentLoop: onTokenUsage hook [awaited]
        AgentLoop->>ToolRegistry: execute(toolName, args)
        ToolRegistry-->>AgentLoop: result string
        AgentLoop->>AgentLoop: compressOldToolResults()
    end

    AgentLoop-->>BitBadgesAgent: loopResult
    BitBadgesAgent->>BitBadgesAgent: handleGetTransaction(sessionId)

    opt validation !== off
        loop Fix Loop (fixLoopMaxRounds)
            BitBadgesAgent->>ValidationGate: runValidationGate(transaction)
            ValidationGate-->>BitBadgesAgent: gate result
            alt gate.valid === false
                BitBadgesAgent->>AgentLoop: runAgentLoop(fixPrompt)
                AgentLoop-->>BitBadgesAgent: loopResult
            end
        end
    end

    BitBadgesAgent->>SessionStore: set(sessionId, messages+tx)
    BitBadgesAgent->>BitBadgesAgent: onCompletion hook [fire-and-forget]
    BitBadgesAgent-->>Caller: BuildResult

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: packages/bitbadgesjs-sdk/src/builder/agent/anthropicClient.ts
Line: 59-64

Comment:
**Version-check error silently replaced by wrong message**

The `catch` block in `loadAnthropicSdk` catches **all** exceptions, including the `PeerDependencyError` thrown by `assertSupportedVersion` when the installed SDK is outside `>=0.80.0 <1.0.0`. The catch re-throws with the "not installed" message, discarding the version-mismatch message that was carefully written.

Concretely: a user with `@anthropic-ai/sdk@0.79.0` will see:

> `@anthropic-ai/sdk is required to use BitBadgesAgent but is not installed`

instead of:

> `@anthropic-ai/sdk version 0.79.0 detected; BitBadgesAgent requires >=0.80.0 <1.0.0. Install a compatible version…`

Fix: re-throw `PeerDependencyError` instances before the generic handler:

```ts
  } catch (err) {
    if (err instanceof PeerDependencyError) throw err;
    throw new PeerDependencyError(
      `@anthropic-ai/sdk is required to use BitBadgesAgent but is not installed. ` +
        `Install it with: npm install @anthropic-ai/sdk (supported range: ${SUPPORTED_RANGE})`
    );
  }
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: packages/bitbadgesjs-sdk/src/builder/agent/images.ts
Line: 17-23

Comment:
**JSDoc contradicts the implementation**

The JSDoc comment says:

> "Only string fields named `image` are rewritten"

But the `walk` function replaces `IMAGE_N` tokens in **every string value** across the entire transaction — the key name is never checked. The test on line 119 confirms this: it substitutes inside `metadataPlaceholders['ipfs://METADATA_COLLECTION'].image`, but the same logic would also replace a field named `description` or `uri` if it contained `IMAGE_1`.

If the broad-replacement behaviour is intentional (matching the frontend), update the JSDoc to reflect it:

```ts
 * Recursively replace every string value matching `IMAGE_N` anywhere in the
 * transaction with the corresponding entry from `images`. All string-valued
 * fields are checked — not just fields named `image`.
```

If the intent really was to restrict replacement to `image`-named fields, the `walk` helper needs a key-awareness parameter.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: packages/bitbadgesjs-sdk/src/builder/agent/errors.ts
Line: 63-72

Comment:
**`AnthropicAuthError` message always mentions `ANTHROPIC_API_KEY`, even for OAuth failures**

The hardcoded error message is:

> "Anthropic authentication failed. Check that ANTHROPIC_API_KEY is set and valid."

This is only helpful when the user is using an API key. When they're using `anthropicAuthToken` or the `ANTHROPIC_OAUTH_TOKEN` env var, the message is misleading — they'll look for an API key that isn't relevant to their setup.

Consider a generic message:

```ts
constructor(detail?: string) {
  super(
    `Anthropic authentication failed. Verify that your Anthropic credentials (API key or OAuth token) are valid.${detail ? ` (${detail})` : ''}`,
    'ANTHROPIC_AUTH_ERROR',
    503
  );
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (2): Last reviewed commit: "feat(builder/agent): Anthropic prompt ca..." | Re-trigger Greptile}

[trevormil]

@greptileai review

[greptile-apps]

Version-check error silently replaced by wrong message

The catch block in loadAnthropicSdk catches all exceptions, including the PeerDependencyError thrown by assertSupportedVersion when the installed SDK is outside >=0.80.0 <1.0.0. The catch re-throws with the "not installed" message, discarding the version-mismatch message that was carefully written.

Concretely: a user with @anthropic-ai/sdk@0.79.0 will see:

@anthropic-ai/sdk is required to use BitBadgesAgent but is not installed

instead of:

@anthropic-ai/sdk version 0.79.0 detected; BitBadgesAgent requires >=0.80.0 <1.0.0. Install a compatible version…

Fix: re-throw PeerDependencyError instances before the generic handler:

  } catch (err) {
    if (err instanceof PeerDependencyError) throw err;
    throw new PeerDependencyError(
      `@anthropic-ai/sdk is required to use BitBadgesAgent but is not installed. ` +
        `Install it with: npm install @anthropic-ai/sdk (supported range: ${SUPPORTED_RANGE})`
    );
  }

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/bitbadgesjs-sdk/src/builder/agent/anthropicClient.ts
Line: 59-64

Comment:
**Version-check error silently replaced by wrong message**

The `catch` block in `loadAnthropicSdk` catches **all** exceptions, including the `PeerDependencyError` thrown by `assertSupportedVersion` when the installed SDK is outside `>=0.80.0 <1.0.0`. The catch re-throws with the "not installed" message, discarding the version-mismatch message that was carefully written.

Concretely: a user with `@anthropic-ai/sdk@0.79.0` will see:

> `@anthropic-ai/sdk is required to use BitBadgesAgent but is not installed`

instead of:

> `@anthropic-ai/sdk version 0.79.0 detected; BitBadgesAgent requires >=0.80.0 <1.0.0. Install a compatible version…`

Fix: re-throw `PeerDependencyError` instances before the generic handler:

```ts
  } catch (err) {
    if (err instanceof PeerDependencyError) throw err;
    throw new PeerDependencyError(
      `@anthropic-ai/sdk is required to use BitBadgesAgent but is not installed. ` +
        `Install it with: npm install @anthropic-ai/sdk (supported range: ${SUPPORTED_RANGE})`
    );
  }
```

How can I resolve this? If you propose a fix, please make it concise.