Verifiable decision evidence for Mastra agents.

Install the published native Mastra adapter.

npm install loopgrid-mastra @mastra/core zod

loopgrid-mastra@0.1.0 is published independently on npm. The adapter declares no mandatory third-party runtime dependencies; the host supplies Mastra createTool(), createStep() and Zod. The compatibility baseline tested @mastra/core@1.75.0 and zod@4.6.6 on supported Node.js 22.18+ / 24 runtimes.

Authorize one exact action, then let Mastra run the tool.

import { createTool } from '@mastra/core/tools';
import { z } from 'zod';
import { LoopGridClient, startMastraDecision, createMastraGuardedTool } from 'loopgrid-mastra';

// Use a disposable Core workspace with an existing 'refund-policy'.
const client = new LoopGridClient({
  baseUrl: 'http://127.0.0.1:8000', // development loopback only
  workspaceId: 'YOUR_DISPOSABLE_WORKSPACE_ID',
  apiKey: process.env.LOOPGRID_SERVICE_KEY, // only when Core requires it
});

// Host-owned authority and exact tool arguments, not model-granted permissions.
const scope = await startMastraDecision(client, {
  decisionType: 'synthetic_refund',
  agent: { id: 'support-agent' },
  authority: { scope: ['refund:create'], limit_usd: 100 },
  model: { provider: 'test', name: 'example-model' },
  context: { prompt_version: 'support-v1' },
  proposedAction: {
    tool: 'sandbox_refund',
    arguments: { amount: 15, currency: 'USD', order: 'DEMO-001' },
  },
  policyFields: { amount: 15, currency: 'USD' },
  idempotencyKey: 'synthetic-refund-example-1',
});

const sandboxRefund = createMastraGuardedTool(scope, {
  createTool,
  id: 'sandbox_refund',
  description: 'Simulate a refund in memory',
  inputSchema: z.object({
    amount: z.number(), currency: z.string(), order: z.string(),
  }),
  outputSchema: z.object({ receipt: z.string() }),
  policyId: 'refund-policy',
  execute: async (inputData, context) => ({
    receipt: 'in-memory-simulation-only',
  }),
});

// Register sandboxRefund with your Mastra Agent or Workflow.
// Arguments must match the signed proposal. Nothing calls a payment API.

This is an integration pattern, not a ready-made payment application. Run it only against a disposable workspace with an explicitly configured Core policy. Mastra supplies tool input to execute(inputData, context); LoopGrid rejects changed arguments or a denied, pending, missing or unverifiable policy decision before the callback executes. A real Agent or Workflow must register the returned tool.

Framework-native tools, workflow steps and decision-correlated events.

Optional createMastraScopedObservationHooks() provide non-authorizing telemetry linked to the same decision and require a stable tool-call ID. Do not stack observation hooks on the same guarded tool. The read-only createMastraLoopGridTools() and host-owned createMastraLoopGridSteps() extend native agents and workflows without giving models approval authority.

Human approval must come from the trusted host.

When Core requires human review, the guarded tool refuses dispatch. The host must authenticate a real reviewer before recording an approval or rejection. A caller's authenticatedByHost: true declaration is not itself an authentication system.

Keep the record lean without overstating verification.

Decision evidence defaults to redacted content with SHA-256 commitments. Policy evaluation still sends the actual proposed action arguments and host authority to the configured LoopGrid Core—do not place secrets in tool arguments. Hashing low-entropy values does not make them anonymous.

const verification = await client.verifyDecision(scope.decisionId);
if (verification.valid !== true) throw new Error('Evidence verification failed');

// Core-side integrity check ≠ separate offline signer-key verification.
const evidenceZip = await client.downloadEvidence(scope.decisionId);

LoopGrid verifies captured evidence integrity and provenance, not whether the AI decision was correct, every event was captured or an external transaction actually succeeded. Independent ZIP verification requires a separately trusted public key and assessment of the export format.

Tested with native Mastra and real LoopGrid Core.

These are synthetic integration and local Core tests, not production financial-workflow certification. See the repository's validation record ↗ and integration contract ↗ for exact evidence boundaries.

Mastra executes. Your application authorizes. LoopGrid preserves the evidence.

Neither a model response nor a tool callback can authorize a payment, manufacture a reviewer identity or establish an independent downstream result. For consequential applications, enforce real host authentication, reconcile ambiguous tool outcomes, apply downstream idempotency and secure access to the Core service.

Source: GitHub ↗ · Security notes ↗ · npm ↗.