epic-12: after epic audit and init commit
This commit is contained in:
@@ -0,0 +1,662 @@
|
||||
---
|
||||
name: "Des Doc V0.1"
|
||||
description: "Design document with full layer diagrams"
|
||||
depth: 1
|
||||
links: ["../index.md", "./spec-v0.1.md"]
|
||||
---
|
||||
|
||||
harness design document
|
||||
|
||||
version: 0.1
|
||||
status: architectural draft
|
||||
|
||||
1. overview
|
||||
|
||||
Harness is a local-first orchestration runtime for structured LLM execution.
|
||||
|
||||
The system is designed around a strict separation of concerns:
|
||||
|
||||
layer| responsibility
|
||||
Router| conversational UX
|
||||
Harness| orchestration + policy
|
||||
Agent Runtime| task execution
|
||||
Model Manager| inference lifecycle
|
||||
Context Processor| memory synthesis
|
||||
Event Store| persistence + replay
|
||||
Tool Runtime| external actions
|
||||
|
||||
The architecture assumes:
|
||||
|
||||
- LLMs are probabilistic
|
||||
- context is expensive
|
||||
- memory must be externalized
|
||||
- workflows require validation
|
||||
- inference is transient
|
||||
- orchestration owns reliability
|
||||
|
||||
The system intentionally resembles operating system architecture more than chatbot architecture.
|
||||
|
||||
---
|
||||
|
||||
2. architectural goals
|
||||
|
||||
primary goals
|
||||
|
||||
- replayable execution
|
||||
- bounded autonomy
|
||||
- local-first operation
|
||||
- model/provider abstraction
|
||||
- deterministic-enough workflows
|
||||
- strict validation
|
||||
- structured artifacts
|
||||
- observability
|
||||
- hardware-aware scheduling
|
||||
|
||||
---
|
||||
|
||||
secondary goals
|
||||
|
||||
- distributed execution
|
||||
- remote provider failover
|
||||
- semantic memory
|
||||
- automatic evaluation
|
||||
- synthetic training data generation
|
||||
|
||||
---
|
||||
|
||||
3. system architecture
|
||||
|
||||
┌────────────────┐
|
||||
│ User │
|
||||
└───────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────┐
|
||||
│ Router │
|
||||
│ conversational facade │
|
||||
└──────────┬─────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ Harness │
|
||||
│ │
|
||||
│ ┌────────────┐ ┌────────────┐ ┌──────────────────┐ │
|
||||
│ │ Session │ │ Transition │ │ Approval Engine │ │
|
||||
│ │ Lifecycle │ │ Engine │ │ │ │
|
||||
│ └─────┬──────┘ └─────┬──────┘ └────────┬─────────┘ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌───────────────────────────────────────────────────┐ │
|
||||
│ │ Event Bus │ │
|
||||
│ └───────────────────────────────────────────────────┘ │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ Execution Layer │
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────────────────────┐ │
|
||||
│ │ StageRuntime │ │ ContextProcessor │ │
|
||||
│ └──────┬───────┘ └──────────────┬───────────────┘ │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌──────────────────────────────────────────────┐ │
|
||||
│ │ Agent Runtime │ │
|
||||
│ └──────────────────────┬───────────────────────┘ │
|
||||
└─────────────────────────┼────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ Inference Layer │
|
||||
│ │
|
||||
│ ┌───────────────┐ ┌────────────────────────────┐ │
|
||||
│ │ Model Manager │────▶│ Inference Providers │ │
|
||||
│ └───────────────┘ │ local / remote / hybrid │ │
|
||||
│ └────────────────────────────┘ │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────┐
|
||||
│ Tool Runtime │
|
||||
└────────────────┘
|
||||
|
||||
---
|
||||
|
||||
4. execution lifecycle
|
||||
|
||||
step 1 — user interaction
|
||||
|
||||
User communicates only with Router.
|
||||
|
||||
Router responsibilities:
|
||||
|
||||
- intent interpretation
|
||||
- steering ingestion
|
||||
- summarization
|
||||
- conversational continuity
|
||||
|
||||
Router never owns workflow state.
|
||||
|
||||
---
|
||||
|
||||
step 2 — session initialization
|
||||
|
||||
Harness:
|
||||
|
||||
- creates session
|
||||
- initializes projections
|
||||
- emits SessionCreated event
|
||||
- resolves workflow entry stage
|
||||
|
||||
---
|
||||
|
||||
step 3 — context synthesis
|
||||
|
||||
ContextProcessor:
|
||||
|
||||
- retrieves relevant events
|
||||
- compresses history
|
||||
- filters artifacts
|
||||
- injects policies
|
||||
- builds token budget
|
||||
|
||||
Output:
|
||||
|
||||
ContextPack
|
||||
|
||||
---
|
||||
|
||||
step 4 — stage execution
|
||||
|
||||
StageRuntime:
|
||||
|
||||
- resolves agent role
|
||||
- resolves required capabilities
|
||||
- acquires suitable model
|
||||
- executes inference
|
||||
|
||||
---
|
||||
|
||||
step 5 — artifact validation
|
||||
|
||||
Pipeline:
|
||||
|
||||
1. routing validation
|
||||
2. payload validation
|
||||
3. semantic validation
|
||||
4. approval validation
|
||||
|
||||
Only validated artifacts emit success transitions.
|
||||
|
||||
---
|
||||
|
||||
step 6 — transition evaluation
|
||||
|
||||
TransitionEngine:
|
||||
|
||||
- evaluates rule graph
|
||||
- emits transition event
|
||||
- schedules next stage
|
||||
|
||||
---
|
||||
|
||||
step 7 — replay + persistence
|
||||
|
||||
Every mutation:
|
||||
|
||||
- emits immutable event
|
||||
- updates projections
|
||||
- persists session state
|
||||
|
||||
---
|
||||
|
||||
5. event sourcing architecture
|
||||
|
||||
rationale
|
||||
|
||||
Event sourcing is mandatory because:
|
||||
|
||||
- LLM execution is nondeterministic
|
||||
- debugging requires replayability
|
||||
- context reconstruction must be deterministic
|
||||
- memory requires compression pipelines
|
||||
|
||||
---
|
||||
|
||||
event categories
|
||||
|
||||
DomainEvents
|
||||
InferenceEvents
|
||||
ToolEvents
|
||||
ApprovalEvents
|
||||
CompressionEvents
|
||||
LifecycleEvents
|
||||
SystemEvents
|
||||
|
||||
---
|
||||
|
||||
event flow
|
||||
|
||||
UserInputReceived
|
||||
↓
|
||||
StageScheduled
|
||||
↓
|
||||
ContextBuilt
|
||||
↓
|
||||
InferenceStarted
|
||||
↓
|
||||
ArtifactProduced
|
||||
↓
|
||||
ArtifactValidated
|
||||
↓
|
||||
ApprovalRequested
|
||||
↓
|
||||
TransitionExecuted
|
||||
|
||||
---
|
||||
|
||||
6. context processing design
|
||||
|
||||
core assumption
|
||||
|
||||
Raw conversational accumulation destroys smaller models.
|
||||
|
||||
Context must be:
|
||||
|
||||
- hierarchical
|
||||
- compressed
|
||||
- relevance-ranked
|
||||
- bounded
|
||||
|
||||
---
|
||||
|
||||
context layers
|
||||
|
||||
layer| meaning
|
||||
L0| live execution
|
||||
L1| active stage
|
||||
L2| compressed session memory
|
||||
L3| durable project memory
|
||||
L4| archival history
|
||||
|
||||
---
|
||||
|
||||
context synthesis pipeline
|
||||
|
||||
events
|
||||
↓
|
||||
deduplication
|
||||
↓
|
||||
relevance ranking
|
||||
↓
|
||||
semantic compression
|
||||
↓
|
||||
artifact extraction
|
||||
↓
|
||||
policy injection
|
||||
↓
|
||||
token budgeting
|
||||
↓
|
||||
ContextPack
|
||||
|
||||
---
|
||||
|
||||
compression rules
|
||||
|
||||
tool logs
|
||||
|
||||
Raw:
|
||||
|
||||
4000 lines shell output
|
||||
|
||||
Compressed:
|
||||
|
||||
pytest failed:
|
||||
- auth_test.py
|
||||
- timeout in token refresh
|
||||
|
||||
---
|
||||
|
||||
retention policy
|
||||
|
||||
data| strategy
|
||||
artifacts| latest valid
|
||||
tool logs| summarize
|
||||
conversation| semantic
|
||||
transitions| retain
|
||||
approvals| retain
|
||||
|
||||
---
|
||||
|
||||
7. model management
|
||||
|
||||
design goals
|
||||
|
||||
- limited hardware optimization
|
||||
- hot-swapping
|
||||
- GPU residency control
|
||||
- provider abstraction
|
||||
- inference isolation
|
||||
|
||||
---
|
||||
|
||||
model manager responsibilities
|
||||
|
||||
- model lifecycle
|
||||
- loading/unloading
|
||||
- GPU scheduling
|
||||
- swap timeout enforcement
|
||||
- health monitoring
|
||||
- concurrency limits
|
||||
|
||||
---
|
||||
|
||||
scheduling strategies
|
||||
|
||||
residency modes
|
||||
|
||||
mode| behavior
|
||||
persistent| never unload
|
||||
dynamic| unload after timeout
|
||||
ephemeral| unload immediately
|
||||
|
||||
---
|
||||
|
||||
capability routing
|
||||
|
||||
Stages do not request model names.
|
||||
|
||||
Stages request capabilities:
|
||||
|
||||
requirements:
|
||||
- coding
|
||||
- reasoning
|
||||
- tool_calling
|
||||
|
||||
Registry resolves:
|
||||
|
||||
- best local model
|
||||
- available GPU budget
|
||||
- fallback providers
|
||||
|
||||
---
|
||||
|
||||
8. agent runtime
|
||||
|
||||
design assumptions
|
||||
|
||||
Agents are:
|
||||
|
||||
- stateless
|
||||
- ephemeral
|
||||
- replaceable
|
||||
|
||||
Agents never:
|
||||
|
||||
- persist memory
|
||||
- mutate workflow state directly
|
||||
- own permissions
|
||||
|
||||
---
|
||||
|
||||
agent lifecycle
|
||||
|
||||
spawn
|
||||
↓
|
||||
receive ContextPack
|
||||
↓
|
||||
execute
|
||||
↓
|
||||
emit Artifact
|
||||
↓
|
||||
terminate
|
||||
|
||||
---
|
||||
|
||||
9. approval system
|
||||
|
||||
rationale
|
||||
|
||||
Autonomous systems require bounded risk.
|
||||
|
||||
Approval gates prevent:
|
||||
|
||||
- destructive execution
|
||||
- runaway automation
|
||||
- hidden escalation
|
||||
|
||||
---
|
||||
|
||||
approval tiers
|
||||
|
||||
tier| meaning
|
||||
T0| inference only
|
||||
T1| read-only
|
||||
T2| reversible mutation
|
||||
T3| external/network
|
||||
T4| destructive
|
||||
|
||||
---
|
||||
|
||||
steering-aware approvals
|
||||
|
||||
Approvals may inject corrective context.
|
||||
|
||||
Example:
|
||||
|
||||
approved, but verify migrations against staging schema first
|
||||
|
||||
Approval events become part of future context synthesis.
|
||||
|
||||
---
|
||||
|
||||
10. transition engine
|
||||
|
||||
rule-based execution
|
||||
|
||||
Transitions are declarative.
|
||||
|
||||
No workflow logic is hardcoded.
|
||||
|
||||
---
|
||||
|
||||
example
|
||||
|
||||
transitions:
|
||||
- when:
|
||||
artifact.status == "success"
|
||||
goto: validation
|
||||
|
||||
- when:
|
||||
retries > 3
|
||||
goto: failed
|
||||
|
||||
---
|
||||
|
||||
safeguards
|
||||
|
||||
Required:
|
||||
|
||||
- cycle detection
|
||||
- deadlock detection
|
||||
- transition tracing
|
||||
- graph visualization
|
||||
|
||||
---
|
||||
|
||||
11. validation system
|
||||
|
||||
layered validation
|
||||
|
||||
layer 1 — routing
|
||||
|
||||
Checks:
|
||||
|
||||
- stage compatibility
|
||||
- capability availability
|
||||
- policy alignment
|
||||
|
||||
---
|
||||
|
||||
layer 2 — schema
|
||||
|
||||
Pydantic validation:
|
||||
|
||||
- structure
|
||||
- typing
|
||||
- required fields
|
||||
|
||||
---
|
||||
|
||||
layer 3 — semantic
|
||||
|
||||
Checks:
|
||||
|
||||
- hallucinated paths
|
||||
- invalid references
|
||||
- unsafe commands
|
||||
- contradictory artifacts
|
||||
|
||||
---
|
||||
|
||||
layer 4 — approval
|
||||
|
||||
Checks:
|
||||
|
||||
- policy thresholds
|
||||
- user permissions
|
||||
- escalation rules
|
||||
|
||||
---
|
||||
|
||||
12. persistence model
|
||||
|
||||
storage backend
|
||||
|
||||
Default:
|
||||
|
||||
SQLite
|
||||
|
||||
Future:
|
||||
|
||||
- PostgreSQL
|
||||
- distributed event stores
|
||||
|
||||
---
|
||||
|
||||
persisted entities
|
||||
|
||||
entity| purpose
|
||||
events| source of truth
|
||||
projections| fast reads
|
||||
artifacts| outputs
|
||||
approvals| audit
|
||||
transitions| replay
|
||||
summaries| context synthesis
|
||||
|
||||
---
|
||||
|
||||
13. observability
|
||||
|
||||
required telemetry
|
||||
|
||||
- token usage
|
||||
- inference latency
|
||||
- stage duration
|
||||
- retries
|
||||
- approval frequency
|
||||
- tool failures
|
||||
- transition graphs
|
||||
|
||||
---
|
||||
|
||||
debugging features
|
||||
|
||||
- replay from cursor
|
||||
- event inspection
|
||||
- context inspection
|
||||
- transition trace
|
||||
- artifact lineage
|
||||
|
||||
---
|
||||
|
||||
14. security model
|
||||
|
||||
principles
|
||||
|
||||
- least privilege
|
||||
- explicit escalation
|
||||
- isolated execution
|
||||
- auditable actions
|
||||
|
||||
---
|
||||
|
||||
recommendations
|
||||
|
||||
- sandbox shell tools
|
||||
- filesystem allowlists
|
||||
- network policies
|
||||
- process isolation
|
||||
- execution timeouts
|
||||
- secret vault integration
|
||||
|
||||
---
|
||||
|
||||
15. scalability roadmap
|
||||
|
||||
v1
|
||||
|
||||
single-node:
|
||||
|
||||
- sqlite
|
||||
- local inference
|
||||
- sequential execution
|
||||
|
||||
---
|
||||
|
||||
v2
|
||||
|
||||
multi-provider:
|
||||
|
||||
- distributed workers
|
||||
- remote execution
|
||||
- shared event store
|
||||
|
||||
---
|
||||
|
||||
v3
|
||||
|
||||
adaptive orchestration:
|
||||
|
||||
- evaluator models
|
||||
- speculative execution
|
||||
- automatic routing optimization
|
||||
|
||||
---
|
||||
|
||||
16. architectural risks
|
||||
|
||||
risk| mitigation
|
||||
context entropy| aggressive compression
|
||||
workflow spaghetti| transition tracing
|
||||
infinite retries| bounded retry policies
|
||||
GPU thrashing| residency scheduler
|
||||
hallucinated execution| semantic validators
|
||||
hidden state| event sourcing
|
||||
|
||||
---
|
||||
|
||||
17. philosophy
|
||||
|
||||
Harness treats LLMs as bounded semantic processors embedded inside deterministic orchestration.
|
||||
|
||||
Reliability emerges from:
|
||||
|
||||
- validation
|
||||
- event sourcing
|
||||
- constrained execution
|
||||
- context synthesis
|
||||
- approval systems
|
||||
- replayability
|
||||
|
||||
not from trusting model intelligence alone.
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
name: "Funure Semantic Rules"
|
||||
description: "Placeholder for future semantic validation rules"
|
||||
depth: 1
|
||||
links: ["../index.md"]
|
||||
---
|
||||
|
||||
potential rules later:
|
||||
stage reachability consistency vs session expectations
|
||||
invalid artifact flow constraints
|
||||
agent binding completeness
|
||||
tool availability mismatch
|
||||
policy timeout sanity checks
|
||||
@@ -0,0 +1,361 @@
|
||||
---
|
||||
name: "Lang Framewok Missing Pieces"
|
||||
description: "Language/framework recommendations and missing subsystems"
|
||||
depth: 1
|
||||
links: ["../index.md", "./spec-v0.1.md"]
|
||||
---
|
||||
|
||||
language:
|
||||
use Kotlin.
|
||||
|
||||
not because it’s trendy, but because architecture is inherently:
|
||||
|
||||
* state-heavy
|
||||
* concurrency-heavy
|
||||
* schema-heavy
|
||||
* event-heavy
|
||||
* validation-heavy
|
||||
|
||||
that maps extremely well to:
|
||||
|
||||
* sealed hierarchies
|
||||
* coroutines
|
||||
* structured concurrency
|
||||
* immutable data classes
|
||||
* serialization
|
||||
* type-safe DSLs
|
||||
|
||||
avoid:
|
||||
* Python as primary runtime
|
||||
* TypeScript as orchestration core
|
||||
|
||||
they’re excellent glue languages, but this system is closer to:
|
||||
* a workflow engine
|
||||
* an orchestration runtime
|
||||
* a distributed state machine
|
||||
than an app backend.
|
||||
|
||||
kotlin gives:
|
||||
* better long-term maintainability
|
||||
* safer concurrency
|
||||
* better event typing
|
||||
* cleaner DSLs
|
||||
* stronger replay guarantees
|
||||
|
||||
framework stack
|
||||
core runtime:
|
||||
* plain kotlin first
|
||||
* minimal framework dependence
|
||||
|
||||
web/api:
|
||||
* [Ktor](https://ktor.io?utm_source=chatgpt.com)
|
||||
|
||||
reasons:
|
||||
* coroutine-native
|
||||
* lightweight
|
||||
* excellent websocket support
|
||||
* no spring complexity
|
||||
* easy embedding
|
||||
* modular
|
||||
|
||||
do NOT use:
|
||||
* [Spring Boot](https://spring.io/projects/spring-boot?utm_source=chatgpt.com)
|
||||
spring will slowly eat the architecture:
|
||||
* hidden lifecycle
|
||||
* implicit DI magic
|
||||
* reflection-heavy
|
||||
* runtime complexity
|
||||
* startup overhead
|
||||
* difficult deterministic control
|
||||
system wants explicit orchestration.
|
||||
|
||||
persistence:
|
||||
* [Exposed](https://github.com/JetBrains/Exposed?utm_source=chatgpt.com) OR plain SQL
|
||||
* [SQLite](https://www.sqlite.org/index.html?utm_source=chatgpt.com) initially
|
||||
* migrate later to [PostgreSQL](https://www.postgresql.org/?utm_source=chatgpt.com)
|
||||
|
||||
serialization:
|
||||
* [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization?utm_source=chatgpt.com)
|
||||
|
||||
config:
|
||||
* [Hoplite](https://github.com/sksamuel/hoplite?utm_source=chatgpt.com)
|
||||
or
|
||||
* [Typesafe Config](https://github.com/lightbend/config?utm_source=chatgpt.com)
|
||||
|
||||
logging:
|
||||
* structured logging ONLY
|
||||
* json logs
|
||||
* correlation ids everywhere
|
||||
|
||||
CLI:
|
||||
* [Clikt](https://ajalt.github.io/clikt/?utm_source=chatgpt.com)
|
||||
|
||||
TUI:
|
||||
* honestly optional initially.
|
||||
* if needed later:
|
||||
|
||||
* [Mordant](https://github.com/ajalt/mordant?utm_source=chatgpt.com)
|
||||
* or web dashboard instead
|
||||
|
||||
web UI:
|
||||
frontend:
|
||||
* [SvelteKit](https://svelte.dev/docs/kit/introduction?utm_source=chatgpt.com)
|
||||
|
||||
not react.
|
||||
|
||||
reasons:
|
||||
* simpler state model
|
||||
* less boilerplate
|
||||
* lower memory
|
||||
* faster iteration
|
||||
* easier websocket/event-stream integration
|
||||
|
||||
ui should behave like:
|
||||
* workflow inspector
|
||||
* event debugger
|
||||
* replay console
|
||||
* orchestration monitor
|
||||
|
||||
NOT “chatgpt clone ui”.
|
||||
|
||||
transport:
|
||||
* websocket first
|
||||
* event-stream oriented
|
||||
|
||||
REST only for:
|
||||
* management
|
||||
* configs
|
||||
* health
|
||||
* exports
|
||||
|
||||
real-time state should be event-driven.
|
||||
|
||||
architecture split
|
||||
important:
|
||||
core MUST NOT depend on infrastructure.
|
||||
only interfaces/ports.
|
||||
hexagonal architecture fits this system very well.
|
||||
|
||||
recommended internal layering
|
||||
domain layer
|
||||
pure logic:
|
||||
* events
|
||||
* transitions
|
||||
* policies
|
||||
* approvals
|
||||
* artifacts
|
||||
* projections
|
||||
* session state
|
||||
|
||||
NO IO.
|
||||
|
||||
application/service layer
|
||||
orchestration:
|
||||
* stage execution
|
||||
* replay coordination
|
||||
* context synthesis
|
||||
* validation pipeline
|
||||
* routing
|
||||
|
||||
infrastructure layer
|
||||
actual implementations:
|
||||
* sqlite
|
||||
* llama.cpp
|
||||
* shell execution
|
||||
* websocket
|
||||
* filesystem
|
||||
|
||||
interface layer
|
||||
external access:
|
||||
* cli
|
||||
* api
|
||||
* ui
|
||||
* websocket
|
||||
|
||||
plugin layer
|
||||
dynamic extensibility.
|
||||
missing pieces in the spec
|
||||
|
||||
1. scheduler subsystem
|
||||
|
||||
* queueing
|
||||
* prioritization
|
||||
* cancellation
|
||||
* starvation prevention
|
||||
* concurrency caps
|
||||
* backpressure
|
||||
|
||||
eventually:
|
||||
```text id="on4q1p"
|
||||
StageScheduled
|
||||
StageDeferred
|
||||
StageBlocked
|
||||
StagePreempted
|
||||
```
|
||||
|
||||
2. capability negotiation
|
||||
currently:
|
||||
stage requests capabilities.
|
||||
|
||||
but models/tools/providers should advertise:
|
||||
|
||||
* hard capabilities
|
||||
* soft capabilities
|
||||
* confidence
|
||||
* limits
|
||||
|
||||
example:
|
||||
|
||||
```yaml id="w4h8b4"
|
||||
coding:
|
||||
score: 0.92
|
||||
reasoning:
|
||||
score: 0.61
|
||||
tool_calling:
|
||||
score: 0.74
|
||||
```
|
||||
|
||||
otherwise routing becomes binary and crude.
|
||||
|
||||
3. deterministic tool contracts
|
||||
|
||||
VERY important.
|
||||
|
||||
tools should never return freeform text internally.
|
||||
|
||||
tool outputs must be typed.
|
||||
|
||||
bad:
|
||||
|
||||
```json id="v4g2pr"
|
||||
"pytest failed due to auth issue"
|
||||
```
|
||||
|
||||
good:
|
||||
|
||||
```json id="i08vuj"
|
||||
{
|
||||
"failed_tests": [
|
||||
{
|
||||
"file": "auth_test.py",
|
||||
"reason": "timeout"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
models can consume summaries.
|
||||
harness consumes structure.
|
||||
|
||||
4. model sandboxing
|
||||
|
||||
define explicitly:
|
||||
|
||||
* max execution time
|
||||
* max tokens
|
||||
* max context
|
||||
* max retries
|
||||
* cancellation semantics
|
||||
* kill signals
|
||||
* watchdogs
|
||||
|
||||
otherwise local models WILL hang eventually.
|
||||
|
||||
5. config versioning/migrations
|
||||
|
||||
absolutely need:
|
||||
|
||||
```yaml id="v0i3qf"
|
||||
config_version: 1
|
||||
```
|
||||
|
||||
plus migration system.
|
||||
|
||||
6. projection snapshots
|
||||
|
||||
replaying 100k events eventually becomes painful.
|
||||
|
||||
need:
|
||||
|
||||
* periodic snapshots
|
||||
* projection checkpoints
|
||||
* replay cursors
|
||||
|
||||
classic event sourcing problem.
|
||||
|
||||
7. artifact lineage graph
|
||||
|
||||
this one is important and often missed.
|
||||
|
||||
artifacts should track:
|
||||
|
||||
* parent artifacts
|
||||
* originating events
|
||||
* tool receipts
|
||||
* approvals
|
||||
* validator passes
|
||||
|
||||
this enables:
|
||||
|
||||
* blame tracing
|
||||
* replay diffing
|
||||
* synthetic training extraction
|
||||
|
||||
8. state machine formalization
|
||||
|
||||
session lifecycle should become an explicit finite state machine.
|
||||
|
||||
not enums.
|
||||
|
||||
otherwise invalid transitions creep in later.
|
||||
|
||||
9. policy engine
|
||||
|
||||
currently mixed into approvals/validation.
|
||||
|
||||
should probably become its own subsystem.
|
||||
|
||||
because eventually policies will govern:
|
||||
|
||||
* tools
|
||||
* providers
|
||||
* models
|
||||
* routing
|
||||
* retries
|
||||
* approvals
|
||||
* networking
|
||||
* secrets
|
||||
* filesystem access
|
||||
|
||||
10. trust boundaries
|
||||
|
||||
* model boundary
|
||||
* tool boundary
|
||||
* plugin boundary
|
||||
* provider boundary
|
||||
* ui boundary
|
||||
|
||||
especially if third-party plugins become possible later.
|
||||
|
||||
big recommendation
|
||||
```text
|
||||
everything important is append-only
|
||||
```
|
||||
|
||||
events:
|
||||
append-only
|
||||
|
||||
artifacts:
|
||||
immutable
|
||||
|
||||
receipts:
|
||||
immutable
|
||||
|
||||
approvals:
|
||||
immutable
|
||||
|
||||
summaries:
|
||||
versioned
|
||||
|
||||
projections:
|
||||
rebuildable
|
||||
@@ -0,0 +1,672 @@
|
||||
---
|
||||
name: "Spec V0.1"
|
||||
description: "Early system specification (Harness v0.1)"
|
||||
depth: 1
|
||||
links: ["../index.md", "../architecture/overview.md"]
|
||||
---
|
||||
|
||||
harness architecture specification
|
||||
|
||||
version: 0.1-draft
|
||||
|
||||
1. purpose
|
||||
|
||||
Harness is a config-driven orchestration runtime for local and remote LLM workflows.
|
||||
|
||||
The system treats models as interchangeable execution engines while the Harness owns:
|
||||
|
||||
- lifecycle
|
||||
- memory
|
||||
- orchestration
|
||||
- permissions
|
||||
- validation
|
||||
- event sourcing
|
||||
- workflow transitions
|
||||
- context synthesis
|
||||
|
||||
Primary goals:
|
||||
|
||||
- deterministic-enough execution on nondeterministic models
|
||||
- local-first operation
|
||||
- replayable execution
|
||||
- bounded autonomy
|
||||
- strong observability
|
||||
- minimal human steering
|
||||
- model/provider agnosticism
|
||||
|
||||
Non-goals:
|
||||
|
||||
- AGI simulation
|
||||
- unconstrained autonomous agents
|
||||
- hidden implicit memory
|
||||
- permanently accumulating context
|
||||
|
||||
---
|
||||
|
||||
2. architecture overview
|
||||
|
||||
┌──────────────────────────┐
|
||||
│ User │
|
||||
└────────────┬─────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────┐
|
||||
│ Router │
|
||||
│ conversational interface │
|
||||
└────────────┬─────────────┘
|
||||
│ summaries
|
||||
▼
|
||||
┌──────────────────────────┐
|
||||
│ Harness │
|
||||
│ orchestration kernel │
|
||||
│ event bus │
|
||||
│ approval engine │
|
||||
│ lifecycle owner │
|
||||
└────────────┬─────────────┘
|
||||
│
|
||||
┌───────┴────────┐
|
||||
▼ ▼
|
||||
┌───────────┐ ┌────────────┐
|
||||
│ Stage │ │ Context │
|
||||
│ Runtime │ │ Processor │
|
||||
└─────┬─────┘ └─────┬──────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────────────────┐
|
||||
│ Agent Runtime │
|
||||
└────────────┬─────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────┐
|
||||
│ Inference Layer │
|
||||
│ local / remote models │
|
||||
└────────────┬─────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────┐
|
||||
│ Tools │
|
||||
└──────────────────────────┘
|
||||
|
||||
---
|
||||
|
||||
3. core principles
|
||||
|
||||
3.1 event sourced
|
||||
|
||||
All system state is reconstructable from events.
|
||||
|
||||
No mutable hidden memory exists outside event projections.
|
||||
|
||||
Benefits:
|
||||
|
||||
- replayability
|
||||
- deterministic debugging
|
||||
- auditability
|
||||
- recovery
|
||||
- analytics
|
||||
- synthetic dataset generation
|
||||
|
||||
---
|
||||
|
||||
3.2 models are stateless
|
||||
|
||||
Models do not own:
|
||||
|
||||
- memory
|
||||
- workflow state
|
||||
- permissions
|
||||
- lifecycle
|
||||
|
||||
Models receive synthesized context only.
|
||||
|
||||
---
|
||||
|
||||
3.3 validation-first execution
|
||||
|
||||
Every agent output is validated at multiple levels:
|
||||
|
||||
1. routing validation
|
||||
2. payload schema validation
|
||||
3. semantic validation
|
||||
4. approval validation
|
||||
|
||||
Invalid artifacts cannot progress workflow state.
|
||||
|
||||
---
|
||||
|
||||
3.4 context is synthesized
|
||||
|
||||
Raw accumulation is forbidden.
|
||||
|
||||
All context is:
|
||||
|
||||
- filtered
|
||||
- deduplicated
|
||||
- compressed
|
||||
- summarized
|
||||
- relevance-ranked
|
||||
|
||||
---
|
||||
|
||||
4. terminology
|
||||
|
||||
term| meaning
|
||||
Harness| orchestration kernel
|
||||
Router| conversational interface layer
|
||||
Stage| workflow state
|
||||
Agent| execution worker
|
||||
Role| semantic responsibility
|
||||
Artifact| validated structured output
|
||||
Transition| movement between stages
|
||||
Event| immutable state mutation
|
||||
Projection| derived state view
|
||||
Context Pack| synthesized model input
|
||||
Approval Gate| human/system checkpoint
|
||||
|
||||
---
|
||||
|
||||
5. configuration system
|
||||
|
||||
5.1 config locations
|
||||
|
||||
Global:
|
||||
|
||||
~/.config/harness/
|
||||
|
||||
Project-local:
|
||||
|
||||
./.harness/
|
||||
|
||||
Precedence:
|
||||
|
||||
project > user > defaults
|
||||
|
||||
---
|
||||
|
||||
5.2 config files
|
||||
|
||||
harness.yaml
|
||||
models.yaml
|
||||
tools.yaml
|
||||
stages.yaml
|
||||
policies.yaml
|
||||
compression.yaml
|
||||
|
||||
---
|
||||
|
||||
6. model registry
|
||||
|
||||
6.1 model definition
|
||||
|
||||
models:
|
||||
qwen_coder_14b:
|
||||
provider: local
|
||||
path: /models/qwen-coder.gguf
|
||||
|
||||
capabilities:
|
||||
- coding
|
||||
- tool_calling
|
||||
- reasoning
|
||||
|
||||
context_size: 32768
|
||||
|
||||
kv_cache:
|
||||
quantization: q8_0
|
||||
|
||||
gpu:
|
||||
layers: 48
|
||||
residency: dynamic
|
||||
swap_timeout_sec: 300
|
||||
|
||||
inference:
|
||||
temperature: 0.2
|
||||
top_p: 0.9
|
||||
repeat_penalty: 1.1
|
||||
|
||||
limits:
|
||||
max_parallel_sessions: 2
|
||||
|
||||
---
|
||||
|
||||
7. providers
|
||||
|
||||
7.1 local provider
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- llama.cpp process management
|
||||
- GPU residency
|
||||
- model loading/unloading
|
||||
- warm pools
|
||||
- swap scheduling
|
||||
- health monitoring
|
||||
|
||||
---
|
||||
|
||||
7.2 remote provider
|
||||
|
||||
providers:
|
||||
openai_compatible:
|
||||
base_url: https://api.example.com/v1
|
||||
api_key_env: HARNESS_API_KEY
|
||||
|
||||
extra:
|
||||
timeout: 120
|
||||
retries: 3
|
||||
|
||||
---
|
||||
|
||||
8. stages
|
||||
|
||||
Stages define execution states.
|
||||
|
||||
Example:
|
||||
|
||||
stages:
|
||||
implementation:
|
||||
role: coder
|
||||
|
||||
requirements:
|
||||
- coding
|
||||
- tool_calling
|
||||
|
||||
allowed_tools:
|
||||
- filesystem
|
||||
- git
|
||||
- shell
|
||||
|
||||
approvals:
|
||||
tool_tier_3: required
|
||||
|
||||
transitions:
|
||||
on_success:
|
||||
- validation
|
||||
on_failure:
|
||||
- retry
|
||||
|
||||
---
|
||||
|
||||
9. agents
|
||||
|
||||
Agents are ephemeral execution workers.
|
||||
|
||||
Agents:
|
||||
|
||||
- consume Context Packs
|
||||
- emit Artifacts
|
||||
- do not persist memory
|
||||
|
||||
---
|
||||
|
||||
10. router
|
||||
|
||||
Router responsibilities:
|
||||
|
||||
- user interaction
|
||||
- conversational continuity
|
||||
- summarizing system state
|
||||
- steering interpretation
|
||||
|
||||
Router is always available but not persistent in execution context.
|
||||
|
||||
Execution agents unload router context during active work.
|
||||
|
||||
After completion:
|
||||
|
||||
- outputs are summarized
|
||||
- summaries are injected into router memory
|
||||
|
||||
---
|
||||
|
||||
11. artifacts
|
||||
|
||||
All stage outputs MUST emit structured artifacts.
|
||||
|
||||
Example:
|
||||
|
||||
class ImplementationArtifact(BaseModel):
|
||||
summary: str
|
||||
modified_files: list[str]
|
||||
risks: list[str]
|
||||
commands_executed: list[str]
|
||||
next_recommendation: str
|
||||
|
||||
---
|
||||
|
||||
12. validation pipeline
|
||||
|
||||
12.1 routing validation
|
||||
|
||||
Checks:
|
||||
|
||||
- valid stage transitions
|
||||
- capability compatibility
|
||||
- policy compliance
|
||||
|
||||
---
|
||||
|
||||
12.2 payload validation
|
||||
|
||||
Pydantic validation:
|
||||
|
||||
- schema correctness
|
||||
- required fields
|
||||
- typing
|
||||
|
||||
---
|
||||
|
||||
12.3 semantic validation
|
||||
|
||||
Checks:
|
||||
|
||||
- contradictory outputs
|
||||
- hallucinated files
|
||||
- invalid commands
|
||||
- policy violations
|
||||
- unsafe operations
|
||||
|
||||
---
|
||||
|
||||
13. approval system
|
||||
|
||||
13.1 approval tiers
|
||||
|
||||
tier| meaning
|
||||
T0| inference only
|
||||
T1| read-only
|
||||
T2| reversible mutation
|
||||
T3| external/network
|
||||
T4| destructive
|
||||
|
||||
---
|
||||
|
||||
13.2 approval modes
|
||||
|
||||
mode| meaning
|
||||
prompt| require confirmation
|
||||
auto| auto approve
|
||||
deny| reject automatically
|
||||
yolo| bypass safeguards
|
||||
|
||||
---
|
||||
|
||||
13.3 approval actions
|
||||
|
||||
User may:
|
||||
|
||||
- approve
|
||||
- reject
|
||||
- auto-approve for session
|
||||
- steer execution
|
||||
|
||||
Example:
|
||||
|
||||
approved, but verify auth edge cases first
|
||||
|
||||
---
|
||||
|
||||
14. event system
|
||||
|
||||
14.1 event categories
|
||||
|
||||
DomainEvents
|
||||
SystemEvents
|
||||
InferenceEvents
|
||||
ToolEvents
|
||||
ApprovalEvents
|
||||
CompressionEvents
|
||||
LifecycleEvents
|
||||
|
||||
---
|
||||
|
||||
14.2 event structure
|
||||
|
||||
class Event(BaseModel):
|
||||
id: UUID
|
||||
session_id: UUID
|
||||
timestamp: datetime
|
||||
type: str
|
||||
payload: dict
|
||||
causation_id: UUID | None
|
||||
correlation_id: UUID | None
|
||||
|
||||
---
|
||||
|
||||
15. replay system
|
||||
|
||||
Replay modes:
|
||||
|
||||
- full replay
|
||||
- partial replay
|
||||
- replay from cursor
|
||||
- inference-skipping replay
|
||||
- deterministic simulation
|
||||
|
||||
Replay reconstructs projections and workflow state.
|
||||
|
||||
---
|
||||
|
||||
16. context processor
|
||||
|
||||
The ContextProcessor synthesizes minimal relevant context.
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- deduplication
|
||||
- summarization
|
||||
- ranking
|
||||
- token budgeting
|
||||
- artifact extraction
|
||||
- tool compression
|
||||
|
||||
---
|
||||
|
||||
16.1 context layers
|
||||
|
||||
L0 live execution
|
||||
L1 stage-local context
|
||||
L2 compressed session memory
|
||||
L3 project memory
|
||||
L4 archival history
|
||||
|
||||
---
|
||||
|
||||
16.2 compression strategies
|
||||
|
||||
compression:
|
||||
tool_logs:
|
||||
mode: summarize
|
||||
|
||||
artifacts:
|
||||
mode: latest_only
|
||||
|
||||
events:
|
||||
mode: deduplicate
|
||||
|
||||
conversations:
|
||||
mode: semantic_summary
|
||||
|
||||
---
|
||||
|
||||
17. tool system
|
||||
|
||||
Tools are config-driven and capability-scoped.
|
||||
|
||||
Default tools may be:
|
||||
|
||||
- disabled
|
||||
- replaced
|
||||
- overridden
|
||||
|
||||
Example:
|
||||
|
||||
tools:
|
||||
shell:
|
||||
enabled: true
|
||||
tier: T2
|
||||
|
||||
git:
|
||||
enabled: true
|
||||
tier: T2
|
||||
|
||||
curl:
|
||||
enabled: true
|
||||
tier: T3
|
||||
|
||||
---
|
||||
|
||||
18. transitions
|
||||
|
||||
Transitions are rule-based.
|
||||
|
||||
No hardcoded workflow graphs exist in code.
|
||||
|
||||
Example:
|
||||
|
||||
transitions:
|
||||
- when:
|
||||
artifact.status == "success"
|
||||
goto: validation
|
||||
|
||||
- when:
|
||||
retries > 3
|
||||
goto: failed
|
||||
|
||||
---
|
||||
|
||||
19. retry policies
|
||||
|
||||
19.1 strategies
|
||||
|
||||
strategy| behavior
|
||||
retry| retry execution
|
||||
fail_safe| skip and continue
|
||||
fail_fast| terminate session
|
||||
|
||||
---
|
||||
|
||||
19.2 retry configuration
|
||||
|
||||
retry:
|
||||
strategy: corrective
|
||||
max_attempts: 3
|
||||
inject_failure_reason: true
|
||||
temperature_backoff: true
|
||||
|
||||
---
|
||||
|
||||
20. persistence
|
||||
|
||||
Default persistence:
|
||||
|
||||
SQLite
|
||||
|
||||
Future:
|
||||
|
||||
- PostgreSQL
|
||||
- event stores
|
||||
- distributed backends
|
||||
|
||||
Persisted:
|
||||
|
||||
- events
|
||||
- projections
|
||||
- artifacts
|
||||
- approvals
|
||||
- transitions
|
||||
- summaries
|
||||
|
||||
---
|
||||
|
||||
21. session lifecycle
|
||||
|
||||
Harness owns session lifecycle.
|
||||
|
||||
States:
|
||||
created
|
||||
active
|
||||
paused
|
||||
awaiting_approval
|
||||
failed
|
||||
completed
|
||||
cancelled
|
||||
|
||||
---
|
||||
|
||||
22. observability
|
||||
|
||||
Required:
|
||||
|
||||
- event tracing
|
||||
- transition tracing
|
||||
- inference timing
|
||||
- token accounting
|
||||
- tool execution logs
|
||||
- replay diagnostics
|
||||
|
||||
Recommended:
|
||||
|
||||
- DAG visualization
|
||||
- live stage graph
|
||||
- approval history
|
||||
|
||||
---
|
||||
|
||||
23. security model
|
||||
|
||||
Principles:
|
||||
|
||||
- least privilege
|
||||
- explicit approvals
|
||||
- isolated tools
|
||||
- auditability
|
||||
- bounded execution
|
||||
|
||||
Recommendations:
|
||||
|
||||
- sandbox shell tools
|
||||
- filesystem allowlists
|
||||
- network policy control
|
||||
- secret isolation
|
||||
- execution timeouts
|
||||
|
||||
---
|
||||
|
||||
24. future extensions
|
||||
|
||||
Potential:
|
||||
|
||||
- distributed agents
|
||||
- evaluator models
|
||||
- speculative execution
|
||||
- long-term semantic memory
|
||||
- automatic fine-tuning corpus extraction
|
||||
- capability benchmarking
|
||||
- adaptive routing
|
||||
|
||||
---
|
||||
|
||||
25. anti-goals
|
||||
|
||||
Avoid:
|
||||
|
||||
- hidden prompts
|
||||
- invisible memory mutation
|
||||
- unrestricted recursion
|
||||
- self-modifying workflows
|
||||
- implicit approvals
|
||||
- context accumulation without compression
|
||||
- permanent agent processes
|
||||
|
||||
---
|
||||
|
||||
26. philosophy summary
|
||||
|
||||
Harness is not an “AI agent framework”.
|
||||
|
||||
It is:
|
||||
|
||||
- an orchestration kernel
|
||||
- an event-sourced execution runtime
|
||||
- a bounded autonomy system
|
||||
- a deterministic shell around probabilistic cognition
|
||||
@@ -0,0 +1,361 @@
|
||||
---
|
||||
name: "Structure"
|
||||
description: "Repository and module directory structure"
|
||||
depth: 1
|
||||
links: ["../index.md", "../modules/modules-and-spec.md"]
|
||||
---
|
||||
|
||||
```text
|
||||
correx/
|
||||
│
|
||||
├── apps/ # runnable entrypoints
|
||||
│ ├── cli/ # clikt-based cli
|
||||
│ ├── server/ # ktor api + websocket server
|
||||
│ ├── worker/ # future distributed executor
|
||||
│ └── desktop/ # optional later
|
||||
│
|
||||
├── core/ # PURE DOMAIN + ORCHESTRATION
|
||||
│ │
|
||||
│ ├── kernel/ # orchestration brain
|
||||
│ │ ├── SessionOrchestrator.kt
|
||||
│ │ ├── WorkflowCoordinator.kt
|
||||
│ │ ├── ExecutionScheduler.kt
|
||||
│ │ └── RuntimeSupervisor.kt
|
||||
│ │
|
||||
│ ├── events/ # event sourcing primitives
|
||||
│ │ ├── model/
|
||||
│ │ ├── store/
|
||||
│ │ ├── append/
|
||||
│ │ ├── replay/
|
||||
│ │ ├── snapshot/
|
||||
│ │ └── projection/
|
||||
│ │
|
||||
│ ├── transitions/ # workflow graph engine
|
||||
│ │ ├── engine/
|
||||
│ │ ├── dsl/
|
||||
│ │ ├── parser/
|
||||
│ │ ├── validator/
|
||||
│ │ ├── graph/
|
||||
│ │ └── conditions/
|
||||
│ │
|
||||
│ ├── context/ # context synthesis
|
||||
│ │ ├── layers/
|
||||
│ │ ├── ranking/
|
||||
│ │ ├── compression/
|
||||
│ │ ├── budgeting/
|
||||
│ │ ├── summarization/
|
||||
│ │ ├── dedup/
|
||||
│ │ └── builders/
|
||||
│ │
|
||||
│ ├── inference/ # model abstraction
|
||||
│ │ ├── contracts/
|
||||
│ │ ├── routing/
|
||||
│ │ ├── scheduling/
|
||||
│ │ ├── lifecycle/
|
||||
│ │ ├── capabilities/
|
||||
│ │ └── isolation/
|
||||
│ │
|
||||
│ ├── stages/ # stage runtime
|
||||
│ │ ├── runtime/
|
||||
│ │ ├── execution/
|
||||
│ │ ├── registry/
|
||||
│ │ └── resolution/
|
||||
│ │
|
||||
│ ├── agents/ # ephemeral execution wrappers
|
||||
│ │ ├── runtime/
|
||||
│ │ ├── spawning/
|
||||
│ │ ├── contracts/
|
||||
│ │ └── teardown/
|
||||
│ │
|
||||
│ ├── artifacts/ # structured outputs
|
||||
│ │ ├── model/
|
||||
│ │ ├── schemas/
|
||||
│ │ ├── lineage/
|
||||
│ │ ├── validation/
|
||||
│ │ └── serialization/
|
||||
│ │
|
||||
│ ├── validation/ # layered validation
|
||||
│ │ ├── routing/
|
||||
│ │ ├── schema/
|
||||
│ │ ├── semantic/
|
||||
│ │ ├── policy/
|
||||
│ │ ├── approvals/
|
||||
│ │ └── pipeline/
|
||||
│ │
|
||||
│ ├── approvals/ # approval engine
|
||||
│ │ ├── tiers/
|
||||
│ │ ├── policies/
|
||||
│ │ ├── escalation/
|
||||
│ │ ├── steering/
|
||||
│ │ └── decisions/
|
||||
│ │
|
||||
│ ├── tools/ # tool orchestration
|
||||
│ │ ├── contracts/
|
||||
│ │ ├── runtime/
|
||||
│ │ ├── receipts/
|
||||
│ │ ├── sandbox/
|
||||
│ │ └── registry/
|
||||
│ │
|
||||
│ ├── router/ # conversational facade
|
||||
│ │ ├── memory/
|
||||
│ │ ├── interpretation/
|
||||
│ │ ├── summarization/
|
||||
│ │ └── steering/
|
||||
│ │
|
||||
│ ├── sessions/ # lifecycle + fsm
|
||||
│ │ ├── lifecycle/
|
||||
│ │ ├── state/
|
||||
│ │ ├── projections/
|
||||
│ │ └── recovery/
|
||||
│ │
|
||||
│ ├── policies/ # separate policy engine
|
||||
│ │ ├── evaluation/
|
||||
│ │ ├── enforcement/
|
||||
│ │ ├── filesystem/
|
||||
│ │ ├── network/
|
||||
│ │ └── execution/
|
||||
│ │
|
||||
│ ├── observability/
|
||||
│ │ ├── tracing/
|
||||
│ │ ├── metrics/
|
||||
│ │ ├── diagnostics/
|
||||
│ │ ├── event_inspection/
|
||||
│ │ └── replay_debugging/
|
||||
│ │
|
||||
│ └── config/
|
||||
│ ├── loading/
|
||||
│ ├── validation/
|
||||
│ ├── migrations/
|
||||
│ ├── defaults/
|
||||
│ └── schemas/
|
||||
│
|
||||
├── infrastructure/ # IO + implementations
|
||||
│ │
|
||||
│ ├── persistence/
|
||||
│ │ ├── sqlite/
|
||||
│ │ ├── postgres/
|
||||
│ │ ├── snapshots/
|
||||
│ │ └── migrations/
|
||||
│ │
|
||||
│ ├── inference/
|
||||
│ │ ├── llama_cpp/
|
||||
│ │ ├── ollama/
|
||||
│ │ ├── vllm/
|
||||
│ │ ├── openai_compatible/
|
||||
│ │ └── mock/
|
||||
│ │
|
||||
│ ├── tools/
|
||||
│ │ ├── shell/
|
||||
│ │ ├── git/
|
||||
│ │ ├── filesystem/
|
||||
│ │ ├── docker/
|
||||
│ │ ├── network/
|
||||
│ │ └── sandboxing/
|
||||
│ │
|
||||
│ ├── security/
|
||||
│ │ ├── secrets/
|
||||
│ │ ├── isolation/
|
||||
│ │ ├── allowlists/
|
||||
│ │ └── permissions/
|
||||
│ │
|
||||
│ ├── scheduler/
|
||||
│ │ ├── queues/
|
||||
│ │ ├── concurrency/
|
||||
│ │ ├── throttling/
|
||||
│ │ └── backpressure/
|
||||
│ │
|
||||
│ └── telemetry/
|
||||
│ ├── logging/
|
||||
│ ├── tracing/
|
||||
│ └── exporters/
|
||||
│
|
||||
├── interfaces/ # transport + api contracts
|
||||
│ │
|
||||
│ ├── api/
|
||||
│ │ ├── rest/
|
||||
│ │ ├── websocket/
|
||||
│ │ ├── dto/
|
||||
│ │ ├── mapping/
|
||||
│ │ └── auth/
|
||||
│ │
|
||||
│ ├── cli/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── formatting/
|
||||
│ │ ├── interactive/
|
||||
│ │ └── progress/
|
||||
│ │
|
||||
│ └── sdk/
|
||||
│ ├── client/
|
||||
│ └── protocol/
|
||||
│
|
||||
├── plugins/ # extension ecosystem
|
||||
│ │
|
||||
│ ├── tools/
|
||||
│ ├── validators/
|
||||
│ ├── compressors/
|
||||
│ ├── providers/
|
||||
│ ├── transitions/
|
||||
│ ├── stages/
|
||||
│ └── policies/
|
||||
│
|
||||
├── frontend/ # sveltekit ui
|
||||
│ │
|
||||
│ ├── src/
|
||||
│ │ ├── routes/
|
||||
│ │ ├── lib/
|
||||
│ │ ├── components/
|
||||
│ │ ├── stores/
|
||||
│ │ ├── websocket/
|
||||
│ │ └── visualizations/
|
||||
│ │
|
||||
│ └── static/
|
||||
│
|
||||
├── testing/
|
||||
│ ├── replay/
|
||||
│ ├── integration/
|
||||
│ ├── fixtures/
|
||||
│ ├── projections/
|
||||
│ ├── transitions/
|
||||
│ ├── approvals/
|
||||
│ └── deterministic/
|
||||
│
|
||||
├── docs/
|
||||
│ ├── architecture/
|
||||
│ ├── events/
|
||||
│ ├── transitions/
|
||||
│ ├── plugins/
|
||||
│ ├── configs/
|
||||
│ └── threat_model/
|
||||
│
|
||||
└── examples/
|
||||
├── workflows/
|
||||
├── configs/
|
||||
├── plugins/
|
||||
└── stages/
|
||||
```
|
||||
|
||||
architecturally:
|
||||
|
||||
```text
|
||||
ui/cli/api
|
||||
↓
|
||||
interfaces layer
|
||||
↓
|
||||
application/orchestration layer
|
||||
↓
|
||||
domain/core layer
|
||||
↓
|
||||
ports/contracts
|
||||
↓
|
||||
infrastructure layer
|
||||
```
|
||||
|
||||
rules:
|
||||
|
||||
* core NEVER imports infrastructure
|
||||
* infrastructure implements ports/interfaces from core
|
||||
* plugins only talk through contracts
|
||||
* ui never touches persistence directly
|
||||
* projections are rebuildable only from events
|
||||
* tools never mutate state directly
|
||||
* models never own memory/state
|
||||
* router never owns execution state
|
||||
|
||||
important internal split
|
||||
|
||||
1. domain/core (pure deterministic logic)
|
||||
|
||||
contains:
|
||||
|
||||
* events
|
||||
* transitions
|
||||
* projections
|
||||
* approvals
|
||||
* policies
|
||||
* artifact definitions
|
||||
* session fsm
|
||||
|
||||
must be:
|
||||
|
||||
* testable without IO
|
||||
* replayable
|
||||
* deterministic
|
||||
|
||||
2. application layer
|
||||
|
||||
contains:
|
||||
|
||||
* orchestration
|
||||
* workflow execution
|
||||
* context building
|
||||
* retries
|
||||
* scheduling
|
||||
* coordination
|
||||
|
||||
this is the “brain”.
|
||||
|
||||
3. infrastructure layer
|
||||
|
||||
contains:
|
||||
|
||||
* sqlite
|
||||
* llama.cpp
|
||||
* shell
|
||||
* websocket
|
||||
* filesystem
|
||||
* network
|
||||
|
||||
replaceable adapters only.
|
||||
|
||||
4. interface layer
|
||||
|
||||
contains:
|
||||
|
||||
* cli
|
||||
* web api
|
||||
* websocket protocol
|
||||
* sdk
|
||||
|
||||
thin wrappers only.
|
||||
|
||||
most important subsystem boundaries
|
||||
|
||||
event system
|
||||
source of truth.
|
||||
|
||||
projection system
|
||||
derived/read models only.
|
||||
|
||||
transition engine
|
||||
pure deterministic graph executor.
|
||||
|
||||
context processor
|
||||
stateless synthesizer.
|
||||
|
||||
validation pipeline
|
||||
hard gatekeeper.
|
||||
|
||||
approval engine
|
||||
risk boundary.
|
||||
|
||||
tool runtime
|
||||
isolated side effects.
|
||||
|
||||
model manager
|
||||
resource scheduler.
|
||||
|
||||
router
|
||||
human-facing facade only.
|
||||
|
||||
if implemented correctly, you should eventually be able to:
|
||||
|
||||
* replay entire sessions deterministically
|
||||
* swap model providers without touching orchestration
|
||||
* rebuild every projection from events
|
||||
* run headless without UI
|
||||
* replace frontend entirely
|
||||
* distribute workers later
|
||||
* test most logic without inference
|
||||
* fuzz transitions/approvals safely
|
||||
|
||||
that’s usually the sign the boundaries are correct.
|
||||
Reference in New Issue
Block a user