Explicit transport and fallback
Local guard/wrap calls do not switch to HTTP when given an endpoint or key. Import guardRemote in Node, or guard_remote / guard_remote_async in Python, for explicit HTTP execution. Supply the full /v1/guard endpoint of your own host and an original(envelope) fallback callable. Managed execution is not available. Fallback must preserve the same logical call and upstream-enforced idempotency key.
Options and return values
The helper sends application/json and refuses redirect following. Writes and unknown operations require idempotency_key before execution.
| Language | Input | Return / failure |
|---|---|---|
| Node | guardRemote(original, RemoteEnvelope, {endpoint, timeoutMs?: 5000, apiKey?, auth?, onEvent?, onAuthDiagnostic?}) | Promise<Response | T>, where T is the fallback result. Read the Response body once with the appropriate parser. |
| Python sync | guard_remote(original, RemoteEnvelope(...), RemoteOptions(endpoint=..., timeout_seconds=5, api_key=None, auth=None, on_event=None, on_auth_diagnostic=None)) | RemoteResponse | T. RemoteResponse exposes status, headers, read(amount=None) and close(). Close it after reading. |
| Python async | await guard_remote_async(original, envelope, options) | Same value type; executes the blocking transport in a worker thread. Cancelling the await does not prove the vendor operation stopped. |
Envelope differences
Both languages require tool, connection, operation, args and mode, plus idempotency_key for writes/unknown. Node additionally permits metadata. The Python RemoteEnvelope dataclass has no metadata or durability keyword. Python uses api_key and timeout_seconds; Node uses apiKey and timeoutMs. Pass apiKey/api_key or an auth session, not both.
Fallback versus completed response
Transport failure, timeout, unavailable authentication or an unclassified guard 5xx invokes the supplied fallback and emits bypass. A completed vendor 5xx marked ok, degraded, repaired or bypassed is preserved instead of replayed. A 4xx response that rejects the request before execution is returned, not automatically retried. Valid policy 409 feedback raises AgindowDriftError; a completed response halt retrieves a same-origin retained outcome within the remaining timeout and is never replayed when recovery fails. Malformed policy feedback is unavailable transport evidence and can invoke fallback, so the vendor must enforce write deduplication.
Sender-bound authentication
Node createProofSigner() returns an ephemeral signer with thumbprint and proof(token, method, target, now). await createRemoteAuth({acquire, signer?, schedule?}) obtains an auth session: headers(method, target), refresh() and close(). acquire(thumbprint) returns {accessToken, expiresAt}; expiresAt uses Unix seconds. Python RemoteAuth and workload_identity provide the corresponding explicit identity path. Acquisition and refresh run outside guarded calls. Unavailable proof material must not trigger an in-call identity network request. Legacy credential fallback is an explicit choice with a legacy_unbound diagnostic, not automatic credential discovery.
Errors and outcomes
AgindowSetupError identifies deterministic setup misuse before execution. AgindowDriftError identifies a policy halt and exposes phase, verdict, retained outcome and feedback; preserve the original cause. Engine warming, loading failure and inspection faults emit bypass and preserve the original result or exception. A response-phase halt cannot undo a completed upstream write. A no-finding default call does not prove detection is active.