throughline 0.4.9 → 0.4.11

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');
@@ -209,6 +236,48 @@ export function buildThreadRollbackRequest({ id, threadId, numTurns }) {
   };
 }
 
+export function resolveRollbackTurnsForAppServer({
+  plannedRollbackTurns,
+  expectedTurns = null,
+  readTurns = null,
+  resumedTurns = null,
+} = {}) {
+  if (!Number.isInteger(plannedRollbackTurns) || plannedRollbackTurns < 1) {
+    throw new Error('resolveRollbackTurnsForAppServer: plannedRollbackTurns must be an integer >= 1');
+  }
+  assertOptionalTurnCount(expectedTurns, 'resolveRollbackTurnsForAppServer: expectedTurns');
+
+  const result = {
+    plannedRollbackTurns,
+    requestedRollbackTurns: plannedRollbackTurns,
+    adjustment: 0,
+    basis: 'planned',
+    reason: 'using_planned_rollback_turns',
+  };
+
+  if (
+    Number.isInteger(expectedTurns) &&
+    Number.isInteger(readTurns) &&
+    Number.isInteger(resumedTurns) &&
+    readTurns === resumedTurns &&
+    readTurns !== expectedTurns
+  ) {
+    const adjustment = readTurns - expectedTurns;
+    const adjustedTurns = plannedRollbackTurns + adjustment;
+    if (adjustedTurns >= 1) {
+      return {
+        plannedRollbackTurns,
+        requestedRollbackTurns: Math.min(adjustedTurns, readTurns),
+        adjustment,
+        basis: 'app_server_turn_count',
+        reason: 'adjusted_by_app_server_turn_delta',
+      };
+    }
+  }
+
+  return result;
+}
+
 export function buildThreadInjectItemsRequest({ id, threadId, items }) {
   assertRequestId(id, 'buildThreadInjectItemsRequest');
   assertNonEmptyString(threadId, 'buildThreadInjectItemsRequest: threadId');
@@ -313,6 +382,12 @@ export async function runCodexTrimPreflight({
     );
     const readTurns = countTurns(beforeRead);
     const resumedTurns = countTurns(resumed);
+    const rollbackResolution = resolveRollbackTurnsForAppServer({
+      plannedRollbackTurns: rollbackTurns,
+      expectedTurns,
+      readTurns,
+      resumedTurns,
+    });
 
     return {
       status: 'preflight-ready',
@@ -321,6 +396,8 @@ export async function runCodexTrimPreflight({
       injectSent: false,
       readTurns,
       resumedTurns,
+      rollbackRequestedTurns: rollbackResolution.requestedRollbackTurns,
+      rollbackResolution,
       turnCountCheck: compareTurnCounts({
         expectedTurns,
         readTurns,
@@ -329,7 +406,7 @@ export async function runCodexTrimPreflight({
       rollbackRequestPreview: buildThreadRollbackRequest({
         id: 'rollback-preview',
         threadId,
-        numTurns: rollbackTurns,
+        numTurns: rollbackResolution.requestedRollbackTurns,
       }),
       notifications: [...new Set(client.notifications)],
       stderr: client.stderr,
@@ -964,27 +1041,17 @@ export async function runCodexTrimExecution({
       readTurns,
       resumedTurns,
     });
-    if (turnCountCheck.status === 'mismatch' || turnCountCheck.status === 'unknown') {
-      return {
-        status: 'refused',
-        reason: 'codex_rollout_app_server_turn_mismatch',
-        threadId,
-        rollbackSent: false,
-        injectSent: false,
-        injectedItems: 0,
-        readTurns,
-        resumedTurns,
-        rollbackRequestedTurns: rollbackTurns,
-        turnCountCheck,
-        notifications: [...new Set(client.notifications)],
-        stderr: client.stderr,
-      };
-    }
+    const rollbackResolution = resolveRollbackTurnsForAppServer({
+      plannedRollbackTurns: rollbackTurns,
+      expectedTurns,
+      readTurns,
+      resumedTurns,
+    });
     const rollback = await client.request(
       buildThreadRollbackRequest({
         id: randomUUID(),
         threadId,
-        numTurns: rollbackTurns,
+        numTurns: rollbackResolution.requestedRollbackTurns,
       }),
     );
     const inject = await client.request(
@@ -1016,7 +1083,8 @@ export async function runCodexTrimExecution({
       injectedItems: 1,
       readTurns,
       resumedTurns,
-      rollbackRequestedTurns: rollbackTurns,
+      rollbackRequestedTurns: rollbackResolution.requestedRollbackTurns,
+      rollbackResolution,
       rollbackResultTurns,
       injectResultTurns,
       afterTurns: postInjectRead.turns,
@@ -1365,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(
@@ -1386,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,12 +14,15 @@ import {
   buildThreadReadRequest,
   buildThreadResumeRequest,
   buildThreadRollbackRequest,
+  buildThreadStartRequest,
   buildThreadTurnsListRequest,
   buildTurnStartRequest,
   compareTurnCounts,
   encodeAppServerMessage,
   parseAppServerLine,
+  resolveRollbackTurnsForAppServer,
   runCodexModelVisibilitySmoke,
+  runCodexNewThreadHandoff,
   runCodexRollbackModelVisiblePrepare,
   runCodexRollbackModelVisibleVerify,
   runCodexTrimPreflight,
@@ -84,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,
@@ -203,6 +212,50 @@ test('compareTurnCounts: rejects invalid expected turn count', () => {
   );
 });
 
+test('resolveRollbackTurnsForAppServer adjusts planned rollback by app-server turn delta', () => {
+  assert.deepEqual(
+    resolveRollbackTurnsForAppServer({
+      plannedRollbackTurns: 6,
+      expectedTurns: 6,
+      readTurns: 7,
+      resumedTurns: 7,
+    }),
+    {
+      plannedRollbackTurns: 6,
+      requestedRollbackTurns: 7,
+      adjustment: 1,
+      basis: 'app_server_turn_count',
+      reason: 'adjusted_by_app_server_turn_delta',
+    },
+  );
+
+  assert.deepEqual(
+    resolveRollbackTurnsForAppServer({
+      plannedRollbackTurns: 2,
+      expectedTurns: 22,
+      readTurns: 21,
+      resumedTurns: 21,
+    }),
+    {
+      plannedRollbackTurns: 2,
+      requestedRollbackTurns: 1,
+      adjustment: -1,
+      basis: 'app_server_turn_count',
+      reason: 'adjusted_by_app_server_turn_delta',
+    },
+  );
+
+  assert.equal(
+    resolveRollbackTurnsForAppServer({
+      plannedRollbackTurns: 6,
+      expectedTurns: 6,
+      readTurns: 7,
+      resumedTurns: 8,
+    }).requestedRollbackTurns,
+    6,
+  );
+});
+
 test('summarizeAppServerStderr: compacts repeated unknown-turn item warnings', () => {
   const stderr = [
     '2026-05-06T00:00:00Z  WARN codex_app_server_protocol::protocol::thread_history: dropping turn-scoped item for unknown turn id `turn-a` item_id="call_1"',