Host adapter

new SessionRuntime() constructs with zero config. But runtime.executeMessage(...) reaches back into the host application for capabilities the substrate doesn't ship absorbed yet — streaming utilities, fabrication guards, intent detectors, citation enrichers, tool registries. The seam is setHarnessModuleLoader.

This page is for hosts mid-migration. If you're building a new agent on @pleach/core, prefer the typed config surfaces (provider, tools, plugins, metaToolNames) — the loader seam exists for hosts that grew up with the substrate inside a larger app and are unwinding the integration gradually.

import {
  setHarnessModuleLoader,
  type HarnessModuleKey,
  type HarnessModuleLoader,
} from "@pleach/core/runtime";

What happens without it

Calling executeMessage without registering a loader produces:

HarnessModuleLoaderUnregisteredError: [harness] Module loader is not
registered. Tried to load key="orchestrator.intentDetector".
The host application must call setHarnessModuleLoader(...) at startup …

The error names the first key the runtime actually reaches for on a turn — an early turn-start key like orchestrator.intentDetector, not a later stream-phase key. Wire the loader at startup and the error goes away.

The 30-second contract

import { setHarnessModuleLoader, type HarnessModuleKey } from "@pleach/core/runtime";

setHarnessModuleLoader((key: HarnessModuleKey) => {
  switch (key) {
    case "orchestrator.streamDegenerationGuards":
      return import("@your-app/streamDegenerationGuards");
    case "orchestrator.fabricationGuard":
      return import("@your-app/fabricationGuard");
    case "orchestrator.intentDetector":
      return import("@your-app/intentDetector");
    // ... ~40 more keys ...
    default:
      throw new Error(`Unhandled harness module key: ${key}`);
  }
});

HarnessModuleKey is a string-literal union. TypeScript will tell you when a new key gets added — the default arm catches anything your switch doesn't cover.

The retirement direction

The loader surface is shrinking, not growing. Each @pleach/core release retires keys as the underlying capability moves into the substrate as typed config:

Keys retired so far:

Re-adding a retired key is a regression. The runtime's substrate test suite catches the regression at build time, not first turn.

The R-tracks

The retirement work is tracked as three named tracks. Hosts can opt into each independently.

The reference adapter at examples/host-adapter/reference.ts in the package marks every R-1-retired arm with a RETIRED YYYY-MM-DD (R-1.X, commit <sha>) comment. Hosts cribbing from that file should delete the marked arms rather than wire them.

CreatePleachRuntimeConfig.host.{strategies, modules, raw}

createPleachRuntime() accepts a typed host carveout that groups the host-private substrate dependencies under three named fields. The carveout is the destination loader-bag keys absorb into as they retire — once a key lands here, the loader stops being asked for it on that runtime.

import {
  createPleachRuntime,
  type CreatePleachRuntimeConfig,
} from "@pleach/core";

The 15 keys host.strategies accepts (from HostExtensionBundle):

orchestratorConfig, lineageTracker, agentRegistry, planManager, learningAuditor, preserveDataRefFields, getDataHandlerFactory, dataChannelRefetch, continuationShadowResolver, entityNameCounter, structurePrefetcher, artifactCacheReader, guestDeniedTools, fabricationDetectorRules, recordGarbledOutput.

The 3 keys host.modules accepts: eventLogWriter, store, interrupt.

const config: CreatePleachRuntimeConfig = {
  plugins: [compliancePlugin, gatewayPlugin],
  host: {
    strategies: {
      lineageTracker: myLineageTracker,
      planManager: myPlanManager,
      guestDeniedTools: GUEST_DENIED,
    },
    modules: {
      eventLogWriter: mySupabaseEventLogWriter,
      store: myMultiNamespaceKV,
    },
    // raw: { ... }  — only when a field is neither classified above nor a top-level option
  },
  userId: "user_123",
};

const runtime = createPleachRuntime(config);

The three fields are independent. A host can fill strategies without touching modules; a host with no operator-supplied module shims can omit modules entirely. raw is the safety valve — prefer strategies/modules when applicable so the autocomplete surface stays meaningful.

Merge precedence

Top-level fields → host.strategies → host.modules → host.raw → (deprecated) advanced. Higher precedence wins on key collision. advanced?: Partial<SessionRuntimeConfig> stays in the shape for 1.x back-compat with the pre-1.0 surface; it retires in 2.0. New hosts shouldn't reach for advanced.

Bag-entry retirement readiness

