Named harnesses, and OpenRouter in place of managed

.github/workflows/ci.yml

@@ -897,7 +897,7 @@ jobs:
       - name: Test the ACP surface
         run: |
           scripts/ci/run-scoped-suite.sh "acp server" acp,runner,tinymemory server::acp
-          scripts/ci/run-scoped-suite.sh "acp run turn" acp,runner,tinymemory harness::acp_run_turn
+          scripts/ci/run-scoped-suite.sh "acp run turn" acp,runner,tinymemory harness::acp::run_turn
 
       # Issue #788: Chargebee billing — the REST layer (`chargebee::`) and the
       # toolbelt bridge (`harness::chargebee`) in one filter, which selects both.
@@ -1013,13 +1013,13 @@ jobs:
       # entry that decides whether an agent can reach them at all. An unrun
       # namespace pin is the wrong thing to have never executed.
       - name: Test tool-belt contract (openhuman, mcp, telegram, media)
-        run: scripts/ci/run-scoped-suite.sh "tool-belt contract" openhuman,mcp,telegram,media harness::build::tests
+        run: scripts/ci/run-scoped-suite.sh "tool-belt contract" openhuman,mcp,telegram,media harness::built_in::build::tests
 
       # The `media` toolbelt's other half: the three tool names and their single
       # `media` namespace. Same feature set as the step above, so this costs a
       # filtered re-run of an already-compiled tree and no fourth resolution.
       - name: Test the media toolbelt
-        run: scripts/ci/run-scoped-suite.sh "media toolbelt" openhuman,mcp,telegram,media harness::toolbelt
+        run: scripts/ci/run-scoped-suite.sh "media toolbelt" openhuman,mcp,telegram,media harness::built_in::toolbelt
 
       # The `mcp` OAuth-flow state, which the belt filter above never reached.
       # `app::types` holds two gated tests — a parked flow is SINGLE-USE (a
@@ -1079,10 +1079,10 @@ jobs:
       # the ACP step above states: the first bare argument is the filter and a
       # second would narrow the selection to nothing.
       - name: Test Composio tenant isolation
-        run: scripts/ci/run-scoped-suite.sh "composio isolation" openhuman,tinycortex,chargebee,paypal,composio harness::composio::isolation_tests
+        run: scripts/ci/run-scoped-suite.sh "composio isolation" openhuman,tinycortex,chargebee,paypal,composio harness::built_in::composio::isolation_tests
 
       - name: Test the Composio ops helpers
-        run: scripts/ci/run-scoped-suite.sh "composio ops helpers" openhuman,tinycortex,chargebee,paypal,composio harness::composio::ops_helper_tests
+        run: scripts/ci/run-scoped-suite.sh "composio ops helpers" openhuman,tinycortex,chargebee,paypal,composio harness::built_in::composio::ops_helper_tests
 
       # Issue #820 — which connected account an agent acts as. A third narrow
       # filter for the same reason the two above are narrow, and the same reason
@@ -1093,7 +1093,7 @@ jobs:
       # the negative half is the one protecting every existing single-account
       # company from having its account resolution changed.
       - name: Test which Composio account an execute acts as
-        run: scripts/ci/run-scoped-suite.sh "composio account choice" openhuman,tinycortex,chargebee,paypal,composio harness::composio::live::live_tests
+        run: scripts/ci/run-scoped-suite.sh "composio account choice" openhuman,tinycortex,chargebee,paypal,composio harness::built_in::composio::live::live_tests
 
       # Issue #820 — a fourth narrow filter, and the first outside `harness::`.
       # The console-plane half of the same decision: the grouping the choice is

docs/spec/README.md

@@ -90,6 +90,8 @@ L0  Substrate       api.tinyhumans.ai, openhuman-core, tiny.place, filesystem
 | [runtime/ports-runs.md](runtime/ports-runs.md) | `RunStore`: attempts and their traces |
 | [runtime/events.md](runtime/events.md) | `CompanyEvent` vocabulary + journal correlation rules |
 | [runtime/manifest.md](runtime/manifest.md) | `company.toml` schema, `agents.toml` compatibility |
