How Session Identity is Defined in Apache Maka: Architecture and Implementation

Session identity in Apache Maka comprises two distinct elements—a human-readable session name for UI recognition and an immutable opaque session ID that uniquely routes messages, manages branching, and ensures stream continuity across the peer-mesh runtime.

In the apache/maka repository, session identity serves as the foundational mechanism for tracking logical conversation threads through the UI layer and distributed runtime. The architecture cleanly separates user-facing identification from internal routing primitives, ensuring that every message submission, revision history, and network stream remains unequivocally attached to the correct logical session.

Core Components of Session Identity

Maka defines session identity through a dual-concept model that balances usability with technical precision.

Human-Readable session Names

The session name provides the user-facing label that appears in browser title bars and conversation headers. In packages/ui/src/titlebar-session-identity.tsx at line 41, the TitlebarSessionIdentity component accepts a sessionName prop that renders the active conversation title (e.g., "Chat with Assistant"). This component handles display logic and rename callbacks but intentionally shields users from the underlying technical identifier.

The Opaque session ID

The session ID is an immutable string that functions as the canonical reference throughout the system. Unlike the display name, this identifier appears in runtime APIs such as window.maka.sessions.submitMessage and internal components including TranscriptViewportNavigation and ResumablePeerStream. The architectural specification in docs/architecture/peer-mesh-architecture.md (line 170) establishes this ID as the "logical stream session identity" that persists across network reconnects and process restarts.

How session ID is Used Throughout the System

The session ID threads through four critical subsystems, enabling consistent state management across distributed contexts.

Title Bar Navigation

TitlebarSessionIdentity manages navigation to parent sessions through callback props that internally carry the session ID. While the component displays only the human-readable name, navigation actions—such as clicking a breadcrumb to return to a root conversation—invoke handlers with the specific session ID required for the transition.

Branch Navigation and Context

The SessionContextLayer component in packages/ui/src/session-context-layer.tsx exposes branching capabilities through the SessionContextBranch interface defined at lines 41-44:

export interface SessionContextBranch {
  parentSessionId: string;      // ← the logical session identifier
  parentSessionName: string;
  fromAbortedTurn?: boolean;
}

When users interact with branch breadcrumbs, the onBranchNavigate(sessionId) callback receives the parentSessionId—the opaque identifier that ensures navigation targets the correct conversation fork, even when multiple sessions share identical display names.

Revision Tracking

Session identity enablestime-travel functionality through revision management. The SessionContextRevision interface (lines 47-52 of session-context-layer.tsx) tracks historical states:

export interface SessionContextRevision {
  current: number;
  total: number;
  previousSessionId?: string;   // ← ID of the prior revision
  nextSessionId?: string;       // ← ID of the next revision
}

These ID references allow the UI to request specific historical states from the backend, ensuring that rollbacks and forward navigation operate on the correct conversation snapshots.

Network Resumption and Peer-Mesh Streaming

In the peer-mesh layer, ResumablePeerStream utilizes the session ID to maintain logical byte-stream continuity across network interruptions. By reusing the same logical stream session identity during reconnects, the system identifies duplicate bytes and calculates precise retransmission requirements without corrupting conversation state.

Implementation Examples

The following patterns demonstrate how to work with both aspects of session identity in production code.

Rendering the Title-Bar Identity

This example shows TitlebarSessionIdentity consuming the display name while preserving the technical ID for navigation callbacks:

import { TitlebarSessionIdentity } from '@maka/ui';

function Header({ sessionId, sessionName, onRename }) {
  return (
    <TitlebarSessionIdentity
      sessionName={sessionName}
      onRenameSession={onRename}
      parentSession={{
        name: 'Root',
        // The UI will call this with the stored ID when the user clicks the left arrow
        onOpen: () => window.maka.sessions.switchTo(sessionId),
      }}
    />
  );
}

Managing Branch Context

When implementing conversation forking, pass the parent session ID through the context layer:

import { SessionContextLayer } from '@maka/ui';

function SessionHeader({ sessionId, parent }) {
  return (
    <SessionContextLayer
      sessionName="Chat with Assistant"
      branch={{
        parentSessionId: parent.id,          // ← logical session identifier
        parentSessionName: parent.name,
      }}
      onBranchNavigate={(id) => window.maka.sessions.switchTo(id)}
    />
  );
}

Navigating Revisions

Revision headers require previous and next session IDs to enable timeline navigation:

import { SessionContextLayer } from '@maka/ui';

function RevisionHeader({ rev }) {
  return (
    <SessionContextLayer
      sessionName="Chat v2"
      revision={{
        current: rev.index,
        total: rev.total,
        previousSessionId: rev.prevId,
        nextSessionId: rev.nextId,
      }}
      onRevisionNavigate={(id) => window.maka.sessions.switchTo(id)}
    />
  );
}

Summary

• Session identity in Maka consists of a display name and an opaque ID, implemented in packages/ui/src/titlebar-session-identity.tsx and referenced throughout the runtime.
• The session ID is immutable and used for message routing, branching, and revision tracking via interfaces like SessionContextBranch and SessionContextRevision in packages/ui/src/session-context-layer.tsx.
• Branch navigation relies on parentSessionId to maintain correct logical pointers when conversations split into parallel threads.
• Network resumption uses the session ID as a logical stream identifier to ensure data integrity across reconnects, as documented in docs/architecture/peer-mesh-architecture.md.

Frequently Asked Questions

What is the difference between session name and session ID in Maka?

The session name is a mutable, human-readable string displayed in the UI title bar through the TitlebarSessionIdentity component, allowing users to recognize conversations. The session ID is an immutable, opaque technical identifier used internally for routing messages, managing branches, and maintaining stream continuity across the peer-mesh network.

How does Maka handle session identity when conversations branch?

When a conversation branches, Maka stores the original session's ID in the parentSessionId field of the SessionContextBranch interface (defined at line 41 of packages/ui/src/session-context-layer.tsx). The UI displays the parent's name but uses this ID when invoking onBranchNavigate() to ensure navigation targets the correct logical conversation thread rather than potentially ambiguous display names.

Can session IDs be exposed to end users?

No. According to the implementation in titlebar-session-identity.tsx and related components, the raw session ID remains an internal implementation detail. The UI architecture intentionally separates the technical identifier from the presentation layer, exposing only the human-readable sessionName to end users while routing all actions through callbacks that internally reference the opaque ID.

Where is session identity persistence documented in the architecture?

The persistence and resumption of session identity across network interruptions is documented in docs/architecture/peer-mesh-architecture.md at line 170, which describes how ResumablePeerStream reuses the logical stream session identity to maintain byte-stream continuity and handle deduplication during reconnects.

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