@unpolarize/code-sessions-schema 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,625 @@
+import * as zod from 'zod';
+import { z } from 'zod';
+import * as zod_to_json_schema from 'zod-to-json-schema';
+
+/**
+ * Canonical, agent-neutral session record schemas.
+ *
+ * Every record carries a versioned `schema` tag so consumers can migrate the
+ * way the SQLite `user_version` pattern does. Native records are adapted INTO
+ * these shapes while the verbatim `raw` event is preserved for lossless resume.
+ */
+declare const AGENTS: readonly ["claude-code", "codex", "grok", "unknown"];
+declare const ROLES: readonly ["user", "assistant", "tool", "system"];
+declare const UsageSchema: z.ZodObject<{
+    input_tokens: z.ZodDefault<z.ZodNumber>;
+    output_tokens: z.ZodDefault<z.ZodNumber>;
+    cache_read_tokens: z.ZodDefault<z.ZodNumber>;
+    cache_write_tokens: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens: number;
+    cache_write_tokens: number;
+}, {
+    input_tokens?: number | undefined;
+    output_tokens?: number | undefined;
+    cache_read_tokens?: number | undefined;
+    cache_write_tokens?: number | undefined;
+}>;
+declare const ToolCallSchema: z.ZodObject<{
+    name: z.ZodString;
+    input: z.ZodOptional<z.ZodUnknown>;
+    id: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    input?: unknown;
+    id?: string | undefined;
+}, {
+    name: string;
+    input?: unknown;
+    id?: string | undefined;
+}>;
+declare const TelemetrySchema: z.ZodObject<{
+    latency_ms: z.ZodOptional<z.ZodNumber>;
+    cost_usd: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    latency_ms?: number | undefined;
+    cost_usd?: number | undefined;
+}, {
+    latency_ms?: number | undefined;
+    cost_usd?: number | undefined;
+}>;
+/** Immutable, write-once per-turn record: turns/NNNNNN.json */
+declare const TurnSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"session-store/turn@1">;
+    session_id: z.ZodString;
+    host: z.ZodString;
+    agent: z.ZodEnum<["claude-code", "codex", "grok", "unknown"]>;
+    turn_index: z.ZodNumber;
+    ts: z.ZodString;
+    role: z.ZodEnum<["user", "assistant", "tool", "system"]>;
+    text: z.ZodDefault<z.ZodString>;
+    tool_calls: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        input: z.ZodOptional<z.ZodUnknown>;
+        id: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        input?: unknown;
+        id?: string | undefined;
+    }, {
+        name: string;
+        input?: unknown;
+        id?: string | undefined;
+    }>, "many">>;
+    usage: z.ZodDefault<z.ZodObject<{
+        input_tokens: z.ZodDefault<z.ZodNumber>;
+        output_tokens: z.ZodDefault<z.ZodNumber>;
+        cache_read_tokens: z.ZodDefault<z.ZodNumber>;
+        cache_write_tokens: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_tokens: number;
+        cache_write_tokens: number;
+    }, {
+        input_tokens?: number | undefined;
+        output_tokens?: number | undefined;
+        cache_read_tokens?: number | undefined;
+        cache_write_tokens?: number | undefined;
+    }>>;
+    telemetry: z.ZodOptional<z.ZodObject<{
+        latency_ms: z.ZodOptional<z.ZodNumber>;
+        cost_usd: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        latency_ms?: number | undefined;
+        cost_usd?: number | undefined;
+    }, {
+        latency_ms?: number | undefined;
+        cost_usd?: number | undefined;
+    }>>;
+    /** true when secret-scrubbing redacted content in this turn */
+    scrubbed: z.ZodDefault<z.ZodBoolean>;
+    /** sha256 pointer when a large tool output was externalized to raw/ */
+    raw_ref: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /** verbatim native event for lossless tier-1 resume */
+    raw: z.ZodOptional<z.ZodUnknown>;
+}, "strict", z.ZodTypeAny, {
+    schema: "session-store/turn@1";
+    session_id: string;
+    host: string;
+    agent: "claude-code" | "codex" | "grok" | "unknown";
+    turn_index: number;
+    ts: string;
+    role: "user" | "assistant" | "tool" | "system";
+    text: string;
+    tool_calls: {
+        name: string;
+        input?: unknown;
+        id?: string | undefined;
+    }[];
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_tokens: number;
+        cache_write_tokens: number;
+    };
+    scrubbed: boolean;
+    raw_ref: string | null;
+    telemetry?: {
+        latency_ms?: number | undefined;
+        cost_usd?: number | undefined;
+    } | undefined;
+    raw?: unknown;
+}, {
+    schema: "session-store/turn@1";
+    session_id: string;
+    host: string;
+    agent: "claude-code" | "codex" | "grok" | "unknown";
+    turn_index: number;
+    ts: string;
+    role: "user" | "assistant" | "tool" | "system";
+    text?: string | undefined;
+    tool_calls?: {
+        name: string;
+        input?: unknown;
+        id?: string | undefined;
+    }[] | undefined;
+    usage?: {
+        input_tokens?: number | undefined;
+        output_tokens?: number | undefined;
+        cache_read_tokens?: number | undefined;
+        cache_write_tokens?: number | undefined;
+    } | undefined;
+    telemetry?: {
+        latency_ms?: number | undefined;
+        cost_usd?: number | undefined;
+    } | undefined;
+    scrubbed?: boolean | undefined;
+    raw_ref?: string | null | undefined;
+    raw?: unknown;
+}>;
+declare const TotalsSchema: z.ZodObject<{
+    input_tokens: z.ZodDefault<z.ZodNumber>;
+    output_tokens: z.ZodDefault<z.ZodNumber>;
+    cost_usd: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    input_tokens: number;
+    output_tokens: number;
+    cost_usd: number;
+}, {
+    input_tokens?: number | undefined;
+    output_tokens?: number | undefined;
+    cost_usd?: number | undefined;
+}>;
+declare const NativeRefSchema: z.ZodObject<{
+    format: z.ZodString;
+    uuid: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    format: string;
+    uuid: string;
+}, {
+    format: string;
+    uuid: string;
+}>;
+/** Derived, rebuildable aggregate: session.json */
+declare const SessionSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"session-store/session@1">;
+    session_id: z.ZodString;
+    host: z.ZodString;
+    agent: z.ZodEnum<["claude-code", "codex", "grok", "unknown"]>;
+    project_path: z.ZodDefault<z.ZodString>;
+    git_branch: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    started_at: z.ZodOptional<z.ZodString>;
+    ended_at: z.ZodOptional<z.ZodString>;
+    turn_count: z.ZodDefault<z.ZodNumber>;
+    tool_call_count: z.ZodDefault<z.ZodNumber>;
+    totals: z.ZodDefault<z.ZodObject<{
+        input_tokens: z.ZodDefault<z.ZodNumber>;
+        output_tokens: z.ZodDefault<z.ZodNumber>;
+        cost_usd: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        input_tokens: number;
+        output_tokens: number;
+        cost_usd: number;
+    }, {
+        input_tokens?: number | undefined;
+        output_tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    }>>;
+    title: z.ZodOptional<z.ZodString>;
+    labels: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    native_ref: z.ZodObject<{
+        format: z.ZodString;
+        uuid: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        format: string;
+        uuid: string;
+    }, {
+        format: string;
+        uuid: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    schema: "session-store/session@1";
+    session_id: string;
+    host: string;
+    agent: "claude-code" | "codex" | "grok" | "unknown";
+    project_path: string;
+    turn_count: number;
+    tool_call_count: number;
+    totals: {
+        input_tokens: number;
+        output_tokens: number;
+        cost_usd: number;
+    };
+    labels: string[];
+    native_ref: {
+        format: string;
+        uuid: string;
+    };
+    git_branch?: string | undefined;
+    model?: string | undefined;
+    started_at?: string | undefined;
+    ended_at?: string | undefined;
+    title?: string | undefined;
+}, {
+    schema: "session-store/session@1";
+    session_id: string;
+    host: string;
+    agent: "claude-code" | "codex" | "grok" | "unknown";
+    native_ref: {
+        format: string;
+        uuid: string;
+    };
+    project_path?: string | undefined;
+    git_branch?: string | undefined;
+    model?: string | undefined;
+    started_at?: string | undefined;
+    ended_at?: string | undefined;
+    turn_count?: number | undefined;
+    tool_call_count?: number | undefined;
+    totals?: {
+        input_tokens?: number | undefined;
+        output_tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    } | undefined;
+    title?: string | undefined;
+    labels?: string[] | undefined;
+}>;
+declare const SIGNAL_KINDS: readonly ["stuck-loop", "error-recovery", "high-cost-turn", "long-session", "affect-negative", "affect-positive", "tool-heavy", "other"];
+declare const SignalSchema: z.ZodObject<{
+    kind: z.ZodEnum<["stuck-loop", "error-recovery", "high-cost-turn", "long-session", "affect-negative", "affect-positive", "tool-heavy", "other"]>;
+    severity: z.ZodDefault<z.ZodEnum<["info", "warn", "critical"]>>;
+    turn_index: z.ZodOptional<z.ZodNumber>;
+    note: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    kind: "stuck-loop" | "error-recovery" | "high-cost-turn" | "long-session" | "affect-negative" | "affect-positive" | "tool-heavy" | "other";
+    severity: "info" | "warn" | "critical";
+    turn_index?: number | undefined;
+    note?: string | undefined;
+}, {
+    kind: "stuck-loop" | "error-recovery" | "high-cost-turn" | "long-session" | "affect-negative" | "affect-positive" | "tool-heavy" | "other";
+    turn_index?: number | undefined;
+    severity?: "info" | "warn" | "critical" | undefined;
+    note?: string | undefined;
+}>;
+/** Derived insights: insights/labels.json (MVP-1.1) */
+declare const InsightsSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"session-store/insights@1">;
+    session_id: z.ZodString;
+    host: z.ZodString;
+    generated_at: z.ZodString;
+    provider: z.ZodString;
+    topic: z.ZodOptional<z.ZodString>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    signals: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<["stuck-loop", "error-recovery", "high-cost-turn", "long-session", "affect-negative", "affect-positive", "tool-heavy", "other"]>;
+        severity: z.ZodDefault<z.ZodEnum<["info", "warn", "critical"]>>;
+        turn_index: z.ZodOptional<z.ZodNumber>;
+        note: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        kind: "stuck-loop" | "error-recovery" | "high-cost-turn" | "long-session" | "affect-negative" | "affect-positive" | "tool-heavy" | "other";
+        severity: "info" | "warn" | "critical";
+        turn_index?: number | undefined;
+        note?: string | undefined;
+    }, {
+        kind: "stuck-loop" | "error-recovery" | "high-cost-turn" | "long-session" | "affect-negative" | "affect-positive" | "tool-heavy" | "other";
+        turn_index?: number | undefined;
+        severity?: "info" | "warn" | "critical" | undefined;
+        note?: string | undefined;
+    }>, "many">>;
+    summary: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    schema: "session-store/insights@1";
+    session_id: string;
+    host: string;
+    generated_at: string;
+    provider: string;
+    tags: string[];
+    signals: {
+        kind: "stuck-loop" | "error-recovery" | "high-cost-turn" | "long-session" | "affect-negative" | "affect-positive" | "tool-heavy" | "other";
+        severity: "info" | "warn" | "critical";
+        turn_index?: number | undefined;
+        note?: string | undefined;
+    }[];
+    topic?: string | undefined;
+    summary?: string | undefined;
+}, {
+    schema: "session-store/insights@1";
+    session_id: string;
+    host: string;
+    generated_at: string;
+    provider: string;
+    topic?: string | undefined;
+    tags?: string[] | undefined;
+    signals?: {
+        kind: "stuck-loop" | "error-recovery" | "high-cost-turn" | "long-session" | "affect-negative" | "affect-positive" | "tool-heavy" | "other";
+        turn_index?: number | undefined;
+        severity?: "info" | "warn" | "critical" | undefined;
+        note?: string | undefined;
+    }[] | undefined;
+    summary?: string | undefined;
+}>;
+type Usage = z.infer<typeof UsageSchema>;
+type ToolCall = z.infer<typeof ToolCallSchema>;
+type Telemetry = z.infer<typeof TelemetrySchema>;
+type Turn = z.infer<typeof TurnSchema>;
+type Totals = z.infer<typeof TotalsSchema>;
+type SessionEnvelope = z.infer<typeof SessionSchema>;
+type Signal = z.infer<typeof SignalSchema>;
+type Insights = z.infer<typeof InsightsSchema>;
+type AgentKind = (typeof AGENTS)[number];
+type Role = (typeof ROLES)[number];
+type SignalKind = (typeof SIGNAL_KINDS)[number];
+declare const SCHEMA_VERSIONS: {
+    readonly turn: "session-store/turn@1";
+    readonly session: "session-store/session@1";
+    readonly insights: "session-store/insights@1";
+};
+
+interface NormalizedEvent {
+    ts: string;
+    role: Role;
+    text: string;
+    tool_calls: ToolCall[];
+    usage: Usage;
+    raw: unknown;
+}
+interface BuildTurnContext {
+    session_id: string;
+    host: string;
+    agent: AgentKind;
+    turn_index: number;
+}
+/** Map a single native Claude line into a normalized event, or null if it is metadata. */
+declare function normalizeClaudeEvent(raw: unknown, fallbackTs?: string): NormalizedEvent | null;
+/** Assemble a complete, schema-valid Turn from a normalized event + identity context. */
+declare function buildTurn(ev: NormalizedEvent, ctx: BuildTurnContext): Turn;
+interface ClaudeSessionMeta {
+    session_id?: string;
+    model?: string;
+    project_path?: string;
+    git_branch?: string;
+    title?: string;
+    started_at?: string;
+    ended_at?: string;
+}
+/** Pull session-envelope metadata out of a batch of native Claude lines. */
+declare function extractClaudeSessionMeta(rawLines: unknown[]): ClaudeSessionMeta;
+/** Convenience: normalize a full batch of lines with sequential turn indices (for tests/backfill). */
+declare function normalizeClaudeLines(rawLines: unknown[], ctx: {
+    session_id: string;
+    host: string;
+    agent: AgentKind;
+    startIndex?: number;
+}): {
+    turns: Turn[];
+    meta: ClaudeSessionMeta;
+};
+
+/** JSON Schema (draft-07) representations for external (non-TS) consumers. */
+declare const turnJsonSchema: zod_to_json_schema.JsonSchema7Type & {
+    $schema?: string | undefined;
+    definitions?: {
+        [key: string]: zod_to_json_schema.JsonSchema7Type;
+    } | undefined;
+};
+declare const sessionJsonSchema: zod_to_json_schema.JsonSchema7Type & {
+    $schema?: string | undefined;
+    definitions?: {
+        [key: string]: zod_to_json_schema.JsonSchema7Type;
+    } | undefined;
+};
+declare const insightsJsonSchema: zod_to_json_schema.JsonSchema7Type & {
+    $schema?: string | undefined;
+    definitions?: {
+        [key: string]: zod_to_json_schema.JsonSchema7Type;
+    } | undefined;
+};
+/** Parse + validate (throws on invalid). Applies schema defaults. */
+declare const parseTurn: (data: unknown) => {
+    schema: "session-store/turn@1";
+    session_id: string;
+    host: string;
+    agent: "claude-code" | "codex" | "grok" | "unknown";
+    turn_index: number;
+    ts: string;
+    role: "user" | "assistant" | "tool" | "system";
+    text: string;
+    tool_calls: {
+        name: string;
+        input?: unknown;
+        id?: string | undefined;
+    }[];
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_tokens: number;
+        cache_write_tokens: number;
+    };
+    scrubbed: boolean;
+    raw_ref: string | null;
+    telemetry?: {
+        latency_ms?: number | undefined;
+        cost_usd?: number | undefined;
+    } | undefined;
+    raw?: unknown;
+};
+declare const parseSession: (data: unknown) => {
+    schema: "session-store/session@1";
+    session_id: string;
+    host: string;
+    agent: "claude-code" | "codex" | "grok" | "unknown";
+    project_path: string;
+    turn_count: number;
+    tool_call_count: number;
+    totals: {
+        input_tokens: number;
+        output_tokens: number;
+        cost_usd: number;
+    };
+    labels: string[];
+    native_ref: {
+        format: string;
+        uuid: string;
+    };
+    git_branch?: string | undefined;
+    model?: string | undefined;
+    started_at?: string | undefined;
+    ended_at?: string | undefined;
+    title?: string | undefined;
+};
+declare const parseInsights: (data: unknown) => {
+    schema: "session-store/insights@1";
+    session_id: string;
+    host: string;
+    generated_at: string;
+    provider: string;
+    tags: string[];
+    signals: {
+        kind: "stuck-loop" | "error-recovery" | "high-cost-turn" | "long-session" | "affect-negative" | "affect-positive" | "tool-heavy" | "other";
+        severity: "info" | "warn" | "critical";
+        turn_index?: number | undefined;
+        note?: string | undefined;
+    }[];
+    topic?: string | undefined;
+    summary?: string | undefined;
+};
+/** Non-throwing validation. */
+declare const safeParseTurn: (data: unknown) => zod.SafeParseReturnType<{
+    schema: "session-store/turn@1";
+    session_id: string;
+    host: string;
+    agent: "claude-code" | "codex" | "grok" | "unknown";
+    turn_index: number;
+    ts: string;
+    role: "user" | "assistant" | "tool" | "system";
+    text?: string | undefined;
+    tool_calls?: {
+        name: string;
+        input?: unknown;
+        id?: string | undefined;
+    }[] | undefined;
+    usage?: {
+        input_tokens?: number | undefined;
+        output_tokens?: number | undefined;
+        cache_read_tokens?: number | undefined;
+        cache_write_tokens?: number | undefined;
+    } | undefined;
+    telemetry?: {
+        latency_ms?: number | undefined;
+        cost_usd?: number | undefined;
+    } | undefined;
+    scrubbed?: boolean | undefined;
+    raw_ref?: string | null | undefined;
+    raw?: unknown;
+}, {
+    schema: "session-store/turn@1";
+    session_id: string;
+    host: string;
+    agent: "claude-code" | "codex" | "grok" | "unknown";
+    turn_index: number;
+    ts: string;
+    role: "user" | "assistant" | "tool" | "system";
+    text: string;
+    tool_calls: {
+        name: string;
+        input?: unknown;
+        id?: string | undefined;
+    }[];
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_tokens: number;
+        cache_write_tokens: number;
+    };
+    scrubbed: boolean;
+    raw_ref: string | null;
+    telemetry?: {
+        latency_ms?: number | undefined;
+        cost_usd?: number | undefined;
+    } | undefined;
+    raw?: unknown;
+}>;
+declare const safeParseSession: (data: unknown) => zod.SafeParseReturnType<{
+    schema: "session-store/session@1";
+    session_id: string;
+    host: string;
+    agent: "claude-code" | "codex" | "grok" | "unknown";
+    native_ref: {
+        format: string;
+        uuid: string;
+    };
+    project_path?: string | undefined;
+    git_branch?: string | undefined;
+    model?: string | undefined;
+    started_at?: string | undefined;
+    ended_at?: string | undefined;
+    turn_count?: number | undefined;
+    tool_call_count?: number | undefined;
+    totals?: {
+        input_tokens?: number | undefined;
+        output_tokens?: number | undefined;
+        cost_usd?: number | undefined;
+    } | undefined;
+    title?: string | undefined;
+    labels?: string[] | undefined;
+}, {
+    schema: "session-store/session@1";
+    session_id: string;
+    host: string;
+    agent: "claude-code" | "codex" | "grok" | "unknown";
+    project_path: string;
+    turn_count: number;
+    tool_call_count: number;
+    totals: {
+        input_tokens: number;
+        output_tokens: number;
+        cost_usd: number;
+    };
+    labels: string[];
+    native_ref: {
+        format: string;
+        uuid: string;
+    };
+    git_branch?: string | undefined;
+    model?: string | undefined;
+    started_at?: string | undefined;
+    ended_at?: string | undefined;
+    title?: string | undefined;
+}>;
+declare const safeParseInsights: (data: unknown) => zod.SafeParseReturnType<{
+    schema: "session-store/insights@1";
+    session_id: string;
+    host: string;
+    generated_at: string;
+    provider: string;
+    topic?: string | undefined;
+    tags?: string[] | undefined;
+    signals?: {
+        kind: "stuck-loop" | "error-recovery" | "high-cost-turn" | "long-session" | "affect-negative" | "affect-positive" | "tool-heavy" | "other";
+        turn_index?: number | undefined;
+        severity?: "info" | "warn" | "critical" | undefined;
+        note?: string | undefined;
+    }[] | undefined;
+    summary?: string | undefined;
+}, {
+    schema: "session-store/insights@1";
+    session_id: string;
+    host: string;
+    generated_at: string;
+    provider: string;
+    tags: string[];
+    signals: {
+        kind: "stuck-loop" | "error-recovery" | "high-cost-turn" | "long-session" | "affect-negative" | "affect-positive" | "tool-heavy" | "other";
+        severity: "info" | "warn" | "critical";
+        turn_index?: number | undefined;
+        note?: string | undefined;
+    }[];
+    topic?: string | undefined;
+    summary?: string | undefined;
+}>;
+
+export { AGENTS, type AgentKind, type BuildTurnContext, type ClaudeSessionMeta, type Insights, InsightsSchema, NativeRefSchema, type NormalizedEvent, ROLES, type Role, SCHEMA_VERSIONS, SIGNAL_KINDS, type SessionEnvelope, SessionSchema, type Signal, type SignalKind, SignalSchema, type Telemetry, TelemetrySchema, type ToolCall, ToolCallSchema, type Totals, TotalsSchema, type Turn, TurnSchema, type Usage, UsageSchema, buildTurn, extractClaudeSessionMeta, insightsJsonSchema, normalizeClaudeEvent, normalizeClaudeLines, parseInsights, parseSession, parseTurn, safeParseInsights, safeParseSession, safeParseTurn, sessionJsonSchema, turnJsonSchema };