OpenAdapt Execute: private-pilot guide

OpenAdapt Execute gives a software or service provider a safe way to complete an authorized transaction in an application that the provider cannot directly integrate with.

Your product decides the business action. OpenAdapt executes the qualified transaction in the customer-controlled browser, desktop, RDP, Citrix, or API environment. It then returns a Seal: ExecuteEvidenceReceiptV1. Unsigned success is failure.

authorized transaction
  -> qualified local execution
  -> effect verification
  -> Seal (verified | halt | reconciliation_required)

The one CLI story:

openadapt-flow replay bundle --seal

A sealed verified run prints VERIFIED, a seal id, and https://openadapt.ai/seals/{id}. That route is synthetic and non-PHI only. --seal on replay is the intended Seal command. openadapt flow seal encrypts a bundle for deployment.

Private pilot. Not a public API.

This page describes the private-pilot product contract. It is not an self-service integration recipe and it does not publish partner access, credentials, an SDK, or a webhook URL. openadapt-types 0.9.0 publishes the shared async Execute schema, OpenAPI document, and signed decision contract. OpenAdapt Cloud provides private execution, customer-runner coordination, and receipt delivery for approved pilot partners.

What a partner gets

OpenAdapt starts with one named transaction in one customer environment. For example: create a follow-up appointment, submit a claim correction, update a loan application, or post a reconciled record.

The qualification work produces:

• a reviewed workflow and parameter contract;
• a named application, version, environment, and runner boundary;
• identity checks for each consequential action;
• a declared effect and the required evidence strength;
• an idempotency rule and an uncertain-delivery rule;
• representative and fault cases;
• a sealed qualified version and an acceptance report.

The partner can then submit an authorized transaction to the private pilot service. The service selects only the exact qualified workflow and the exact customer-controlled runner that can meet the contract.

The Execute contract

The production surface is asynchronous. A transaction can wait for a person, wait for reconciliation, or resume after a runner restart. A caller receives an execution identifier and observes state changes. It does not wait for a GUI session in one HTTP request.

ExecuteRequestV1

Each ExecuteRequestV1 contains exactly these public fields:

• schema_version: openadapt.execute-request/v1;
• qualification_id;
• workflow_version and workflow_digest;
• environment_id;
• typed parameters;
• idempotency_key;
• authorization_context with actor_id and authorization_reference;
• effect_strength_schema_version; and
• minimum_effect_strength.

The same idempotency key with the same request returns the existing execution. A changed request under that key is refused. OpenAdapt also keeps an effect-aware record of delivery, so it does not repeat a write after an uncertain result.

Internal qualification and runtime binding

The qualification and runtime hold additional controls outside ExecuteRequestV1. They bind the approved workflow to its sealed bundle, policy, runner capability set, and customer environment. The runner also checks the locally issued authority and its exact delivery and input binding before it acts. These controls protect the execution path; they are not caller fields in the public Execute request.

Lifecycle states

The private-pilot contract uses these states. A state describes current work; it is not a success claim.

State	Meaning
queued	OpenAdapt accepted the request for dispatch.
running	The runner is observing, resolving, acting, or verifying.
decision_required	A bounded attended question needs an authorized person.
waiting_for_reconciliation	A possible or conflicting effect needs a live read before OpenAdapt can continue.
terminal	The execution has one final transaction outcome and a receipt.

Terminal transaction outcomes

The released OpenAdapt Execute v1 contract defines these outcomes. The private-pilot service exposes the same values without translating them into a generic "success" flag.

Outcome	Meaning for the partner
verified	The configured authorization, identity, postcondition, and effect contracts passed.
halted_before_effect	OpenAdapt stopped and evidence established that no consequential effect occurred.
reconciliation_required	Delivery, persistence, or the observed effect is uncertain or conflicting. Do not submit the write again. Reconcile first.
failed_platform	A platform failure occurred before any possible business effect.
rejected_policy	Qualification, authorization, identity, environment, or policy refused the transaction before effect.
rolled_back_verified	A configured compensating action completed and the receipt includes verification evidence for that compensating effect.

verified is the business-success outcome. rolled_back_verified proves the configured compensating effect, not the original requested effect.

Customer-controlled execution

The runner stays in the agreed customer boundary. This can be a workstation, a customer-managed VM, a VDI client, or a dedicated browser runner.

The runner validates the exact authorization locally before it acts. The control plane cannot substitute the bundle, widen the policy, or reuse an authorization for a different input. Sensitive screen content and live entity identifiers stay in that boundary unless the customer explicitly configures a different evidence path.

OpenAdapt uses a qualification-owned entity class only as static presentation metadata. A task may say patient record, insurance claim, or loan application when its certified contract declares that class. A remote surface does not infer a class or an identity from a screenshot, OCR, an application name, parameters, or a model. If the class is unavailable, it uses record or item. The runner rechecks the real identity before any resumed action.

Attended and unattended operation

The private pilot runs attended. A person is signed in to the target application, and the runner acts inside that session. A consequential write pauses at decision_required until an authorized person answers, and the runner rechecks live identity and workflow state before it continues. The attended decisions section below describes that round trip.

