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 worker add <name>, which resolves the matching asset for the host from the workers registry API.

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,shell

# 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

Modules

Worker	Kind	Summary
acp	Rust	Agent Client Protocol surface — stdio JSON-RPC, exposes iii agents as ACP sessions.
harness	Node	TS port of the iii harness stack — bundles harness (provider registry + credentials/settings/permissions via the configuration worker), turn-orchestrator, approval-gate, hook-fanout, models-catalog, the provider-* workers, llm-budget, and context-compaction as one pnpm monorepo. Conversations persist in session-manager. See harness/README.md.
session-manager	Rust	Durable, reactive, branching conversation store — fourteen session::* functions plus six trigger types; the transcript backend for harness and console. See session-manager/architecture/.
database	Rust	PostgreSQL, MySQL, and SQLite client — query, execute, transactions, prepared statements, and change feeds.
iii-directory	Rust	Engine introspection (functions / triggers / workers), workers-registry proxy, and filesystem-backed skill + prompt reader.
iii-lsp	Rust	Language Server for iii function ids, trigger configs, and worker discovery. Autocomplete / hover across JS/TS, Python, Rust.
iii-lsp-vscode	Node	VS Code extension that embeds iii-lsp.
image-resize	Rust	Image resize via channel I/O — JPEG/PNG/WebP with EXIF auto-orient, scale-to-fit / crop-to-fit.
mcp	Rust	MCP 2025-06-18 Streamable HTTP bridge — exposes iii functions tagged mcp.expose as MCP tools.
shell	Rust	Unix shell + filesystem worker — shell::exec with allowlist/denylist/timeout/output caps and background jobs; fs::ls/stat/mkdir/rm/chmod/mv/grep/sed/read/write with host jail, denylist, and size caps.
storage	Rust	S3-compatible object storage across AWS S3, GCS, Cloudflare R2, and a managed local rustfs backend. Streamed uploads, presigned URLs, and object change triggers.
todo-worker	Node	Quickstart CRUD todo worker using the Node iii SDK.
todo-worker-python	Python	Quickstart CRUD todo worker using the Python iii SDK.

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).

Binary releases

Rust workers ship as standalone binaries — see the modules table above — and are released via GitHub Actions:

1. Trigger the Create Tag workflow (Actions tab) — pick a worker, bump type (patch/minor/major), and a registry tag (latest / next).
2. A tag of the form <worker>/v<X.Y.Z> is pushed to main, with the registry tag embedded in the tag's annotated message.
3. The unified Release workflow fires on the tag, cross-compiles binaries for up to 9 targets (Linux gnu/musl, macOS x86_64 + aarch64, Windows x86_64/i686/aarch64, armv7), uploads them to a GitHub Release with SHA-256 checksums, and calls POST /publish on the workers registry API.

Targets per build (Windows targets are skipped on POSIX-only workers such as shell):

aarch64-apple-darwin
x86_64-apple-darwin
x86_64-pc-windows-msvc
i686-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

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 the worker's collected function + trigger interface. iii worker add <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 deploy: 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 worker add, 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 by reading each worker's iii.worker.yaml, 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, iii.worker.yaml valid, tests/ non-empty, and the manifest version is greater than the version on the PR's base branch.

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

CD

Releases are cut manually via the Create Tag workflow (.github/workflows/create-tag.yml) — pick a worker, a bump type, and a registry tag (latest / next). The resulting <worker>/v<X.Y.Z> tag drives a single dispatcher (.github/workflows/release.yml) that:

1. Routes on deploy from iii.worker.yaml:
   • binary → cross-compile via _rust-binary.yml.
   • image → multi-arch image to ghcr.io/<owner>/<worker> via _container.yml.
   • bundle → single-file archive via _bundle.yml.
2. Calls POST /publish against the workers registry API via _publish-registry.yml.

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

License

Apache 2.0 — see LICENSE.