tlc-claude-code 2.4.3 → 2.4.5

package/server/lib/capture/codex-event-parser.js

@@ -0,0 +1,76 @@
+function parseCodexEventLine(line) {
+  if (typeof line !== 'string' || line.trim() === '') {
+    return null;
+  }
+
+  try {
+    return JSON.parse(line);
+  } catch (_) {
+    return null;
+  }
+}
+
+function extractThreadId(event) {
+  if (
+    event &&
+    event.type === 'thread.started' &&
+    typeof event.thread_id === 'string' &&
+    event.thread_id.trim() !== ''
+  ) {
+    return event.thread_id;
+  }
+
+  return null;
+}
+
+function extractAgentMessages(event) {
+  if (!event || event.type !== 'agent_message') {
+    return [];
+  }
+
+  const items = Array.isArray(event.message && event.message.items)
+    ? event.message.items
+    : Array.isArray(event.items)
+      ? event.items
+      : [];
+
+  return items
+    .filter((item) => item && item.type === 'text' && typeof item.text === 'string' && item.text.trim() !== '')
+    .map((item) => item.text);
+}
+
+function parseCodexEvents(jsonStream) {
+  const lines = typeof jsonStream === 'string' ? jsonStream.split('\n') : [];
+  const events = [];
+  const agentMessages = [];
+  let threadId = null;
+
+  for (const line of lines) {
+    const event = parseCodexEventLine(line);
+    if (!event) {
+      continue;
+    }
+
+    events.push(event);
+
+    const nextThreadId = extractThreadId(event);
+    if (nextThreadId) {
+      threadId = nextThreadId;
+    }
+
+    agentMessages.push(...extractAgentMessages(event));
+  }
+
+  return {
+    threadId,
+    agentMessages,
+    events,
+  };
+}
+
+module.exports = {
+  extractAgentMessages,
+  extractThreadId,
+  parseCodexEventLine,
+  parseCodexEvents,
+};

package/server/lib/capture/codex-event-parser.test.js

@@ -0,0 +1,83 @@
+import { describe, it, expect } from 'vitest';
+
+import { parseCodexEvents } from './codex-event-parser.js';
+
+describe('capture/codex-event-parser', () => {
+  it('extracts threadId from thread.started events', () => {
+    const result = parseCodexEvents([
+      '{"type":"status","message":"booting"}',
+      '{"type":"thread.started","thread_id":"thread_123"}',
+    ].join('\n'));
+
+    expect(result.threadId).toBe('thread_123');
+  });
+
+  it('extracts text from agent_message item arrays', () => {
+    const result = parseCodexEvents([
+      JSON.stringify({
+        type: 'agent_message',
+        message: {
+          items: [
+            { type: 'text', text: 'First message' },
+            { type: 'image', url: 'ignored' },
+            { type: 'text', text: 'Second message' },
+          ],
+        },
+      }),
+    ].join('\n'));
+
+    expect(result.agentMessages).toEqual(['First message', 'Second message']);
+  });
+
+  it('preserves all parsed JSON events while skipping malformed lines', () => {
+    const result = parseCodexEvents([
+      '{"type":"status","message":"booting"}',
+      'not-json',
+      '{"type":"thread.started","thread_id":"thread_999"}',
+    ].join('\n'));
+
+    expect(result.events).toEqual([
+      { type: 'status', message: 'booting' },
+      { type: 'thread.started', thread_id: 'thread_999' },
+    ]);
+  });
+
+  it('returns null threadId when no thread.started event exists', () => {
+    const result = parseCodexEvents('{"type":"status","message":"booting"}\n');
+
+    expect(result.threadId).toBeNull();
+  });
+
+  it('ignores blank lines and non-agent_message events', () => {
+    const result = parseCodexEvents([
+      '',
+      '{"type":"status","message":"booting"}',
+      '',
+      '{"type":"message.delta","delta":"partial"}',
+      '',
+    ].join('\n'));
+
+    expect(result.agentMessages).toEqual([]);
+    expect(result.events).toEqual([
+      { type: 'status', message: 'booting' },
+      { type: 'message.delta', delta: 'partial' },
+    ]);
+  });
+
+  it('handles missing or non-string agent message text safely', () => {
+    const result = parseCodexEvents([
+      JSON.stringify({
+        type: 'agent_message',
+        message: {
+          items: [
+            { type: 'text', text: '' },
+            { type: 'text', text: 42 },
+            { type: 'text', text: 'usable' },
+          ],
+        },
+      }),
+    ].join('\n'));
+
+    expect(result.agentMessages).toEqual(['usable']);
+  });
+});

