@jskit-ai/assistant-core 0.1.199 → 0.1.201

package/src/server/conversation/codexDetachedTurn.js

@@ -0,0 +1,332 @@
+import { normalizeText, isPlainObject } from "./normalize.js";
+import { classifyCodexAppServerEvent, codexAppServerNotificationParams, codexAppServerNotificationThreadId, codexAppServerNotificationTurnId, codexAppServerNotificationTurnStatus, codexAppServerNotificationError, codexAppServerStatusFromValue, codexAppServerProviderThreadAssistantSegments, codexAppServerProviderTurnId, codexAppServerProviderTurnStatus, codexAppServerProviderTurnForOperation, codexAppServerProviderTurnText, codexAppServerProviderTurnError } from "./codexEvents.js";
+import { codexAppServerTurnStatusIsProviderFailure, codexAppServerTurnStatusIsSuccessfulComplete } from "./codexTurnState.js";
+
+const CODEX_APP_SERVER_DETACHED_TURN_TIMEOUT_MS = 180_000;
+const CODEX_APP_SERVER_DETACHED_FAILURE_DETAIL_GRACE_MS = 500;
+
+function codexAppServerTurnTokenUsage(notification = {}) {
+  if (normalizeText(notification.method) !== "thread/tokenUsage/updated") {
+    return null;
+  }
+  const params = codexAppServerNotificationParams(notification);
+  const tokenUsage = isPlainObject(params.tokenUsage) ? params.tokenUsage : {};
+  const turnUsage = isPlainObject(tokenUsage.last) ? tokenUsage.last : tokenUsage;
+  const snapshot = {};
+  for (const field of [
+    "cachedInputTokens",
+    "cacheWriteInputTokens",
+    "inputTokens",
+    "outputTokens",
+    "reasoningOutputTokens",
+    "totalTokens"
+  ]) {
+    const value = Number(turnUsage[field]);
+    if (Number.isSafeInteger(value) && value >= 0) {
+      snapshot[field] = value;
+    }
+  }
+  return Object.keys(snapshot).length ? Object.freeze(snapshot) : null;
+}
+
+function createCodexAppServerDetachedTurnWatcher(provider = null, threadId = "", {
+  includeThreadHistory = true,
+  allowEmptyResponse = false,
+  onEvent = null,
+  timeoutMs = CODEX_APP_SERVER_DETACHED_TURN_TIMEOUT_MS
+} = {}) {
+  const normalizedThreadId = normalizeText(threadId);
+  let targetTurnId = "";
+  let finalText = "";
+  let usage = null;
+  let failureDetailTimeout = null;
+  let settled = false;
+  let timeout = null;
+  let connectionCheck = null;
+  let unsubscribe = null;
+  let pendingCompletionStatus = "";
+  let pendingFailure = null;
+  let resolveWaiter = null;
+  let rejectWaiter = null;
+
+  function cleanup() {
+    clearTimeout(timeout);
+    timeout = null;
+    clearInterval(connectionCheck);
+    connectionCheck = null;
+    clearTimeout(failureDetailTimeout);
+    failureDetailTimeout = null;
+    unsubscribe?.();
+    unsubscribe = null;
+  }
+
+  function finish(result = {}) {
+    if (settled) {
+      return;
+    }
+    settled = true;
+    cleanup();
+    resolveWaiter?.(result);
+  }
+
+  function fail(error) {
+    if (settled) {
+      return;
+    }
+    settled = true;
+    cleanup();
+    rejectWaiter?.(error);
+  }
+
+  function emitWatcherEvent(classification = {}, notification) {
+    if (typeof onEvent !== "function" || !classification?.kind) {
+      return;
+    }
+    onEvent({
+      ...classification,
+      threadId: classification.threadId || normalizedThreadId,
+      turnId: classification.turnId || targetTurnId
+    }, notification);
+  }
+
+  async function resultFromThread() {
+    if (
+      !includeThreadHistory ||
+      !normalizedThreadId ||
+      !targetTurnId ||
+      typeof provider?.readThread !== "function"
+    ) {
+      return {
+        status: "",
+        statusType: "",
+        text: ""
+      };
+    }
+    const thread = await provider.readThread(normalizedThreadId);
+    const rawStatus = thread.raw?.status || thread.response?.thread?.status;
+    return {
+      status: codexAppServerStatusFromValue(rawStatus),
+      statusType: normalizeText(typeof rawStatus === "string" ? rawStatus : rawStatus?.type),
+      text: codexAppServerProviderThreadAssistantSegments(thread, targetTurnId)
+        .map((segment) => segment.text)
+        .join("\n\n")
+    };
+  }
+
+  function failAfterDetailGrace(error) {
+    if (settled || failureDetailTimeout) {
+      return;
+    }
+    failureDetailTimeout = setTimeout(() => {
+      failureDetailTimeout = null;
+      fail(error);
+    }, CODEX_APP_SERVER_DETACHED_FAILURE_DETAIL_GRACE_MS);
+  }
+
+  async function finishFromCompletion(status = "completed") {
+    try {
+      if (!targetTurnId) {
+        pendingCompletionStatus = normalizeText(status) || "completed";
+        return;
+      }
+      const authoritative = await resultFromThread().catch(() => ({
+        status: "",
+        statusType: "",
+        text: ""
+      }));
+      finalText = authoritative.text || finalText;
+      if (!finalText && !allowEmptyResponse) {
+        pendingCompletionStatus = normalizeText(status) || "completed";
+        const systemError = authoritative.statusType === "systemError" || authoritative.status === "failed";
+        failAfterDetailGrace(new Error(systemError
+          ? "Codex app-server thread entered a system error before producing an assistant response."
+          : "Codex app-server completed without producing an assistant response."));
+        return;
+      }
+      finish({
+        status,
+        text: finalText,
+        threadId: normalizedThreadId,
+        turnId: targetTurnId,
+        usage
+      });
+    } catch (error) {
+      fail(error);
+    }
+  }
+
+  function notificationMatches(notification = {}) {
+    const notificationThreadId = codexAppServerNotificationThreadId(notification);
+    if (notificationThreadId && notificationThreadId !== normalizedThreadId) {
+      return false;
+    }
+    const notificationTurnId = codexAppServerNotificationTurnId(notification);
+    return !targetTurnId || !notificationTurnId || notificationTurnId === targetTurnId;
+  }
+
+  return {
+    async completeNow(status = "completed") {
+      await finishFromCompletion(status);
+    },
+    failNow(error) {
+      fail(error);
+    },
+    failAfterDetailGrace(error) {
+      failAfterDetailGrace(error);
+    },
+    setTurnId(turnId = "") {
+      targetTurnId = normalizeText(turnId);
+      if (pendingFailure) {
+        failAfterDetailGrace(pendingFailure);
+        return;
+      }
+      if (pendingCompletionStatus) {
+        const status = pendingCompletionStatus;
+        pendingCompletionStatus = "";
+        void finishFromCompletion(status);
+      }
+    },
+    wait() {
+      if (settled) {
+        return Promise.reject(new Error("Codex app-server detached turn watcher was already settled."));
+      }
+      return new Promise((resolve, reject) => {
+        resolveWaiter = resolve;
+        rejectWaiter = reject;
+        if (timeoutMs > 0) {
+          timeout = setTimeout(() => {
+            fail(new Error("Timed out waiting for Codex app-server response."));
+          }, timeoutMs);
+        } else {
+          // Interactive repair turns may take longer than bounded helper jobs.
+          // Retain their watcher until completion, interruption, or connection loss.
+          const generation = provider?.currentConnectionGeneration?.();
+          connectionCheck = setInterval(() => {
+            if (provider?.isAvailable?.() === false ||
+              provider?.currentConnectionGeneration?.() !== generation) {
+              fail(new Error("Connection to Codex was lost while the temporary AI was working."));
+            }
+          }, 1000);
+          connectionCheck.unref?.();
+        }
+        unsubscribe = typeof provider?.subscribe === "function"
+          ? provider.subscribe((notification = {}) => {
+              if (!notificationMatches(notification)) {
+                return;
+              }
+              usage = codexAppServerTurnTokenUsage(notification) || usage;
+              const classification = classifyCodexAppServerEvent(notification);
+              emitWatcherEvent(classification, notification);
+              if (
+                classification.kind === "provider_error" &&
+                classification.text &&
+                codexAppServerNotificationParams(notification).willRetry !== true
+              ) {
+                const error = new Error(classification.text);
+                if (!targetTurnId) {
+                  pendingFailure = error;
+                  return;
+                }
+                fail(error);
+                return;
+              }
+              if (classification.kind === "final_assistant_result" && classification.text) {
+                finalText = classification.text;
+                if (pendingCompletionStatus && targetTurnId) {
+                  const status = pendingCompletionStatus;
+                  pendingCompletionStatus = "";
+                  clearTimeout(failureDetailTimeout);
+                  failureDetailTimeout = null;
+                  void finishFromCompletion(status);
+                }
+              }
+              const method = normalizeText(notification.method);
+              if (method !== "turn/completed" && method !== "thread/status/changed") {
+                return;
+              }
+              const status = codexAppServerNotificationTurnStatus(notification) || "completed";
+              if (codexAppServerTurnStatusIsProviderFailure(status)) {
+                const error = new Error(codexAppServerNotificationError(notification) || `Codex app-server turn ${status}.`);
+                if (!targetTurnId) {
+                  pendingFailure = error;
+                  return;
+                }
+                failAfterDetailGrace(error);
+                return;
+              }
+              if (codexAppServerTurnStatusIsSuccessfulComplete(status)) {
+                void finishFromCompletion(status);
+              }
+            })
+          : null;
+      });
+    }
+  };
+}
+
+function codexAppServerTurnError(reason, details = {}, providerMessage = "") {
+  const retryable = reason === "failed";
+  const error = new Error(providerMessage || (reason === "identity_missing"
+    ? "Codex did not return the exact turn identity."
+    : `Codex app-server turn ${details.status}.`));
+  error.code = `codex_app_server_turn_${reason}`;
+  error.details = { ...details, retryable };
+  error.retryable = retryable;
+  return error;
+}
+
+async function waitForCodexAppServerTurn(provider, threadId = "", turn = null, {
+  timeoutMs = CODEX_APP_SERVER_DETACHED_TURN_TIMEOUT_MS,
+  createError = codexAppServerTurnError
+} = {}) {
+  const normalizedThreadId = normalizeText(threadId || "");
+  const turnId = codexAppServerProviderTurnId(turn || {});
+  const status = codexAppServerProviderTurnStatus(turn || {});
+  if (!normalizedThreadId || !turnId) {
+    throw createError("identity_missing", { threadId: normalizedThreadId, turnId });
+  }
+  if (codexAppServerTurnStatusIsProviderFailure(status)) {
+    throw createError(
+      "failed",
+      { status, threadId: normalizedThreadId, turnId },
+      codexAppServerProviderTurnError(turn || {})
+    );
+  }
+  const existingText = codexAppServerProviderTurnText({
+    raw: { turns: [turn] }
+  }, turnId);
+  if (codexAppServerTurnStatusIsSuccessfulComplete(status) && existingText) {
+    return {
+      status,
+      text: existingText,
+      threadId: normalizedThreadId,
+      turnId,
+      usage: null
+    };
+  }
+  const watcher = createCodexAppServerDetachedTurnWatcher(provider, normalizedThreadId, {
+    timeoutMs
+  });
+  watcher.setTurnId(turnId);
+  const pending = watcher.wait();
+  void pending.catch(() => null);
+  if (codexAppServerTurnStatusIsSuccessfulComplete(status)) {
+    await watcher.completeNow(status);
+  } else if (typeof provider?.readThread === "function") {
+    const latestThread = await provider.readThread(normalizedThreadId);
+    const latestTurn = codexAppServerProviderTurnForOperation(latestThread, { turnId });
+    const latestStatus = codexAppServerProviderTurnStatus(latestTurn || {});
+    if (codexAppServerTurnStatusIsProviderFailure(latestStatus)) {
+      watcher.failNow(createError(
+        "failed",
+        { status: latestStatus, threadId: normalizedThreadId, turnId },
+        codexAppServerProviderTurnError(latestTurn || {})
+      ));
+    } else if (codexAppServerTurnStatusIsSuccessfulComplete(latestStatus)) {
+      await watcher.completeNow(latestStatus);
+    }
+  }
+  return pending;
+}
+
+export { CODEX_APP_SERVER_DETACHED_TURN_TIMEOUT_MS, createCodexAppServerDetachedTurnWatcher, waitForCodexAppServerTurn };

