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";
codex_sdk - Events from Codex SDK live streamingcodex_exec - Events from codex exec --json outputcodex_history - Events imported from Codex historyclaude_code_history - Events imported from Claude Code historygemini_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;
}
Unique identifier for the event (24-character SHA-256 hash)
Repository identifier (12-character SHA-1 hash of absolute path)
User/contributor identifier, or null if unknown
Session UUID that groups related events
Thread identifier for conversation context
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
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
Sequence number within session
createCapturedEvent
Creates a normalized captured event envelope.
function createCapturedEvent(
input: CreateCapturedEventInput
): CapturedEventEnvelope
input
CreateCapturedEventInput
required
Event creation parameters
CapturedEventEnvelope
repoIdFromPath
Generates a repository ID from a filesystem path.
function repoIdFromPath(pathname: string): string
Absolute or relative path to repository
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