Notifications V2 & Audit Trail
Relevant source files
The following files were used as context for generating this wiki page:
The Notifications V2 and Audit Trail systems provide a robust infrastructure for communication and historical tracking within the Orcy platform. Notifications V2 introduces a durable, multi-channel messaging system that supports subscriptions, acknowledgement, and retention-based clearance for both human and agent pod members. The Audit Trail V2 serves as a canonical projection over the entire project lifecycle, capturing events from effort logging, code evidence, pipeline integrations, and webhook sources.
Together, these systems ensure that all pod activities are observable, accountable, and traceable. The Audit Trail specifically focuses on provenance metadata and completeness tracking, while Notifications V2 manages attention and alerting across in-app, Slack, Discord, and webhook channels.
Sources: README.md:58-62, README.md:120-123
Notification System V2
The Notification System V2 is designed for durable delivery and lifecycle management of alerts. It moves away from transient messages to a stateful model where deliveries can be acknowledged, snoozed, or muted.
Key Capabilities
- Multi-Channel Routing: Supports in-app notifications, webhooks, Slack, and Discord.
- Subscription Model: Pod members can subscribe to specific event types within a habitat.
- Attention Management: Includes features for acknowledgement, snoozing until a specific time, and manual/retention-based clearance.
- Recipient Deduping: Collapses participants with shared external identities to prevent duplicate deliveries across pods.
Sources: README.md:120-123, packages/mcp/src/api.ts:511-514, packages/mcp/src/api.ts:1330-1367
Notification Lifecycle Flow
The following diagram illustrates how a notification delivery is managed by a pod member via the MCP client or API.
MCP Notification Interface
Pod members interacting via the Model Context Protocol (MCP) have access to self-service notification tools.
| Method | Description | Path |
|---|---|---|
getInbox | Lists active, unread notifications for the habitat. | /api/habitats/:id/notifications/inbox |
acknowledgeDelivery | Marks a specific notification delivery as read/handled. | /api/habitats/:id/notifications/deliveries/:id/ack |
snoozeDelivery | Defers a notification until a provided ISO timestamp. | /api/habitats/:id/notifications/deliveries/:id/snooze |
getSubscriptions | Lists current event subscriptions for the caller. | /api/habitats/:id/notifications/subscriptions |
Sources: packages/mcp/src/api.ts:1330-1367, packages/mcp/src/api/interfaces.ts:511-520
Audit Trail V2
Audit Trail V2 provides a high-fidelity, append-only log of all significant actions within a habitat. It aggregates data from various sources to create a "canonical projection" of the project's history.
System Architecture
The audit system is built to support streaming exports and scoped evidence bundles, ensuring that work provenance can be verified during reviews or quality gates.
Audit Data Components
The system captures structured metadata including provenance (who did what and from where) and integrity (ensuring logs haven't been tampered with).
- Provenance Metadata: Tracks the source (e.g.,
rest_api,mcp_tool) and actor type (agent vs human). - Completeness Tracking: Monitors if required evidence (like commits or PR links) is present for completed tasks.
- Integrity Logging: Includes health snapshots and integrity hashes to validate the audit chain.
Sources: README.md:124-127, packages/mcp/src/api.ts:602-610, packages/api/src/test/documentationValidation.test.ts:47-51
Audit API and Export Options
The system supports flexible querying and exporting through the AuditClient.
| Parameter | Type | Description |
|---|---|---|
format | csv, json, jsonl | The file format for the exported log. |
includeProvenance | boolean | Whether to include actor and source metadata. |
includeIntegrity | boolean | Whether to include cryptographic integrity checks. |
entityType | string | Filter by specific entity (task, mission, habitat). |
since/until | string | ISO timestamps for time-windowed exports. |
Sources: packages/mcp/src/api.ts:1115-1141, packages/mcp/src/api/interfaces.ts:446-455
Security and Authorization
Both systems enforce strict security postures depending on whether the deployment is local-dev or remote.
- Identity Binding: Actor identity is derived directly from the API key or JWT; it is never accepted from the request body or URL to prevent impersonation.
- Scope Enforcement: Specific operations, such as acknowledging notifications, require dedicated write scopes (e.g.,
notification.write). - Audit Headers: MCP tools automatically inject
X-Orcy-Audit-SourceandX-Orcy-MCP-Toolheaders to ensure accurate provenance in the audit trail.
Sources: packages/api/src/test/documentationValidation.test.ts:21-40, packages/mcp/src/api.ts:511-536, packages/mcp/src/api.ts:555-565
Summary
Notifications V2 and Audit Trail V2 form the backbone of Orcy's coordination and accountability layers. Notifications manage the real-time attention of pod members through stateful, multi-channel deliveries, while the Audit Trail provides a permanent, verifiable record of all actions. By combining provenance metadata with rigorous security and identity binding, Orcy ensures that every task execution and mission progression is transparent and auditable.