# dami904/dreamkeeper architecture

> Architecture diagram of the GitHub repository dami904/dreamkeeper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dami904/dreamkeeper
- Repository: https://github.com/dami904/dreamkeeper

## Overview

DreamKeeper is a safety and execution layer for Daydreams agents that submit value-moving actions through KeeperHub or a direct onchain fallback. The principal flow is agent → registered actions → client preflight and execution → transport, with reconciliation for uncertain outcomes. Separate capabilities include conditional check-and-execute, curated protocol actions, Tempo hold/release/cancel, audit and trust reporting, and spending-limit queries. Source excerpts show the client’s firewall, idempotency, and persistence responsibilities; some wiring for other listed subsystems is inferred only from documented product capabilities and is left unlinked where ownership is not evident.

Main entry points: [`packages/core/src/keeperhub/client.ts`](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/keeperhub/client.ts) (KeeperHub Client), [`packages/core/src/daydreams/actions.ts`](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/daydreams/actions.ts) (Agent Actions), [`packages/core/src/keeperhub/transport.ts`](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/keeperhub/transport.ts) (Transport Interface), [`packages/core/src/daydreams/extension.ts`](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/daydreams/extension.ts) (DreamKeeper Extension)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Agent Integration"]
  node_extension["DreamKeeper Extension<br/>[extension.ts]"]
  node_actions["Agent Actions<br/>[actions.ts]"]
end

subgraph group_safety["Safety Controls"]
  node_validator["Firewall Validator<br/>[validator.ts]"]
  node_invariants["Preflight Invariants<br/>[invariants.ts]"]
  node_breaker["Circuit Breaker<br/>[circuit-breaker.ts]"]
end

subgraph group_execution["Execution"]
  node_client["KeeperHub Client<br/>[client.ts]"]
  node_transport["Transport Interface<br/>[transport.ts]"]
  node_live["KeeperHub Transport<br/>[live-transport.ts]"]
  node_mock["Mock Transport<br/>[mock-transport.ts]"]
  node_onchain["Onchain Fallback"]
  node_tempo["Tempo Payments<br/>[client.ts]"]
  node_protocol["Protocol Actions<br/>[actions.ts]"]
end

subgraph group_state["State and Reporting"]
  node_ledger[("Trust Ledger<br/>[trust-ledger.ts]")]
  node_idempotency[("Idempotency Store<br/>[idempotency.ts]")]
  node_stateflow["Execution State Machine<br/>[state-machine.ts]"]
  node_filestore[("File Persistence<br/>[file-store.ts]")]
  node_reporting["Audit and Trust Reports<br/>[actions.ts]"]
end

node_agent(("Daydreams Agent"))
node_daydreams(("Daydreams Runtime"))
node_keeperhub{{"KeeperHub Service"}}
node_chain{{"Blockchain RPC"}}

node_agent -->|"submits intent"| node_daydreams
node_daydreams -->|"loads extension"| node_extension
node_extension -->|"creates client"| node_client
node_extension -->|"registers actions"| node_actions
node_agent -->|"invokes tools"| node_actions
node_actions -->|"calls operations"| node_client
node_client -->|"validates intents"| node_validator
node_client -->|"checks execution gate"| node_breaker
node_client -->|"records trust events"| node_ledger
node_client -->|"checks keys"| node_idempotency
node_client -->|"tracks outcomes"| node_stateflow
node_client -->|"dispatches operations"| node_transport
node_client -->|"persists snapshots"| node_filestore
node_transport -->|"implemented by"| node_live
node_transport -->|"implemented by"| node_mock
node_transport -.->|"implemented by"| node_onchain
node_live -->|"calls tools"| node_keeperhub
node_onchain -->|"reads and broadcasts"| node_chain
node_client -->|"manages holds"| node_tempo
node_actions -->|"exposes curated calls"| node_protocol
node_actions -->|"exposes queries"| node_reporting

