iii workers

Workers for the iii engine. Each top-level directory is a self-contained worker module: a process that connects to the engine over WebSocket, registers functions + triggers, and does something useful.

Workers are installed via iii trigger compose::add worker=<name>, which resolves the matching asset for the host from the workers registry API.

Develop the Harness locally

The template/ project runs the local Harness source with Harness Medium agent profiles, skills and configuration seeds already in place:

cd template
iii compose --up

It uses the sibling worker directories in this checkout, including ../harness, not a published Harness package. See the template guide for authentication, the console URL and restarting a worker after a source change. With the stack stopped, refresh upstream profiles and skills using ./template/sync.sh --stack-stopped (or preview with --dry-run). It preserves local configuration and Compose files and records the exact imported commit. The original source-only stack remains available.

Skills

Each worker ships an agent skill under <worker>/skills/. Install them with the skills CLI (works with Claude Code, Cursor, and 30+ other agents).

# List every worker skill in this repo
npx skills add iii-hq/workers --list

# Install one worker's skill
npx skills add iii-hq/workers --skill database

# Install several
npx skills add iii-hq/workers --skill database,coder,ide

# Install all worker skills at once
npx skills add iii-hq/workers --all

For the iii engine's top-level skills (mental model, SDKs, config, patterns), see iii-hq/iii:

npx skills add iii-hq/iii --all

Kits

kits/ holds kits: agent profiles, skills and the workers they need, installed together through iii-directory (see Kits). Current kit: deepwork, dynamic multi-agent workflows on the kanban board.

Modules

Worker	Kind	Summary
whatsapp	Go	Linked-phone sessions through whatsmeow and official Meta Cloud API messaging, attachments, groups, and filtered events; includes ADE setup and integration tests.
acp	Rust	Agent Client Protocol surface — stdio JSON-RPC, exposes iii agents as ACP sessions.
approval-gate	Rust	Human-in-the-loop approval gate — evaluates each function call (continue / deny / hold), holds pending calls for a human, and emits approval::pending-* events. Binds the harness pre_trigger hook. See approval-gate/architecture/.
harness	Node	TS port of the iii harness stack — bundles harness (provider registry + credentials/settings/permissions via the configuration worker), turn-orchestrator, hook-fanout, models-catalog, the provider-* workers, llm-budget, and context-compaction as one pnpm monorepo. Approval is delegated to the standalone approval-gate worker via the pre_trigger hook. Conversations persist in session-manager. See harness/README.md.
eval	Rust	Durable same-model A/B evaluation for prompts and system prompts — runs paired harness sessions, delegates correctness to iii evaluator functions, and reports pass rates with token, cost, latency, function-call, trace, and span metrics.

SDK

Workers target the iii-sdk package on each ecosystem:

• Rust — crates.io/crates/iii-sdk
• Node — npmjs.com/package/iii-sdk
• Python — pypi.org/project/iii-sdk

Each module pins its exact version in its own manifest (Cargo.toml, package.json, or pyproject.toml).

Build

Rust workers:

cd <worker>
cargo build --release

Node/Python workers follow the standard npm install / pip install -e . flow — see each module's README for specifics. harness is a pnpm monorepo (pnpm install && pnpm build).

Harness local development

See harness/DEVELOPMENT.md to start the iii engine and the local Harness stack with worker-compose.yaml.

Binary releases

Rust workers ship as standalone binaries. Release Control is the only supported interface for starting, retrying, reconciling, or canceling a deployment. GitHub Actions only executes its authenticated steps. See docs/sops/release.md for the sequence and recovery rules.

Default targets per build (workers with platform restrictions declare an explicit subset in .deploy/workers.yaml; for example, ide excludes Windows and sandbox-code-runner excludes Intel macOS):

aarch64-apple-darwin
x86_64-apple-darwin
x86_64-pc-windows-msvc
aarch64-pc-windows-msvc
x86_64-unknown-linux-gnu
x86_64-unknown-linux-musl
aarch64-unknown-linux-gnu
armv7-unknown-linux-gnueabihf

Intel macOS builds run natively on GitHub's macos-15-intel runner; Apple Silicon builds keep the dedicated workers-release-macos-arm-5core pool. Changes to this matrix take effect in newly built and published worker versions; existing Registry versions and immutable release assets are not retrofitted.

Local binary matrix

Build a Rust worker locally without waiting for GitHub Actions:

python3 .github/scripts/build_worker_binaries.py ide

On Windows, use py .github\scripts\build_worker_binaries.py ide. The TUI starts with every target available on the current host selected; use the arrow keys and Space to change the matrix, then Enter to build. Archives and SHA-256 files are written to dist/workers/<worker>/ using the same names as release assets.

The local matrix deliberately excludes all MSVC targets. Linux targets build through cross, backed by Docker or Podman, on macOS, Linux, or Windows. Apple targets build with Cargo and the Apple SDK, so they are available only when the host is macOS. Workers with UI bundles also require Node.js and pnpm; their frontends are built once before the Rust matrix starts.

Prerequisites:

cargo install cross --locked
docker info # or: podman info

For automation, skip the TUI with --all or --targets <triple>,<triple>. Use --plan to inspect the resolved matrix without compiling.

Registry

Workers are discovered through the workers registry API at https://api.workers.iii.dev. Each release publishes a manifest entry declaring the worker kind (binary / container image), supported targets, download URLs, and immutable package metadata. iii trigger compose::add worker=<name> queries this API to locate the right asset for the host.

Add a new worker

Start with docs/sops/new-worker.md — the cross-cutting checklist (naming, required files, CI gates, release wiring). For the inside of a Rust artifact.kind: rust-binary worker, continue with docs/sops/binary-worker.md. Each worker ships a consumer README.md per the worker-readme.md contract (install via iii trigger compose::add worker=<name>, quickstart, configuration). docs/README.md indexes all shared docs.

CI

Pull requests trigger per-worker lint + tests for the changed worker(s). .github/workflows/ci.yml discovers changes from the private .deploy/workers.yaml build catalog, then routes:

• Rust → cargo fmt --check, cargo clippy -- -D warnings, cargo test --all-features
• Node → biome ci against biome.json and npm test
• Python → ruff check + ruff format --check against ruff.toml and pytest

The pr-checks job additionally enforces, per changed worker: README.md present, the private build entry and public iii.worker.yaml valid, tests/ non-empty, and the package version not behind the PR base. It also requires non-empty public discovery tags on workers whose interface capture is enabled — see the Discovery tags step.

Full reference (discovery buckets, interface boot smoke, e2e workflows): docs/architecture/testing-and-ci.md.

CD

Release Control is the only supported release interface. For each source SHA, deploy-descriptor-index.yml uses the repository-owned compiler to join .deploy/workers.yaml, the public manifest, and the package manifest exactly once.

This repository only builds. build.yml takes one worker and one exact source SHA, validates the selected descriptor, builds one independent job per build unit through _deploy-build.yml, captures the registered interface, and uploads only immutable, content-addressed bytes:

• release assets under the shared build-<source_sha> prerelease, uploaded once and never overwritten (an existing asset with different bytes fails the job);
• an OCI index tagged build-<source_sha> when the descriptor declares an image;
• an attested build-manifest artifact naming every asset by URL and SHA-256, the image digest, the descriptor and the captured interface.

Release Control reads that manifest and publishes the Registry version, moves the @next or @latest channel by compare-and-swap, creates the versioned GitHub release and tags the image. No workflow here knows a version, a channel or a Release Control endpoint.

Step-by-step (variants, troubleshooting, rollback): docs/sops/release.md.

License

Apache 2.0 — see LICENSE.