throughline 0.4.10 → 0.4.12

package/src/cli/install.test.mjs

@@ -8,6 +8,7 @@ import {
   buildCodexPostToolUseHookCommand,
   buildCodexStopHookCommand,
   buildCodexUserPromptSubmitHookCommand,
+  resolveCodexHookNodePath,
   run,
   resolveThroughlineOnPath,
 } from './install.mjs';
@@ -123,13 +124,13 @@ test('global install registers Codex session hooks and enables hooks features',
       .flatMap(g => g.hooks ?? [])
       .find(h => h.command === expectedPromptCommand);
     assert.ok(promptHook, 'Codex UserPromptSubmit should have absolute throughline.mjs codex-hook user-prompt-submit');
-    assert.equal(promptHook.async, false, 'Codex UserPromptSubmit hook should be synchronous for context injection');
+    assert.equal(promptHook.async, false, 'Codex UserPromptSubmit hook should be synchronous for capture/monitor state');
     assert.equal(promptHook.timeoutSec, 30, 'Codex UserPromptSubmit hook should be short');
     const postToolUseHook = hooks.hooks.PostToolUse
       .flatMap(g => g.hooks ?? [])
       .find(h => h.command === expectedPostToolUseCommand);
     assert.ok(postToolUseHook, 'Codex PostToolUse should have absolute throughline.mjs codex-hook post-tool-use');
-    assert.equal(postToolUseHook.async, false, 'Codex PostToolUse hook should be synchronous for context injection');
+    assert.equal(postToolUseHook.async, false, 'Codex PostToolUse hook should be synchronous for capture/monitor state');
     assert.equal(postToolUseHook.timeoutSec, 30, 'Codex PostToolUse hook should be short');
     const config = readFileSync(join(home.dir, '.codex', 'config.toml'), 'utf8');
     assert.match(config, /^\[features\]\ncodex_hooks = true/m);
@@ -157,9 +158,10 @@ test('global install copies Throughline Codex skill to ~/.codex/skills/', async
     const metadataBody = readFileSync(metadata, 'utf8');
     assert.match(skillBody, /name: throughline/);
     assert.match(skillBody, /Bare "\$throughline"/);
-    assert.match(skillBody, /throughline trim --execute --host codex --all/);
-    assert.match(skillBody, /do not run doctor \/ dry-run \/ handoff \/ preflight first/);
-    assert.match(metadataBody, /scripted current-thread rollback \+ Throughline memory inject/);
+    assert.match(skillBody, /throughline codex-handoff-start --execute/);
+    assert.match(skillBody, /do not run doctor \/ dry-run \/ preflight first/);
+    assert.match(metadataBody, /start a new Codex thread with Throughline handoff memory/);
+    assert.doesNotMatch(metadataBody, /scripted current-thread rollback/);
     assert.doesNotMatch(metadataBody, /preview blocked Codex trim/);
     assert.doesNotMatch(metadataBody, /inspect guarded Codex trim/);
   } finally {
@@ -515,6 +517,38 @@ test('resolveThroughlineOnPath: finds throughline binary in PATH directory', ()
   }
 });
 
