# harness

> Meta-worker that composes the modular Node workers backing the iii chat surface.

| field | value |
|-------|-------|
| version | 0.4.7 |
| type | bundle |
| repo | https://github.com/iii-hq/workers |
| author | iii |

## installation

```sh
iii worker add harness@0.4.7
```

## dependencies

- `iii-state` @ `^0.11.0`
- `iii-stream` @ `^0.11.0`
- `iii-directory` @ `^0.5.1`
- `database` @ `^0.2.2`

## readme

# harness

Node/TypeScript port of the iii harness stack. One package, one folder per
worker, one feature per file. Each worker is independently runnable as
`pnpm dev:<worker>` (development) or `iii-<worker>` (production binary).

The Rust workers `shell`, `iii-directory`, and the engine's `state::*`/
`stream::*`/`iii::durable::*` primitives are NOT ported — they run
alongside `harness` over the iii bus.

## Workers

| Folder | Bus surface | Role |
|---|---|---|
| `src/harness/` | `ui::subscribe`/`unsubscribe`, `harness::fs::read_inline`, `policy::check_permissions` | Meta-worker; loads `iii-permissions.yaml`; spins up `ui::*` fanout pumps. |
| `src/approval-gate/` | `approval::resolve` | Routes operator decisions to per-call `turn::approval_resume` fns (registered by turn-orchestrator). |
| `src/turn-orchestrator/` | `run::start`, `turn::{state}`, `turn::get_state` | Durable FSM driving each agent turn; `dispatchWithHook` approval chokepoint. |
| `src/session/` | `session-tree::*` (11 fns), `session-inbox::*` (3 fns) | Branching session storage + per-session inbox queues. |
| `src/llm-budget/` | `budget::*` (14 fns) | Workspace + agent LLM spend caps. |
| `src/hook-fanout/` | `hook-fanout::publish_collect` | Generic publish-and-collect over a stream topic. |
| `src/auth-credentials/` | `auth::*` (file-backed) | Provider credential store. |
| `src/models-catalog/` | `models::list`, `models::get`, `models::supports` | Static model metadata. |
| `src/provider-anthropic/` | `provider::anthropic::stream`, `provider::anthropic::complete` | Anthropic SSE → channel writer. |
| `src/provider-openai/` | `provider::openai::stream`, `provider::openai::complete` | OpenAI SSE → channel writer. |
| `src/provider-kimi/` | `provider::kimi::stream`, `provider::kimi::complete` | Kimi (Moonshot) Chat Completions SSE → channel writer. |
| `src/provider-lmstudio/` | `provider::lmstudio::stream`, `provider::lmstudio::complete` | LM Studio (localhost) Chat Completions SSE → channel writer. |
| `src/context-compaction/` | (none — pure side-car on `agent::events`) | Optional out-of-band session-history compactor. |

## Quickstart

```bash
pnpm install
pnpm build              # compile to dist/
# In separate terminals (or via your process manager):
node dist/harness/main.js               --url ws://127.0.0.1:49134 --config ./config.yaml
node dist/turn-orchestrator/main.js     --url ws://127.0.0.1:49134 --config ./config.yaml
node dist/approval-gate/main.js         --url ws://127.0.0.1:49134 --config ./config.yaml
node dist/session/main.js               --url ws://127.0.0.1:49134 --config ./config.yaml
node dist/hook-fanout/main.js           --url ws://127.0.0.1:49134
node dist/auth-credentials/main.js      --url ws://127.0.0.1:49134 --config ./config.yaml
node dist/models-catalog/main.js        --url ws://127.0.0.1:49134
node dist/provider-anthropic/main.js    --url ws://127.0.0.1:49134 --config ./config.yaml
node dist/provider-openai/main.js       --url ws://127.0.0.1:49134 --config ./config.yaml
node dist/provider-kimi/main.js         --url ws://127.0.0.1:49134 --config ./config.yaml
node dist/provider-lmstudio/main.js     --url ws://127.0.0.1:49134 --config ./config.yaml
node dist/llm-budget/main.js            --url ws://127.0.0.1:49134
# Optional side-car:
node dist/context-compaction/main.js    --url ws://127.0.0.1:49134
```

For development, replace `node dist/<worker>/main.js` with `pnpm dev:<worker>`.

## Configuration

All workers honour `--url` / `III_URL` for the engine WebSocket and
`--config` for the YAML config file (default `./config.yaml`).

The harness worker watches `iii-permissions.yaml` (default
`./iii-permissions.yaml`) and reloads it on change. The shipped default
file at the workspace root is symlinked into this folder.

## Layout

- `docs/` — architecture documentation: [`docs/architecture.md`](docs/architecture.md) is the system overview; one file per worker lives under [`docs/workers/`](docs/workers/).
- `src/types/` — wire types (mirrors `harness/crates/harness-types`).
- `src/runtime/` — cross-worker SDK helpers (worker bootstrap, state/stream wrappers, OTel stub).
- `src/<worker>/` — one folder per worker. Each `register.ts` composes the worker's bus surface from per-feature files; each `main.ts` is the binary entry-point.
- `tests/` — vitest suites per worker.

## api reference

```json
{
  "functions": [
    {
      "description": "Browser kickoff: forward payload to run::start. Used by console/web over the iii-browser-sdk.",
      "metadata": {},
      "name": "harness::trigger",
      "request_schema": {},
      "response_schema": {}
    },
    {
      "description": "Check a function call against iii-permissions.yaml; returns allow, deny, or needs_approval.",
      "metadata": {},
      "name": "policy::check_permissions",
      "request_schema": {
        "$ref": "#/definitions/CheckPermissionsPayload",
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "CheckPermissionsPayload": {
            "additionalProperties": false,
            "properties": {
              "args": {
                "additionalProperties": {},
                "type": "object"
              },
              "function_id": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "function_id"
            ],
            "type": "object"
          }
        }
      },
      "response_schema": {}
    },
    {
      "description": "Read a host file via shell::fs::read, drain its channel, and return a {content:[{text}], details:{size, truncated, bytes_read}} envelope (max 256 KiB inline by default).",
      "metadata": {},
      "name": "harness::fs::read_inline",
      "request_schema": {},
      "response_schema": {}
    },
    {
      "description": "Condition: state event is a new session record (event_type=state:created, scope=agent, key=session/<id>/turn_state).",
      "metadata": {},
      "name": "harness::session::is_create_event",
      "request_schema": {},
      "response_schema": {}
    },
    {
      "description": "Remove a browser's subscription to a session (or its all-sessions sub if session_id is null).",
      "metadata": {},
      "name": "ui::unsubscribe",
      "request_schema": {},
      "response_schema": {}
    },
    {
      "description": "Internal: agent::events fanout handler.",
      "metadata": {},
      "name": "harness::fanout::agent_event_handler",
      "request_schema": {},
      "response_schema": {}
    },
    {
      "description": "Internal: fans out a single newly-created session id to ui::sessions::changed::<browser_id>.",
      "metadata": {},
      "name": "harness::fanout::session_created",
      "request_schema": {},
      "response_schema": {}
    },
    {
      "description": "Register a browser's interest in a session (or all sessions if session_id is null).",
      "metadata": {},
      "name": "ui::subscribe",
      "request_schema": {},
      "response_schema": {}
    }
  ],
  "triggers": []
}
```