agent-hitch 0.1.1 → 0.2.1

package/README.md

@@ -4,46 +4,68 @@
 [![GitHub release](https://img.shields.io/github/v/release/rsi-gear/agent-hitch)](https://github.com/rsi-gear/agent-hitch/releases)
 [![Discord](https://img.shields.io/badge/Discord-Join_chat-5865F2?logo=discord&logoColor=white)](https://discord.gg/cZ4NBbHDk)
 
-**Let agents choose their harness with one runtime.**
+[English](README.md) | [简体中文](README.zh-CN.md)
 
-Hitch lets an agent choose which harness and revision to use for each run. It is
-an agent-first CLI and daemon for discovering and running native coding agents
-through one stable, machine-oriented interface.
+**Content-addressed version control and evidence storage for agent harnesses.**
 
-Hitch is designed as infrastructure for Recursive Self-Improvement (RSI),
-including harness evolution and model evolution.
+Hitch makes every agent run traceable to an exact harness revision. It resolves
+harness references to immutable identities, prepares content-addressed runnable
+artifacts, executes them through a stable interface, and preserves the
+trajectory and evaluation evidence produced by each run.
 
-> Status: pre-alpha. Installed-harness discovery, immutable revision resolution,
-> prepared artifact caching, direct runs, the local daemon, and Harbor-backed
-> agent evals are implemented.
+Git can identify the harness source that changed. Hitch carries that identity
+through build and execution:
 
-## News
+```text
+Harness ref
+  -> resolved revision
+  -> prepared artifact
+  -> run / eval
+  -> trajectory
+  -> feedback and evaluation evidence
+
+Hitch controller
+  -> content-addressed runtime bundle
+  -> referenced by containerized evals
+```
 
-- **2026-08-13:** Hitch now supports DeepSeek Harness.
+Hitch is infrastructure for systems that develop, compare, and evolve agent
+harnesses. It owns version resolution, runnable artifacts, execution records,
+and evidence. Candidate generation, comparison policy, and promotion decisions
+belong to the system using Hitch.
 
-## Available now
+> **Status:** pre-alpha. The core identity and evidence path is implemented,
+> including immutable revision resolution, prepared artifact caching, direct and
+> daemon-backed runs, Harbor-backed evals, content-addressed controller runtimes,
+> DSH-compatible canonical trajectories, and message feedback.
 
-Hitch currently supports Codex CLI, Claude Code, Pi, OpenCode, and DeepSeek
-Harness adapters. It provides:
+## Why harness version control?
 
-- executable discovery, version probing, and executable fingerprints;
-- exact package-version and Git-commit resolution;
-- immutable prepared artifacts with integrity-aware caching;
-- direct execution with normalized JSONL events;
-- a persistent local daemon with bounded concurrency;
-- queued and active-run cancellation, timeouts, and process-tree cleanup;
-- managed shared, Git worktree, and independent-copy workspace modes;
-- Harbor-backed evaluation in Docker with normalized reward summaries;
-- atomic manifests/results plus raw stdout and stderr logs; and
-- conservative recovery of interrupted records after daemon restart.
+An agent harness is more than a source commit. What actually ran can also depend
+on the package release, build output, controller code, workspace mode, native
+adapter, and mutable executable installed on a machine. A score or transcript
+without those identities is difficult to audit and harder to reproduce.
 
-Versioned machine-contract schemas live in [`docs/schemas`](docs/schemas).
-Runtime validation rejects unknown request fields and preserves typed errors
-across the daemon HTTP boundary.
+Hitch preserves an explicit chain from a requested harness reference to the
+evidence generated by its execution:
+
+| Record | What it identifies |
+| --- | --- |
+| Harness reference | The version, commit, local source, or installed executable requested by the caller |
+| Resolved revision | The immutable source identity selected for the run |
+| Prepared artifact | The validated, content-addressed runnable build |
+| Controller runtime | The exact Hitch runtime uploaded for a containerized eval |
+| Run or eval record | The request, workspace, lifecycle, result, and links between identities |
+| Canonical trajectory | The agent messages and tool activity in a stable DSH-compatible format |
+| Feedback and eval evidence | Message-level feedback, verifier output, rewards, and backend records |
+
+This is a local versioning and evidence layer, not a replacement for Git and not
+yet a remote artifact registry. Hitch does not currently provide branches,
+tags, diffs, candidate promotion, or rollback policy.
 
-## Installation
+## Quick start
 
-Hitch requires Node.js 22 or newer. Install the CLI globally from npm:
+Hitch requires Node.js 22 or newer. Install it from npm:
 
 ```bash
 npm install --global agent-hitch
@@ -51,25 +73,18 @@ hitch --version
 hitch list --json
 ```
 
-You can also try it without a global installation:
+Resolve and prepare an exact harness version:
 
 ```bash
-npx agent-hitch --help
-```
-
-For development from a checkout:
-
-```bash
-npm test
-npm link
-hitch list --json
+hitch resolve codex@version:0.92.0 --json
+hitch prepare codex@version:0.92.0 --json
 ```
 
-Run a task directly:
+Run that exact version in an isolated Git worktree:
 
 ```bash
 hitch run \
-  --harness codex@installed \
+  --harness codex@version:0.92.0 \
   --model gpt-5.6-terra \
   --cwd /workspace/project \
   --workspace-mode worktree \
@@ -77,42 +92,96 @@ hitch run \
   --output jsonl
 ```
 
-Run through the persistent daemon:
+Every run writes an atomic manifest and result, raw process logs, normalized
+events, and a canonical trajectory below `~/.hitch/runs/RUN_ID`. Inspect the
+trajectory through the CLI:
 
 ```bash
-hitch daemon start --max-concurrent 4
+hitch trajectory inspect RUN_ID --json
+```
 
-hitch run \
-  --daemon \
-  --harness codex@installed \
-  --model gpt-5.6-terra \
-  --cwd /workspace/project \
-  --prompt-file task.md \
-  --output jsonl
+For development from a checkout:
 
-hitch daemon status --json
-hitch daemon stop
+```bash
+npm install
+npm run check
+npm link
+hitch list --json
 ```
 
-Submit asynchronously and cancel later:
+## Harness references
+
+Harness selection is explicit for every run. Exact package versions and Git
+commits resolve to immutable identities and are prepared in Hitch's artifact
+store.
 
 ```bash
-hitch daemon submit \
-  --harness claude@installed \
-  --cwd /workspace/project \
-  --prompt-file task.md
+# Use and fingerprint the executable already installed on this machine.
+hitch run --harness codex@installed --prompt "Inspect this repository"
+
+# Resolve, prepare, or run an exact published version.
+hitch resolve codex@version:0.92.0 --json
+hitch prepare codex@version:0.92.0 --json
+hitch run --harness codex@version:0.92.0 --prompt "Inspect this repository"
+
+# Build a commit from the registered upstream repository.
+hitch run --harness codex@commit:0123456789abcdef --prompt "Inspect this repository"
 
-hitch daemon cancel run_<id>
+# Build a clean commit from a local harness repository.
+hitch run \
+  --harness 'pi@git+file:///workspace/pi#0123456789abcdef' \
+  --prompt "Inspect this repository"
 ```
 
-State is stored below `~/.hitch` by default. Use `--root <path>` or
-`HITCH_ROOT` to relocate it. Native executable overrides use
-`HITCH_CODEX_PATH`, `HITCH_CLAUDE_PATH`, `HITCH_PI_PATH`,
-`HITCH_OPENCODE_PATH`, and `HITCH_DEEPSEEK_PATH`.
+Bare names such as `codex` are compatibility aliases for `codex@installed`.
+Installed executables are useful for local work, but exact version or commit
+references should be preferred when portability matters.
+
+Version selectors require exact semantic versions; ranges and mutable tags such
+as `latest` are not accepted. Short commit IDs are expanded and must be
+unambiguous. Local Git repositories must be clean. Codex, Pi, and DeepSeek
+Harness support source-commit preparation; Claude Code and OpenCode currently
+support installed and exact-version sources.
+
+Preparation executes registered package lifecycle or source-build commands with
+the permissions of the Hitch process. Content addressing makes an artifact
+auditable and cacheable; it does not make untrusted build code safe.
+
+## Evidence from every run
+
+Hitch keeps lifecycle events and agent trajectories as two related but distinct
+records:
+
+- normalized JSONL events describe Hitch's control plane, including resolution,
+  preparation, process lifecycle, cancellation, and terminal status;
+- supported adapters preserve redacted provider-native events before any
+  translation, while a DSH-compatible canonical trajectory remains available
+  as a derived view;
+- `trajectory.ref.json` V2 binds every trajectory file by relative path, byte
+  size, role, and SHA-256 digest; and
+- feedback sidecars attach versioned positive or negative ratings and notes to
+  assistant messages without rewriting the immutable trajectory.
+
+```bash
+hitch trajectory inspect RUN_ID
+hitch runs list --context-kind benchmark_task --json
+hitch compare model --benchmark BENCHMARK --task TASK --json
+hitch feedback list RUN_ID --json
+hitch feedback put RUN_ID \
+  --message MESSAGE_ID \
+  --rating positive \
+  --note "Kept the change focused" \
+  --json
+```
+
+Machine-contract schemas are versioned in [`docs/schemas`](docs/schemas).
+Runtime validation rejects unknown request fields and preserves typed errors
+across the daemon HTTP boundary.
 
 ## Harbor-backed evals
 
-Run an agent eval with Harbor:
+Hitch can evaluate an exact, portable harness revision with
+[Harbor](https://github.com/harbor-framework/harbor):
 
 ```bash
 # Installs pinned Harbor into ~/.hitch/tools without changing system Python.
@@ -128,104 +197,138 @@ hitch eval run \
   --max-concurrent 4
 
 hitch eval list
-hitch eval inspect eval_<id> --json
+hitch eval inspect EVAL_ID --json
 ```
 
-`hitch eval setup harbor` requires Python 3.12+ and creates an isolated virtual
-environment at `~/.hitch/tools/harbor-<version>`. It does not install or start
-Docker. `hitch eval doctor` checks Python, the selected Harbor installation,
-the Docker daemon, and whether a common provider credential is present. Hitch
-automatically prefers the managed Harbor installation for subsequent evals;
-`--harbor` and `HITCH_HARBOR_PATH` remain explicit overrides.
-
 Harbor owns task discovery, Docker lifecycle, verification, and rewards. Its
-custom Hitch agent uploads a minimal Hitch runtime into each task container and
-runs the exact selected harness revision in `/app`. This ensures the benchmark
-measures the Hitch execution path rather than Harbor's native agent adapter.
+custom Hitch agent uploads a minimal, SHA-256-addressed Hitch controller runtime
+into each task container and executes the selected harness revision in `/app`.
+The resulting eval record links the request, resolved revision, controller
+runtime, backend configuration and logs, normalized result, reward summary, and
+trajectory evidence.
+
+Eval accepts exact `version:` refs, registered `commit:` refs, and explicit
+local `git+file:///absolute/repo#<full-lowercase-commit>` refs. For local Git,
+Hitch transports a verified exact-commit object pack into each Harbor trial;
+uncommitted files, Git config, credentials, and unrelated history are excluded.
+The local repository must be clean and abbreviated commits, branches, tags,
+`HEAD`, and installed executables are rejected. Common provider credentials are
+forwarded by environment-variable reference; use `--pass-env NAME` for an
+additional variable.
+
+See [Harbor-backed agent evals](docs/evals.md) for setup, portability rules, and
+the execution boundary.
+
+## Stable execution layer
+
+Versioned artifacts still need a consistent way to run. Hitch provides adapters
+for Codex CLI, Claude Code, Pi, OpenCode, and DeepSeek Harness and normalizes
+their invocation and lifecycle behavior behind one machine-oriented contract.
+
+```text
+caller -> Hitch CLI / daemon -> shared run engine -> Codex CLI
+                                             \----> Claude Code
+                                             \----> Pi
+                                             \----> OpenCode
+                                             \----> DeepSeek Harness
+```
 
-Eval currently accepts exact `version:` refs and `commit:` refs backed by a
-registered remote source. Installed executables and local `git+file://` refs are
-rejected because they are not portable into Harbor containers. Common provider
-credentials are forwarded by environment-variable reference; use
-`--pass-env NAME` for an additional variable. Eval records are stored under
-`~/.hitch/evals` and include the request, resolved revision, plan, generated
-Harbor config, raw backend logs/result, normalized result, and JSONL events.
+The direct CLI and persistent daemon use the same run engine, so revision
+resolution, records, timeout, cancellation, and event behavior do not drift.
+The runtime currently provides:
 
-## Select a harness revision
+- executable discovery, version probing, and executable fingerprints;
+- exact package-version and Git-commit resolution;
+- immutable prepared artifacts with integrity-aware caching;
+- direct execution with normalized JSONL events;
+- a persistent local daemon with bounded concurrency;
+- queued and active-run cancellation, timeouts, and process-tree cleanup;
+- managed shared, Git worktree, and independent-copy workspace modes;
+- atomic manifests and results plus raw stdout and stderr logs; and
+- conservative recovery of interrupted records after daemon restart.
 
-Harness selection is explicit for every run. Bare names retain the installed
-executable behavior; exact published versions and Git commits resolve to
-immutable identities and are prepared in Hitch's artifact store.
+Run through the daemon when a long-lived queue is useful:
 
 ```bash
-# Bare name is an alias for codex@installed.
-hitch run --harness codex --prompt "Inspect this repository"
+hitch daemon start --max-concurrent 4
 
-# Resolve or prewarm an exact published version.
-hitch resolve codex@version:0.92.0 --json
-hitch prepare codex@version:0.92.0 --json
-hitch run --harness codex@version:0.92.0 --prompt "Inspect this repository"
+hitch run \
+  --daemon \
+  --harness codex@version:0.92.0 \
+  --cwd /workspace/project \
+  --prompt-file task.md \
+  --output jsonl
 
-# Build a commit from the registered upstream repository.
-hitch run --harness codex@commit:0123456789abcdef --prompt "Inspect this repository"
+hitch daemon status --json
+hitch daemon stop
+```
 
-# Build a clean commit from a local harness repository.
-hitch run \
-  --harness 'pi@git+file:///workspace/pi#0123456789abcdef' \
-  --prompt "Inspect this repository"
+Asynchronous submission and cancellation are also available:
+
+```bash
+hitch daemon submit \
+  --harness claude@version:EXACT_VERSION \
+  --cwd /workspace/project \
+  --prompt-file task.md
+
+hitch daemon cancel RUN_ID
 ```
 
-Version selectors require exact semantic versions; ranges and `latest` are not
-accepted. Short commit IDs are expanded and must be unambiguous. Local Git
-repositories must be clean. Codex, Pi, and DeepSeek Harness support
-source-commit preparation; Claude Code and OpenCode currently support installed
-and exact-version sources.
+## State and isolation
 
-The legacy `--agent <name>` option remains available as an alias for
-`--harness <name>@installed`. It cannot select revisions or be combined with
-`--harness`.
+State is stored below `~/.hitch` by default. Use `--root <path>` or
+`HITCH_ROOT` to relocate it. Each root owns its artifact store, controller
+runtime store, run and eval records, daemon token, and queue.
 
-Preparation executes the registered package lifecycle or source-build commands
-with the permissions of the Hitch process. A resolved identity makes the input
-auditable and cacheable; it is not a security sandbox.
+Native executable overrides use `HITCH_CODEX_PATH`, `HITCH_CLAUDE_PATH`,
+`HITCH_PI_PATH`, `HITCH_OPENCODE_PATH`, and `HITCH_DEEPSEEK_PATH`.
 
-## Why Hitch?
+Workspace modes make mutation boundaries explicit:
 
-Coding-agent CLIs expose different commands, model flags, configuration formats,
-session models, event streams, and process behavior. Hitch absorbs that
-integration cost behind a small adapter contract while preserving the native
-runtime.
+- `shared` runs directly in the source directory;
+- `worktree` creates a detached Git worktree from a clean `HEAD`; and
+- `copy` creates an independent filesystem copy.
 
-```text
-caller -> Hitch CLI / daemon -> shared run engine -> Codex CLI
-                                             \----> Claude Code
-                                             \----> Pi
-                                             \----> OpenCode
-                                             \----> DeepSeek Harness
-```
+Workspace isolation is not a process security sandbox.
 
-The direct CLI and daemon use the same engine, so persistence, timeout,
-cancellation, and event behavior do not drift.
+## Design principles
+
+- **Traceable by default:** every run links the requested reference, resolved
+  revision, runnable artifact, execution record, and evidence.
+- **Immutable resolution:** mutable input is resolved before preparation or
+  execution, then recorded by identity.
+- **Content-addressed reuse:** validated artifacts and controller runtimes are
+  reused by digest rather than copied per run.
+- **Evidence without lossy abstraction:** stable canonical records coexist with
+  raw harness output and explicit trajectory fidelity.
+- **Machine-first contracts:** structured output, versioned schemas, and typed
+  failures are the public interface.
+- **Policy lives above Hitch:** mutation, ranking, promotion, and rollback remain
+  explicit decisions for the calling system.
+- **Safe interruption:** cancellation targets the complete subprocess tree, and
+  interrupted workspace-mutating runs are never replayed implicitly.
 
 ## Planned work
 
+- [x] Strict model/harness comparison primitives over run evidence
+- [ ] Named candidate and champion references
+- [ ] Promotion and rollback records without embedding promotion policy
+- [ ] Remote artifact and evidence synchronization
 - [ ] Additional harness adapters
 - [ ] Additional API provider support
 - [ ] Local model inference support
 
-## Design principles
+## News
 
-- **Agent-first:** structured output, stable exit categories, no required UI.
-- **Explicit over ambient:** agent, model, workspace, and state root are visible.
-- **Minimal common contract:** unknown native events remain available rather
-  than being forced into misleading abstractions.
-- **Isolated control state:** each root has its own daemon, token, queue, and run
-  records.
-- **Safe interruption:** cancellation targets the complete subprocess tree.
-- **No implicit replay:** interrupted workspace-mutating runs fail visibly.
+- **2026-08-20:** Hitch 0.2 development moved the project to strict TypeScript
+  compiled to ESM, added a shared SHA-256 controller runtime cache, recorded a
+  DSH-compatible canonical trajectory for every run, and introduced
+  lifecycle-bound message feedback.
+- **2026-08-13:** Hitch added DeepSeek Harness support.
 
 ## Documentation
 
+- [Hitch 0.2 development spec](docs/hitch-0.2-development-spec.md)
 - [Design document](docs/design.md)
 - [Agent daemon analysis and port](docs/daemon.md)
 - [Workspace isolation](docs/workspaces.md)
@@ -235,7 +338,7 @@ cancellation, and event behavior do not drift.
 ## Community
 
 Join the [Hitch community on Discord](https://discord.gg/cZ4NBbHDk) to ask
-questions, share feedback, and discuss coding-agent infrastructure.
+questions, share feedback, and discuss agent-harness infrastructure.
 
 ## Acknowledgements