+test('resolveCodexHookNodePath: prefers a stable PATH node symlink when it resolves to current Node', () => {
+  const stableNode = join('/opt/homebrew/bin', process.platform === 'win32' ? 'node.exe' : 'node');
+  const cellarNode = join('/opt/homebrew/Cellar/node/26.0.0/bin', process.platform === 'win32' ? 'node.exe' : 'node');
+  const realNode = join('/opt/homebrew/Cellar/node/26.0.0/bin', process.platform === 'win32' ? 'node.exe' : 'node');
+  const result = resolveCodexHookNodePath({
+    env: { PATH: '/opt/homebrew/bin' },
+    execPath: cellarNode,
+    exists: (p) => p === stableNode,
+    realpath: (p) => {
+      if (p === stableNode || p === cellarNode) return realNode;
+      throw new Error(`unexpected path: ${p}`);
+    },
+  });
+  assert.equal(result, stableNode);
+});
+
+test('resolveCodexHookNodePath: falls back to process execPath when PATH node is different', () => {
+  const pathNode = join('/usr/local/bin', process.platform === 'win32' ? 'node.exe' : 'node');
+  const execPath = join('/opt/homebrew/Cellar/node/26.0.0/bin', process.platform === 'win32' ? 'node.exe' : 'node');
+  const result = resolveCodexHookNodePath({
+    env: { PATH: '/usr/local/bin' },
+    execPath,
+    exists: (p) => p === pathNode,
+    realpath: (p) => {
+      if (p === pathNode) return '/different/node';
+      if (p === execPath) return '/current/node';
+      throw new Error(`unexpected path: ${p}`);
+    },
+  });
+  assert.equal(result, execPath);
+});
+
 test('install is idempotent: second run keeps exactly one tl.md and one hook entry', async () => {
   const home = makeTempHome();
   if (home.resolved !== home.dir) {

package/src/codex-app-server.mjs

@@ -4,6 +4,7 @@ import { randomUUID } from 'node:crypto';
 export const CODEX_APP_SERVER_METHODS = Object.freeze({
   initialize: 'initialize',
   initialized: 'initialized',
+  threadStart: 'thread/start',
   threadRead: 'thread/read',
   threadResume: 'thread/resume',
   threadTurnsList: 'thread/turns/list',
@@ -125,6 +126,32 @@ export function buildInitializedNotification() {
   };
 }
 
+export function buildThreadStartRequest({
+  id,
+  cwd,
+  approvalPolicy = null,
+  sandbox = null,
+  model = null,
+  sessionStartSource = 'clear',
+}) {
+  assertRequestId(id, 'buildThreadStartRequest');
+  assertNonEmptyString(cwd, 'buildThreadStartRequest: cwd');
+  if (sessionStartSource !== 'startup' && sessionStartSource !== 'clear') {
+    throw new Error('buildThreadStartRequest: sessionStartSource must be startup or clear');
+  }
+  return {
+    id,
+    method: CODEX_APP_SERVER_METHODS.threadStart,
+    params: compactNullish({
+      cwd,
+      approvalPolicy,
+      sandbox,
+      model,
+      sessionStartSource,
+    }),
+  };
+}
+
 export function buildThreadReadRequest({ id, threadId, includeTurns = true }) {
   assertRequestId(id, 'buildThreadReadRequest');
   assertNonEmptyString(threadId, 'buildThreadReadRequest: threadId');
@@ -1406,6 +1433,116 @@ export async function runCodexRollbackModelVisibleVerify({
   }
 }
 
+export async function runCodexNewThreadHandoff({
+  cwd,
+  prompt,
+  command = 'codex',
+  commandArgs = ['app-server', '--listen', 'stdio://'],
+  timeoutMs = 120_000,
+  requestTimeoutMs = 60_000,
+  waitForTurn = true,
+  sessionStartSource = 'clear',
+  delivery = 'user-turn',
+} = {}) {
+  assertNonEmptyString(cwd, 'runCodexNewThreadHandoff: cwd');
+  assertNonEmptyString(prompt, 'runCodexNewThreadHandoff: prompt');
+  assertNonEmptyString(command, 'runCodexNewThreadHandoff: command');
+  if (!Array.isArray(commandArgs)) {
+    throw new Error('runCodexNewThreadHandoff: commandArgs must be an array');
+  }
+  if (sessionStartSource !== 'startup' && sessionStartSource !== 'clear') {
+    throw new Error('runCodexNewThreadHandoff: sessionStartSource must be startup or clear');
+  }
+  if (delivery !== 'user-turn' && delivery !== 'developer-item') {
+    throw new Error('runCodexNewThreadHandoff: delivery must be user-turn or developer-item');
+  }
+
+  const client = startAppServerClient({
+    command,
+    args: commandArgs,
+    cwd,
+    timeoutMs,
+    requestTimeoutMs,
+  });
+
+  try {
+    await initializeThroughlineAppServerClient(client, {
+      clientName: 'throughline-codex-new-thread-handoff',
+      clientTitle: 'Throughline Codex New Thread Handoff',
+    });
+
+    const threadStart = await client.request(
+      buildThreadStartRequest({
+        id: randomUUID(),
+        cwd,
+        sessionStartSource,
+      }),
+    );
+    const threadId = findThreadIdInAppServerPayload(threadStart);
+    if (!isCodexThreadId(threadId)) {
+      throw new Error(`thread/start did not return a Codex thread id: ${JSON.stringify(threadStart).slice(0, 500)}`);
+    }
+
+    if (delivery === 'developer-item') {
+      await client.request(
+        buildThreadInjectItemsRequest({
+          id: randomUUID(),
+          threadId,
+          items: [buildDeveloperMessageItem(prompt)],
+        }),
+      );
+      return {
+        status: 'started',
+        reason: 'new_thread_started_and_developer_memory_injected',
+        threadId,
+        delivery,
+        injectSent: true,
+        turnStatus: 'not-started',
+        notifications: [...new Set(client.notifications)],
+        agentText: collectAgentText(client.notificationEvents),
+        stderr: client.stderr,
+      };
+    }
+
+    await client.request(buildTurnStartRequest({ id: randomUUID(), threadId, text: prompt }));
+    const observedTurnEvent = waitForTurn
+      ? await client.waitForNotification({
+          predicate: (event) => event.method === 'turn/completed' || event.method === 'turn/failed',
+          timeoutMs: requestTimeoutMs,
+        })
+      : null;
+    const turnStatus =
+      observedTurnEvent?.method === 'turn/completed'
+        ? 'completed'
+        : observedTurnEvent?.method === 'turn/failed'
+          ? 'failed'
+          : waitForTurn
+            ? 'timeout'
+            : 'unchecked';
+
+    return {
+      status: turnStatus === 'failed' || turnStatus === 'timeout' ? 'started-unverified' : 'started',
+      reason:
+        turnStatus === 'completed'
+          ? 'new_thread_started_and_turn_completed'
+          : turnStatus === 'failed'
+            ? 'new_thread_started_but_turn_failed'
+            : turnStatus === 'timeout'
+              ? 'new_thread_started_but_turn_completion_not_observed'
+              : 'new_thread_started_without_waiting_for_turn',
+      threadId,
+      delivery,
+      injectSent: false,
+      turnStatus,
+      notifications: [...new Set(client.notifications)],
+      agentText: collectAgentText(client.notificationEvents),
+      stderr: client.stderr,
+    };
+  } finally {
+    await client.close();
+  }
+}
+
 function initializeThroughlineAppServerClient(client, { clientName, clientTitle }) {
   return client
     .request(
@@ -1427,6 +1564,25 @@ function extractRollbackModelVisibleMarkers(text, markerPrefix) {
   return [...new Set(text.match(pattern) ?? [])];
 }
 
+function findThreadIdInAppServerPayload(value) {
+  if (!isRecord(value)) return null;
+  if (isCodexThreadId(value.id)) return value.id;
+  if (isCodexThreadId(value.threadId)) return value.threadId;
+  if (isRecord(value.thread)) {
+    const nested = findThreadIdInAppServerPayload(value.thread);
+    if (nested) return nested;
+  }
+  if (isRecord(value.params)) {
+    const nested = findThreadIdInAppServerPayload(value.params);
+    if (nested) return nested;
+  }
+  return null;
+}
+
+function isCodexThreadId(value) {
+  return typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+}
+
 async function waitForThreadTurnCount({ client, threadId, expectedTurns, attempts, delayMs }) {
   let lastTurns = null;
   for (let attempt = 1; attempt <= attempts; attempt++) {

package/src/codex-app-server.test.mjs

@@ -14,6 +14,7 @@ import {
   buildThreadReadRequest,
   buildThreadResumeRequest,
   buildThreadRollbackRequest,
+  buildThreadStartRequest,
   buildThreadTurnsListRequest,
   buildTurnStartRequest,
   compareTurnCounts,
@@ -21,6 +22,7 @@ import {
   parseAppServerLine,
   resolveRollbackTurnsForAppServer,
   runCodexModelVisibilitySmoke,
+  runCodexNewThreadHandoff,
   runCodexRollbackModelVisiblePrepare,
   runCodexRollbackModelVisibleVerify,
   runCodexTrimPreflight,
@@ -85,6 +87,12 @@ test('buildInitializeRequest opts into the experimental app-server API', () => {
 
 test('thread request builders encode the verified rollback/inject flow', () => {
   const threadId = 'thread-1';
+  assert.deepEqual(buildThreadStartRequest({ id: 'start-1', cwd: '/repo' }), {
+    id: 'start-1',
+    method: CODEX_APP_SERVER_METHODS.threadStart,
+    params: { cwd: '/repo', sessionStartSource: 'clear' },
+  });
+
   assert.deepEqual(buildThreadReadRequest({ id: 1, threadId }), {
     id: 1,
     method: CODEX_APP_SERVER_METHODS.threadRead,