ExAgent.Continuation (ExAgent v2.2.2)

View Source

Administrative queries and host-authorized decisions for atomic records.

Runtime pause/resume integration is separate. The host authorizes commands and owns templates, policies, credentials and effect dispatch. A Store receipt says a data transition committed, not that an external effect ran exactly once.

Summary

Functions

Explicitly allow later deletion/replacement of an exact terminal run's retained historical uncertainty. Requires administrative bindings/authorization, the :evidence_hash from get/2 and allow_evidence_deletion: true. This is not an assertion that the old external effect was reconciled and does not delete data. Without it, start/prune cannot silently discard evidence retired by a retry.

Persist an :approve, :deny, :cancel or :expire decision without executing IO on behalf of the agent. Deny terminates the pending execution, retaining effects.

Read one agent continuation from the trusted scoped Store, independently of its former runtime process. Returns data only, including the current record/revision. This query never authorizes execution or resolves executable configuration.

Delete eligible terminal records from one bounded page in the trusted namespace. Returns deleted and retained/conflicted identities plus the next scan cursor. Active/uncertain records are never deleted. Stop admissions and writers before using this for namespace removal; this is not a namespace-wide atomic operation. before is an exclusive UTC-millisecond retention cutoff. Actor is host supplied.

Reconcile one uncertain tool effect using a host-confirmed outcome. The host must obtain the real external result (or prove non-execution); this API performs no external IO and does not roll back or retry the tool. Model recovery requires its explicit model-state/frame evidence and is not inferred from a tool outcome. Options use the same lifetime/revision/operation/actor/authorize binding as decide.

Reconcile an uncertain Model request with host-confirmed effective (post-hook) response and portable model data. Evidence is %{response: response, model_data: data}; optional :accounting supplies already-qualified Usage maps for the exact ancestor IDs. Existing confirmed accounting is never repriced.

Revoke an expired claim; unresolved effect intents become uncertain, never automatic retries.

Retry only the exact data transition from a failed runtime checkpoint. Store configuration is supplied separately and never appears in the data-only token. A committed/replayed claim or effect-intent receipt does not authorize dispatch; inspect/recover the current record explicitly before requesting a new resume.

Explicitly accept the risk of duplicating one uncertain effect and authorize a new linked attempt. Pass a binding returned in get/2's :retryable_effects and the usual operation/actor/authorize options, plus accept_duplicate_risk: true and a nonsecret visible-ASCII :idempotency_key (at most512 bytes).

Functions

acknowledge_history(store, id, opts)

Explicitly allow later deletion/replacement of an exact terminal run's retained historical uncertainty. Requires administrative bindings/authorization, the :evidence_hash from get/2 and allow_evidence_deletion: true. This is not an assertion that the old external effect was reconciled and does not delete data. Without it, start/prune cannot silently discard evidence retired by a retry.

decide(store, id, decision, opts)

Persist an :approve, :deny, :cancel or :expire decision without executing IO on behalf of the agent. Deny terminates the pending execution, retaining effects.

Required options are :record_id, :revision, :operation_id, :actor and :authorize. Approve/deny also require :approval_id and :payload_hash. The trusted authorize.(actor, decision, target) must return {:ok, actor_id}; all other returns and exceptions deny. Only that bounded string actor ID is persisted, never the actor context or callback. Target contains the current data record and exact requested binding; applications enforce tenant/business authorization here, not through model text.

Reuse all binding options and operation ID to retry a lost ACK. A receipt proves the earlier transition committed, not permission for new model/tool effects. Opposite decisions and changed bindings cannot reuse an operation ID.

get(store, id)

Read one agent continuation from the trusted scoped Store, independently of its former runtime process. Returns data only, including the current record/revision. This query never authorizes execution or resolves executable configuration.

prune_page(store, before, actor_id, query \\ %{})

Delete eligible terminal records from one bounded page in the trusted namespace. Returns deleted and retained/conflicted identities plus the next scan cursor. Active/uncertain records are never deleted. Stop admissions and writers before using this for namespace removal; this is not a namespace-wide atomic operation. before is an exclusive UTC-millisecond retention cutoff. Actor is host supplied.

reconcile(store, id, effect_id, outcome, opts)

Reconcile one uncertain tool effect using a host-confirmed outcome. The host must obtain the real external result (or prove non-execution); this API performs no external IO and does not roll back or retry the tool. Model recovery requires its explicit model-state/frame evidence and is not inferred from a tool outcome. Options use the same lifetime/revision/operation/actor/authorize binding as decide.

reconcile_model(store, id, effect_id, evidence, opts)

Reconcile an uncertain Model request with host-confirmed effective (post-hook) response and portable model data. Evidence is %{response: response, model_data: data}; optional :accounting supplies already-qualified Usage maps for the exact ancestor IDs. Existing confirmed accounting is never repriced.

In addition to the administrative actor/revision/authorize options, pass the trusted target :agent and its :continuation references/model codec. For a child this is that child's host definition, not code selected from stored data. Validation uses Model's no-IO resume preflight and the current output profile. No Model request or after-model hook is executed by this operation.

recover(store, id, opts)

Revoke an expired claim; unresolved effect intents become uncertain, never automatic retries.

retry_checkpoint(store, token)

Retry only the exact data transition from a failed runtime checkpoint. Store configuration is supplied separately and never appears in the data-only token. A committed/replayed claim or effect-intent receipt does not authorize dispatch; inspect/recover the current record explicitly before requesting a new resume.

retry_effect(store, id, binding, opts)

Explicitly accept the risk of duplicating one uncertain effect and authorize a new linked attempt. Pass a binding returned in get/2's :retryable_effects and the usual operation/actor/authorize options, plus accept_duplicate_risk: true and a nonsecret visible-ASCII :idempotency_key (at most512 bytes).

This only records the decision; resume still needs a new claim and intent ACK. The original intent/outcome stays literally uncertain in historical evidence. A key's delivery to the tool context or Model callback/provider is not a claim that the external service deduplicates it, especially if the first call had no key. Context-free tools and unsupported Model transports reject retry before IO.