throughline 0.3.23 → 0.3.25

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

@@ -0,0 +1,163 @@
+import { getDb } from '../db.mjs';
+import { buildHandoffRecord } from '../handoff-record.mjs';
+import { buildCodexHandoffSmoke } from '../codex-handoff-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,
+    printPrompt: false,
+    memoStdin: false,
+    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 === '--json') {
+      out.json = true;
+    } else if (arg === '--print-prompt') {
+      out.printPrompt = true;
+    } else if (arg === '--memo-stdin') {
+      out.memoStdin = true;
+    } 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.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 smoke');
+  lines.push('');
+  lines.push(`  status:                 ${result.status}`);
+  lines.push(`  reason:                 ${result.reason}`);
+  lines.push(`  session:                ${result.sessionId}`);
+  lines.push(`  source agent:           ${result.sourceAgent}`);
+  lines.push(`  prompt chars:           ${result.promptChars}/${result.maxPromptChars}`);
+  lines.push(`  estimated tokens:       ${result.estimatedTokens}`);
+  lines.push(`  L1 summaries:           ${result.l1Summaries}`);
+  lines.push(`  recent L2 bodies:       ${result.recentBodies}`);
+  lines.push(`  L3 references:          ${result.l3References}`);
+  lines.push(`  rendered detail cmds:   ${result.renderedDetailCommands}`);
+  lines.push('');
+  lines.push('  checks:');
+  for (const check of result.checks) {
+    lines.push(`    - ${check.id}: ${check.status}`);
+  }
+  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-smoke] ${msg}\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-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-smoke] no handoff memory found for session ${sessionId}\n`);
+    process.exit(1);
+  }
+
+  const result = buildCodexHandoffSmoke(record, {
+    maxPromptChars: parsed.maxPromptChars,
+    maxDetailRefs: parsed.maxDetailRefs,
+    maxRecentBodies: parsed.maxRecentBodies,
+    maxBodyChars: parsed.maxBodyChars,
+    includePrompt: parsed.printPrompt,
+  });
+
+  if (parsed.json) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  else process.stdout.write(renderTextResult(result) + '\n');
+  process.exit(result.status === 'ready' ? 0 : 1);
+}
+
+export const _internal = {
+  parseArgs,
+  renderTextResult,
+};

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

@@ -0,0 +1,149 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } 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-smoke-home-'));
+}
+
+function makeTempProject() {
+  return mkdtempSync(join(tmpdir(), 'tl-codex-handoff-smoke-project-'));
+}
+
+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?codexHandoffSmoke=${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-smoke', ?, 'active', 1, 2)`,
+    ).run(project);
+    db.prepare(
+      `INSERT INTO skeletons
+         (session_id, origin_session_id, turn_number, role, summary, created_at)
+       VALUES ('codex:thread-handoff-smoke', 'codex:thread-handoff-smoke', 1, 'assistant',
+               'older handoff smoke summary', 1000)`,
+    ).run();
+    db.prepare(
+      `INSERT INTO bodies
+         (session_id, origin_session_id, turn_number, role, text, token_count, created_at)
+       VALUES ('codex:thread-handoff-smoke', 'codex:thread-handoff-smoke', 2, 'assistant',
+               'latest handoff smoke body', 4, 2000)`,
+    ).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 = [], input = undefined) {
+  return spawnSync(
+    process.execPath,
+    [join(REPO_ROOT, 'bin/throughline.mjs'), 'codex-handoff-smoke', ...args],
+    {
+      cwd: project,
+      env: {
+        ...process.env,
+        HOME: home,
+        USERPROFILE: home,
+      },
+      encoding: 'utf8',
+      input,
+    },
+  );
+}
+
+test('codex-handoff-smoke validates latest Codex session as JSON', async () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  try {
+    await seedDb(home, project);
+    const result = runSmoke(home, project, ['--json']);
+
+    assert.equal(result.status, 0, result.stderr);
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.status, 'ready');
+    assert.equal(payload.sessionId, 'codex:thread-handoff-smoke');
+    assert.equal(payload.reason, 'fresh_thread_handoff_prompt_ready');
+    assert.equal(payload.checks.every((check) => check.status === 'pass'), true);
+    assert.equal(payload.prompt, undefined);
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('codex-handoff-smoke can print the generated prompt', async () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  try {
+    await seedDb(home, project);
+    const result = runSmoke(home, project, [
+      '--session',
+      'codex:thread-handoff-smoke',
+      '--print-prompt',
+    ]);
+
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, /throughline codex handoff smoke/);
+    assert.match(result.stdout, /status:\s+ready/);
+    assert.match(result.stdout, /Throughline: New Codex Thread Handoff/);
+    assert.match(result.stdout, /latest handoff smoke body/);
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('codex-handoff-smoke exits nonzero when prompt size check fails', async () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  try {
+    await seedDb(home, project);
+    const result = runSmoke(home, project, [
+      '--session',
+      'codex:thread-handoff-smoke',
+      '--max-prompt-chars',
+      '50',
+      '--json',
+    ]);
+
+    assert.equal(result.status, 1);
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.status, 'not-ready');
+    assert.equal(
+      payload.checks.find((check) => check.id === 'prompt_size_within_limit')?.status,
+      'fail',
+    );
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('codex-handoff-smoke rejects invalid limits', () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  try {
+    const result = runSmoke(home, project, ['--max-prompt-chars', '0']);
+
+    assert.equal(result.status, 1);
+    assert.match(result.stderr, /--max-prompt-chars must be a positive integer/);
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});

package/src/cli/codex-handoff-start.mjs

@@ -0,0 +1,291 @@
+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 } from '../codex-handoff-model-smoke.mjs';
+import { estimateTokens } from '../token-estimator.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,
+    printPrompt: false,
+    memoStdin: false,
+    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 === '--json') {
+      out.json = true;
+    } else if (arg === '--print-prompt') {
+      out.printPrompt = true;
+    } else if (arg === '--memo-stdin') {
+      out.memoStdin = true;
+    } 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.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 limitArgs(parsed, { includeMaxPromptChars = false } = {}) {
+  const args = [];
+  if (includeMaxPromptChars && parsed.maxPromptChars !== undefined) {
+    args.push('--max-prompt-chars', String(parsed.maxPromptChars));
+  }
+  if (parsed.maxDetailRefs !== undefined) {
+    args.push('--max-detail-refs', String(parsed.maxDetailRefs));
+  }
+  if (parsed.maxRecentBodies !== undefined) {
+    args.push('--max-recent-bodies', String(parsed.maxRecentBodies));
+  }
+  if (parsed.maxBodyChars !== undefined) {
+    args.push('--max-body-chars', String(parsed.maxBodyChars));
+  }
+  return args;
+}
+
+function memoArgs(parsed) {
+  return parsed.memoStdin ? ['--memo-stdin'] : [];
+}
+
+function commandFor(parts) {
+  return parts.join(' ');
+}
+
+function buildGuidance({ sessionId, parsed, handoffSmoke, handoffPrompt }) {
+  const smokeArgs = limitArgs(parsed, { includeMaxPromptChars: true });
+  const handoffArgs = limitArgs(parsed);
+  const modelPrompt = buildCodexHandoffModelSmokePrompt({
+    handoffPrompt,
+    marker: 'TL_CODEX_HANDOFF_START_SMOKE',
+  });
+  const commands = {
+    structuralSmoke: commandFor([
+      'throughline',
+      'codex-handoff-smoke',
+      '--session',
+      sessionId,
+      ...smokeArgs,
+      ...memoArgs(parsed),
+      '--json',
+    ]),
+    modelSmokeDryRun: commandFor([
+      'throughline',
+      'codex-handoff-model-smoke',
+      '--session',
+      sessionId,
+      ...smokeArgs,
+      ...memoArgs(parsed),
+      '--dry-run',
+      '--json',
+    ]),
+    renderPrompt: commandFor([
+      'throughline',
+      'codex-resume',
+      '--session',
+      sessionId,
+      '--format',
+      'handoff',
+      ...handoffArgs,
+      ...memoArgs(parsed),
+    ]),
+    liveModelSmoke: commandFor([
+      'THROUGHLINE_EXPERIMENTAL_CODEX_HANDOFF_MODEL_SMOKE=1',
+      'throughline',
+      'codex-handoff-model-smoke',
+      '--session',
+      sessionId,
+      ...smokeArgs,
+      ...memoArgs(parsed),
+      '--json',
+    ]),
+  };
+  const ready = handoffSmoke.status === 'ready';
+  return {
+    status: ready ? 'ready' : 'not-ready',
+    reason: ready ? 'fresh_thread_handoff_start_ready' : 'handoff_smoke_not_ready',
+    sessionId,
+    mutatesCurrentThread: false,
+    startThreadManually: true,
+    handoffSmoke,
+    modelPromptChars: modelPrompt.length,
+    estimatedModelPromptTokens: estimateTokens(modelPrompt),
+    memoStdin: parsed.memoStdin,
+    memoReplayNote: parsed.memoStdin
+      ? 'Commands include --memo-stdin; pipe the same memo when replaying them.'
+      : null,
+    commands,
+    steps: ready
+      ? [
+          'Run the structural smoke command if you want to re-check the handoff prompt.',
+          'Run the model smoke dry-run command if you want to inspect the Codex exec boundary without starting a model turn.',
+          'Render the handoff prompt with the render prompt command, or pass --print-prompt to this command.',
+          ...(parsed.memoStdin
+            ? ['When replaying individual commands, pipe the same memo because they include --memo-stdin.']
+            : []),
+          'Start a new Codex thread and provide the handoff prompt as the opening context.',
+        ]
+      : [
+          'Fix the failing handoff smoke checks before starting a new Codex thread.',
+          'This handoff command does not run current-thread trim; use trim --execute --host codex for guarded current-thread rollback / inject.',
+        ],
+  };
+}
+
+function renderTextResult(result) {
+  const lines = [];
+  lines.push('throughline codex handoff start');
+  lines.push('');
+  lines.push(`  status:            ${result.status}`);
+  lines.push(`  reason:            ${result.reason}`);
+  lines.push(`  session:           ${result.sessionId}`);
+  lines.push(`  mutates thread:    ${result.mutatesCurrentThread ? 'yes' : 'no'}`);
+  lines.push(`  handoff smoke:     ${result.handoffSmoke.status}`);
+  lines.push(`  prompt chars:      ${result.handoffSmoke.promptChars}/${result.handoffSmoke.maxPromptChars}`);
+  lines.push(`  model prompt:      ${result.modelPromptChars}`);
+  if (result.memoReplayNote) {
+    lines.push(`  memo replay:       ${result.memoReplayNote}`);
+  }
+  lines.push('');
+  lines.push('  commands:');
+  lines.push(`    structural smoke:    ${result.commands.structuralSmoke}`);
+  lines.push(`    model smoke dry-run: ${result.commands.modelSmokeDryRun}`);
+  lines.push(`    render prompt:       ${result.commands.renderPrompt}`);
+  lines.push(`    live model smoke:    ${result.commands.liveModelSmoke}`);
+  lines.push('');
+  lines.push('  steps:');
+  for (const step of result.steps) {
+    lines.push(`    - ${step}`);
+  }
+  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-start] ${msg}\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-start] 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-start] no handoff memory found for session ${sessionId}\n`);
+    process.exit(1);
+  }
+
+  const smokeOptions = {
+    maxPromptChars: parsed.maxPromptChars,
+    maxDetailRefs: parsed.maxDetailRefs,
+    maxRecentBodies: parsed.maxRecentBodies,
+    maxBodyChars: parsed.maxBodyChars,
+  };
+  const handoffSmoke = buildCodexHandoffSmoke(record, smokeOptions);
+  const handoffPrompt = renderCodexNewThreadHandoff(record, {
+    maxDetailRefs: parsed.maxDetailRefs,
+    maxRecentBodies: parsed.maxRecentBodies,
+    maxBodyChars: parsed.maxBodyChars,
+  });
+  const result = buildGuidance({
+    sessionId,
+    parsed,
+    handoffSmoke,
+    handoffPrompt,
+  });
+  if (parsed.printPrompt) {
+    result.prompt = handoffPrompt;
+  }
+
+  if (parsed.json) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  else process.stdout.write(renderTextResult(result) + '\n');
+  process.exit(result.status === 'ready' ? 0 : 1);
+}
+
+export const _internal = {
+  parseArgs,
+  renderTextResult,
+};