soa-harness-impl

Reference implementation of SOA-Harness v1.0 — the formal spec for Secure Operating Agents.

SOA-Harness defines a production-standard harness for agentic AI runtimes: cryptographically-signed agent identity, permission gating, hash-chained audit, structured streaming, token budgets, crash-safe session persistence, and a conformance test suite (soa-validate). This repo is the TypeScript reference implementation of that spec.

Quick start (~15 min, fresh laptop)

Prerequisites:

• Node.js 20 or newer (22 recommended)
• npm 10 or newer (older versions have different npx behavior and may silently skip scaffold binaries)
• Supported platforms: Windows 10+, macOS 11+, Linux (including WSL2 Ubuntu 22.04+)

Scaffold a new agent project, install deps, launch the Runner:

npx create-soa-agent my-agent
cd my-agent
npm install
node ./start.mjs

Expected output:

[create-soa-agent] WARNING: generated a synthetic Ed25519 keypair ...
[create-soa-agent] scaffolded 3 files into /.../my-agent
[demo] first audit row produced: aud_<hex> (AutoAllow); session=ses_<hex>
[demo] Runner live at http://127.0.0.1:7700 — Ctrl-C to stop

In a second terminal, verify the HTTP surface:

curl -s http://127.0.0.1:7700/health
# {"status":"alive","soaHarnessVersion":"1.0"}

curl -s http://127.0.0.1:7700/.well-known/agent-card.json | jq .name
# "demo-agent"

curl -s -I http://127.0.0.1:7700/.well-known/agent-card.jws | head -1
# HTTP/1.1 200 OK

Wall-clock benchmarks (captured in docs/m4/dry-run-telemetry.md):

• Windows 11 (PowerShell): 7.5s end-to-end
• WSL2 Ubuntu 24.04: 11.8s end-to-end

Troubleshooting:

• Port 7700 already in use — set PORT=<other> before node ./start.mjs (any free port; the probe URLs above use whatever PORT resolves to)
• npm install errors with EUNSUPPORTEDPROTOCOL — you're on npm < 10 or hit a stale npm cache; upgrade via npm install -g npm@latest and retry with a clean node_modules
• npx create-soa-agent exits with no output — the binary uses a symlink-aware main-guard; if you're seeing this on Linux/macOS you're on an older create-soa-agent version. npm cache clean --force then retry
• Node version mismatch — Runner refuses to start on Node < 20 with a startup error; upgrade Node

Which path? Decision tree

Two consumption modes, mutually exclusive:

(a) Scaffold a new agent — create-soa-agent

Use when: starting from scratch, want a working SOA-conformant Runner as your base.

npx create-soa-agent my-agent

Ships a minimal ReadOnly agent with a self-signed demo keypair. Replace the Agent Card + keys + tools with your own before deploying anywhere non-local.

(b) Wrap an existing LangGraph agent — @soa-harness/langgraph-adapter

Use when: you already have a project with @langchain/langgraph installed and a compiled StateGraph, and you want to make it SOA-conformant (signed Agent Card, permission interception, audit chain, StreamEvent emission).

# Assumes @langchain/langgraph ~0.2.74 and @langchain/core ^0.3.0 already in your project (peer deps)
npm install @soa-harness/langgraph-adapter

To preview the adapter without integrating it first, run the demo binary against a fixture graph:

npx -p @soa-harness/langgraph-adapter soa-langgraph-adapter-demo
# Logs adapter URL (default :7701) and back-end Runner URL, then idles until Ctrl-C

See packages/langgraph-adapter/README.md for the wrapping recipe. Conformance to SOA-Harness §18.5 Adapter Conformance requires pre-dispatch permission interception per §18.5.2 — the adapter handles this automatically.

Do not combine both paths in the same project — pick one.

What you get

A running Runner exposes the following HTTP surface (per SOA-Harness spec §5–§15):

Plus wiring for PreToolUse / PostToolUse hooks (§15), CRL cache (§7.3.1), handler key rotation (§10.6), and dynamic MCP tool registration (§11.3.1).

Packages

Published under the @soa-harness npm organization and create-soa-agent (unscoped).

All packages ship on the latest dist-tag at 1.0.0. The next dist-tag retires 14 days after the v1.0.0 release per the spec's dist-tag strategy.

Conformance status

Per-run breakdown:

• Native run against Core Runner URL: 152 pass / 0 fail / 10 skip / 0 error — 4 SV-ADAPTER probes skip when --adapter flag is absent
• Adapter run (--adapter=langgraph) against adapter demo URL: 4 pass / 0 fail / 158 skip / 0 error — SV-ADAPTER-01..04 pass; non-adapter tests auto-skip with scope=adapter-only

Conformance is validated by soa-validate, a separate Go conformance harness. The three-repo split — spec / impl / validate — prevents self-proving conformance. Two-run composition (native + adapter) is normative per the spec's adapter-conformance rules.

Conformance-label stance at v1.0.0:

• "Reference Implementation" — self-assigned for this TypeScript runtime plus the Go soa-validate harness, both shipping under the same v1.0.0 tag.
• "Bake-Off Verified" — requires one independent second-party implementation whose soa-validate output converges to zero divergence. Until one exists, downstream adopters claim Reference-level conformance only.

Cross-platform install verification passed on Windows 11 and WSL2 Ubuntu 24.04 with significant headroom against the onboarding-time budget (archived under docs/archive/m4/dry-run-telemetry.md).

Configuration surface

Environment variables the Runner reads (non-exhaustive; see packages/runner/src/config.ts for the full list):

Loopback-only test hooks are prefixed SOA_*_TEST_* / RUNNER_TEST_* and refuse to bind on non-loopback interfaces.

Sibling repos

• soa-harness-specification — normative spec (Markdown + JSON Schemas + test vectors). This impl pins to a specific spec MANIFEST digest via soa-validate.lock.
• soa-validate — Go conformance harness. Separate repo by design so the implementation and validator are independently authored.

Development

End-users consuming the published packages use npm (as shown in Quick start above). Contributors working on the monorepo itself use pnpm because the packages are wired as workspaces:

git clone https://github.com/wleeb1010/soa-harness-impl
cd soa-harness-impl
pnpm install
pnpm -r build
pnpm -r test   # 865 tests across 6 workspace packages

For in-monorepo scaffold iteration (file-linked runner instead of registry):

npx create-soa-agent --link my-agent

Publish process

See docs/m4/publish-runbook.md for the full recipe — pre-publish checklist, dist-tag discipline, post-publish verification, rollback.

License

Apache 2.0. See LICENSE.

Contributing

See CONTRIBUTING.md. Crypto-sensitive paths (packages/core, packages/runner/src/audit, packages/runner/src/session) require two-reviewer approval — see CODEOWNERS.