package/server/lib/capture/ensure-ready.js

@@ -0,0 +1,56 @@
+const path = require('path');
+
+const REQUIRED_DIRECTORIES = [
+  path.join('.tlc', 'memory', 'team', 'decisions'),
+  path.join('.tlc', 'memory', 'team', 'gotchas'),
+  path.join('.tlc', 'memory', '.local', 'sessions'),
+];
+
+const REQUIRED_GITKEEPS = [
+  path.join('.tlc', 'memory', 'team', 'decisions', '.gitkeep'),
+  path.join('.tlc', 'memory', 'team', 'gotchas', '.gitkeep'),
+];
+
+function ensureDirectory(projectDir, relativePath, fs, created, existing) {
+  const fullPath = path.join(projectDir, relativePath);
+
+  if (fs.existsSync(fullPath)) {
+    existing.push(relativePath);
+    return;
+  }
+
+  fs.mkdirSync(fullPath, { recursive: true });
+  created.push(relativePath);
+}
+
+function ensureFile(projectDir, relativePath, fs, created, existing) {
+  const fullPath = path.join(projectDir, relativePath);
+
+  if (fs.existsSync(fullPath)) {
+    existing.push(relativePath);
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, '');
+  created.push(relativePath);
+}
+
+function ensureMemoryReady(projectDir, { fs = require('fs') } = {}) {
+  const created = [];
+  const existing = [];
+
+  for (const relativePath of REQUIRED_DIRECTORIES) {
+    ensureDirectory(projectDir, relativePath, fs, created, existing);
+  }
+
+  for (const relativePath of REQUIRED_GITKEEPS) {
+    ensureFile(projectDir, relativePath, fs, created, existing);
+  }
+
+  return { created, existing };
+}
+
+module.exports = {
+  ensureMemoryReady,
+};

package/server/lib/capture/ensure-ready.test.js

