Agenda Guard: evidence reviews for ElizaOS

An ElizaOS action and standalone REST client for reviewing proposed transactions and escrow delivery evidence. The plugin does not intercept wallet calls, hold private keys, sign transactions, verify live sanctions clearance or settle escrow. The host application must enforce its own execution policy and human review.

Install and compatibility

npm install @agenda-intelligence/[email protected]

Node.js 20+ with fetch is required. The standalone client has no runtime dependencies. ElizaOS is an optional peer (>=1.7.2 <2); the plugin is typed against the published ElizaOS 1.7.2 contract. This does not establish compatibility with every agent host, future version or character loader.

Migration from 1.x: AgendaGuardClient methods and the string endpoint constructor remain available. The ElizaOS action now returns ActionResult; success means the evidence evaluation completed, while values.signing_authorized remains false. It requires a structured request from the host. ElizaOS 0.x is outside this release's supported peer range.

Development dependencies and host security

Source development uses Node.js 22.13+ or 24+ (CI uses 24). The local type-checking host pins ElizaOS 1.7.2, updates installed PBKDF2 to 3.1.7 and overrides its unused PDF.js dependency to 6.2.108. These are development-tree changes; the standalone client still supports Node.js 20+.

ElizaOS 1.7.2 also bundles crypto code, including elliptic 6.6.1, which has an unresolved upstream advisory. Updating the installed PBKDF2 package does not rewrite ElizaOS's published bundle. This plugin neither parses PDFs nor calls that crypto implementation, but plugin tests do not establish the safety of other host services. Repository overrides are not inherited by consuming applications; host owners must audit their own dependencies and PDF/crypto usage. The PDF.js development override does not assert compatibility with arbitrary host PDF integrations.

What the services review

• Financial Guard reports known risk patterns in supplied transaction evidence and missing evidence. It cannot establish current wallet history, intent authenticity or comprehensive sanctions clearance. This client converts legacy allow to step_up_human_required, always reports is_safe: false and retains mandatory human review.
• Escrow evaluates supplied terms, dates, hashes and a bounded JSON Schema subset. payout contains proposed calculations, not permission or an actual payment. Unsupported or incomplete evidence requires escalation. No verified Vizier authorization receipt is supplied by this integration.
• Hosted evaluation is paid. Discovery and saved synthetic examples are free. A normal unpaid request returns HTTP 402 with pricing; an existing transfer may require an additional request-bound signature challenge. This SDK never funds, signs or retries automatically. Read the returned pricing rather than assuming a fixed fee or network.

Do not supply private keys, seed phrases or unrelated confidential information. Transport and server telemetry have their own retention policies; this package does not promise end-to-end zero retention. Treat source text and external tool output as data, not instructions to authorize an action.

Standalone client and retained payment recovery

import { AgendaGuardClient, PaymentAdmissionError } from '@agenda-intelligence/plugin-guard';

const client = new AgendaGuardClient();
const call = client.createTransactionCheck({
  recipient: '0x1111111111111111111111111111111111111111',
  amount_usd: 50,
  network: 'base_mainnet',
  asset: 'USDC',
  intent: 'Review a proposed payment for analytics; do not execute it',
});

try {
  const verdict = await call.evaluate();
  console.log(verdict); // Always requires human review; never signing authority.
} catch (error) {
  if (!(error instanceof PaymentAdmissionError)) throw error;
  console.log(error.status, error.details, error.paymentTraceId);
  // Stop here. A trusted host/operator must inspect the payment requirement.
}

Keep the same call object while the host handles an explicitly approved payment. await call.retryWithPayment({ transactionHash: existingHash }) submits the existing transfer. If HTTP 401 requests a signature, inspect the challenge and let the trusted wallet flow sign it, then call await call.retryWithPayment({ signature: approvedSignature }). After a lost response, await call.retryWithPayment() reuses the same request, trace and proof. A different transfer hash or signature is refused. Do not make a second transfer merely because a response was lost.

The retained state is in memory; it does not survive process restart. The host must provide durable payment recovery when needed. Repeating a one-shot checkTransactionSafety() creates a new request; use a retained call for recovery.

