tlc-claude-code 2.4.2 → 2.4.4

package/server/lib/capture/generic-capture.test.js

@@ -0,0 +1,171 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+const SPOOL_PATH = path.join('.tlc', 'memory', '.spool.jsonl');
+
+function readSpoolEntries(projectDir) {
+  const spoolPath = path.join(projectDir, SPOOL_PATH);
+  const content = fs.readFileSync(spoolPath, 'utf8').trim();
+
+  return content.split('\n').filter(Boolean).map((line) => JSON.parse(line));
+}
+
+describe('capture/generic-capture', () => {
+  let projectDir;
+  let captureFromStdout;
+  let captureFromApiResponse;
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-03-28T12:34:56.000Z'));
+    projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-generic-capture-'));
+    ({ captureFromStdout, captureFromApiResponse } = await import('./generic-capture.js'));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.resetModules();
+    fs.rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('captures stdout into a redacted envelope', () => {
+    const result = captureFromStdout({
+      stdout: 'token=abc123 password=hunter2 /Users/jurgen/private/app.js',
+      provider: 'gemini',
+      taskName: 'Implement auth',
+      projectDir,
+    });
+
+    const [entry] = readSpoolEntries(projectDir);
+
+    expect(result).toEqual({ captured: 1, skipped: 0 });
+    expect(entry).toMatchObject({
+      provider: 'gemini',
+      source: 'stdout',
+      taskName: 'Implement auth',
+      timestamp: '2026-03-28T12:34:56.000Z',
+      metadata: {
+        assistantMessage: 'token=[TOKEN_REDACTED] password=[REDACTED] ~/private/app.js',
+      },
+    });
+    expect(entry.text).toBe('token=[TOKEN_REDACTED] password=[REDACTED] ~/private/app.js');
+  });
+
+  it('returns skipped when stdout is empty', () => {
+    const result = captureFromStdout({
+      stdout: '   ',
+      provider: 'gemini',
+      taskName: 'Implement auth',
+      projectDir,
+    });
+
+    expect(result).toEqual({ captured: 0, skipped: 1 });
+    expect(fs.existsSync(path.join(projectDir, SPOOL_PATH))).toBe(false);
+  });
+
+  it('appends to an existing spool file', () => {
+    const spoolPath = path.join(projectDir, SPOOL_PATH);
+    fs.mkdirSync(path.dirname(spoolPath), { recursive: true });
+    fs.writeFileSync(spoolPath, `${JSON.stringify({ existing: true })}\n`);
+
+    captureFromStdout({
+      stdout: 'We decided to use SQLite for local state.',
+      provider: 'openrouter',
+      taskName: 'State storage',
+      projectDir,
+    });
+
+    const lines = fs.readFileSync(spoolPath, 'utf8').trim().split('\n');
+
+    expect(lines).toHaveLength(2);
+    expect(JSON.parse(lines[0])).toEqual({ existing: true });
+    expect(JSON.parse(lines[1])).toMatchObject({
+      provider: 'openrouter',
+      source: 'stdout',
+    });
+  });
+
+  it('captures api response content when present', () => {
+    const result = captureFromApiResponse({
+      response: {
+        content: 'secret=hunter2\nWe decided to use retries.',
+      },
+      provider: 'gemini',
+      taskName: 'Retry policy',
+      projectDir,
+    });
+
+    const [entry] = readSpoolEntries(projectDir);
+
+    expect(result).toEqual({ captured: 1, skipped: 0 });
+    expect(entry.source).toBe('api-response');
+    expect(entry.text).toContain('[REDACTED]');
+    expect(entry.text).toContain('We decided to use retries.');
+    expect(entry.text).not.toContain('hunter2');
+  });
+
+  it('falls back to choices[0].message.content for api responses', () => {
+    captureFromApiResponse({
+      response: {
+        choices: [
+          {
+            message: {
+              content: 'Use Redis for rate limits.',
+            },
+          },
+        ],
+      },
+      provider: 'openai',
+      taskName: 'Rate limits',
+      projectDir,
+    });
+
+    const [entry] = readSpoolEntries(projectDir);
+
+    expect(entry.text).toBe('Use Redis for rate limits.');
+    expect(entry.metadata.assistantMessage).toBe('Use Redis for rate limits.');
+  });
+
+  it('falls back to JSON stringification when api response has no direct text field', () => {
+    captureFromApiResponse({
+      response: {
+        status: 'ok',
+        data: {
+          message: 'We decided to shard by tenant.',
+        },
+      },
+      provider: 'anthropic-proxy',
+      taskName: 'Sharding',
+      projectDir,
+    });
+
+    const [entry] = readSpoolEntries(projectDir);
+
+    expect(entry.text).toContain('"status":"ok"');
+    expect(entry.text).toContain('"message":"We decided to shard by tenant."');
+  });
+
+  it('supports injected fs implementations', () => {
+    const injectedFs = {
+      ...fs,
+      appendFileSync: vi.fn(fs.appendFileSync),
+      existsSync: vi.fn(fs.existsSync),
+      mkdirSync: vi.fn(fs.mkdirSync),
+      readFileSync: vi.fn(fs.readFileSync),
+      writeFileSync: vi.fn(fs.writeFileSync),
+    };
+
+    const result = captureFromApiResponse({
+      response: { content: 'Use a queue for webhooks.' },
+      provider: 'gemini',
+      taskName: 'Webhook delivery',
+      projectDir,
+      fs: injectedFs,
+    });
+
+    expect(result).toEqual({ captured: 1, skipped: 0 });
+    expect(injectedFs.appendFileSync).toHaveBeenCalledTimes(1);
+  });
+});

