# Hosted Workflows and instruction delivery

This reference describes setup capability. Use it after selecting the user's
MCP or CLI execution adapter. Preserve a
healthy existing grant and never extract another application's OAuth tokens.

## Resolve one released guide bundle

Read these stable pointers once per setup or repair:

```text
https://api.paywithlocus.com/api/agent/compatibility.json
https://api.paywithlocus.com/api/agent/guides/manifest.json
```

The compatibility record separates API, published plugin availability, guide
bundle, tool taxonomy, Workflow SDK, and fixed runtime versions. The guide
manifest contains the environment, exact bundle digest, immutable content URLs,
skill name, safe install path, and entrypoint marker. A guide version is not
evidence that a same-version plugin release exists. Do not construct a plugin
tag or staging hostname; use only the returned available URLs and digests.

Prefer registered native skills from the official Locus plugin when the
compatibility record marks its artifact available. If the host cannot register
skills but the agent has persistent filesystem access, hydrate the manifest or
use an available archive to install the complete, digest-verified `locus`,
`locus-setup`, and `locus-workflows` trees in a stable user-scoped agent-data
directory. Reject unsafe or duplicate install paths and require one `SKILL.md`
entrypoint per skill. Record exact paths in the host's persistent instruction
index when one exists. Reopen the relevant local `SKILL.md` before work; keep
every linked reference and asset beside it.
Only when neither native registration nor persistent files are available should
the MCP connection call `get_locus_guide()` for the index. Fetch a guide by
stable ID or task, then fetch each returned resource by ID. JSON and TypeScript
template assets are returned as text with their media type and digest. Reload
the same version after context loss; retrieval does not establish persistence.

## Hosted Workflow availability

An execution-scoped connection sees these tools only while the hosted runtime
is enabled for the deployed environment:

- `workflow_definition`: list/search, create/update/get, clone, archive, or
  save an exact checked revision as an immutable version; updates support
  exact targeted edits and stable idempotency keys for ambiguous retries;
- `workflow_validate`: pre-persistence inline structural check, exact-revision
  structural check, or isolated no-network fixtures;
- `workflow_run`: submit a saved version in bounded `pilot` or `run` mode;
- `workflow_runs`: list, inspect, page an already-stored provider response or
  artifact without another provider charge, cancel, or explicitly resume
  durable runs.

The same authenticated personal connection authorizes submission. The backend
derives short-lived run authority from that parent grant; the sandbox receives
no reusable account, OAuth refresh, enterprise, or provider credential. Every
paid call passes through the Locus gateway, which rechecks the current parent,
binding, effect, environment, and aggregate exact-decimal budget.

`search_apis` returns `workflow_binding_eligible` and `describe_api` returns
the detailed `workflow_binding` record. Use those live fields to select exact
allowed slugs and pin every advertised contract digest before validation.
This applies to BYOK Enterprise Custom APIs too: a tenant-visible `custom-*`
endpoint is available to hosted code only when its exact slug is also on the
platform Workflow allowlist. The encrypted provider key remains server-side.

Use the released `workflows`, `workflow-authoring`, `workflow-testing`,
`hosted-execution`, and `runs-and-resume` guides for the complete source,
validation, pilot, receipt, cancellation, and recovery procedure. Initial
hosted execution supports only approved Locus read/compute bindings and pure
computation. It does not inherit CRM, email, browser, or other outer-agent
connectors and does not authorize scheduling, publishing, outreach, booking, or
external writes.

## Verify result artifacts

Read result and log artifacts through `workflow_runs` with `action: "artifact"`
and follow every returned cursor. Concatenate each `page.content` value in
offset order without adding separators or formatting. `size_bytes` is the UTF-8
byte length of that canonical JSON text, and `sha256` is the lowercase SHA-256
digest of those exact concatenated bytes—not of the outer MCP response or a
pretty-printed parse. A mismatch is a server or transport integrity failure;
report it instead of guessing a different digest scheme.

Hosted `ctx.call` and `row.call` resolve to the provider response body itself,
not the MCP, billing, receipt, or `{data: ...}` envelope. Successful JSON
responses are decoded according to their content type, while malformed JSON
and non-JSON bodies remain strings. When a call's shape is unexpected, use the
call ID from run inspection with
`workflow_runs({action:"call",run_id,call_id})`; do not launch another pilot
just to inspect the same paid response.

## Readiness record

Report connection, instruction delivery, fresh-session activation, local
authoring, and hosted execution independently. “Plugin installed” is not
execution evidence. “Fixture passed” is not a live-provider pilot.
Missing authoritative evidence is unverified. A pilot and production run each
require a hard credit cap. The server requires successful fixtures before live
execution and a successful pilot of the exact saved version before a production
run. Pilot readiness records successful execution only;
`pilot_output_quality` remains `not_evaluated` until the caller verifies the
expected business fields and invariants.