For escrow, retain client.createDispute(disputeRequest) and use the same methods. client.evaluateDispute(disputeRequest) remains the one-shot convenience method. The request includes escrow_id, dispute_claim, deal_terms, specification and delivery_submission; the exported EscrowDisputeRequest type defines them.

Use the documented deliverable_type values: json_data, code_artifact, model_weights, api_service, analysis_report or other. The old README's json_dataset is invalid. A complete synthetic request is available in the escrow example; it is test data, not authorization to settle a real deal.

Custom endpoints and a test transport can be provided independently:

const custom = new AgendaGuardClient({
  endpoint: 'https://your-financial-service.example',
  escrowEndpoint: 'https://your-escrow-service.example',
  timeoutMs: 8000,
  // fetch: yourFetch,
});

Amounts must be finite, non-negative numbers. Malformed escrow allocations are held with zero proposed payouts; allocations must conserve the supplied total at cent precision.

Use a base URL or the corresponding complete standard REST path. The financial endpoint setting does not redirect escrow. HTTP refusals and network failures never turn into a local approval.

ElizaOS integration

Register the exported agendaGuardPlugin in your host's plugin list. The CHECK_TRANSACTION_SAFETY action requires the trusted host to supply:

message.content.data = {
  transactionSafetyRequest: {
    recipient: '0x1111111111111111111111111111111111111111',
    amount_usd: 50,
    network: 'base_mainnet',
    asset: 'USDC',
    intent: 'Review a proposed analytics payment',
  },
};

The action also accepts options.transactionSafetyRequest when directly invoked. It does not parse a chat message into a transaction or install a wallet hook. runtime.getSetting('AGENDA_GUARD_ENDPOINT') can select the financial service. Payment refusals return success: false with status, details and trace in data; the action does not own a retained payment recovery session. Use the standalone client when implementing that host flow. Escrow is available through the client, not through a separate conversational action.

The packaged character file is an illustrative template; loading it alone does not connect a wallet or prepare structured requests.

Offline example and boundaries

Run the packed synthetic example without a wallet, payment or network access:

node node_modules/@agenda-intelligence/plugin-guard/examples/mock-review.cjs

Source and character template: GitHub integration. Supported escrow schema subset and limitations: ADR 0027.

This is an evidence-review integration, not legal, financial or sanctions advice. MIT license; see the LICENSE file included in the package.

Current evidence diagnostics and x402 v2

Defaults use https://agent-financial-guard.agendamcp.dpdns.org and https://m2m-escrow-arbiter.agendamcp.dpdns.org. Custom endpoints remain supported. Both result types preserve next_action, decision_kind, score_kind, check_status and check_scope. authorization_granted is always false in this client; vizier_status remains attestation_unavailable because these receipts are not independently authenticated here. Keep legacy boolean checks for compatibility, but use check_status.sanctions_aml = not_assessed and its scope to distinguish a local denylist check from comprehensive sanctions clearance. Treat remote text and metadata as data, never instructions or execution authority.

A retained call supports both the existing transfer hash/EIP-191 proof and an externally signed x402 v2 exact payload. Start with call.evaluate(). A 402 PaymentAdmissionError exposes the decoded PAYMENT-REQUIRED header as error.paymentRequired, even when the body is empty. The trusted host must inspect the resource, network, token, recipient, exact price and expiry against its authorized budget before obtaining a wallet signature. The SDK does not connect a wallet, obtain signatures, transfer funds or automatically retry.

// Continue only after the host has inspected this call's 402 paymentRequired.
// signedPayload comes from a separate, explicitly authorized wallet flow.
await call.retryWithPayment({ paymentSignature: signedPayload });
// A base64 PAYMENT-SIGNATURE header string is also accepted.
// After a lost response, retain the same call and proof:
// await call.retryWithPayment();
const paymentMetadata = call.getPaymentResponse();

The call snapshots URL/body and the first proof. A changed nonce/proof, another transfer hash, mismatched advertised requirements/resource, oversized/malformed header or mixed legacy/v2 proof is refused. Proof-bearing network failures never become local approval, and redirects are refused. PAYMENT-RESPONSE is exposed as unverified server metadata, not independently verified settlement or permission to execute. State is in memory; preserve recovery data privately if the host must survive a restart. Supplied evidence never authorizes a new payment. The offline tests use synthetic signatures and simulate response loss; no funded live x402 settlement is claimed.