ECHO Harness

中文说明

Execution · Context · Harness · Orchestration

A lightweight, local-first autonomous coding agent built from scratch.

ECHO Harness is a Windows-first TypeScript CLI that connects to an OpenAI-compatible model, runs an explicit Turn/Step agent loop, executes bounded workspace tools, records redacted JSONL events, and exposes the same application service through a loopback-only Web console.

Why it is worth inspecting

• The loop belongs to ECHO. Provider transport, context projection, tool dispatch, safety, termination, and recovery are implemented in this repository rather than delegated to an agent framework.
• Evidence is part of the product. The CLI separates model text, tool requests, failures, diffs, test results, and the final Turn status. A tool succeeding is never presented as proof that the whole task succeeded.
• Windows is a tested platform. PowerShell discovery, non-console execution, Unicode paths, bounded output, timeouts, cancellation, and process-tree termination have automated coverage.
• Safety is centralized. Six tools share workspace isolation, validation, approval, hard-deny, redaction, timeout, and output-limit rules.
• Capabilities can be created safely enough to inspect. After explicit Full Access confirmation, an Agent can author, self-test, check, install, hot-load, disable, and uninstall extensions scoped to the current workspace. They persist across Sessions but never become global plugins.
• Quality is reproducible. Fake Provider evals, a resettable failing-test fixture, coverage thresholds, malicious scan samples, and a Windows GitHub Actions gate provide reviewable evidence.

Architecture

CLI / local Web console
   |
   v
Agent Loop -----> Context Projector -----> OpenAI-compatible Provider
   |                    ^
   |                    |
   +----> Safety Policy +----> redacted JSONL Session Store
   |
   +----> Tool Registry ----> files / PowerShell / workspace extensions

The six P0 tools are list_files, search_text, read_file, write_file, apply_patch, and run_command. Tool calls execute sequentially so state changes, approvals, and terminal events remain deterministic.

P3 adds full-access, which requires explicit human confirmation and removes per-operation prompts without removing validation, cancellation, timeouts, output bounds, redaction, or process cleanup. Only in that mode can the Agent use seven extension_* lifecycle tools. Installed extension code runs in a bounded Worker protocol, remains under the current workspace .echo/, and is not an OS sandbox.

Requirements

• Windows with PowerShell
• Node.js 22
• Corepack and the repository-pinned pnpm@11.24.0
• An OpenAI-compatible endpoint, API key, and model name for real runs

Install

corepack enable
corepack prepare pnpm@11.24.0 --activate
pnpm install --frozen-lockfile
pnpm build

Configure

Non-secret settings persist only at <artifact-root>/config/echo.config.json. artifact-root is the directory of the CLI module or executable (dist/ after pnpm build), never process.cwd(). Create or update that file with the interactive wizard:

pnpm build
node .\dist\cli.js config
$env:ECHO_API_KEY = '<secret>'

The wizard asks for the OpenAI-compatible Provider URL, discover vs manual model catalog, default model, and safety mode. It keeps a memory draft until the final confirmation, then writes the file atomically. Discover mode stores only the default model; candidate IDs are fetched later with GET /models, cached in-process, and never required by run. Chat /model lists candidates through the catalog port. Discovery failure does not block the configured model. ECHO_API_KEY is the only supported secret environment variable and is never saved. CLI flags such as --model, --base-url, and --safety-mode override the file for one run or chat and do not query the catalog. Missing configuration makes run/chat exit 2 and suggest echo-harness config. P1-2A landed the loader, P1-2B landed catalog discovery, and P1-1B landed chat. The loader does not read ECHO_BASE_URL, ECHO_MODEL, ECHO_SAFETY_MODE, workspace echo.config.json, or workspace .echo/config.

See ADR-0002 and ADR-0005.

Run

node .\dist\cli.js run "Inspect the project and fix the failing tests." `
  --workspace . `
  --safety-mode balanced `
  --non-interactive `
  --no-color

Use node .\dist\cli.js run --help for the complete option list. Progress and diagnostics go to stderr as a grouped Step timeline; the final model answer goes to stdout. Exit codes distinguish configuration, Provider, tool, policy, limit, and cancellation failures. ASCII is used when the terminal is not a TTY; --no-color removes ANSI without changing labels or structure.

Chat

node .\dist\cli.js chat --workspace .
node .\dist\cli.js chat --resume <session-id> --workspace .

