README
¶
contextmatrix-harness
The FSM-free engine that drives one LLM session: an agentic tool-use loop plus the model client, tool registry, secret redaction, and event stream it needs — and nothing about what the session is for.
This module is consumed by both backends in the ContextMatrix ecosystem:
- contextmatrix-agent wraps it with a task FSM (
orchestrator/worker) to execute board cards. - contextmatrix-chat wraps it with an interactive driver using the Inbox, compaction, and seeded-history surfaces to power chat sessions.
Packages
| Package | Responsibility |
|---|---|
events |
typed event stream → stdout + JSON transcript |
llm |
raw-HTTP OpenAI-compatible client (default OpenRouter): Send/SendStream, SSE, models[] failover |
tools |
jailed filesystem/shell Tool registry, read-only subset, Skill tool |
harness |
the loop: Run, Verify, SpawnSubagents, the Inbox seam, Config |
redact |
literal-secret masking, injected into the loop via Config.RedactToolOutput |
Boundary invariant
harness imports only events, llm, tools (+ stdlib). The module as a
whole has zero external module dependencies. Both rules are enforced in CI by
scripts/deps-gate.sh (make deps-gate). Keep the loop free of orchestration,
protocol, transport, and policy concerns — those belong in the consuming backend.
Entry points
harness.Run, harness.Config, harness.Inbox, harness.Result,
events.Emitter, tools.Registry, tools.Tool, llm.LLM, llm.Catalog.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package events defines the harness event stream: a sequence of typed events written human-readably to stdout and as JSON lines to a transcript.
|
Package events defines the harness event stream: a sequence of typed events written human-readably to stdout and as JSON lines to a transcript. |
|
Package llm is a raw-HTTP, OpenAI-compatible client for OpenRouter or any OpenAI-compatible endpoint behind a narrow Send/SendStream interface.
|
Package llm is a raw-HTTP, OpenAI-compatible client for OpenRouter or any OpenAI-compatible endpoint behind a narrow Send/SendStream interface. |
|
Package redact masks known literal secret values in strings before they reach the model, the event stream, transcripts, or log frames.
|
Package redact masks known literal secret values in strings before they reach the model, the event stream, transcripts, or log frames. |
|
Package tools provides the harness tool registry and a small set of filesystem/shell tools, each jailed to a workspace root.
|
Package tools provides the harness tool registry and a small set of filesystem/shell tools, each jailed to a workspace root. |
Click to show internal directories.
Click to hide internal directories.