Activity Stream & Audit Logs
Relevant source files
The following files were used as context for generating this wiki page:
Activity Stream & Audit Logs record and display the execution history of TypeScript programs, tool interactions, and system events within Coral. The system provides a real-time observability layer that allows users to monitor agent work, review pending policy approvals, and audit historical records of provider operations.
The system captures high-fidelity evidence, including exact program source code, logical arguments, and native upstream responses. It organizes this data into a hierarchical structure of Tasks, Runs, and Invocations to provide context for every recorded action.
Sources: README.md, apps/reef/app/lib/activity.server.test.ts:22-30
Architecture and Data Hierarchy
The activity system organizes records into a three-tier hierarchy to maintain context and provenance.
Data Model Hierarchy
- Task: The top-level unit representing a user-requested goal or intent. It contains one or more interactions.
- Interaction/Submission: A specific attempt to achieve a task, such as a search query, a describe call, or an
execprogram submission. - Run: The sandboxed execution of a program. It contains events and invocations.
- Invocation/Operation: A specific call made by a program to an external provider (e.g., GitHub, Linear) or a internal Coral function.
- Event: Fine-grained logs and emissions generated during a Run, including
program.logged,program.emitted, and lifecycle marks likerun.started.
Sources: apps/reef/app/views/activity/activity.test.tsx:12-60, apps/reef/app/lib/activity.server.test.ts:31-65, crates/coral-grpc/src/grpc/activity.rs:88-128
Component Relationship
The diagram shows how high-level Tasks group program Runs, which in turn own the detailed Invocations and Events.
Sources: apps/reef/app/lib/activity.server.test.ts:66-80, crates/coral-grpc/src/grpc/activity.rs:252-300
Real-time Streaming (Live Mode)
Coral uses a streaming architecture to push updates to the UI as they occur. The watch_activity gRPC service establishes a long-lived connection that wakes activity observers whenever an observable mutation occurs.
Live Observation Flow
The flow ensures that the UI remains synchronized with the backend without constant polling. Mutations marked with execute_change trigger immediate observer wake-ups.
Sources: AGENTS.md:55-65, crates/coral-grpc/src/grpc/activity.rs:200-240, apps/reef/e2e/scenarios/main/activity/live.test.ts:15-50
Audit Log Evidence and Snapshots
The activity system retains exact evidence of what occurred to prevent "audit drift" where current policy or code changes might obscure historical truth.
| Evidence Type | Description | Sources |
|---|---|---|
| Accepted Source | The exact TypeScript program text executed during a specific Run. | crates/coral-grpc/tests/grpc/activity_evidence.rs:650-700 |
| Logical Arguments | The JSON-encoded arguments passed to a provider operation. | apps/reef/app/views/activity/detail.test.tsx:90-110 |
| Native Response | The raw response received from the upstream service, including HTTP status codes. | apps/reef/app/views/activity/detail.test.tsx:125-150 |
| Source Location | The specific line and column in the program source that triggered a log or call. | apps/reef/app/lib/activity.server.test.ts:85-100 |
| Function Snapshots | A copy of a saved function's source code at the moment it was called by another program. | apps/reef/app/views/activity/detail.test.tsx:210-230 |
Sources: apps/reef/app/views/activity/detail.test.tsx, crates/coral-grpc/tests/grpc/activity_evidence.rs
Policy Approvals and Action Queue
When a policy rule requires approval for an operation, the Invocation enters a Pending state. The activity system manages these as "Required Actions" that must be resolved by a user.
Key Logic for Actions:
- Queueing: Required actions are paged and listed with the Run that waits on them.
- Decision Persistence: When a user approves or declines, the system records the
approver,decided_attimestamp, and an optionalcomment. - Concurrency: A single Run may wait on multiple concurrent approvals or account connections. The system advance the review once the current decision is submitted.
- Deadlines: Actions carry a
deadline(expiry) decided in the Run Owner's memory to ensure atomicity.
Sources: crates/coral-grpc/src/grpc/activity.rs:335-375, apps/reef/app/lib/activity.server.test.ts:1140-1180, apps/reef/app/views/activity/detail.test.tsx:750-800
Security and Authority Boundaries
The activity system enforces strict visibility rules to prevent unauthorized access to sensitive audit logs.
Visibility Rules:
- Personal Scope: Users see their own activity and work they are authorized to oversee.
- Agent Scope: Agent history is independently authorized. Effective Workspace Owners can observe Agent work, but demotion immediately removes access to rows and snapshots without requiring a page reload.
- Workspace Isolation: Read/write operations must match both the Workspace identity and the entity identity.
- Authority Loss: If authority is revoked while a user is viewing a stream, the system conceals the snapshots and reports "This history is unavailable."
Sources: AGENTS.md:110-115, apps/reef/e2e/scenarios/main/activity/live.test.ts:360-410, apps/reef/app/lib/activity.server.test.ts:1000-1030
Summary
The Activity Stream & Audit Logs system provides a durable, real-time record of all agent interactions within Coral. By preserving exact snapshots of code and data, and enforcing policy-driven approval workflows, it ensures that every automated action is observable, auditable, and controlled by human operators.