Core Types

Core type definitions and interfaces for Codaph event capture and processing

Overview

The core types module defines the fundamental data structures used throughout Codaph for capturing and processing agent events.

Types

AgentSource

Identifies the origin of captured events.

type AgentSource =
  | "codex_sdk"
  | "codex_exec"
  | "codex_history"
  | "claude_code_history"
  | "gemini_cli_history";

Values:

• codex_sdk - Events from Codex SDK live streaming
• codex_exec - Events from codex exec --json output
• codex_history - Events imported from Codex history
• claude_code_history - Events imported from Claude Code history
• gemini_cli_history - Events imported from Gemini CLI history

ReasoningAvailability

Indicates the availability of reasoning content in an event.

type ReasoningAvailability = "full" | "partial" | "unavailable";

CapturedEventEnvelope

The canonical shape for all captured agent events.

interface CapturedEventEnvelope {
  eventId: string;
  source: AgentSource;
  repoId: string;
  actorId: string | null;
  sessionId: string;
  threadId: string | null;
  ts: string;
  eventType: string;
  payload: Record<string, unknown>;
  reasoningAvailability: ReasoningAvailability;
}

eventId · string · required

Unique identifier for the event (24-character SHA-256 hash)

source · AgentSource · required

Origin of the event

repoId · string · required

Repository identifier (12-character SHA-1 hash of absolute path)

actorId · string | null · required

User/contributor identifier, or null if unknown

sessionId · string · required

Session UUID that groups related events

threadId · string | null · required

Thread identifier for conversation context

ts · string · required

ISO 8601 timestamp

eventType · string · required

Event type (e.g., “prompt.submitted”, “item.completed”)

payload · Record<string, unknown> · required

Event-specific data

reasoningAvailability · ReasoningAvailability · required

Indicates if reasoning content is available

CreateCapturedEventInput

Input for creating a captured event with optional fields.

interface CreateCapturedEventInput {
  eventId?: string;
  source: AgentSource;
  repoId: string;
  actorId?: string | null;
  sessionId: string;
  threadId: string | null;
  ts: string;
  sequence: number;
  eventType: string;
  payload: Record<string, unknown>;
  reasoningAvailability?: ReasoningAvailability;
}

IngestContext

Context for event normalization in the ingest pipeline.

interface IngestContext {
  source: AgentSource;
  repoId: string;
  actorId?: string | null;
  sessionId: string;
  threadId: string | null;
  sequence: number;
  eventId?: string;
  ts?: string;
}

Functions

createEventId

Generates a deterministic event ID from event properties.

function createEventId(input: {
  source: AgentSource;
  threadId: string | null;
  sequence: number;
  eventType: string;
  ts: string;
}): string

input.source · AgentSource · required

Event source

input.threadId · string | null · required

Thread identifier

input.sequence · number · required

Sequence number within session

input.eventType · string · required

Event type

input.ts · string · required

ISO timestamp

Returns: 24-character SHA-256 hash

createCapturedEvent

Creates a normalized captured event envelope.

function createCapturedEvent(
  input: CreateCapturedEventInput
): CapturedEventEnvelope

input · CreateCapturedEventInput · required

Event creation parameters

Returns: Fully normalized CapturedEventEnvelope

repoIdFromPath

Generates a repository ID from a filesystem path.

function repoIdFromPath(pathname: string): string

pathname · string · required

Absolute or relative path to repository

Returns: 12-character SHA-1 hash of resolved absolute path

Usage Example

import {
  createCapturedEvent,
  repoIdFromPath,
  type CapturedEventEnvelope,
} from './lib/core-types';

const repoId = repoIdFromPath('/path/to/repo');

const event = createCapturedEvent({
  source: 'codex_sdk',
  repoId,
  sessionId: 'session-uuid',
  threadId: 'thread-123',
  ts: new Date().toISOString(),
  sequence: 1,
  eventType: 'prompt.submitted',
  payload: {
    prompt: 'Fix the bug in auth.ts',
  },
});

console.log(event.eventId); // Auto-generated hash