Drivers & connections

Source: harness/docs/runtime/drivers.md — status: current.

Drivers & connections

Drivers come from registered driver providers selected by product composition (../packages/harness-server/src/composition.ts; PRODUCT_PROVIDERS opened as openDriverRegistry(PRODUCT_PROVIDERS)).

Plugins do not introduce drivers. Extension plugins are not a source of new drivers. New capability arrives as connections on existing drivers (/connect, MCP servers), as pack tools on InhumanPlugin, or as .scm commands — never as third-party driver code. Driver providers are not loaded through plugin manifests or the plugin loader.

Grain: ../canon/grain.md — DriverSpec / ConnectionSpec projected by KernelReflector onto KernelRoot; faces from spec.live; demand materializes via ensure; tool work points at ConnectionSpec; wire names are projection. PEW/Driver / PEW/Connection contract: ../packages/plexus-expectations/README.md (PEWDriverConnection, ensure / broken, pre-load can).

1. Driver roster

The registered driver-provider roster. Names, can, and multiplicity are preserved. importPath for a shipped driver is the driver name; resolution is in-process (DriverRegistry.connectionClass(name) over PRODUCT_PROVIDERS), no import() at adopt. Product composition selects this roster. Plugin manifests do not load it.

Name	`can`	Multiplicity	What
`openai-compat`	completion	add-as-secondary	OpenAI-compatible chat completions
`openrouter`	completion	add-by-default	OpenRouter (PKCE key exchange)
`nous`	completion	add-by-default	Nous Portal (device-code OAuth)
`chatgpt`	completion	add-by-default	ChatGPT subscription (OIDC)
`grok`	completion, web-search	add-by-default	Grok subscription (OIDC); pin to use as search
`mcp-stdio`	mcp	add-as-secondary	MCP stdio (spawned server)
`mcp-http`	mcp	add-as-secondary	MCP Streamable HTTP
`web-keyless`	web-search, web-extract	add-by-default	Implicit keyless ring (Exa → Parallel → Firecrawl → Keenable → Tavily)
`web-nous`	web-search, web-extract	add-by-default	Projected intern when a `nous` connection exists; Firecrawl gateway + Portal JWT. Pick: pin → file BYOK dedicated → this intern → keyless
`exa`	web-search, web-extract	add-as-secondary	Exa neural search (API key)
`parallel`	web-search, web-extract	add-as-secondary	Parallel AI search (API key)
`firecrawl`	web-search, web-extract	add-as-secondary	Firecrawl search (API key or self-hosted URL)
`keenable`	web-search, web-extract	add-as-secondary	Keenable web index (API key)
`tavily`	web-search, web-extract	add-as-secondary	Tavily search and extract (API key)

oidc/ is an internal base class for chatgpt/grok/nous, not a driver row. Hermes is an OAuth client of Nous Portal, not a driver ID. web-nous is projected by reflectKernel (not adopted, not a second secret bag).

2. Split

DriverSpec (registered roster + KernelReflector)      PEWDriverConnection (after ensure)
  name, description, importPath                class.bootstrap()
  supported Expectation model names            new (ConnectionSpec) → instance
        │
        ├── pre-load can (names + entityClasses lens)   ← commands / pickers read this
        │
        └── ensure → instance.resolve(Expectation)      ← PEW/Work only

Read path	Write / work path
DriverSpec / ConnectionSpec faces, pre-load `can`, ready/broken status	ensure + PEW resolve → ExpectationActor

Commands wrap the read path. ConnectionSpec membership is config.json keys; specs and faces come from the files via KernelReflector onto KernelRoot. DriverSpec inventory is the registered driver-provider roster (composition → openDriverRegistry(PRODUCT_PROVIDERS) in reflectKernel).

3. Inventory upserts in place

../packages/harness-server/src/daemon/kernel/fs-reflection/reflectKernel.ts projects files onto the live KernelRoot. It does not reconstruct the graph. Each row is:

into.drivers[name]        ??= new DriverSpec()
into.connections[id]      ??= new ConnectionSpec({ driver })
into.plugins[pluginName]  ??= new InstalledPlugin()
into.commands[verb]       ??= new CommandSpec()

Then fields are written onto that same object. Dropped names are deleted. Identity is stable across a file reload; clients holding a spec keep the same node.

reflectKernel still merges inventory.drivers from plugin plugin.json after the registered roster. No shipped plugin uses that door. The merge is unsupported. Product law is the roster above — plugins do not introduce drivers. Do not document the merge as a supported hatch for plugin-supplied drivers. Removing that path is a later explicit edit.

4. Multiplicity (from driver face)

Value	Meaning for `/connect`
`add-by-default`	adopt can be terminal from driver pick
`add-as-secondary`	nested context acquires config, then adopt

5. Scheme ambient

(harness/kernel/…) reads the KernelReflector projection (files → KernelRoot), not a kernel dial.

(harness/kernel/drivers :can 'completion)   ; DriverSpec list
(harness/kernel/connections)                ; ConnectionSpec list
(harness/kernel/can (harness/kernel/driver c))
(:models (:live c))                         ; openai-compat invocation ids
(harness/kernel/issue c)

Thin over KernelRoot catalog. Entities cross as opaque handles; field reads are host verbs. can is the DriverSpec claim (Expectation model names / claim classes), available before resolve.

6. Verb split

Verb	Uses for
`/connect`	drivers + connections; adopt / drop; set current wire (+ last-used model)
`/model`	list invocation ids from `live.models` on completion wires; set session model
`/mcp`	MCP ConnectionSpecs; health / tool count / session disable / authenticate; add is `mcp-server/adopt`

Operator tools globs and toolSeverity overlay: ../client/operate.md. Hidden names leave the catalog and still fail tools/call. Severity is not a license.

See ../plugins/commands.md for choice/action surface and partitions.

7. Laws

Plugins do not introduce drivers. Extension plugins are not driver providers. Anything that needs harness/models is daemon code; a plugin depends on the plugin SDK (@inhuman.tools/plugin-sdk) and Arrival only.
No scheme path that writes load authority or free filesystem import targets.
Specs and faces are observations; ensure + resolve are work.
can is claimed Expectation model names on the DriverSpec, not the catalog tool list.

8. Code anchors

Driver roster + in-process resolve — ../packages/harness-server/src/composition.ts
Spec registry (files → KernelRoot) — ../packages/harness-server/src/daemon/kernel/fs-reflection/KernelReflector.ts + ../packages/harness-server/src/daemon/kernel/fs-reflection/reflectKernel.ts
Ensure / PEWDriverConnection contract — ../packages/plexus-expectations/README.md
PEW executor (claim owner only): orchestrator ensure + actor spawn — PEW/Work boundary, not command inventory