+| [runtime/harnesses.md](runtime/harnesses.md) | Named execution engines: `built_in` vs `acp`, transports, per-agent binding |
+| [runtime/providers.md](runtime/providers.md) | Inference providers, dual-mode OpenRouter, per-harness credentials |
 | [runtime/globals.md](runtime/globals.md) | The global baseline every company gets: agents, workflows, skills, the starting tool belt, and `[globals].disable` |
 | [runtime/lifecycle.md](runtime/lifecycle.md) | Company state machine and durability |
 | [runtime/planning.md](runtime/planning.md) | The Planning station: pass contract, prerequisite verdicts, boot sweep |

docs/spec/runtime/README.md

@@ -46,7 +46,8 @@ Supporting docs:
 - [artifacts.md](artifacts.md) — what makes something a deliverable: the
   explicit-publish rule, `(task, source)` identity, body caps and reference
   bodies, and the single follow-up nudge
-- [manifest.md](manifest.md) — `company.toml` schema
+- [manifest.md](manifest.md) — `company.toml` schema,
+  with [manifest-semantics.md](manifest-semantics.md) for each key's behaviour
 - [globals.md](globals.md) — the global baseline: the agents, workflows, skills
   and starting tool belt every company gets whichever vertical it started from,
   how a company supersedes or disables one, and why provenance is persisted

docs/spec/runtime/agents.md

@@ -69,6 +69,9 @@ layout first.
 role = "Copywriter"                     # required
 description = "Write ads and campaign copy."
 tier = "reasoning"                      # cognition hint; never selects a model
+harness = "deep"                        # which [[harness]] runs this agent's
+                                        # turns — see harnesses.md. Omitted
+                                        # means the company's default harness.
 tools = ["docs.*", "mcp:notion"]        # grant globs — see tools.md
 delegates_to = ["creative"]             # desks this agent may hand work to
 budget_usd_daily = 5.0                  # per-agent daily cap