<session-id> may be the full ID or the unique 8-character SESSION value from the Chat banner / /status.

Chat reuses the same application service as run. Typed idle lines may run /help, /status, /model, /model refresh, /safety, and /quit. A bracketed paste is at most one Turn and never a Slash command. Ctrl+C cancels a running Turn and returns to the prompt; idle Ctrl+C exits 130.

Local Web console

node .\dist\cli.js web --workspace .
node .\dist\cli.js web --workspace . --no-open

Phase A starts a 127.0.0.1 console for one fixed workspace. The default command opens the server-issued, verified loopback bootstrap URL. --no-open prints that same URL and does not open a browser. The console provides live Session/Turn/approval APIs, aggregated Chat, SSE reconnection, Provider settings, and a bounded Trace/Inspector view. It shares configuration, application services, safety policy, and redacted Session storage with the CLI.

See ADR-0007, the Web API contract, and the WebUI specification.

Resettable demonstration

The fixed demo shows one continuous story: inspect code, observe a failing TypeScript test, locate the bug, apply a source-only patch, rerun the test, and finish with evidence.

pnpm build
node scripts/demo-reset.mjs
$goal = (Get-Content -Raw .\fixtures\demo\prompt.txt).Trim()
node .\dist\cli.js run $goal `
  --workspace .\fixtures\demo `
  --safety-mode balanced `
  --non-interactive `
  --no-color `
  --max-steps 12

The real-Provider acceptance helper runs the story three times when credentials are explicitly available:

node scripts/demo-accept.mjs

See docs/demo.md for reset, expected beats, privacy checks, and recording fallbacks.

The P3 demonstration adds a synthetic PDF capability gap without using assessment content:

pnpm build
pnpm p3:demo:reset
pnpm p3:demo:baseline
pnpm accept:p3-pdf
pnpm p3:demo:verify

It gives the Agent only the capability gap and durability constraints. The Agent chooses the extension and tool names, creates and tests the implementation, hot-loads it, repairs only the allowed source file, and reuses the capability in an exact new Session. The acceptance helper rejects one-off PDF-reading bypasses and cross-workspace leakage. Protected-input hashes and a test process outside the Harness decide acceptance; the model cannot certify its own work.

Quality gate

pnpm check
pnpm eval:offline
pnpm smoke:demo
pnpm smoke:artifact
pnpm test:web:e2e

pnpm check runs formatting, linting, strict type checking, coverage, build, CLI smoke, artifact cwd and isolated Web smoke, secret scan, identity scan, Web artifact scan, and generated malicious-sample self-tests. Playwright covers keyboard, accessibility, 200% zoom, reconnection, approvals, Provider secrecy, and large Trace sessions. CI uses only the deterministic Fake Provider and never receives a real API key.

Controlled local acceptance of the packaged Web console is explicit and non-CI:

pnpm build
pnpm accept:web-provider

The helper reads Provider credentials from the environment or gitignored .env.test, uses a temporary workspace, verifies Chat/SSE/recovery/Trace, prints no response body or key, and restores temporary configuration. Details and evidence are in docs/testing.md and the P2 acceptance matrix.

Documentation

• Architecture
• Core contracts
• Security model
• CLI UX
• Demo guide
• Testing and evals
• ADR-0001: project foundation
• ADR-0002: P1 config and artifact-root
• ADR-0003: application service and recoverable sessions
• ADR-0005: restore artifact-root config
• ADR-0006: aggregated model content and reasoning events
• ADR-0007: fixed-workspace local Web console
• P1 CLI plan
• P2 local WebUI plan
• P2 acceptance matrix
• ADR-0010: explicit Full Access mode
• ADR-0011: workspace-scoped extensions
• P3 extension plan
• P3 acceptance matrix
• Local Web API contract
• WebUI product and interaction specification

Honest limits

• ECHO is not an operating-system sandbox. Approved PowerShell commands can still access network or files permitted to the current user.
• The current release does not provide MCP, multi-agent execution, remote Web access, a global extension market, OCR, Session export, or a general rollback system. The CLI and local Web console reuse the same application service.
• Compatibility is verified against a bounded OpenAI-compatible service configuration, not every provider implementation.
• Model requests may contain repository excerpts selected by the Context Projector. Use ECHO only with code and services you are authorized to process.
• Automated redaction and scans reduce disclosure risk but do not replace human review of Git metadata, screenshots, terminal chrome, and submission materials.