Amber Protocol

Governed Agent Harness for real engineering systems.

Amber Protocol is the governed execution boundary between AI agents and real systems. It governs what an agent may see, use, execute, and emit, with whose approval, and what evidence proves it — in files beside the code, not in chat history.

Amber Protocol 是 AI Agent 与真实系统之间的治理执行边界。

Version: 2.0.1 · Status: Stable · Milestones & test status →

What is Amber?

Amber Protocol is a repository-local governance layer for projects that already use coding agents in recurring, real delivery work. The hard part is no longer only producing code. It is preserving enough trustworthy state for the next person or agent to understand what happened, what was approved, what evidence exists, and what should happen next.

Amber makes that state explicit through plans, sessions, evidence, decisions, and handoffs stored beside the code. Its core outcome is Trusted Continuation: another person or agent can enter without the old chat, identify the current state, and take one correct next step.

Amber = the in-repo team replication layer: how a team safely uses AI on this codebase, written as handoff-ready file evidence.

It sits under your existing coding engine and adds governance plus evidence. It is not another agent runtime, and not an org-scale platform.

Layering

Engines do the work; Amber proves what was done, whether it is safe to keep, and how to hand it off.

What Amber will NOT do

These are product boundaries, not TODOs:

1. Not a replacement for the coding engine / not a general agent runtime
2. No Dynamic Workflow execution, no live subagent dispatch, no automatic execution of your project commands
3. No org-scale marketplace, cross-repo gateway, cross-machine dashboard, or always-on scheduler
4. No overwrite of existing project docs (init / wiki only create missing files)

Full boundaries: Team Replication Charter and SPEC.md.

Who it is for

The target environment is a Coding-Agent-Enabled Repository: maintainers already use one or more coding agents for ongoing delivery under human review. A one-off experiment or a repository that merely installed an agent tool does not qualify.

• Primary user — Repository Maintainer: accountable for the repository outcome and continuity.
• Working user — agent-assisted developer: frames and performs bounded delivery work.
• Decision user — reviewer: makes go/no-go decisions from plans, diffs, and evidence.

Why Amber?

AI coding work becomes easier to trust when the workflow leaves inspectable evidence:

• Continue without the old chat: plans, sessions, evidence, and handoffs make state portable across people and agents.
• Review from repository evidence: decisions rest on inspectable artifacts, not a completion claim in a transcript.
• Recover at the right stage: failures and interruptions remain attached to the step that produced them.
• Keep authority explicit: human approvals and governed boundaries are records, not hidden runtime assumptions.

Product journey

Fit -> Adopt -> First trusted continuation -> Deliver -> Recover -> Review / Accept

Feature, bugfix, and refactor routes remain backend policy. Users keep one frontstage model:

Frame -> Authorize -> Work -> Prove -> Review -> Handoff / Accept

Context repair, continuous improvement, team expansion, and high-assurance operations are conditional paths. They do not block the first Trusted Continuation. See the feature matrix and complete journey definitions.

Installation

From npm (Recommended)

npm install -g amber-protocol
amber --version

From source

git clone https://github.com/Bandersnatch0x/amber-protocol.git
cd amber-protocol
npm install
node scripts/amber.js --version

Upgrading to 2.0.0

2.0.0 is a breaking release: three command families that shipped in 1.6.0 — and were already marked deprecated in its help text — are now removed. Nothing else changed shape: plans, sessions, gates, approvals, evidence, and handoffs keep their contracts.

The disposition is recorded, not implied — the removed surfaces and their replacement routes stay readable from the tool itself:

amber harness legacy --target .    # every removed surface with its replacement route

If you pin ^1.6.0, a npm update will not cross into 2.0.0 — that range deliberately stops short of the break. Move to ^2.0.0 once you are off the removed commands.

Quick Start (about 10 minutes)

Use one real task to test whether Amber creates Trusted Continuation. File generation alone is not activation.

# J0 — establish fit without changing the project
amber audit --target my-project

# J1 — install the minimum surface; existing files are skipped
amber init --target my-project
amber doctor --target my-project

# J2 — frame one real goal and follow the state-derived next step
amber next --objective "finish the current API change" --target my-project

# Generate a repository-local continuation bundle
amber handoff --target my-project

Now open a fresh agent session or ask another maintainer to inspect the repository without the old chat. Amber is activated only when that new context can explain the current state and take one correct next step.

init and wiki never overwrite existing files. Default help exposes seven fallback verbs: audit, init, doctor, next, plan, handoff, and session. amber --all keeps the expert and compatibility surface available. See the CLI reference.

Expert path (not the homepage main line): read-only continuous-improvement discovery via amber loop recommend — see the loop sections under "What It Won't Do" below.

Command surface

Default amber --help projects seven primary verbs — the whole journey fits in them:

Everything else is governance and platform surface, deliberately one flag away in amber --all:

• Context and knowledge — wiki, context request|ingest|verify|refresh|stats, memory, knowledge
• Governed records — artifact, principal, evidence, approval, gate, policy
• Control and assurance — projection, adapter, maintain, retention, external, breakglass, eval run
• Delivery and reporting — sync session, governance report, loop recommend, learnings, break-loop, harness

Hiding a family from the default help changes discovery, never capability: every family is documented in the CLI reference, and amber <family> --help is authoritative for its flags.

Using it in DeepSeek Harness

The overlay ships as a native dsh-plugin bundle:

