# placidoe/agent-deck-harness-core architecture

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

- Interactive diagram: https://gitdiagram.com/placidoe/agent-deck-harness-core
- Repository: https://github.com/placidoe/agent-deck-harness-core

## Overview

Agent Deck Harness Core is a provider-neutral runtime and SDK for reliable long-horizon agent runs. A caller starts or resumes a run; the harness asks a Manager for a bounded contract, assembles referenced context, sends it to an Executor, then submits the execution and state to an independent Auditor. It applies evidence-backed ledger updates and only completes when requirements are verified with clean integrity and no blockers; otherwise it can request human attention. State snapshots and append-only events support restart and observability. The README documents additional planned capabilities, but adapters, routing, retrieval, and scheduling are not implemented.

Main entry points: [`src/harness.ts`](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/harness.ts) (AgentHarness), [`src/types.ts`](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts) (RunStore contract), [`src/store.ts`](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/store.ts) (Memory store), [`src/context.ts`](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/context.ts) (Context builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Run orchestration"]
  node_harness["AgentHarness<br/>[harness.ts]"]
  node_context["Context builder<br/>[context.ts]"]
  node_metrics["Call metrics<br/>[types.ts]"]
  node_index["SDK exports<br/>[index.ts]"]
end

subgraph group_ledger["Verified ledger"]
  node_ledger["Run state ledger<br/>[types.ts]"]
  node_evidence["Evidence records<br/>[types.ts]"]
  node_requirements["Requirements<br/>[types.ts]"]
  node_facts["Facts and artifacts<br/>[types.ts]"]
  node_blockers["Blockers and attention<br/>[types.ts]"]
end

subgraph group_persistence["Run persistence"]
  node_store["RunStore contract<br/>[types.ts]"]
  node_memory[("Memory store<br/>[store.ts]")]
  node_jsonfile[("JSON file store<br/>[store.ts]")]
  node_events["Event stream<br/>[types.ts]"]
end

subgraph group_contracts["Provider contracts"]
  node_manager["Manager<br/>[types.ts]"]
  node_executor["Executor<br/>[types.ts]"]
  node_auditor["Auditor<br/>[types.ts]"]
end

node_caller(("SDK caller"))

node_caller -->|"imports SDK"| node_index
node_index -->|"exports"| node_harness
node_caller -->|"starts or resumes"| node_harness
node_harness -->|"loads and saves"| node_store
node_store -->|"implemented by"| node_memory
node_store -->|"implemented by"| node_jsonfile
node_harness -->|"requests decision"| node_manager
node_manager -->|"returns decision"| node_harness
node_harness -->|"assembles context"| node_context
node_context -->|"selects references"| node_ledger
node_harness -->|"dispatches contract"| node_executor
node_harness -->|"submits execution"| node_auditor
node_auditor -->|"returns audit"| node_harness
node_harness -->|"applies updates"| node_requirements
node_harness -->|"records evidence"| node_evidence
node_harness -->|"upserts records"| node_facts
node_harness -->|"sets attention"| node_blockers
node_harness -->|"records timings"| node_metrics
node_harness -->|"appends events"| node_events
node_harness -->|"emits events"| node_caller
node_memory -->|"stores snapshots"| node_ledger
node_memory -->|"stores events"| node_events
node_jsonfile -->|"writes snapshots"| node_ledger
node_jsonfile -->|"appends JSONL"| node_events

click node_harness "https://github.com/placidoe/agent-deck-harness-core/blob/main/src/harness.ts"
click node_manager "https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts"
click node_executor "https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts"
click node_auditor "https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts"
click node_context "https://github.com/placidoe/agent-deck-harness-core/blob/main/src/context.ts"
click node_ledger "https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts"
click node_evidence "https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts"
click node_requirements "https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts"
click node_facts "https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts"
click node_blockers "https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts"
click node_metrics "https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts"
click node_store "https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts"
click node_memory "https://github.com/placidoe/agent-deck-harness-core/blob/main/src/store.ts"
click node_jsonfile "https://github.com/placidoe/agent-deck-harness-core/blob/main/src/store.ts"
click node_events "https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts"
click node_index "https://github.com/placidoe/agent-deck-harness-core/blob/main/src/index.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_harness,node_context,node_metrics,node_index toneBlue
class node_ledger,node_evidence,node_requirements,node_facts,node_blockers toneAmber
class node_store,node_memory,node_jsonfile,node_events toneMint
class node_manager,node_executor,node_auditor toneRose
class node_caller toneIndigo
```

## Components

### Run orchestration

- [AgentHarness](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/harness.ts): `src/harness.ts`
- [Context builder](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/context.ts): `src/context.ts`
- [Call metrics](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts): `src/types.ts`
- [SDK exports](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/index.ts): `src/index.ts`

### Verified ledger

- [Run state ledger](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts): `src/types.ts`
- [Evidence records](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts): `src/types.ts`
- [Requirements](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts): `src/types.ts`
- [Facts and artifacts](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts): `src/types.ts`
- [Blockers and attention](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts): `src/types.ts`

### Run persistence

- [RunStore contract](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts): `src/types.ts`
- [Memory store](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/store.ts): `src/store.ts`
- [JSON file store](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/store.ts): `src/store.ts`
- [Event stream](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts): `src/types.ts`

### Provider contracts

- [Manager](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts): `src/types.ts`
- [Executor](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts): `src/types.ts`
- [Auditor](https://github.com/placidoe/agent-deck-harness-core/blob/main/src/types.ts): `src/types.ts`

### Other components

- **SDK caller**

## Connections

- SDK caller → SDK exports: imports SDK
- SDK exports → AgentHarness: exports
- SDK caller → AgentHarness: starts or resumes
- AgentHarness → RunStore contract: loads and saves
- RunStore contract → Memory store: implemented by
- RunStore contract → JSON file store: implemented by
- AgentHarness → Manager: requests decision
- Manager → AgentHarness: returns decision
- AgentHarness → Context builder: assembles context
- Context builder → Run state ledger: selects references
- AgentHarness → Executor: dispatches contract
- AgentHarness → Auditor: submits execution
- Auditor → AgentHarness: returns audit
- AgentHarness → Requirements: applies updates
- AgentHarness → Evidence records: records evidence
- AgentHarness → Facts and artifacts: upserts records
- AgentHarness → Blockers and attention: sets attention
- AgentHarness → Call metrics: records timings
- AgentHarness → Event stream: appends events
- AgentHarness → SDK caller: emits events
- Memory store → Run state ledger: stores snapshots
- Memory store → Event stream: stores events
- JSON file store → Run state ledger: writes snapshots
- JSON file store → Event stream: appends JSONL