groove-dev 0.27.75 → 0.27.78

package/moe-training/shared/envelope-schema.js

@@ -0,0 +1,220 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import { SUPPORTED_PROVIDERS, MODEL_TIERS } from './constants.js';
+
+export const STEP_TYPES = ['thought', 'action', 'observation', 'correction', 'resolution', 'error', 'coordination'];
+
+const VALID_MODEL_ENGINES = Object.keys(MODEL_TIERS);
+const VALID_COMPLEXITIES = ['light', 'medium', 'heavy'];
+const VALID_OUTCOME_STATUSES = ['SUCCESS', 'CRASH', 'KILLED'];
+const MAX_STEPS_PER_ENVELOPE = 500;
+const MAX_STEP_CONTENT_LENGTH = 10_000;
+const MAX_TOKEN_COUNT = 100_000;
+const MAX_STEP_NUMBER = 50_000;
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+const ONE_HOUR_MS = 60 * 60 * 1000;
+const HEX_32 = /^[0-9a-f]{32}$/;
+const HEX_64 = /^[0-9a-f]{64}$/;
+const MAX_OUTCOME_NUMERIC = 50_000;
+
+export class EnvelopeBuilder {
+  constructor() {
+    this._steps = [];
+  }
+
+  addStep(step) {
+    this._steps.push(step);
+    return this;
+  }
+
+  build(envelopeId, sessionId, chunkSequence, contributorId, metadata) {
+    return {
+      envelope_id: envelopeId,
+      session_id: sessionId,
+      chunk_sequence: chunkSequence,
+      contributor_id: contributorId,
+      attestation: { session_hmac: '', sequence: 0, app_version_hash: '' },
+      metadata,
+      trajectory_log: [...this._steps],
+    };
+  }
+
+  static buildSessionClose(envelopeId, sessionId, outcome) {
+    return {
+      envelope_id: envelopeId,
+      session_id: sessionId,
+      type: 'SESSION_CLOSE',
+      attestation: { session_hmac: '', sequence: 0, app_version_hash: '' },
+      outcome,
+    };
+  }
+}
+
+export function validateEnvelope(envelope) {
+  const errors = [];
+
+  if (!envelope) {
+    return { valid: false, errors: ['Envelope is null or undefined'] };
+  }
+
+  if (envelope.type === 'SESSION_CLOSE') {
+    return validateSessionClose(envelope);
+  }
+
+  if (!envelope.session_id || typeof envelope.session_id !== 'string') {
+    errors.push('Missing or invalid session_id');
+  }
+  if (typeof envelope.chunk_sequence !== 'number') {
+    errors.push('Missing or invalid chunk_sequence');
+  }
+
+  // contributor_id: must be 32-char hex (UUID without dashes)
+  if (!envelope.contributor_id || typeof envelope.contributor_id !== 'string') {
+    errors.push('Missing or invalid contributor_id');
+  } else if (!HEX_32.test(envelope.contributor_id)) {
+    errors.push('contributor_id must be a 32-character hex string');
+  }
+
+  // Attestation validation
+  if (!envelope.attestation || typeof envelope.attestation !== 'object') {
+    errors.push('Missing attestation');
+  } else {
+    if (typeof envelope.attestation.session_hmac !== 'string' || !HEX_64.test(envelope.attestation.session_hmac)) {
+      errors.push('attestation.session_hmac must be exactly 64 hex characters');
+    }
+    if (typeof envelope.attestation.sequence !== 'number' || !Number.isInteger(envelope.attestation.sequence) || envelope.attestation.sequence < 0 || envelope.attestation.sequence > 1_000_000) {
+      errors.push('attestation.sequence must be a non-negative integer, max 1000000');
+    }
+    if (typeof envelope.attestation.app_version_hash !== 'string' || !HEX_64.test(envelope.attestation.app_version_hash)) {
+      errors.push('attestation.app_version_hash must be exactly 64 hex characters');
+    }
+  }
+
+  // Metadata validation
+  if (!envelope.metadata || typeof envelope.metadata !== 'object') {
+    errors.push('Missing metadata');
+  } else {
+    const m = envelope.metadata;
+    if (!m.provider || !SUPPORTED_PROVIDERS.includes(m.provider)) {
+      errors.push(`metadata.provider must be one of: ${SUPPORTED_PROVIDERS.join(', ')}`);
+    }
+    if (!m.model_engine || !VALID_MODEL_ENGINES.includes(m.model_engine)) {
+      errors.push(`metadata.model_engine must be one of: ${VALID_MODEL_ENGINES.join(', ')}`);
+    }
+    if (!m.agent_role || typeof m.agent_role !== 'string' || m.agent_role.length > 50) {
+      errors.push('metadata.agent_role must be a string, max 50 characters');
+    }
+    if (!m.agent_id || typeof m.agent_id !== 'string' || m.agent_id.length > 100) {
+      errors.push('metadata.agent_id must be a string, max 100 characters');
+    }
+    if (m.team_size !== undefined && m.team_size !== null) {
+      if (!Number.isInteger(m.team_size) || m.team_size < 1 || m.team_size > 50) {
+        errors.push('metadata.team_size must be an integer 1-50');
+      }
+    }
+    if (m.task_complexity !== undefined && m.task_complexity !== null) {
+      if (!VALID_COMPLEXITIES.includes(m.task_complexity)) {
+        errors.push('metadata.task_complexity must be light, medium, or heavy');
+      }
+    }
+    if (m.groove_version !== undefined && m.groove_version !== null) {
+      if (typeof m.groove_version !== 'string' || m.groove_version.length > 20) {
+        errors.push('metadata.groove_version must be a string, max 20 characters');
+      }
+    }
+    // session_quality is ignored from client — server derives quality
+  }
+
+  // Trajectory log validation
+  if (!Array.isArray(envelope.trajectory_log)) {
+    errors.push('Missing or invalid trajectory_log');
+  } else {
+    if (envelope.trajectory_log.length > MAX_STEPS_PER_ENVELOPE) {
+      errors.push(`trajectory_log exceeds maximum of ${MAX_STEPS_PER_ENVELOPE} steps (got ${envelope.trajectory_log.length})`);
+    }
+
+    const now = Date.now();
+    const sevenDaysAgo = now - SEVEN_DAYS_MS;
+    const futureLimit = now + ONE_HOUR_MS;
+
+    for (let i = 0; i < Math.min(envelope.trajectory_log.length, MAX_STEPS_PER_ENVELOPE); i++) {
+      const step = envelope.trajectory_log[i];
+      if (!STEP_TYPES.includes(step.type)) {
+        errors.push(`Invalid step type "${step.type}" at index ${i}`);
+      }
+      if (typeof step.step !== 'number' || !Number.isInteger(step.step) || step.step < 0 || step.step > MAX_STEP_NUMBER) {
+        errors.push(`step.step must be a non-negative integer, max ${MAX_STEP_NUMBER} at index ${i}`);
+      }
+      if (typeof step.timestamp !== 'number') {
+        errors.push(`Missing timestamp at index ${i}`);
+      } else {
+        const tsMs = step.timestamp < 1e12 ? step.timestamp * 1000 : step.timestamp;
+        if (tsMs < sevenDaysAgo || tsMs > futureLimit) {
+          errors.push(`Timestamp out of range at index ${i} (must be within last 7 days, max 1 hour in future)`);
+        }
+      }
+      if (step.content !== undefined && typeof step.content === 'string' && step.content.length > MAX_STEP_CONTENT_LENGTH) {
+        errors.push(`step.content exceeds ${MAX_STEP_CONTENT_LENGTH} characters at index ${i}`);
+      }
+      if (step.token_count !== undefined) {
+        if (typeof step.token_count !== 'number' || step.token_count < 0 || step.token_count > MAX_TOKEN_COUNT) {
+          errors.push(`step.token_count must be 0-${MAX_TOKEN_COUNT} at index ${i}`);
+        }
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+function validateSessionClose(envelope) {
+  const errors = [];
+
+  if (!envelope.session_id || typeof envelope.session_id !== 'string') {
+    errors.push('Missing or invalid session_id');
+  }
+  if (envelope.type !== 'SESSION_CLOSE') {
+    errors.push('Invalid type for SESSION_CLOSE envelope');
+  }
+
+  // Attestation validation
+  if (!envelope.attestation || typeof envelope.attestation !== 'object') {
+    errors.push('Missing attestation');
+  } else {
+    if (typeof envelope.attestation.session_hmac !== 'string' || !HEX_64.test(envelope.attestation.session_hmac)) {
+      errors.push('attestation.session_hmac must be exactly 64 hex characters');
+    }
+    if (typeof envelope.attestation.sequence !== 'number' || !Number.isInteger(envelope.attestation.sequence) || envelope.attestation.sequence < 0 || envelope.attestation.sequence > 1_000_000) {
+      errors.push('attestation.sequence must be a non-negative integer, max 1000000');
+    }
+    if (typeof envelope.attestation.app_version_hash !== 'string' || !HEX_64.test(envelope.attestation.app_version_hash)) {
+      errors.push('attestation.app_version_hash must be exactly 64 hex characters');
+    }
+  }
+
+  // Outcome validation
+  if (!envelope.outcome || typeof envelope.outcome !== 'object') {
+    errors.push('Missing outcome');
+  } else {
+    if (!VALID_OUTCOME_STATUSES.includes(envelope.outcome.status)) {
+      errors.push(`outcome.status must be one of: ${VALID_OUTCOME_STATUSES.join(', ')}`);
+    }
+    if (typeof envelope.outcome.total_steps !== 'number' || !Number.isInteger(envelope.outcome.total_steps) || envelope.outcome.total_steps < 0 || envelope.outcome.total_steps > MAX_OUTCOME_NUMERIC) {
+      errors.push('Missing or invalid outcome.total_steps');
+    }
+    if (typeof envelope.outcome.total_chunks !== 'number' || !Number.isInteger(envelope.outcome.total_chunks) || envelope.outcome.total_chunks < 0 || envelope.outcome.total_chunks > MAX_OUTCOME_NUMERIC) {
+      errors.push('Missing or invalid outcome.total_chunks');
+    }
+    const numericFields = ['user_interventions', 'total_tokens', 'duration_seconds', 'files_modified', 'errors_encountered', 'errors_recovered', 'coordination_events'];
+    for (const field of numericFields) {
+      if (envelope.outcome[field] !== undefined) {
+        const v = envelope.outcome[field];
+        if (typeof v !== 'number' || !Number.isInteger(v) || v < 0 || v > MAX_OUTCOME_NUMERIC) {
+          errors.push(`outcome.${field} must be a non-negative integer, max ${MAX_OUTCOME_NUMERIC}`);
+        }
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/moe-training/test/client/consent.test.js

@@ -0,0 +1,121 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { ConsentManager } from '../../client/consent.js';
+
+describe('ConsentManager', () => {
+  let tmpDir, dbPath, manager;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'consent-test-'));
+    dbPath = join(tmpDir, 'consent.db');
+    manager = new ConsentManager(dbPath);
+  });
+
+  afterEach(() => {
+    manager.close();
+    rmSync(tmpDir, { recursive: true });
+  });
+
+  it('opt in then isOptedIn returns true', () => {
+    manager.recordConsent('user1', true, '1.0');
+    assert.equal(manager.isOptedIn('user1'), true);
+  });
+
+  it('opt out then isOptedIn returns false', () => {
+    manager.recordConsent('user1', true, '1.0');
+    manager.revokeConsent('user1');
+    assert.equal(manager.isOptedIn('user1'), false);
+  });
+
+  it('no consent record returns false', () => {
+    assert.equal(manager.isOptedIn('nonexistent'), false);
+  });
+
+  it('version mismatch returns false', () => {
+    manager.recordConsent('user1', true, '0.9');
+    assert.equal(manager.isOptedIn('user1'), false);
+  });
+
+  it('getOptedInCount counts correctly', () => {
+    manager.recordConsent('user1', true, '1.0');
+    manager.recordConsent('user2', true, '1.0');
+    manager.recordConsent('user3', false, '1.0');
+    assert.equal(manager.getOptedInCount(), 2);
+  });
+
+  it('getConsentHistory returns all records', () => {
+    manager.recordConsent('user1', true, '1.0', { source: 'ui' });
+    manager.revokeConsent('user1');
+    const history = manager.getConsentHistory('user1');
+    assert.equal(history.length, 2);
+    assert.equal(history[0].opted_in, true);
+    assert.deepEqual(history[0].metadata, { source: 'ui' });
+    assert.equal(history[1].opted_in, false);
+  });
+});
+
+describe('ConsentManager.getOrCreateUserId', () => {
+  let tmpDir, userIdPath;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'userid-test-'));
+    userIdPath = join(tmpDir, 'user_id');
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true });
+  });
+
+  it('creates user_id file and returns id', () => {
+    const id = ConsentManager.getOrCreateUserId(userIdPath);
+    assert.ok(id.length > 0);
+    assert.ok(existsSync(userIdPath));
+  });
+
+  it('returns same id on second call', () => {
+    const id1 = ConsentManager.getOrCreateUserId(userIdPath);
+    const id2 = ConsentManager.getOrCreateUserId(userIdPath);
+    assert.equal(id1, id2);
+  });
+});
+
+describe('ConsentManager.isCaptureEnabled', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'capture-test-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true });
+  });
+
+  it('returns false when no user_id file exists', () => {
+    const result = ConsentManager.isCaptureEnabled(join(tmpDir, 'no_file'), join(tmpDir, 'c.db'));
+    assert.equal(result, false);
+  });
+
+  it('returns false when user not opted in', () => {
+    const uidPath = join(tmpDir, 'user_id');
+    const uid = ConsentManager.getOrCreateUserId(uidPath);
+    const dbPath = join(tmpDir, 'consent.db');
+    const result = ConsentManager.isCaptureEnabled(uidPath, dbPath);
+    assert.equal(result, false);
+  });
+
+  it('returns true when user is opted in', () => {
+    const uidPath = join(tmpDir, 'user_id');
+    const uid = ConsentManager.getOrCreateUserId(uidPath);
+    const dbPath = join(tmpDir, 'consent.db');
+    const mgr = new ConsentManager(dbPath);
+    mgr.recordConsent(uid, true, '1.0');
+    mgr.close();
+    const result = ConsentManager.isCaptureEnabled(uidPath, dbPath);
+    assert.equal(result, true);
+  });
+});

