diff --git a/README.md b/README.md index 3c14789..7422ef2 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,8 @@ control, and only then reports **Verified done**. decide whether the result is accepted. - **Keep the evidence.** Every run leaves a project-local, redacted report you can inspect or commit with the work. +- **Choose your runtime.** Use the embedded worker, an installed coding app, + or an operator-owned OpenAI-compatible endpoint such as vLLM. - **Stay local by default.** The GUI binds to loopback, and local model paths do not require a cloud service. @@ -58,14 +60,14 @@ mechanics demo, not evidence about model quality. See the complete @@ -76,8 +78,8 @@ mechanics demo, not evidence about model quality. See the complete See the mobile first-run experience

- - Agentic Harness mobile first-run screen + + Agentic Harness mobile Home screen with the safe demo result

@@ -85,6 +87,21 @@ mechanics demo, not evidence about model quality. See the complete Click any preview for the full-size screenshot. +
+See guided setup and provider settings + +

+ + Agentic Harness guided setup and provider settings + +

+ +The setup flow tests the selected connection before saving it. Provider, +execution method, task effort, and completion assurance remain separate +choices. + +
+ ## Prefer the terminal? ```bash @@ -154,36 +171,42 @@ route can remain hidden. The interface never silently changes a local selection to a cloud route.
-Example managed installation +How embedded, managed, and model-provider layers fit together -This example includes installation-specific local and cloud routes. Friendly -names lead; technical mode identifiers stay in Advanced details. Choices appear -only when the connected backend proves that they exist and reports their current -availability, and unavailable routes remain visible with a reason. +The embedded worker is the default. A managed runtime such as Local Studio is +optional and remains operator-owned; it is not bundled as a hidden dependency. +The model provider is a separate choice, so a managed route can use an +operator's vLLM or another OpenAI-compatible endpoint without changing the +Harness's completion gate.

- - Managed Agentic Harness installation with execution routes and local model profiles + + Agentic Harness architecture showing embedded and managed runtimes with local or cloud model providers