@@ -90,6 +93,19 @@ ledgers = [                                 # per-agent ledger access (omit for
 can_declare_ledgers = false                 # may this agent `define_ledger`? default true
 ```
 
+### `tier` versus `harness`
+
+They answer different questions and are deliberately separate fields.
+
+`tier` names a **workload** (`reasoning`, `vision`, …) and is resolved against
+whatever provider the agent's harness turns out to use. `harness` names the
+**engine and the credential**. So an agent keeps its tier when it moves between
+harnesses, and two agents sharing a tier on different harnesses run on different
+models — which is the point of naming more than one.
+
+Naming a harness the company does not declare is a validation error, reported
+against both the agent and the id. Naming none is not: every roster written
+before `[[harness]]` existed binds nobody, and all of them keep working.
 ### `context` write access
 
 A bare string in `context` is read-only — routed into the prompt, nothing

docs/spec/runtime/credentials.md

@@ -189,8 +189,20 @@ one account into a broken toolkit: when the console revokes an account, and when
 whatever credential the company's *declared provider* wants — an OpenRouter
 `sk-or-…`, a raw BYOK token, an `openai_compatible` key. It is provider-scoped,
 not an identity, and handing it to the TinyHumans backend would present one
-vendor's credential to another. The two coincide only when the declared provider
-is `managed`, and even then they are the same value for different reasons.
+vendor's credential to another.
+
+Since `managed`'s removal the two never coincide, which makes the separation
+cleaner rather than looser. A company holding **no** inference key rides the
+subscription on the platform's own credential — resolved from this host's
+identity, not from `inference/key` — and a company that sets one is naming an
+OpenRouter account that has nothing to do with TinyHumans. See
+[providers.md](providers.md).
+
+There is one such slot **per harness**: the default harness keeps the flat
+`inference/key`, and every named one uses `harness/<id>/inference/key`. The
+asymmetry is deliberate — the `SecretStore` has no rename, so namespacing the
+default too would orphan the stored credential of every company already
+running.
 
 ## What this does not cover
 

docs/spec/runtime/harnesses.md

@@ -0,0 +1,227 @@
+# Harnesses
+
+*What actually runs an agent's turn, and how a company picks.*
+
+Terms: [glossary](../glossary.md). The models a harness talks to are
+[providers.md](providers.md); the roster it runs is [agents.md](agents.md).
+
+---
+
+## What a harness is
+
+A **harness** is one answer to "what runs this agent's turn". A company declares
+a named set of them and binds each teammate to one, so a single roster can span
+a cheap model, an expensive one, and the operator's own coding CLI.
+
+Two kinds ship:
+
+| kind | what runs the turn | credential |
+|---|---|---|
+| `built_in` | the embedded OpenHuman/tinyagents loop, in this process | its own `[harness.inference]` |
+| `acp` | an external agent over the Agent Client Protocol | the agent's own |
+
+`built_in` is the default and the only kind that consults
+[providers.md](providers.md). An ACP agent already holds a credential — that is
+the point of it — so it needs nothing from us.
+
+### The case this exists for
+
+A desktop company with **no key at all**. The operator has Claude Code installed
+and signed in; OpenCompany drives it over ACP against their existing
+subscription. Nothing to configure on first run, which is a materially different
+product from one that opens on a credential form.
+
+The same seam serves two more things at no extra cost: reverse dispatch (a cloud
+host hands work to a runner on someone's machine, which is an ACP agent as far
+as this is concerned) and any other harness that speaks the protocol.
+
+---
+
+## Declaring harnesses
+
+```toml
+[[harness]]
+id      = "embedded"
+kind    = "built_in"
+default = true
+
+[harness.inference]                 # attaches to the entry above
+provider = "openrouter"
+
+[[harness]]
+id   = "deep"
+kind = "built_in"
+
+[harness.inference]
+provider       = "openrouter"
+api_key_secret = "harness/deep/inference/key"
+models         = { "reasoning-v1" = "<openrouter-slug>" }
+
+[[harness]]
+id   = "my_laptop"
+kind = "acp"
+
+[harness.acp]
+transport = "local"
+agent     = "claude"
+```
+
+`[harness.inference]` and `[harness.acp]` attach to the **most recently
+declared** `[[harness]]`. That is ordinary TOML array-of-tables sub-table
+syntax, but it is easy to misread as a company-level section, so it is worth
+reading twice.
+
+### Binding an agent
+
+```toml
+# agents/researcher.toml
+role    = "Researcher"
+harness = "deep"
+```
+
+Inline `[[agent]]` entries take the same field. An agent naming no harness runs
+on the one marked `default = true`.
+
+### The implicit harness
+
+A company with **no `[[harness]]` block** gets one implicit `built_in` harness,
+marked default, inheriting the company-level `[inference]`. Every bundle under
+`companies/` and every existing tenant lands here, so named harnesses are purely
+additive: nothing has to be rewritten to keep working.
+
+Read harnesses through `CompanyManifest::effective_harnesses`, never the bare
+`harnesses` field. A company that declares none still runs on a harness, and a
+caller reading the raw field would see an empty list and conclude it has no
+engine, which is never true.
+
+---
+
+## Validation
+
+`CompanyManifest::validate` rejects, in prosumer language:
+
+- a duplicate, empty, or non-snake_case `id`
+- zero or more than one `default = true`, naming the candidates either way
+- an agent naming a harness nothing declares, naming what *is* declared
+- `[harness.inference]` on an `acp` kind, or `[harness.acp]` on a `built_in` one
+- `transport = "local"` with no `agent`, or naming a `runner`; and the reverse
+  for `transport = "runner"`
+
+A section on the wrong kind is an **error, not an ignored key**. This is the
+same rule [agents.md](agents.md) applies to a bundle carrying both roster forms,
+and for the same reason: a silently discarded declaration stays invisible until
+the thing it configured misbehaves, and "my model setting does nothing" is an
+expensive way to discover that `[harness.inference]` needs `kind = "built_in"`.
+
+---
+
+## ACP transports
+
+```toml
+[harness.acp]
+transport = "local"      # spawn an agent on this machine
+agent     = "claude"     # claude | codex | goose
+
+[harness.acp]
+transport = "runner"     # reach one that dialed in
+runner    = "stevens_laptop"
+```
+
+**A remote runner is a transport, not a third kind.**
+`src/runner/dispatch.rs::RunnerDispatch` already implements the same `AcpAgent`
+port the local subprocess does, so the only thing that differs is how bytes
+reach the agent. Modelling it as a third kind would add a resolution path that
+resolves to the same place.
+
+The transports differ in where they live, which is why `AcpAgent` is a **port**
+rather than an ACP client in the host crate: a subprocess over stdio belongs to
+the desktop shell, a WebSocket to the runner lane. The same inversion the
+storage ports use.
+
+### Readiness
+
+For `transport = "local"`, the desktop probes four states rather than two:
+
+| state | what to do |
+|---|---|
+| `NotInstalled` | install it |
+| `NotSignedIn` | sign in |
+| `Ready` | — |
+| `SpawnFailed` | read the reason |
+
+**Installed but not signed in** is the most common state on a fresh machine, and
+it looks identical to "not installed" if all you check is `which`. The fixes are
+completely different, so collapsing them tells someone to do the wrong thing.
+
+Sign-in is probed by looking for the harness's credential file, not by running
+it: asking a harness whether it is logged in means starting it, which is slow on
+a list refreshed whenever a settings pane opens, and for some prompts
+interactively. The probe can be wrong in one direction — a stale credential
+reads as signed in — and that is the acceptable direction, because the failure
+then surfaces on first use with the harness's own message, which is more
+accurate than anything guessed.
+
+---
+
+## Routing
+
+`HarnessRouter` (`src/harness/router.rs`) holds one `RunTurn` per declared
+harness and forwards each call to the one its agent names. `RunTurn` already
+carried `agent_id` on all three of its methods, so the dispatch point always
+existed — nothing had ever varied on it.
+
+The lanes are built at runtime-build time by `harness::lanes::build`, and
+`HarnessBrain` routes through them. **A company declaring one harness (or none)
+builds no router at all** — `run_turn()` hands back the single lane directly, so
+the overwhelmingly common path is byte-identical to what it was.
+
+Each `built_in` lane gets its own `HarnessPool` and its own `HarnessDeps`,
+differing in exactly two fields: the provider (scoped to that harness's config
+and credential slots) and `serves`, which narrows the pool to the agents bound
+to it. That narrowing is what makes one-pool-per-harness affordable — without
+it, a ten-agent roster across three harnesses would stand up thirty live agents
+to use ten.
+
+All three methods route. A method forwarding to a fixed engine would send
+*dispatched card* turns to the wrong model while operator chat looked correct.
+
+### A harness with no engine fails the turn
+
+A harness can be declared, valid, and still have no engine. Today that is every
+`acp` harness on a server build: the transports live in the desktop shell (a
+stdio subprocess) and the runner lane (a socket), and neither is wired into the
+server. Those turns fail, naming the harness and the fix.
+
+They MUST NOT fall back to another harness's engine. That is the worst outcome
+available: the turn would succeed, on a model and a credential nobody chose, and
+the only evidence would be a billing line.
+
+---
+
+## What a harness does not decide
+
+- **`[brain].mode`** (`hosted` | `sidecar`) is a separate axis. It selects the
+  cognition seam *within* the built-in harness.
+- **Tools, policy, budgets, desks.** All company- or agent-scoped, and unchanged
+  by which engine runs the turn. An ACP agent is still subject to the company's
+  approval policy.
+- **Which model an agent's `tier` means.** A tier names a workload and is
+  resolved against whatever provider its harness turns out to use, so an agent
+  keeps its tier when it moves between harnesses. See
+  [providers.md](providers.md).
+
+---
+
+## Implementation map
+
+| concern | where |
+|---|---|
+| manifest types, kind/transport vocabularies | `src/company/types.rs` |
+| validation, `effective_harnesses`, `harness_for` | `src/company/manifest.rs` |
+| per-agent dispatch | `src/harness/router.rs` |
+| building the lanes at boot | `src/harness/lanes.rs` |
+| the built-in engine | `src/harness/built_in/` |
+| the ACP `RunTurn` and its port | `src/harness/acp/run_turn.rs` |
+| local transport: discovery, spawn, codec | `src-tauri/src/acp/` |
+| runner transport | `src/runner/dispatch.rs` |
+| per-harness roster narrowing | `HarnessDeps::serves` |