package/moe-training/test/client/envelope-builder.test.js

@@ -0,0 +1,107 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { EnvelopeBuilder } from '../../client/envelope-builder.js';
+import { CHUNK_SIZE } from '../../shared/constants.js';
+
+const metadata = {
+  model_engine: 'claude-opus-4-6',
+  provider: 'claude-code',
+  agent_role: 'backend',
+  agent_id: 'backend-1',
+  task_complexity: 'medium',
+  team_size: 2,
+  session_quality: 80,
+  groove_version: '0.27.0',
+};
+
+describe('EnvelopeBuilder', () => {
+  it('adding steps below CHUNK_SIZE returns null', () => {
+    const builder = new EnvelopeBuilder('sess_1', 'user_1', metadata);
+    for (let i = 0; i < CHUNK_SIZE - 1; i++) {
+      const result = builder.addStep({ step: i + 1, type: 'thought', timestamp: Date.now() / 1000 });
+      assert.equal(result, null);
+    }
+  });
+
+  it('adding step that hits CHUNK_SIZE returns envelope', () => {
+    const builder = new EnvelopeBuilder('sess_1', 'user_1', metadata);
+    let envelope = null;
+    for (let i = 0; i < CHUNK_SIZE; i++) {
+      envelope = builder.addStep({ step: i + 1, type: 'thought', timestamp: Date.now() / 1000 });
+    }
+    assert.ok(envelope);
+    assert.equal(envelope.trajectory_log.length, CHUNK_SIZE);
+    assert.equal(envelope.session_id, 'sess_1');
+    assert.equal(envelope.contributor_id, 'user_1');
+    assert.ok(envelope.envelope_id.startsWith('env_'));
+    assert.equal(envelope.chunk_sequence, 0);
+  });
+
+  it('flush returns remaining steps', () => {
+    const builder = new EnvelopeBuilder('sess_1', 'user_1', metadata);
+    builder.addStep({ step: 1, type: 'thought', timestamp: 123 });
+    builder.addStep({ step: 2, type: 'action', timestamp: 124 });
+    const envelope = builder.flush();
+    assert.ok(envelope);
+    assert.equal(envelope.trajectory_log.length, 2);
+  });
+
+  it('flush returns null when buffer is empty', () => {
+    const builder = new EnvelopeBuilder('sess_1', 'user_1', metadata);
+    assert.equal(builder.flush(), null);
+  });
+
+  it('SESSION_CLOSE includes outcome data', () => {
+    const builder = new EnvelopeBuilder('sess_1', 'user_1', metadata);
+    const outcome = {
+      status: 'SUCCESS',
+      user_interventions: 1,
+      total_steps: 50,
+      total_chunks: 1,
+      total_tokens: 5000,
+      duration_seconds: 120,
+      files_modified: 3,
+      errors_encountered: 1,
+      errors_recovered: 1,
+      coordination_events: 0,
+    };
+    const close = builder.buildSessionClose(outcome);
+    assert.ok(close.envelope_id.startsWith('env_'));
+    assert.equal(close.session_id, 'sess_1');
+    assert.equal(close.type, 'SESSION_CLOSE');
+    assert.deepEqual(close.outcome, outcome);
+  });
+
+  it('truncates step content at 10000 characters', () => {
+    const builder = new EnvelopeBuilder('sess_1', 'user_1', metadata);
+    const longContent = 'x'.repeat(15_000);
+    builder.addStep({ step: 1, type: 'thought', timestamp: 123, content: longContent });
+    const envelope = builder.flush();
+    assert.equal(envelope.trajectory_log[0].content.length, 10_000);
+  });
+
+  it('caps token_count at 100000', () => {
+    const builder = new EnvelopeBuilder('sess_1', 'user_1', metadata);
+    builder.addStep({ step: 1, type: 'thought', timestamp: 123, token_count: 999_999 });
+    const envelope = builder.flush();
+    assert.equal(envelope.trajectory_log[0].token_count, 100_000);
+  });
+
+  it('chunk sequence increments correctly', () => {
+    const builder = new EnvelopeBuilder('sess_1', 'user_1', metadata);
+    let first = null;
+    let second = null;
+
+    for (let i = 0; i < CHUNK_SIZE; i++) {
+      first = builder.addStep({ step: i + 1, type: 'thought', timestamp: Date.now() / 1000 }) || first;
+    }
+    for (let i = 0; i < CHUNK_SIZE; i++) {
+      second = builder.addStep({ step: CHUNK_SIZE + i + 1, type: 'action', timestamp: Date.now() / 1000 }) || second;
+    }
+
+    assert.equal(first.chunk_sequence, 0);
+    assert.equal(second.chunk_sequence, 1);
+  });
+});

