Choose distribution and protocol separately
Prefer an OCI image for a new integration. It pins the interpreter and dependencies and resolves to a linux/amd64 manifest digest. A Dockerfile recipe is not a published image, and a published image is not an executed combination. Private registry support also depends on the Sandbox provider. The source-package format remains a compatibility path for Python/Node source usinghexagon-json-v1. It does not orchestrate dependency installation. Both paths store tenant-owned registrations and pin versions; the control plane does not import uploaded source. Reusing an existing id/version with changed content conflicts. Select a new version and create a new Session when changing the pinned definition.
Check protocols.ts for model protocols, Tools and continuation semantics. For example, the current Codex adapter declares Responses, Hermes declares Chat Completions, and Aider does not declare remote Tools. An image label cannot add executable protocol support. Extending a protocol requires implementation and rejection tests, not just another catalog value.
Trace the three adapter methods
HarnessAdapter is the authoritative interface:
Use OCI runtime-adapter.ts for the existing dispatch and managed-cli.ts for managed CLI result handling. OCI supplies dependencies; the adapter installs bridge/configuration support rather than silently replacing the pinned CLI. Keep argv as separate strings and test actual upstream flags at the pinned version. Do not rely on a daemon entrypoint when the contract expects one supervised invocation.
Model access comes from the worker’s scoped configuration. Preserve its proxy URL and delegated authentication arrangement; do not replace it with a vendor endpoint or account key. Where required by the CLI, retain the proxy’s
/v1 prefix. Raw upstream model/provider keys stay in the control plane. Never log environment credentials, place them in artifacts, or enable unrelated account integrations implicitly.
Build from the minimal Python Harness
The existing Python Agent is a real model-driven loop with shell execution, Tool mailbox access, bounded steps and local conversation history. Its OCI Dockerfile pins the base image and selectshexagon-json-v1. Read both before adapting them. Shell execution is part of the guest’s power, not a new isolation boundary.
An OCI build from the repository root can be prepared with:
hexagon-json-v1, the program receives one JSON object through stdin followed by EOF. It contains run_id, input, scoped model endpoint/name, optional native_session, the Run’s artifact_directory, and declared tools; current adapters can also pass initialization. Consume the supplied configuration, preserve history under the Session workspace and write exports only to the supplied artifact directory.
The successful final record is one JSON line:
text nonempty and the optional native identifier bounded to 512 characters. For source packages the parser uses a strict schema, so do not add diagnostic fields to this record. The example’s exceptional output currently includes diagnostic fields; that is rejected by the source parser and must never be treated as successful execution. Review and test failure reporting when deriving your implementation. Ordinary logs are not an assistant result. Common worker handling additionally requires a successful process outcome and artifact export; a valid-looking JSON line alone does not complete the Run.
A portable failure record
When deriving ahexagon-json-v1 implementation, emit a bounded failure record containing only contract fields, then exit nonzero:
Use the Tool bridge and continuation contract
Bound Tools use the existing mailbox/bridge, not direct upstream credentials. A custom loop callshttp://127.0.0.1:8765/tools/<run_id>/call with the Run-scoped HEXAGON_TOOL_TOKEN, a stable call ID, declared name and arguments. Continue polling the same call ID and arguments through authorization/approval waits, then inspect the result including isError. Creating a new call ID during a wait can create a different invocation. Native MCP-capable CLIs use tool_bridge.py through the adapter’s configuration.
Return the actual native continuation identifier when supported, and pass it back on the next Run. Do not fabricate one from the Run ID if the upstream CLI expects its own Session identifier. The generic Python example owns its own history, so its identifier has a different implementation contract. Verify a follow-up that depends on previous context, including after supported filesystem resume. Initialization support also needs deliberate first-turn/follow-up behavior; declaring a capability does not implement it.
Cancellation remains Runtime’s responsibility. The adapter must not detach an independent agent daemon that escapes process supervision. Inspect Runtime and test descendants, cancellation during Tool waits, and late output. Client event disconnection does not cancel a Run. Preserve uncertainty after process loss rather than starting another invocation blindly. Native action visibility differs by CLI; expose actual events and never manufacture hidden reasoning.
Registration and verification changes
For a new OCI protocol, review protocol declarations, image schema/registration, runtime adapter, result parser, catalog/templates and evidence records together. Existing protocols can often reuse the registry without a new built-in branch. Relevant sources include images.ts, catalog.ts, templates.ts and verification.ts. Source registration is in harness-packages.ts. Tenant ownership must be checked for definitions, registry secrets and Session bindings. Start with deterministic parser/configuration tests:Separate the success checks
Do not testresult(stdout) with only one successful JSON object. Adapter parsing, process exit and platform terminal state are separate decisions. Cover these inputs independently in the new implementation’s tests:
The strict source-package result schema and the generic OCI parser are different code paths. Source packages reject additional fields; the current generic OCI
hexagon-json-v1 branch does not use the same strict schema. For portability, emit only agreed final-result fields and test both registration paths. Acceptance of diagnostic fields through one distribution path is not a universal protocol guarantee.
Inspect observable causes of final failure as well. The worker uses persisted model transport records to distinguish some failures as model_transport_failed, model_authentication_failed, model_rate_limited or model_request_failed; otherwise failure may be harness_execution_failed. Do not rewrite every nonzero exit as a user-key problem or expose raw upstream responses through public errors.
Design acceptance for the minimal Harness
Pin an explicitly supported Provider, image digest, model protocol and SDK version, then record these observations in order. These are execution requirements, not newly passed results claimed by this page.- In the first turn, obtain a verifiable model response, save a known file and export an artifact. Check exit, final reply and downloaded digest.
- Continue the same Session with a new Run ID and submission idempotency key. Ask for a prior conversation fact and the saved file without placing the answer in the second prompt.
- For a Harness declaring Tools, exercise the existing bridge and test both normal output and
isError, preserving call ID and arguments. - During authorization or approval waits, confirm the original Run remains waiting. After a decision, continue the original call and check external operation count; a second Run is not continuation evidence.
- Cancel an active turn and confirm Runtime-supervised process state, Run terminal state and already-dispatched external outcomes. Cancellation cannot retract prior effects.
- Close the Session, confirm cloud and associated-resource cleanup, then download exported artifacts again. Run the required journey independently through the other SDK and separately record cross-language continuation.