Package adapters & agent harnesses

Overview

One package. One contract. One authority boundary.

A Coaray package is a compiled, signed, tenant-neutral specification for a kind of worker. It defines what the worker is responsible for, the jobs it accepts, the evidence and outcomes those jobs require, the capabilities it may request, and the policies every execution surface must obey.

A package is not an agent process, a model, a connected account, a deployment, or a folder of prompts. The adapter’s job is to translate the package into a host-native shape without creating a second source of package meaning. The harness runs the model loop. Neither receives the right to approve effects or declare completion.

The mental model

Package, adapter, harness, and coordinator are different jobs.

Keeping these nouns separate is the core safety property. The package supplies portable intent and policy. The adapter verifies and projects it. The harness owns a native agent session. The coordinator owns consequential state.

What the package owns

The package carries method and limits—not customer state.

Canonical Worker IR is the portable contract the adapter must preserve. It contains enough structure to form the worker in a harness, but deliberately excludes everything that would turn a release artifact into a credential or customer-data vessel.

Adaptation pipeline

Adaptation is a verified projection, not a prompt conversion.

The adapter does not copy instructions into a persona and hope for equivalent behavior. Each stage binds exact bytes, declared policy, and local authority before the harness can be activated.

1. 01

   Compile

   Studio source is normalized into canonical Worker IR. The compiler—not the UI or the runtime—defines the executable package meaning.

2. 02

   Address

   Worker IR, contracts, schemas, and deterministic components become an immutable OCI artifact identified by its manifest digest.

3. 03

   Sign + attest

   The publisher signs the exact artifact and an independent conformance authority attests the same manifest and Worker IR bytes.

4. 04

   Admit

   The host checks protocol compatibility, required features, evaluator authorities, pure-component policy, and every capability binding.

5. 05

   Project

   The adapter derives a host-native persona, skill, read-only tool list, and effect-capability declarations from the admitted release.

6. 06

   Resolve

   Each provider-neutral capability must resolve to one canonical enabled tool and one exact verified connection revision.

7. 07

   Bind

   The resulting execution plan is hashed, approved, and rebound to the deployment, persona, session, model, and connection set.

8. 08

   Run

   The harness may produce text and typed proposals. The coordinator alone advances work, authorizes effects, evaluates outcomes, and issues receipts.

Capability resolution

Provider-neutral requirements become exact local bindings.

Worker IR asks for a capability such as a read or send operation. It does not name a secret, customer account, or mutable provider connection. During provisioning, the OpenWorker execution adapter resolves that requirement against the signed host capability registry and live connection records.

// Canonical Worker IR — illustrative shape
{
  "capabilityKey": "records.read",
  "risk": "read_only",
  "approval": "not_required"
}

// Device-local execution plan — derived, never packaged
{
  "capabilityKey": "records.read",
  "runtimeTool": "records_search",
  "connector": "records",
  "connectionId": "conn_…",
  "connectionRevision": 7,
  "authorityDigest": "sha256:…"
}

The resolver must prove all of the following

• The capability exists in the host’s canonical registry.
• The connector identity is canonical—not an alias.
• The connector is available, connected, and enabled.
• Exactly one enabled runtime tool matches the binding.
• Exactly one online, verified connection can perform it.
• The connection revision and authority digest are exact.
• Tool, host binding, and package agree on effect risk.
• Consequential capabilities require exact host approval.
• No enabled connector tool sits outside the package ceiling.

The complete plan is canonicalized and hashed. Session binding and restart inspection recompute the plan and require the same digest, so a changed connection, model, tool inventory, or permission cannot quietly inherit an earlier approval.

The runtime harness

OpenWorker hosts the agent. Coaray keeps the authority.

The internal runtime port isolates upstream OpenWorker protocol details behind four domain operations: inspect the installation, prepare a deployment, read a transcript, and run a model turn. Production runtime kind is exactlyopenworker; this seam is not a runtime marketplace.

Authority boundary

The adapter may narrow authority. It may never manufacture it.

Three independently checked boundaries prevent the harness from becoming operational truth: release admission, persona consent, and coordinator authorization.

Integrity chain

artifactDigest
  ├─ workerIrDigest
  ├─ publisher signature
  ├─ independent conformance report
  └─ registry admission
       ↓
provisioning envelope
       ↓
materializationDigest + personaDigest + skillDigest
       ↓
capabilityPlanDigest + connection revisions
       ↓
runtime deployment binding

Failure behavior

When proof breaks, execution stops honestly.

The adapter is intentionally intolerant of ambiguity. A missing proof does not produce a degraded worker; it produces a specific blocking state the operator can resolve.

Implementation status

What is real now—and what still blocks the full promise.

This page describes the governing package-adapter boundary. The implementation already enforces substantial parts of that boundary, but the complete sellable lifecycle is not finished.

Reference

Where the boundary lives in the codebase.