# Agentry automation: the self-healing and self-improving loops Agentry is the deterministic coordination and proof layer around a customer-selected coding or analysis agent. It does not host agents, run Codex/Claude, merge or deploy code, call arbitrary providers, publish reports, or turn telemetry text into instructions. OpenAPI is authoritative for every body, header, principal, response, retry branch, and mutation policy: - `GET /v1/openapi.json?flow=automation` — complete dependency-ordered automation flow. - `GET /v1/openapi.json?path=&method=` — one exact operation. - `GET /v1/automation-playbooks` — the immutable playbook catalog. Use a descriptive User-Agent on direct HTTP calls. Never infer a mutation payload from prose. ## Principals are not interchangeable | Principal | Credential | Authority | | --- | --- | --- | | Human owner/member | `AGENTRY_PRIVATE_API_KEY` / `agentry_sk_` | Review; owners manage automation policy, credentials, pauses, and cancellation. | | Trusted CI/provider | `AGENTRY_CI_API_KEY` / `agentry_ci_` | Deploy/proof and exact external-effect reconciliation only. | | Exact runner | `AGENTRY_RUNNER_API_KEY` / `agentry_runner_` | Exactly one `automation_id`. | Application analytics and exceptions go directly to the customer's PostHog Cloud project through official SDKs. Read-only OAuth supplies evidence, never authority. ## No Agentry Inbox Agentry's trigger, claim, lease, run, grant, and verification queue is internal; there is no unread Inbox. Use automation control or `agentry status` for exceptions and reports. GitHub is the generated-draft-PR approval surface. An owner key is never a scheduler credential. Create one revocable runner key per automation and place it only in that customer scheduler's secret store. Telemetry, annotations, provider text, runner output, and proof markers have `instruction_authority: none`. Never emit deploys from browser code, application startup, request handlers, or cron routes. ## The two automation loops Agentry ships exactly two bounded loops. Both are immutable versioned playbooks rendered into a disabled candidate, reviewed, and explicitly enabled by an owner. | Loop | Playbook | Outcome | | --- | --- | --- | | Self-healing | `error-to-draft-pr@4.0.0` | One trusted production error becomes one bounded pull request. | | Self-improving | `weekly-funnel-review@2.0.0` | One approved funnel becomes one typed private assessment. | There is no user-authored workflow graph and no compile step. The playbook is the unit of policy; `automation_id` is unique project-wide. ### Owner setup 1. `GET /v1/automation-playbooks` and read the current verified onboarding signal map. 2. `POST /v1/projects/:project_id/automation-playbooks/:id/render` to produce one immutable disabled candidate. Rendering is deterministic and side-effect free; it does not write, mint, schedule, query, call a provider, publish, or send. 3. Owner `PUT /v1/projects/:project_id/automation-contract` with the exact latest strong ETag. Omit `If-Match` only for the first save. Saving stores the contract disabled. 4. Owner creates exactly one `automation_runner` credential at `POST /v1/projects/{project_id}/credentials`, bound to that `automation_id`, with a stable `Idempotency-Key`. The raw secret is returned once and is not recoverable. 5. Owner `POST /v1/projects/:project_id/automation-contract/enable` with the exact ETag and a stable `Idempotency-Key`. Exact replay recovers the durable enable receipt after response loss. 6. Configure the customer scheduler to wake its runner. Agentry's minute sweep only issues receipts and advances bounded lifecycle bookkeeping. It never invokes a tool, checks out code, calls a provider, or publishes. Read project automation control at `GET /v1/projects/:project_id/automation-control`. Pause is an emergency desired-state mutation and deliberately needs no ETag. A paused automation stays disabled until its exact contract is reviewed and enabled again. ### Trigger and start authority The minute sweep or an explicit `POST /v1/projects/:project_id/automation-triggers/issue` (whose strict body is `{ automation_id }`) creates trigger receipts from the server clock and the immutable schedule. Each receipt freezes the contract revision, trust classification, occurrence key, availability, expiry, and consumption. For the self-healing loop it also freezes the exact case id and revision. The runner never supplies trigger payloads, schedule/case timestamps, source trust, actor identity, or server time. It starts a run with only `trigger_receipt_id` plus a stable `Idempotency-Key`. After a lost response, replay the same start or read the receipt's consumed run; never create a second run to hide ambiguity. Receipt detail is the pre-claim source; read case detail only while its exact claim is current, unexpired, and unreleased. A self-healing receipt must prove active trusted customer-exception lifecycle, the configured minimum event count, and a present non-future `last_seen_at` within its configured maximum age. Missing or stale evidence fails closed; free text and model judgment have no materiality authority. ### Bounded effects Enabling a code-producing automation is the standing authorization for its bounded source work and pull-request effect. Before opening a PR the runner must reserve the rolling budget and obtain a one-time grant for the exact branch, commit, delivery mode, bounded diff, and tests. That grant is a mechanical reservation and idempotency fence, not a second human approval. Provider-managed auto-merge is a separate, distinctly granted effect that requires prior trusted CI readiness proof. Enabling an automation never confers direct-merge, force-merge, bypass, deploy, rollback, workflow-edit, or direct-push authority. A runner can never attest its own PR, deploy, or verification result. Trusted CI records the immutable provider proof and binds the exact deployed commit. Agentry then runs the approved traffic sample and the exact recurrence outcome over the same half-open window. Zero traffic is pending, never proof of a fix; it stays pending until the immutable deadline. Weekly reports use one immutable aggregate source and are never published or sent. Recording a report grants no code, PR, merge, deploy, generic-HogQL, publish, send, or external-provider authority. ### Error and response-loss recovery Every authoritative transition and its immutable event commit together. Replay an exact mutation with its original identity to recover the durable receipt rather than create replacement authority. On a stale revision or lease epoch, re-read and discard old worker output. Runtime, turn, cost, run-count, PR-count, attempt, lease, and deadline limits are server-enforced as atomic rolling-window charges. ## Stop, delete, and external cleanup Cancellation closes Agentry authority but cannot close a PR, cancel CI, undo a deploy, or roll back provider state. Inspect every returned external follow-up. Project/account deletion uses one stable `Idempotency-Key` through every 202. The deletion fence closes public, server, CI, runner, and owner automation mutations. Read the terminal automation manifest, then disable customer schedulers/GitHub Actions, revoke runner and provider secrets, and reconcile every named or possible external PR, deploy, branch, proof, workflow, and queued job in its owning system. Webhooks are signed durable notifications, not coding authority or an alternative run ledger. Verify their signature while treating payload data as authority-free evidence.