package/server/lib/capture/index.js

@@ -0,0 +1,117 @@
+const path = require('path');
+
+const { captureFromStdout, captureFromApiResponse } = require('./generic-capture');
+
+const zeroCaptureCounts = new Map();
+let warningCount = 0;
+const MAX_WARNINGS_PER_SESSION = 3;
+const WARNING_LOG_PATH = path.join('.tlc', 'memory', '.capture-warnings.log');
+
+function warningsEnabled() {
+  return process.env.TLC_CAPTURE_WARNINGS !== 'false';
+}
+
+function maybeWarn(projectDir, fs, message) {
+  if (!warningsEnabled() || warningCount >= MAX_WARNINGS_PER_SESSION) {
+    return;
+  }
+
+  warningCount += 1;
+  console.warn(message);
+
+  if (!projectDir) {
+    return;
+  }
+
+  try {
+    const logPath = path.join(projectDir, WARNING_LOG_PATH);
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    fs.appendFileSync(logPath, `${new Date().toISOString()} ${message}\n`, 'utf8');
+  } catch (_) {
+    // Warning emission must not break capture routing.
+  }
+}
+
+function maybeEmitWarning({ provider, output, taskName, projectDir, result, fs }) {
+  if (result && result.captured > 0) {
+    zeroCaptureCounts.set(provider, 0);
+    return;
+  }
+
+  const nextCount = (zeroCaptureCounts.get(provider) || 0) + 1;
+  zeroCaptureCounts.set(provider, nextCount);
+
+  if (typeof output !== 'string' || output.length <= 500) {
+    return;
+  }
+
+  if (nextCount >= 3) {
+    maybeWarn(
+      projectDir,
+      fs,
+      `[TLC WARNING] ${provider} has produced 0 memory captures for ${nextCount} consecutive tasks. Check capture configuration.`,
+    );
+    return;
+  }
+
+  maybeWarn(
+    projectDir,
+    fs,
+    `[TLC WARNING] No decisions captured from ${provider} for task "${taskName}". Memory capture may not be working for this provider.`,
+  );
+}
+
+function captureFromProvider({
+  provider,
+  output,
+  taskName,
+  threadId,
+  projectDir,
+  hookInput,
+  lastMessageFile,
+  jsonStream,
+  fs = require('fs'),
+}) {
+  let result;
+
+  if (provider === 'claude') {
+    const { captureClaudeExchange } = require('./claude-capture');
+    result = captureClaudeExchange({ hookInput, projectDir, fs });
+  } else if (provider === 'codex') {
+    const { captureCodexOutput } = require('./codex-capture');
+    result = captureCodexOutput({
+      lastMessageFile,
+      jsonStream,
+      stdout: output,
+      taskName,
+      threadId,
+      projectDir,
+      fs,
+    });
+  } else {
+    result = captureFromStdout({
+      stdout: output,
+      provider,
+      taskName,
+      projectDir,
+      fs,
+    });
+  }
+
+  maybeEmitWarning({
+    provider,
+    output,
+    taskName,
+    projectDir,
+    result,
+    fs,
+  });
+
+  return result;
+}
+
+module.exports = {
+  captureFromProvider,
+  captureFromStdout,
+  captureFromApiResponse,
+};

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

