@glideco/agent-events

OSS reference implementation of the agent activity-log taxonomy from the Glide OSS plan §M4. Every event type that the MCP layer appends to activity_log lives here as a Zod schema in a discriminated union. The closed vocabulary is intentional: audit log consumers — compliance exporters, explainer narrators, anomaly detectors — switch on eventType; adding a new event type requires a deliberate schema update and a corresponding render path. The package ships the v1 surface of the AgentActivityEvent JSON Schema published at glide.co/schemas/agent-banking/v1/.

Install

npm install @glideco/agent-events

npmjs.com/package/@glideco/agent-events

Why a closed vocab?

An open event taxonomy is a footgun for every downstream consumer. If any string is a valid eventType, the compliance exporter can’t tell the difference between a known event and a fabricated one, and the anomaly detector’s switch statement silently falls through to a no-op default. The discriminated union here enforces that every eventType literal has a known schema. Unrecognized event types fail AgentEventSchema.parse() at the boundary where the event enters the system — typically inside the MCP tool handler — not later when a reviewer tries to render it. Adding a new event type is a two-line change (literal + schema + union entry) that produces a TypeScript compile error everywhere the switch is exhaustive. That friction is the point.

Event types (v1)

Event type	Payload schema	When it fires
`tool_call`	`ToolCallEventSchema`	Tool handler completes (pass or flag)
`tool_call_blocked`	`ToolCallEventSchema`	Policy engine returns `deny` before execution
`tool_call_failed`	`ToolCallEventSchema`	Tool handler throws (infra error, not policy)
`reasoning_step`	`ReasoningStepEventSchema`	Agent emits a reasoning excerpt (≤200 chars, secrets-safe)
`risk_verdict`	`RiskVerdictEventSchema`	Risk layer returns `pass` / `flag` / `block`
`anomaly_detected`	`AnomalyDetectedEventSchema`	`@glideco/anomaly` heuristic fires
`step_up_requested`	`StepUpRequestedEventSchema`	Tool needs principal step-up before proceeding
`step_up_completed`	`StepUpCompletedEventSchema`	Principal completes biometric / passkey / hardware-key
`step_up_declined`	`StepUpRequestedEventSchema`	Principal declines or times out (same shape as requested)
`policy_change`	`PolicyChangeEventSchema`	Operator updates the vault’s policy envelope
`policy_stale`	`PolicyChangeEventSchema`	Agent detects its cached policy is behind current version
`agent_install`	inline	Skill installed on an entity
`agent_uninstall`	inline	Skill removed
`kill_switch`	`KillSwitchEventSchema`	Forensic kill-switch activated (`all-agents` or scoped)
`dsar_redaction_applied`	`DsarRedactionEventSchema`	`@glideco/dsar` partial redaction applied
`dsar_tombstone_applied`	`DsarRedactionEventSchema`	`@glideco/dsar` full-erasure tombstone applied

Key payload shapes

The ToolCallEvent is the most data-rich shape. It carries the SHA-256 digests of input and output (never the raw values), the risk verdict, policy version, grant ID, and optional on-chain tx hash + amount:

import {
  AgentEventSchema,
  ToolCallEventSchema,
  isAgentEventOfType,
  parseAgentEvent,
  type AgentEvent,
  type ToolCallEvent,
} from '@glideco/agent-events';

// Validate an inbound event from the MCP layer:
const event = parseAgentEvent(rawJson);
// Throws z.ZodError if eventType is unrecognized or payload is malformed.

// Narrow to a specific shape with a type guard:
if (isAgentEventOfType(event, 'tool_call')) {
  // event.data is typed as ToolCallEvent
  console.log(event.data.toolName);         // e.g. 'transfer.sendUsdc'
  console.log(event.data.riskVerdict);      // 'pass' | 'flag' | 'block'
  console.log(event.data.policyVersion);    // integer; 0 on first issue
  console.log(event.data.onChainTxHash);    // undefined for non-broadcast tools
}

Step-up events carry a sigil — a short opaque string that links the requested, completed, and declined triple into a single audit thread:

import { parseAgentEvent } from '@glideco/agent-events';

const requested = parseAgentEvent({
  eventType: 'step_up_requested',
  data: {
    sigil: 'su_2Zg4mKpT',
    reason: 'Transfer amount $5,200 exceeds step-up threshold $5,000',
    amountCents: 520_000,
    counterparty: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
  },
});

const completed = parseAgentEvent({
  eventType: 'step_up_completed',
  data: {
    sigil: 'su_2Zg4mKpT',
    approvedAtMs: Date.now(),
    factor: 'biometric',
  },
});

Policy change events record the direction of the change alongside version numbers:

const change = parseAgentEvent({
  eventType: 'policy_change',
  data: {
    fromVersion: 3,
    toVersion: 4,
    changedBy: 'user_operator_xyz',
    direction: 'tighten', // 'tighten' | 'loosen' | 'lateral'
  },
});

Safe parsing

parseAgentEvent throws on invalid input. For a non-throwing path use AgentEventSchema.safeParse:

import { AgentEventSchema } from '@glideco/agent-events';

const result = AgentEventSchema.safeParse(untrustedPayload);
if (!result.success) {
  console.error('invalid event', result.error.flatten());
} else {
  // result.data is a narrowed AgentEvent
}

Adding a new event type

Add the literal to AGENT_EVENT_TYPES.
Write a Zod schema for the payload.
Add a union member to AgentEventSchema.
Update the activity_log writer and any switch-exhaustive consumers.

New event types must go into unused positions — the literal strings are stable v1 once published in the JSON Schema at glide.co/schemas/agent-banking/v1/.

Reading list

AgentActivityEvent JSON Schema — the canonical v1 schema derived from this package.
@glideco/anomaly — emits anomaly_detected events consumed by this taxonomy.
@glideco/dsar — emits dsar_redaction_applied and dsar_tombstone_applied events; same payload shape.
@glideco/compliance-export — reads activity_log rows typed against these schemas for export.
Source on GitHub

Get started

Concepts

Packages

Connectors

Agent skills

Headless MCP

Security

Standards

Legal

@glideco/agent-events

Install

Why a closed vocab?

Event types (v1)

Key payload shapes

Safe parsing

Adding a new event type

Reading list

​Install

​Why a closed vocab?

​Event types (v1)

​Key payload shapes

​Safe parsing

​Adding a new event type

​Reading list

Install

Why a closed vocab?

Event types (v1)

Key payload shapes

Safe parsing

Adding a new event type

Reading list