A per-bag-entry status report tracks the migration off the orchestratorHotpath bag toward the typed surface + plugin-routed runtime.plugins.collect* cohort. The bag is transitional, not terminal — every entry carries an inline retirement-path comment on the OrchestratorHotpathModules interface declaration.

The canonical routing layer is runtime.plugins.collect* — the bag is the legacy fallback. Hosts adopting facets should read through the plugins facet, not the bag. See Facets.

Audit gates enforcing the contract

Four gates run in CI on the upstream core repo. Their job is to catch "we typed the hook but the bag read is still load-bearing" regressions at build time, rather than at first turn in production.

pleach-plugin-modernize codemod

The codemod rewrites the four soft-deprecated bare properties into their typed contribute* method form. It does not migrate to definePleachPlugin — it's a narrower rewrite that produces method-form plugins which definePleachPlugin can then accept.

tools: [a, b]            →  contributeTools: () => [a, b]
events: { foo: ... }     →  contributeEventTypes: () => ({ foo: ... })
customEventTypes: [...]  →  contributeEventTypes: () => [...]
batchingHints: [a, b]    →  contributeBatchingHints: () => [a, b]

The codemod is an internal repo script in the upstream core repo, not a published npm binary:

node scripts/codemods/pleach-plugin-modernize.mjs <glob> [--dry-run] [--json]

It only rewrites bare properties inside object literals containing a name: "<string>" field, so arbitrary objects aren't touched. Collision-safe — if a contribute* method already exists alongside the bare property in the same plugin object, the codemod warns to stderr and skips. customEventTypes folds into contributeEventTypes only when no events / contributeEventTypes already exists in the same literal; otherwise it's left for manual merge.

It's the prep step for the upcoming bare-property cut, after which those forms become type errors. The output composes with definePleachPlugin without further edits.

setOrchestratorHotpathModules

A second registration helper for hot-path modules — capabilities called synchronously inside the per-call seam loop, where dynamic import overhead would matter.

import { setOrchestratorHotpathModules } from "@pleach/core/runtime";

setOrchestratorHotpathModules({
  fabricationGuard: fabricationGuardModule as never,
  // ... other hotpath modules
});

Used for capabilities that are domain-coupled in a way the substrate doesn't want to absorb. The fabrication guard, for example, carries host-specific regex tables (tool aliases, phantom tool replacements, identifier patterns) — registering it synchronously keeps host-domain rules in host code without introducing dynamic-import latency on the per-call path.

metaToolNames (the canonical R-1.A migration)

Hosts that previously resolved CONTINUATION_META_TOOL_NAMES through the loader should now pass them as typed config:

import { SessionRuntime } from "@pleach/core";

const runtime = new SessionRuntime({
  metaToolNames: new Set([
    "set_step_complete",
    "wait_for_jobs",
    // ... your meta-tool names
  ]),
  // ...other config
});

Without the field, the runtime fires a one-shot probe lazily on the first read of the meta-tool set (not at construction) — the _getMetaToolNames() accessor emits it the first time a guard reaches for the set and finds it undefined:

[UXParity:metaToolNames-config-missing] { reason: "metaToolNames-undefined-at-read", ... }

The runtime then falls back to a shared empty set, which silently disables continuation and fabrication guards that key off the set. (setOrchestratorAdapter is unrelated — it's a deprecated delegating stub that forwards to the adapter facet and emits no metaToolNames warning.) Fix by passing the field; never ship past the probe in production.

The reference adapter

The package ships two reference adapter files at examples/host-adapter/:

Start from index.mjs for a brand-new host — implement one key at a time as you need it. Crib from reference.ts to see the full set of keys a mature integration wires.

What gets called when

Different keys resolve at different turn phases. A rough map:

The runtime does not cache resolved modules itself — dynamicImportApp re-invokes the registered loader on every call. Deduplication comes from the process-wide import() module cache the loader delegates to, so a key resolves cheaply on repeat reaches but the loader still runs each time (scope is process-wide, not per-runtime-lifetime).

When you don't need the loader

For a brand-new host that's not bringing a legacy orchestrator into the substrate:

• Use the typed provider config field for LLM execution.
• Use the plugins config field for domain extensions.
• Use metaToolNames for continuation flow control.
• Register tools through plugin contributeTools or the legacy setOrchestratorRegistry shim.

You'll still hit some loader-required keys (the substrate is mid- migration), but the minimum set is small. The no-op adapter at examples/host-adapter/index.mjs implements just the keys required for a first-turn execution to land.

Where to go next