agentKeep the harness in control
AgentRun's document and authoring APIs can be adopted independently of its interpreter. A host that already implements Workflow v2 should validate every emitted document with its own validator before activation. Matching format versions do not imply matching supported primitives or recovery guarantees.
| Boundary | DSL responsibility | Host responsibility |
|---|---|---|
| Definition | Types, schemas, graph, validation, digest | Candidate custody, review, supported grammar, activation |
| Model work | Requested input, output and SOP sections | Model configuration, complete SOP/skill context, tools, budgets |
| Effects | Declared calls, deadlines, retries, result validation | Tool permissions, idempotency receipts, unknown-effect reconciliation |
| Lifecycle | Execution events and scoped hooks | Durable stores, cancellation, steering, recovery compatibility |
| Delivery | Declared output or terminal artifact | File custody, delivery and independent acceptance |
Adopt authoring first
defineWorkflow emits ordinary v2 JSON. An existing host can consume it without importing runTypedWorkflow or replacing its interpreter. Validate the serialized document through the actual host, then compare successful output, escalation, assembled SOP context, digests, and recovery behavior.
The optional integration probe does this against a separately built compatible harness:
node scripts/check-harness-compatibility.mjs /absolute/path/to/built-harness
It imports that harness's development bundle and uses scripted adapters. It checks compatible graph execution, malformed input rejection, complete SOP slices, skill propagation, pin identity, and reopening an actual completed frozen run without repeating effects or model steps. A separate code-only case exercises the actual FrozenEngine, including its input seeding and persisted structured output. It also checks that unsupported nodes and unsupported durable structures are rejected. It is an integration probe for the existing host, not a universal adapter for other frameworks.
That host seeds workflows with {question, context}. A strict input contract must include the host's context field; a question-only strict object is not interchangeable. The proof uses the actual host input shape. Its code-only engine case does not establish live model, tool-server or production-delivery behavior.
The tested existing host supports a smaller vocabulary than this standalone runtime: it does not acquire Jev judge/pick/sift/route support or arbitrary nested composition from the builder. Those require a separate host integration candidate. The probe therefore deliberately uses the shared vocabulary. The deep-research tutorial exercises the standalone runtime, not that older host.
Input admission
Declared root input schemas must be enforced before workflow dispatch. The accompanying host change adds that check while preserving older workflows without an input declaration. Host-level fallback policy remains separate: rejecting a frozen workflow attempt does not decide whether the host may subsequently attempt agentic recovery.
Nested execution and recovery
executionPath identifies a runtime location, including nested child, map-item and loop-iteration positions. Adapters and events receive it alongside the existing display labels. Recovery hooks receive it as an additional final argument.
A host using recovery for newly composed structures must explicitly set recovery.supportsExecutionPaths: true and key its store by the full path. This flag is a host declaration, not a durability implementation supplied by the DSL. Hosts must still reject structures their cursor and receipt handling cannot recover. Observer events are not durable commits.
Preserve runtime versions and existing receipts when resuming persisted runs. Validate upgrades on new candidate identities; never assume an unchanged JSON digest proves identical interpreter behavior. A completed process or a passing schema alone does not prove external delivery.
Existing flat workflows retain their legacy effect keys, including their historical same-label/same-input equivalence. Newly composed graphs use versioned path-scoped keys so child, branch, item and iteration occurrences do not collide. A slice inherits the identity mode and original positions of its complete document. This compatibility rule is not a migration of old stores or an exactly-once delivery guarantee.
Rollback
The builder and inspection API are opt-in. Existing JSON authoring can remain in use. Keep the current host interpreter and its supported graph subset until replacement integration and retention tests pass. Roll back activation for new candidates; retain old stores and receipts for reconciliation.