# Install once; dsh adds the Amber bundle layer to the profile
dsh plugin --profile web add dsh-amber-protocol

# Afterwards a normal start loads Amber (no repeated --patch)
dsh --profile web

On Windows the default port 3080 is often reserved; add --port 13080 if the listener fails.

Unpublished-checkout fallback: if you are developing Amber itself and the bundle is not published yet, use an overlay patch instead. Edit dsh/amber-full.patch.yml, replace /path/to/amber-protocol with this repository's path, and layer it at startup without touching the profile:

dsh --profile web --patch /path/to/amber-protocol/dsh/amber-full.patch.yml

Full notes: dsh/README.md.

Core Concepts

Amber organizes governance into seven control layers, weighted toward safety — the higher the priority, the more of Amber's surface that layer gets:

The through-line: strengthen Governance, Verification, and Observability; keep Lifecycle repository-local; avoid drifting into a full agent platform. The governance model maps each layer to concrete commands.

What gets installed — the minimum surface doctor checks for:

• AGENTS.md and CLAUDE.md — agent-facing rules
• feature_list.json — tracked feature state
• PROGRESS.md, session-handoff.md, clean-state-checklist.md, evaluator-rubric.md
• .amber/continuous-improvement/state.json
• a minimal docs/wiki/ — project context, system map, runbook, verification, glossary

All starter files are safe defaults. init and wiki skip existing files and report what would be created in dry-run mode.

What It Won't Do

These boundaries are part of the product, not TODOs:

• No dynamic workflow execution or live subagent dispatch
• No automatic / unattended execution — see "Governed loop execution" below for the one gated exception
• No scheduled / cron / hook-triggered execution
• No external writes (PRs, issue trackers, notifications) or agent tool-call interception
• No automatic rewrite of existing project docs
• No governed verb-stage execution in a vanilla install: the implementation-owned adapter table ships empty (there is no fallback), so session run stages fail closed until a capability is registered — and registering one is a reviewed code change, not a config edit

Governed loop execution (opt-in, gated)

Since ADR-0003, Amber can run a loop contract's declared governed.command — but only behind four gates: a declarative policy check (.amber/governance/rules.json, deny-wins / default-deny), an explicit amber loop approve (one approval authorizes one run), an isolated git worktree (your main checkout is never the cwd), and a tamper-evident hash-chain ledger. Default loop run is still dry-run; execution needs --execute.

amber loop approve --file <pack> --contract <id> --reviewer <name>
amber loop run --file <pack> --contract <id> --execute
amber loop verify-ledger --contract <id>
amber governance standards --target .   # honest OWASP-ASI coverage of what this does (and doesn't) cover

For the full boundary notes, see SPEC.md.

amber loop recommend — the safe continuous-improvement entry

amber loop recommend is read-only: it scans the local workflow-packs' loop contracts, scores them against a maintenance goal, and prints the dry-run command best suited to human review. It never schedules work, executes workflow steps, dispatches agents, or writes an external system.

amber loop recommend --target . --goal "continuous improvement" --json
amber loop run --file workflow-packs/safe-amber-bootstrap.pack.json --contract daily-amber-triage --dry-run --json

Live scheduling stays outside the product boundary: loop run requires --dry-run.

Governed trust layer (trusted-control contracts)

Beyond the journey surface, Amber ships a contract-tested trust layer (four canonical contracts with product tests, all delivered):

• Governed execution attempts — every session run attempt freezes its admission inputs (scope, policy, capability, request digest) before any effect; the gates re-verify against the frozen values, and authorization grants bind that frozen tuple with single-use consumption. Drift is refused at the gate, before execution.
• Evidence with assurance levels — receipts carry unavailable / observed / replayable / verified, and a replay bundle (amber handoff bundle --replay-scope) rebuilds the authorization chain offline.
• Governed memory — durable lessons flow through amber memory (request → ingest → human approve → book); MEMORY.md stays human-curated and hash-registered.
• Instruction-surface evals — amber eval run replays deterministic model-independent checks of the agent-facing surfaces.
• MCP Action Types — 21 thin projections of the governed verbs; mutating actions return approvalRequired and are never executed by the MCP surface.

These surfaces are the protocol's reference implementation: governed verb stages currently fail closed (no capability is registered — see "What It Won't Do") and the canonical specs are awaiting their coordinator re-review.

Documentation

The public documentation site (apps/docs) provides reader-focused guides, concepts, and authoritative single-source CLI references with 100% offline local search:

npm run docs:build      # Build the static documentation site
npm run docs:verify     # Run the mechanical verification seam
npm run docs:gen        # Generate CLI reference pages from command registry
npm run docs:gen:check  # Verify zero drift between code and CLI reference docs
npm run docs:test       # Run public documentation test suite

The optional Web Viewer (apps/web) is a journey-aware inspector. It shows the current J0–J5 stage, the next governed action, active sessions, pending gates, and repository-local evidence. It reflects Amber state; it does not create a second workflow or replace the Agent/CLI authority surface.

cd apps/web
npm install --legacy-peer-deps
npm run dev
# Visit http://localhost:3001

Contributing

See CONTRIBUTING.md for development setup, CI, and the release process.

Support

• 📖 Documentation: docs/
• 🐛 Report bugs: GitHub Issues
• 💡 Feature requests: GitHub Discussions

License

MIT License — see LICENSE for details.