# AI Execute SDK evaluation guide

Public documentation revision 3 · October 7, 2026

RC15.3 candidate / Managed API 0.1.0-rc.3. One AI job, one approved budget across
retries, agents and provider changes. Public downloads provide MIT Python and
JavaScript/TypeScript clients and the API contract. The full gateway evaluator is
available through an agreed technical review. Downloading a client activates no
hosted service, native AI execution or paid account.

## Install the SDKs

Download both archives from <https://haltseal.com/developers/execute/> and check
their SHA-256 against this revision's `SDK_SHA256SUMS.txt`. From the folder containing those files:

```sh
python3 -m pip install --no-index --no-deps ./haltseal_execute_sdk_preview-0.1.0rc3-py3-none-any.whl
npm install --ignore-scripts ./haltseal-execute-sdk-preview-0.1.0-rc.3.tgz
```

Python 3.11+ and Node 22+ are the preview requirements. These are direct downloads,
not PyPI/npm registry releases. Their MIT notices are included in the packages
and supplied as `SDK-LICENSE.txt`. Installing a client does not provide a running
gateway, signed approval or execute key.

## Request and run the full local evaluator

Use <https://haltseal.com/contact/?topic=ai-execution#message> with non-confidential
product, provider and budget-approval context. The evaluation package contains
the gateway, two separate HTTP provider fixtures, both SDKs and reproduction
tools. Core source and operational materials remain within the agreed review and
retain their separate evaluation license.

After receiving the authorized package, verify its supplied archive hash and
follow its setup and acceptance instructions on Linux with Python 3.11+,
Node 22+, npm and pip. Keep the original private history and credentials.

The evaluator supplies authenticated approval, customer-bound access and a
configured local gateway. Both SDKs install offline. Follow the supplied
acceptance guide and retain the evaluation results. Costs are synthetic.
Owner-run qualification passed 116 tests and 16 actual SIGKILL boundaries; these
are not native bills, customer workflows or independent reproduction.

| Event | Final consumption | Unresolved maximum | Available | B needs $12 |
| --- | ---: | ---: | ---: | --- |
| $20 approved; A accepts $12; reply/job ID lost | $0 | $12 | $8 | HOLD |
| Read-only recovery verifies A's final $4 cost | $4 | $0 | $16 | Still held |
| Explicit resume reserves B's $12 | $4 | $12 | $4 | ACCEPT |

Changing a customer-bound key or registered alias keeps the same business.
Repeated evidence does not release capacity twice. Recovery does not dispatch a
successor. A distinct permitted job capped at the remaining $8 could fit while A
is unknown: this preserves a cost envelope, not one effect for every attempt.

## Integrate with an authorized gateway

Your trusted order service signs the authoritative identity, customer, approved
cumulative total, revision, expiry and status. An admin imports the approval with
`POST /v1/businesses`. Persist the returned business ID and issue customer-bound
execute keys to agents. Agents cannot import approvals or create funding.
Follow the evaluator's operational guide for the configured local fixture.

The website snippets assume that gateway, approved business and key. The fixture
action is `lab.fixed_job.v1` on connection `lab`. USD amounts are integer
micro-unit strings: `"12000000"` means $12. HTTPS is mandatory outside explicitly
enabled literal loopback evaluation. Keys belong in trusted backend code, not a
browser. No native provider is qualified by this release.

## Handle a lost gateway response

Persist the business ID, attempt key and complete economic request before calling
execute. `TransportUnknown` can mean the gateway already accepted it. Keep the
same identity/payload. When the gateway execution ID was lost:

```python
existing = client.lookup(business_id, "render-1")
observed = client.recover(existing["id"])
```

```javascript
const existing = await client.lookup(businessId, "render-1");
const observed = await client.recover(existing.id);
```

The query names are `scope_id` and `operation_key`; use the canonical business ID
and attempt key. A 404 while the original request is in flight does not prove an
unsent provider job. Wait or repeat only the identical gateway execute request.
Do not change the key to escape the timeout or repeat a provider POST directly.
Changing the economic request under the same key conflicts.

An HTTP success can return HOLD and does not mean a final cost. Read state with
`get`; recover only the original execution. A held successor needs explicit
`resume` and fresh checks. Cancellation alone does not refund exposed work.
Incomplete, ambiguous or mismatched evidence retains the reservation.

## Review the contract and readiness

`openapi.json`, `API.md` and `BUSINESS_RECOVERY.md` accompany the SDKs. Your trusted
approval system must identify real work; two source IDs can still conceal one
job. Every controlled provider call must use the gateway. Historical consumption
and unresolved work must survive future cutover.

Managed use requires a binding native cost ceiling, original-job recovery, final
billing, hosted/onboarding qualification and agreed terms. Price estimates,
completion, empty lookup or cancellation alone do not prove billing finality.
Keep raw order/job/invoice records and credentials out of the inquiry form.

This is a single-host local preview. Backup restoration, joint-history rollback,
host migration and automatic history migration remain unqualified. Production
is NO_GO. Operator recovery instructions are supplied within the agreed review.