@@ -0,0 +1,263 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { createRequire } from 'module';
+
+const SPOOL_PATH = path.join('.tlc', 'memory', '.spool.jsonl');
+const WARNING_LOG = path.join('.tlc', 'memory', '.capture-warnings.log');
+const require = createRequire(import.meta.url);
+
+function longOutput() {
+  return 'Decision '.repeat(80);
+}
+
+function readSpoolEntries(projectDir) {
+  const spoolPath = path.join(projectDir, SPOOL_PATH);
+  const content = fs.readFileSync(spoolPath, 'utf8').trim();
+
+  return content.split('\n').filter(Boolean).map((line) => JSON.parse(line));
+}
+
+function createFailingFs() {
+  return {
+    ...fs,
+    appendFileSync: vi.fn(() => {
+      throw new Error('append failed');
+    }),
+  };
+}
+
+describe('capture/index', () => {
+  let projectDir;
+  let captureFromProvider;
+  let captureFromStdout;
+  let captureFromApiResponse;
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-03-28T12:34:56.000Z'));
+    projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-capture-index-'));
+    delete process.env.TLC_CAPTURE_WARNINGS;
+    ({ captureFromProvider, captureFromStdout, captureFromApiResponse } = await import('./index.js'));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    vi.resetModules();
+    delete process.env.TLC_CAPTURE_WARNINGS;
+    fs.rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('routes claude to claude-capture', () => {
+    captureFromProvider({
+      provider: 'claude',
+      output: 'stdout fallback',
+      taskName: 'Task',
+      hookInput: JSON.stringify({
+        session_id: 'sess-1',
+        assistant_message: 'We decided to use Postgres.',
+      }),
+      projectDir,
+    });
+
+    const [entry] = readSpoolEntries(projectDir);
+
+    expect(entry).toMatchObject({
+      provider: 'claude',
+      source: 'stop-hook',
+      threadId: 'sess-1',
+      text: 'We decided to use Postgres.',
+    });
+  });
+
+  it('routes codex to codex-capture with the expected source resolution', () => {
+    captureFromProvider({
+      provider: 'codex',
+      output: 'stdout fallback',
+      taskName: 'Task',
+      threadId: null,
+      jsonStream: [
+        '{"type":"thread.started","thread_id":"thread-from-json"}',
+        JSON.stringify({
+          type: 'agent_message',
+          message: {
+            items: [
+              { type: 'text', text: 'First agent message' },
+              { type: 'text', text: 'Second agent message' },
+            ],
+          },
+        }),
+      ].join('\n'),
+      projectDir,
+    });
+
+    const [entry] = readSpoolEntries(projectDir);
+
+    expect(entry).toMatchObject({
+      provider: 'codex',
+      source: 'json-stream',
+      threadId: 'thread-from-json',
+      text: 'First agent message\n\nSecond agent message',
+    });
+  });
+
+  it('routes unknown providers to generic stdout capture', () => {
+    captureFromProvider({
+      provider: 'gemini',
+      output: 'Use Redis for caching.',
+      taskName: 'Task',
+      projectDir,
+    });
+
+    const [entry] = readSpoolEntries(projectDir);
+
+    expect(entry).toMatchObject({
+      provider: 'gemini',
+      source: 'stdout',
+      taskName: 'Task',
+      text: 'Use Redis for caching.',
+    });
+  });
+
+  it('re-exports generic capture functions', async () => {
+    const index = require('./index.js');
+    const generic = require('./generic-capture.js');
+
+    expect(index.captureFromStdout).toBe(generic.captureFromStdout);
+    expect(index.captureFromApiResponse).toBe(generic.captureFromApiResponse);
+  });
+
+  it('does not warn when captures succeed', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    captureFromProvider({
+      provider: 'gemini',
+      output: longOutput(),
+      taskName: 'Task',
+      projectDir,
+    });
+
+    expect(warnSpy).not.toHaveBeenCalled();
+    expect(fs.existsSync(path.join(projectDir, WARNING_LOG))).toBe(false);
+  });
+
+  it('does not warn when output is too short', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    captureFromProvider({
+      provider: 'claude',
+      output: 'short output',
+      taskName: 'Task',
+      hookInput: '{"session_id"',
+      projectDir,
+    });
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it('warns and writes to the warning log when a long output captures nothing', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    captureFromProvider({
+      provider: 'claude',
+      output: longOutput(),
+      taskName: 'Investigate retries',
+      hookInput: '{"session_id"',
+      projectDir,
+    });
+
+    const logPath = path.join(projectDir, WARNING_LOG);
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0][0]).toContain('No decisions captured from claude');
+    expect(warnSpy.mock.calls[0][0]).toContain('Investigate retries');
+    expect(fs.readFileSync(logPath, 'utf8')).toContain('2026-03-28T12:34:56.000Z');
+    expect(fs.readFileSync(logPath, 'utf8')).toContain('No decisions captured from claude');
+  });
+
+  it('escalates on the third consecutive zero capture for the same provider', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 1', hookInput: '{"bad"', projectDir });
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 2', hookInput: '{"bad"', projectDir });
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 3', hookInput: '{"bad"', projectDir });
+
+    expect(warnSpy).toHaveBeenCalledTimes(3);
+    expect(warnSpy.mock.calls[2][0]).toContain('claude has produced 0 memory captures for 3 consecutive tasks');
+  });
+
+  it('resets the consecutive zero counter after a successful capture', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 1', hookInput: '{"bad"', projectDir });
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 2', hookInput: '{"bad"', projectDir });
+    captureFromProvider({
+      provider: 'claude',
+      output: longOutput(),
+      taskName: 'Task 3',
+      hookInput: JSON.stringify({
+        session_id: 'sess-2',
+        assistant_message: 'We decided to use Redis.',
+      }),
+      projectDir,
+    });
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 4', hookInput: '{"bad"', projectDir });
+
+    expect(warnSpy).toHaveBeenCalledTimes(3);
+    expect(warnSpy.mock.calls[2][0]).toContain('No decisions captured from claude');
+    expect(warnSpy.mock.calls[2][0]).not.toContain('consecutive tasks');
+  });
+
+  it('tracks consecutive zero captures per provider independently', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const failingFs = createFailingFs();
+
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 1', hookInput: '{"bad"', projectDir });
+    captureFromProvider({
+      provider: 'codex',
+      output: longOutput(),
+      taskName: 'Task 2',
+      threadId: 'thread-1',
+      projectDir,
+      fs: failingFs,
+    });
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 3', hookInput: '{"bad"', projectDir });
+
+    expect(warnSpy).toHaveBeenCalledTimes(3);
+    expect(warnSpy.mock.calls[1][0]).toContain('No decisions captured from codex');
+    expect(warnSpy.mock.calls[2][0]).toContain('No decisions captured from claude');
+    expect(warnSpy.mock.calls[2][0]).not.toContain('consecutive tasks');
+  });
+
+  it('caps warnings at three per session', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 1', hookInput: '{"bad"', projectDir });
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 2', hookInput: '{"bad"', projectDir });
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 3', hookInput: '{"bad"', projectDir });
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 4', hookInput: '{"bad"', projectDir });
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 5', hookInput: '{"bad"', projectDir });
+
+    expect(warnSpy).toHaveBeenCalledTimes(3);
+    const logLines = fs.readFileSync(path.join(projectDir, WARNING_LOG), 'utf8').trim().split('\n');
+    expect(logLines).toHaveLength(3);
+  });
+
+  it('disables warnings entirely when TLC_CAPTURE_WARNINGS is false', () => {
+    process.env.TLC_CAPTURE_WARNINGS = 'false';
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    captureFromProvider({
+      provider: 'claude',
+      output: longOutput(),
+      taskName: 'Investigate retries',
+      hookInput: '{"session_id"',
+      projectDir,
+    });
+
+    expect(warnSpy).not.toHaveBeenCalled();
+    expect(fs.existsSync(path.join(projectDir, WARNING_LOG))).toBe(false);
+  });
+});

package/server/lib/capture/redactor.js

@@ -0,0 +1,68 @@
+function redactKeyValue(input, key, replacement) {
+  const quotedPattern = new RegExp(`(["']?${key}["']?)(\\s*[:=]\\s*)(["'])(.*?)\\3`, 'gi');
+  const barePattern = new RegExp(`(["']?${key}["']?)(\\s*[:=]\\s*)([^\\s"',}]+)`, 'gi');
+
+  return input
+    .replace(quotedPattern, (_, matchedKey, separator, quote) => `${matchedKey}${separator}${quote}${replacement}${quote}`)
+    .replace(barePattern, (_, matchedKey, separator) => `${matchedKey}${separator}${replacement}`);
+}
+
+function redactPaths(input) {
+  return input
+    .replace(/\/Users\/[^/\s]+\/([^\s]+)/g, '~/$1')
+    .replace(/\/home\/[^/\s]+\/([^\s]+)/g, '~/$1');
+}
+
+function collapseStackTrace(input) {
+  const lines = input.split('\n');
+
+  if (lines.length < 4) {
+    return input;
+  }
+
+  const stackLikeLineCount = lines.slice(1).filter((line) => /^\s+at\b/.test(line) || /^(Caused by|Error:)/.test(line)).length;
+
+  if (stackLikeLineCount < 2) {
+    return input;
+  }
+
+  return `${lines[0]}\n... ${lines.length - 2} more lines\n${lines[lines.length - 1]}`;
+}
+
+function applyExtraPatterns(input, extraPatterns) {
+  let output = input;
+
+  for (const entry of extraPatterns) {
+    if (!entry || !(entry.pattern instanceof RegExp) || typeof entry.replacement !== 'string') {
+      continue;
+    }
+
+    output = output.replace(entry.pattern, entry.replacement);
+  }
+
+  return output;
+}
+
+function redact(text, { extraPatterns = [] } = {}) {
+  let output = String(text);
+
+  output = output.replace(/\bsk-[A-Za-z0-9_-]+\b/g, '[API_KEY_REDACTED]');
+  output = output.replace(/\bgh[pus]_[A-Za-z0-9_]+\b/g, '[API_KEY_REDACTED]');
+  output = output.replace(/\bBearer\s+[A-Za-z0-9._-]+\b/gi, 'Bearer [TOKEN_REDACTED]');
+
+  output = redactKeyValue(output, 'token', '[TOKEN_REDACTED]');
+  output = redactKeyValue(output, 'password', '[REDACTED]');
+  output = redactKeyValue(output, 'secret', '[REDACTED]');
+
+  output = redactPaths(output);
+  output = output.replace(/([=:])([A-Za-z0-9+/=]{101,})(?=[^A-Za-z0-9+/=]|$)/g, '$1[BASE64_REDACTED]');
+  output = output.replace(/(^|[\s([{,])([A-Za-z0-9+/=]{101,})(?=$|[\s)\]},])/g, (_, prefix) => `${prefix}[BASE64_REDACTED]`);
+  output = collapseStackTrace(output);
+  output = applyExtraPatterns(output, extraPatterns);
+
+  return output;
+}
+
+module.exports = {
+  redact,
+};