10 KiB
name, description, depth, links
| name | description | depth | links | ||
|---|---|---|---|---|---|
| Spec V0.1 | Early system specification (Harness v0.1) | 1 |
|
harness architecture specification
version: 0.1-draft
- 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
- 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 │ └──────────────────────────┘
- 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:
- routing validation
- payload schema validation
- semantic validation
- 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
- 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
- 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
- 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
- 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
- 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
- agents
Agents are ephemeral execution workers.
Agents:
- consume Context Packs
- emit Artifacts
- do not persist memory
- 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
- 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
- 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
- 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
- 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
- replay system
Replay modes:
- full replay
- partial replay
- replay from cursor
- inference-skipping replay
- deterministic simulation
Replay reconstructs projections and workflow state.
- 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
- 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
- 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
- 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
- persistence
Default persistence:
SQLite
Future:
- PostgreSQL
- event stores
- distributed backends
Persisted:
- events
- projections
- artifacts
- approvals
- transitions
- summaries
- session lifecycle
Harness owns session lifecycle.
States: created active paused awaiting_approval failed completed cancelled
- observability
Required:
- event tracing
- transition tracing
- inference timing
- token accounting
- tool execution logs
- replay diagnostics
Recommended:
- DAG visualization
- live stage graph
- approval history
- 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
- future extensions
Potential:
- distributed agents
- evaluator models
- speculative execution
- long-term semantic memory
- automatic fine-tuning corpus extraction
- capability benchmarking
- adaptive routing
- anti-goals
Avoid:
- hidden prompts
- invisible memory mutation
- unrestricted recursion
- self-modifying workflows
- implicit approvals
- context accumulation without compression
- permanent agent processes
- 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