copperhead 0.9.0 → 0.11.0

package/NOTICE

@@ -2,4 +2,4 @@ copperhead
 Copyright 2026 Chouhan Industries
 
 This product includes software developed at Chouhan Industries
-(https://github.com/chouhanindustries/copperhead).
+(https://github.com/copperheadhq/copperhead).

package/README.md

@@ -1,17 +1,17 @@
 <p align="center">
-  <a href="https://copperhead.sh"><img src="https://raw.githubusercontent.com/chouhanindustries/copperhead/main/docs/branding/lockup-transparent.png" alt="copperhead" width="440"></a>
+  <a href="https://copperhead.sh"><img src="https://raw.githubusercontent.com/copperheadhq/copperhead/main/docs/branding/lockup-transparent.png" alt="copperhead" width="440"></a>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/copperhead"><img src="https://img.shields.io/npm/v/copperhead?color=b87333" alt="npm"></a>
-  <a href="https://github.com/chouhanindustries/copperhead/actions/workflows/ci.yml"><img src="https://github.com/chouhanindustries/copperhead/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/copperheadhq/copperhead/actions/workflows/ci.yml"><img src="https://github.com/copperheadhq/copperhead/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/npm/l/copperhead?color=15181c" alt="license"></a>
 </p>
 
 **Cursor for circuit boards.** An AI agent that designs, documents, and validates real PCBs from a prompt, working directly on existing KiCad repositories.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/chouhanindustries/copperhead/main/assets/copperhead.gif" alt="copperhead agent shell demo" width="720">
+  <img src="https://raw.githubusercontent.com/copperheadhq/copperhead/main/assets/copperhead.gif" alt="copperhead agent shell demo" width="720">
 </p>
 
 > **Status: early.** Phase 1 is implemented and the CLI runs. The [technical specification](openspec/specs/SPEC.md) is the source of truth; expect the surface to move before 1.0.
@@ -32,7 +32,7 @@ It reads and edits real `.kicad_sch` / `.kicad_pcb` files (s-expression text), m
 > [!TIP]
 > **Most users should not install copperhead by hand.** If you are working inside an AI coding assistant (like Claude Code, Cursor, or Codex), you can install and configure copperhead automatically for your repository by pasting this single line:
 > ```text
-> Install copperhead for this repo using https://raw.githubusercontent.com/chouhanindustries/copperhead/main/agent-install-prompt.md
+> Install copperhead for this repo using https://raw.githubusercontent.com/copperheadhq/copperhead/main/agent-install-prompt.md
 > ```
 
 If you prefer to install manually:
@@ -56,7 +56,7 @@ The script is conservative by design: it never runs `sudo` and never edits shell
 ### Requirements
 
 - Node.js ≥ 20
-- [KiCad](https://www.kicad.org/) ≥ 8 with `kicad-cli` on PATH
+- [KiCad](https://www.kicad.org/) ≥ 8 with `kicad-cli` on PATH (on Windows and macOS, copperhead also searches standard installation directories automatically; override with `COPPERHEAD_KICAD_CLI`)
 - One model backend: a locally installed, ChatGPT-authenticated [Codex CLI](https://learn.chatgpt.com/docs/codex/cli), a logged-in [Cursor Agent CLI](#saved-login-cursor-agent) (`agent login`), logged-in Claude Code (see [Saved login](#saved-login-claude-code)), or `ANTHROPIC_API_KEY`/`OPENAI_API_KEY` in the environment. `check` never calls an LLM.
 
 ## Quick start
@@ -115,16 +115,21 @@ Spec-gated in, verification-gated out: the design can't drift from its requireme
 ```text
 copperhead init [--path hardware/]   # scaffold docs/ from an existing schematic; idempotent
 copperhead do "<change request>"     # the core loop: propose, edit, verify, propagate, commit
+copperhead skill list                # registered skills (no LLM)
+copperhead skill run generate-report # read-only design report (needs a model)
 copperhead check                     # ERC + DRC + doc-drift + spec validation; no LLM calls (alias: verify)
-copperhead doctor                    # env preflight: kicad-cli, git, node, provider credential; no LLM/network
+copperhead doctor                    # env preflight: node, kicad-cli, git, openspec, provider credential; no LLM/network
 copperhead sync [--dry-run]          # verify the whole design state, resolve drift
 copperhead create --brief brief.md   # brief → full output package
 copperhead export bom --supplier jlcpcb   # supplier-ready ordering file from docs/BOM.md
+copperhead mcp                       # EXPERIMENTAL: serve the gated pipeline to MCP hosts over stdio
 ```
 
-Global flags: `--repo <path>` (default: cwd) and `--json` for machine-readable output. `--model` is available on `do`, `sync`, `create`, and `doctor`; `--interactive` only on `do` and `create`; `do` also takes `--dry-run`, `--max-turns`, and `--allow-dirty`.
+Global flags: `--repo <path>` (default: cwd) and `--json` for machine-readable output. `--model` is available on `do`, `sync`, `create`, `skill run`, and `doctor`; `--interactive` only on `do` and `create`; `do` also takes `--dry-run`, `--max-turns`, and `--allow-dirty`.
 
-`--model` accepts `gpt-5` (OpenAI), `claude` / `claude-<id>` (Anthropic API), `claude-code` / `claude-code:<id>` (Claude Code, saved login), `cursor` / `cursor:<id>` (Cursor Agent CLI, saved login), and `codex` / `codex:<id>` (Codex CLI, saved login). Routing is by prefix; `claude-code` is matched before the `claude` prefix. `compat:<id>` targets any OpenAI-compatible endpoint (Groq, OpenRouter, Gemini, or a local Ollama) via `COPPERHEAD_BASE_URL` and `COPPERHEAD_API_KEY_ENV`.
+`copperhead create` still uses its own hardcoded stages; those are not yet skills.
+
+`--model` accepts `gpt-5` (OpenAI), `claude` / `claude-<id>` (Anthropic API), `claude-code` / `claude-code:<id>` (Claude Code, saved login), `cursor` / `cursor:<id>` (Cursor Agent CLI, saved login), and `codex` / `codex:<id>` (Codex CLI, saved login). Routing is by prefix; `claude-code` is matched before the `claude` prefix. `compat:<id>` targets any OpenAI-compatible endpoint (Groq, OpenRouter, Gemini, or a local Ollama) via `COPPERHEAD_BASE_URL` and `COPPERHEAD_API_KEY_ENV` - worked examples for each in [`.env.example`](.env.example) and the [configuration reference](https://docs.copperhead.sh/reference/configuration/#model-selection).
 
 ### Saved login (Cursor Agent)
 
@@ -169,6 +174,39 @@ copperhead export bom --supplier mouser --spares 15     # Mouser cart CSV, 15% s
 
 Nothing is a black box: decisions land in an append-only `docs/DECISIONS.md`, every run writes a human-readable summary next to its transcript, and a per-run `docs/CHANGELOG.md` narrates the design history.
 
+## MCP server (experimental)
+
+Coding agents are already pointed at KiCad repos through generic file tools, which
+means a host agent can rewrite a `.kicad_sch` with no spec gate, no verification,
+and no rollback. `copperhead mcp` closes that: it serves the gated pipeline to any
+MCP host as five opaque, outcome-level tools — `copperhead_check`, `copperhead_do`,
+`copperhead_sync`, `copperhead_init`, `copperhead_doctor` — and nothing finer. There is no file-edit
+tool, no raw KiCad tool, and no partial-loop tool to reach around, so a host agent
+cannot skip spec-gating or verification by any sequence of calls.
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "copperhead": {
+      "command": "copperhead",
+      "args": ["mcp", "--repo", "/absolute/path/to/your/kicad/project"]
+    }
+  }
+}
+```
+
+> **The surface is experimental and unstable.** It declares a `0.` protocol major:
+> tool names, inputs, and result shapes may change in any release, and there is no
+> registry listing until the stabilization criteria are met. Host configuration for
+> Claude Code and generic stdio hosts, the companion skill, the Codex gap, and those
+> criteria are all in [`integrations/`](integrations/README.md).
+
+`copperhead_check`, `copperhead_init` and `copperhead_doctor` need no credential; `copperhead_do` and
+`copperhead_sync` with `resolve: true` refuse with a typed error naming the missing
+environment variable. The server opens no network transport of its own — stdio only,
+and LLM calls happen exactly where the CLI already makes them.
+
 ## What it is not
 
 - **Not an autorouter.** Routing stays human or delegated; copperhead produces the DRC-clean draft that layout tools optimize from.
@@ -214,6 +252,7 @@ Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md) for setup and
 
 - [`AGENTS.md`](AGENTS.md): repository instructions loaded automatically by Codex and compatible coding agents; [`CLAUDE.md`](CLAUDE.md) provides the corresponding Claude Code guidance
 - [`src/`](src/): CLI ([`cli.ts`](src/cli.ts), [`commands/`](src/commands/)), the provider-agnostic agent loop ([`agent/`](src/agent/)), the `kicad-cli` wrapper and s-expression reader ([`kicad/`](src/kicad/)), and doc/constraint memory ([`memory/`](src/memory/))
+- [`integrations/`](integrations/README.md): MCP host configuration and the companion Claude Code skill
 - [`test/`](test/): offline suite plus [`fixtures/`](test/fixtures/), a tiny known-good KiCad project
 - [`openspec/specs/SPEC.md`](openspec/specs/SPEC.md): the full technical specification, including binary acceptance criteria
 - [`openspec/changes/build-copperhead-phase-1/`](openspec/changes/build-copperhead-phase-1/): the implementation plan with proposal, design decisions, capability specs, and task checklist

package/dist/agent/context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.js.map

package/dist/agent/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/agent/context.ts"],"names":[],"mappings":""}

package/dist/agent/dock-renderer.js

@@ -53,8 +53,8 @@ export class DockRenderer {
     log(line) {
         this.emit(line);
     }
-    toolResult(name, firstLine) {
-        this.emit(toolLine(name, firstLine));
+    toolResult(name, firstLine, ok, viewHint) {
+        this.emit(toolLine(name, firstLine, ok, viewHint));
     }
     turnStartMs = Date.now();
     turnStart(turn, maxTurns, tokensIn, tokensOut) {

package/dist/agent/dock-renderer.js.map

@@ -1 +1 @@
-{"version":3,"file":"dock-renderer.js","sourceRoot":"","sources":["../../src/agent/dock-renderer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dock-renderer.js","sourceRoot":"","sources":["../../src/agent/dock-renderer.ts"],"names":[],"mappings":"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"}

package/dist/agent/envelope.js

@@ -0,0 +1,105 @@
+import { redactSecrets } from '../util/redact.js';
+/** Envelope protocol version for the ToolResult shape (design D5). */
+export const PROTOCOL_VERSION = 1;
+function redactEnvelopeText(text) {
+    let out = redactSecrets(text);
+    for (const [name, val] of Object.entries(process.env)) {
+        if (!val || val.length < 8)
+            continue;
+        if (!/_(KEY|SECRET|TOKEN)$/.test(name))
+            continue;
+        if (out.includes(val))
+            out = out.split(val).join('[REDACTED]');
+    }
+    return out;
+}
+function redactDeep(value) {
+    if (typeof value === 'string')
+        return redactEnvelopeText(value);
+    if (Array.isArray(value))
+        return value.map(redactDeep);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactDeep(v)]));
+    }
+    return value;
+}
+/** Redact every string field at construction so render/dock never see secrets. */
+export function seal(partial) {
+    return {
+        ok: partial.ok,
+        summary: redactEnvelopeText(partial.summary),
+        ...(partial.detail !== undefined ? { detail: redactEnvelopeText(partial.detail) } : {}),
+        ...(partial.data !== undefined ? { data: redactDeep(partial.data) } : {}),
+        ...(partial.error
+            ? { error: { kind: partial.error.kind, message: redactEnvelopeText(partial.error.message) } }
+            : {}),
+        ...(partial.viewHint ? { viewHint: partial.viewHint } : {}),
+    };
+}
+export function okResult(text, viewHint, data) {
+    const first = text.split('\n')[0] ?? text;
+    return seal({
+        ok: true,
+        summary: first,
+        ...(text !== first ? { detail: text } : {}),
+        ...(data !== undefined ? { data } : {}),
+        ...(viewHint ? { viewHint } : {}),
+    });
+}
+export function failResult(kind, message, viewHint) {
+    const first = message.split('\n')[0] ?? message;
+    return seal({
+        ok: false,
+        summary: first,
+        error: { kind, message },
+        ...(viewHint ? { viewHint } : {}),
+    });
+}
+/** Flatten an envelope to the string providers already consume as tool Msg content. */
+export function flatten(result) {
+    if (result.error)
+        return result.error.message;
+    if (result.detail) {
+        return result.detail.startsWith(result.summary) ? result.detail : `${result.summary}\n${result.detail}`;
+    }
+    return result.summary;
+}
+/** Build an envelope from text plus an outcome already known by the handler. */
+export function outcomeResult(text, ok, viewHint) {
+    const first = text.split('\n')[0] ?? text;
+    return seal({
+        ok,
+        summary: first,
+        ...(text !== first ? { detail: text } : {}),
+        ...(viewHint ? { viewHint } : {}),
+    });
+}
+/**
+ * Wrap a legacy handler string. Error-shaped prefixes become typed failures so
+ * validation/refusal are not retried; everything else is success. Flattened
+ * text equals the original string.
+ */
+export function textResult(text, viewHint) {
+    if (/^error:/.test(text) ||
+        text.startsWith('rejected:') ||
+        text.startsWith('edit REVERTED') ||
+        text.startsWith('validation FAILED')) {
+        return failResult('validation', text, viewHint);
+    }
+    if (text.startsWith('refused:') ||
+        text.startsWith('cannot finish yet') ||
+        text.startsWith('proposal validated but human declined')) {
+        return failResult('refusal', text, viewHint);
+    }
+    return okResult(text, viewHint);
+}
+export function unavailable(name, editsUnlocked, reason) {
+    const suffix = reason
+        ? ` (${reason})`
+        : editsUnlocked
+            ? ''
+            : ' (edit tools unlock after the proposal validates)';
+    const message = `tool "${name}" is not available${suffix}`;
+    return failResult('unavailable', message);
+}
+//# sourceMappingURL=envelope.js.map

package/dist/agent/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/agent/envelope.ts"],"names":[],"mappings":"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"}

package/dist/agent/filetools.js

@@ -52,6 +52,29 @@ export async function toolEditFile(repoRoot, p, oldString, newString, replaceAll
     return `edited ${p}`;
 }
 const SKIP_DIRS = new Set(['.git', 'node_modules', 'dist', '.copperhead']);
+/**
+ * Longest match line returned to the model, in characters.
+ *
+ * The file-size bound in `toolSearch` (5 MB) bounds the file, not the line, and
+ * on a one-object-per-line document those are very different limits. A
+ * `transcript.jsonl` line is an entire `{ts, type, data}` record with tool
+ * output inline, so a few matches inside one file can be hundreds of thousands
+ * of tokens. A live run died on exactly that — `Prompt is too long · the
+ * request is ~1003121 tokens (limit 1000000) but this conversation is only
+ * ~403383 tokens`, the balance being search results — and it cost a stage
+ * attempt. The agent had done nothing wrong: it searched the repo it was told
+ * to work in, and a `run-logs/` directory happened to be sitting in it.
+ *
+ * A match is a pointer, not a payload — enough to see the hit and decide
+ * whether to read the file. Truncation is marked so a clipped line is
+ * distinguishable from a short one.
+ */
+const MAX_MATCH_CHARS = 400;
+/** Clip one match line to `MAX_MATCH_CHARS`, marking it when clipped. */
+function clipMatch(line) {
+    const t = line.trim();
+    return t.length <= MAX_MATCH_CHARS ? t : `${t.slice(0, MAX_MATCH_CHARS)}… [+${t.length - MAX_MATCH_CHARS} chars]`;
+}
 export function globToRegex(glob) {
     let out = '';
     for (let i = 0; i < glob.length; i++) {
@@ -105,7 +128,7 @@ export async function toolSearch(repoRoot, pattern, glob, maxMatches = 200) {
                 const lines = text.split('\n');
                 for (let i = 0; i < lines.length && matches.length < maxMatches; i++) {
                     if (re.test(lines[i]))
-                        matches.push({ file: rel, line: i + 1, text: lines[i].trim() });
+                        matches.push({ file: rel, line: i + 1, text: clipMatch(lines[i]) });
                 }
             }
             if (matches.length >= maxMatches)

package/dist/agent/filetools.js.map

@@ -1 +1 @@
-{"version":3,"file":"filetools.js","sourceRoot":"","sources":["../../src/agent/filetools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"filetools.js","sourceRoot":"","sources":["../../src/agent/filetools.ts"],"names":[],"mappings":"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"}

package/dist/agent/ledger.js

@@ -1,5 +1,19 @@
 export class ObligationsLedger {
+    gateLegibility;
     open = [];
+    /**
+     * @param gateLegibility whether error-severity legibility findings block
+     * `finish`. True for repos whose schematic copperhead authored (create
+     * origin) — there the standard is copperhead's own responsibility. False for
+     * hand-drawn repos (`do` on an init-ed or hand-maintained project), where a
+     * pre-existing sheet could never satisfy the standard without a full redraw
+     * and the obligation would wedge every schematic-touching run; those repos
+     * get the same findings as advisory information via the tool and `check`
+     * (design C6: check reports, create gates).
+     */
+    constructor(gateLegibility = true) {
+        this.gateLegibility = gateLegibility;
+    }
     add(kind, detail, openedBy) {
         if (!this.open.some((o) => o.kind === kind && o.detail === detail)) {
             this.open.push({ kind, detail, openedBy });
@@ -20,12 +34,22 @@ export class ObligationsLedger {
         this.add('erc', 'ERC must pass after schematic edits', file);
         if (file.endsWith('.kicad_pcb'))
             this.add('drc', 'DRC must pass after board edits', file);
+        if (file.endsWith('.kicad_sch') && this.gateLegibility) {
+            this.add('legibility', 'check_legibility must run clean after schematic edits', file);
+        }
         this.add('drift', 'check_drift must run clean after KiCad edits', file);
         this.add('changelog', 'CHANGELOG.md entry for this run', file);
     }
     onDocEdit(file) {
         this.add('drift', 'check_drift must run clean after doc edits', file);
     }
+    /** A checker run updates the obligation: clean clears it, errors re-open it (gated repos only). */
+    onLegibilityResult(errorCount) {
+        this.clear('legibility');
+        if (errorCount > 0 && this.gateLegibility) {
+            this.add('legibility', `${errorCount} error-severity legibility finding(s) unreconciled`, 'check_legibility');
+        }
+    }
     onConstraintChange(constraintKey, affects) {
         this.add('constraint-dual-write', constraintKey, constraintKey);
         for (const item of affects) {

package/dist/agent/ledger.js.map

@@ -1 +1 @@
-{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../src/agent/ledger.ts"],"names":[],"mappings":"AAoBA,MAAM,OAAO,iBAAiB;IACpB,IAAI,GAAiB,EAAE,CAAC;IAEhC,GAAG,CAAC,IAAoB,EAAE,MAAc,EAAE,QAAgB;QACxD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,EAAE,CAAC;YACnE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,oEAAoE;IACpE,KAAK,CAAC,IAAoB,EAAE,MAAe;QACzC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAC1B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAC3E,CAAC;QACF,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACnC,CAAC;IAED,yEAAyE;IACzE,UAAU,CAAC,IAAoB;QAC7B,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAClD,CAAC;IAED,iFAAiF;IACjF,WAAW,CAAC,IAAY;QACtB,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,qCAAqC,EAAE,IAAI,CAAC,CAAC;QAC7D,IAAI,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,iCAAiC,EAAE,IAAI,CAAC,CAAC;QAC1F,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,8CAA8C,EAAE,IAAI,CAAC,CAAC;QACxE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,iCAAiC,EAAE,IAAI,CAAC,CAAC;IACjE,CAAC;IAED,SAAS,CAAC,IAAY;QACpB,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,4CAA4C,EAAE,IAAI,CAAC,CAAC;IACxE,CAAC;IAED,kBAAkB,CAAC,aAAqB,EAAE,OAAiB;QACzD,IAAI,CAAC,GAAG,CAAC,uBAAuB,EAAE,aAAa,EAAE,aAAa,CAAC,CAAC;QAChE,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,GAAG,aAAa,YAAY,IAAI,EAAE,EAAE,aAAa,CAAC,CAAC;QACjF,CAAC;IACH,CAAC;IAED,UAAU,CAAC,OAAe;QACxB,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAChD,CAAC;IAED,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,QAAQ;QACN,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,gCAAgC,CAAC;QAC1D,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,MAAM,eAAe,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChG,CAAC;CACF"}
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../src/agent/ledger.ts"],"names":[],"mappings":"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"}