> ## Documentation Index
> Fetch the complete documentation index at: https://glide-9da73dea.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AgentActivityEvent (v1)

> Append-only audit event emitted after every MCP tool call. Consumed by the Trust Console, audit:stream subscribers, and ops dashboards.

`AgentActivityEvent` describes the audit-event projection consumed by the Trust Console and authorized agent clients. Server-side handlers write activity records. The F4 Postgres trigger guards updates and deletion, with a separate authorized DSAR redaction path; it does not create every event on behalf of application code.

## Canonical URL

[`https://glide.co/schemas/agent-banking/v1/agent-activity-event.json`](https://glide.co/schemas/agent-banking/v1/agent-activity-event.json)

## Required fields

| Field | Type | Notes |
| - | - | - |
| `eventType` | `string` (1–64 chars) | Free-text event-kind label retained for backward compat with the original `/draft/` placeholder shape. New producers SHOULD also set `eventKind`. If both are present they MUST match. |
| `timestamp` | `isoDateTimeUtc` | When the event occurred (UTC, `Z` suffix required). Server-stamped at the producer — the trigger never trusts a clock value supplied by an agent runtime. |
| `agentId` | `string` (1–128 chars) | `agent_principal_id` of the acting agent. UUIDv4 in production; the looser `string` type keeps backward compat with placeholder draft data and operator-emitted events. |

## Optional fields

| Field | Type | Notes |
| - | - | - |
| `schemaVersion` | `'v1'` | Locks the event to the v1 schema. Absence is treated as v1 by consumers; a non-`'v1'` value MUST be refused at ingest. |
| `eventKind` | `agentActivityEventKind` | Closed enum (see below). Preferred over `eventType` for new producers. Unknown values drop the event at ingest — don't emit values outside the enum. |
| `eventId` | `uuidV4` | Unique identifier for this event row. Consumers de-duplicate on this. Older streams used the DB row `id`; new producers SHOULD always set it. |
| `principalId` | `uuidV4 \| null` | Human principal whose vault is being acted on. Null for system-emitted events (kill-switch, scheduled jobs). |
| `vaultId` | `uuidV4 \| null` | Vault the action targets. Together with `principalId` forms the RFC 8707 audience binding. Null for system events not tied to a specific vault. |
| `grantId` | `uuidV4 \| null` | JTI of the grant that authorized this action. Null for events not tied to a grant (e.g. operator-initiated kill-switch). |
| `toolCallId` | `uuidV4 \| null` | ID of the MCP tool call this event describes. Null for non-tool-call events (e.g. `consent_granted`). |
| `summary` | `string` (1–280 chars) | Human-readable one-line summary for the Trust Console list row. Plain text, no markdown, no PII unless the principal already has access to it. |
| `extra` | `object` | Open-ended bag for kind-specific fields (risk verdict reason text, anomaly score, etc.). Producers MUST keep this under 4 kB. Consumers MUST treat unknown keys as opaque. Allows event-shape evolution without bumping `schemaVersion`. |

### `eventKind` vocabulary

| Value | When emitted |
| - | - |
| `tool_call` | Any MCP tool completes (allowed or denied). |
| `reasoning_step` | Agent runtime emits a reasoning trace to the Trust Console (opt-in). |
| `risk_verdict` | Policy engine produces a verdict (`allow` / `allow_with_step_up` / `deny`). |
| `anomaly_detected` | `@glideco/anomaly` heuristics fire on a tool call. |
| `consent_prompt` | Step-up auth prompt sent to the principal. |
| `consent_granted` | Principal completed the step-up. |
| `consent_denied` | Principal declined or the prompt timed out. |
| `step_up_required` | Policy engine flipped verdict to `allow_with_step_up`. |
| `step_up_completed` | Step-up sigil consumed; execution proceeds. |
| `policy_violation` | Tool call exceeded a hard cap or counterparty allowlist gate. |
| `grant_issued` | OAuth AS issued a new grant. |
| `grant_revoked` | A grant was revoked (operator or principal action). |
| `kill_switch_triggered` | Forensic kill-switch fired for an agent or vault. |

## Lifecycle

Server-side handlers write activity events for the operations they handle. The event's kind, tool-call identifier and recorded status distinguish a completed action, a denial and an approval request.

**Who consumes:**

* **Trust Console UI** — tails the table via a tRPC subscription with per-principal row-level security.
* **`audit:stream` MCP scope** — exposes a read-only window to authorized agent runtimes. Scoped to the calling grant's `vaultId`; cross-vault reads are refused.
* **Ops dashboards** — query `activity_log` directly (read-only DB role), filtering on `agent_principal_id IS NOT NULL`.

**Retention:** the `activity_log` table is append-only with no TTL at v1. Row-level security ensures each principal can only read their own events. Future versions may introduce archival tiers (see `@glideco/compliance-export`).

## Example

```ts theme={null}
import { z } from 'zod';

// AgentActivityEvent is the JSON Schema shape; in TypeScript use the
// @glideco/schemas package for runtime validation.
const AgentActivityEvent = z.object({
  schemaVersion: z.literal('v1').optional(),
  eventType: z.string().min(1).max(64),
  eventKind: z.enum([
    'tool_call', 'reasoning_step', 'risk_verdict', 'anomaly_detected',
    'consent_prompt', 'consent_granted', 'consent_denied',
    'step_up_required', 'step_up_completed', 'policy_violation',
    'grant_issued', 'grant_revoked', 'kill_switch_triggered',
  ]).optional(),
  eventId: z.string().uuid().optional(),
  timestamp: z.string().datetime(),
  agentId: z.string().min(1).max(128),
  principalId: z.string().uuid().nullable().optional(),
  vaultId: z.string().uuid().nullable().optional(),
  grantId: z.string().uuid().nullable().optional(),
  toolCallId: z.string().uuid().nullable().optional(),
  summary: z.string().min(1).max(280).optional(),
  extra: z.record(z.unknown()).default({}),
});

const event = AgentActivityEvent.parse({
  schemaVersion: 'v1',
  eventType: 'tool_call',
  eventKind: 'tool_call',
  eventId: '11111111-1111-4111-8111-111111111111',
  timestamp: '2026-05-04T12:00:00.000Z',
  agentId: '22222222-2222-4222-8222-222222222222',
  principalId: '33333333-3333-4333-8333-333333333333',
  vaultId: '44444444-4444-4444-8444-444444444444',
  grantId: '55555555-5555-4555-8555-555555555555',
  toolCallId: '66666666-6666-4666-8666-666666666666',
  summary: 'Initiated $250.00 USDC payment via payments.initiate',
  extra: { risk_verdict: 'allow', rail: 'usdc-base' },
});
```

## Validation

The event is validated three ways:

1. **At write time** by the producing application and its schema validation. The append-only trigger guards mutations; it is not a JSON Schema event validator.

2. **At build time** via `scripts/validate-manifests.mjs`:

   ```bash theme={null}
   pnpm --filter '@glideco/schemas' validate-events
   ```

3. **Against the published JSON Schema** for consumer-side validation:

   ```bash theme={null}
   npx ajv-cli validate \
     -s https://glide.co/schemas/agent-banking/v1/agent-activity-event.json \
     -d ./my-event.json
   ```

## Common pitfalls

* **Setting `eventKind` but not `eventType`.** The schema marks `eventType` as required for backward compat. Both fields must be set and must match.
* **Omitting `eventId` on new producers.** Consumers de-duplicate on `eventId`. Without it, retried deliveries create duplicate Trust Console rows.
* **Passing a non-UTC `timestamp`.** The `isoDateTimeUtc` type requires the `Z` suffix. `+00:00` offset strings fail schema validation and are rejected at ingest.
* **Emitting an `eventKind` value outside the closed enum.** Unknown values are dropped at ingest without error. The enum is CODEOWNERS-protected — new values require a schema migration.
* **Storing PII in `summary`.** The `summary` field renders in the Trust Console list row, which may be visible to support staff. Keep it to action + amount + rail — no email addresses, phone numbers, or wallet addresses.

## Reading list

* [AgentPolicyEnvelope](https://glide-9da73dea.mintlify.site/oss/standards/agent-policy-envelope.md) — the envelope that produced the `risk_verdict` captured in `extra`.
* [Receipt](https://glide-9da73dea.mintlify.site/oss/standards/receipt.md) — the companion write-side record for money-touching calls.
* [Grant](https://glide-9da73dea.mintlify.site/oss/standards/grant.md) — the `grantId` / `jti` this event references.
* [Money-safety contracts](https://glide-9da73dea.mintlify.site/oss/concepts/money-safety-contracts.md) — F4 IRON RULE that makes this table append-only.
* [Source on GitHub](https://github.com/darshanbathija/axtior-neobank/tree/main/apps/web/public/schemas/agent-banking/v1/agent-activity-event.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.