package/moe-training/test/client/parsers/claude-code.test.js

@@ -0,0 +1,119 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { ClaudeCodeParser } from '../../../client/parsers/claude-code.js';
+
+describe('ClaudeCodeParser', () => {
+  it('parses assistant message as thought', () => {
+    const parser = new ClaudeCodeParser();
+    const event = {
+      type: 'assistant',
+      message: {
+        content: [{ type: 'text', text: 'I need to fix the bug' }],
+        usage: { input_tokens: 100, output_tokens: 50 },
+      },
+    };
+    const result = parser.parseEvent(event);
+    assert.equal(result.type, 'thought');
+    assert.equal(result.content, 'I need to fix the bug');
+    assert.equal(result.token_count, 50);
+  });
+
+  it('parses tool_use block as action', () => {
+    const parser = new ClaudeCodeParser();
+    const event = {
+      type: 'assistant',
+      message: {
+        content: [{ type: 'tool_use', id: 'tu_1', name: 'Read', input: { file_path: '/test.js' } }],
+        usage: { output_tokens: 10 },
+      },
+    };
+    const result = parser.parseEvent(event);
+    assert.equal(result.type, 'action');
+    assert.equal(result.tool, 'Read');
+    assert.deepEqual(result.arguments, { file_path: '/test.js' });
+  });
+
+  it('parses tool_result as observation', () => {
+    const parser = new ClaudeCodeParser();
+    // First register a tool use
+    parser.parseEvent({
+      type: 'assistant',
+      message: {
+        content: [{ type: 'tool_use', id: 'tu_2', name: 'Read', input: {} }],
+        usage: {},
+      },
+    });
+    // Then parse result
+    const event = {
+      type: 'assistant',
+      message: {
+        content: [{ type: 'tool_result', tool_use_id: 'tu_2', content: 'file contents here', is_error: false }],
+        usage: {},
+      },
+    };
+    const result = parser.parseEvent(event);
+    assert.equal(result.type, 'observation');
+    assert.equal(result.content, 'file contents here');
+    assert.equal(result.is_error, false);
+  });
+
+  it('parses error tool_result as error', () => {
+    const parser = new ClaudeCodeParser();
+    const event = {
+      type: 'assistant',
+      message: {
+        content: [{ type: 'tool_result', tool_use_id: 'tu_3', content: 'Permission denied', is_error: true }],
+        usage: {},
+      },
+    };
+    const result = parser.parseEvent(event);
+    assert.equal(result.type, 'error');
+    assert.equal(result.is_error, true);
+  });
+
+  it('parses result event as resolution', () => {
+    const parser = new ClaudeCodeParser();
+    const event = { type: 'result', result: 'Task completed successfully', total_tokens_used: 500 };
+    const result = parser.parseEvent(event);
+    assert.equal(result.type, 'resolution');
+    assert.equal(result.content, 'Task completed successfully');
+    assert.equal(result.token_count, 500);
+  });
+
+  it('extracts tokens from assistant event', () => {
+    const parser = new ClaudeCodeParser();
+    const event = {
+      type: 'assistant',
+      message: {
+        usage: {
+          input_tokens: 100,
+          output_tokens: 50,
+          cache_read_input_tokens: 30,
+          cache_creation_input_tokens: 10,
+        },
+      },
+    };
+    const tokens = parser.extractTokens(event);
+    assert.deepEqual(tokens, { input: 100, output: 50, cacheRead: 30, cacheCreation: 10 });
+  });
+
+  it('extracts session id', () => {
+    const parser = new ClaudeCodeParser();
+    assert.equal(parser.extractSessionId({ session_id: 'sess-abc' }), 'sess-abc');
+    assert.equal(parser.extractSessionId({}), null);
+  });
+
+  it('extracts model from assistant event', () => {
+    const parser = new ClaudeCodeParser();
+    assert.equal(parser.extractModel({ type: 'assistant', message: { model: 'claude-opus-4-6' } }), 'claude-opus-4-6');
+    assert.equal(parser.extractModel({ type: 'result' }), null);
+  });
+
+  it('returns null for unknown event types', () => {
+    const parser = new ClaudeCodeParser();
+    assert.equal(parser.parseEvent({ type: 'system' }), null);
+    assert.equal(parser.parseEvent(null), null);
+  });
+});

