throughline 0.3.24 → 0.4.0

package/src/cli/codex-capture.mjs

@@ -0,0 +1,95 @@
+import { getDb } from '../db.mjs';
+import { captureCodexRolloutToDb } from '../codex-capture.mjs';
+import { resolveCodexThreadIdentity } from '../codex-thread-identity.mjs';
+
+function parseArgs(argv) {
+  const out = {
+    codexThreadId: null,
+    codexHome: null,
+    projectPath: process.cwd(),
+    json: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--codex-thread-id') {
+      const value = argv[++i];
+      if (!value || value.startsWith('-')) throw new Error('--codex-thread-id requires an id');
+      out.codexThreadId = value;
+    } else if (arg === '--codex-home') {
+      const value = argv[++i];
+      if (!value || value.startsWith('-')) throw new Error('--codex-home requires a path');
+      out.codexHome = value;
+    } else if (arg === '--project') {
+      const value = argv[++i];
+      if (!value || value.startsWith('-')) throw new Error('--project requires a path');
+      out.projectPath = value;
+    } else if (arg === '--json') {
+      out.json = true;
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+
+  return out;
+}
+
+export async function run(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs(argv);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : 'unknown';
+    process.stderr.write(`[codex-capture] ${msg}\n`);
+    process.exit(1);
+  }
+
+  const identity = resolveCodexThreadIdentity({ codexThreadId: parsed.codexThreadId }, process.env);
+  if (!identity.codexThreadId) {
+    process.stderr.write(
+      '[codex-capture] missing Codex thread id. Pass --codex-thread-id <id> or set THROUGHLINE_CODEX_THREAD_ID / CODEX_THREAD_ID.\n',
+    );
+    process.exit(1);
+  }
+
+  let result;
+  try {
+    result = captureCodexRolloutToDb(getDb(), {
+      threadId: identity.codexThreadId,
+      codexHome: parsed.codexHome ?? undefined,
+      projectPath: parsed.projectPath,
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : 'unknown';
+    process.stderr.write(`[codex-capture] ${msg}\n`);
+    process.exit(1);
+  }
+
+  const output = {
+    ...result,
+    codexThreadIdSource: identity.codexThreadIdSource,
+  };
+
+  if (parsed.json) {
+    process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+  } else {
+    process.stdout.write(renderReport(output) + '\n');
+  }
+
+  process.exit(result.status === 'captured' ? 0 : 1);
+}
+
+function renderReport(result) {
+  const lines = [];
+  lines.push('## Throughline Codex Capture');
+  lines.push('');
+  lines.push(`Status: ${result.status}`);
+  if (result.reason) lines.push(`Reason: ${result.reason}`);
+  lines.push(`Codex thread: ${result.threadId}`);
+  lines.push(`Throughline session: ${result.sessionId}`);
+  lines.push(`Project: ${result.projectPath}`);
+  if (result.rolloutPath) lines.push(`Rollout: ${result.rolloutPath}`);
+  lines.push(`Captured turns: ${result.capturedTurns}`);
+  lines.push(`Captured rows: ${result.capturedRows}`);
+  return lines.join('\n');
+}

package/src/cli/codex-handoff-model-smoke.mjs

@@ -0,0 +1,292 @@
+import { randomUUID } from 'node:crypto';
+
+import { getDb } from '../db.mjs';
+import { buildHandoffRecord } from '../handoff-record.mjs';
+import { renderCodexNewThreadHandoff } from '../codex-handoff.mjs';
+import { buildCodexHandoffSmoke } from '../codex-handoff-smoke.mjs';
+import {
+  buildCodexHandoffModelSmokePrompt,
+  CODEX_HANDOFF_MODEL_SMOKE_ENV,
+  DEFAULT_CODEX_HANDOFF_MODEL_SMOKE_TIMEOUT_MS,
+  runCodexHandoffModelSmoke,
+} from '../codex-handoff-model-smoke.mjs';
+
+async function readStdin() {
+  let raw = '';
+  await new Promise((resolve) => {
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      raw += chunk;
+    });
+    process.stdin.on('end', resolve);
+  });
+  return raw;
+}
+
+function parseNonNegativeInteger(args, index, flag) {
+  const value = Number(args[index]);
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`${flag} must be a non-negative integer`);
+  }
+  return value;
+}
+
+function parsePositiveInteger(args, index, flag) {
+  const value = Number(args[index]);
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`${flag} must be a positive integer`);
+  }
+  return value;
+}
+
+function parseArgs(args) {
+  const out = {
+    sessionId: null,
+    json: false,
+    dryRun: false,
+    printPrompt: false,
+    memoStdin: false,
+    marker: `TL_CODEX_HANDOFF_${randomUUID().slice(0, 8)}`,
+    codexCliBin: null,
+    timeoutMs: DEFAULT_CODEX_HANDOFF_MODEL_SMOKE_TIMEOUT_MS,
+    maxPromptChars: undefined,
+    maxDetailRefs: undefined,
+    maxRecentBodies: undefined,
+    maxBodyChars: undefined,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--session') {
+      const value = args[++i];
+      if (!value || value.startsWith('-')) {
+        throw new Error('--session requires a session id');
+      }
+      out.sessionId = value;
+    } else if (arg === '--dry-run') {
+      out.dryRun = true;
+    } else if (arg === '--print-prompt') {
+      out.printPrompt = true;
+    } else if (arg === '--memo-stdin') {
+      out.memoStdin = true;
+    } else if (arg === '--marker') {
+      const value = args[++i];
+      if (!value || value.startsWith('-')) {
+        throw new Error('--marker requires a marker string');
+      }
+      out.marker = value;
+    } else if (arg === '--codex-cli-bin') {
+      const value = args[++i];
+      if (!value || value.startsWith('-')) {
+        throw new Error('--codex-cli-bin requires a command path');
+      }
+      out.codexCliBin = value;
+    } else if (arg === '--timeout-ms') {
+      out.timeoutMs = parsePositiveInteger(args, ++i, '--timeout-ms');
+    } else if (arg === '--max-prompt-chars') {
+      out.maxPromptChars = parsePositiveInteger(args, ++i, '--max-prompt-chars');
+    } else if (arg === '--max-detail-refs') {
+      out.maxDetailRefs = parseNonNegativeInteger(args, ++i, '--max-detail-refs');
+    } else if (arg === '--max-recent-bodies') {
+      out.maxRecentBodies = parseNonNegativeInteger(args, ++i, '--max-recent-bodies');
+    } else if (arg === '--max-body-chars') {
+      out.maxBodyChars = parseNonNegativeInteger(args, ++i, '--max-body-chars');
+    } else if (arg === '--json') {
+      out.json = true;
+    } else if (!arg.startsWith('-') && !out.sessionId) {
+      out.sessionId = arg;
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+
+  return out;
+}
+
+function findLatestCodexSessionId(db, projectPath) {
+  const row = db
+    .prepare(
+      `SELECT session_id
+       FROM sessions
+       WHERE lower(project_path) = lower(?)
+         AND session_id LIKE 'codex:%'
+       ORDER BY updated_at DESC
+       LIMIT 1`,
+    )
+    .get(projectPath);
+  return row?.session_id ?? null;
+}
+
+function renderTextResult(result) {
+  const lines = [];
+  lines.push('throughline codex handoff model smoke');
+  lines.push('');
+  lines.push(`  status:          ${result.status}`);
+  lines.push(`  reason:          ${result.reason}`);
+  lines.push(`  session:         ${result.sessionId}`);
+  lines.push(`  marker:          ${result.marker}`);
+  lines.push(`  handoff smoke:   ${result.handoffSmoke.status}`);
+  lines.push(`  prompt chars:    ${result.handoffSmoke.promptChars}`);
+  if (result.modelPromptChars !== undefined) {
+    lines.push(`  model prompt:    ${result.modelPromptChars}`);
+  }
+  if (result.wouldRun !== undefined) {
+    lines.push(`  would run:       ${result.wouldRun ? 'yes' : 'no'}`);
+  }
+  lines.push(`  marker visible:  ${result.markerVisible ? 'yes' : 'no'}`);
+  if (result.commandPreview) {
+    lines.push(`  command:         ${result.commandPreview.join(' ')}`);
+  }
+  if (result.stdout) {
+    lines.push('');
+    lines.push('stdout:');
+    lines.push(result.stdout.trim());
+  }
+  if (result.stderr) {
+    lines.push('');
+    lines.push('stderr:');
+    lines.push(result.stderr.trim());
+  }
+  if (result.prompt) {
+    lines.push('');
+    lines.push(result.prompt);
+  }
+  return lines.join('\n');
+}
+
+export async function run(args) {
+  let parsed;
+  try {
+    parsed = parseArgs(args);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : 'unknown';
+    process.stderr.write(`[codex-handoff-model-smoke] ${msg}\n`);
+    process.exit(1);
+  }
+
+  const command = parsed.codexCliBin ?? process.env.THROUGHLINE_CODEX_CLI_BIN ?? 'codex';
+  if (!parsed.dryRun && process.env[CODEX_HANDOFF_MODEL_SMOKE_ENV] !== '1') {
+    const result = {
+      status: 'refused',
+      reason: 'experimental_env_required',
+      requiredEnv: `${CODEX_HANDOFF_MODEL_SMOKE_ENV}=1`,
+    };
+    if (parsed.json) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    else process.stderr.write(`[codex-handoff-model-smoke] ${result.reason}\n`);
+    process.exit(1);
+  }
+
+  const inflightMemo = parsed.memoStdin ? await readStdin() : null;
+  const db = getDb();
+  const sessionId = parsed.sessionId ?? findLatestCodexSessionId(db, process.cwd());
+  if (!sessionId) {
+    process.stderr.write(
+      '[codex-handoff-model-smoke] no Codex session found for this project. Pass --session codex:<thread-id> explicitly.\n',
+    );
+    process.exit(1);
+  }
+
+  const record = buildHandoffRecord(db, {
+    sessionId,
+    isInheritance: false,
+    inflightMemo,
+  });
+  if (!record) {
+    process.stderr.write(`[codex-handoff-model-smoke] no handoff memory found for session ${sessionId}\n`);
+    process.exit(1);
+  }
+
+  const handoffSmoke = buildCodexHandoffSmoke(record, {
+    maxPromptChars: parsed.maxPromptChars,
+    maxDetailRefs: parsed.maxDetailRefs,
+    maxRecentBodies: parsed.maxRecentBodies,
+    maxBodyChars: parsed.maxBodyChars,
+  });
+  if (handoffSmoke.status !== 'ready') {
+    const result = {
+      status: 'refused',
+      reason: 'handoff_smoke_not_ready',
+      sessionId,
+      handoffSmoke,
+    };
+    if (parsed.json) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    else process.stdout.write(renderTextResult({ ...result, marker: parsed.marker, markerVisible: false }) + '\n');
+    process.exit(1);
+  }
+
+  const handoffPrompt = renderCodexNewThreadHandoff(record, {
+    maxDetailRefs: parsed.maxDetailRefs,
+    maxRecentBodies: parsed.maxRecentBodies,
+    maxBodyChars: parsed.maxBodyChars,
+  });
+  const prompt = buildCodexHandoffModelSmokePrompt({
+    handoffPrompt,
+    marker: parsed.marker,
+  });
+  const commandPreview = [
+    command,
+    'exec',
+    '--ephemeral',
+    '--ignore-user-config',
+    '--ignore-rules',
+    '--skip-git-repo-check',
+    '--sandbox',
+    'read-only',
+    '-C',
+    process.cwd(),
+    '<prompt>',
+  ];
+  if (parsed.dryRun) {
+    const result = {
+      status: 'dry-run',
+      reason: 'codex_exec_not_started',
+      sessionId,
+      marker: parsed.marker,
+      markerVisible: false,
+      handoffSmoke,
+      command,
+      commandPreview,
+      modelPromptChars: prompt.length,
+      estimatedModelPromptTokens: Math.ceil(prompt.length / 4),
+      proofScope: 'dry_run_only',
+      wouldRun: false,
+      mutatesCurrentThread: false,
+      prompt: parsed.printPrompt ? prompt : undefined,
+    };
+    if (parsed.json) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    else process.stdout.write(renderTextResult(result) + '\n');
+    process.exit(0);
+  }
+  const smoke = runCodexHandoffModelSmoke({
+    prompt,
+    marker: parsed.marker,
+    cwd: process.cwd(),
+    command,
+    timeoutMs: parsed.timeoutMs,
+    env: {
+      ...process.env,
+      [CODEX_HANDOFF_MODEL_SMOKE_ENV]: process.env[CODEX_HANDOFF_MODEL_SMOKE_ENV],
+    },
+  });
+  const result = {
+    ...smoke,
+    sessionId,
+    handoffSmoke,
+    command,
+    commandPreview,
+    modelPromptChars: prompt.length,
+    estimatedModelPromptTokens: Math.ceil(prompt.length / 4),
+    proofScope: 'codex_exec_ephemeral_read_only',
+    wouldRun: true,
+    mutatesCurrentThread: false,
+  };
+
+  if (parsed.json) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  else process.stdout.write(renderTextResult(result) + '\n');
+  process.exit(result.status === 'visible' ? 0 : 1);
+}
+
+export const _internal = {
+  parseArgs,
+  renderTextResult,
+};

package/src/cli/codex-handoff-model-smoke.test.mjs

@@ -0,0 +1,262 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+
+function makeTempHome() {
+  return mkdtempSync(join(tmpdir(), 'tl-codex-handoff-model-home-'));
+}
+
+function makeTempProject() {
+  return mkdtempSync(join(tmpdir(), 'tl-codex-handoff-model-project-'));
+}
+
+function makeFakeCodexCli(dir) {
+  const script = join(dir, 'fake-codex-cli.mjs');
+  writeFileSync(
+    script,
+    `#!/usr/bin/env node
+const prompt = process.argv.at(-1) ?? '';
+if (!process.argv.includes('exec')) process.exit(7);
+if (!process.argv.includes('--ephemeral')) process.exit(8);
+if (!prompt.includes('latest handoff model body')) process.exit(9);
+const marker = (prompt.match(/TL_CLI_HANDOFF_MODEL/) ?? [''])[0];
+process.stdout.write(marker + '\\n');
+`,
+  );
+  chmodSync(script, 0o755);
+  return script;
+}
+
+async function seedDb(home, project) {
+  const originalHome = process.env.HOME;
+  const originalUserProfile = process.env.USERPROFILE;
+  process.env.HOME = home;
+  process.env.USERPROFILE = home;
+  try {
+    const mod = await import(`../db.mjs?codexHandoffModel=${Date.now()}-${Math.random()}`);
+    const db = mod.getDb();
+    db.prepare(
+      `INSERT INTO sessions (session_id, project_path, status, created_at, updated_at)
+       VALUES ('codex:thread-handoff-model', ?, 'active', 1, 2)`,
+    ).run(project);
+    db.prepare(
+      `INSERT INTO bodies
+         (session_id, origin_session_id, turn_number, role, text, token_count, created_at)
+       VALUES ('codex:thread-handoff-model', 'codex:thread-handoff-model', 1, 'assistant',
+               'latest handoff model body', 4, 1000)`,
+    ).run();
+    db.close();
+  } finally {
+    if (originalHome === undefined) delete process.env.HOME;
+    else process.env.HOME = originalHome;
+    if (originalUserProfile === undefined) delete process.env.USERPROFILE;
+    else process.env.USERPROFILE = originalUserProfile;
+  }
+}
+
+function runSmoke(home, project, args = [], extraEnv = {}, input = undefined) {
+  return spawnSync(
+    process.execPath,
+    [join(REPO_ROOT, 'bin/throughline.mjs'), 'codex-handoff-model-smoke', ...args],
+    {
+      cwd: project,
+      env: {
+        ...process.env,
+        HOME: home,
+        USERPROFILE: home,
+        ...extraEnv,
+      },
+      encoding: 'utf8',
+      input,
+    },
+  );
+}
+
+test('codex-handoff-model-smoke refuses without explicit env', async () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  try {
+    await seedDb(home, project);
+    const result = runSmoke(home, project, [
+      '--session',
+      'codex:thread-handoff-model',
+      '--json',
+    ]);
+
+    assert.equal(result.status, 1);
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.status, 'refused');
+    assert.equal(payload.reason, 'experimental_env_required');
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('codex-handoff-model-smoke dry-run does not require env or start Codex exec', async () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  try {
+    await seedDb(home, project);
+    const result = runSmoke(home, project, [
+      '--session',
+      'codex:thread-handoff-model',
+      '--marker',
+      'TL_CLI_HANDOFF_MODEL_DRY_RUN',
+      '--dry-run',
+      '--json',
+    ]);
+
+    assert.equal(result.status, 0, result.stderr);
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.status, 'dry-run');
+    assert.equal(payload.reason, 'codex_exec_not_started');
+    assert.equal(payload.sessionId, 'codex:thread-handoff-model');
+    assert.equal(payload.handoffSmoke.status, 'ready');
+    assert.equal(payload.wouldRun, false);
+    assert.equal(payload.mutatesCurrentThread, false);
+    assert.equal(payload.markerVisible, false);
+    assert.equal(payload.proofScope, 'dry_run_only');
+    assert.equal(payload.commandPreview.at(-1), '<prompt>');
+    assert.equal(payload.prompt, undefined);
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('codex-handoff-model-smoke dry-run can print the exact model prompt', async () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  try {
+    await seedDb(home, project);
+    const result = runSmoke(home, project, [
+      '--session',
+      'codex:thread-handoff-model',
+      '--marker',
+      'TL_CLI_HANDOFF_MODEL_PRINT',
+      '--dry-run',
+      '--print-prompt',
+      '--json',
+    ]);
+
+    assert.equal(result.status, 0, result.stderr);
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.status, 'dry-run');
+    assert.match(payload.prompt, /## Throughline: New Codex Thread Handoff/);
+    assert.match(payload.prompt, /### Throughline Fresh-Thread Handoff Model Smoke/);
+    assert.match(payload.prompt, /TL_CLI_HANDOFF_MODEL_PRINT/);
+    assert.equal(payload.modelPromptChars, payload.prompt.length);
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('codex-handoff-model-smoke dry-run accepts Codex-primary memo on stdin', async () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  try {
+    await seedDb(home, project);
+    const result = runSmoke(
+      home,
+      project,
+      [
+        '--session',
+        'codex:thread-handoff-model',
+        '--marker',
+        'TL_CLI_HANDOFF_MODEL_MEMO',
+        '--dry-run',
+        '--memo-stdin',
+        '--print-prompt',
+        '--json',
+      ],
+      {},
+      '**Next move**: memo-visible model smoke',
+    );
+
+    assert.equal(result.status, 0, result.stderr);
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.status, 'dry-run');
+    assert.match(payload.prompt, /In-flight Memo/);
+    assert.match(payload.prompt, /memo-visible model smoke/);
+    assert.match(payload.prompt, /TL_CLI_HANDOFF_MODEL_MEMO/);
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('codex-handoff-model-smoke runs fake ephemeral Codex exec smoke', async () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  try {
+    await seedDb(home, project);
+    const fake = makeFakeCodexCli(project);
+    const result = runSmoke(
+      home,
+      project,
+      [
+        '--session',
+        'codex:thread-handoff-model',
+        '--marker',
+        'TL_CLI_HANDOFF_MODEL',
+        '--codex-cli-bin',
+        fake,
+        '--json',
+      ],
+      { THROUGHLINE_EXPERIMENTAL_CODEX_HANDOFF_MODEL_SMOKE: '1' },
+    );
+
+    assert.equal(result.status, 0, result.stderr);
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.status, 'visible');
+    assert.equal(payload.reason, 'marker_found_in_codex_exec_output');
+    assert.equal(payload.sessionId, 'codex:thread-handoff-model');
+    assert.equal(payload.handoffSmoke.status, 'ready');
+    assert.equal(payload.proofScope, 'codex_exec_ephemeral_read_only');
+    assert.equal(payload.mutatesCurrentThread, false);
+    assert.match(payload.stdout, /TL_CLI_HANDOFF_MODEL/);
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('codex-handoff-model-smoke refuses when structural handoff smoke is not ready', async () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  try {
+    await seedDb(home, project);
+    const fake = makeFakeCodexCli(project);
+    const result = runSmoke(
+      home,
+      project,
+      [
+        '--session',
+        'codex:thread-handoff-model',
+        '--max-prompt-chars',
+        '50',
+        '--codex-cli-bin',
+        fake,
+        '--json',
+      ],
+      { THROUGHLINE_EXPERIMENTAL_CODEX_HANDOFF_MODEL_SMOKE: '1' },
+    );
+
+    assert.equal(result.status, 1);
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.status, 'refused');
+    assert.equal(payload.reason, 'handoff_smoke_not_ready');
+    assert.equal(payload.handoffSmoke.status, 'not-ready');
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});