@@ -0,0 +1,135 @@
+import { describe, it, beforeEach, afterEach, expect, vi } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+const TARGETS = [
+  path.join('.tlc', 'memory', 'team', 'decisions'),
+  path.join('.tlc', 'memory', 'team', 'gotchas'),
+  path.join('.tlc', 'memory', '.local', 'sessions'),
+];
+
+const GITKEEPS = [
+  path.join('.tlc', 'memory', 'team', 'decisions', '.gitkeep'),
+  path.join('.tlc', 'memory', 'team', 'gotchas', '.gitkeep'),
+];
+
+describe('ensureMemoryReady', () => {
+  let projectDir;
+  let ensureMemoryReady;
+
+  beforeEach(async () => {
+    projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-ensure-ready-test-'));
+    ({ ensureMemoryReady } = await import('./ensure-ready.js'));
+  });
+
+  afterEach(() => {
+    vi.resetModules();
+    fs.rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('creates the canonical memory directories and team .gitkeep files', () => {
+    const result = ensureMemoryReady(projectDir);
+
+    expect(result.created.slice().sort()).toEqual([...TARGETS, ...GITKEEPS].sort());
+    expect(result.existing).toEqual([]);
+
+    for (const relativePath of TARGETS) {
+      expect(fs.existsSync(path.join(projectDir, relativePath))).toBe(true);
+    }
+
+    for (const relativePath of GITKEEPS) {
+      expect(fs.existsSync(path.join(projectDir, relativePath))).toBe(true);
+      expect(fs.readFileSync(path.join(projectDir, relativePath), 'utf8')).toBe('');
+    }
+  });
+
+  it('is idempotent across repeated calls', () => {
+    const first = ensureMemoryReady(projectDir);
+    const second = ensureMemoryReady(projectDir);
+
+    expect(first.created.slice().sort()).toEqual([...TARGETS, ...GITKEEPS].sort());
+    expect(second.created).toEqual([]);
+    expect(second.existing.slice().sort()).toEqual([...TARGETS, ...GITKEEPS].sort());
+  });
+
+  it('reports pre-existing directories and .gitkeep files separately from new ones', () => {
+    fs.mkdirSync(path.join(projectDir, '.tlc', 'memory', 'team', 'decisions'), { recursive: true });
+    fs.writeFileSync(path.join(projectDir, '.tlc', 'memory', 'team', 'decisions', '.gitkeep'), '');
+    fs.mkdirSync(path.join(projectDir, '.tlc', 'memory', '.local', 'sessions'), { recursive: true });
+
+    const result = ensureMemoryReady(projectDir);
+
+    expect(result.created.slice().sort()).toEqual([
+      path.join('.tlc', 'memory', 'team', 'gotchas'),
+      path.join('.tlc', 'memory', 'team', 'gotchas', '.gitkeep'),
+    ].sort());
+    expect(result.existing.slice().sort()).toEqual([
+      path.join('.tlc', 'memory', 'team', 'decisions'),
+      path.join('.tlc', 'memory', 'team', 'decisions', '.gitkeep'),
+      path.join('.tlc', 'memory', '.local', 'sessions'),
+    ].sort());
+  });
+
+  it('creates missing .gitkeep files when team directories already exist', () => {
+    fs.mkdirSync(path.join(projectDir, '.tlc', 'memory', 'team', 'decisions'), { recursive: true });
+    fs.mkdirSync(path.join(projectDir, '.tlc', 'memory', 'team', 'gotchas'), { recursive: true });
+    fs.mkdirSync(path.join(projectDir, '.tlc', 'memory', '.local', 'sessions'), { recursive: true });
+
+    const result = ensureMemoryReady(projectDir);
+
+    expect(result.created.slice().sort()).toEqual(GITKEEPS.slice().sort());
+    expect(result.existing.slice().sort()).toEqual(TARGETS.slice().sort());
+  });
+
+  it('does not overwrite existing .gitkeep content', () => {
+    const decisionsGitkeep = path.join(projectDir, '.tlc', 'memory', 'team', 'decisions', '.gitkeep');
+    const gotchasGitkeep = path.join(projectDir, '.tlc', 'memory', 'team', 'gotchas', '.gitkeep');
+
+    fs.mkdirSync(path.dirname(decisionsGitkeep), { recursive: true });
+    fs.mkdirSync(path.dirname(gotchasGitkeep), { recursive: true });
+    fs.mkdirSync(path.join(projectDir, '.tlc', 'memory', '.local', 'sessions'), { recursive: true });
+    fs.writeFileSync(decisionsGitkeep, 'keep me\n');
+    fs.writeFileSync(gotchasGitkeep, 'still here\n');
+
+    const result = ensureMemoryReady(projectDir);
+
+    expect(result.created).toEqual([]);
+    expect(result.existing.slice().sort()).toEqual([...TARGETS, ...GITKEEPS].sort());
+    expect(fs.readFileSync(decisionsGitkeep, 'utf8')).toBe('keep me\n');
+    expect(fs.readFileSync(gotchasGitkeep, 'utf8')).toBe('still here\n');
+  });
+
+  it('creates parent directories recursively from an empty project root', () => {
+    ensureMemoryReady(projectDir);
+
+    expect(fs.existsSync(path.join(projectDir, '.tlc'))).toBe(true);
+    expect(fs.existsSync(path.join(projectDir, '.tlc', 'memory', 'team'))).toBe(true);
+    expect(fs.existsSync(path.join(projectDir, '.tlc', 'memory', '.local'))).toBe(true);
+  });
+
+  it('supports injected fs implementations', () => {
+    const injectedFs = {
+      ...fs,
+      mkdirSync: vi.fn(fs.mkdirSync),
+      writeFileSync: vi.fn(fs.writeFileSync),
+      existsSync: vi.fn(fs.existsSync),
+    };
+
+    const result = ensureMemoryReady(projectDir, { fs: injectedFs });
+
+    expect(result.created.slice().sort()).toEqual([...TARGETS, ...GITKEEPS].sort());
+    expect(injectedFs.mkdirSync).toHaveBeenCalled();
+    expect(injectedFs.writeFileSync).toHaveBeenCalledTimes(2);
+  });
+
+  it('handles partially initialized local memory trees', () => {
+    fs.mkdirSync(path.join(projectDir, '.tlc', 'memory', '.local'), { recursive: true });
+
+    const result = ensureMemoryReady(projectDir);
+
+    expect(result.created.slice().sort()).toEqual([...TARGETS, ...GITKEEPS].sort());
+    expect(result.existing).toEqual([]);
+    expect(fs.existsSync(path.join(projectDir, '.tlc', 'memory', '.local', 'sessions'))).toBe(true);
+  });
+});

package/server/lib/capture/envelope.js

@@ -0,0 +1,77 @@
+const crypto = require('crypto');
+
+function normalizeMessage(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+
+  return value.trim();
+}
+
+function createEnvelope({
+  provider,
+  source,
+  taskName,
+  threadId,
+  userMessage,
+  assistantMessage,
+  timestamp,
+}) {
+  const normalizedUserMessage = normalizeMessage(userMessage);
+  const normalizedAssistantMessage = normalizeMessage(assistantMessage);
+  const parts = [normalizedUserMessage, normalizedAssistantMessage].filter(Boolean);
+
+  if (parts.length === 0) {
+    throw new Error('createEnvelope requires at least one non-empty message');
+  }
+
+  return {
+    provider,
+    source,
+    taskName,
+    threadId,
+    text: parts.join('\n\n'),
+    timestamp: typeof timestamp === 'string' ? timestamp : new Date().toISOString(),
+    metadata: {
+      userMessage,
+      assistantMessage,
+    },
+  };
+}
+
+function validateEnvelope(obj) {
+  const errors = [];
+  const value = obj || {};
+
+  if (typeof value.provider !== 'string') {
+    errors.push('provider must be a string');
+  }
+
+  if (typeof value.text !== 'string' || value.text.trim() === '') {
+    errors.push('text must be a non-empty string');
+  }
+
+  if (typeof value.timestamp !== 'string') {
+    errors.push('timestamp must be a string');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+function idempotencyKey(envelope) {
+  const provider = typeof envelope.provider === 'string' ? envelope.provider : '';
+  const timestamp = typeof envelope.timestamp === 'string' ? envelope.timestamp : '';
+  const text = typeof envelope.text === 'string' ? envelope.text : '';
+  const payload = provider + timestamp + text.slice(0, 100);
+
+  return crypto.createHash('sha256').update(payload).digest('hex');
+}
+
+module.exports = {
+  createEnvelope,
+  validateEnvelope,
+  idempotencyKey,
+};

package/server/lib/capture/envelope.test.js

@@ -0,0 +1,169 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import crypto from 'crypto';
+
+describe('capture/envelope', () => {
+  let envelopeModule;
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-03-28T10:11:12.000Z'));
+    envelopeModule = await import('./envelope.js');
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.resetModules();
+  });
+
+  it('creates a normalized envelope with combined text and metadata', () => {
+    const envelope = envelopeModule.createEnvelope({
+      provider: 'openai',
+      source: 'chat',
+      taskName: 'capture',
+      threadId: 'thread-1',
+      userMessage: 'User asks a question',
+      assistantMessage: 'Assistant answers it',
+      timestamp: '2026-03-27T00:00:00.000Z',
+    });
+
+    expect(envelope).toEqual({
+      provider: 'openai',
+      source: 'chat',
+      taskName: 'capture',
+      threadId: 'thread-1',
+      text: 'User asks a question\n\nAssistant answers it',
+      timestamp: '2026-03-27T00:00:00.000Z',
+      metadata: {
+        userMessage: 'User asks a question',
+        assistantMessage: 'Assistant answers it',
+      },
+    });
+  });
+
+  it('trims both messages before combining them', () => {
+    const envelope = envelopeModule.createEnvelope({
+      provider: 'openai',
+      userMessage: '  hello  ',
+      assistantMessage: '\n world \n',
+    });
+
+    expect(envelope.text).toBe('hello\n\nworld');
+    expect(envelope.metadata).toEqual({
+      userMessage: '  hello  ',
+      assistantMessage: '\n world \n',
+    });
+  });
+
+  it('supports an envelope with only a user message', () => {
+    const envelope = envelopeModule.createEnvelope({
+      provider: 'openai',
+      userMessage: 'Only user content',
+      assistantMessage: '   ',
+    });
+
+    expect(envelope.text).toBe('Only user content');
+  });
+
+  it('supports an envelope with only an assistant message', () => {
+    const envelope = envelopeModule.createEnvelope({
+      provider: 'openai',
+      userMessage: '',
+      assistantMessage: 'Only assistant content',
+    });
+
+    expect(envelope.text).toBe('Only assistant content');
+  });
+
+  it('defaults timestamp to the current ISO string', () => {
+    const envelope = envelopeModule.createEnvelope({
+      provider: 'openai',
+      userMessage: 'hello',
+      assistantMessage: 'world',
+    });
+
+    expect(envelope.timestamp).toBe('2026-03-28T10:11:12.000Z');
+  });
+
+  it('throws when both messages are empty after trimming', () => {
+    expect(() => envelopeModule.createEnvelope({
+      provider: 'openai',
+      userMessage: '   ',
+      assistantMessage: '\n\t',
+    })).toThrow(/at least one/i);
+  });
+
+  it('validateEnvelope returns valid for a complete minimal envelope', () => {
+    expect(envelopeModule.validateEnvelope({
+      provider: 'openai',
+      text: 'combined text',
+      timestamp: '2026-03-28T10:11:12.000Z',
+    })).toEqual({
+      valid: true,
+      errors: [],
+    });
+  });
+
+  it('validateEnvelope reports missing required fields', () => {
+    const result = envelopeModule.validateEnvelope({
+      provider: 42,
+      text: '   ',
+      timestamp: null,
+    });
+
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('provider must be a string');
+    expect(result.errors).toContain('text must be a non-empty string');
+    expect(result.errors).toContain('timestamp must be a string');
+  });
+
+  it('validateEnvelope allows optional fields and metadata', () => {
+    const result = envelopeModule.validateEnvelope({
+      provider: 'openai',
+      source: 'cli',
+      taskName: 'summarize',
+      threadId: 'thread-9',
+      text: 'combined text',
+      timestamp: '2026-03-28T10:11:12.000Z',
+      metadata: {
+        userMessage: 'u',
+        assistantMessage: 'a',
+      },
+    });
+
+    expect(result).toEqual({
+      valid: true,
+      errors: [],
+    });
+  });
+
+  it('creates a stable idempotency key from provider timestamp and truncated text', () => {
+    const envelope = {
+      provider: 'openai',
+      timestamp: '2026-03-28T10:11:12.000Z',
+      text: 'x'.repeat(120),
+    };
+
+    const expected = crypto
+      .createHash('sha256')
+      .update(`openai2026-03-28T10:11:12.000Z${'x'.repeat(100)}`)
+      .digest('hex');
+
+    expect(envelopeModule.idempotencyKey(envelope)).toBe(expected);
+  });
+
+  it('idempotency key ignores text beyond the first 100 characters', () => {
+    const prefix = 'p'.repeat(100);
+    const first = envelopeModule.idempotencyKey({
+      provider: 'openai',
+      timestamp: '2026-03-28T10:11:12.000Z',
+      text: `${prefix}AAA`,
+    });
+    const second = envelopeModule.idempotencyKey({
+      provider: 'openai',
+      timestamp: '2026-03-28T10:11:12.000Z',
+      text: `${prefix}BBB`,
+    });
+
+    expect(first).toBe(second);
+  });
+});

package/server/lib/capture/extractor.js

@@ -0,0 +1,51 @@
+const { classify } = require('./classifier.js');
+
+function splitSentences(text) {
+  if (typeof text !== 'string' || !text.trim()) {
+    return [];
+  }
+
+  return text
+    .match(/[^.!?\n]+[.!?]?/g)
+    .map((sentence) => sentence.trim())
+    .filter(Boolean);
+}
+
+function extractDecisions(text, { role = 'unknown' } = {}) {
+  const sentences = splitSentences(text);
+  const seen = new Set();
+  const results = [];
+
+  for (const sentence of sentences) {
+    const classification = classify(sentence);
+
+    if (classification.type === 'session') {
+      continue;
+    }
+
+    const statement = sentence;
+
+    if (seen.has(statement)) {
+      continue;
+    }
+
+    seen.add(statement);
+
+    const confidence = role === 'assistant'
+      ? classification.confidence * 1.5
+      : classification.confidence;
+
+    results.push({
+      statement,
+      context: sentence,
+      confidence,
+      role,
+    });
+  }
+
+  return results;
+}
+
+module.exports = {
+  extractDecisions,
+};