package/moe-training/test/client/parsers/codex.test.js

@@ -0,0 +1,83 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { CodexParser } from '../../../client/parsers/codex.js';
+
+describe('CodexParser', () => {
+  it('parses item.started agent_message as thought', () => {
+    const parser = new CodexParser();
+    const result = parser.parseEvent({
+      type: 'item.started',
+      item: { type: 'agent_message', text: 'Let me analyze this' },
+    });
+    assert.equal(result.type, 'thought');
+    assert.equal(result.content, 'Let me analyze this');
+  });
+
+  it('parses item.started command_execution as action', () => {
+    const parser = new CodexParser();
+    const result = parser.parseEvent({
+      type: 'item.started',
+      item: { type: 'command_execution', command: 'ls -la' },
+    });
+    assert.equal(result.type, 'action');
+    assert.equal(result.tool, 'command_execution');
+    assert.deepEqual(result.arguments, { command: 'ls -la' });
+  });
+
+  it('parses item.started file_edit as action', () => {
+    const parser = new CodexParser();
+    const result = parser.parseEvent({
+      type: 'item.started',
+      item: { type: 'file_edit', path: '/src/app.js' },
+    });
+    assert.equal(result.type, 'action');
+    assert.equal(result.tool, 'file_edit');
+  });
+
+  it('parses item.completed command_execution as observation', () => {
+    const parser = new CodexParser();
+    const result = parser.parseEvent({
+      type: 'item.completed',
+      item: { type: 'command_execution', aggregated_output: 'file1\nfile2', exit_code: 0 },
+    });
+    assert.equal(result.type, 'observation');
+    assert.equal(result.content, 'file1\nfile2');
+  });
+
+  it('parses item.completed with error exit code as error', () => {
+    const parser = new CodexParser();
+    const result = parser.parseEvent({
+      type: 'item.completed',
+      item: { type: 'command_execution', aggregated_output: 'ENOENT', exit_code: 1 },
+    });
+    assert.equal(result.type, 'error');
+  });
+
+  it('parses turn.completed as resolution', () => {
+    const parser = new CodexParser();
+    const result = parser.parseEvent({ type: 'turn.completed' });
+    assert.equal(result.type, 'resolution');
+  });
+
+  it('extracts tokens from usage', () => {
+    const parser = new CodexParser();
+    const tokens = parser.extractTokens({
+      type: 'item.completed',
+      usage: { input_tokens: 200, output_tokens: 100 },
+    });
+    assert.deepEqual(tokens, { input: 200, output: 100, cacheRead: 0, cacheCreation: 0 });
+  });
+
+  it('extracts session id from thread.started', () => {
+    const parser = new CodexParser();
+    assert.equal(parser.extractSessionId({ type: 'thread.started', thread_id: 'th_123' }), 'th_123');
+    assert.equal(parser.extractSessionId({ type: 'item.started' }), null);
+  });
+
+  it('returns null for unknown event types', () => {
+    const parser = new CodexParser();
+    assert.equal(parser.parseEvent({ type: 'unknown.event' }), null);
+  });
+});