That person stays the legal actor. A Seal records that the configured authorization, identity, postcondition, and effect contracts passed for one run. A Seal is not a physician signature.

Unattended operation is qualified separately and is not part of the private pilot. It requires a dedicated agent identity, privileged access management, and session recording. In either mode, OpenAdapt does not type a person's password, reuse a person's login, or share a service account.

Oracle tiers

Only a tier 2 or tier 3 oracle mints a production Seal.

Tier	What it reads	Production Seal
0	Visual / OCR	Never. Dev only.
1	Second session or independent UI read	Never.
2	System-of-record read (API, database, file, ack)	Yes.
3	Counterparty artifact (payer status, legal export)	Yes.

The field map, requires_seal, and Copilot coexistence live on The Seal.

Attended decisions and mobile delivery

When the runner cannot prove a required condition, it creates one signed, bounded operational decision task. The operator can answer from the local console or the authenticated phone/web decision surface. The hosted lane receives a closed-schema context without screenshots or protected fields. The runner-local portal can show detailed retained evidence inside the customer boundary.

An operator answer is not a command to repeat a write. The runner first reacquires focus, a fresh observation, the workflow state, identity evidence, and the target. It continues only if those checks pass. The resulting Seal binds the decision, the runner transition, and the final state to the exact task and authorization.

These three images show the runner-local, full-evidence portal with synthetic OpenEMR data. The hosted lane uses the same signed actions and transition states, but it does not receive these screenshots.

Request: the phone shows one bounded question and only the actions allowed for that exact pause.

Answer accepted: the signed answer is bound to the run. It is not a successful result. The customer runner must retrieve it and check the live application.

Runner result: the answer does not become success until the customer runner checks the live state and records the receipt.

Try all six synthetic decision types or review the full attended-decision contract.

The released public contract for this round trip is openadapt-types 0.9.0. It defines the async Execute schema and OpenAPI document, plus signed, PHI-safe decision tasks and receipts. Flow and Cloud use this contract for the decision relay and private-pilot execution. The partner event stream does not contain raw screenshots or live record data.

Receipts and partner integration

ExecuteEvidenceReceiptV1 is the Seal

Every terminal execution returns an ExecuteEvidenceReceiptV1. That object is the Seal. Map the receipt fields 1:1.

Receipt field	Seal field
receipt_id	Seal id. Verify at https://openadapt.ai/seals/{receipt_id} (synthetic only).
execution_id	The POST /v1/executions that produced this Seal
workflow_digest, workflow_version	Admitted program
qualification_id, environment_id, runner_id, nonce	Admission, environment, runner, uniqueness
oracle_tier	0 visual, 1 second-session, 2 system of record, 3 counterparty
outcome	verified / halt / reconciliation_required / the other terminal values
contracts	Authorization, identity, postcondition, effect
evidence_digest	Pointer to retained evidence. Bytes stay in the boundary.
issued_at	When the Seal was issued

verified requires oracle_tier 2 or 3. HTTP 202 is not a Seal. The status resource supplies evidence_receipt_id only when its state is terminal.

Consequential MCP tools advertise requires_seal: true. If the tool returns unsigned success, treat it as failure.

Local and private evidence

The customer-controlled runner retains richer evidence outside ExecuteEvidenceReceiptV1. This can include the exact bundle and input bindings, runner and environment details, report bodies, screenshots, live identity checks, and application observations. The public receipt identifies that evidence by digest. It does not copy it into the partner event stream.

The partner stores the Seal with its own transaction record. That is what you show an end customer. A screenshot or a UI banner is not proof.

Private-pilot integrations use signed, versioned webhook events and polling. Webhook retry, signature verification, ordering, and event deduplication are part of the Execute contract. The Execute integration guide shows the request, status, Seal, and webhook flow. The field map lives on The Seal.

Start with one workflow

The first step is a Workflow Qualification Sprint, not broad platform integration. Bring one repeated transaction, the actual target application and environment, a verifier path, and the operator who handles exceptions.

The sprint gives both teams a qualified transaction, a measured acceptance campaign, and a clear reuse decision. If the same transaction can transfer to additional customer environments, OpenAdapt and the partner turn it into a commercial compatibility pack.

Product boundary

Layer	Availability	Role
OpenAdapt Flow	MIT-licensed	Local compiler, governed runtime, halt/teach, qualification tools. Compile-once is a cache.
openadapt-types	MIT-licensed	Shared Execute schema. The evidence receipt is the Seal.
OpenAdapt Cloud foundation	Private and deployed	Tenant control plane, customer-runner coordination, signed decision relay.
OpenAdapt Execute	Private pilot	POST /v1/executions issues Seals. Not a new repository.
Compatibility packs and verifier recipes	Commercial	Per-application and per-environment qualification assets. Bundles are not liquid.

Next step

Qualify one workflow

Bring one system, one transaction, and one measurable business result. We will define the execution and evidence contract together.