package/src/server/conversation/codexEvents.js

@@ -3,6 +3,61 @@ import {
   normalizeText
 } from "./normalize.js";
 
+const CODEX_TOKEN_USAGE_METHOD = "thread/tokenUsage/updated";
+
+function nonNegativeInteger(value) {
+  if (value === null || value === undefined || String(value).trim() === "") {
+    return null;
+  }
+  const number = Number(value);
+  return Number.isSafeInteger(number) && number >= 0 ? number : null;
+}
+
+function codexContextUsageFromNotification(notification = {}) {
+  if (normalizeText(notification?.method) !== CODEX_TOKEN_USAGE_METHOD) {
+    return null;
+  }
+  const params = notification?.params && typeof notification.params === "object"
+    ? notification.params
+    : {};
+  const tokenUsage = params.tokenUsage && typeof params.tokenUsage === "object"
+    ? params.tokenUsage
+    : {};
+  const last = tokenUsage.last && typeof tokenUsage.last === "object"
+    ? tokenUsage.last
+    : {};
+  const total = tokenUsage.total && typeof tokenUsage.total === "object"
+    ? tokenUsage.total
+    : {};
+  const usedTokens = nonNegativeInteger(last.totalTokens);
+  const inputTokens = nonNegativeInteger(last.inputTokens);
+  const cumulativeTokens = nonNegativeInteger(total.totalTokens);
+  const windowTokens = nonNegativeInteger(tokenUsage.modelContextWindow);
+  const threadId = normalizeText(params.threadId);
+  const turnId = normalizeText(params.turnId);
+  if (
+    !threadId ||
+    !turnId ||
+    usedTokens === null ||
+    inputTokens === null ||
+    cumulativeTokens === null ||
+    !windowTokens ||
+    usedTokens > windowTokens ||
+    inputTokens > usedTokens ||
+    cumulativeTokens < usedTokens
+  ) {
+    return null;
+  }
+  return Object.freeze({
+    cumulativeTokens,
+    inputTokens,
+    threadId,
+    turnId,
+    usedTokens,
+    windowTokens
+  });
+}
+
 const CODEX_APP_SERVER_CONTEXT_COMPACTION_SIGNALS = new Set(
   [
     "contextcompaction",
@@ -346,6 +401,11 @@ function classifyCodexAppServerEvent(notification = {}) {
     threadId: codexAppServerNotificationThreadId(notification),
     turnId: codexAppServerNotificationTurnId(notification)
   };
+  if (itemType === "contextCompaction" && (method === "item/started" || method === "item/completed")) {
+    base.phase = method === "item/started" ? "compacting" : "working";
+  } else if (method === "error" && codexAppServerNotificationParams(notification).willRetry === true) {
+    base.phase = "retrying";
+  }
 
   if (method === "item/agentMessage/delta") {
     const { delta } = codexAppServerNotificationParams(notification);
@@ -376,6 +436,7 @@ function classifyCodexAppServerEvent(notification = {}) {
     return {
       ...base,
       kind: "reasoning_summary",
+      delta: codexAppServerContentText(codexAppServerNotificationParams(notification).delta),
       text: normalizeText(codexAppServerContentText(codexAppServerNotificationParams(notification).delta))
     };
   }
@@ -462,6 +523,7 @@ function classifyCodexAppServerEvent(notification = {}) {
     return {
       ...base,
       kind: "status",
+      ...(codexAppServerNotificationTurnStatus(notification) === "inProgress" ? { phase: "working" } : {}),
       text: codexAppServerNotificationTurnStatus(notification)
     };
   }
@@ -544,7 +606,7 @@ function codexAppServerProviderThread(value = {}) {
 }
 
 function codexAppServerProviderTurnId(turn = {}) {
-  return normalizeText(turn.id || turn.turnId || turn.turn_id || turn.turn?.id);
+  return normalizeText(turn.id || turn.turnId || turn.turn_id || turn.turn?.id || "");
 }
 
 function codexAppServerProviderTurnItems(turn = {}) {
@@ -623,8 +685,139 @@ function codexAppServerOutputOwnerTurnId({
     : normalizeText(notificationTurnId);
 }
 
+function codexAppServerThreadRawValue(thread = {}) {
+  if (isPlainObject(thread.raw)) {
+    return thread.raw;
+  }
+  if (isPlainObject(thread.response?.thread)) {
+    return thread.response.thread;
+  }
+  return isPlainObject(thread) ? thread : {};
+}
+
+function codexAppServerThreadTurnId(thread = {}) {
+  const observedTurnId = normalizeText(thread.observedTurn?.id || "");
+  if (observedTurnId) {
+    return observedTurnId;
+  }
+  const rawThread = codexAppServerThreadRawValue(thread);
+  const status = isPlainObject(rawThread.status) ? rawThread.status : {};
+  return normalizeText(
+    thread.turnId ||
+    thread.turn_id ||
+    thread.turn?.id ||
+    rawThread.turnId ||
+    rawThread.turn_id ||
+    rawThread.turn?.id ||
+    rawThread.currentTurnId ||
+    rawThread.current_turn_id ||
+    rawThread.activeTurnId ||
+    rawThread.active_turn_id ||
+    status.turnId ||
+    status.turn_id ||
+    status.turn?.id ||
+    status.currentTurnId ||
+    status.current_turn_id ||
+    status.activeTurnId ||
+    status.active_turn_id ||
+    ""
+  );
+}
+
+function codexAppServerThreadError(thread = {}) {
+  const rawThread = codexAppServerThreadRawValue(thread);
+  const status = isPlainObject(rawThread.status) ? rawThread.status : {};
+  return codexAppServerErrorText(rawThread.error || status.error);
+}
+
+function codexAppServerProviderThreadTurns(thread = null) {
+  const rawThread = codexAppServerThreadRawValue(thread || {});
+  return (Array.isArray(rawThread.turns) ? rawThread.turns : [])
+    .filter((turn) => isPlainObject(turn));
+}
+
+function codexAppServerProviderTurnStatus(turn = {}) {
+  return codexAppServerStatusFromValue(turn.status || turn.state);
+}
+
+function codexAppServerProviderTurnClientIds(turn = {}) {
+  return codexAppServerProviderTurnItems(turn)
+    .map((item) => normalizeText(
+      item.clientId ||
+      item.client_id ||
+      item.clientUserMessageId ||
+      item.client_user_message_id ||
+      ""
+    ))
+    .filter(Boolean);
+}
+
+function codexAppServerProviderTurnForOperation(thread = null, {
+  clientMessageId = "",
+  turnId = ""
+} = {}) {
+  const normalizedTurnId = normalizeText(turnId || "");
+  const normalizedClientMessageId = normalizeText(clientMessageId || "");
+  const turns = codexAppServerProviderThreadTurns(thread);
+  if (normalizedTurnId) {
+    return turns.find((turn) => (
+      codexAppServerProviderTurnId(turn) === normalizedTurnId
+    )) || null;
+  }
+  if (!normalizedClientMessageId) {
+    return null;
+  }
+  return [...turns].reverse().find((turn) => (
+    codexAppServerProviderTurnClientIds(turn).includes(normalizedClientMessageId)
+  )) || null;
+}
+
+// Native snapshot matching from the original renewal handover/seed paths.
+// The application projects these classifications into its approval/error policy.
+function inspectCodexAppServerRenewalThread(thread = null, {
+  clientMessageId = "",
+  turnId: expectedTurnId = "",
+  requireFresh = false
+} = {}) {
+  const snapshotTurns = codexAppServerProviderThreadTurns(thread);
+  const targetTurn = codexAppServerProviderTurnForOperation(thread, {
+    clientMessageId,
+    turnId: expectedTurnId
+  });
+  if (expectedTurnId && !targetTurn) return { targetTurn, failure: "turn_missing" };
+  if (!requireFresh && !targetTurn && snapshotTurns.length === 0) return { targetTurn, failure: "history_missing" };
+  if (requireFresh && snapshotTurns.some((turn) => (
+    !targetTurn || codexAppServerProviderTurnId(turn) !== codexAppServerProviderTurnId(targetTurn)
+  ))) return { targetTurn, failure: "unrelated_history" };
+  return { targetTurn, failure: "" };
+}
+
+function codexAppServerProviderTurnText(thread = null, turnId = "") {
+  return codexAppServerProviderThreadAssistantSegments(thread || {}, turnId)
+    .map((segment) => segment.text)
+    .join("\n\n")
+    .trim();
+}
+
+function codexAppServerProviderTurnError(turn = {}) {
+  return codexAppServerErrorText(turn.error || turn.status?.error || turn.state?.error);
+}
+
 export {
+  codexContextUsageFromNotification,
   classifyCodexAppServerEvent,
+  codexAppServerThreadRawValue,
+  codexAppServerThreadTurnId,
+  codexAppServerThreadError,
+  codexAppServerProviderThreadTurns,
+  codexAppServerProviderTurnId,
+  codexAppServerProviderTurnStatus,
+  codexAppServerProviderTurnItems,
+  codexAppServerProviderTurnClientIds,
+  codexAppServerProviderTurnForOperation,
+  inspectCodexAppServerRenewalThread,
+  codexAppServerProviderTurnText,
+  codexAppServerProviderTurnError,
   codexAppServerAssistantItemText,
   codexAppServerContentText,
   codexAppServerContextRefreshReason,

package/src/server/conversation/codexGoalCommands.js

@@ -0,0 +1,124 @@
+import { CODEX_APP_SERVER_AGENT_RUN_ID } from "./codexTurnState.js";
+
+// Private composition of unchanged operations from the original run owner.
+export function createCodexGoalCommands({
+  conversationContext,
+  ensureThreadReady,
+  publish,
+  readCodexAppServerAgentRunForSession,
+  reconcileCodexAppServerGoalUpdated,
+  submitCodexAppServerAssistantResult,
+  subscribeCodexAppServerEvents,
+  turnState
+}) {
+  async function prepareCodexAppServerGoalContext(sessionId, options, preparation, { prepareThread = false } = {}) {
+    let context;
+    if (prepareThread) {
+      const prepared = await preparation.readiness(ensureThreadReady);
+      if (prepared.ok === false) return prepared;
+      context = await conversationContext(sessionId, {}, {});
+    } else {
+      // This is the current command's authorized context. Goal controls
+      // may deliberately retain a pinned selection after a model switch.
+      context = await conversationContext(sessionId, {}, options === undefined ? {} : options);
+    }
+    return preparation.project(context, options);
+  }
+
+  function validateCodexAppServerGoalInput(input = {}) {
+    if (!["set", "pause", "resume", "cancel"].includes(input.action)) {
+      return { ok: false, error: "Choose set, pause, resume, or cancel." };
+    }
+    if (input.action === "set" && (typeof input.objective !== "string" || !input.objective.trim() ||
+        (input.tokenBudget !== undefined && (!Number.isSafeInteger(input.tokenBudget) || input.tokenBudget <= 0)))) {
+      return { ok: false, error: "Enter a goal objective and an optional positive whole-number token budget." };
+    }
+    return null;
+  }
+
+  async function updateCodexAppServerGoal(sessionId, input = {}, {
+    context: initialContext,
+    prepareConversation
+  } = {}) {
+    let context = initialContext;
+    if (context.ok === false) return context;
+    let threadId = context.threadId;
+    if (threadId !== input.threadId || (!threadId && input.action !== "set")) {
+      return { ok: false, error: "The Codex conversation changed. Refresh the goal before trying again." };
+    }
+    if (input.action === "set") {
+      if (turnState(context.session).status === "observation_lost") {
+        return { ok: false, error: "Resume or send a message to restore the stopped conversation before setting a goal." };
+      }
+      if (!threadId) {
+        context = await prepareConversation();
+        if (context.ok === false) return context;
+        threadId = context.threadId;
+      }
+      const { goal: previousGoal } = await context.provider.readGoal(threadId);
+      if (previousGoal && (previousGoal.status !== "complete" || previousGoal.createdAt !== input.createdAt)) {
+        return { ok: false, error: "The Codex goal changed. Refresh it before setting a new goal." };
+      }
+      subscribeCodexAppServerEvents(sessionId, context.provider, threadId, context);
+      const result = await context.provider.setGoal(threadId, {
+        objective: input.objective, tokenBudget: input.tokenBudget
+      });
+      await reconcileCodexAppServerGoalUpdated(sessionId, context.provider, threadId, {
+        params: { goal: result.goal }
+      });
+      await publish(sessionId, { reason: "codex-goal", nativeGoal: { threadId, goal: result.goal || null } });
+      return { ok: true, status: "available", threadId, goal: result.goal || null };
+    }
+    const { goal } = await context.provider.readGoal(threadId);
+    if (!goal || goal.status === "complete" || goal.createdAt !== input.createdAt || goal.objective !== input.objective) {
+      return { ok: false, error: "The Codex goal changed. Refresh it before trying again." };
+    }
+    if (input.action === "cancel") {
+      subscribeCodexAppServerEvents(sessionId, context.provider, threadId, context);
+      await context.provider.clearGoal(threadId);
+      await reconcileCodexAppServerGoalUpdated(sessionId, context.provider, threadId, {
+        method: "thread/goal/cleared",
+        params: { threadId }
+      });
+      await publish(sessionId, { reason: "codex-goal", nativeGoal: { threadId, goal: null } });
+      return { ok: true, status: "available", threadId, goal: null };
+    }
+    if (input.action === "pause" && !["active", "paused"].includes(goal.status)) {
+      return { ok: false, error: "This goal is already stopped. Refresh its details." };
+    }
+    const observationLost = turnState(context.session).status === "observation_lost";
+    if (observationLost && turnState(context.session).active) {
+      return { ok: false, error: "Codex has not yet confirmed a stop. Retry after the service has stopped." };
+    }
+    if (input.action === "resume" && !["paused", "blocked", "usageLimited", ...(observationLost ? ["active"] : [])].includes(goal.status)) {
+      return { ok: false, error: "This goal cannot be resumed from its current status. Refresh its details." };
+    }
+    subscribeCodexAppServerEvents(sessionId, context.provider, threadId, context);
+    if (observationLost && input.action === "resume") {
+      const recovered = await submitCodexAppServerAssistantResult(sessionId, threadId, turnState(context.session).turnId, { recoverFromProvider: true });
+      if (recovered.reason === "error") throw new Error(recovered.error);
+      await context.runtime.store.mutateSession(sessionId, async () => {
+        const run = await readCodexAppServerAgentRunForSession(context.runtime.store, sessionId);
+        if (run.active || run.providerThreadId !== threadId) throw new Error("The assistant changed. Refresh before resuming.");
+        await context.runtime.store.writeAgentRunEvent(sessionId, CODEX_APP_SERVER_AGENT_RUN_ID, {
+          event: { kind: "codex-observation-explicit-resume" },
+          patch: { providerStatus: "interrupted", error: "" }
+        });
+      });
+      await context.provider.resumeThread(threadId, context.resumeOptions);
+    }
+    const result = await context.provider.setGoalStatus(threadId, input.action === "pause" ? "paused" : "active");
+    await reconcileCodexAppServerGoalUpdated(sessionId, context.provider, threadId, {
+      params: { goal: result.goal }
+    });
+    await publish(sessionId, { reason: "codex-goal", nativeGoal: { threadId, goal: result.goal || null } });
+    return { ok: true, status: "available", goal: result.goal || null };
+  }
+
+
+  return {
+    prepareCodexAppServerGoalContext,
+    validateCodexAppServerGoalInput,
+    updateCodexAppServerGoal
+  };
+}