diff --git a/CLAUDE.md b/CLAUDE.md index c7e0e41c..c51a1ac6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -3,8 +3,8 @@ ## Architecture Rust monorepo with Cargo workspace. See `docs/arch.md` for component inventory. See `docs/spec/credential-backend-interface.md` for the CredentialBackend trait contract (15 methods). -See `docs/spec/plans/milestones-roadmap.md` for the M1–M7 milestone roadmap (replaces the archived v1/v2 staged plan). -See `docs/spec/plans/execution-plan.md` for the orchestration runbook (ralph, team, ultraqa). +See `docs/plan/milestones-roadmap.md` for the M1–M7 milestone roadmap (replaces the archived v1/v2 staged plan). +See `docs/plan/execution-plan.md` for the orchestration runbook (ralph, team, ultraqa). Do not read folder `docs/archived` ## Docs layout (lean) @@ -18,7 +18,7 @@ Do not read folder `docs/archived` **User-facing instructions** — every behavior/caveat a user would notice (e.g. `agentkeys wire` taking over the runtime's `hooks:` block) goes in [`docs/user-manual.md`](docs/user-manual.md), the single home for user-aware instructions. ## Architecture-as-source-of-truth policy -[`docs/arch.md`](docs/arch.md) is the **single source of truth** for component inventory, key inventory (K1–K11), trust boundaries, identity model (HDKD actor tree), and per-actor binding ceremonies. **After editing any architectural doc** (broker plans, signer-protocol, demo doc, runbooks, plan files in `docs/spec/plans/`, heima-gaps), re-open `arch.md` and verify it still matches; if it diverges, update arch.md in the same change. If the per-doc detail outgrows arch.md, link from arch.md outward — never duplicate. The wiki page at [`docs/wiki/agent-role-and-usage-hdkd-per-agent-omni.md`](docs/wiki/agent-role-and-usage-hdkd-per-agent-omni.md) is a focused operator reference for the agent role; it defers to arch.md. +[`docs/arch.md`](docs/arch.md) is the **single source of truth** for component inventory, key inventory (K1–K11), trust boundaries, identity model (HDKD actor tree), and per-actor binding ceremonies. **After editing any architectural doc** (broker plans, signer-protocol, demo doc, runbooks, plan files in `docs/plan/`, heima-gaps), re-open `arch.md` and verify it still matches; if it diverges, update arch.md in the same change. If the per-doc detail outgrows arch.md, link from arch.md outward — never duplicate. The wiki page at [`docs/wiki/agent-role-and-usage-hdkd-per-agent-omni.md`](docs/wiki/agent-role-and-usage-hdkd-per-agent-omni.md) is a focused operator reference for the agent role; it defers to arch.md. ## `/create-pr` policy When the `/create-pr` skill is invoked from a Claude Code worktree at `.claude/worktrees/`, the worktree is a *git worktree* under the main repo — `jj` cannot colocate there (`jj git init --colocate` fails with "Cannot create a colocated jj repo inside a Git worktree"). Use this hybrid workflow so the jj-only rule is preserved everywhere it can be: @@ -76,7 +76,7 @@ If a hardcoded value is genuinely temporary — e.g. you're sketching a fix and Hardcoded values that go unrecorded compound: each new operator adds defaults baked into a different layer, the runbook drifts from reality, and the project becomes un-deployable to anyone but the original author. The audit log is the cure — it forces an explicit decision instead of an accumulating series of "I'll fix it later"s. ## Plan-completion policy -When the user references a plan (e.g. `docs/spec/plans/issue-XX-*.md`), **complete every numbered step in the plan's implementation-order table — not a self-selected subset**. If you cannot complete a step (interactive flow needs human, scope explosion, prerequisites missing), say so up front before starting work and get explicit approval to defer. Never silently drop steps and ship a partial plan as "done." +When the user references a plan (e.g. `docs/plan/issue-XX-*.md`), **complete every numbered step in the plan's implementation-order table — not a self-selected subset**. If you cannot complete a step (interactive flow needs human, scope explosion, prerequisites missing), say so up front before starting work and get explicit approval to defer. Never silently drop steps and ship a partial plan as "done." The end-of-PR summary is mandatory and has two sections in this exact order: @@ -211,7 +211,7 @@ The agent-side wire demo (`agentkeys wire hermes` inside the aiosandbox) MUST ex On every session start: 1. `jj log --limit 10 && cat harness/progress.json && bash harness/init.sh $(jq -r .current_stage harness/progress.json)` -2. Read the milestone scope for the current milestone in `docs/spec/plans/milestones-roadmap.md` (the v1/v2 stage framing is archived at `docs/archived/development-stages-v2-2026-04.md`) +2. Read the milestone scope for the current milestone in `docs/plan/milestones-roadmap.md` (the v1/v2 stage framing is archived at `docs/archived/development-stages-v2-2026-04.md`) 3. Pick the HIGHEST-PRIORITY incomplete deliverable from `harness/features.json` 4. Implement ONE deliverable 5. Run tests: `cargo test -p ` for the affected crate @@ -257,7 +257,7 @@ Determine the real opcode level any time by *executing* a probe on a dev chain ( ## Deployed contract registry -Live contract addresses on each chain (Heima mainnet v2 set, the ERC-4337 master infra #164, historical v1) are kept in [`docs/contracts.md`](docs/contracts.md) — the single canonical registry, indexed from `arch.md` §5. (The old `docs/spec/deployed-contracts.md` is now a redirect to it.) The same addresses are also written to `scripts/operator-workstation.env` (via `env_set` in `scripts/heima-bring-up.sh` step 6) for shell-script consumption — those env-file entries are the operational source of truth and `docs/contracts.md` is the human-readable canonical record (deployer, deploy date, block, explorer links, ABI summary). +Live contract addresses on each chain (Heima mainnet v2 set, the ERC-4337 master infra #164, historical v1) plus the prod/test EVM deployer wallets are kept in [`docs/spec/deployed-contracts.md`](docs/spec/deployed-contracts.md) — the single canonical registry, indexed from `arch.md` §5. (`docs/contracts.md` is now a redirect to it.) The same addresses are also written to `scripts/operator-workstation.env` (via `env_set` in `scripts/heima-bring-up.sh` step 6) for shell-script consumption — those env-file entries are the operational source of truth and `docs/spec/deployed-contracts.md` is the human-readable canonical record (deployer, deploy date, block, explorer links, ABI summary). Verify all contracts are live + functional any time: diff --git a/README.md b/README.md index 75d499ed..2d59ea8d 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ Dual-licensed under **MIT OR Apache-2.0**, at your choice. | [`CLAUDE.md`](CLAUDE.md) | Project-specific rules: docs layout, /create-pr workflow in worktrees, terminology-source-of-truth, branch push policy, idempotent-remote-setup invariants, runbook-fix-fold-back policy. **Read first, every session.** | | [`docs/arch.md`](docs/arch.md) | Single source of truth for component inventory (K1–K11), trust boundaries, HDKD actor tree, per-actor binding ceremonies. When the per-doc detail outgrows arch.md, link outward — never duplicate. | | [`docs/spec/plans/development-stages.md`](docs/spec/plans/development-stages.md) | The 8-stage build plan. Each stage has a `harness/stage-N-done.sh` gate; never self-grade — run the gate. | -| [`docs/spec/plans/execution-plan.md`](docs/spec/plans/execution-plan.md) | Orchestration runbook (ralph, team, ultraqa workflows). | +| [`docs/plan/execution-plan.md`](docs/plan/execution-plan.md) | Orchestration runbook (ralph, team, ultraqa workflows). | | [`docs/spec/broker-and-operator-dev-guide.md`](docs/spec/broker-and-operator-dev-guide.md) | Inner edit-build-test loop for broker + operator-side code. Use this before suggesting changes to the broker's run-time behavior. | ### Hard rules (from CLAUDE.md) diff --git a/TODOS.md b/TODOS.md index b57c4df2..15332224 100644 --- a/TODOS.md +++ b/TODOS.md @@ -54,13 +54,13 @@ production-aligned path. ### Deprecate `agentkeys-mock-server` `/credential/*` — replace with S3 + OIDC + client-side AES-GCM -Draft issue body lives at [`docs/spec/plans/issue-credential-storage-s3-oidc.md`](docs/spec/plans/issue-credential-storage-s3-oidc.md). File on the GitHub repo with: +Draft issue body lives at [`docs/plan/issue-credential-storage-s3-oidc.md`](docs/plan/issue-credential-storage-s3-oidc.md). File on the GitHub repo with: ```bash gh issue create --repo litentry/agentKeys \ --title "Replace mock-server /credential/* with S3-backed encrypted storage (OIDC-scoped, PrincipalTag-isolated)" \ --label "stage-7+,architecture,credential-storage" \ - --body-file docs/spec/plans/issue-credential-storage-s3-oidc.md + --body-file docs/plan/issue-credential-storage-s3-oidc.md ``` Architecture rationale, wire contract sketch, IAM-delta scope, and 6-step migration plan all in the draft. Reuses the SES Lambda's PrincipalTag-isolated bucket + the §5.1 OIDC workflow — zero new deployable artifacts. Forced by the post-issue-#83 storage failure: provision now succeeds through key mint but the legacy backend at `:8090` (loopback-only per [arch.md §11](docs/arch.md#L670)) is unreachable from the operator workstation. diff --git a/crates/agentkeys-broker-server/Cargo.toml b/crates/agentkeys-broker-server/Cargo.toml index 6ebfe507..4ff0a79e 100644 --- a/crates/agentkeys-broker-server/Cargo.toml +++ b/crates/agentkeys-broker-server/Cargo.toml @@ -37,7 +37,7 @@ aws-sdk-sts = "1" # Real SES sender for email-link auth. Optional, gated behind # auth-email-link — without the feature the broker has no SES sender at # all (StubEmailSender remains for tests). Pulled in by Pass 1 of -# Option B per docs/spec/plans/issue-74 (see commit log). +# Option B per docs/archived/issue-74-dev-key-service-plan.md (see commit log). aws-sdk-sesv2 = { version = "1", optional = true } jsonwebtoken = "9" p256 = { version = "0.13", features = ["pkcs8", "pem", "ecdsa"] } diff --git a/crates/agentkeys-broker-server/src/handlers/agent/mod.rs b/crates/agentkeys-broker-server/src/handlers/agent/mod.rs index e6e312e9..d81491a5 100644 --- a/crates/agentkeys-broker-server/src/handlers/agent/mod.rs +++ b/crates/agentkeys-broker-server/src/handlers/agent/mod.rs @@ -1,6 +1,6 @@ //! §10.2 agent-bootstrap endpoints — **method A, agent-initiated** (issue #144, //! flipped from master-initiated; design doc -//! `docs/spec/plans/agent-initiated-pairing-method-a.md`). +//! `docs/archived/agent-initiated-pairing-method-a.md`). //! //! The agent shows a code, the master claims it (the Matter/HomeKit IoT model), //! and the master still submits the on-chain binding (decision 1 — no contract diff --git a/crates/agentkeys-cli/src/hook.rs b/crates/agentkeys-cli/src/hook.rs index 40cef97d..a9617166 100644 --- a/crates/agentkeys-cli/src/hook.rs +++ b/crates/agentkeys-cli/src/hook.rs @@ -10,7 +10,7 @@ //! //! Wire protocol (Hermes / Claude-Code compatible — see //! `docs/wiki/agent-iam-guarantee-glossary.md` §3 + the plan -//! `docs/spec/plans/phase-1-fresh-user-wire-onboarding.md` §5.2): +//! `docs/plan/phase-1-fresh-user-wire-onboarding.md` §5.2): //! //! ```text //! stdin: {hook_event_name, tool_name, tool_input, session_id, cwd, extra} diff --git a/crates/agentkeys-cli/src/lib.rs b/crates/agentkeys-cli/src/lib.rs index 5338543c..68eac918 100644 --- a/crates/agentkeys-cli/src/lib.rs +++ b/crates/agentkeys-cli/src/lib.rs @@ -118,7 +118,7 @@ impl CredentialBackendKind { /// Which envelope format the S3 backend writes. Defaults to `V1` to keep /// existing #87 deployments working unchanged; operators opt in to `V2` /// once they've finished the dual-tag + bucket-policy migration steps in -/// `docs/spec/plans/v2-issues/issue-v2-stage-1-foundation.md`. +/// `docs/plan/v2-issues/issue-v2-stage-1-foundation.md`. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum EnvelopeVersionFlag { V1, diff --git a/crates/agentkeys-cli/src/wire.rs b/crates/agentkeys-cli/src/wire.rs index 76f5402e..0c8e2f51 100644 --- a/crates/agentkeys-cli/src/wire.rs +++ b/crates/agentkeys-cli/src/wire.rs @@ -8,7 +8,7 @@ //! //! Phase 1.a ships the Hermes adapter. The `RuntimeAdapter` trait is the //! seam additional runtimes (Claude Code, Codex, OpenClaw) slot into in -//! Phase 1.b — see docs/spec/plans/phase-1-fresh-user-wire-onboarding.md §4. +//! Phase 1.b — see docs/plan/phase-1-fresh-user-wire-onboarding.md §4. use std::path::PathBuf; use std::process::Command; diff --git a/crates/agentkeys-core/src/s3_backend.rs b/crates/agentkeys-core/src/s3_backend.rs index 8f9b63a2..69d6f40f 100644 --- a/crates/agentkeys-core/src/s3_backend.rs +++ b/crates/agentkeys-core/src/s3_backend.rs @@ -180,7 +180,7 @@ impl S3CredentialBackend { /// `actor_omni_hex`. Stage 1 ships v1 as default so existing #87 /// deployments keep working unchanged; per-operator opt-in flips this /// to v2 once the bucket policy + OIDC dual-tag rollout completes - /// (see `docs/spec/plans/v2-issues/issue-v2-stage-1-foundation.md` + /// (see `docs/plan/v2-issues/issue-v2-stage-1-foundation.md` /// migration step 9). pub fn with_write_envelope(mut self, envelope: WriteEnvelope) -> Self { self.write_envelope = envelope; diff --git a/crates/agentkeys-mcp-server/README.md b/crates/agentkeys-mcp-server/README.md index 13192b6d..44e1ebd3 100644 --- a/crates/agentkeys-mcp-server/README.md +++ b/crates/agentkeys-mcp-server/README.md @@ -35,7 +35,7 @@ Auto-seeds vendor `magiclick:demo-tok` + three memory namespaces (`travel`, `family`, `profile`) on actor `O_kevin_001`. Walk the three-act storyboard with `bash scripts/mcp-demo-mode-a.sh` (asserts each act's exact wire shape). Full step-by-step walkthrough: -[`docs/spec/plans/issue-107-mcp-demo-runbook.md`](../../docs/spec/plans/issue-107-mcp-demo-runbook.md). +[`docs/plan/issue-107-mcp-demo-runbook.md`](../../docs/plan/issue-107-mcp-demo-runbook.md). ### Local (HTTP, against a real broker / workers) @@ -72,7 +72,7 @@ cargo run -p agentkeys-mcp-server -- \ Test it locally without a real cloud account: `bash scripts/mcp-demo-mode-d-xiaozhi-endpoint.sh` spins up a mock relay that mirrors `xinnan-tech/mcp-endpoint-server`'s routing exactly, then drives every act through it. Full runbook in -[`docs/spec/plans/issue-107-mcp-demo-runbook.md`](../../docs/spec/plans/issue-107-mcp-demo-runbook.md) §B. +[`docs/plan/issue-107-mcp-demo-runbook.md`](../../docs/plan/issue-107-mcp-demo-runbook.md) §B. ### Docker @@ -198,5 +198,5 @@ Coverage: - Vendor onboarding portal — M2 (#114) - Volcano Ark marketplace registration — M2 -See [`docs/spec/plans/issue-107-mcp-server-phase1.md`](../../docs/spec/plans/issue-107-mcp-server-phase1.md) +See [`docs/archived/issue-107-mcp-server-phase1.md`](../../docs/archived/issue-107-mcp-server-phase1.md) for the full plan + follow-ups. diff --git a/crates/agentkeys-mcp-server/src/tools/stubs.rs b/crates/agentkeys-mcp-server/src/tools/stubs.rs index 4746309d..08244f55 100644 --- a/crates/agentkeys-mcp-server/src/tools/stubs.rs +++ b/crates/agentkeys-mcp-server/src/tools/stubs.rs @@ -10,7 +10,7 @@ use crate::errors::McpError; pub const SPEC_URL: &str = - "https://github.com/litentry/agentKeys/blob/main/docs/spec/plans/milestones-roadmap.md#m4"; + "https://github.com/litentry/agentKeys/blob/main/docs/plan/milestones-roadmap.md#m4"; pub fn not_implemented_v1() -> McpError { McpError::NotImplementedV1 { diff --git a/docs/agent-iam-strategy.md b/docs/agent-iam-strategy.md index a9cf4ccb..a658cf8b 100644 --- a/docs/agent-iam-strategy.md +++ b/docs/agent-iam-strategy.md @@ -7,7 +7,7 @@ **Companion docs**: - [`ai-hardware-companion-office-hours.md`](./research/ai-hardware-companion-office-hours.md) — original wedge brainstorm (positioning is updated by this doc) - [`xiaozhi-hermes-architecture.md`](./research/xiaozhi-hermes-architecture.md), [`volcano-ark-mcp-integration.md`](./research/volcano-ark-mcp-integration.md), [`tuya-vs-xiaozhi.md`](./research/tuya-vs-xiaozhi.md) — tactical adapter architectures (unchanged by this doc) -- [issue #103 plan](./spec/plans/issue-103-aiosandbox-hermes-esp32-demo.md) — Phase 1 execution (scope is updated by this doc) +- [issue #103 plan](./plan/issue-103-aiosandbox-hermes-esp32-demo.md) — Phase 1 execution (scope is updated by this doc) --- @@ -240,7 +240,7 @@ A corollary of §3.6: if hooks are the IAM-guarantee delivery mechanism, *who wr - **Manual** — user runs both `agentkeys …` and the runtime's own setup wizard, then hand-edits `~/./config.` to register AgentKeys hooks. Two-wizard friction. Demo "surprise" effect diluted because the user already configured the runtime. - **Automatic** — AgentKeys CLI writes the hook scripts + the `hooks:` block + the runtime's LLM-provider config in one idempotent command. One wizard. Strong demo surprise. Higher maintenance burden (track each runtime's config schema; nightly drift check needed). -**Decision (2026-05-28): hybrid.** Detailed in [`docs/spec/plans/phase-1-fresh-user-wire-onboarding.md`](./spec/plans/phase-1-fresh-user-wire-onboarding.md): +**Decision (2026-05-28): hybrid.** Detailed in [`docs/plan/phase-1-fresh-user-wire-onboarding.md`](./plan/phase-1-fresh-user-wire-onboarding.md): | AgentKeys owns | Runtime owns | |---|---| @@ -330,7 +330,7 @@ The demo runs on MagicLick 2.5 (xiaozhi-esp32 v1.9.4, unchanged) + stock xinnan- | Deliverable | What it is | Why it matters | |---|---|---| | AgentKeys MCP server | 7 active tools wrapping existing backend RPCs | The integration surface vendors plug into | -| **`agentkeys wire ` CLI** (per §3.7) | Hybrid auto-provisioning — writes IAM-gate config + LLM-provider config into a Task Host's config files; idempotent; tracked in [`docs/spec/plans/phase-1-fresh-user-wire-onboarding.md`](./spec/plans/phase-1-fresh-user-wire-onboarding.md) | The user-facing entry point that turns "AgentKeys is wired into the runtime" into one command. The fresh-user "surprise" moment depends on this. | +| **`agentkeys wire ` CLI** (per §3.7) | Hybrid auto-provisioning — writes IAM-gate config + LLM-provider config into a Task Host's config files; idempotent; tracked in [`docs/plan/phase-1-fresh-user-wire-onboarding.md`](./plan/phase-1-fresh-user-wire-onboarding.md) | The user-facing entry point that turns "AgentKeys is wired into the runtime" into one command. The fresh-user "surprise" moment depends on this. | | Hermes adapter (Phase 1.a) | First runtime adapter for `wire`; lives in `crates/agentkeys-cli/src/wire/adapters/hermes.rs` | Validates the hybrid auto-provisioning shape against a real Task Host inside aiosandbox | | `agentkeys hook check / audit / memory-inject` CLI helpers | The thin wrappers the dropped hook scripts call — translate host stdin/stdout JSON to AgentKeys MCP tool calls | Makes the hook scripts trivial (single `exec` line); bug fixes ship in the AgentKeys binary, not in the user's filesystem | | Parent-control web UI (mobile-responsive) | One page: actor list, scope toggles, revoke buttons, audit feed | The face of "Agent IAM" — without this, Act 3 isn't a demo | @@ -495,7 +495,7 @@ Privacy is a benefit, not a category. "Privacy product" is crowded (Brave, DuckD |---|---| | [`ai-hardware-companion-office-hours.md`](./research/ai-hardware-companion-office-hours.md) | Update positioning note at top to point at this strategy doc + add Agent IAM framing + three-narrative reality. Substance below the banner stays. | | [`ai-hardware-companion-wedge.md`](./research/ai-hardware-companion-wedge.md) | Update positioning sections — sharper "Agent IAM" framing; keep market sizing + competitive analysis as-is. | -| [issue #103 plan](./spec/plans/issue-103-aiosandbox-hermes-esp32-demo.md) | Pivot demo storyboard to the three-act IAM demo per §4.3. Add parent-control web UI deliverable. Note the four corrections (bounded revocation, two-tier audit, delegation-as-preview, zero orchestration). Implementation detail unchanged (cap-token machinery already exists). | +| [issue #103 plan](./plan/issue-103-aiosandbox-hermes-esp32-demo.md) | Pivot demo storyboard to the three-act IAM demo per §4.3. Add parent-control web UI deliverable. Note the four corrections (bounded revocation, two-tier audit, delegation-as-preview, zero orchestration). Implementation detail unchanged (cap-token machinery already exists). | | [`xiaozhi-hermes-architecture.md`](./research/xiaozhi-hermes-architecture.md) | No change — MCP-direct pivot still correct. | | [`volcano-ark-mcp-integration.md`](./research/volcano-ark-mcp-integration.md) | Minor: clarify Phase 2 timing per §5 above; tool inventory unchanged. | | [`tuya-vs-xiaozhi.md`](./research/tuya-vs-xiaozhi.md) | No change — complement-not-compete framing still correct. | diff --git a/docs/arch.md b/docs/arch.md index 94f2ea5d..50ebdc82 100644 --- a/docs/arch.md +++ b/docs/arch.md @@ -15,9 +15,9 @@ This doc supersedes the pre-v2 architecture revision (which described a single-b - [`signer-protocol.md`](spec/signer-protocol.md) — typed RPC over mTLS to the signer - [`threat-model-key-custody.md`](spec/threat-model-key-custody.md) — retroactive-confidentiality + key custody position - [`credential-backend-interface.md`](spec/credential-backend-interface.md) — `CredentialBackend` trait surface (now backed by the sidecar) -- [`spec/plans/v2-issues/issue-v2-stage-1-foundation.md`](spec/plans/v2-issues/issue-v2-stage-1-foundation.md) — stage 1 deliverable inventory (shipped) -- [`spec/plans/v2-issues/issue-v2-stage-2-hardening.md`](spec/plans/v2-issues/issue-v2-stage-2-hardening.md) — stage 2 deliverable inventory (shipped) -- [`spec/plans/v2-issues/issue-payment-service-deferred.md`](spec/plans/v2-issues/issue-payment-service-deferred.md) — payment-service design (shipped per modes P-1/P-2/P-3) +- [`plan/v2-issues/issue-v2-stage-1-foundation.md`](plan/v2-issues/issue-v2-stage-1-foundation.md) — stage 1 deliverable inventory (shipped) +- [`plan/v2-issues/issue-v2-stage-2-hardening.md`](plan/v2-issues/issue-v2-stage-2-hardening.md) — stage 2 deliverable inventory (shipped) +- [`plan/v2-issues/issue-payment-service-deferred.md`](plan/v2-issues/issue-payment-service-deferred.md) — payment-service design (shipped per modes P-1/P-2/P-3) --- @@ -199,7 +199,7 @@ flowchart TB Pinned to disambiguate the same value showing up under different labels across components. **Use the canonical column** in every new doc, runbook, CLI output, and commit message; the alias column lists every spelling that exists today so a reader chasing one of them can find their way back. Per `CLAUDE.md` → "Terminology-source-of-truth rule", if you introduce a name not in this table, either add the alias row here or rename the call site to match the canonical name in the same change. -> **Deployed addresses** for every contract named here (per chain — Heima mainnet v2 set, the ERC-4337 master infra #164, historical v1) live in [`contracts.md`](contracts.md), the canonical address registry. Mirrored to `scripts/operator-workstation.env` for tooling. +> **Deployed addresses** for every contract named here (per chain — Heima mainnet v2 set, the ERC-4337 master infra #164, historical v1) plus the prod/test EVM deployer wallets live in [`spec/deployed-contracts.md`](spec/deployed-contracts.md), the canonical address registry. Mirrored to `scripts/operator-workstation.env` for tooling. | Canonical name | Identity | Aliases seen in the codebase / docs | |---|---|---| @@ -2057,7 +2057,7 @@ Task Host runtimes (Claude Code, Codex, Hermes, OpenClaw) fire lifecycle hooks ( Tier-1 coverage means one reference script bundle ports across four hosts with thin shims. Issue #133 is the canonical track: ship reference hook configs + `agentkeys hook check` CLI helper + cap-mint pre-warming for sub-50ms p99 latency. -**Operator-facing delivery: `agentkeys wire `** (per [`docs/agent-iam-strategy.md`](agent-iam-strategy.md) §3.7). The reference hook configs from #133 are not hand-installed by users. AgentKeys ships a single CLI command — `agentkeys wire hermes`, `agentkeys wire claude-code`, etc. — that idempotently writes the hook scripts (under `~/./agent-hooks/`), appends the `hooks:` block to the runtime's config, pre-approves first-use consent, fetches the LLM API key from the credential broker, and verifies via the runtime's own `hooks doctor` equivalent. Output follows the CLAUDE.md `ok proceeding / skip / fail ` convention; re-runs are no-ops modulo drift. Per-runtime adapter trait lives in `crates/agentkeys-cli/src/wire/adapters/`. Full plan: [`docs/spec/plans/phase-1-fresh-user-wire-onboarding.md`](spec/plans/phase-1-fresh-user-wire-onboarding.md). +**Operator-facing delivery: `agentkeys wire `** (per [`docs/agent-iam-strategy.md`](agent-iam-strategy.md) §3.7). The reference hook configs from #133 are not hand-installed by users. AgentKeys ships a single CLI command — `agentkeys wire hermes`, `agentkeys wire claude-code`, etc. — that idempotently writes the hook scripts (under `~/./agent-hooks/`), appends the `hooks:` block to the runtime's config, pre-approves first-use consent, fetches the LLM API key from the credential broker, and verifies via the runtime's own `hooks doctor` equivalent. Output follows the CLAUDE.md `ok proceeding / skip / fail ` convention; re-runs are no-ops modulo drift. Per-runtime adapter trait lives in `crates/agentkeys-cli/src/wire/adapters/`. Full plan: [`docs/plan/phase-1-fresh-user-wire-onboarding.md`](plan/phase-1-fresh-user-wire-onboarding.md). ### 22d.3 Fallback — OpenAI-compatible proxy (Phase 3b, lower priority) @@ -2223,12 +2223,12 @@ The full bring-up runbook lives in [`scripts/setup-broker-host.sh`](../scripts/s - **Typed signer RPC** — [`signer-protocol.md`](spec/signer-protocol.md) - **K3 threat model + TEE attestation** — [`threat-model-key-custody.md`](spec/threat-model-key-custody.md) - **CredentialBackend trait surface** — [`credential-backend-interface.md`](spec/credential-backend-interface.md) -- **Stage 1 deliverable inventory** — [`spec/plans/v2-issues/issue-v2-stage-1-foundation.md`](spec/plans/v2-issues/issue-v2-stage-1-foundation.md) -- **Stage 2 deliverable inventory** — [`spec/plans/v2-issues/issue-v2-stage-2-hardening.md`](spec/plans/v2-issues/issue-v2-stage-2-hardening.md) -- **Payment-service design** — [`spec/plans/v2-issues/issue-payment-service-deferred.md`](spec/plans/v2-issues/issue-payment-service-deferred.md) +- **Stage 1 deliverable inventory** — [`plan/v2-issues/issue-v2-stage-1-foundation.md`](plan/v2-issues/issue-v2-stage-1-foundation.md) +- **Stage 2 deliverable inventory** — [`plan/v2-issues/issue-v2-stage-2-hardening.md`](plan/v2-issues/issue-v2-stage-2-hardening.md) +- **Payment-service design** — [`plan/v2-issues/issue-payment-service-deferred.md`](plan/v2-issues/issue-payment-service-deferred.md) - **Migration from pre-v2** — [`v2-stage1-migration-and-demo.md`](v2-stage1-migration-and-demo.md) (historical; the migration window closed when stage 1 shipped) - **Operator runbook** — [`scripts/setup-broker-host.sh`](../scripts/setup-broker-host.sh) (idempotent). Historical: [`docs/archived/operator-runbook-stage7-2026-04.md`](archived/operator-runbook-stage7-2026-04.md). -- **Milestone roadmap (M1-M7)** — [`spec/plans/milestones-roadmap.md`](spec/plans/milestones-roadmap.md) +- **Milestone roadmap (M1-M7)** — [`plan/milestones-roadmap.md`](plan/milestones-roadmap.md) - **Cloud-side IAM + DNS + cert** — [`../cloud-setup.md`](cloud-bootstrap.md) - **Per-actor reference (agent role)** — [`wiki/agent-role-and-usage-hdkd-per-agent-omni.md`](wiki/agent-role-and-usage-hdkd-per-agent-omni.md) - **Upstream backend classes (per-upstream design)** — [`wiki/upstream-backend-classes-exercise-vs-distribution.md`](wiki/upstream-backend-classes-exercise-vs-distribution.md) @@ -2259,10 +2259,10 @@ The full bring-up runbook lives in [`scripts/setup-broker-host.sh`](../scripts/s ## 27. What's NOT in this doc -- **Per-endpoint request/response shapes.** Each endpoint surface has its own canonical doc — broker endpoints in `spec/plans/v2-issues/issue-v2-stage-1-foundation.md`; signer in `signer-protocol.md`; workers in per-worker READMEs under each crate. +- **Per-endpoint request/response shapes.** Each endpoint surface has its own canonical doc — broker endpoints in `plan/v2-issues/issue-v2-stage-1-foundation.md`; signer in `signer-protocol.md`; workers in per-worker READMEs under each crate. - **Per-step environment-variable inventory.** That's `operator-runbook.md`. - **Detailed threat model for K3 retroactive confidentiality.** That's `threat-model-key-custody.md`. -- **Stage-by-stage build progression history.** That's `plans/development-stages.md` + `spec/plans/v2-issues/`. +- **Stage-by-stage build progression history.** That's `plans/development-stages.md` + `plan/v2-issues/`. - **MetaMask / Foundry tooling instructions.** Retired in v2 — operators no longer hold local EVM keys unless they want to (`identity_type = evm` is supported but not required). - **v3+ hardening** (per-(user, service) KEK, wrap-and-rewrap, ZK-proven cap minting, threshold-MPC signer, per-operator K3) — tracked separately as v3+ issues. v2 ships the design described here. diff --git a/docs/spec/plans/agent-initiated-pairing-method-a.md b/docs/archived/agent-initiated-pairing-method-a.md similarity index 100% rename from docs/spec/plans/agent-initiated-pairing-method-a.md rename to docs/archived/agent-initiated-pairing-method-a.md diff --git a/docs/spec/plans/design-spec.md b/docs/archived/design-spec.md similarity index 100% rename from docs/spec/plans/design-spec.md rename to docs/archived/design-spec.md diff --git a/docs/spec/plans/eng-review-test-plan.md b/docs/archived/eng-review-test-plan.md similarity index 100% rename from docs/spec/plans/eng-review-test-plan.md rename to docs/archived/eng-review-test-plan.md diff --git a/docs/spec/plans/issue-107-mcp-server-phase1.md b/docs/archived/issue-107-mcp-server-phase1.md similarity index 100% rename from docs/spec/plans/issue-107-mcp-server-phase1.md rename to docs/archived/issue-107-mcp-server-phase1.md diff --git a/docs/spec/plans/issue-144-hdkd-agent-bootstrap.md b/docs/archived/issue-144-hdkd-agent-bootstrap.md similarity index 100% rename from docs/spec/plans/issue-144-hdkd-agent-bootstrap.md rename to docs/archived/issue-144-hdkd-agent-bootstrap.md diff --git a/docs/spec/plans/issue-64/AMBIGUITIES.md b/docs/archived/issue-64/AMBIGUITIES.md similarity index 100% rename from docs/spec/plans/issue-64/AMBIGUITIES.md rename to docs/archived/issue-64/AMBIGUITIES.md diff --git a/docs/spec/plans/issue-64/DECISIONS.md b/docs/archived/issue-64/DECISIONS.md similarity index 100% rename from docs/spec/plans/issue-64/DECISIONS.md rename to docs/archived/issue-64/DECISIONS.md diff --git a/docs/spec/plans/issue-64/PHASE-0-CHECKPOINT.md b/docs/archived/issue-64/PHASE-0-CHECKPOINT.md similarity index 100% rename from docs/spec/plans/issue-64/PHASE-0-CHECKPOINT.md rename to docs/archived/issue-64/PHASE-0-CHECKPOINT.md diff --git a/docs/spec/plans/issue-64/PLAN.md b/docs/archived/issue-64/PLAN.md similarity index 100% rename from docs/spec/plans/issue-64/PLAN.md rename to docs/archived/issue-64/PLAN.md diff --git a/docs/spec/plans/issue-64/V0.1-FOLLOWUPS.md b/docs/archived/issue-64/V0.1-FOLLOWUPS.md similarity index 100% rename from docs/spec/plans/issue-64/V0.1-FOLLOWUPS.md rename to docs/archived/issue-64/V0.1-FOLLOWUPS.md diff --git a/docs/spec/plans/issue-64/codex-phaseA-round1.md b/docs/archived/issue-64/codex-phaseA-round1.md similarity index 100% rename from docs/spec/plans/issue-64/codex-phaseA-round1.md rename to docs/archived/issue-64/codex-phaseA-round1.md diff --git a/docs/spec/plans/issue-64/codex-phaseA-round2.md b/docs/archived/issue-64/codex-phaseA-round2.md similarity index 100% rename from docs/spec/plans/issue-64/codex-phaseA-round2.md rename to docs/archived/issue-64/codex-phaseA-round2.md diff --git a/docs/spec/plans/issue-64/codex-phaseA2-round1.md b/docs/archived/issue-64/codex-phaseA2-round1.md similarity index 100% rename from docs/spec/plans/issue-64/codex-phaseA2-round1.md rename to docs/archived/issue-64/codex-phaseA2-round1.md diff --git a/docs/spec/plans/issue-64/codex-phaseA2-round2.md b/docs/archived/issue-64/codex-phaseA2-round2.md similarity index 100% rename from docs/spec/plans/issue-64/codex-phaseA2-round2.md rename to docs/archived/issue-64/codex-phaseA2-round2.md diff --git a/docs/spec/plans/issue-64/codex-phaseA2-round3.md b/docs/archived/issue-64/codex-phaseA2-round3.md similarity index 100% rename from docs/spec/plans/issue-64/codex-phaseA2-round3.md rename to docs/archived/issue-64/codex-phaseA2-round3.md diff --git a/docs/spec/plans/issue-64/codex-round1.md b/docs/archived/issue-64/codex-round1.md similarity index 100% rename from docs/spec/plans/issue-64/codex-round1.md rename to docs/archived/issue-64/codex-round1.md diff --git a/docs/spec/plans/issue-64/codex-round2.md b/docs/archived/issue-64/codex-round2.md similarity index 100% rename from docs/spec/plans/issue-64/codex-round2.md rename to docs/archived/issue-64/codex-round2.md diff --git a/docs/spec/plans/issue-64/prd.json b/docs/archived/issue-64/prd.json similarity index 100% rename from docs/spec/plans/issue-64/prd.json rename to docs/archived/issue-64/prd.json diff --git a/docs/spec/plans/issue-74-dev-key-service-plan.md b/docs/archived/issue-74-dev-key-service-plan.md similarity index 100% rename from docs/spec/plans/issue-74-dev-key-service-plan.md rename to docs/archived/issue-74-dev-key-service-plan.md diff --git a/docs/contracts.md b/docs/contracts.md index 1c89e9b5..9d3bed51 100644 --- a/docs/contracts.md +++ b/docs/contracts.md @@ -1,72 +1,5 @@ -# Deployed contracts — canonical registry +# Deployed contracts — moved -**Single source of truth** for every on-chain contract address AgentKeys has deployed, per chain. Answers "what's the live address of `SidecarRegistry` / the ERC-4337 `EntryPoint` on Heima mainnet right now?" +The canonical deployed-contract registry now lives at **[`docs/spec/deployed-contracts.md`](spec/deployed-contracts.md)** — single source for every on-chain address across chains plus the prod/test EVM deployer wallets, indexed from [`arch.md`](arch.md) §5. -Mirrored into [`scripts/operator-workstation.env`](../scripts/operator-workstation.env) (the shell-consumable form, written by `scripts/heima-bring-up.sh` step 6 via `env_set`). When the two diverge, **this doc is authoritative for human reads, the env file for tooling**; the bring-up script keeps both in sync. Indexed from [`arch.md`](arch.md) §5. - ---- - -## Heima mainnet (chain_id = 212013) - -### v2 stage-1 set (current live) - -| Contract | Address | Bytecode | -|---|---|---| -| `AgentKeysScope` | `0xd44b375daefc65768f417d0f0125b68d5ba7df3b` | 4572 bytes | -| `SidecarRegistry` | `0x1Ac62f1C2D828476a5D784e850a700dC1f17e0bE` | 4572 bytes | -| `K3EpochCounter` | `0x6c9e675c699a06acefbc156afdee6bfbfe32ccb3` | 591 bytes | -| `CredentialAudit` | `0x63c4545ac01c77cc74044f25b8edea3880224577` | 3043 bytes | -| `P256Verifier` | `0xda5b772f9d6c09abe80414eea908612df9b54749` | (pre-deployed verifier) | -| `K11Verifier` | `0x5a441431f08e0f5f5ed10659620cb4e0e814e627` | (pre-deployed verifier) | - -### ERC-4337 master infra (#164, deployed 2026-06-02) - -Foundation plumbing for the P-256 smart-account master ([plan](plan/chain/erc4337-master-account.md)). **NOT yet the live master-auth:** the registry/scope cutover to account-authorization (#164 E3/E7) is a later coordinated redeploy; these are inert until masters are registered as accounts. - -| Contract | Address | Notes | -|---|---|---| -| `EntryPoint` (ERC-4337 v0.7) | `0x6672E1b315332167aBA12E0B1d3532a7e9B1ADE9` | canonical eth-infinitism v0.7 bytecode; landed a UserOp end-to-end in the spike | -| `P256AccountFactory` | `0x1ccCe65b22De81aDA4F378FeAf7503d93f5d27a3` | CREATE2 factory; `constructor(entryPoint, k11Verifier)`; wired to the live `K11Verifier`; mainnet CREATE2 determinism smoke-verified | - -### Historical v1 deploy (superseded by v2; preserved for old-tx cross-reference) - -| Contract | Address | Bytecode | -|---|---|---| -| `AgentKeysScope` | `0x14C23B5D1cE20c094af643a20e6b0972dAD12aa8` | 3146 bytes | -| `SidecarRegistry` | `0x76D574a107727bE87fc1422661A030FEFda70786` | 3301 bytes | -| `K3EpochCounter` | `0x8396dEc50ff755d6DE7728DABB00Be2eFBCdf4dF` | 687 bytes | -| `CredentialAudit` | `0x1801ded1a4FBD8c9224Ab18B9EcbB293B8674c06` | 1421 bytes | - -## Heima Paseo testnet (chain_id = 2013) - -Halted (block 2,905,430 frozen since 2026-01-15). **No contracts deployed** — the `*_ADDRESS_HEIMA_PASEO` entries in `operator-workstation.env` are placeholders (`0x..01`–`0x..04`). When collators return: `AGENTKEYS_CHAIN=heima-paseo bash harness/v2-stage1-demo.sh --only-step 9` deploys + auto-funds via Alice sudo; update this doc with the live testnet addresses then. - ---- - -## Deploy metadata (Heima mainnet v2) - -- Deployer wallet (EVM): `0xdE644936D5B7d5d42032fd08bbA42Fbbfd6663Bc` -- Deployer wallet (Substrate SS58 prefix 31): `47NGSq6JE5ZSnymGNa4nFVjWbsuhTfoSKN2jtpk28mUyC1M3` *(see [funding the EVM side via the Substrate twin](../scripts/evm-to-substrate-address.mjs))* -- v2 deploy date: 2026-05-19 · #164 E1 deploy date: 2026-06-02 -- Compiler: Solc 0.8.20, `evm_version = "london"` (a `forge script` header-validation workaround, NOT Heima's EVM level — Heima executes **Cancun**; see CLAUDE.md "Heima EVM compatibility level"). The EntryPoint v0.7 is the canonical eth-infinitism bytecode, deployed via `forge create`. -- Deploy script: [`crates/agentkeys-chain/script/DeployAgentKeysV1.s.sol`](../crates/agentkeys-chain/script/DeployAgentKeysV1.s.sol) - -**Constructor wiring** (verified post-deploy): -- `AgentKeysScope.registry()` = the v2 `SidecarRegistry` ✓ -- `P256AccountFactory.entryPoint()` = the v0.7 `EntryPoint` ✓, `.k11Verifier()` = the live `K11Verifier` ✓ -- `K3EpochCounter.currentEpoch()` = `1`; `.signerGovernance()` = deployer (to be transferred to an M-of-N multisig) -- `SidecarRegistry.ROLE_CAP_MINT()` = `1`, `ROLE_RECOVERY()` = `2`, `ROLE_SCOPE_MGMT()` = `4` ✓ - -## Verifying contracts are live (read-only RPC, zero gas) - -```bash -# One-shot health check across the v2 set: -AGENTKEYS_CHAIN=heima bash scripts/verify-heima-contracts.sh # exits 0 on all-pass - -# Bytecode presence (eth_getCode), e.g. the ERC-4337 EntryPoint: -cast code 0x6672E1b315332167aBA12E0B1d3532a7e9B1ADE9 --rpc-url https://rpc.heima-parachain.heima.network | head -c 12 -# View call, e.g. factory wiring: -cast call 0x1ccCe65b22De81aDA4F378FeAf7503d93f5d27a3 "entryPoint()(address)" --rpc-url https://rpc.heima-parachain.heima.network -``` - -**Explorer note:** [`heima.statescan.io`](https://heima.statescan.io/) is Substrate-side — it indexes pallet extrinsics/events but does NOT decode EVM calls/bytecode. EVM contract verification on Heima goes via direct RPC until agentkeys-specific indexing on Litentry's `subscan-essentials` fork ships (arch.md §22a.6). +This file is kept only as a redirect so links added in #171 still resolve. Do not add addresses here — edit [`docs/spec/deployed-contracts.md`](spec/deployed-contracts.md). diff --git a/docs/dev-setup.md b/docs/dev-setup.md index 57f05e3c..fcf49ec8 100644 --- a/docs/dev-setup.md +++ b/docs/dev-setup.md @@ -249,11 +249,11 @@ The stage-done script is the authoritative evaluator — never self-grade. If it Providers add, remove, and reorder signup steps. When a deterministic scraper breaks, diagnose with the `/agentkeys-workflow-collection` skill — it drives a real Chrome session via `chrome-devtools-mcp` to produce a diff-ready transcript. That transcript is what feeds back into the scraper's pattern library. -The longer-term plan (Stage 5b → folded into M2 vendor wedge) is to detect drift automatically from telemetry and hand MCP-capable callers a fallback that their own LLM can drive — details in [`spec/plans/milestones-roadmap.md`](./spec/plans/milestones-roadmap.md) § M2. +The longer-term plan (Stage 5b → folded into M2 vendor wedge) is to detect drift automatically from telemetry and hand MCP-capable callers a fallback that their own LLM can drive — details in [`plan/milestones-roadmap.md`](./plan/milestones-roadmap.md) § M2. ## 10. Further reading -- [`spec/plans/milestones-roadmap.md`](./spec/plans/milestones-roadmap.md) — M1-M7 roadmap (replaces the archived v1/v2 stage plan) +- [`plan/milestones-roadmap.md`](./plan/milestones-roadmap.md) — M1-M7 roadmap (replaces the archived v1/v2 stage plan) - [`cloud-bootstrap.md`](./cloud-bootstrap.md) — one-time AWS infra (DNS, SES, S3, IAM, OIDC federation) - [`../scripts/setup-broker-host.sh`](../scripts/setup-broker-host.sh) — idempotent broker bring-up + supervise + rotate - [`spec/credential-backend-interface.md`](./spec/credential-backend-interface.md) — 15-method trait contract diff --git a/docs/operator-runbook-wire.md b/docs/operator-runbook-wire.md index abdfb3f5..9b750525 100644 --- a/docs/operator-runbook-wire.md +++ b/docs/operator-runbook-wire.md @@ -11,7 +11,7 @@ reads only its permitted memory, is deterministically denied an over-cap action > **hooks** into Hermes's config so the LLM cannot bypass `permission.check` / > `audit.append` / memory injection. Background: [`docs/agent-iam-strategy.md`](agent-iam-strategy.md) > §3.6–3.7, [`docs/arch.md`](arch.md) §22d, [`docs/wiki/agent-iam-guarantee-glossary.md`](wiki/agent-iam-guarantee-glossary.md). -> Full action table + automation decisions: [`docs/spec/plans/phase1-wire-harness-test-plan.md`](spec/plans/phase1-wire-harness-test-plan.md). +> Full action table + automation decisions: [`docs/plan/phase1-wire-harness-test-plan.md`](plan/phase1-wire-harness-test-plan.md). ## TL;DR — pick a mode and run one command @@ -208,7 +208,7 @@ key signs anything. `ok …` / `fail …` per step. **Prereqs:** `cast` (Foundry) on PATH; the deployer key (`~/.agentkeys/heima-deployer.key` — funds the deposit + gas); Python 3 (the script auto-provisions a `cryptography` venv at `~/.agentkeys/erc4337-venv`). The live EntryPoint + factory addresses are in -[`docs/contracts.md`](contracts.md). **Append-only:** each run mints a fresh account +[`docs/spec/deployed-contracts.md`](spec/deployed-contracts.md). **Append-only:** each run mints a fresh account (it is NOT idempotent in the resource sense). The bundler is not required — the demo calls `EntryPoint.handleOps` directly. Full design + cutover status: [`docs/plan/chain/erc4337-master-account.md`](plan/chain/erc4337-master-account.md). @@ -371,7 +371,7 @@ echo '{"tool_name":"x"}' | agentkeys hook audit ## Cross-references - [`harness/phase1-wire-demo.sh`](../harness/phase1-wire-demo.sh) — the harness this runbook drives -- [`docs/spec/plans/phase1-wire-harness-test-plan.md`](spec/plans/phase1-wire-harness-test-plan.md) — the action table + automation decisions +- [`docs/plan/phase1-wire-harness-test-plan.md`](plan/phase1-wire-harness-test-plan.md) — the action table + automation decisions - [`docs/agent-iam-strategy.md`](agent-iam-strategy.md) §3.6/§3.7/§4.3 · [`docs/arch.md`](arch.md) §22d · [`docs/wiki/agent-iam-guarantee-glossary.md`](wiki/agent-iam-guarantee-glossary.md) - [Issue #133](https://github.com/litentry/agentKeys/issues/133) — multi-runtime hook reference configs (Phase 1.b) - [Issue #152](https://github.com/litentry/agentKeys/issues/152) — **scope:** this runbook covers the **Local-LLM / Task-agent** path only (stdio MCP server built + run *in the sandbox*). The **Hosted-LLM** path (xiaozhi / vendor-cloud — a broker-hosted `mcp-endpoint` the remote LLM connects *into*, per arch.md §22c.2 / §22d.3) is deferred to #152. diff --git a/docs/plan/README.md b/docs/plan/README.md index 8500cfb5..b6f66cf1 100644 --- a/docs/plan/README.md +++ b/docs/plan/README.md @@ -13,7 +13,27 @@ Plain markdown. No YAML frontmatter. Link to repo files with `../../` and See the `agentkeys-docs` skill for the full layout policy. +## Canonical roadmap + runbook + +These two are the live source-of-truth pointers referenced from [`../arch.md`](../arch.md) and `CLAUDE.md`. Keep them current; don't archive. + +- [`milestones-roadmap.md`](milestones-roadmap.md) — the M1–M7 milestone roadmap (replaces the archived v1/v2 staged plan). +- [`execution-plan.md`](execution-plan.md) — orchestration runbook (ralph, team, ultraqa workflows). + ## Active plans - [`agentkeys-memory-design.md`](agentkeys-memory-design.md) — memory worker design (single file). -- [`web-flow/`](web-flow/) — parent-control web UI operator user flow. Multi-file. Binds harness v2-stage {1,2,3} flows to UI screens with real inputs (no mock data). Start at [`web-flow/README.md`](web-flow/README.md). +- [`ceo-plan.md`](ceo-plan.md) — v0 product approach (Minimal Viable Tool). Foundational vision; largely superseded by `milestones-roadmap.md` for sequencing — keep for the DX/mock-backend contract framing. +- [`issue-103-aiosandbox-hermes-esp32-demo.md`](issue-103-aiosandbox-hermes-esp32-demo.md) — M1 ESP32 demo tracking doc. **Partially superseded:** sections C4/C5/C6 are stale (architecture moved to Hermes + MCP + hooks); the forward path is `phase-1-fresh-user-wire-onboarding.md`. +- [`issue-107-mcp-demo-runbook.md`](issue-107-mcp-demo-runbook.md) — two-mode MCP demo runbook (light in-memory / real broker). +- [`issue-74-step-1c-device-key-auth.md`](issue-74-step-1c-device-key-auth.md) — v1c device-key auth (HDKD per-agent omni + WebAuthn-uniform binding). +- [`issue-82-erc7730-v2-aligned.md`](issue-82-erc7730-v2-aligned.md) — ERC-7730 signing-display + intent-aware audit (M3/M4). +- [`issue-credential-storage-s3-oidc.md`](issue-credential-storage-s3-oidc.md) — S3-backed AES-256-GCM credential store replacing the mock-server `/credential/*` endpoints. +- [`phase-1-fresh-user-wire-onboarding.md`](phase-1-fresh-user-wire-onboarding.md) — fresh-user `agentkeys wire ` onboarding journey to the Agent IAM "surprise". +- [`phase1-wire-harness-test-plan.md`](phase1-wire-harness-test-plan.md) — two-mode test plan for the wire harness. + +## Multi-file plan directories + +- [`chain/`](chain/) — ERC-4337 P-256 smart-account master ([`chain/erc4337-master-account.md`](chain/erc4337-master-account.md) + [`chain/erc4337-threat-model.md`](chain/erc4337-threat-model.md)). +- [`web-flow/`](web-flow/) — parent-control web UI operator user flow. Binds harness v2-stage {1,2,3} flows to UI screens with real inputs (no mock data). Start at [`web-flow/README.md`](web-flow/README.md). +- [`v2-issues/`](v2-issues/) — v2 architecture roadmap issues (sovereign sidecar + on-chain scope/registry, multi-master recovery, deferred payment service). Future GitHub issues, not yet filed. diff --git a/docs/spec/plans/ceo-plan.md b/docs/plan/ceo-plan.md similarity index 99% rename from docs/spec/plans/ceo-plan.md rename to docs/plan/ceo-plan.md index 9284b8f7..8c2e0d81 100644 --- a/docs/spec/plans/ceo-plan.md +++ b/docs/plan/ceo-plan.md @@ -4,7 +4,7 @@ status: ACTIVE # CEO Plan: AgentKeys — Autonomous Agent Credential Platform Generated by /plan-ceo-review on 2026-04-08 -Revised 2026-04-09 against [`../1-step-analysis.md`](../1-step-analysis.md) §3.3c (Round 13 runtime reality check) and [`../../research/aiosandbox/agent-infra-sandbox-runtime-probe.md`](../../research/aiosandbox/agent-infra-sandbox-runtime-probe.md). +Revised 2026-04-09 against [`../1-step-analysis.md`](../spec/1-step-analysis.md) §3.3c (Round 13 runtime reality check) and [`../../research/aiosandbox/agent-infra-sandbox-runtime-probe.md`](../research/aiosandbox/agent-infra-sandbox-runtime-probe.md). Branch: main | Mode: SELECTIVE EXPANSION Repo: hanwencheng/project-life @@ -135,7 +135,7 @@ Recover is the same primitive as Pair — it just carries a different `AuthReque **Identity linking ties into Heima's identity graph.** `pallet-omni-account` already supports linking multiple identities to one account (email, phone, social handles, ENS names). AgentKeys reuses this: `agentkeys link` writes a new identity-link entry for the agent's wallet address. The backend's `open_auth_request(Recover, {human_readable_id})` resolves the link via the same graph. No new infrastructure — just a new use of an existing Heima capability. -**Scope change, high-value release, key rotation** — all route through the same primitive with `AuthRequestType::ScopeChange`, `HighValueRelease`, `KeyRotate`. One mechanism, many uses. Full type list in [`../credential-backend-interface.md`](../credential-backend-interface.md). +**Scope change, high-value release, key rotation** — all route through the same primitive with `AuthRequestType::ScopeChange`, `HighValueRelease`, `KeyRotate`. One mechanism, many uses. Full type list in [`../credential-backend-interface.md`](../spec/credential-backend-interface.md). - `agentkeys store agent-A openrouter ` → manually store a credential scoped to agent-A (the 1Password-like flow, primary CLI demo for humans) - Agent-driven provisioning (separate demo, via MCP not CLI): an agent with browser control (e.g., OpenClaw) calls `agentkeys.provision(service: "openrouter")` via MCP → daemon's provisioner orchestrator spawns Playwright → browser automation creates real OpenRouter account → API key encrypted to mock shielding key → stored in mock backend. The agent does this autonomously — the human doesn't run a CLI command for provisioning. diff --git a/docs/plan/chain/erc4337-master-account.md b/docs/plan/chain/erc4337-master-account.md index ec20e42d..547a1bf2 100644 --- a/docs/plan/chain/erc4337-master-account.md +++ b/docs/plan/chain/erc4337-master-account.md @@ -79,7 +79,7 @@ Each phase is independently shippable, idempotent where it mutates chain state ( - **E0** ✅ threat-model drafted → [`erc4337-threat-model.md`](erc4337-threat-model.md). - **E2** ✅ `IERC4337.sol`, `P256Account.sol`, `P256AccountFactory.sol` — **codex-reviewed** (1 P2 fixed: verifier/`abi.decode` reverts now map to `SIG_VALIDATION_FAILED` via a try/catch self-call); **17 account tests green**. -- **E1** ✅ **deployed live on Heima mainnet 2026-06-02** (recorded in [`contracts.md`](../../contracts.md)): +- **E1** ✅ **deployed live on Heima mainnet 2026-06-02** (recorded in [`deployed-contracts.md`](../../spec/deployed-contracts.md)): - `EntryPoint` v0.7 = `0x6672E1b315332167aBA12E0B1d3532a7e9B1ADE9` (canonical bytecode; landed a UserOp in the spike). - `P256AccountFactory` = `0x1ccCe65b22De81aDA4F378FeAf7503d93f5d27a3` (CREATE2 determinism smoke-verified on mainnet: `getAddress` == `createAccount`). - **E3** ✅ `AgentKeysScope` thinned to account-auth (in-contract K11 + `scopeNonce` retired; `setScopeWithWebauthn`→`setScope`); registry agent-bind closed structurally (master = account). diff --git a/docs/spec/plans/execution-plan.md b/docs/plan/execution-plan.md similarity index 97% rename from docs/spec/plans/execution-plan.md rename to docs/plan/execution-plan.md index 79d8e2a0..7d1a94f0 100644 --- a/docs/spec/plans/execution-plan.md +++ b/docs/plan/execution-plan.md @@ -20,9 +20,9 @@ cd ~/Projects/agentkeys git init # Copy spec docs so agents have them without leaving the repo -mkdir -p docs/spec/plans docs/research/aiosandbox +mkdir -p docs/plan docs/research/aiosandbox cp ~/Projects/project-life/projects/idea/agentkeys/v2/*.md docs/spec/ -cp ~/Projects/project-life/projects/idea/agentkeys/v2/plans/*.md docs/spec/plans/ +cp ~/Projects/project-life/projects/idea/agentkeys/v2/plans/*.md docs/plan/ cp ~/Projects/project-life/projects/idea/agentkeys/v2/aiosandbox/*.md docs/research/aiosandbox/ git add -A && git commit -m "docs: seed spec documents from project-life" @@ -47,7 +47,7 @@ The largest stage: 37 tests, 10 stories. Ralph loops through them. **Invoke:** ``` -/oh-my-claudecode:ralph "Implement Stage 1 per docs/spec/plans/development-stages.md: agentkeys-mock-server (axum + rusqlite) with 7 SQLite tables, 15 REST endpoints implementing every CredentialBackend method, identity linking, master key custody, TTL/single-use enforcement, MockHttpClient connection. 37 tests must pass. See docs/spec/plans/eng-review-test-plan.md for the full test matrix including property tests (pair-code collision, nonce uniqueness) and integrity tests (tamper detection, OTP replay). Tag stage-1-done when done." +/oh-my-claudecode:ralph "Implement Stage 1 per docs/spec/plans/development-stages.md: agentkeys-mock-server (axum + rusqlite) with 7 SQLite tables, 15 REST endpoints implementing every CredentialBackend method, identity linking, master key custody, TTL/single-use enforcement, MockHttpClient connection. 37 tests must pass. See docs/archived/eng-review-test-plan.md for the full test matrix including property tests (pair-code collision, nonce uniqueness) and integrity tests (tamper detection, OTP replay). Tag stage-1-done when done." ``` **Deliverables:** Mock server starts on port 8090, all 37 tests pass, curl smoke test works, `bash harness/stage-1-done.sh` exits 0. diff --git a/docs/spec/plans/issue-103-aiosandbox-hermes-esp32-demo.md b/docs/plan/issue-103-aiosandbox-hermes-esp32-demo.md similarity index 87% rename from docs/spec/plans/issue-103-aiosandbox-hermes-esp32-demo.md rename to docs/plan/issue-103-aiosandbox-hermes-esp32-demo.md index e851b716..2ec6d028 100644 --- a/docs/spec/plans/issue-103-aiosandbox-hermes-esp32-demo.md +++ b/docs/plan/issue-103-aiosandbox-hermes-esp32-demo.md @@ -8,20 +8,20 @@ > > The integration architecture is **Option B** (vendor surface → Task Host runtime → both MCPs: aiosandbox loopback + AgentKeys over network), with **hooks as the primary IAM-guarantee mechanism** and the OpenAI-compatible proxy as a **lower-priority fallback** for hosts without a hook surface. > -> Full reasoning and the IAM-tool-vs-IAM-guarantee distinction live in [`docs/wiki/agent-iam-guarantee-glossary.md`](../../wiki/agent-iam-guarantee-glossary.md); strategic anchor in [`docs/agent-iam-strategy.md`](../../agent-iam-strategy.md) §3.6 + §3.7; execution plan in [`docs/spec/plans/phase-1-fresh-user-wire-onboarding.md`](phase-1-fresh-user-wire-onboarding.md). The previous Rust-runtime runbook + verification + setup script were archived 2026-05-28 under `docs/archived/*-rust-runtime-2026-05*`. +> Full reasoning and the IAM-tool-vs-IAM-guarantee distinction live in [`docs/wiki/agent-iam-guarantee-glossary.md`](../wiki/agent-iam-guarantee-glossary.md); strategic anchor in [`docs/agent-iam-strategy.md`](../agent-iam-strategy.md) §3.6 + §3.7; execution plan in [`docs/plan/phase-1-fresh-user-wire-onboarding.md`](phase-1-fresh-user-wire-onboarding.md). The previous Rust-runtime runbook + verification + setup script were archived 2026-05-28 under `docs/archived/*-rust-runtime-2026-05*`. > > Phase split: > - **Phase 1** (this PR + immediate follow-up): AgentKeys MCP server (7 tools per strategy §4.2), Hermes MCP registration inside aiosandbox. > - **Phase 3** ([issue #133](https://github.com/litentry/agentKeys/issues/133)): reference hook configs for Tier-1 hosts (Claude Code, Codex, Hermes, OpenClaw), `agentkeys hook check` CLI helper, cap-mint pre-warming. > - **Phase 3b** (after #133 ships): proxy fallback for Tier-2 hosts (xiaozhi-server, vendor mobile SDKs, plain `openai.ChatCompletion` scripts). > -> ## ⚠ PIVOT 2026-05-24 (multiple rounds) — read strategic anchor FIRST: [`docs/agent-iam-strategy.md`](../../agent-iam-strategy.md) +> ## ⚠ PIVOT 2026-05-24 (multiple rounds) — read strategic anchor FIRST: [`docs/agent-iam-strategy.md`](../agent-iam-strategy.md) > > **Strategic frame**: AgentKeys is the **Agent IAM and memory control plane** for the AI device era. This issue ships Phase 1 from the strategy doc — a three-act demo that proves AgentKeys is Agent IAM, not chatbot infrastructure. > -> **Hardware** (verified): MagicLick 2.5 (ESP32-S3 + ES8311 + 128×128 LCD + WiFi/4G) running xiaozhi-esp32 v1.9.4. See [`docs/research/xiaozhi-esp32-magiclink.md`](../../research/xiaozhi-esp32-magiclink.md). +> **Hardware** (verified): MagicLick 2.5 (ESP32-S3 + ES8311 + 128×128 LCD + WiFi/4G) running xiaozhi-esp32 v1.9.4. See [`docs/research/xiaozhi-esp32-magiclink.md`](../research/xiaozhi-esp32-magiclink.md). > -> **Architecture** (MCP-direct, NOT Hermes-bridge): xiaozhi-server has first-class MCP support (`core/providers/tools/server_mcp/`). We register the AgentKeys MCP server in `mcp_server_settings.json`; the LLM (Qwen/Kimi/Doubao/Claude) calls our tools directly. No fork, no Hermes middleman. Hermes joins Phase 3 as a callable MCP tool (`hermes.execute_task`) the LLM can invoke for complex agentic work — not as the LLM-caller replacement. See [`docs/research/xiaozhi-hermes-architecture.md`](../../research/xiaozhi-hermes-architecture.md). +> **Architecture** (MCP-direct, NOT Hermes-bridge): xiaozhi-server has first-class MCP support (`core/providers/tools/server_mcp/`). We register the AgentKeys MCP server in `mcp_server_settings.json`; the LLM (Qwen/Kimi/Doubao/Claude) calls our tools directly. No fork, no Hermes middleman. Hermes joins Phase 3 as a callable MCP tool (`hermes.execute_task`) the LLM can invoke for complex agentic work — not as the LLM-caller replacement. See [`docs/research/xiaozhi-hermes-architecture.md`](../research/xiaozhi-hermes-architecture.md). > > **Phase 1 demo (three acts)** — replaces the single-act memory injection demo described below. Goal: <5-minute vendor pitch that reads as Agent IAM, not chatbot. > - **Act 1 — Permissioned Memory**: device reads ONLY the memory namespace it's allowed to read (not "the device knows you" — "the device knows what it's allowed to know about you") @@ -30,13 +30,13 @@ > > **Four architecture commitments** (corrected from earlier loose framing): > 1. **Revocation**: *immediate online, bounded TTL/cache offline*. Not "no propagation delay." High-risk actions always online; low-risk reads use short-lived cached caps; offline mode denies sensitive actions by default. -> 2. **Audit (two-tier)**: real-time off-chain feed in parent-control UI + **2-min batched Merkle root anchored on-chain** (chain choice is deployment config; the strategy stays chain-agnostic per [`agent-iam-strategy.md`](../../agent-iam-strategy.md) §3.2). NOT real-time on-chain. The chain explorer is tamper-evidence proof, not the UX surface. +> 2. **Audit (two-tier)**: real-time off-chain feed in parent-control UI + **2-min batched Merkle root anchored on-chain** (chain choice is deployment config; the strategy stays chain-agnostic per [`agent-iam-strategy.md`](../agent-iam-strategy.md) §3.2). NOT real-time on-chain. The chain explorer is tamper-evidence proof, not the UX surface. > 3. **Delegation**: `agentkeys.delegation.grant` is **schema-documented but not active** in v1. Returns `not_implemented_in_v1`. Active delegation lands in Phase 4. > 4. **Zero orchestration in v1** — hard line. If a vendor needs orchestration, they pick a runtime (Hermes/OpenClaw/their own) via Phase 3 MCP tools. > > **What's NEW vs what's shipped**: cap-token machinery (broker, signer, K3/K10 HDKD, memory/cred/audit workers, per-actor isolation per issue #90) is already shipped via Stage 7+. New work for Phase 1: MCP server wrapper around existing backend RPCs (~1 week), parent-control web UI (mobile-responsive, ~3-4 days), two-tier audit wiring (~1 day), demo runbook (~half day). Total ~2 weeks. > -> **Sections below**: §C3 (mock memory + daemon endpoint) still useful as backend context. §C4 (custom Hermes runtime as Rust crate) is **SUPERSEDED** — use the AgentKeys MCP server pattern from [`docs/research/volcano-ark-mcp-integration.md`](../../research/volcano-ark-mcp-integration.md). §C5 (Dockerfile with hermes-runtime) is **SUPERSEDED**. §C6 (custom ESP32 firmware) **SUPERSEDED for MagicLick demo** — firmware is unchanged. §C7 (deploy script) needs rework to provision the MCP server + xiaozhi-server stock + parent web UI instead of the bridge. The "Implementation order" and "Effort estimate" sections below reflect the older bridge-fork plan and should be read as historical context, not current spec. +> **Sections below**: §C3 (mock memory + daemon endpoint) still useful as backend context. §C4 (custom Hermes runtime as Rust crate) is **SUPERSEDED** — use the AgentKeys MCP server pattern from [`docs/research/volcano-ark-mcp-integration.md`](../research/volcano-ark-mcp-integration.md). §C5 (Dockerfile with hermes-runtime) is **SUPERSEDED**. §C6 (custom ESP32 firmware) **SUPERSEDED for MagicLick demo** — firmware is unchanged. §C7 (deploy script) needs rework to provision the MCP server + xiaozhi-server stock + parent web UI instead of the bridge. The "Implementation order" and "Effort estimate" sections below reflect the older bridge-fork plan and should be read as historical context, not current spec. > > **What this means for the original plan sections:** > - §C3 (mock memory + daemon endpoint) — **STILL VALID**, no changes @@ -46,12 +46,12 @@ > - §C7 (deploy script) — **PARTIALLY VALID**. Update to provision the bridge instead of a custom hermes-runtime. > - §Implementation order — **SUPERSEDED** by the 6-step "Specific next steps" list in the research doc. > -> Full rationale, hardware specs, communication protocols, four candidate reference server implementations, and hardware verification procedures live in [`docs/research/xiaozhi-esp32-magiclink.md`](../../research/xiaozhi-esp32-magiclink.md). A follow-up commit will rewrite the C-sections below to match the pivoted direction. Until then, read the research doc as the source of truth. +> Full rationale, hardware specs, communication protocols, four candidate reference server implementations, and hardware verification procedures live in [`docs/research/xiaozhi-esp32-magiclink.md`](../research/xiaozhi-esp32-magiclink.md). A follow-up commit will rewrite the C-sections below to match the pivoted direction. Until then, read the research doc as the source of truth. **Related research:** -- [`docs/research/aiosandbox/agent-infra-sandbox-analysis.md`](../../research/aiosandbox/agent-infra-sandbox-analysis.md) -- [`docs/research/aiosandbox/agent-infra-sandbox-runtime-probe.md`](../../research/aiosandbox/agent-infra-sandbox-runtime-probe.md) -- [`docs/research/ai-hardware-companion-office-hours.md`](../../research/ai-hardware-companion-office-hours.md) (Approach D) -- [`docs/arch.md`](../../arch.md) (agent-infra/sandbox is the canonical agent runtime; memory-service at `bots//memory/*`) +- [`docs/research/aiosandbox/agent-infra-sandbox-analysis.md`](../research/aiosandbox/agent-infra-sandbox-analysis.md) +- [`docs/research/aiosandbox/agent-infra-sandbox-runtime-probe.md`](../research/aiosandbox/agent-infra-sandbox-runtime-probe.md) +- [`docs/research/ai-hardware-companion-office-hours.md`](../research/ai-hardware-companion-office-hours.md) (Approach D) +- [`docs/arch.md`](../arch.md) (agent-infra/sandbox is the canonical agent runtime; memory-service at `bots//memory/*`) ## Goal @@ -59,7 +59,7 @@ Ship a working end-to-end demo for the AgentKeys hardware-vendor wedge: > An ESP32 hardware device, configured with one URL and one actor token, talks to a cloud-hosted `agent-infra/sandbox` running a Hermes agent runtime + `agentkeys-daemon`. The agent auto-injects a mock user-memory MD file from S3 at boot, so the device sounds personalized from the very first conversation. -This is the v0 buyer-pitch demo that the [office-hours design doc §9.6 Storyboard](../../research/ai-hardware-companion-office-hours.md) calls for, scoped down to **single device, single sandbox, single mock memory blob**. Cross-vendor portability, cap-token enforcement, multi-tenant orchestration, payment rails, and the parent-control app are out of scope for v0 demo. +This is the v0 buyer-pitch demo that the [office-hours design doc §9.6 Storyboard](../research/ai-hardware-companion-office-hours.md) calls for, scoped down to **single device, single sandbox, single mock memory blob**. Cross-vendor portability, cap-token enforcement, multi-tenant orchestration, payment rails, and the parent-control app are out of scope for v0 demo. ## Why now @@ -75,7 +75,7 @@ The office-hours diagnostic surfaced that the next critical step is a working de - Text-mode interaction (button press → text payload → agent → text response → serial-print or BLE-companion-app display); voice mode deferred to a follow-up issue - Subsidized LLM (Qwen-class via DashScope or OpenRouter) for the agent - Public-facing demo URL (`https://demo.aiosandbox.litentry.org` or similar) -- One-command setup script (idempotent per [CLAUDE.md "Idempotent remote-setup rule"](../../../CLAUDE.md)) +- One-command setup script (idempotent per [CLAUDE.md "Idempotent remote-setup rule"](../../CLAUDE.md)) - Demo runbook for live walk-throughs **NOT in scope (deferred to follow-ups):** @@ -139,13 +139,13 @@ The office-hours diagnostic surfaced that the next critical step is a working de └────────────────────────────────────────────┘ ``` -Reuse of canonical AgentKeys primitives ([`docs/arch.md`](../../arch.md)): +Reuse of canonical AgentKeys primitives ([`docs/arch.md`](../arch.md)): - **Sandbox**: `agent-infra/sandbox` is already arch.md's chosen agent runtime substrate (§3.3a, §10.4) - **Actor model**: `O_demo_001` is a fixed HDKD-derived actor omni for v0 demo (single actor; production binds per device) - **Memory bucket layout**: `bots//memory/` matches arch.md §15.2 — we use the same layout with a demo prefix so the path stays canonical - **Daemon**: `agentkeys-daemon` extends with one new GET endpoint `/v1/memory//profile.md`; no new K-key infra needed -- **supervisord**: stock sandbox ships supervisord at PID 1 (per [runtime probe finding 3 in §1](../../research/aiosandbox/agent-infra-sandbox-runtime-probe.md)) — we register `agentkeys-daemon` + `hermes-runtime` as new programs in `/opt/gem/supervisord.conf` +- **supervisord**: stock sandbox ships supervisord at PID 1 (per [runtime probe finding 3 in §1](../research/aiosandbox/agent-infra-sandbox-runtime-probe.md)) — we register `agentkeys-daemon` + `hermes-runtime` as new programs in `/opt/gem/supervisord.conf` ## Components @@ -195,7 +195,7 @@ last_updated: 2026-05-23T10:00:00Z ### C3 — `agentkeys-daemon` new endpoint -Add handler to [`crates/agentkeys-daemon/src/handlers/`](../../../crates/agentkeys-daemon): +Add handler to [`crates/agentkeys-daemon/src/handlers/`](../../crates/agentkeys-daemon): ```rust // GET /v1/memory/{actor_omni}/profile.md @@ -257,7 +257,7 @@ NEW crate at `crates/agentkeys-hermes-runtime/`: Response: {"response": "string", "memory_loaded": true, "tokens_used": N} ``` -**Naming note**: "Hermes" in this issue refers to the lightweight AgentKeys-native runtime we're shipping for this demo, NOT NousResearch's Hermes LLM and NOT an existing third-party project. We picked the name in [office-hours §Approach D](../../research/ai-hardware-companion-office-hours.md). A 1-week research spike (open question §1 below) should confirm whether a public OSS project named "Hermes" already occupies this namespace and we need to rename — best candidates if rename needed: `agentkeys-companion`, `agentkeys-runtime`, `agentkeys-shell`. +**Naming note**: "Hermes" in this issue refers to the lightweight AgentKeys-native runtime we're shipping for this demo, NOT NousResearch's Hermes LLM and NOT an existing third-party project. We picked the name in [office-hours §Approach D](../research/ai-hardware-companion-office-hours.md). A 1-week research spike (open question §1 below) should confirm whether a public OSS project named "Hermes" already occupies this namespace and we need to rename — best candidates if rename needed: `agentkeys-companion`, `agentkeys-runtime`, `agentkeys-shell`. ### C5 — Extended sandbox image @@ -281,7 +281,7 @@ RUN mkdir -p /home/gem/.agentkeys && chown gem:gem /home/gem/.agentkeys EXPOSE 8080 8089 8090 ``` -Supervisord programs (per [runtime probe §4 B10](../../research/aiosandbox/agent-infra-sandbox-runtime-probe.md)): +Supervisord programs (per [runtime probe §4 B10](../research/aiosandbox/agent-infra-sandbox-runtime-probe.md)): ```ini # /opt/gem/supervisord.d/agentkeys-daemon.conf @@ -383,7 +383,7 @@ Token is validated by hermes-runtime against `AGENTKEYS_DEMO_ACTOR_TOKEN` env va NEW: `scripts/setup-demo-aiosandbox.sh` -Idempotent per [CLAUDE.md "Idempotent remote-setup rule"](../../../CLAUDE.md) — every step pre-checks state and short-circuits if already done. +Idempotent per [CLAUDE.md "Idempotent remote-setup rule"](../../CLAUDE.md) — every step pre-checks state and short-circuits if already done. Step inventory: @@ -466,14 +466,14 @@ A reviewer takes the demo runbook, runs `bash scripts/setup-demo-aiosandbox.sh` - Step 12 (runbook): **~2 days** - **Total: ~1-2 weeks for a working v0 demo** (revised 2026-05-24 from original ~3 week estimate) -**The revision happened because** the [risk-verification research](../../research/xiaozhi-hermes-risks.md) showed all three identified risks were either built-in-mitigated (R1: Hermes session headers, 2-4 hrs), mostly-not-real (R2: learning loop is background-off-turn-path), or fine-for-v0 (R3: gateway is multi-tenant by design). A newly discovered fourth risk (R4: cold agent construction per request adds 50-300ms) needs 1 day of fork-local pooling work. Net effect: bridge work ~3-4 days, parallel tracks (AgentKeys daemon endpoint, S3 mock, device config, runbook) ~3-4 days. Calendar time ~1-2 weeks depending on engineer concurrency. +**The revision happened because** the [risk-verification research](../research/xiaozhi-hermes-risks.md) showed all three identified risks were either built-in-mitigated (R1: Hermes session headers, 2-4 hrs), mostly-not-real (R2: learning loop is background-off-turn-path), or fine-for-v0 (R3: gateway is multi-tenant by design). A newly discovered fourth risk (R4: cold agent construction per request adds 50-300ms) needs 1 day of fork-local pooling work. Net effect: bridge work ~3-4 days, parallel tracks (AgentKeys daemon endpoint, S3 mock, device config, runbook) ~3-4 days. Calendar time ~1-2 weeks depending on engineer concurrency. This fits the office-hours §9.7 next-moves timeline: demo ready in 1-2 weeks, vendor outreach happens in parallel (the assignment from §The Assignment). ## What landed (to fill at PR time) -*To be completed by the implementing engineer at PR time per [CLAUDE.md plan-completion policy](../../../CLAUDE.md).* +*To be completed by the implementing engineer at PR time per [CLAUDE.md plan-completion policy](../../CLAUDE.md).* ## What did NOT land (to fill at PR time) -*To be completed by the implementing engineer at PR time per [CLAUDE.md plan-completion policy](../../../CLAUDE.md). If empty, state "All plan steps shipped."* +*To be completed by the implementing engineer at PR time per [CLAUDE.md plan-completion policy](../../CLAUDE.md). If empty, state "All plan steps shipped."* diff --git a/docs/spec/plans/issue-107-mcp-demo-runbook.md b/docs/plan/issue-107-mcp-demo-runbook.md similarity index 96% rename from docs/spec/plans/issue-107-mcp-demo-runbook.md rename to docs/plan/issue-107-mcp-demo-runbook.md index 25843bca..0330bce3 100644 --- a/docs/spec/plans/issue-107-mcp-demo-runbook.md +++ b/docs/plan/issue-107-mcp-demo-runbook.md @@ -23,7 +23,7 @@ That's it. The script builds the binary, allocates an ephemeral port, boots the server with `--backend in-memory`, walks all three acts of the storyboard with JSON-RPC assertions, exercises the auth negative paths, and cleans up. Expected output ends with `ALL ASSERTIONS PASSED.` (19 checks). This is the -same one-liner the CI workflow runs (see [`.github/workflows/mcp-server.yml`](../../../.github/workflows/mcp-server.yml)) — copy-paste-equivalent in CI and on +same one-liner the CI workflow runs (see [`.github/workflows/mcp-server.yml`](../../.github/workflows/mcp-server.yml)) — copy-paste-equivalent in CI and on your laptop. If you want to walk the demo manually instead of running the script, the @@ -115,7 +115,7 @@ Expected `structuredContent`: } ``` -**Why this matters — and what's M1 vs M4:** in this dev demo the MCP server forwards `namespace` to the in-memory backend, which honors it as a storage key. That makes the dev demo visibly namespace-scoped. **In M1 production**, the real memory worker today does NOT enforce `namespace` cryptographically — the wire field flows through but the S3 key derivation only uses `(actor, service)`. Lifting `namespace` into the SIGNED `CapPayload` so the worker can enforce it is M4 follow-up to #108 ([plan §6](issue-107-mcp-server-phase1.md#6-what-did-not-land-deferred)). The dev demo demonstrates the wire shape; cryptographic enforcement lands later. +**Why this matters — and what's M1 vs M4:** in this dev demo the MCP server forwards `namespace` to the in-memory backend, which honors it as a storage key. That makes the dev demo visibly namespace-scoped. **In M1 production**, the real memory worker today does NOT enforce `namespace` cryptographically — the wire field flows through but the S3 key derivation only uses `(actor, service)`. Lifting `namespace` into the SIGNED `CapPayload` so the worker can enforce it is M4 follow-up to #108 ([plan §6](../archived/issue-107-mcp-server-phase1.md#6-what-did-not-land-deferred)). The dev demo demonstrates the wire shape; cryptographic enforcement lands later. ### 4. Act 2 — Deterministic Denial @@ -215,7 +215,7 @@ curl -sS -X POST http://127.0.0.1:8088/mcp \ Expected: 5b succeeds (`"revocation":"in_memory"`), 5c returns a JSON-RPC error with body `unknown cap_id: this-cap-was-never-minted`, 5d returns `{"ok": true, "envelope_hash": "0x<32-byte sha256>"}`. The `envelope_hash` is a SHA-256 over the audit input — two different appends produce two different hashes. -**Why this matters:** revoke + audit are decoupled by design. The dev backend tracks minted nonces and refuses to revoke unknown ones — so a typo or a stale cap surfaces immediately. In M1 production, broker-side revocation is still a follow-up (`cap.revoke` is a graceful stub against the real backend per [plan §6](issue-107-mcp-server-phase1.md#6-what-did-not-land-deferred)); the dev demo shows the contract the broker will honor in M4. +**Why this matters:** revoke + audit are decoupled by design. The dev backend tracks minted nonces and refuses to revoke unknown ones — so a typo or a stale cap surfaces immediately. In M1 production, broker-side revocation is still a follow-up (`cap.revoke` is a graceful stub against the real backend per [plan §6](../archived/issue-107-mcp-server-phase1.md#6-what-did-not-land-deferred)); the dev demo shows the contract the broker will honor in M4. ### 6. Acceptance-criterion #3 — auth negative paths @@ -271,7 +271,7 @@ Expected error body: "data": { "error": "not_implemented_in_v1", "scheduled_for": "M4", - "spec_url": "https://github.com/litentry/agentKeys/blob/main/docs/spec/plans/milestones-roadmap.md#m4" + "spec_url": "https://github.com/litentry/agentKeys/blob/main/docs/plan/milestones-roadmap.md#m4" } }, "id": 1 @@ -405,7 +405,7 @@ AGENTKEYS_CHAIN=heima bash scripts/verify-heima-contracts.sh > reads contract addresses from `scripts/operator-workstation.env` (the > default `$ENV_FILE`). With `AGENTKEYS_CHAIN=heima` it verifies the > **live v2 stage-1 contracts on Heima mainnet** (the addresses in -> [`docs/spec/deployed-contracts.md`](deployed-contracts.md)) — there is no +> [`docs/spec/deployed-contracts.md`](../spec/deployed-contracts.md)) — there is no > separate "test" set of contracts. Demo isolation is per-actor (fresh > `operator_omni` / `actor_omni` / `device_key_hash` per run, cap-mint > enforces device binding on chain). For an off-prod env file (e.g. a @@ -423,7 +423,7 @@ Capture for the next step: ### B.5 Deploy the MCP server on the broker (hosted-LLM path — issue #152, deferred) -> **Moved.** The broker-hosted MCP endpoint is the **Hosted-LLM** path (a remote vendor LLM connects *inward* over WSS) — tracked in [#152](https://github.com/litentry/agentKeys/issues/152) and **deferred**. It is a broker-host concern, so it no longer lives in `setup-cloud.sh` (which is IAM/permission-only). The old `setup-cloud.sh --only-step 15` SSM-ran `setup-mcp-host.sh`, cloning `main` and cold-building via `cargo install --git` (~10–20 min EVERY run). Enable it on the broker with [`setup-mcp-host.sh`](../../../scripts/setup-mcp-host.sh) (cached incremental `cargo build -p` against the checkout); thereafter `setup-broker-host.sh` re-converges it automatically — **no flag to remember**: +> **Moved.** The broker-hosted MCP endpoint is the **Hosted-LLM** path (a remote vendor LLM connects *inward* over WSS) — tracked in [#152](https://github.com/litentry/agentKeys/issues/152) and **deferred**. It is a broker-host concern, so it no longer lives in `setup-cloud.sh` (which is IAM/permission-only). The old `setup-cloud.sh --only-step 15` SSM-ran `setup-mcp-host.sh`, cloning `main` and cold-building via `cargo install --git` (~10–20 min EVERY run). Enable it on the broker with [`setup-mcp-host.sh`](../../scripts/setup-mcp-host.sh) (cached incremental `cargo build -p` against the checkout); thereafter `setup-broker-host.sh` re-converges it automatically — **no flag to remember**: ```bash # On the broker (reach it via scripts/ssh-broker.sh), from the /opt/agentkeys-src checkout: @@ -431,7 +431,7 @@ sudo bash /opt/agentkeys-src/scripts/setup-mcp-host.sh # prod → mc sudo bash /opt/agentkeys-src/scripts/setup-mcp-host.sh --test # test → test-mcp.${ZONE} ``` -Once the MCP binary is installed, every `setup-broker-host.sh` run keeps it converged (idempotent), so routine broker setups need nothing extra. **The Local-LLM / Task-agent wire demo does NOT need this** — that MCP server runs in the agent's own sandbox (see [`docs/operator-runbook-wire.md`](../../operator-runbook-wire.md) + `harness/phase1-wire-demo.sh`). +Once the MCP binary is installed, every `setup-broker-host.sh` run keeps it converged (idempotent), so routine broker setups need nothing extra. **The Local-LLM / Task-agent wire demo does NOT need this** — that MCP server runs in the agent's own sandbox (see [`docs/operator-runbook-wire.md`](../operator-runbook-wire.md) + `harness/phase1-wire-demo.sh`). **Local development install (laptop / Claude Code / Codex CLI / Claude Desktop):** @@ -670,7 +670,7 @@ sudo systemctl disable --now agentkeys-mcp-server mcp-endpoint-server ## See also -- [`docs/spec/plans/issue-107-mcp-server-phase1.md`](issue-107-mcp-server-phase1.md) — the canonical plan + landed-vs-deferred table for #107. -- [`docs/agent-iam-strategy.md`](../../agent-iam-strategy.md) §4.3 — the three-act demo storyboard. -- [`docs/research/xiaozhi-hermes-architecture.md`](../../research/xiaozhi-hermes-architecture.md) — why xiaozhi-server's stock MCP support means no fork needed. -- [`crates/agentkeys-mcp-server/README.md`](../../../crates/agentkeys-mcp-server/README.md) — server-side ops reference. +- [`docs/archived/issue-107-mcp-server-phase1.md`](../archived/issue-107-mcp-server-phase1.md) — the canonical plan + landed-vs-deferred table for #107. +- [`docs/agent-iam-strategy.md`](../agent-iam-strategy.md) §4.3 — the three-act demo storyboard. +- [`docs/research/xiaozhi-hermes-architecture.md`](../research/xiaozhi-hermes-architecture.md) — why xiaozhi-server's stock MCP support means no fork needed. +- [`crates/agentkeys-mcp-server/README.md`](../../crates/agentkeys-mcp-server/README.md) — server-side ops reference. diff --git a/docs/spec/plans/issue-74-step-1c-device-key-auth.md b/docs/plan/issue-74-step-1c-device-key-auth.md similarity index 98% rename from docs/spec/plans/issue-74-step-1c-device-key-auth.md rename to docs/plan/issue-74-step-1c-device-key-auth.md index 98161e13..9127226a 100644 --- a/docs/spec/plans/issue-74-step-1c-device-key-auth.md +++ b/docs/plan/issue-74-step-1c-device-key-auth.md @@ -27,7 +27,7 @@ collapse: Q7 email-account-compromise → device-takeover gap by requiring hardware-attested user presence at re-bind time. -[`docs/arch.md`](../../arch.md) §4 (HDKD actor +[`docs/arch.md`](../arch.md) §4 (HDKD actor tree), §4a (mental model), and §5a (per-actor binding ceremonies) are the **single source of truth** for the v0.2 target. The per-identity-type sections in this plan are the v1c wire-shape @@ -39,7 +39,7 @@ lets a Linux box act as a master without a built-in platform authenticator) is deferred — see [issue #79](https://github.com/litentry/agentKeys/issues/79). The agent-role/usage operator reference lives at -[`docs/wiki/agent-role-and-usage-hdkd-per-agent-omni.md`](../../../docs/wiki/agent-role-and-usage-hdkd-per-agent-omni.md). +[`docs/wiki/agent-role-and-usage-hdkd-per-agent-omni.md`](../wiki/agent-role-and-usage-hdkd-per-agent-omni.md). ## Goal @@ -177,7 +177,7 @@ listener / DNS / nginx work. > describe the **v1c-interim** bespoke PoP shapes. The v0.2 target > collapses these into a uniform WebAuthn binding ceremony for > masters plus a uniform link-code binding ceremony for agents — -> see [`architecture.md` §5a.1](../../arch.md). The +> see [`architecture.md` §5a.1](../arch.md). The > identity-source half (email click / OAuth callback / EVM SIWE > identity verification) survives unchanged in v0.2; only the > device-pubkey-commit half collapses. @@ -427,7 +427,7 @@ Step 1c is **strictly stronger** than all three Heima variants: timestamp window is ±60s. - **Device key persistence on a fresh sandbox VM.** **RESOLVED** (Q8) — - decision recorded in [`architecture.md` §5a.4](../../arch.md). + decision recorded in [`architecture.md` §5a.4](../arch.md). Stock `agent-infra/sandbox` does not expose the host's OS keychain; `keyring-rs` falls back to a file-backend at `~/.agentkeys/daemon-/session.json` (mode 0600), which diff --git a/docs/spec/plans/issue-82-erc7730-v2-aligned.md b/docs/plan/issue-82-erc7730-v2-aligned.md similarity index 99% rename from docs/spec/plans/issue-82-erc7730-v2-aligned.md rename to docs/plan/issue-82-erc7730-v2-aligned.md index 1da8e177..a7b0626b 100644 --- a/docs/spec/plans/issue-82-erc7730-v2-aligned.md +++ b/docs/plan/issue-82-erc7730-v2-aligned.md @@ -20,7 +20,7 @@ This plan re-targets all four phases against v2 surfaces. **It also adds K11-bin ## Phase 1 — EIP-712 typed-data signing -**Wire shape** (extends [`signer-protocol.md`](../signer-protocol.md)): +**Wire shape** (extends [`signer-protocol.md`](../spec/signer-protocol.md)): ``` POST /dev/sign-typed-data diff --git a/docs/spec/plans/issue-credential-storage-s3-oidc.md b/docs/plan/issue-credential-storage-s3-oidc.md similarity index 93% rename from docs/spec/plans/issue-credential-storage-s3-oidc.md rename to docs/plan/issue-credential-storage-s3-oidc.md index ceefda0f..f3738335 100644 --- a/docs/spec/plans/issue-credential-storage-s3-oidc.md +++ b/docs/plan/issue-credential-storage-s3-oidc.md @@ -6,18 +6,18 @@ _Draft body for a new GitHub issue on `litentry/agentKeys`. Filed via:_ gh issue create --repo litentry/agentKeys \ --title "Replace mock-server /credential/* with S3-backed encrypted storage (OIDC-scoped, PrincipalTag-isolated)" \ --label "stage-7+,architecture,credential-storage" \ - --body-file docs/spec/plans/issue-credential-storage-s3-oidc.md + --body-file docs/plan/issue-credential-storage-s3-oidc.md ``` --- ## Context -[arch.md §9 #10](../../docs/arch.md#L608) flags the mock-server backend (`agentkeys-backend.service` on `127.0.0.1:8090` on the deployed broker host) as **legacy and pending deprecation**: +[arch.md §9 #10](../arch.md#L608) flags the mock-server backend (`agentkeys-backend.service` on `127.0.0.1:8090` on the deployed broker host) as **legacy and pending deprecation**: > Backend (mock-server) — Legacy `/session/*` + `/credential/*` + `/audit/*` (broker's Tier-2 reachability target; **will be deprecated as callers migrate to the new flow**) -[arch.md §11](../../docs/arch.md#L670) explicitly forbids exposing this backend publicly: +[arch.md §11](../arch.md#L670) explicitly forbids exposing this backend publicly: > The legacy backend at `:8090` is **never** publicly exposed; only the broker on the same host reaches it. @@ -99,4 +99,4 @@ Extend the existing bucket policy (already grants PrincipalTag-scoped read on `b - Forced by [issue #83](https://github.com/litentry/agentKeys/issues/83) follow-up: the auto-provision pipeline now succeeds through key mint but fails at storage because the legacy backend isn't reachable. - Reuses infra from [SES routing Lambda](../../infra/ses-routing-lambda/) (issue #83 follow-up). -- See [arch.md §9 #10](../../docs/arch.md#L608), [§11](../../docs/arch.md#L636), [cloud-setup.md §4.5](../../docs/cloud-setup.md). +- See [arch.md §9 #10](../arch.md#L608), [§11](../arch.md#L636), [cloud-setup.md §4.5](../../docs/cloud-setup.md). diff --git a/docs/spec/plans/milestones-roadmap.md b/docs/plan/milestones-roadmap.md similarity index 80% rename from docs/spec/plans/milestones-roadmap.md rename to docs/plan/milestones-roadmap.md index 39c88502..8e01aa25 100644 --- a/docs/spec/plans/milestones-roadmap.md +++ b/docs/plan/milestones-roadmap.md @@ -2,9 +2,9 @@ **Status**: source of truth for milestone-level work after the v2-stage1/2/3 demo lands. **Date**: 2026-05-24. -**Companion to**: [`docs/arch.md`](../../arch.md) (architecture invariants), [`docs/agent-iam-strategy.md`](../../agent-iam-strategy.md) (positioning + risks + corrections). +**Companion to**: [`docs/arch.md`](../arch.md) (architecture invariants), [`docs/agent-iam-strategy.md`](../agent-iam-strategy.md) (positioning + risks + corrections). -This file replaces the v1/v2 staged development-stages.md plan (now archived at [`docs/archived/development-stages-v2-2026-04.md`](../../archived/development-stages-v2-2026-04.md)). Once v2-stage3 ships green, the v1/v2 naming retires entirely. Future work is tracked under the seven milestones below, plus a "beyond M7" horizon. +This file replaces the v1/v2 staged development-stages.md plan (now archived at [`docs/archived/development-stages-v2-2026-04.md`](../archived/development-stages-v2-2026-04.md)). Once v2-stage3 ships green, the v1/v2 naming retires entirely. Future work is tracked under the seven milestones below, plus a "beyond M7" horizon. --- @@ -12,7 +12,7 @@ This file replaces the v1/v2 staged development-stages.md plan (now archived at AgentKeys is the **Authority Host** for the AI device era — the cross-vendor identity + memory + permissions + audit layer that lives outside any one agent runtime. We are not a chatbot. We are not an orchestrator. We are the IAM that holds when a hardware vendor's stack changes underneath. The product surface evolves from a three-act demo (M1) → a paid vendor pilot (M2) → cross-runtime neutrality (M3) → production-grade capability + revocation depth (M4) → consumer mobile surface (M5) → TEE-rooted security (M6) → standards adoption (M7). Each milestone earns the right to the next by deploying a working reference implementation before chasing the next ambition. -The category we own is **Agent IAM** — Identity, Memory, Permissions, capability-token Authority, Audit, Delegation, Revocation. Memory is **one of** these surfaces, not the headline. The competition is Auth0/Okta for agents, not Mem0 for chatbots. See [`agent-iam-strategy.md` §2.2](../../agent-iam-strategy.md) for the full positioning. +The category we own is **Agent IAM** — Identity, Memory, Permissions, capability-token Authority, Audit, Delegation, Revocation. Memory is **one of** these surfaces, not the headline. The competition is Auth0/Okta for agents, not Mem0 for chatbots. See [`agent-iam-strategy.md` §2.2](../agent-iam-strategy.md) for the full positioning. --- @@ -22,10 +22,10 @@ Already shipped, persisted for historical context: - `agentkeys-broker-server` — OIDC issuer + cap-token mint + audit - `agentkeys-signer` — TEE-isolatable signer with HDKD per-actor derivation -- `agentkeys-worker-creds` + `agentkeys-worker-memory` + `agentkeys-worker-audit` — per-data-class isolation enforced at four layers (broker cap-mint, worker chain-verify, AWS PrincipalTag, per-data-class bucket separation) per [arch.md §17](../../arch.md) -- HDKD identity tree (K1–K11 key inventory per [arch.md §4](../../arch.md)) -- v2-stage1/2/3 demo orchestrators in [`harness/`](../../../harness/) prove the end-to-end Heima EVM backbone + per-actor isolation -- Project board automation (this `pm/` folder; see [`pm/PROJECT-DASHBOARD-GUIDE.md`](../../../pm/PROJECT-DASHBOARD-GUIDE.md)) +- `agentkeys-worker-creds` + `agentkeys-worker-memory` + `agentkeys-worker-audit` — per-data-class isolation enforced at four layers (broker cap-mint, worker chain-verify, AWS PrincipalTag, per-data-class bucket separation) per [arch.md §17](../arch.md) +- HDKD identity tree (K1–K11 key inventory per [arch.md §4](../arch.md)) +- v2-stage1/2/3 demo orchestrators in [`harness/`](../../harness/) prove the end-to-end Heima EVM backbone + per-actor isolation +- Project board automation (this `pm/` folder; see [`pm/PROJECT-DASHBOARD-GUIDE.md`](../../pm/PROJECT-DASHBOARD-GUIDE.md)) What this gives us going into M1: a working backend, deployed signer + broker on the broker host, audited isolation, deterministic field schemas on the project board. The v2 staging name retires after v2-stage3 ships green; future work refers to milestones, not stages. @@ -33,21 +33,21 @@ What this gives us going into M1: a working backend, deployed signer + broker on ## 2. M1 — Agent IAM v0 demo (0–2 weeks) -**Goal**: a hardware vendor watches a 5-minute demo and understands "this is the IAM for AI devices, not another chatbot platform." Anchored to [`agent-iam-strategy.md` §4](../../agent-iam-strategy.md). +**Goal**: a hardware vendor watches a 5-minute demo and understands "this is the IAM for AI devices, not another chatbot platform." Anchored to [`agent-iam-strategy.md` §4](../agent-iam-strategy.md). ### Scope - **MagicLick 2.5 hardware** (ESP32-S3 + ES8311 + 128×128 LCD + WiFi/4G) running the upstream [xiaozhi-esp32](https://github.com/78/xiaozhi-esp32) firmware with no AgentKeys-side fork. Xiaozhi-server's first-class MCP support means we register one MCP server in its `mcp_server_settings.json` — no Hermes-as-bridge fork needed. - **AgentKeys MCP server** (issue #107) exposing 7 active tools (`identity.whoami`, `memory.get`, `memory.put`, `permission.check`, `cap.mint`, `cap.revoke`, `audit.append`) + 3 schema-preview tools (`delegation.grant`, `delegation.revoke`, `approval.request` — return `not_implemented_in_v1`). -- **Memory namespace model** (issue #108) — v0 defaults `personal / family / work / travel`. Wire-format `namespace` field on memory put/get + cap-token `namespaces_allowed` claim. Per [`agent-iam-strategy.md` §3.5](../../agent-iam-strategy.md). -- **Two-tier audit** (issue #109) — real-time off-chain feed for the parent UI; 2-minute Merkle-batched on-chain anchor for tamper-evidence. Chain-agnostic. Per [`agent-iam-strategy.md` §3.2](../../agent-iam-strategy.md). -- **Bounded revocation** (issue #110) — immediate online, ≤60-second offline via cap-token TTL. Per [`agent-iam-strategy.md` §3.1](../../agent-iam-strategy.md). +- **Memory namespace model** (issue #108) — v0 defaults `personal / family / work / travel`. Wire-format `namespace` field on memory put/get + cap-token `namespaces_allowed` claim. Per [`agent-iam-strategy.md` §3.5](../agent-iam-strategy.md). +- **Two-tier audit** (issue #109) — real-time off-chain feed for the parent UI; 2-minute Merkle-batched on-chain anchor for tamper-evidence. Chain-agnostic. Per [`agent-iam-strategy.md` §3.2](../agent-iam-strategy.md). +- **Bounded revocation** (issue #110) — immediate online, ≤60-second offline via cap-token TTL. Per [`agent-iam-strategy.md` §3.1](../agent-iam-strategy.md). - **Parent-control web UI** (issue #111) — mobile-responsive, three columns: actor list / scope toggles per namespace / real-time audit feed. Native app deferred to M5. -- **Three-act demo storyboard**: (1) permissioned memory recall demonstrating namespace isolation; (2) deterministic denial of an out-of-scope action; (3) parent revokes a scope live and the device's next attempt fails. Per [`agent-iam-strategy.md` §4.3](../../agent-iam-strategy.md). +- **Three-act demo storyboard**: (1) permissioned memory recall demonstrating namespace isolation; (2) deterministic denial of an out-of-scope action; (3) parent revokes a scope live and the device's next attempt fails. Per [`agent-iam-strategy.md` §4.3](../agent-iam-strategy.md). ### Hard exclusions -Per [`agent-iam-strategy.md` §2.4 + §4.5](../../agent-iam-strategy.md): no orchestration, no active delegation (schema only), no approval workflows, no native mobile app, no real-time on-chain audit, no vendor onboarding portal, no second-rail integration (Volcano Ark Phase 2). +Per [`agent-iam-strategy.md` §2.4 + §4.5](../agent-iam-strategy.md): no orchestration, no active delegation (schema only), no approval workflows, no native mobile app, no real-time on-chain audit, no vendor onboarding portal, no second-rail integration (Volcano Ark Phase 2). ### M1 done when @@ -83,7 +83,7 @@ Per [`agent-iam-strategy.md` §2.4 + §4.5](../../agent-iam-strategy.md): no orc ### M2 kill criterion -Per [`agent-iam-strategy.md` §C12](../../agent-iam-strategy.md): 0 paid pilots from 3 priority vendors in 6 months → pivot to MCP credential broker for consumer agent apps. +Per [`agent-iam-strategy.md` §C12](../agent-iam-strategy.md): 0 paid pilots from 3 priority vendors in 6 months → pivot to MCP credential broker for consumer agent apps. --- @@ -94,7 +94,7 @@ Per [`agent-iam-strategy.md` §C12](../../agent-iam-strategy.md): 0 paid pilots ### Scope - **Hermes-MCP wrapper** (issue #117) — NousResearch [hermes-agent](https://github.com/nousresearch/hermes-agent) exposed as an MCP server: `hermes.execute_task(task, context, constraints)` returns `{result, steps_taken, cost_usd, audit_trail_id}`. Hermes calls AgentKeys MCP tools internally (recursive composition). -- **OpenClaw-MCP wrapper** (issue #118) — Tencent OpenClaw same shape as Hermes (commercial ToS verified per [`agent-iam-strategy.md` §9.5](../../agent-iam-strategy.md)). +- **OpenClaw-MCP wrapper** (issue #118) — Tencent OpenClaw same shape as Hermes (commercial ToS verified per [`agent-iam-strategy.md` §9.5](../agent-iam-strategy.md)). - **Doubao agent compatibility** — already exercised via M2's Volcano Ark registration; M3 hardens the integration to production. - **Claude Code / Codex CLI compatibility** — these are coding agents (different use case from the consumer demo) but proving cross-runtime IAM works for developer-tier agents widens the moat. - **Python SDK + TypeScript SDK** for non-MCP integration paths. @@ -116,7 +116,7 @@ Per the May session's "agent-as-MCP-tool, NOT LLM-caller-replacement" call: agen ### Scope -- **Delegation chains in production** — parent agent → child agent with scope narrowing, TTL inheritance, revocation cascade, audit chain. Per [`agent-iam-strategy.md` §3.3](../../agent-iam-strategy.md) corrected design: delegation is implicit in cap-tokens by default; explicit delegation activates only after vendor proves M2-tier traction. +- **Delegation chains in production** — parent agent → child agent with scope narrowing, TTL inheritance, revocation cascade, audit chain. Per [`agent-iam-strategy.md` §3.3](../agent-iam-strategy.md) corrected design: delegation is implicit in cap-tokens by default; explicit delegation activates only after vendor proves M2-tier traction. - **Approval workflows** — high-risk actions (payment > threshold, cross-namespace memory grant, scope expansion) push to the parent app for one-tap approval before execution. Replaces deterministic-denial as the path for "I trust this agent but want eyes on this specific request." - **Policy versioning** — vendors deploy new policies; existing devices upgrade with explicit audit trail showing the diff. - **Audit replay** — regulator-grade reconstruction of any agent's authority history from the on-chain anchor + off-chain feed. First-class regulator API. @@ -145,7 +145,7 @@ Per the May session's "agent-as-MCP-tool, NOT LLM-caller-replacement" call: agen ### Why this is M5 not M1 -Per [`agent-iam-strategy.md` §6 Risk 3](../../agent-iam-strategy.md): native mobile is expensive and slow to iterate. The v0 web UI is sufficient to prove the UX premise; native ships only after a paying vendor pilot has signed and consumer demand is demonstrated. +Per [`agent-iam-strategy.md` §6 Risk 3](../agent-iam-strategy.md): native mobile is expensive and slow to iterate. The v0 web UI is sufficient to prove the UX premise; native ships only after a paying vendor pilot has signed and consumer demand is demonstrated. ### M5 done when @@ -160,11 +160,11 @@ Per [`agent-iam-strategy.md` §6 Risk 3](../../agent-iam-strategy.md): native mo ### Scope -- **K3 (MSK) inside TEE** — Master Sealing Key only readable by the TEE-attested signer process. Per [`arch.md` §4 K3 row](../../arch.md). +- **K3 (MSK) inside TEE** — Master Sealing Key only readable by the TEE-attested signer process. Per [`arch.md` §4 K3 row](../arch.md). - **K10 / K11 device-key hardening** — WebAuthn enrollment ceremony at the TEE attestation boundary. Stage-1 K11 enrollment audit-row format finalized. - **Key rotation depth** — K3 epoch rotation in production (currently shipped as scaffolding); K1 broker key rotation; K2 OIDC key rotation. Each documented as a ceremony in arch.md §10. - **Sealed key migration** — operator switches the broker host's TEE and migrates K3 with a sealed-blob transfer ceremony (Phase 6 from earlier roadmap; deferred from M5 because pre-M4 we don't yet have enough deployed TEEs to justify the ceremony complexity). -- **Threat model deepening** — adversarial review per [`docs/spec/threat-model-key-custody.md`](../threat-model-key-custody.md). External pentest pass + remediation. +- **Threat model deepening** — adversarial review per [`docs/spec/threat-model-key-custody.md`](../spec/threat-model-key-custody.md). External pentest pass + remediation. ### M6 done when @@ -181,9 +181,9 @@ Per [`agent-iam-strategy.md` §6 Risk 3](../../agent-iam-strategy.md): native mo ### Scope - **Propose MCP extensions** for IAM-grade auth headers (session keys, cap-token forwarding, audit-chain headers). -- **OAuth-for-Agents specification engagement** — likely IETF or W3C working group. Lead the spec discussion with deployed reference code, not slide decks. Per [`agent-iam-strategy.md` §6 Risk 5](../../agent-iam-strategy.md): premature standards engagement looks like vendor lobbying; standards work is post-12-months. +- **OAuth-for-Agents specification engagement** — likely IETF or W3C working group. Lead the spec discussion with deployed reference code, not slide decks. Per [`agent-iam-strategy.md` §6 Risk 5](../agent-iam-strategy.md): premature standards engagement looks like vendor lobbying; standards work is post-12-months. - **Reference implementations for non-MCP runtimes** — raw HTTP / gRPC clients for vendors that don't use MCP. -- **Brand-owner partnerships at scale** — Tuya (built in M2), Xiaomi (per [`tuya-vs-xiaozhi.md` Phase 3c "deferred"](../../research/tuya-vs-xiaozhi.md)), Alibaba Smart Home (per Phase 3b "partnership-gated"), Samsung SmartThings. +- **Brand-owner partnerships at scale** — Tuya (built in M2), Xiaomi (per [`tuya-vs-xiaozhi.md` Phase 3c "deferred"](../research/tuya-vs-xiaozhi.md)), Alibaba Smart Home (per Phase 3b "partnership-gated"), Samsung SmartThings. - **Open-source SDK ecosystem** — MIT-licensed SDK + MCP server. Community contributions, third-party integrations, hackathon presence. ### M7 done when @@ -204,7 +204,7 @@ If MCP becomes the de-facto AI integration protocol (current trajectory looks li ### 9.2 Multi-region + multi-chain neutrality -Production deployments across multiple regions (US / EU / APAC) and multiple chain backbones (Heima default; Base / Ethereum / Polygon / chain-X for vendor preference). Per [`arch.md` §22 (chain-pluggable design)](../../arch.md) the architecture supports this today; M-beyond is the actual deployment. +Production deployments across multiple regions (US / EU / APAC) and multiple chain backbones (Heima default; Base / Ethereum / Polygon / chain-X for vendor preference). Per [`arch.md` §22 (chain-pluggable design)](../arch.md) the architecture supports this today; M-beyond is the actual deployment. ### 9.3 Regulator-grade product line @@ -212,7 +212,7 @@ A separate product tier with audit-chain APIs, SOC2 / ISO27001 attestations, com ### 9.4 Hyperscaler interop without absorption -Per [`agent-iam-strategy.md` §6 Risk 1](../../agent-iam-strategy.md): Anthropic / OpenAI / ByteDance each build native walled-garden IAM for their own runtime. AgentKeys becomes the cross-walled-garden bridge — a vendor's device can authenticate to Claude *and* Doubao through the same actor tree. Hyperscalers don't credibly build this themselves (each can only do their own garden). +Per [`agent-iam-strategy.md` §6 Risk 1](../agent-iam-strategy.md): Anthropic / OpenAI / ByteDance each build native walled-garden IAM for their own runtime. AgentKeys becomes the cross-walled-garden bridge — a vendor's device can authenticate to Claude *and* Doubao through the same actor tree. Hyperscalers don't credibly build this themselves (each can only do their own garden). ### 9.5 Authority-as-infrastructure pricing @@ -226,7 +226,7 @@ If MCP stalls or shifts, AgentKeys has the actor-tree + cap-token + audit primit ## 10. Strategic risks to track at every milestone -Full list in [`agent-iam-strategy.md` §6](../../agent-iam-strategy.md). Summary: +Full list in [`agent-iam-strategy.md` §6](../agent-iam-strategy.md). Summary: | Risk | Mitigation | |---|---| @@ -247,18 +247,18 @@ Full list in [`agent-iam-strategy.md` §6](../../agent-iam-strategy.md). Summary - **Per-PR planning**: every PR description that touches feature work should name which milestone it's serving — and if it's expanding scope beyond the milestone's spec, that's a conversation before implementation. - **Per-quarter retrospective**: walk this doc and the strategy doc together; identify scope drift, mitigation effectiveness, and what the next milestone needs to gain to be honest about its "done when." -When this doc disagrees with [`arch.md`](../../arch.md), arch.md wins — the milestone roadmap is the plan, arch.md is the architecture. When it disagrees with [`agent-iam-strategy.md`](../../agent-iam-strategy.md), the strategy doc wins on positioning + corrections; this doc owns sequencing + scope per milestone. +When this doc disagrees with [`arch.md`](../arch.md), arch.md wins — the milestone roadmap is the plan, arch.md is the architecture. When it disagrees with [`agent-iam-strategy.md`](../agent-iam-strategy.md), the strategy doc wins on positioning + corrections; this doc owns sequencing + scope per milestone. --- ## 12. References -- **Architecture** (single source of truth) — [`docs/arch.md`](../../arch.md) -- **Strategy** (positioning, corrections, risks) — [`docs/agent-iam-strategy.md`](../../agent-iam-strategy.md) -- **xiaozhi-server integration** — [`docs/research/xiaozhi-hermes-architecture.md`](../../research/xiaozhi-hermes-architecture.md), [`docs/research/xiaozhi-hermes-risks.md`](../../research/xiaozhi-hermes-risks.md), [`docs/research/xiaozhi-esp32-magiclink.md`](../../research/xiaozhi-esp32-magiclink.md) -- **Volcano Ark integration** — [`docs/research/volcano-ark-mcp-integration.md`](../../research/volcano-ark-mcp-integration.md) -- **Tuya analysis** — [`docs/research/tuya-vs-xiaozhi.md`](../../research/tuya-vs-xiaozhi.md) -- **AI hardware wedge thesis** — [`docs/research/ai-hardware-companion-wedge.md`](../../research/ai-hardware-companion-wedge.md), [`docs/research/ai-hardware-companion-office-hours.md`](../../research/ai-hardware-companion-office-hours.md) -- **Memory system survey** — [`docs/research/ai-memory-systems-survey.md`](../../research/ai-memory-systems-survey.md), [`docs/plan/agentkeys-memory-design.md`](../../plan/agentkeys-memory-design.md) -- **Project board guide** — [`pm/PROJECT-DASHBOARD-GUIDE.md`](../../../pm/PROJECT-DASHBOARD-GUIDE.md) -- **Archived stage docs** (historical only): [`docs/archived/`](../../archived/) — `development-stages-v2-2026-04.md`, `stage7-demo-and-verification-2026-04.md`, `stage8-wip-2026-04.md`, `operator-runbook-stage7-2026-04.md` +- **Architecture** (single source of truth) — [`docs/arch.md`](../arch.md) +- **Strategy** (positioning, corrections, risks) — [`docs/agent-iam-strategy.md`](../agent-iam-strategy.md) +- **xiaozhi-server integration** — [`docs/research/xiaozhi-hermes-architecture.md`](../research/xiaozhi-hermes-architecture.md), [`docs/research/xiaozhi-hermes-risks.md`](../research/xiaozhi-hermes-risks.md), [`docs/research/xiaozhi-esp32-magiclink.md`](../research/xiaozhi-esp32-magiclink.md) +- **Volcano Ark integration** — [`docs/research/volcano-ark-mcp-integration.md`](../research/volcano-ark-mcp-integration.md) +- **Tuya analysis** — [`docs/research/tuya-vs-xiaozhi.md`](../research/tuya-vs-xiaozhi.md) +- **AI hardware wedge thesis** — [`docs/research/ai-hardware-companion-wedge.md`](../research/ai-hardware-companion-wedge.md), [`docs/research/ai-hardware-companion-office-hours.md`](../research/ai-hardware-companion-office-hours.md) +- **Memory system survey** — [`docs/research/ai-memory-systems-survey.md`](../research/ai-memory-systems-survey.md), [`docs/plan/agentkeys-memory-design.md`](agentkeys-memory-design.md) +- **Project board guide** — [`pm/PROJECT-DASHBOARD-GUIDE.md`](../../pm/PROJECT-DASHBOARD-GUIDE.md) +- **Archived stage docs** (historical only): [`docs/archived/`](../archived/) — `development-stages-v2-2026-04.md`, `stage7-demo-and-verification-2026-04.md`, `stage8-wip-2026-04.md`, `operator-runbook-stage7-2026-04.md` diff --git a/docs/spec/plans/phase-1-fresh-user-wire-onboarding.md b/docs/plan/phase-1-fresh-user-wire-onboarding.md similarity index 87% rename from docs/spec/plans/phase-1-fresh-user-wire-onboarding.md rename to docs/plan/phase-1-fresh-user-wire-onboarding.md index 0d27d629..5f0579c3 100644 --- a/docs/spec/plans/phase-1-fresh-user-wire-onboarding.md +++ b/docs/plan/phase-1-fresh-user-wire-onboarding.md @@ -2,12 +2,12 @@ **Status:** DRAFT 2026-05-28 **Tracking issue:** TBD (to be filed) -**Strategic anchor:** [`docs/agent-iam-strategy.md`](../../agent-iam-strategy.md) §4 (Revised Phase 1) -**Architecture record:** [`docs/arch.md`](../../arch.md) §22d (IAM-guarantee delivery — hooks-first, proxy-fallback) — to be extended with §22d.6 once this plan lands +**Strategic anchor:** [`docs/agent-iam-strategy.md`](../agent-iam-strategy.md) §4 (Revised Phase 1) +**Architecture record:** [`docs/arch.md`](../arch.md) §22d (IAM-guarantee delivery — hooks-first, proxy-fallback) — to be extended with §22d.6 once this plan lands **Replaces:** the C4/C5/C6 Rust-runtime sections of [`issue-103-aiosandbox-hermes-esp32-demo.md`](issue-103-aiosandbox-hermes-esp32-demo.md), now superseded by real Hermes + AgentKeys hooks **Companions:** -- [`docs/wiki/agent-iam-guarantee-glossary.md`](../../wiki/agent-iam-guarantee-glossary.md) — IAM guarantee architecture (the previous operator-facing summary at `docs/demo-aiosandbox-runbook.md` §6 was archived 2026-05-28; a new lean runbook lands with this plan's Phase 1.a implementation) -- [`docs/wiki/agent-iam-guarantee-glossary.md`](../../wiki/agent-iam-guarantee-glossary.md) — terminology (IAM tool vs IAM guarantee, hooks vs proxy) +- [`docs/wiki/agent-iam-guarantee-glossary.md`](../wiki/agent-iam-guarantee-glossary.md) — IAM guarantee architecture (the previous operator-facing summary at `docs/demo-aiosandbox-runbook.md` §6 was archived 2026-05-28; a new lean runbook lands with this plan's Phase 1.a implementation) +- [`docs/wiki/agent-iam-guarantee-glossary.md`](../wiki/agent-iam-guarantee-glossary.md) — terminology (IAM tool vs IAM guarantee, hooks vs proxy) - [Issue #133](https://github.com/litentry/agentKeys/issues/133) — the canonical track for hook reference configs (this plan delivers it as `agentkeys wire`) ## 1. Goal — the 7-step user journey @@ -173,7 +173,7 @@ Each adapter lives in a separate file under `crates/agentkeys-cli/src/wire/adapt | Runtime | Hooks system | Adapter writes | LLM-key flow | Manual steps user must do | |---|---|---|---|---| -| **Hermes** | Shell hooks in `~/.hermes/config.yaml` (verified via [`agent-iam-guarantee-glossary.md`](../../wiki/agent-iam-guarantee-glossary.md) §3) | `hooks:` block + scripts in `~/.hermes/agent-hooks/` + `hooks_auto_accept: true`. Bootstrap: `hermes config set model.provider …` etc. | Fetched from broker; written into `~/.hermes/config.yaml` under `model.api_key` | None for default flow; Nous Portal OAuth only if user wants Portal-routed inference | +| **Hermes** | Shell hooks in `~/.hermes/config.yaml` (verified via [`agent-iam-guarantee-glossary.md`](../wiki/agent-iam-guarantee-glossary.md) §3) | `hooks:` block + scripts in `~/.hermes/agent-hooks/` + `hooks_auto_accept: true`. Bootstrap: `hermes config set model.provider …` etc. | Fetched from broker; written into `~/.hermes/config.yaml` under `model.api_key` | None for default flow; Nous Portal OAuth only if user wants Portal-routed inference | | **OpenClaw** | Likely shell hooks (inferred from Hermes lineage; **verify before locking in**) | Likely same as Hermes; verify with live install | Same as Hermes | TBD pending verification | | **Claude Code** | Hooks via `~/.claude/settings.json` (24+ events) | `hooks.PreToolUse/PostToolUse/Stop/etc.` blocks; scripts in `~/.claude/hooks/` | Anthropic API key via `claude config set` OR Claude account OAuth | `claude login` if using account auth | | **Codex** | Hooks via `~/.codex/hooks.json` or `~/.codex/config.toml` (10 events) | Hook bindings via the `[hooks]` table; scripts in `~/.codex/hooks/` | OpenAI API key via `codex auth login` OR ChatGPT account | `codex auth login` | @@ -277,10 +277,10 @@ Artifacts archived 2026-05-28 (moved to `docs/archived/` per CLAUDE.md "Move sta | Artifact (pre-archive path) | Disposition | Archived location | |---|---|---| -| `docs/demo-aiosandbox-runbook.md` | Moved (entire file — including the §6 architecture content, now duplicated in [arch.md §22d](../../arch.md) + [wiki glossary](../../wiki/agent-iam-guarantee-glossary.md)) | [`docs/archived/demo-aiosandbox-runbook-rust-runtime-2026-05.md`](../../archived/demo-aiosandbox-runbook-rust-runtime-2026-05.md) | -| `docs/verify-issue-103.md` | Moved (tested the obsolete Rust crate); replaced by per-step verification in the future wire-flow runbook | [`docs/archived/verify-issue-103-rust-runtime-2026-05.md`](../../archived/verify-issue-103-rust-runtime-2026-05.md) | -| `scripts/setup-demo-aiosandbox.sh` | Moved (provisioned the Rust runtime image); replaced by `agentkeys wire hermes` | [`docs/archived/setup-demo-aiosandbox-rust-runtime-2026-05.sh`](../../archived/setup-demo-aiosandbox-rust-runtime-2026-05.sh) | -| `docker/aiosandbox-demo/` (directory: Dockerfile + supervisord configs + nginx fragment) | Moved; Hermes install goes via `agentkeys wire hermes` against a stock sandbox container | [`docs/archived/aiosandbox-demo-rust-runtime-2026-05/`](../../archived/aiosandbox-demo-rust-runtime-2026-05/) | +| `docs/demo-aiosandbox-runbook.md` | Moved (entire file — including the §6 architecture content, now duplicated in [arch.md §22d](../arch.md) + [wiki glossary](../wiki/agent-iam-guarantee-glossary.md)) | [`docs/archived/demo-aiosandbox-runbook-rust-runtime-2026-05.md`](../archived/demo-aiosandbox-runbook-rust-runtime-2026-05.md) | +| `docs/verify-issue-103.md` | Moved (tested the obsolete Rust crate); replaced by per-step verification in the future wire-flow runbook | [`docs/archived/verify-issue-103-rust-runtime-2026-05.md`](../archived/verify-issue-103-rust-runtime-2026-05.md) | +| `scripts/setup-demo-aiosandbox.sh` | Moved (provisioned the Rust runtime image); replaced by `agentkeys wire hermes` | [`docs/archived/setup-demo-aiosandbox-rust-runtime-2026-05.sh`](../archived/setup-demo-aiosandbox-rust-runtime-2026-05.sh) | +| `docker/aiosandbox-demo/` (directory: Dockerfile + supervisord configs + nginx fragment) | Moved; Hermes install goes via `agentkeys wire hermes` against a stock sandbox container | [`docs/archived/aiosandbox-demo-rust-runtime-2026-05/`](../archived/aiosandbox-demo-rust-runtime-2026-05/) | Code-side contradictions still requiring disposition (await operator confirmation before removing): @@ -288,29 +288,29 @@ Code-side contradictions still requiring disposition (await operator confirmatio |---|---|---| | [`crates/agentkeys-hermes-runtime/`](../../../crates/agentkeys-hermes-runtime/) (entire crate, ~600 lines of Rust + tests) | Remove from `Cargo.toml` workspace `members`; delete crate dir (git history preserves) | The crate's role is now played by real Hermes inside aiosandbox; the wire CLI replaces the HTTP runtime. No follow-up needs this code. | | [`crates/agentkeys-daemon/src/demo_memory.rs`](../../../crates/agentkeys-daemon/src/demo_memory.rs) + `--demo-memory` daemon flag + the `run_demo_memory_mode()` function in `main.rs` | Remove the module, the flag, and the dispatch path | Replaced by `agentkeys.memory.get` MCP tool calling the production memory worker; demo memory ingest is via `agentkeys creds add` / `agentkeys memory put` from the master CLI instead. | -| [`tests/fixtures/demo-profile.md`](../../../tests/fixtures/demo-profile.md) | **Keep** — re-used as the seed profile content loaded into S3 by the Phase 1 demo bootstrap | Still the canonical demo-user profile; new role is "S3 seed", not "compile-time include" | +| [`tests/fixtures/demo-profile.md`](../../tests/fixtures/demo-profile.md) | **Keep** — re-used as the seed profile content loaded into S3 by the Phase 1 demo bootstrap | Still the canonical demo-user profile; new role is "S3 seed", not "compile-time include" | -The fixture [`tests/fixtures/demo-profile.md`](../../../tests/fixtures/demo-profile.md) STAYS — it's still the demo profile content, just loaded into S3 (via the real memory worker path) instead of bundled into a Rust binary. +The fixture [`tests/fixtures/demo-profile.md`](../../tests/fixtures/demo-profile.md) STAYS — it's still the demo profile content, just loaded into S3 (via the real memory worker path) instead of bundled into a Rust binary. ## 10. Cross-references -- [strategy doc §4](../../agent-iam-strategy.md) — Phase 1 demo storyboard (three acts) that this plan operationalizes -- [strategy doc §3.6](../../agent-iam-strategy.md) — IAM tool vs IAM guarantee distinction; this plan delivers the guarantee layer -- [arch.md §22d](../../arch.md) — IAM-guarantee delivery (hooks-first, proxy-fallback) at the architecture level -- [wiki glossary](../../wiki/agent-iam-guarantee-glossary.md) — standalone terminology + hook availability table across runtimes +- [strategy doc §4](../agent-iam-strategy.md) — Phase 1 demo storyboard (three acts) that this plan operationalizes +- [strategy doc §3.6](../agent-iam-strategy.md) — IAM tool vs IAM guarantee distinction; this plan delivers the guarantee layer +- [arch.md §22d](../arch.md) — IAM-guarantee delivery (hooks-first, proxy-fallback) at the architecture level +- [wiki glossary](../wiki/agent-iam-guarantee-glossary.md) — standalone terminology + hook availability table across runtimes - [issue #107](https://github.com/litentry/agentKeys/issues/107) — AgentKeys MCP server (prerequisite for this plan) - [issue #133](https://github.com/litentry/agentKeys/issues/133) — Phase 3 hook integration; this plan ships Phase 1's hook-driven IAM guarantees as `agentkeys wire` -## 11. What landed / What did NOT land (per [CLAUDE.md plan-completion policy](../../../CLAUDE.md)) +## 11. What landed / What did NOT land (per [CLAUDE.md plan-completion policy](../../CLAUDE.md)) ### What landed (Phase 1.a, this PR) -1. **`agentkeys hook` helpers** — [`crates/agentkeys-cli/src/hook.rs`](../../../crates/agentkeys-cli/src/hook.rs). Three subcommands (`check`, `audit`, `memory-inject`) that read host stdin JSON, call AgentKeys MCP tools over HTTP (`tools/call` → `result.structuredContent`), and emit host-shaped stdout JSON. `check` fails CLOSED. 6 unit tests. -2. **`agentkeys wire hermes`** — [`crates/agentkeys-cli/src/wire.rs`](../../../crates/agentkeys-cli/src/wire.rs). `RuntimeAdapter` trait + `HermesAdapter`: detects Hermes, writes 3 hook scripts to `~/.hermes/agent-hooks/` (identity baked in, absolute `agentkeys` path), merges a sentinel-delimited managed `hooks:` block into `~/.hermes/config.yaml` (preserves other keys, refuses to clobber foreign `hooks:`), sets `hooks_auto_accept: true`, verifies via `hermes hooks doctor`. Idempotent (`ok proceeding / skip / fail` per step); `--check-only` reports drift without writing. 7 unit tests. -3. **CLI wiring** — `Commands::Wire` + `Commands::Hook` + `HookAction` in [`main.rs`](../../../crates/agentkeys-cli/src/main.rs); `pub mod hook; pub mod wire;` in [`lib.rs`](../../../crates/agentkeys-cli/src/lib.rs). +1. **`agentkeys hook` helpers** — [`crates/agentkeys-cli/src/hook.rs`](../../crates/agentkeys-cli/src/hook.rs). Three subcommands (`check`, `audit`, `memory-inject`) that read host stdin JSON, call AgentKeys MCP tools over HTTP (`tools/call` → `result.structuredContent`), and emit host-shaped stdout JSON. `check` fails CLOSED. 6 unit tests. +2. **`agentkeys wire hermes`** — [`crates/agentkeys-cli/src/wire.rs`](../../crates/agentkeys-cli/src/wire.rs). `RuntimeAdapter` trait + `HermesAdapter`: detects Hermes, writes 3 hook scripts to `~/.hermes/agent-hooks/` (identity baked in, absolute `agentkeys` path), merges a sentinel-delimited managed `hooks:` block into `~/.hermes/config.yaml` (preserves other keys, refuses to clobber foreign `hooks:`), sets `hooks_auto_accept: true`, verifies via `hermes hooks doctor`. Idempotent (`ok proceeding / skip / fail` per step); `--check-only` reports drift without writing. 7 unit tests. +3. **CLI wiring** — `Commands::Wire` + `Commands::Hook` + `HookAction` in [`main.rs`](../../crates/agentkeys-cli/src/main.rs); `pub mod hook; pub mod wire;` in [`lib.rs`](../../crates/agentkeys-cli/src/lib.rs). 4. **MCP server 7 tools** — already shipped under [#107](https://github.com/litentry/agentKeys/issues/107); verified the hook helpers call them correctly. 5. **Drift detection** — `agentkeys wire hermes --check-only` (single-invocation; the nightly cron wrapper is deferred — see below). -6. **Operator runbook** — [`docs/operator-runbook-wire.md`](../../operator-runbook-wire.md) — the 7-step flow + the three-act demo verification, with commands verified end-to-end. +6. **Operator runbook** — [`docs/operator-runbook-wire.md`](../operator-runbook-wire.md) — the 7-step flow + the three-act demo verification, with commands verified end-to-end. 7. **End-to-end smoke test verified** (against the in-memory MCP backend on the host): - Act 1 Permissioned Memory: `memory-inject travel` → `{"context":"## Memory: travel\nChengdu trip — Apr 12 to 16, hotpot at Yulin."}` - Act 2 Deterministic Denial: `check --scope payment.spend` over-cap → `{"decision":"block","reason":"daily_spend_cap_exceeded: cap=500, requested=600, period=daily"}`; under-cap → `{}` diff --git a/docs/spec/plans/phase1-wire-harness-test-plan.md b/docs/plan/phase1-wire-harness-test-plan.md similarity index 100% rename from docs/spec/plans/phase1-wire-harness-test-plan.md rename to docs/plan/phase1-wire-harness-test-plan.md diff --git a/docs/spec/plans/v2-issues/issue-payment-service-deferred.md b/docs/plan/v2-issues/issue-payment-service-deferred.md similarity index 98% rename from docs/spec/plans/v2-issues/issue-payment-service-deferred.md rename to docs/plan/v2-issues/issue-payment-service-deferred.md index f564ab78..50e88d58 100644 --- a/docs/spec/plans/v2-issues/issue-payment-service-deferred.md +++ b/docs/plan/v2-issues/issue-payment-service-deferred.md @@ -7,7 +7,7 @@ gh issue create \ --title "payment-service worker — deferred from v2 main scope" \ --label "documentation,enhancement" \ - --body-file docs/spec/plans/v2-issues/issue-payment-service-deferred.md + --body-file docs/plan/v2-issues/issue-payment-service-deferred.md ``` --- diff --git a/docs/spec/plans/v2-issues/issue-v2-stage-1-foundation.md b/docs/plan/v2-issues/issue-v2-stage-1-foundation.md similarity index 99% rename from docs/spec/plans/v2-issues/issue-v2-stage-1-foundation.md rename to docs/plan/v2-issues/issue-v2-stage-1-foundation.md index f6a5f039..4532f8de 100644 --- a/docs/spec/plans/v2-issues/issue-v2-stage-1-foundation.md +++ b/docs/plan/v2-issues/issue-v2-stage-1-foundation.md @@ -7,7 +7,7 @@ gh issue create \ --title "v2 stage 1 — Foundation: sovereign sidecar + on-chain identity + credentials-service worker" \ --label "documentation,enhancement" \ - --body-file docs/spec/plans/v2-issues/issue-v2-stage-1-foundation.md + --body-file docs/plan/v2-issues/issue-v2-stage-1-foundation.md ``` --- diff --git a/docs/spec/plans/v2-issues/issue-v2-stage-2-hardening.md b/docs/plan/v2-issues/issue-v2-stage-2-hardening.md similarity index 99% rename from docs/spec/plans/v2-issues/issue-v2-stage-2-hardening.md rename to docs/plan/v2-issues/issue-v2-stage-2-hardening.md index 4246ae17..77a2aec9 100644 --- a/docs/spec/plans/v2-issues/issue-v2-stage-2-hardening.md +++ b/docs/plan/v2-issues/issue-v2-stage-2-hardening.md @@ -7,7 +7,7 @@ gh issue create \ --title "v2 stage 2 — Hardening: K11 WebAuthn + multi-device recovery + audit/memory/email workers" \ --label "documentation,enhancement" \ - --body-file docs/spec/plans/v2-issues/issue-v2-stage-2-hardening.md + --body-file docs/plan/v2-issues/issue-v2-stage-2-hardening.md ``` --- diff --git a/docs/research/memory-build-vs-gate-decision.md b/docs/research/memory-build-vs-gate-decision.md index 6b1e09ff..0d2c182c 100644 --- a/docs/research/memory-build-vs-gate-decision.md +++ b/docs/research/memory-build-vs-gate-decision.md @@ -1,7 +1,7 @@ # Memory: build vs. gate — decision record **Status:** DECIDED — **Position C (gated store, pluggable engine)**. 2026-05. -**Question owner:** Hanwen. **Supersedes the framing of** [`../plan/agentkeys-memory-design.md`](../plan/agentkeys-memory-design.md) (which reads as "build a memory system"); reconciles it with [`agent-iam-strategy.md`](./agent-iam-strategy.md) and [`../spec/plans/milestones-roadmap.md`](../spec/plans/milestones-roadmap.md) M1. +**Question owner:** Hanwen. **Supersedes the framing of** [`../plan/agentkeys-memory-design.md`](../plan/agentkeys-memory-design.md) (which reads as "build a memory system"); reconciles it with [`agent-iam-strategy.md`](./agent-iam-strategy.md) and [`../plan/milestones-roadmap.md`](../plan/milestones-roadmap.md) M1. --- @@ -133,7 +133,7 @@ The repo currently holds three positions that look inconsistent; C reconciles th | Doc | What it says today | Under Position C | |---|---|---| | [`agent-iam-strategy.md`](./agent-iam-strategy.md) | "Memory MCP server is too narrow; we're the authority/control plane" (gate-leaning) | ✅ Correct — we gate. Add: we also own the *store*, not the engine. | -| [`milestones-roadmap.md`](../spec/plans/milestones-roadmap.md) M1 | `memory.get`/`memory.put` MCP tools + `namespaces_allowed` cap claim (gated store) | ✅ This **is** Position C already — a gated store exposed as tool calls. Keep as-is. | +| [`milestones-roadmap.md`](../plan/milestones-roadmap.md) M1 | `memory.get`/`memory.put` MCP tools + `namespaces_allowed` cap claim (gated store) | ✅ This **is** Position C already — a gated store exposed as tool calls. Keep as-is. | | [`memory-design.md`](../plan/agentkeys-memory-design.md) | Full worker: vault + vector index + BM25 + rebuild-index ("build a system") | ⚠️ Over-scoped. The **store** half (cap-gated get/put, K3 envelope, per-actor S3, namespaces, audit) is Position C and stays. The **engine** half (vector index, BM25, `/rebuild-index`, embedding rotation) becomes *optional / pluggable* — not core, not the default ship. | The roadmap (M1) was already at Position C. `memory-design.md` is the outlier that drifted toward A. This record pins the intent; a future edit to `memory-design.md` should reframe it from "memory system" to "gated memory backend" and move §4.2/§5 (search + index engine) into an explicit "pluggable engine — not built by us in v0" section. @@ -186,7 +186,7 @@ Delegating any of these three = giving up the differentiator and re-importing th **In-repo:** - [`agent-iam-strategy.md`](./agent-iam-strategy.md) — authority-host thesis; line 46 "memory MCP server too narrow." -- [`../spec/plans/milestones-roadmap.md`](../spec/plans/milestones-roadmap.md) — M1 `memory.get`/`memory.put` + namespaces (already Position C). +- [`../plan/milestones-roadmap.md`](../plan/milestones-roadmap.md) — M1 `memory.get`/`memory.put` + namespaces (already Position C). - [`../plan/agentkeys-memory-design.md`](../plan/agentkeys-memory-design.md) — the store design (keep) + engine design (now pluggable). - [`ai-memory-systems-survey.md`](./ai-memory-systems-survey.md), [`agentmemory-and-claw-code-followup.md`](./agentmemory-and-claw-code-followup.md), [`xiaozhi-hermes-architecture.md`](./xiaozhi-hermes-architecture.md) — engine survey + Hermes provider/hook model. diff --git a/docs/research/volcano-ark-mcp-integration.md b/docs/research/volcano-ark-mcp-integration.md index 4ea8d5d5..6ae181ca 100644 --- a/docs/research/volcano-ark-mcp-integration.md +++ b/docs/research/volcano-ark-mcp-integration.md @@ -343,4 +343,4 @@ Both terminate at the same AgentKeys backend. Both honor the same cross-vendor c - [`xiaozhi-hermes-architecture.md`](./xiaozhi-hermes-architecture.md) — sibling adapter architecture (xiaozhi path) - [`xiaozhi-hermes-risks.md`](./xiaozhi-hermes-risks.md) — risk-verification pattern that informed this doc's risk section - [`ai-hardware-companion-office-hours.md`](./ai-hardware-companion-office-hours.md) — original Approach D + cross-vendor consent model -- [issue #103 plan](../spec/plans/issue-103-aiosandbox-hermes-esp32-demo.md) — xiaozhi-side implementation +- [issue #103 plan](../plan/issue-103-aiosandbox-hermes-esp32-demo.md) — xiaozhi-side implementation diff --git a/docs/research/xiaozhi-hermes-architecture.md b/docs/research/xiaozhi-hermes-architecture.md index 3c63c552..9360b7eb 100644 --- a/docs/research/xiaozhi-hermes-architecture.md +++ b/docs/research/xiaozhi-hermes-architecture.md @@ -221,4 +221,4 @@ This sits inside the "1.5–2.0s realistic floor" called out in [office-hours de - [`xiaozhi-hermes-risks.md`](./xiaozhi-hermes-risks.md) — risk verification + mitigations - [`ai-hardware-companion-office-hours.md`](./ai-hardware-companion-office-hours.md) — wedge strategy (Approach D) - [`ai-hardware-companion-wedge.md`](./ai-hardware-companion-wedge.md) — market + competitive landscape -- [issue #103 plan](../spec/plans/issue-103-aiosandbox-hermes-esp32-demo.md) — implementation plan (sections C4/C5/C6 superseded by this direction) +- [issue #103 plan](../plan/issue-103-aiosandbox-hermes-esp32-demo.md) — implementation plan (sections C4/C5/C6 superseded by this direction) diff --git a/docs/research/xiaozhi-hermes-risks.md b/docs/research/xiaozhi-hermes-risks.md index 1c8f51db..976f3f6d 100644 --- a/docs/research/xiaozhi-hermes-risks.md +++ b/docs/research/xiaozhi-hermes-risks.md @@ -199,7 +199,7 @@ The fork-local hack is cheaper but creates a maintenance fork burden. The upstre ## Net effect on the v0 plan -The original [issue #103 plan](../spec/plans/issue-103-aiosandbox-hermes-esp32-demo.md) estimated 3 weeks for the demo. With these risk findings the integration is substantially smaller: +The original [issue #103 plan](../plan/issue-103-aiosandbox-hermes-esp32-demo.md) estimated 3 weeks for the demo. With these risk findings the integration is substantially smaller: | Bridge work | Effort | |---|---| @@ -247,4 +247,4 @@ The biggest remaining unknown is **the actual streaming-SSE flow from Hermes thr - [`xiaozhi-esp32-magiclink.md`](./xiaozhi-esp32-magiclink.md) — hardware research + Option 1 vs 2 decision - [`xiaozhi-hermes-architecture.md`](./xiaozhi-hermes-architecture.md) — architecture diagrams - [`ai-hardware-companion-office-hours.md`](./ai-hardware-companion-office-hours.md) — wedge strategy -- [issue #103 plan](../spec/plans/issue-103-aiosandbox-hermes-esp32-demo.md) — implementation plan +- [issue #103 plan](../plan/issue-103-aiosandbox-hermes-esp32-demo.md) — implementation plan diff --git a/docs/spec/1-step-analysis.md b/docs/spec/1-step-analysis.md index d07cc56a..d79a8bf1 100644 --- a/docs/spec/1-step-analysis.md +++ b/docs/spec/1-step-analysis.md @@ -6,7 +6,7 @@ **Parent docs (authoritative for product vision):** -- `[./design-spec.md](design-spec.md)` — executive summary of AgentKeys: browser-automation provisioning, MCP delivery, x402 billing, Heima TEE storage +- `[./design-spec.md](../archived/design-spec.md)` — executive summary of AgentKeys: browser-automation provisioning, MCP delivery, x402 billing, Heima TEE storage - `[/Users/hanwencheng/Projects/project-life/.omc/specs/deep-interview-agentkeys.md](../../../../.omc/specs/deep-interview-agentkeys.md)` — full deep-interview spec (11 rounds, 19% ambiguity, PASSED) **Companion research docs:** diff --git a/docs/spec/credential-backend-interface.md b/docs/spec/credential-backend-interface.md index c171d482..77f58372 100644 --- a/docs/spec/credential-backend-interface.md +++ b/docs/spec/credential-backend-interface.md @@ -445,7 +445,7 @@ The Kai meeting questions are now reframed around the trait interface: ## 6. Cross-References -- CEO plan: [`./ceo-plan.md`](projects/idea/agentkeys/plans/ceo-plan.md) +- CEO plan: [`./ceo-plan.md`](../plan/ceo-plan.md) - Architecture (13 components): [`../arch.md`](../arch.md) - Auth-layer analysis: [`./1-step-analysis.md`](./1-step-analysis.md) - Kai meeting agenda: [`./heima-open-questions.md`](./heima-open-questions.md) diff --git a/docs/spec/deployed-contracts.md b/docs/spec/deployed-contracts.md index 246b2f9b..65410f4e 100644 --- a/docs/spec/deployed-contracts.md +++ b/docs/spec/deployed-contracts.md @@ -1,5 +1,143 @@ -# Deployed contracts — moved +# Deployed contracts — canonical registry -The canonical deployed-contract registry now lives at **[`docs/contracts.md`](../contracts.md)** (single source for every on-chain address across chains, indexed from [`arch.md`](../arch.md) §5). +**Single source of truth** for every on-chain contract address AgentKeys has deployed, per chain, plus the EVM deployer wallets (prod vs test/CI). Answers "what's the live address of `SidecarRegistry` / the ERC-4337 `EntryPoint` on Heima mainnet right now?" and "which EVM account deployed it?" -This file is kept only as a redirect so older links resolve. Do not add addresses here — edit [`docs/contracts.md`](../contracts.md). +Mirrored into [`scripts/operator-workstation.env`](../../scripts/operator-workstation.env) (the shell-consumable form, written by `scripts/heima-bring-up.sh` step 6 via `env_set`). When the two diverge, **this doc is authoritative for human reads, the env file for tooling**; the bring-up script keeps both in sync. Indexed from [`arch.md`](../arch.md) §5. (`docs/contracts.md` is a redirect to this file.) + +--- + +## EVM deployer wallets (prod vs test/CI) + +Two distinct EVM accounts deploy AgentKeys contracts. They are **different keys**, so each lands the contract set at **different addresses** via `(deployer, nonce)` CREATE derivation — the prod set and the test set never collide. + +| Role | Deployer EVM address | Key location | Source of truth | +|---|---|---|---| +| **Local / prod deploy** | `0xdE644936D5B7d5d42032fd08bbA42Fbbfd6663Bc` | `$HEIMA_DEPLOYER_KEY_FILE` (default `~/.agentkeys/heima-deployer.key`, never committed) | [`scripts/operator-workstation.env`](../../scripts/operator-workstation.env) `HEIMA_DEPLOYER_ADDR_HEIMA` | +| **Test / CI deploy** | `0x9FE9e6c208e9e75D2A19a5c2683127c33896F259` | `~/.agentkeys/heima-deployer-test.key` (operator-provided; wired into GitHub Actions secrets via [`scripts/ci-set-github-secrets.sh`](../../scripts/ci-set-github-secrets.sh)) | [`scripts/operator-workstation.test.env`](../../scripts/operator-workstation.test.env) `HEIMA_DEPLOYER_ADDR_HEIMA` | + +- The prod deployer's Substrate twin (SS58 prefix 31) is `47NGSq6JE5ZSnymGNa4nFVjWbsuhTfoSKN2jtpk28mUyC1M3` — fund the EVM side via the twin, see [`scripts/evm-to-substrate-address.mjs`](../../scripts/evm-to-substrate-address.mjs). +- Heima Paseo testnet uses its own deployer `0xeBdE9E5F8c0495e87a871BF4f17Fb85e1bFE827F` (`HEIMA_PASEO_DEPLOYER_ADDR`) — currently unused (chain halted, see below). + +--- + +## Heima mainnet (chain_id = 212013) + +### v2 stage-1 set (current live — prod deployer) + +| Contract | Address | Bytecode | +|---|---|---| +| `AgentKeysScope` | `0xd44b375daefc65768f417d0f0125b68d5ba7df3b` | 4572 bytes | +| `SidecarRegistry` | `0x1Ac62f1C2D828476a5D784e850a700dC1f17e0bE` | 4572 bytes | +| `K3EpochCounter` | `0x6c9e675c699a06acefbc156afdee6bfbfe32ccb3` | 591 bytes | +| `CredentialAudit` | `0x63c4545ac01c77cc74044f25b8edea3880224577` | 3043 bytes | +| `P256Verifier` | `0xda5b772f9d6c09abe80414eea908612df9b54749` | (pre-deployed verifier) | +| `K11Verifier` | `0x5a441431f08e0f5f5ed10659620cb4e0e814e627` | (pre-deployed verifier) | + +### ERC-4337 master infra (#164, deployed 2026-06-02 — prod deployer) + +Foundation plumbing for the P-256 smart-account master ([plan](../plan/chain/erc4337-master-account.md)). **NOT yet the live master-auth:** the registry/scope cutover to account-authorization (#164 E3/E7) is a later coordinated redeploy; these are inert until masters are registered as accounts. + +| Contract | Address | Notes | +|---|---|---| +| `EntryPoint` (ERC-4337 v0.7) | `0x6672E1b315332167aBA12E0B1d3532a7e9B1ADE9` | canonical eth-infinitism v0.7 bytecode; landed a UserOp end-to-end in the spike | +| `P256AccountFactory` | `0x1ccCe65b22De81aDA4F378FeAf7503d93f5d27a3` | CREATE2 factory; `constructor(entryPoint, k11Verifier)`; wired to the live `K11Verifier`; mainnet CREATE2 determinism smoke-verified | + +### Test / CI deploy (Heima mainnet — test deployer) + +The test stack deploys the **same four contracts** with the test deployer key (`0x9FE9…F259`), landing them at **different addresses** (distinct `(deployer, nonce)` derivation). It shares the prod AWS account but uses distinct IAM roles, S3 buckets, OIDC issuer, and `-test` DNS — a leaked test cred cannot reach prod data. + +- **Tier-1 CI** (the no-LLM gate from #66/#98) runs against an **ephemeral anvil** chain — fresh contracts per run, no persistent mainnet addresses. +- **Tier-2 / persistent test deploy** addresses are pinned in [`scripts/operator-workstation.test.env`](../../scripts/operator-workstation.test.env) (`*_ADDRESS_HEIMA`). **The values there today are placeholders** — that file's own header says "replace with real test addresses post-deploy." Pin the real ones after a one-shot test deploy: + + ```bash + AGENTKEYS_CHAIN=heima HEIMA_DEPLOYER_KEY_FILE=~/.agentkeys/heima-deployer-test.key \ + MAINNET_CONFIRM=1 bash scripts/setup-heima.sh --from-step 4 --to-step 8 + ``` + +- The `P256Verifier` + `K11Verifier` are **shared pre-deployed** contracts — same address on prod and test (mirror the prod values above). + +### Historical v1 deploy (superseded by v2; preserved for old-tx cross-reference) + +| Contract | Address | Bytecode | +|---|---|---| +| `AgentKeysScope` | `0x14C23B5D1cE20c094af643a20e6b0972dAD12aa8` | 3146 bytes | +| `SidecarRegistry` | `0x76D574a107727bE87fc1422661A030FEFda70786` | 3301 bytes | +| `K3EpochCounter` | `0x8396dEc50ff755d6DE7728DABB00Be2eFBCdf4dF` | 687 bytes | +| `CredentialAudit` | `0x1801ded1a4FBD8c9224Ab18B9EcbB293B8674c06` | 1421 bytes | + +## Heima Paseo testnet (chain_id = 2013) + +Halted (block 2,905,430 frozen since 2026-01-15). **No contracts deployed** — the `*_ADDRESS_HEIMA_PASEO` entries in `operator-workstation.env` are placeholders (`0x..01`–`0x..04`). When collators return: `AGENTKEYS_CHAIN=heima-paseo bash harness/v2-stage1-demo.sh --only-step 9` deploys + auto-funds via Alice sudo; update this doc with the live testnet addresses then. + +--- + +## Deploy metadata (Heima mainnet v2) + +- Deployer wallet (EVM): `0xdE644936D5B7d5d42032fd08bbA42Fbbfd6663Bc` (prod) — see the deployer table above for prod vs test. +- v2 deploy date: 2026-05-19 · #164 E1 deploy date: 2026-06-02 +- Compiler: Solc 0.8.20, `evm_version = "london"` (a `forge script` header-validation workaround, NOT Heima's EVM level — Heima executes **Cancun**; see CLAUDE.md "Heima EVM compatibility level"). The EntryPoint v0.7 is the canonical eth-infinitism bytecode, deployed via `forge create`. +- Deploy script: [`crates/agentkeys-chain/script/DeployAgentKeysV1.s.sol`](../../crates/agentkeys-chain/script/DeployAgentKeysV1.s.sol) + +**Constructor wiring** (verified post-deploy): +- `AgentKeysScope.registry()` = the v2 `SidecarRegistry` ✓ +- `P256AccountFactory.entryPoint()` = the v0.7 `EntryPoint` ✓, `.k11Verifier()` = the live `K11Verifier` ✓ +- `K3EpochCounter.currentEpoch()` = `1`; `.signerGovernance()` = deployer (to be transferred to an M-of-N multisig) +- `SidecarRegistry.ROLE_CAP_MINT()` = `1`, `ROLE_RECOVERY()` = `2`, `ROLE_SCOPE_MGMT()` = `4` ✓ + +## Verifying contracts are live (read-only RPC, zero gas) + +```bash +# One-shot health check across the v2 set: +AGENTKEYS_CHAIN=heima bash scripts/verify-heima-contracts.sh # exits 0 on all-pass + +# Bytecode presence (eth_getCode), e.g. the ERC-4337 EntryPoint: +cast code 0x6672E1b315332167aBA12E0B1d3532a7e9B1ADE9 --rpc-url https://rpc.heima-parachain.heima.network | head -c 12 +# View call, e.g. factory wiring: +cast call 0x1ccCe65b22De81aDA4F378FeAf7503d93f5d27a3 "entryPoint()(address)" --rpc-url https://rpc.heima-parachain.heima.network +``` + +The verify script checks, per contract: (1) **bytecode presence** (`eth_getCode` non-empty); (2) **view functions** return the expected constant (catches wrong-code-at-this-slot drift); (3) **constructor wiring** (`AgentKeysScope.registry()` → the deployed `SidecarRegistry`); (4) **initialization** (`K3EpochCounter.currentEpoch ≥ 1`, `signerGovernance != address(0)`). It reads addresses from `operator-workstation.env`, so changing `AGENTKEYS_CHAIN` picks up the chain-specific deployment. + +**Explorer note:** [`heima.statescan.io`](https://heima.statescan.io/) is Substrate-side — it indexes pallet extrinsics/events but does NOT decode EVM calls/bytecode. EVM contract verification on Heima goes via direct RPC until agentkeys-specific indexing on Litentry's `subscan-essentials` fork ships (arch.md §22a.6). + +## Re-deploy / replace + +Re-running `bash harness/v2-stage1-demo.sh --only-step 9` is **idempotent**: it calls `cast code` on each stored address and skips the deploy if all four already have on-chain bytecode. Re-deploys only fire when the stored address is the `0x0` sentinel / absent, or has no bytecode on-chain (chain reset, address corrupted). To **force** a fresh deploy at new addresses (e.g. after a contract patch), clear the address entries from `operator-workstation.env` (or set them to `0x0`) and re-run. After any re-deploy, **update this doc** with the new addresses + bytecode sizes + deploy date — the deploy operator owns the doc bump; the bring-up script handles `operator-workstation.env` automatically but doesn't touch markdown. + +## ABI summary + +Full ABIs in [`crates/agentkeys-chain/src/*.sol`](../../crates/agentkeys-chain/src/). The functions broker + workers + CLI read on hot paths: + +### `SidecarRegistry` +- `registerMasterDevice(bytes32 deviceKeyHash, bytes32 operatorOmni, bytes32 actorOmni, bytes32 k11CredId, bytes attestation, uint8 roles, bytes k11Assertion)` — first call bootstraps `operatorMasterWallet[operatorOmni] = msg.sender`; subsequent require existing master + K11 +- `registerAgentDevice(bytes32 deviceKeyHash, bytes32 operatorOmni, bytes32 actorOmni, bytes linkCodeRedemption, bytes agentPopSig)` — master-only; agents get `ROLE_CAP_MINT` only +- `revokeDevice(bytes32 deviceKeyHash, bytes k11Assertion)` — master-only; K11 required for master tier +- `getDevice(bytes32 deviceKeyHash) → DeviceEntry` — view +- `isActive(bytes32 deviceKeyHash) → bool` — hot-path view for workers +- `operatorMasterWallet(bytes32 operatorOmni) → address` — auto-generated getter + +### `AgentKeysScope` +- `setScopeWithWebauthn(bytes32 operatorOmni, bytes32 agentOmni, bytes32[] services, bool readOnly, uint128 maxPerCall, uint128 maxPerPeriod, uint128 maxTotal, uint32 periodSeconds, bytes k11Assertion)` — master-only, K11-gated +- `revokeScope(bytes32 operatorOmni, bytes32 agentOmni, bytes k11Assertion)` — master-only, K11-gated +- `getScope(bytes32 operatorOmni, bytes32 agentOmni) → Scope` — view +- `isServiceInScope(bytes32 operatorOmni, bytes32 agentOmni, bytes32 serviceHash) → bool` — hot-path view + +### `K3EpochCounter` +- `advanceEpoch()` — signerGovernance-only +- `setSignerGovernance(address newGov)` — signerGovernance-only (handoff or rotation) +- `currentEpoch() → uint256` — auto-generated getter +- `signerGovernance() → address` — auto-generated getter + +### `CredentialAudit` +- `append(bytes32 operatorOmni, bytes32 actorOmni, bytes32 serviceHash, uint8 opType, bytes32 payloadHash)` — open append (any caller; gas is the spam-resistance) +- `getEntries(bytes32 operatorOmni, uint256 offset, uint256 limit) → AuditEntry[]` — paginated view +- `entryCount(bytes32 operatorOmni) → uint256` — view + +## When this doc needs to change + +1. **New deploy on any chain** — update the table for that chain (addresses + bytecode sizes + date + deployer + tx hash if known) +2. **Constructor re-wiring** — any change to the deploy script's constructor args; re-record the "Constructor wiring" section +3. **K3 epoch advance** — `currentEpoch` monotonically increases; update the "Constructor wiring" line for the latest value +4. **`signerGovernance` transfer** — when handoff from deployer → operational signer (or → multisig in stage 2) happens, record the new address + tx hash +5. **Re-deploy** at fresh addresses — replace the table row entirely; old addresses move to the "Historical deploys" section for audit-trail +6. **Test deploy pinned** — when the test stack's persistent (non-anvil) addresses are deployed, replace the placeholders in `operator-workstation.test.env` and record them in the "Test / CI deploy" section above diff --git a/docs/spec/heima-cli-exploration.md b/docs/spec/heima-cli-exploration.md index e8a9437e..aa9782fe 100644 --- a/docs/spec/heima-cli-exploration.md +++ b/docs/spec/heima-cli-exploration.md @@ -1,6 +1,6 @@ # AgentKeys / Heima CLI — Exploration of a Blockchain-Backed 1Password CLI Replacement -> **ARCHIVED** — This was the initial exploration document (2026-04-07). All questions below have been resolved. See [`plans/ceo-plan.md`](plans/ceo-plan.md) for the v0 plan, and [`credential-backend-interface.md`](credential-backend-interface.md) for the trait spec. +> **ARCHIVED** — This was the initial exploration document (2026-04-07). All questions below have been resolved. See [`plans/ceo-plan.md`](../plan/ceo-plan.md) for the v0 plan, and [`credential-backend-interface.md`](credential-backend-interface.md) for the trait spec. **Status:** archived exploration draft, 2026-04-07 **Inputs:** [`lifeKnowledge/heima.md`](heima.md) (Heima capability analysis), 1Password CLI feature inventory (research summary), reference site https://agentvault-site.vercel.app/ diff --git a/docs/spec/heima-gaps-vs-desired-architecture.md b/docs/spec/heima-gaps-vs-desired-architecture.md index acaff19a..502ddc65 100644 --- a/docs/spec/heima-gaps-vs-desired-architecture.md +++ b/docs/spec/heima-gaps-vs-desired-architecture.md @@ -20,8 +20,8 @@ Related docs: - [`architecture.md`](architecture.md) — canonical broker / signer / daemon / key-flow doc (post-issue-#74). - [`signer-protocol.md`](signer-protocol.md) — `/dev/*` wire contract. -- [`plans/issue-74-dev-key-service-plan.md`](plans/issue-74-dev-key-service-plan.md) — dev_key_service signer landed in PR #75. -- [`plans/issue-74-step-1c-device-key-auth.md`](plans/issue-74-step-1c-device-key-auth.md) — device-key auth on `/dev/*`, planned. +- [`plans/issue-74-dev-key-service-plan.md`](../archived/issue-74-dev-key-service-plan.md) — dev_key_service signer landed in PR #75. +- [`plans/issue-74-step-1c-device-key-auth.md`](../plan/issue-74-step-1c-device-key-auth.md) — device-key auth on `/dev/*`, planned. - [`docs/wiki/blockchain-tee-architecture.md`](../wiki/blockchain-tee-architecture.md) — canonical desired architecture (four rules). - [`docs/wiki/key-security.md`](../wiki/key-security.md) — TEE key security model. - [`plans/development-stages.md`](./plans/development-stages.md) — stage roadmap; this gap list is the critical path for Stage 6 and Stage 7. @@ -42,7 +42,7 @@ The table below is the at-a-glance answer to "where do we stand?" Per-gap detail | 8 | `pallet-oidc-pubkeys` (URL-hijack defense) | **GAP — unchanged** | Stage 7b; depends on §3 having TEE-attested rather than on-disk keypair. | | 9 | `pallet-enclave-successors` (MRSIGNER governance) | **GAP — unchanged** | Required only when MRSIGNER rotation lands; not a v0.1 blocker. | | 10 | **(NEW)** Signer-edge contract for the per-user wallet key | **PARTIAL — wire shape pinned, dev-stage backend** | `signer-protocol.md` v0.1 ships the wire contract; `dev_key_service` is the dev-stage HKDF backend; issue #74 step 2 (TEE worker) closes the trust gap. | -| 11 | **(NEW)** Per-request crypto auth on the signer edge | **PLANNED** | Heima's `ClientAuth::EvmSiweSigned` / `BackendSigned` tier model is the prior art. Issue #74 step 1c (device-key auth) is a strict superset — see [`plans/issue-74-step-1c-device-key-auth.md`](plans/issue-74-step-1c-device-key-auth.md). | +| 11 | **(NEW)** Per-request crypto auth on the signer edge | **PLANNED** | Heima's `ClientAuth::EvmSiweSigned` / `BackendSigned` tier model is the prior art. Issue #74 step 1c (device-key auth) is a strict superset — see [`plans/issue-74-step-1c-device-key-auth.md`](../plan/issue-74-step-1c-device-key-auth.md). | | 12 | (tracking metadata) | n/a | Resolution log lives in §12 below. | --- @@ -371,7 +371,7 @@ was no equivalent service for an operator authenticated via email/OAuth2 (no local crypto wallet) to obtain a deterministic EVM wallet under the operator's `omni_account`. -PR #75 ([issue #74 step 1](plans/issue-74-dev-key-service-plan.md)) +PR #75 ([issue #74 step 1](../archived/issue-74-dev-key-service-plan.md)) ships: - The wire contract in [`signer-protocol.md`](signer-protocol.md): `POST /dev/derive-address` and `POST /dev/sign-message` with @@ -423,7 +423,7 @@ as a normal config value. ## 11. Gap (NEW): per-request crypto auth on the signer edge -**Status:** PLANNED — design in [`plans/issue-74-step-1c-device-key-auth.md`](plans/issue-74-step-1c-device-key-auth.md); CEO review pending. +**Status:** PLANNED — design in [`plans/issue-74-step-1c-device-key-auth.md`](../plan/issue-74-step-1c-device-key-auth.md); CEO review pending. ### Current diff --git a/docs/spec/open-source-posture.md b/docs/spec/open-source-posture.md index e5b278bd..a1102a54 100644 --- a/docs/spec/open-source-posture.md +++ b/docs/spec/open-source-posture.md @@ -7,8 +7,8 @@ **Sibling docs:** - [`../arch.md`](../arch.md) — Rust/TypeScript component split and Cargo workspace layout (read this first for the 13-component inventory) - [`./1-step-analysis.md`](./1-step-analysis.md) — auth-layer sub-analysis (threat model lives in §3.3c) -- [`./plans/design-spec.md`](plans/design-spec.md) — original product vision (historical) -- [`./plans/ceo-plan.md`](plans/ceo-plan.md) — v0 implementation plan (canonical) +- [`./plans/design-spec.md`](../archived/design-spec.md) — original product vision (historical) +- [`./plans/ceo-plan.md`](../plan/ceo-plan.md) — v0 implementation plan (canonical) - [`./heima-open-questions.md`](./heima-open-questions.md) — Kai meeting agenda (Q9 is the top priority dependency) **Prior interview reference:** @@ -356,7 +356,7 @@ What the writeup can honestly claim, given everything above: - **Component inventory and language choices:** [`../arch.md`](../arch.md) §2, §3 - **Kernel hardening threat model:** [`./1-step-analysis.md`](./1-step-analysis.md) §3.3c -- **Multi-repo structure:** [`./plans/ceo-plan.md`](plans/ceo-plan.md) §"Repository structure" +- **Multi-repo structure:** [`./plans/ceo-plan.md`](../plan/ceo-plan.md) §"Repository structure" - **TEE worker Kai questions:** [`./heima-open-questions.md`](./heima-open-questions.md) Q9 (top priority), Q11, Q1, Q2 - **Heima parachain licensing:** see `/lifeKnowledge/heima.md` - **User flows showing trust boundaries in action:** [`./1-step-analysis.md`](./1-step-analysis.md) §4 diff --git a/docs/spec/tech-brief.md b/docs/spec/tech-brief.md index 288c11d4..99fd45c5 100644 --- a/docs/spec/tech-brief.md +++ b/docs/spec/tech-brief.md @@ -436,7 +436,7 @@ After Round 13 runtime probe findings, the priority has shifted: | [`credential-backend-interface.md`](credential-backend-interface.md) | Full Rust trait definition, `AuthRequestType` enum, canonical serialization spec, replay-resistance invariants | | [`architecture.md`](architecture.md) | 13-component inventory, language split rationale, trust domain diagram | | [`heima-open-questions.md`](heima-open-questions.md) | Full meeting agenda with 12 questions, hinge decisions, walk-out deliverable | -| [`plans/ceo-plan.md`](plans/ceo-plan.md) | v0 scope decisions, component list, auth flow, deferred items | -| [`plans/eng-review-test-plan.md`](plans/eng-review-test-plan.md) | 50+ test cases including rendezvous, auth-request, sandbox hardening | +| [`plans/ceo-plan.md`](../plan/ceo-plan.md) | v0 scope decisions, component list, auth flow, deferred items | +| [`plans/eng-review-test-plan.md`](../archived/eng-review-test-plan.md) | 50+ test cases including rendezvous, auth-request, sandbox hardening | | [`../research/aiosandbox/agent-infra-sandbox-runtime-probe.md`](../research/aiosandbox/agent-infra-sandbox-runtime-probe.md) | Empirical probe of `agent-infra/sandbox` — why UID isolation is impossible on stock image | | [`1-step-analysis.md`](1-step-analysis.md) | Deep auth-layer analysis (990 lines), session key tiers, user flows, threat model | diff --git a/docs/v2-stage1-migration-and-demo.md b/docs/v2-stage1-migration-and-demo.md index 49efe810..310e0065 100644 --- a/docs/v2-stage1-migration-and-demo.md +++ b/docs/v2-stage1-migration-and-demo.md @@ -1,6 +1,6 @@ # v2 stage 1 — fresh-start demo (Litentry/Heima EVM backbone) -**Status (2026-05-24)**: this doc is transitional. The v1/v2 staging name retires after v2-stage3 ships green; M1-M7 ([`docs/spec/plans/milestones-roadmap.md`](spec/plans/milestones-roadmap.md)) is the forward-facing framing. Until then, this remains the operator runbook for stage-1 bring-up. +**Status (2026-05-24)**: this doc is transitional. The v1/v2 staging name retires after v2-stage3 ships green; M1-M7 ([`docs/plan/milestones-roadmap.md`](plan/milestones-roadmap.md)) is the forward-facing framing. Until then, this remains the operator runbook for stage-1 bring-up. **Audience**: operators bringing up a **brand new** v2 stage-1 deployment from scratch. Everything previously inherited from the stage-7 demo is called out explicitly — that demo doc is now archived; inline pointers below go to the archive when the historical step is still relevant. @@ -9,7 +9,7 @@ **Chain backbone**: Litentry's parachain (rebranded to **Heima Network** in 2026) is the EVM L1 we deploy all stage-1 contracts on. Heima is Substrate + Frontier — `pallet_evm` + `pallet_ethereum` give native EVM compatibility with first-class EVM account addresses as `msg.sender`. Stage-1's four contracts (`AgentKeysScope`, `SidecarRegistry`, `K3EpochCounter`, `CredentialAudit`) are plain Solidity, deployed via Foundry or Hardhat using the operator's `current_master_wallet`. **Reference docs**: -- Stage 1 deliverable inventory — [docs/spec/plans/v2-issues/issue-v2-stage-1-foundation.md](spec/plans/v2-issues/issue-v2-stage-1-foundation.md) +- Stage 1 deliverable inventory — [docs/plan/v2-issues/issue-v2-stage-1-foundation.md](plan/v2-issues/issue-v2-stage-1-foundation.md) - Stage 7 demo (parent for §0 prereqs, §1 init, §2 SIWE, §3 OIDC+STS, §4 isolation proof, §5 provision) — [docs/archived/stage7-demo-and-verification-2026-04.md](archived/stage7-demo-and-verification-2026-04.md) - Architecture v2 (single source of truth) — [docs/arch.md](arch.md) @@ -1363,7 +1363,7 @@ Per-iteration error → fix log: [`docs/v2-stage1-iteration-log.md`](v2-stage1-i ## Cross-references -- **Stage 1 deliverable inventory** — [docs/spec/plans/v2-issues/issue-v2-stage-1-foundation.md](spec/plans/v2-issues/issue-v2-stage-1-foundation.md) +- **Stage 1 deliverable inventory** — [docs/plan/v2-issues/issue-v2-stage-1-foundation.md](plan/v2-issues/issue-v2-stage-1-foundation.md) - **Architecture v2 (single source of truth)** — [docs/arch.md](arch.md) - **Stage 7 demo (parent for inherited §0 prereqs + §1 init + §3 OIDC/STS)** — [docs/archived/stage7-demo-and-verification-2026-04.md](archived/stage7-demo-and-verification-2026-04.md) - **Cloud setup (parent for AWS IAM, OIDC provider, bucket policy)** — [docs/cloud-bootstrap.md](cloud-bootstrap.md) diff --git a/docs/wiki/agent-iam-guarantee-glossary.md b/docs/wiki/agent-iam-guarantee-glossary.md index 18bbf132..414d5a89 100644 --- a/docs/wiki/agent-iam-guarantee-glossary.md +++ b/docs/wiki/agent-iam-guarantee-glossary.md @@ -90,7 +90,7 @@ Rationale (anchored in [`agent-iam-strategy.md`](../../docs/agent-iam-strategy.m | Phase | Track | Deliverable | |---|---|---| | **Phase 1** (this PR + immediate follow-up) | MCP server | Extend [`crates/agentkeys-mcp-server`](../../crates/agentkeys-mcp-server) with the 7 Phase-1 tools (`identity.whoami`, `memory.get`, `memory.put`, `permission.check`, `cap.mint`, `cap.revoke`, `audit.append`) per strategy doc §4.2 | -| **Phase 1** | `agentkeys wire ` CLI + Hermes adapter | Single command that drops AgentKeys hook scripts into `~/.hermes/agent-hooks/` and appends the `hooks:` block to `~/.hermes/config.yaml` — three-act demo (Permissioned Memory / Deterministic Denial / Online Revocation per strategy doc §4.3). Full plan: [`docs/spec/plans/phase-1-fresh-user-wire-onboarding.md`](../spec/plans/phase-1-fresh-user-wire-onboarding.md) | +| **Phase 1** | `agentkeys wire ` CLI + Hermes adapter | Single command that drops AgentKeys hook scripts into `~/.hermes/agent-hooks/` and appends the `hooks:` block to `~/.hermes/config.yaml` — three-act demo (Permissioned Memory / Deterministic Denial / Online Revocation per strategy doc §4.3). Full plan: [`docs/plan/phase-1-fresh-user-wire-onboarding.md`](../plan/phase-1-fresh-user-wire-onboarding.md) | | **Phase 3** ([#133](https://github.com/litentry/agentKeys/issues/133)) | Hooks production | Reference hook configs for Hermes + Claude Code + Codex + OpenClaw; `agentkeys hook check` CLI helper; cap-mint pre-warming for sub-50ms p99 | | **Phase 3b** (after #133) | Proxy fallback | OpenAI-compatible proxy endpoint for hooks-less hosts (xiaozhi-server, vendor mobile chatbots). Lower priority. | | **Phase 4** | Standards | Propose MCP extensions for IAM-grade auth headers; OAuth-for-Agents engagement. Per strategy doc §5 Phase 5. | @@ -98,7 +98,7 @@ Rationale (anchored in [`agent-iam-strategy.md`](../../docs/agent-iam-strategy.m ## 6. Cross-references - [`docs/agent-iam-strategy.md`](../../docs/agent-iam-strategy.md) — strategic anchor: Authority Host vs Task Host (§2.1), zero-orchestration hard line (§2.4), MCP as integration surface (§2.3), Phase 1 MCP scope (§4.2), three-act demo (§4.3), 12-month roadmap (§5) -- [`docs/spec/plans/issue-103-aiosandbox-hermes-esp32-demo.md`](../spec/plans/issue-103-aiosandbox-hermes-esp32-demo.md) — execution plan for Phase 1 -- [`docs/spec/plans/phase-1-fresh-user-wire-onboarding.md`](../spec/plans/phase-1-fresh-user-wire-onboarding.md) — Phase 1 plan that ships the `agentkeys wire` CLI delivering these hooks (the previous operator-facing summary at `docs/demo-aiosandbox-runbook.md` §6 was archived 2026-05-28) +- [`docs/plan/issue-103-aiosandbox-hermes-esp32-demo.md`](../plan/issue-103-aiosandbox-hermes-esp32-demo.md) — execution plan for Phase 1 +- [`docs/plan/phase-1-fresh-user-wire-onboarding.md`](../plan/phase-1-fresh-user-wire-onboarding.md) — Phase 1 plan that ships the `agentkeys wire` CLI delivering these hooks (the previous operator-facing summary at `docs/demo-aiosandbox-runbook.md` §6 was archived 2026-05-28) - [Issue #133](https://github.com/litentry/agentKeys/issues/133) — Phase 3 LLM-host hook integration; the canonical track for the hooks deliverable - [Issue #103](https://github.com/litentry/agentKeys/issues/103) — Phase 1 demo umbrella diff --git a/firmware/esp32s3-agentkeys/README.md b/firmware/esp32s3-agentkeys/README.md index 0da25965..cdcbd468 100644 --- a/firmware/esp32s3-agentkeys/README.md +++ b/firmware/esp32s3-agentkeys/README.md @@ -95,6 +95,6 @@ firmware/esp32s3-agentkeys/ ## Related -- **Plan**: [`docs/spec/plans/issue-103-aiosandbox-hermes-esp32-demo.md`](../../docs/spec/plans/issue-103-aiosandbox-hermes-esp32-demo.md) +- **Plan**: [`docs/plan/issue-103-aiosandbox-hermes-esp32-demo.md`](../../docs/plan/issue-103-aiosandbox-hermes-esp32-demo.md) - **Sandbox-side runbook**: TBD (issue #103 step 12) - **AgentKeys arch**: [`docs/arch.md`](../../docs/arch.md) diff --git a/harness/phase1-wire-demo.sh b/harness/phase1-wire-demo.sh index cb16477a..69d216bc 100755 --- a/harness/phase1-wire-demo.sh +++ b/harness/phase1-wire-demo.sh @@ -4,7 +4,7 @@ # container (actor). Idempotent: every step pre-checks + short-circuits # (`ok proceeding` / `skip ` / `fail `). # -# Spec: docs/spec/plans/phase1-wire-harness-test-plan.md +# Spec: docs/plan/phase1-wire-harness-test-plan.md # # Two modes — you MUST pick ONE explicitly (there is NO default; running real # mode by accident flips the sandbox MCP to the live broker and loses the demo): diff --git a/pm/PROJECT-DASHBOARD-GUIDE.md b/pm/PROJECT-DASHBOARD-GUIDE.md index 3211bd31..16cffe85 100644 --- a/pm/PROJECT-DASHBOARD-GUIDE.md +++ b/pm/PROJECT-DASHBOARD-GUIDE.md @@ -341,7 +341,7 @@ bash pm/scripts/audit.sh # verify state ## Things the project board is NOT for -- **Source of truth for scope / requirements**: that's the issue body + linked design doc (`docs/research/*` or `docs/spec/plans/*`) +- **Source of truth for scope / requirements**: that's the issue body + linked design doc (`docs/research/*` or `docs/plan/*`) - **Real-time chat / debate**: use issue comments; project board is a queue, not a discussion forum - **Roadmap planning**: the milestones (`pm/milestones.json` + the GitHub Milestones page) are the roadmap; the board reflects them, doesn't define them - **Burndown charts / velocity metrics**: GitHub Projects has some basic insights but if you want real burndown, use a dedicated tool (Linear, Jira). For us, the milestone progress view + the audit script are sufficient. diff --git a/pm/README.md b/pm/README.md index 1585367c..fe09b9ac 100644 --- a/pm/README.md +++ b/pm/README.md @@ -10,7 +10,7 @@ Avoid hand-clicking the GitHub UI for **declarative** PM state. Milestones + lab The associated GitHub Project (private) is [`litentry/projects/19`](https://github.com/orgs/litentry/projects/19) — see [`PROJECT-DASHBOARD-GUIDE.md`](./PROJECT-DASHBOARD-GUIDE.md) for board usage. -The 7-milestone roadmap detail (M1-M7 + post-M7 horizons + strategic risks) lives in [`docs/spec/plans/milestones-roadmap.md`](../docs/spec/plans/milestones-roadmap.md) — the operational companion to [`docs/arch.md`](../docs/arch.md) (architecture) and [`docs/research/agent-iam-strategy.md`](../docs/research/agent-iam-strategy.md) (positioning). +The 7-milestone roadmap detail (M1-M7 + post-M7 horizons + strategic risks) lives in [`docs/plan/milestones-roadmap.md`](../docs/plan/milestones-roadmap.md) — the operational companion to [`docs/arch.md`](../docs/arch.md) (architecture) and [`docs/research/agent-iam-strategy.md`](../docs/research/agent-iam-strategy.md) (positioning). ## Files @@ -102,7 +102,7 @@ Repo labels are LEAN. Most categorization moved to project fields. Remaining lab | M6 | TEE integration + enhanced security | Phase 6 — production crypto hardening, key rotation depth | | M7 | Standards + ecosystem | Phase 7 — MCP extensions, OAuth-for-Agents, partnerships | -Full per-milestone detail in [`docs/spec/plans/milestones-roadmap.md`](../docs/spec/plans/milestones-roadmap.md). +Full per-milestone detail in [`docs/plan/milestones-roadmap.md`](../docs/plan/milestones-roadmap.md). ## Why JSON not YAML diff --git a/scripts/mcp-demo-mode-a.sh b/scripts/mcp-demo-mode-a.sh index 263117b5..33fceaa8 100755 --- a/scripts/mcp-demo-mode-a.sh +++ b/scripts/mcp-demo-mode-a.sh @@ -3,7 +3,7 @@ # # Boots `agentkeys-mcp-server --backend in-memory`, walks Acts 1/2/3, # asserts each act's expected JSON shape, then cleans up. Use this as -# the regression check for `docs/spec/plans/issue-107-mcp-demo-runbook.md` +# the regression check for `docs/plan/issue-107-mcp-demo-runbook.md` # §A — if any assertion fails, the runbook drifted from reality. # # Hardened per /codex:adversarial-review (2026-05-25): @@ -261,4 +261,4 @@ assert_eq "$(jread "$STUB" '.error.data.scheduled_for')" "M4" "scheduled_for: M4 echo echo "ALL ASSERTIONS PASSED." -echo " see docs/spec/plans/issue-107-mcp-demo-runbook.md for the full walkthrough." +echo " see docs/plan/issue-107-mcp-demo-runbook.md for the full walkthrough."