Skip to content

Commit 00b0ecd

Browse files
EvanAI0331EvanAI0331
committed
Package Harness as Codex plugin
0 parents  commit 00b0ecd

496 files changed

Lines changed: 104796 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/plugins/marketplace.json‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"name": "harness-codex-marketplace",
3+
"plugins": [
4+
{
5+
"name": "harness-codex-plugin",
6+
"source": {
7+
"source": "git-subdir",
8+
"url": "https://github.com/BTCNAI/harness-codex-marketplace.git",
9+
"path": "./plugins/harness-codex-plugin",
10+
"ref": "v0.1.0"
11+
},
12+
"policy": {
13+
"installation": "AVAILABLE",
14+
"authentication": "ON_INSTALL"
15+
},
16+
"category": "Productivity"
17+
}
18+
]
19+
}

‎.codex-plugin/plugin.json‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
{
2+
"name": "harness-codex-plugin",
3+
"version": "0.1.0",
4+
"description": "Essential workflow framework runtime for building, running, and verifying custom Codex agent harnesses.",
5+
"license": "MIT",
6+
"author": {
7+
"name": "BTCNAI",
8+
"url": "https://github.com/BTCNAI"
9+
},
10+
"homepage": "https://github.com/BTCNAI/harness-codex-plugin",
11+
"repository": "https://github.com/BTCNAI/harness-codex-plugin",
12+
"keywords": [
13+
"codex-plugin",
14+
"workflow-framework",
15+
"agent-harness",
16+
"spec-driven-execution",
17+
"runtime-verification"
18+
],
19+
"interface": {
20+
"displayName": "Harness Essential Workflow Framework",
21+
"shortDescription": "The workflow framework for custom Codex agent harnesses.",
22+
"longDescription": "Harness provides an essential workflow-first framework for custom Codex agent systems with role, execution, and output specs; capability registries; artifacts; runtime trace; and fail-closed verification.",
23+
"developerName": "Harness contributors",
24+
"category": "Productivity",
25+
"capabilities": [
26+
"Read",
27+
"Write"
28+
],
29+
"websiteURL": "https://github.com/BTCNAI/harness-codex-plugin",
30+
"defaultPrompt": [
31+
"Use Harness Workflow Builder to convert a custom workflow into a spec-bound harness.",
32+
"Use Harness Runtime Verifier to check role, execution, output specs and artifact evidence.",
33+
"Use Harness Plugin Packager before distribution."
34+
],
35+
"brandColor": "#0F766E"
36+
},
37+
"skills": "./skills/",
38+
"mcpServers": "./.mcp.json"
39+
}

‎.env.example‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Harness Studio open-source example environment
2+
# credentialRef maps to `${CREDENTIAL_REF}_API_KEY`
3+
# Example: OPENAI_MAIN -> OPENAI_MAIN_API_KEY
4+
5+
DEMO_MODE=false
6+
DATABASE_PATH=./data/harness.sqlite
7+
ARTIFACT_DIR=./artifacts
8+
9+
DEFAULT_LLM_PROVIDER=openai_compatible
10+
DEFAULT_LLM_MODEL=qwen3.6-plus
11+
DEFAULT_LLM_BASE_URL=https://api.openai.com/v1
12+
DEFAULT_LLM_CREDENTIAL_REF=OPENAI_MAIN
13+
DEFAULT_LLM_TEMPERATURE=0.2
14+
DEFAULT_LLM_MAX_TOKENS=4096
15+
16+
LLM_REQUEST_TIMEOUT_MS=120000
17+
18+
OPENAI_MAIN_API_KEY=
19+
GITHUB_USERNAME=
20+
GITHUB_PASSWORD=
21+
22+
AGENT_REACH_ENABLED=false
23+
AGENT_REACH_MCPORTER_CMD=mcporter
24+
GITHUB_SEARCH_ENABLED=false
25+
SPECX_MODE=local

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
name: Bug report
3+
about: Report a reproducible bug in Harness Studio
4+
title: "[Bug]"
5+
labels: bug
6+
---
7+
8+
## Summary
9+
10+
## DEMO_MODE
11+
12+
- [ ] Enabled
13+
- [ ] Disabled
14+
15+
## Provider / Runtime Settings
16+
17+
- Provider:
18+
- Model:
19+
- Base URL:
20+
- Credential Ref:
21+
- Request Timeout MS:
22+
23+
## Reproduction Steps
24+
25+
1.
26+
2.
27+
3.
28+
29+
## Expected Result
30+
31+
## Actual Result
32+
33+
## Additional Context
34+

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
name: Feature request
3+
about: Suggest an improvement for Harness Studio
4+
title: "[Feature]"
5+
labels: enhancement
6+
---
7+
8+
## What problem are you trying to solve?
9+
10+
## What would you like to happen?
11+
12+
## Why does it matter for the harness workflow?
13+
14+
## Additional context
15+

‎.github/pull_request_template.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
## Summary
2+
3+
## Testing
4+
5+
- [ ] `npm run typecheck`
6+
- [ ] `npm run test:smoke`
7+
8+
## Impact
9+
10+
- [ ] Docs changed
11+
- [ ] Env changed
12+
- [ ] Smoke behavior changed
13+
14+
## Notes
15+

‎.github/workflows/test.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: test
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
jobs:
8+
verify:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: actions/checkout@v4
12+
13+
- uses: actions/setup-node@v4
14+
with:
15+
node-version: "24"
16+
cache: npm
17+
18+
- uses: actions/setup-python@v5
19+
with:
20+
python-version: "3.12"
21+
22+
- run: npm ci
23+
- run: python3 -m pip install pytest -r requirements.txt
24+
- run: npm run plugin:verify
25+
- run: npm run plugin:verify-specs
26+
- run: python3 -m pytest tests/test_harness_cli.py
27+
- run: npm run typecheck
28+
- run: npm run lint
29+
- run: npm run build
30+
- run: npm run test:smoke