+See [Local Studio and model runtimes](https://github.com/moortekweb-art/agentic-harness/blob/main/docs/LOCAL_STUDIO_INTEGRATION.md) for the deployment boundary and private-network guidance. +
## Current evidence and open beta -Version 0.12.0 is a released self-hosted completion-assurance tool validated -against the project's frozen adversarial protocol. Its frozen specification and evidence boundaries passed a -preregistered ten-case adversarial matrix with zero false verified completions. -External usability and real-agent performance validation remain in progress. +Version 0.13.6 is the current released self-hosted completion-assurance tool. +It closes verifier and managed-GUI trust-boundary gaps while preserving the +one-trusted-user, one-workspace product boundary. The release is suitable for +bounded self-hosted use; it is not a hosted multi-user service or an +independent security audit. -- Read the [v0.12.0 release and evidence packet](https://github.com/moortekweb-art/agentic-harness/releases/tag/v0.12.0). +- Read the [v0.13.6 release notes](https://github.com/moortekweb-art/agentic-harness/blob/main/docs/RELEASE_NOTES_0.13.6.md). - Review the [assurance protocol](https://github.com/moortekweb-art/agentic-harness/blob/main/evaluation/V012_ASSURANCE_PROTOCOL.md). - Try it on a disposable branch using the [external beta guide](https://github.com/moortekweb-art/agentic-harness/blob/main/docs/EXTERNAL_BETA.md). - Count a success, failure, blocked setup, or abandoned attempt through the [beta issue form](https://github.com/moortekweb-art/agentic-harness/issues/new?template=external-beta.yml). -The project does not claim that the harness improves model intelligence or that -the still-open external beta has already proved broad usability. +The project does not claim that the harness improves model intelligence or +that one safe demo proves broad real-agent performance. Treat external model +and managed-runtime integrations as deployment-specific until their own +connection, identity, and end-to-end acceptance paths have been verified. ## Advanced Workflows @@ -618,6 +641,7 @@ goal/report smoke test, and writes `SHA256SUMS` beside the artifacts. - [GUI architecture](https://github.com/moortekweb-art/agentic-harness/blob/main/docs/GUI_ARCHITECTURE.md) - [GUI design](https://github.com/moortekweb-art/agentic-harness/blob/main/docs/GUI_DESIGN.md) +- [Local Studio and model runtimes](https://github.com/moortekweb-art/agentic-harness/blob/main/docs/LOCAL_STUDIO_INTEGRATION.md) - [GUI deployment](https://github.com/moortekweb-art/agentic-harness/blob/main/docs/GUI_DEPLOYMENT.md) - [Public-release boundary](https://github.com/moortekweb-art/agentic-harness/blob/main/docs/PUBLIC_RELEASE.md) - [Autonomous goal contract](https://github.com/moortekweb-art/agentic-harness/blob/main/docs/CODEX_GOAL_PARITY.md) diff --git a/docs/IMG2IMG_ASSET_PROVENANCE.md b/docs/IMG2IMG_ASSET_PROVENANCE.md index 0425b0e..655c271 100644 --- a/docs/IMG2IMG_ASSET_PROVENANCE.md +++ b/docs/IMG2IMG_ASSET_PROVENANCE.md @@ -11,6 +11,21 @@ status evidence and never runtime-generated content. - `docs/assets/gui-concepts/review-desk.png` — evidence/review semantics - `docs/assets/agentic-harness-social-preview.png` — limited technical depth +## Current product screenshots + +The 0.13.6 GUI screenshots used by the public README are behavioral captures, +not generated illustrations: + +- `agentic-harness-gui-home-0.13.6.png` +- `agentic-harness-gui-settings-0.13.6.png` +- `agentic-harness-gui-verified-0.13.6.png` +- `agentic-harness-gui-mobile-0.13.6.png` + +They were captured on 2026-08-01 from the packaged GUI against a disposable +workspace using the built-in safe demo. The fixture used no model, API key, +private host, or maintainer workspace. The architecture overview +`agentic-harness-architecture-0.13.6.svg` is hand-authored, versioned artwork. + ## Assets | Runtime asset | Source master | Purpose | Generation record | diff --git a/docs/LOCAL_STUDIO_INTEGRATION.md b/docs/LOCAL_STUDIO_INTEGRATION.md new file mode 100644 index 0000000..bb2e481 --- /dev/null +++ b/docs/LOCAL_STUDIO_INTEGRATION.md @@ -0,0 +1,83 @@ +# Local Studio and model runtimes + +Agentic Harness is the completion-assurance layer. It can run with its +embedded engine, or it can sit in front of an operator-owned execution +runtime. Local Studio is an optional example of that second arrangement; it +is not bundled with this package and is not required for the default install. + +## What each layer owns + +| Layer | Owns | Does not claim | +| --- | --- | --- | +| Agentic Harness | Objective, scope, effort, task identity, allowed actions, independent checks, evidence, and the final `Verified done`, `Blocked with reason`, or `Failed with evidence` state | That a model is correct merely because it says a task is complete | +| Local Studio or another managed runtime | The operator's model process, queue, model profile, execution host, and runtime-specific lifecycle | That its worker claim is independent verification | +| vLLM, Ollama, LM Studio, llama.cpp, or a cloud endpoint | Model inference behind the provider contract | That the endpoint supplies the Harness's completion gate | + +The public package deliberately keeps these boundaries separate. A provider +choice is not an effort choice, and a managed route is not silently converted +into a local or cloud route. The Harness accepts a result only after the +configured independent review succeeds. + +## Recommended arrangements + +### Portable self-hosted install + +Use the default embedded backend when one trusted user is working in one +workspace: + +```bash +pipx install local-agentic-harness +cd /path/to/project +agentic-harness gui +``` + +In Settings, connect an installed coding app or an OpenAI-compatible model +endpoint. A local vLLM server is one valid provider when it is reachable from +the machine running the GUI and exposes the expected API. The Harness does +not require a particular model brand or a particular inference host. + +### Managed or remote execution + +Use the optional managed compatibility backend only when an operator already +has a compatible external controller/runtime contract: + +```bash +agentic-harness-gui \ + --backend local-goal \ + --project-dir /path/to/project \ + --no-open +``` + +The external runtime may be Local Studio, a vLLM-backed controller, or another +operator-owned service. The exact adapter and service remain deployment +specific; this repository does not ship a private controller, a private +hostname, or a default remote connection. See +[`TURNSTONE_INTEGRATION.md`](TURNSTONE_INTEGRATION.md) for the public +compatibility boundary. + +In managed mode, the GUI should expose the runtime's route and availability as +read-only facts. The Harness must retain the requested objective, route, work +area, verification policy, and authoritative task identity. A status page, +queue completion, or worker sentence is not enough to produce `Verified done`. + +## Network and secret boundary + +Keep the GUI loopback-bound unless a private, authenticated reverse proxy is +required. If a private network or Tailscale is used, proxy the loopback +service rather than binding the control surface directly to an untrusted +interface. Configure the GUI token and allowed host explicitly, and never put +credentials in URLs, project configuration, screenshots, reports, or task +events. + +Remote model use also requires explicit consent because selected prompts, +file excerpts, and tool observations may leave the machine for the endpoint +chosen in Settings. A private-network endpoint and a same-machine endpoint are +different data-boundary claims and should be presented as such. + +## Public product boundary + +This package is a self-hosted tool for one trusted user and one selected +workspace. Combining it with Local Studio can make a powerful private +deployment, but it does not turn the process into a hosted multi-user service. +A hosted product needs identity, per-user isolated workspaces and secrets, +quotas, abuse controls, audit records, and teardown outside this package. diff --git a/docs/assets/agentic-harness-architecture-0.13.6.svg b/docs/assets/agentic-harness-architecture-0.13.6.svg new file mode 100644 index 0000000..59d3243 --- /dev/null +++ b/docs/assets/agentic-harness-architecture-0.13.6.svg @@ -0,0 +1,67 @@ + + Agentic Harness architecture + The Harness owns the objective and independent completion gate. It can use an embedded worker or an optional managed runtime, which can call a local or cloud model provider. + + + + + + + + + + + + + + + + + + One completion gate, many runtimes + Keep task identity, evidence, and verification separate from model execution. + + + + AGENTIC HARNESS + Objective → work → proof + • task identity and scope + • bounded actions and evidence + • independent deterministic review + + Verified · Blocked · Failed + + + + + + + + DEFAULT + Embedded worker + One install, one workspace + + + + + OPTIONAL + Managed runtime + Local Studio or another adapter + + + + + + + + PROVIDERS + vLLM + Ollama + LM Studio + llama.cpp + Cloud API + operator chosen + + + The provider supplies inference. The Harness supplies the acceptance decision. + diff --git a/docs/assets/agentic-harness-gui-home-0.13.6.png b/docs/assets/agentic-harness-gui-home-0.13.6.png new file mode 100644 index 0000000..a2727f8 Binary files /dev/null and b/docs/assets/agentic-harness-gui-home-0.13.6.png differ diff --git a/docs/assets/agentic-harness-gui-mobile-0.13.6.png b/docs/assets/agentic-harness-gui-mobile-0.13.6.png new file mode 100644 index 0000000..39f399e Binary files /dev/null and b/docs/assets/agentic-harness-gui-mobile-0.13.6.png differ diff --git a/docs/assets/agentic-harness-gui-settings-0.13.6.png b/docs/assets/agentic-harness-gui-settings-0.13.6.png new file mode 100644 index 0000000..08c744e Binary files /dev/null and b/docs/assets/agentic-harness-gui-settings-0.13.6.png differ diff --git a/docs/assets/agentic-harness-gui-verified-0.13.6.png b/docs/assets/agentic-harness-gui-verified-0.13.6.png new file mode 100644 index 0000000..9a4ae9f Binary files /dev/null and b/docs/assets/agentic-harness-gui-verified-0.13.6.png differ diff --git a/tests/test_examples.py b/tests/test_examples.py index 45935f3..78a3994 100644 --- a/tests/test_examples.py +++ b/tests/test_examples.py @@ -90,7 +90,8 @@ def test_readme_public_intro_leads_with_a_short_product_and_install_path() -> No '--check "python -m pytest tests/ -q"' ) in public_intro assert ".agentic-harness/runs/{goal-id}/report.md" in public_intro - assert "agentic-harness-gui.png" in public_intro + assert "agentic-harness-gui-home-0.13.6.png" in public_intro + assert "agentic-harness-gui-verified-0.13.6.png" in public_intro assert 'width="420"' in public_intro assert "See the mobile first-run experience" in public_intro assert 'width="220"' in public_intro
- - Agentic Harness Home screen + + Agentic Harness Home screen with a free-form task prompt and safe demo -
Describe the outcome. Choose an effort level and see what will run before files change. +
Describe the outcome. Use a normal sentence, choose an effort level, and see what will run before files change. 		- - Agentic Harness verified task evidence + + Agentic Harness verified task evidence
Inspect the proof. Verified done includes changed files, the worker report, and independent evidence.