Application model

The product boundary

The harness should own application-level orchestration and lifecycle management. Execution backends should continue to own agent execution semantics. This distinction is the core design rule for every feature request, config decision, and public API addition.

Stable runtime records

The public runtime should talk in terms of product records and operator outcomes rather than checkpoint internals. The important nouns are requests, sessions, approvals, events, and lifecycle actions such as start, inspect, resolve, and stop.

Why the API surface stays small

The runtime contract should remain product-facing and stable. The public model is intentionally smaller than the underlying adapter internals because the runtime must survive backend changes without redefining the app.

createAgentHarness(...)
request(...)
subscribe(...)
listRequests(...)
listSessions(...)
listApprovals(...)
resolveApproval(...)
getHealth(...)
stop(...)

If a proposed feature mainly mirrors adapter-private semantics or backend-specific tuning state, it probably does not belong in the stable runtime contract.

Upstream alignment

The product should stay losslessly aligned with upstream execution semantics. The runtime can translate and adapt internally, but it should not expose a second local meaning for concepts upstream already defines.

Good pattern

Keep backend translation inside the adapter layer and expose stable runtime concepts only when the product genuinely owns them.

Bad pattern

Inventing harness-specific semantics for upstream memory, graph, checkpoint, or execution behavior just to make the config look uniform.

Choosing an execution backend

Backend selection is an agent configuration choice, not a change in product identity. The same runtime still owns approvals, inspection, lifecycle, recovery, and operator behavior.

• Use backend: deepagent when higher-level orchestration semantics are the natural fit.
• Use backend: langchain-v1 for lighter agent shapes or explicitly chosen LangChain flows.
• Do not expose backend-specific abstractions as if they were first-class product concepts.

Design implications

This model affects everything else in the docs. YAML stays runtime-oriented and backend-neutral where possible. Docs should explain behavior in runtime language first. Tests should validate stable records and product-visible lifecycle, not only adapter internals.