# huiliyi37/tianshu-harness architecture

> Architecture diagram of the GitHub repository huiliyi37/tianshu-harness, 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/huiliyi37/tianshu-harness
- Repository: https://github.com/huiliyi37/tianshu-harness

## Overview

Tianshu Harness is a coding-agent runtime with terminal and desktop interfaces, designed to keep goals, state, evidence, and completion checks under runtime control. The principal workflow is user request → turn orchestration and model reasoning → tool execution and observation → evidence-backed delivery. The graph also preserves documented memory, planning, multi-agent, caching, and external-tool capabilities. README documentation supports several capability links; sampled source confirms selected internals, but does not expose all orchestration wiring.

Main entry points: [`src/agent/turn-orchestrator.ts`](https://github.com/huiliyi37/tianshu-harness/blob/main/src/agent/turn-orchestrator.ts) (Turn orchestration), [`src/agent/tool-pipeline.ts`](https://github.com/huiliyi37/tianshu-harness/blob/main/src/agent/tool-pipeline.ts) (Tool pipeline), [`src/cli/entry.ts`](https://github.com/huiliyi37/tianshu-harness/blob/main/src/cli/entry.ts) (CLI entry), [`src/prompt/engine.ts`](https://github.com/huiliyi37/tianshu-harness/blob/main/src/prompt/engine.ts) (Prompt and context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_cli["CLI entry<br/>[entry.ts]"]
  node_tui["Terminal UI<br/>[live-engine.ts]"]
  node_desktop["Desktop client"]
end

subgraph group_runtime["Cognitive runtime"]
  node_turn["Turn orchestration"]
  node_hooks["Runtime hooks<br/>[runtime-hooks.ts]"]
  node_contract["Task contract<br/>[task-contract.ts]"]
  node_prompt["Prompt and context<br/>[engine.ts]"]
  node_cache["Prefix cache<br/>[index.ts]"]
end

subgraph group_execution["Task execution"]
  node_plan["Plan workflow<br/>[plan-approval.ts]"]
  node_workers["Agent coordination"]
  node_tools["Tool pipeline<br/>[tool-pipeline.ts]"]
  node_evidence["Evidence and delivery<br/>[deliver-task.ts]"]
end

subgraph group_state["Session and memory"]
  node_session[("Session state<br/>[session-state.ts]")]
  node_memory[("Project memory<br/>[unified-memory.ts]")]
end

subgraph group_integrations["Models and tools"]
  node_provider["Model provider API<br/>[factory.ts]"]
  node_models(("Foundation models"))
  node_mcp["MCP tools<br/>[manager.ts]"]
  node_lsp["Language servers<br/>[manager.ts]"]
end

node_user(("Developer"))

node_user -->|"submits task"| node_cli
node_cli -->|"starts session"| node_turn
node_turn -->|"tracks goal"| node_contract
node_turn -->|"runs supervision"| node_hooks
node_turn -->|"builds context"| node_prompt
node_prompt -->|"maintains prefix"| node_cache
node_turn -->|"requests completion"| node_provider
node_provider -->|"sends requests"| node_models
node_turn -->|"dispatches actions"| node_tools
node_tools -->|"records verification"| node_evidence
node_evidence -->|"gates delivery"| node_turn
node_turn -->|"updates state"| node_session
node_turn -->|"uses memory"| node_memory
node_turn -->|"supports planning"| node_plan
node_turn -->|"coordinates agents"| node_workers
node_tools -->|"invokes servers"| node_mcp
node_tools -->|"uses diagnostics"| node_lsp
node_cli -->|"renders terminal"| node_tui
node_desktop -.->|"shares runtime"| node_turn

click node_cli "https://github.com/huiliyi37/tianshu-harness/blob/main/src/cli/entry.ts"
click node_tui "https://github.com/huiliyi37/tianshu-harness/blob/main/src/tui/engine/live-engine.ts"
click node_turn "https://github.com/huiliyi37/tianshu-harness/blob/main/src/agent/turn-orchestrator.ts"
click node_hooks "https://github.com/huiliyi37/tianshu-harness/blob/main/src/agent/runtime-hooks.ts"
click node_contract "https://github.com/huiliyi37/tianshu-harness/blob/main/src/context/task-contract.ts"
click node_prompt "https://github.com/huiliyi37/tianshu-harness/blob/main/src/prompt/engine.ts"
click node_cache "https://github.com/huiliyi37/tianshu-harness/blob/main/src/cache/index.ts"
click node_plan "https://github.com/huiliyi37/tianshu-harness/blob/main/src/plan/plan-approval.ts"
click node_workers "https://github.com/huiliyi37/tianshu-harness/blob/main/src/agent/team-orchestrator.ts"
click node_tools "https://github.com/huiliyi37/tianshu-harness/blob/main/src/agent/tool-pipeline.ts"
click node_evidence "https://github.com/huiliyi37/tianshu-harness/blob/main/src/agent/deliver-task.ts"
click node_session "https://github.com/huiliyi37/tianshu-harness/blob/main/src/agent/session-state.ts"
click node_memory "https://github.com/huiliyi37/tianshu-harness/blob/main/src/memory/unified-memory.ts"
click node_provider "https://github.com/huiliyi37/tianshu-harness/blob/main/src/api/factory.ts"
click node_mcp "https://github.com/huiliyi37/tianshu-harness/blob/main/src/mcp/manager.ts"
click node_lsp "https://github.com/huiliyi37/tianshu-harness/blob/main/src/lsp/manager.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_cli,node_tui,node_desktop toneBlue
class node_turn,node_hooks,node_contract,node_prompt,node_cache toneAmber
class node_plan,node_workers,node_tools,node_evidence toneMint
class node_session,node_memory toneRose
class node_provider,node_models,node_mcp,node_lsp,node_user toneIndigo
```

## Components

### User experience

- [CLI entry](https://github.com/huiliyi37/tianshu-harness/blob/main/src/cli/entry.ts): `src/cli/entry.ts`
- [Terminal UI](https://github.com/huiliyi37/tianshu-harness/blob/main/src/tui/engine/live-engine.ts): `src/tui/engine/live-engine.ts`
- **Desktop client**

### Cognitive runtime

- [Turn orchestration](https://github.com/huiliyi37/tianshu-harness/blob/main/src/agent/turn-orchestrator.ts): `src/agent/turn-orchestrator.ts`
- [Runtime hooks](https://github.com/huiliyi37/tianshu-harness/blob/main/src/agent/runtime-hooks.ts): `src/agent/runtime-hooks.ts`
- [Task contract](https://github.com/huiliyi37/tianshu-harness/blob/main/src/context/task-contract.ts): `src/context/task-contract.ts`
- [Prompt and context](https://github.com/huiliyi37/tianshu-harness/blob/main/src/prompt/engine.ts): `src/prompt/engine.ts`
- [Prefix cache](https://github.com/huiliyi37/tianshu-harness/blob/main/src/cache/index.ts): `src/cache/index.ts`

### Task execution

- [Plan workflow](https://github.com/huiliyi37/tianshu-harness/blob/main/src/plan/plan-approval.ts): `src/plan/plan-approval.ts`
- [Agent coordination](https://github.com/huiliyi37/tianshu-harness/blob/main/src/agent/team-orchestrator.ts): `src/agent/team-orchestrator.ts`
- [Tool pipeline](https://github.com/huiliyi37/tianshu-harness/blob/main/src/agent/tool-pipeline.ts): `src/agent/tool-pipeline.ts`
- [Evidence and delivery](https://github.com/huiliyi37/tianshu-harness/blob/main/src/agent/deliver-task.ts): `src/agent/deliver-task.ts`

### Session and memory

- [Session state](https://github.com/huiliyi37/tianshu-harness/blob/main/src/agent/session-state.ts): `src/agent/session-state.ts`
- [Project memory](https://github.com/huiliyi37/tianshu-harness/blob/main/src/memory/unified-memory.ts): `src/memory/unified-memory.ts`

### Models and tools

- [Model provider API](https://github.com/huiliyi37/tianshu-harness/blob/main/src/api/factory.ts): `src/api/factory.ts`
- **Foundation models**
- [MCP tools](https://github.com/huiliyi37/tianshu-harness/blob/main/src/mcp/manager.ts): `src/mcp/manager.ts`
- [Language servers](https://github.com/huiliyi37/tianshu-harness/blob/main/src/lsp/manager.ts): `src/lsp/manager.ts`

### Other components

- **Developer**

## Connections

- Developer → CLI entry: submits task
- CLI entry → Turn orchestration: starts session
- Turn orchestration → Task contract: tracks goal
- Turn orchestration → Runtime hooks: runs supervision
- Turn orchestration → Prompt and context: builds context
- Prompt and context → Prefix cache: maintains prefix
- Turn orchestration → Model provider API: requests completion
- Model provider API → Foundation models: sends requests
- Turn orchestration → Tool pipeline: dispatches actions
- Tool pipeline → Evidence and delivery: records verification
- Evidence and delivery → Turn orchestration: gates delivery
- Turn orchestration → Session state: updates state
- Turn orchestration → Project memory: uses memory
- Turn orchestration → Plan workflow: supports planning
- Turn orchestration → Agent coordination: coordinates agents
- Tool pipeline → MCP tools: invokes servers
- Tool pipeline → Language servers: uses diagnostics
- CLI entry → Terminal UI: renders terminal
- Desktop client → Turn orchestration: shares runtime