Session Inspection System and Projections in Magnitude: A Complete Guide

The session inspection system in Magnitude is a CLI-driven toolkit that captures every agent interaction as a chronological event log, while projections are deterministic, pure functions that derive specific state views—such as UI hierarchies or task graphs—from those ordered events.

Magnitude stores every interaction that occurs while an agent is running as a session, creating a reproducible record of the entire runtime. The session inspection system and projection architecture enable developers to debug, analyze, and replay agent behavior with fine-grained control over which aspects of the system state they examine.

What Is the Session Inspection System?

A session in Magnitude is a chronological log of events—including turns, prompts, tool calls, and UI updates—that represents a complete record of an agent's execution. The session inspection system provides CLI utilities and runtime helpers that allow developers to query, search, and materialize views of this data long after the original execution has completed.

The system operates on an event log stored according to the architecture defined in design/storage/session-event-log.md. Each event is timestamped and typed, creating an immutable history that serves as the single source of truth for all inspection operations.

How Projections Work in Magnitude

Projections are deterministic, pure functions that consume the stream of session events and derive higher-level views of the system state. Because they are pure—meaning they have no side effects and given the same ordered list of events they always produce the same output—they are safe to run on any machine and form the foundation of Magnitude's reproducibility guarantees.

Built-in Projection Types

Magnitude ships with a comprehensive set of built-in projections, each residing in packages/acn/src/projections/ and representing a specific slice of the runtime:

• Window: Represents the current UI window hierarchy, including panels and tabs.
• Fork: Captures the branching structure of conversations, essential for multi-turn exploration scenarios.
• TaskGraph: Maintains the graph of tasks the agent has scheduled or completed.
• Turn: Tracks the most recent turn (prompt + response) of the agent.
• Display: Records all UI updates emitted during the session.
• Compaction: Generates a compacted view that removes duplicate or redundant events.
• WorkingState: Tracks internal mutable state of the agent, such as cached variables.
• SessionContext: Provides high-level metadata including session title, model used, and timestamps.
• Replay: Enables a full replay of the session that can be fed back into the agent for deterministic execution.
• AgentRegistry: Lists the agents and providers that were loaded during the session.
• Artifact: Tracks files or other artifacts created during execution.
• ChatTitle: Stores the title inferred for the chat based on its content.

Core CLI Commands for Session Inspection

The session inspection system exposes functionality through the bun session namespace, providing commands to list, view, search, and project session data.

Listing and Viewing Sessions

Use the list command to see all recorded sessions with their IDs, titles, and timestamps:

bun session list

To inspect specific events within a session, use the events command with optional type filtering:

bun session events 2023-08-15-01 --type turn_started,user_message

For detailed inspection of a single event, specify the session ID and event index:

bun session event 2023-08-15-01 42

Searching Event History

The search command finds events containing specific strings across sessions, supports limiting to recent sessions with --last:

bun session search "RateLimitError" --last 5

Replaying Projections

The projection command re-applies events to a specific projection and emits the resulting state as JSON:

bun session projection 2023-08-15-01 Window | jq .

For point-in-time projection, materialize all built-in projections at a specific event offset using the --at flag:

bun session projection 2023-08-15-01 all --at 42 | jq '.WorkingState'

To run a custom projection, specify its name as defined in the projections directory:

bun session projection 2023-08-15-01 MyProjection > my-projection-output.json

Technical Implementation Details

Session Inspector Module

The core CLI implementation resides in packages/acn/src/session-inspector.ts. This module reads the event log and dispatches events to the appropriate projection functions. It handles filtering (--type) and slicing (--from, --to) before events reach the projection layer, ensuring efficient processing even for large sessions.

The projection pipeline follows this flow:

event log → SessionInspector → Projection functions → JSON output

Projection Architecture

Individual projection implementations live in packages/acn/src/projections/. For example, the SessionContext projection is implemented in packages/agent/src/projections/session-context.ts, demonstrating how high-level metadata is derived from raw events.

Runtime state management backing the inspector is handled by packages/acn/src/session-runtime-state.ts, which maintains the mutable state required to feed projections while keeping the core event log immutable.

Summary

• Sessions are immutable, chronological logs of all agent interactions stored in the event log architecture.
• The session inspection system provides CLI tools (bun session list, events, search, projection) for querying and analyzing these logs.
• Projections are pure, deterministic functions that transform event streams into specific state views like Window, TaskGraph, or WorkingState.
• The system supports point-in-time projection using the --at flag to reconstruct state at arbitrary event indices.
• Core implementation files include packages/acn/src/session-inspector.ts for CLI logic and packages/acn/src/projections/* for individual projection logic.

Frequently Asked Questions

How does Magnitude ensure projection determinism across different machines?

Projections are implemented as pure functions that depend solely on the ordered list of input events, with no access to external state, random number generators, or system time. As long as the event log is identical, the projection output is identical regardless of where or when it runs, making them safe for distributed debugging and reproducible builds.

Can I create custom projections for domain-specific debugging?

Yes. Developers can implement custom projections by creating new modules in the packages/acn/src/projections/ directory that consume the event stream and emit JSON. Since the session inspector in packages/acn/src/session-inspector.ts dispatches dynamically to any registered projection, custom implementations integrate seamlessly with the bun session projection CLI command.

What is the performance impact of the session inspection system on running agents?

The inspection system operates on immutable event logs that are written asynchronously to disk according to design/storage/session-event-log.md. Projections are computed on-demand when CLI commands are executed, not during runtime, ensuring zero overhead during active agent execution unless explicitly enabled for real-time monitoring.

How does session inspection differ from traditional logging frameworks?

Unlike unstructured logs, Magnitude's sessions enforce a strict event schema where every interaction is typed and ordered. Projections provide structured, queryable views of system state rather than requiring developers to parse text logs, enablingTime-travel debugging and state reconstruction at specific event indices through commands like bun session projection <id> all --at <index>.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}