@unpolarize/code-sessions-schema 0.1.0

package/dist/index.js

@@ -0,0 +1,277 @@
+// src/schemas.ts
+import { z } from "zod";
+var AGENTS = ["claude-code", "codex", "grok", "unknown"];
+var ROLES = ["user", "assistant", "tool", "system"];
+var UsageSchema = z.object({
+  input_tokens: z.number().int().nonnegative().default(0),
+  output_tokens: z.number().int().nonnegative().default(0),
+  cache_read_tokens: z.number().int().nonnegative().default(0),
+  cache_write_tokens: z.number().int().nonnegative().default(0)
+}).strict();
+var ToolCallSchema = z.object({
+  name: z.string(),
+  input: z.unknown().optional(),
+  id: z.string().optional()
+}).strict();
+var TelemetrySchema = z.object({
+  latency_ms: z.number().nonnegative().optional(),
+  cost_usd: z.number().nonnegative().optional()
+}).strict();
+var TurnSchema = z.object({
+  schema: z.literal("session-store/turn@1"),
+  session_id: z.string().min(1),
+  host: z.string().min(1),
+  agent: z.enum(AGENTS),
+  turn_index: z.number().int().nonnegative(),
+  ts: z.string().min(1),
+  role: z.enum(ROLES),
+  text: z.string().default(""),
+  tool_calls: z.array(ToolCallSchema).default([]),
+  usage: UsageSchema.default({}),
+  telemetry: TelemetrySchema.optional(),
+  /** true when secret-scrubbing redacted content in this turn */
+  scrubbed: z.boolean().default(false),
+  /** sha256 pointer when a large tool output was externalized to raw/ */
+  raw_ref: z.string().nullable().default(null),
+  /** verbatim native event for lossless tier-1 resume */
+  raw: z.unknown().optional()
+}).strict();
+var TotalsSchema = z.object({
+  input_tokens: z.number().int().nonnegative().default(0),
+  output_tokens: z.number().int().nonnegative().default(0),
+  cost_usd: z.number().nonnegative().default(0)
+}).strict();
+var NativeRefSchema = z.object({
+  format: z.string(),
+  uuid: z.string()
+}).strict();
+var SessionSchema = z.object({
+  schema: z.literal("session-store/session@1"),
+  session_id: z.string().min(1),
+  host: z.string().min(1),
+  agent: z.enum(AGENTS),
+  project_path: z.string().default(""),
+  git_branch: z.string().optional(),
+  model: z.string().optional(),
+  started_at: z.string().optional(),
+  ended_at: z.string().optional(),
+  turn_count: z.number().int().nonnegative().default(0),
+  tool_call_count: z.number().int().nonnegative().default(0),
+  totals: TotalsSchema.default({}),
+  title: z.string().optional(),
+  labels: z.array(z.string()).default([]),
+  native_ref: NativeRefSchema
+}).strict();
+var SIGNAL_KINDS = [
+  "stuck-loop",
+  "error-recovery",
+  "high-cost-turn",
+  "long-session",
+  "affect-negative",
+  "affect-positive",
+  "tool-heavy",
+  "other"
+];
+var SignalSchema = z.object({
+  kind: z.enum(SIGNAL_KINDS),
+  severity: z.enum(["info", "warn", "critical"]).default("info"),
+  turn_index: z.number().int().nonnegative().optional(),
+  note: z.string().optional()
+}).strict();
+var InsightsSchema = z.object({
+  schema: z.literal("session-store/insights@1"),
+  session_id: z.string().min(1),
+  host: z.string().min(1),
+  generated_at: z.string(),
+  provider: z.string(),
+  topic: z.string().optional(),
+  tags: z.array(z.string()).default([]),
+  signals: z.array(SignalSchema).default([]),
+  summary: z.string().optional()
+}).strict();
+var SCHEMA_VERSIONS = {
+  turn: "session-store/turn@1",
+  session: "session-store/session@1",
+  insights: "session-store/insights@1"
+};
+
+// src/normalize.ts
+var ZERO_USAGE = {
+  input_tokens: 0,
+  output_tokens: 0,
+  cache_read_tokens: 0,
+  cache_write_tokens: 0
+};
+function mapUsage(u) {
+  if (!u || typeof u !== "object") return { ...ZERO_USAGE };
+  const num = (v) => typeof v === "number" && v >= 0 ? Math.floor(v) : 0;
+  return {
+    input_tokens: num(u.input_tokens),
+    output_tokens: num(u.output_tokens),
+    cache_read_tokens: num(u.cache_read_input_tokens ?? u.cache_read_tokens),
+    cache_write_tokens: num(u.cache_creation_input_tokens ?? u.cache_write_tokens)
+  };
+}
+function blocksToText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts = [];
+  for (const block of content) {
+    if (typeof block === "string") {
+      parts.push(block);
+    } else if (block && typeof block === "object") {
+      const b = block;
+      if (b.type === "text" && typeof b.text === "string") parts.push(b.text);
+      else if (b.type === "tool_result") parts.push(toolResultText(b.content));
+    }
+  }
+  return parts.join("\n");
+}
+function toolResultText(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content.map(
+      (c) => c && typeof c === "object" && typeof c.text === "string" ? c.text : typeof c === "string" ? c : JSON.stringify(c)
+    ).join("\n");
+  }
+  return content == null ? "" : JSON.stringify(content);
+}
+function extractToolCalls(content) {
+  if (!Array.isArray(content)) return [];
+  const calls = [];
+  for (const block of content) {
+    if (block && typeof block === "object" && block.type === "tool_use") {
+      const b = block;
+      const call = { name: typeof b.name === "string" ? b.name : "unknown" };
+      if (b.input !== void 0) call.input = b.input;
+      if (typeof b.id === "string") call.id = b.id;
+      calls.push(call);
+    }
+  }
+  return calls;
+}
+function hasToolResult(content) {
+  return Array.isArray(content) && content.some((b) => b && typeof b === "object" && b.type === "tool_result");
+}
+function normalizeClaudeEvent(raw, fallbackTs = "") {
+  if (!raw || typeof raw !== "object") return null;
+  const ev = raw;
+  const ts = typeof ev.timestamp === "string" ? ev.timestamp : fallbackTs;
+  const message = ev.message && typeof ev.message === "object" ? ev.message : void 0;
+  if (ev.type === "assistant" && message) {
+    return {
+      ts,
+      role: "assistant",
+      text: blocksToText(message.content),
+      tool_calls: extractToolCalls(message.content),
+      usage: mapUsage(message.usage),
+      raw
+    };
+  }
+  if (ev.type === "user" && message) {
+    const isTool = hasToolResult(message.content);
+    return {
+      ts,
+      role: isTool ? "tool" : "user",
+      text: blocksToText(message.content),
+      tool_calls: [],
+      usage: { ...ZERO_USAGE },
+      raw
+    };
+  }
+  return null;
+}
+function buildTurn(ev, ctx) {
+  return {
+    schema: SCHEMA_VERSIONS.turn,
+    session_id: ctx.session_id,
+    host: ctx.host,
+    agent: ctx.agent,
+    turn_index: ctx.turn_index,
+    ts: ev.ts,
+    role: ev.role,
+    text: ev.text,
+    tool_calls: ev.tool_calls,
+    usage: ev.usage,
+    scrubbed: false,
+    raw_ref: null,
+    raw: ev.raw
+  };
+}
+function extractClaudeSessionMeta(rawLines) {
+  const meta = {};
+  for (const raw of rawLines) {
+    if (!raw || typeof raw !== "object") continue;
+    const ev = raw;
+    if (typeof ev.sessionId === "string" && !meta.session_id) meta.session_id = ev.sessionId;
+    if (typeof ev.cwd === "string") meta.project_path = ev.cwd;
+    if (typeof ev.gitBranch === "string") meta.git_branch = ev.gitBranch;
+    if (ev.message && typeof ev.message.model === "string") meta.model = ev.message.model;
+    if (ev.type === "ai-title") {
+      const t = ev.title ?? ev.message ?? ev.content;
+      if (typeof t === "string") meta.title = t;
+    }
+    if (typeof ev.timestamp === "string") {
+      if (!meta.started_at) meta.started_at = ev.timestamp;
+      meta.ended_at = ev.timestamp;
+    }
+  }
+  return meta;
+}
+function normalizeClaudeLines(rawLines, ctx) {
+  let idx = ctx.startIndex ?? 0;
+  const turns = [];
+  for (const raw of rawLines) {
+    const norm = normalizeClaudeEvent(raw);
+    if (!norm) continue;
+    turns.push(
+      buildTurn(norm, {
+        session_id: ctx.session_id,
+        host: ctx.host,
+        agent: ctx.agent,
+        turn_index: idx++
+      })
+    );
+  }
+  return { turns, meta: extractClaudeSessionMeta(rawLines) };
+}
+
+// src/validators.ts
+import { zodToJsonSchema } from "zod-to-json-schema";
+var turnJsonSchema = zodToJsonSchema(TurnSchema, "Turn");
+var sessionJsonSchema = zodToJsonSchema(SessionSchema, "Session");
+var insightsJsonSchema = zodToJsonSchema(InsightsSchema, "Insights");
+var parseTurn = (data) => TurnSchema.parse(data);
+var parseSession = (data) => SessionSchema.parse(data);
+var parseInsights = (data) => InsightsSchema.parse(data);
+var safeParseTurn = (data) => TurnSchema.safeParse(data);
+var safeParseSession = (data) => SessionSchema.safeParse(data);
+var safeParseInsights = (data) => InsightsSchema.safeParse(data);
+export {
+  AGENTS,
+  InsightsSchema,
+  NativeRefSchema,
+  ROLES,
+  SCHEMA_VERSIONS,
+  SIGNAL_KINDS,
+  SessionSchema,
+  SignalSchema,
+  TelemetrySchema,
+  ToolCallSchema,
+  TotalsSchema,
+  TurnSchema,
+  UsageSchema,
+  buildTurn,
+  extractClaudeSessionMeta,
+  insightsJsonSchema,
+  normalizeClaudeEvent,
+  normalizeClaudeLines,
+  parseInsights,
+  parseSession,
+  parseTurn,
+  safeParseInsights,
+  safeParseSession,
+  safeParseTurn,
+  sessionJsonSchema,
+  turnJsonSchema
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@unpolarize/code-sessions-schema",
+  "version": "0.1.0",
+  "description": "Canonical wire schema for cross-agent session records (turns, envelopes, insights)",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": ["dist", "src"],
+  "publishConfig": { "access": "public" },
+  "repository": { "type": "git", "url": "git+https://github.com/unpolarize/code-sessions.git", "directory": "packages/schema" },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --out-dir dist"
+  },
+  "dependencies": {
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.23.5"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './schemas';
+export * from './normalize';
+export * from './validators';

package/src/normalize.test.ts

@@ -0,0 +1,122 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import {
+  buildTurn,
+  extractClaudeSessionMeta,
+  normalizeClaudeEvent,
+  normalizeClaudeLines,
+} from './normalize';
+import { parseTurn } from './validators';
+
+const fixturePath = fileURLToPath(
+  new URL('../test/fixtures/claude-session.jsonl', import.meta.url),
+);
+
+function loadFixtureLines(): unknown[] {
+  return readFileSync(fixturePath, 'utf8')
+    .split('\n')
+    .filter((l) => l.trim().length > 0)
+    .map((l) => JSON.parse(l));
+}
+
+describe('normalizeClaudeEvent', () => {
+  it('maps an assistant line to an assistant turn with tool calls and usage', () => {
+    const lines = loadFixtureLines();
+    const assistant = lines[2];
+    const ev = normalizeClaudeEvent(assistant);
+    expect(ev).not.toBeNull();
+    expect(ev!.role).toBe('assistant');
+    expect(ev!.text).toContain("I'll read the file.");
+    expect(ev!.tool_calls).toHaveLength(1);
+    expect(ev!.tool_calls[0]).toMatchObject({ name: 'Read', id: 'tu_1' });
+    expect(ev!.usage).toEqual({
+      input_tokens: 1200,
+      output_tokens: 45,
+      cache_read_tokens: 8000,
+      cache_write_tokens: 100,
+    });
+  });
+
+  it('maps a tool_result user line to a tool turn', () => {
+    const lines = loadFixtureLines();
+    const ev = normalizeClaudeEvent(lines[3]);
+    expect(ev!.role).toBe('tool');
+    expect(ev!.text).toContain('export const foo = 1;');
+  });
+
+  it('maps a plain user line to a user turn', () => {
+    const lines = loadFixtureLines();
+    const ev = normalizeClaudeEvent(lines[0]);
+    expect(ev!.role).toBe('user');
+    expect(ev!.text).toBe('Fix the bug in foo.ts');
+  });
+
+  it('returns null for metadata lines (system, ai-title)', () => {
+    const lines = loadFixtureLines();
+    expect(normalizeClaudeEvent(lines[1])).toBeNull(); // system
+    expect(normalizeClaudeEvent(lines[4])).toBeNull(); // ai-title
+    expect(normalizeClaudeEvent(null)).toBeNull();
+    expect(normalizeClaudeEvent({ type: 'permission-mode' })).toBeNull();
+  });
+});
+
+describe('normalizeClaudeLines', () => {
+  it('produces conversational turns with sequential indices', () => {
+    const lines = loadFixtureLines();
+    const { turns } = normalizeClaudeLines(lines, {
+      session_id: 'sess-abc',
+      host: 'test-host',
+      agent: 'claude-code',
+    });
+    // 1 user + 1 assistant + 1 tool + 1 assistant = 4 (system + ai-title dropped)
+    expect(turns.map((t) => t.role)).toEqual(['user', 'assistant', 'tool', 'assistant']);
+    expect(turns.map((t) => t.turn_index)).toEqual([0, 1, 2, 3]);
+    for (const t of turns) {
+      expect(() => parseTurn(t)).not.toThrow();
+      expect(t.session_id).toBe('sess-abc');
+      expect(t.host).toBe('test-host');
+      expect(t.agent).toBe('claude-code');
+    }
+  });
+
+  it('respects a startIndex for incremental capture', () => {
+    const lines = loadFixtureLines();
+    const { turns } = normalizeClaudeLines(lines.slice(5), {
+      session_id: 'sess-abc',
+      host: 'test-host',
+      agent: 'claude-code',
+      startIndex: 7,
+    });
+    expect(turns).toHaveLength(1);
+    expect(turns[0]!.turn_index).toBe(7);
+    expect(turns[0]!.text).toBe('Fixed it.');
+  });
+});
+
+describe('extractClaudeSessionMeta', () => {
+  it('pulls envelope metadata from a batch of lines', () => {
+    const meta = extractClaudeSessionMeta(loadFixtureLines());
+    expect(meta.session_id).toBe('sess-abc');
+    expect(meta.project_path).toBe('/Users/z/proj');
+    expect(meta.git_branch).toBe('main');
+    expect(meta.model).toBe('claude-opus-4-8');
+    expect(meta.title).toBe('Fix bug in foo.ts');
+    expect(meta.started_at).toBe('2026-06-20T08:00:00Z');
+    expect(meta.ended_at).toBe('2026-06-20T08:00:10Z');
+  });
+});
+
+describe('buildTurn', () => {
+  it('assembles a schema-valid turn from a normalized event', () => {
+    const ev = normalizeClaudeEvent(loadFixtureLines()[0])!;
+    const turn = buildTurn(ev, {
+      session_id: 's',
+      host: 'h',
+      agent: 'claude-code',
+      turn_index: 0,
+    });
+    expect(turn.schema).toBe('session-store/turn@1');
+    expect(() => parseTurn(turn)).not.toThrow();
+  });
+});

package/src/normalize.ts

@@ -0,0 +1,215 @@
+import {
+  SCHEMA_VERSIONS,
+  type AgentKind,
+  type Role,
+  type ToolCall,
+  type Turn,
+  type Usage,
+} from './schemas';
+
+/**
+ * Adapter: Claude Code JSONL events -> canonical turn records.
+ *
+ * Claude writes one JSON object per line. The conversational lines are `user`
+ * and `assistant`; everything else (`ai-title`, `system`, `permission-mode`,
+ * `queue-operation`, `attachment`, `last-prompt`, `summary`) is metadata and
+ * does not become a turn.
+ */
+
+// Native Claude events are loosely typed; we narrow defensively.
+type Raw = Record<string, any>;
+
+export interface NormalizedEvent {
+  ts: string;
+  role: Role;
+  text: string;
+  tool_calls: ToolCall[];
+  usage: Usage;
+  raw: unknown;
+}
+
+export interface BuildTurnContext {
+  session_id: string;
+  host: string;
+  agent: AgentKind;
+  turn_index: number;
+}
+
+const ZERO_USAGE: Usage = {
+  input_tokens: 0,
+  output_tokens: 0,
+  cache_read_tokens: 0,
+  cache_write_tokens: 0,
+};
+
+function mapUsage(u: Raw | undefined): Usage {
+  if (!u || typeof u !== 'object') return { ...ZERO_USAGE };
+  const num = (v: unknown): number => (typeof v === 'number' && v >= 0 ? Math.floor(v) : 0);
+  return {
+    input_tokens: num(u.input_tokens),
+    output_tokens: num(u.output_tokens),
+    cache_read_tokens: num(u.cache_read_input_tokens ?? u.cache_read_tokens),
+    cache_write_tokens: num(u.cache_creation_input_tokens ?? u.cache_write_tokens),
+  };
+}
+
+function blocksToText(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  const parts: string[] = [];
+  for (const block of content) {
+    if (typeof block === 'string') {
+      parts.push(block);
+    } else if (block && typeof block === 'object') {
+      const b = block as Raw;
+      if (b.type === 'text' && typeof b.text === 'string') parts.push(b.text);
+      else if (b.type === 'tool_result') parts.push(toolResultText(b.content));
+    }
+  }
+  return parts.join('\n');
+}
+
+function toolResultText(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((c) =>
+        c && typeof c === 'object' && typeof (c as Raw).text === 'string'
+          ? (c as Raw).text
+          : typeof c === 'string'
+            ? c
+            : JSON.stringify(c),
+      )
+      .join('\n');
+  }
+  return content == null ? '' : JSON.stringify(content);
+}
+
+function extractToolCalls(content: unknown): ToolCall[] {
+  if (!Array.isArray(content)) return [];
+  const calls: ToolCall[] = [];
+  for (const block of content) {
+    if (block && typeof block === 'object' && (block as Raw).type === 'tool_use') {
+      const b = block as Raw;
+      const call: ToolCall = { name: typeof b.name === 'string' ? b.name : 'unknown' };
+      if (b.input !== undefined) call.input = b.input;
+      if (typeof b.id === 'string') call.id = b.id;
+      calls.push(call);
+    }
+  }
+  return calls;
+}
+
+function hasToolResult(content: unknown): boolean {
+  return (
+    Array.isArray(content) &&
+    content.some((b) => b && typeof b === 'object' && (b as Raw).type === 'tool_result')
+  );
+}
+
+/** Map a single native Claude line into a normalized event, or null if it is metadata. */
+export function normalizeClaudeEvent(raw: unknown, fallbackTs = ''): NormalizedEvent | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const ev = raw as Raw;
+  const ts: string = typeof ev.timestamp === 'string' ? ev.timestamp : fallbackTs;
+  const message: Raw | undefined =
+    ev.message && typeof ev.message === 'object' ? ev.message : undefined;
+
+  if (ev.type === 'assistant' && message) {
+    return {
+      ts,
+      role: 'assistant',
+      text: blocksToText(message.content),
+      tool_calls: extractToolCalls(message.content),
+      usage: mapUsage(message.usage),
+      raw,
+    };
+  }
+
+  if (ev.type === 'user' && message) {
+    const isTool = hasToolResult(message.content);
+    return {
+      ts,
+      role: isTool ? 'tool' : 'user',
+      text: blocksToText(message.content),
+      tool_calls: [],
+      usage: { ...ZERO_USAGE },
+      raw,
+    };
+  }
+
+  return null;
+}
+
+/** Assemble a complete, schema-valid Turn from a normalized event + identity context. */
+export function buildTurn(ev: NormalizedEvent, ctx: BuildTurnContext): Turn {
+  return {
+    schema: SCHEMA_VERSIONS.turn,
+    session_id: ctx.session_id,
+    host: ctx.host,
+    agent: ctx.agent,
+    turn_index: ctx.turn_index,
+    ts: ev.ts,
+    role: ev.role,
+    text: ev.text,
+    tool_calls: ev.tool_calls,
+    usage: ev.usage,
+    scrubbed: false,
+    raw_ref: null,
+    raw: ev.raw,
+  };
+}
+
+export 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. */
+export function extractClaudeSessionMeta(rawLines: unknown[]): ClaudeSessionMeta {
+  const meta: ClaudeSessionMeta = {};
+  for (const raw of rawLines) {
+    if (!raw || typeof raw !== 'object') continue;
+    const ev = raw as Raw;
+    if (typeof ev.sessionId === 'string' && !meta.session_id) meta.session_id = ev.sessionId;
+    if (typeof ev.cwd === 'string') meta.project_path = ev.cwd;
+    if (typeof ev.gitBranch === 'string') meta.git_branch = ev.gitBranch;
+    if (ev.message && typeof ev.message.model === 'string') meta.model = ev.message.model;
+    if (ev.type === 'ai-title') {
+      const t = ev.title ?? ev.message ?? ev.content;
+      if (typeof t === 'string') meta.title = t;
+    }
+    if (typeof ev.timestamp === 'string') {
+      if (!meta.started_at) meta.started_at = ev.timestamp;
+      meta.ended_at = ev.timestamp;
+    }
+  }
+  return meta;
+}
+
+/** Convenience: normalize a full batch of lines with sequential turn indices (for tests/backfill). */
+export function normalizeClaudeLines(
+  rawLines: unknown[],
+  ctx: { session_id: string; host: string; agent: AgentKind; startIndex?: number },
+): { turns: Turn[]; meta: ClaudeSessionMeta } {
+  let idx = ctx.startIndex ?? 0;
+  const turns: Turn[] = [];
+  for (const raw of rawLines) {
+    const norm = normalizeClaudeEvent(raw);
+    if (!norm) continue;
+    turns.push(
+      buildTurn(norm, {
+        session_id: ctx.session_id,
+        host: ctx.host,
+        agent: ctx.agent,
+        turn_index: idx++,
+      }),
+    );
+  }
+  return { turns, meta: extractClaudeSessionMeta(rawLines) };
+}