click node_extension "https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/daydreams/extension.ts"
click node_actions "https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/daydreams/actions.ts"
click node_client "https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/keeperhub/client.ts"
click node_validator "https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/firewall/validator.ts"
click node_invariants "https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/firewall/invariants.ts"
click node_breaker "https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/firewall/circuit-breaker.ts"
click node_ledger "https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/firewall/trust-ledger.ts"
click node_transport "https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/keeperhub/transport.ts"
click node_live "https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/keeperhub/live-transport.ts"
click node_mock "https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/keeperhub/mock-transport.ts"
click node_onchain "https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/keeperhub/onchain-transport.ts"
click node_idempotency "https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/keeperhub/idempotency.ts"
click node_stateflow "https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/keeperhub/state-machine.ts"
click node_filestore "https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/persistence/file-store.ts"
click node_tempo "https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/keeperhub/client.ts"
click node_protocol "https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/daydreams/actions.ts"
click node_reporting "https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/daydreams/actions.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extension,node_actions toneBlue
class node_validator,node_invariants,node_breaker toneAmber
class node_client,node_transport,node_live,node_mock,node_onchain,node_tempo,node_protocol toneMint
class node_ledger,node_idempotency,node_stateflow,node_filestore,node_reporting toneRose
class node_agent,node_daydreams,node_keeperhub,node_chain toneIndigo
```

## Components

### Agent Integration

- [DreamKeeper Extension](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/daydreams/extension.ts): `packages/core/src/daydreams/extension.ts`
- [Agent Actions](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/daydreams/actions.ts): `packages/core/src/daydreams/actions.ts`

### Safety Controls

- [Firewall Validator](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/firewall/validator.ts): `packages/core/src/firewall/validator.ts`
- [Preflight Invariants](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/firewall/invariants.ts): `packages/core/src/firewall/invariants.ts`
- [Circuit Breaker](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/firewall/circuit-breaker.ts): `packages/core/src/firewall/circuit-breaker.ts`

### Execution

- [KeeperHub Client](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/keeperhub/client.ts): `packages/core/src/keeperhub/client.ts`
- [Transport Interface](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/keeperhub/transport.ts): `packages/core/src/keeperhub/transport.ts`
- [KeeperHub Transport](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/keeperhub/live-transport.ts): `packages/core/src/keeperhub/live-transport.ts`
- [Mock Transport](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/keeperhub/mock-transport.ts): `packages/core/src/keeperhub/mock-transport.ts`
- [Onchain Fallback](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/keeperhub/onchain-transport.ts): `packages/core/src/keeperhub/onchain-transport.ts`
- [Tempo Payments](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/keeperhub/client.ts): `packages/core/src/keeperhub/client.ts`
- [Protocol Actions](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/daydreams/actions.ts): `packages/core/src/daydreams/actions.ts`

### State and Reporting

- [Trust Ledger](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/firewall/trust-ledger.ts): `packages/core/src/firewall/trust-ledger.ts`
- [Idempotency Store](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/keeperhub/idempotency.ts): `packages/core/src/keeperhub/idempotency.ts`
- [Execution State Machine](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/keeperhub/state-machine.ts): `packages/core/src/keeperhub/state-machine.ts`
- [File Persistence](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/persistence/file-store.ts): `packages/core/src/persistence/file-store.ts`
- [Audit and Trust Reports](https://github.com/dami904/dreamkeeper/blob/main/packages/core/src/daydreams/actions.ts): `packages/core/src/daydreams/actions.ts`

### Other components

- **Daydreams Agent**
- **Daydreams Runtime**
- **KeeperHub Service**
- **Blockchain RPC**

## Connections

- Daydreams Agent → Daydreams Runtime: submits intent
- Daydreams Runtime → DreamKeeper Extension: loads extension
- DreamKeeper Extension → KeeperHub Client: creates client
- DreamKeeper Extension → Agent Actions: registers actions
- Daydreams Agent → Agent Actions: invokes tools
- Agent Actions → KeeperHub Client: calls operations
- KeeperHub Client → Firewall Validator: validates intents
- KeeperHub Client → Circuit Breaker: checks execution gate
- KeeperHub Client → Trust Ledger: records trust events
- KeeperHub Client → Idempotency Store: checks keys
- KeeperHub Client → Execution State Machine: tracks outcomes
- KeeperHub Client → Transport Interface: dispatches operations
- KeeperHub Client → File Persistence: persists snapshots
- Transport Interface → KeeperHub Transport: implemented by
- Transport Interface → Mock Transport: implemented by
- Transport Interface → Onchain Fallback: implemented by
- KeeperHub Transport → KeeperHub Service: calls tools
- Onchain Fallback → Blockchain RPC: reads and broadcasts
- KeeperHub Client → Tempo Payments: manages holds
- Agent Actions → Protocol Actions: exposes curated calls
- Agent Actions → Audit and Trust Reports: exposes queries