‎.gitignore‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
node_modules
2+
.venv*
3+
.next
4+
dist
5+
coverage/
6+
data/
7+
data/*.sqlite
8+
data/*.db
9+
artifacts/
10+
runs/
11+
tmp/
12+
release/
13+
.env
14+
.env.*
15+
!.env.example
16+
npm-debug.log*
17+
yarn-debug.log*
18+
yarn-error.log*
19+
pnpm-debug.log*
20+
.DS_Store
21+
*.log
22+
out/

‎.mcp.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"mcpServers": {
3+
"harness": {
4+
"command": "python3",
5+
"args": [
6+
"./scripts/launch_harness_mcp.py"
7+
]
8+
}
9+
}
10+
}

‎ARCHITECTURE.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Architecture
2+
3+
Harness Studio uses one workspace entry point and two execution flows:
4+
5+
- **Build**: generate and evolve the harness graph
6+
- **Run**: execute a single task against a built harness
7+
8+
The system is intentionally split so build and run do not share the same phase logic or success criteria.
9+
10+
## 1. Single Workspace Model
11+
12+
The main workspace is `/harness/[id]`.
13+
14+
It owns:
15+
16+
- Harness Goal intake
17+
- Capability policy intake
18+
- Build / Rebuild actions
19+
- Run New Task entry
20+
- Graph, inspector, and build/runtime drawers
21+
22+
`/harness/new` only creates a new harness and redirects back to the workspace.
23+
24+
## 2. Build / Run Separation
25+
26+
### Build
27+
28+
The build path creates or updates the harness graph.
29+
30+
Relevant code:
31+
32+
- `src/lib/build-orchestrator.ts`
33+
- `src/lib/planner/*`
34+
- `src/lib/specx/*`
35+
- `src/lib/scriptx/*`
36+
- `src/lib/capabilities/*`
37+
38+
Build is responsible for:
39+
40+
- planning
41+
- composing the blueprint
42+
- resolving capabilities
43+
- compiling specs and scripts
44+
- assembling the graph
45+
46+
Build does not execute runtime tasks.
47+
48+
### Run
49+
50+
The run path consumes a persisted task instance and produces task artifacts.
51+
52+
Relevant code:
53+
54+
- `src/lib/run-orchestrator.ts`
55+
- `src/lib/runtime/*`
56+
- `src/lib/run-output/*`
57+
- `src/lib/task/*`
58+
59+
Run is responsible for:
60+
61+
- task instance planning
62+
- agent runtime decisions
63+
- capability selection
64+
- tool / skill / script execution
65+
- node output artifacts
66+
- final deliverable aggregation
67+
- final report generation as an auxiliary output
68+
69+
## 3. State Machines
70+
71+
The project uses explicit state transitions:
72+
73+
- `src/lib/harness-machine.ts`
74+
- `src/lib/run-machine.ts`
75+
76+
States are not mutated directly from components or routes.
77+
78+
## 4. Task Instance Layer
79+
80+
The task instance is the authoritative run plan.
81+
82+
Persisted fields include:
83+
84+
- `id`
85+
- `runId`
86+
- `harnessId`
87+
- `instruction`
88+
- `goal`
89+
- `constraints`
90+
- `successCriteria`
91+
- `perAgentAssignments`
92+
- `finalDeliverable`
93+
- `planningSummary`
94+
95+
Agents read the task instance, not just the raw task instruction string.
96+
97+
## 5. Artifact Layer
98+
99+
Artifacts are the main runtime output unit.
100+
101+
Supported artifact types include:
102+
103+
- `task.instance`
104+
- `agent.plan`
105+
- `agent.output`
106+
- `tool.result`
107+
- `spec.validation`
108+
- `final.deliverable`
109+
- `final.report`
110+
- `error.report`
111+
112+
The run detail view is artifacts-first.
113+
114+
## 6. Final Deliverable
115+
116+
`src/lib/run-output/final-deliverable-aggregator.ts` collects the key node artifacts and requires a real `final.deliverable` artifact.
117+
118+
The final report is a secondary summary, not the primary task result.
119+
120+
## 7. Adapters
121+
122+
The codebase uses adapter boundaries so runtime can be swapped or demoed without replacing the orchestrator.
123+
124+
- **LLM**: `src/lib/llm/*`
125+
- **SpecX**: `src/lib/specx/*`
126+
- **Capability resolution**: `src/lib/capabilities/*`
127+
- **Runtime execution**: `src/lib/runtime/*`
128+
- **Script authoring and compilation**: `src/lib/scriptx/*`
129+
130+
`DEMO_MODE=true` swaps only adapter implementations.
131+
132+
## 8. SQLite and SSE
133+
134+
- SQLite database bootstrap lives in `src/lib/sqlite.ts`
135+
- Event streaming lives in `src/lib/useEventStream.ts`
136+
- Harness and run events are persisted and pushed through SSE
137+
138+
## 9. Code Map
139+
140+
```text
141+
src/
142+
app/
143+
api/
144+
harness/
145+
runs/
146+
components/
147+
lib/
148+
capabilities/
149+
llm/
150+
planner/
151+
run-output/
152+
runtime/
153+
scriptx/
154+
specx/
155+
task/
156+
shared/
157+
prompts/
158+
registries/
159+
schemas/
160+
specs/
161+
types/
162+
```

0 commit comments

Comments
 (0)