Effect agent harness demo

A production-shaped monorepo whose demo is a deliberately small agent harness. The interesting part is the code architecture: Effect schemas describe every boundary, services state capabilities, layers assemble implementations, and tests swap the model and tools without mocks or global state.

The repository does not ship a model credential or pretend that arbitrary process execution is safe. The AI provider is an adapter seam, and the Rust worker is a bounded process supervisor—not a security sandbox.

Tour

Path	Purpose
apps/cli/	Effect CLI for local and operator-driven harness runs
apps/harnessd/	Typed HTTP API and long-lived Bun runtime boundary
apps/native/	Tauri shell with one managed Effect runtime at the UI boundary
apps/web/	Small Bun status server and architecture landing page
packages/agent-core/	Stable schemas, errors, services, event journal, and agent loop
packages/agent-demo/	Shared provider-free model, tool, and runnable demo layer
packages/agent-runtime/	Isolated effect/ai and supervised-shell adapters
packages/agent-testkit/	Scripted model and deterministic tool layers
packages/infra/	Alchemy stack composition for the deployable web surface
packages/sandbox-client/	Effect Schema contract shared with the Rust worker
crates/agent-sandboxd/	NDJSON process supervisor with deadlines and output bounds
crates/alloy-web3-example/	Alloy HTTP provider and sol! contract interface example
crates/cloudflare-worker-example/	Rust (workers-rs) Cloudflare Worker deployed by the Alchemy stack
contracts/	Foundry Solidity project with Counter contract and forge tests
docs/adr/	Architecture Decision Records for standing repo decisions

Start with packages/agent-core/src/services/AgentHarness.ts, then read packages/agent-testkit/test/agent-harness.test.ts. The test is the shortest executable explanation of the design.

Use it

Initialize a project

In an empty directory, choose a slice of the maintained repository:

nix flake init -t github:darkmatter/template#nix-ts-lib
# Or: #nix-rust-lib / #nix-polyglot-lib

Template	Source slice
nix-ts-lib (default)	agent-core, agent-demo, agent-runtime, agent-testkit, sandbox-client, web-core, and shared tooling packages
nix-rust-lib	The agent-sandboxd supervisor and alloy-web3-example Rust crates
nix-polyglot-lib	Both slices above

All three exclude apps/, infrastructure deployment examples, and app-specific Nix outputs. nix/templates.nix selects tracked source paths; it does not keep copies of library implementations, manifests, or tooling configuration. The shared flake and devshell adapt to the languages present. Initializing a template creates a snapshot, not a live link to upstream.

Run git init and git add . in the initialized directory so Nix and the root policy check can see the files, then enter nix develop. For TypeScript, run bun install --frozen-lockfile, bun run check, bun run test, bun run lint, and bun run fmt:check. For Rust, run cargo check --workspace and cargo test --workspace. Run both sets for the polyglot slice, and nix flake check for any slice.

The workspace manifests and lockfiles are reused unchanged apart from shared scripts supporting absent apps. Bun skips lockfile workspaces not included in the slice; app-only commands such as bun run dev are for the full repository, not the library templates.

Harness demo

The full repository retains the runnable applications and operational tooling:

nix develop
bun install
x test
x dev

Open http://localhost:3000. The status API is /api/status; metrics are at /api/metrics.

Run the deterministic harness from the terminal:

bun run cli run --events "Explain the harness boundaries"

Or start the daemon and submit the same run over its schema-described API:

bun run harnessd
curl -sS http://127.0.0.1:4319/runs \
  -H 'content-type: application/json' \
  -d '{"goal":"Explain the harness boundaries"}'

The daemon publishes its OpenAPI document at http://127.0.0.1:4319/openapi.json.

Validate both language stacks:

bun run check
bun run test
bun run lint
bun run fmt:check
cargo check --workspace
cargo test --workspace
forge test --root contracts

Design notes

• agent-core imports no provider SDK, desktop framework, or process API.
• CLI, daemon, and desktop consume the same DemoHarnessLayer; none owns a second orchestration loop.
• AgentHarness.layerNoDeps captures its dependencies once and exposes an operation with no hidden environment requirement.
• Domain failures use schema-backed tagged errors and remain recoverable.
• The in-memory journal uses Ref, PubSub, and Stream, bounding retained histories while returning each terminal snapshot atomically; persistence can replace its layer without changing the loop.
• The Effect AI surface is quarantined in agent-runtime so provider churn cannot spread through the domain.
• Tauri owns callback execution through one ManagedRuntime; libraries only describe effects.
• Alchemy owns infrastructure composition, not the application agent runtime.
• Typed RPC examples should use effect-orpc with compatible @orpc/* peers; see apps/harnessd/src/orpc.ts for the minimal Effect procedure pattern.
• Postgres is the preferred application data store. Use kysely + pg or @effect/sql-pg for new persistence examples; existing D1 resources are Cloudflare demo infrastructure rather than the recommended default.

See the architecture guide for dependency direction and the canonical patterns note for the version-pinned Effect and Alchemy decisions. Standing structural choices are recorded in Architecture Decision Records.

Operations

ops/ remains the repository's operational boundary for containers, environments, deployment, SOPS material, observability, and policy. See ops/README.md. The web config can add an encrypted SOPS document behind environment config through alchemy-sops; decrypted values never enter the status payload.

License

Private reference repository.