@alas-ide/codex-acp 2.5.0-alas.2 → 2.5.0-alas.3

package/dist/index.js

@@ -40611,7 +40611,7 @@ var package_default = {
   publishConfig: {
     access: "public"
   },
-  version: "2.5.0-alas.2",
+  version: "2.5.0-alas.3",
   description: "",
   main: "dist/index.js",
   bin: {
@@ -40689,7 +40689,7 @@ var package_default = {
   alasDownstream: {
     upstreamVersion: "2.5.0",
     upstreamCommit: "34e08970aa324a2be985f5080674d5aa91d7666f",
-    sourceCommit: "0f50c0b0345fd0e67b91ffc3c49d6b998d27da0c"
+    sourceCommit: "de8d4c961871fc0584ca1bd89f31a8de95066c65"
   }
 };
 
@@ -40919,9 +40919,31 @@ var CodexSubagentSubscriptions = class {
 
 // src/SessionFork.ts
 import { createHash } from "node:crypto";
+var NEUTRAL_FORK_POINT_META_KEY = "forkPoint";
+var NEUTRAL_FORK_POINT_VERSION = 1;
+function neutralForkPointCapability() {
+  return { version: NEUTRAL_FORK_POINT_VERSION, boundary: "turn" };
+}
+function clientRequestsNeutralForkPoint(capabilities) {
+  const declared = capabilities?._meta?.[NEUTRAL_FORK_POINT_META_KEY];
+  if (!isUnknownRecord(declared)) return false;
+  const version2 = declared["version"];
+  return typeof version2 === "number" && Number.isInteger(version2) && version2 >= 1;
+}
+function hasNeutralForkPoint(meta3) {
+  return meta3 != null && meta3[NEUTRAL_FORK_POINT_META_KEY] !== void 0;
+}
+function forkPointNotNegotiatedError() {
+  return RequestError.invalidParams(
+    { [NEUTRAL_FORK_POINT_META_KEY]: { reason: "notNegotiated" } },
+    "session/fork _meta.forkPoint needs initialize clientCapabilities._meta.forkPoint"
+  );
+}
 async function forkSession(request, additionalDirectories, dependencies, instructions) {
+  const forkPoint = readForkPoint(request._meta);
   await dependencies.refreshSkills(request.cwd, additionalDirectories);
-  const lastTurnId = await resolveForkTurnId(request, dependencies.codexClient);
+  const match = forkPoint ? await resolveForkPoint(request, forkPoint, dependencies.codexClient) : void 0;
+  const lastTurnId = match?.turnId;
   const sessionConfig = await dependencies.createSessionConfig(
     request.cwd,
     additionalDirectories,
@@ -40953,26 +40975,83 @@ async function forkSession(request, additionalDirectories, dependencies, instruc
     currentServiceTier: response.serviceTier ?? null,
     additionalDirectories,
     skippedMcpServers: sessionConfig.skippedMcpServers,
-    ...instructions ? { instructions } : {}
+    ...instructions ? { instructions } : {},
+    ...forkPoint?.kind === "neutral" && match ? {
+      forkPoint: {
+        boundary: "turn",
+        messageId: match.messageId,
+        turnId: match.turnId,
+        lastItemId: match.lastItemId,
+        matchedBy: match.matchedBy
+      }
+    } : {}
   };
 }
-async function resolveForkTurnId(request, codexClient) {
-  const forkPoint = readAirForkPoint(request._meta);
-  if (!forkPoint) return void 0;
+function readForkPoint(meta3) {
+  if (hasNeutralForkPoint(meta3)) return { kind: "neutral", ...readNeutralForkPoint(meta3[NEUTRAL_FORK_POINT_META_KEY]) };
+  const air = readAirForkPoint(meta3);
+  return air ? { kind: "air", ...air } : void 0;
+}
+async function resolveForkPoint(request, forkPoint, codexClient) {
   const history = await codexClient.threadReadWithHistory(request.sessionId);
-  const candidateIds = airForkMessageIdCandidates(forkPoint.messageId);
-  const itemTurnId = candidateIds.map((candidateId) => history.thread.turns.find((turn) => turn.items.some((item) => item.id === candidateId))?.id).find((turnId) => turnId !== void 0);
-  if (itemTurnId) return itemTurnId;
+  const turns = history.thread.turns;
+  const matchById = (candidateId) => {
+    const turn = turns.find((turn2) => turn2.items.some((item) => item.id === candidateId));
+    return turn ? toMatch(turn, candidateId, "id") : void 0;
+  };
+  const candidateIds = forkPoint.kind === "air" ? airForkMessageIdCandidates(forkPoint.messageId) : [forkPoint.messageId];
+  const idMatch = candidateIds.map(matchById).find((match) => match !== void 0);
+  if (idMatch) return idMatch;
   if (forkPoint.messageFingerprint) {
-    const matchingTurns = history.thread.turns.flatMap((turn) => turn.items.filter((item) => item.type === "agentMessage" && fingerprintAgentMessage(item.text) === forkPoint.messageFingerprint).map(() => turn.id));
-    const fingerprintTurnId = matchingTurns[forkPoint.messageOccurrence - 1];
-    if (fingerprintTurnId) return fingerprintTurnId;
+    const renderCwd = history.thread.cwd ?? request.cwd;
+    const clientText = forkPoint.kind === "neutral" ? (text) => renderFileCitations(text, renderCwd) : (text) => text;
+    const matches = turns.flatMap((turn) => turn.items.filter((item) => item.type === "agentMessage" && fingerprintAgentMessage(clientText(item.text)) === forkPoint.messageFingerprint).map((item) => toMatch(turn, item.id, "fingerprint")));
+    const fingerprintMatch = matches[forkPoint.messageOccurrence - 1];
+    if (fingerprintMatch) return fingerprintMatch;
+  }
+  if (forkPoint.kind === "neutral") {
+    throw RequestError.invalidParams(
+      { [NEUTRAL_FORK_POINT_META_KEY]: { messageId: forkPoint.messageId, reason: "notFound" } },
+      `Fork point message ${forkPoint.messageId} was not found in session ${request.sessionId}`
+    );
   }
   throw RequestError.invalidParams(
     { messageId: forkPoint.messageId },
     `Fork point message ${forkPoint.messageId} was not found in session ${request.sessionId}`
   );
 }
+function toMatch(turn, messageId, matchedBy) {
+  return { messageId, turnId: turn.id, lastItemId: turn.items.at(-1).id, matchedBy };
+}
+function readNeutralForkPoint(forkPoint) {
+  const invalid = (field, message) => RequestError.invalidParams(
+    { [NEUTRAL_FORK_POINT_META_KEY]: { field } },
+    `session/fork _meta.forkPoint: ${message}`
+  );
+  if (!isUnknownRecord(forkPoint)) throw invalid(NEUTRAL_FORK_POINT_META_KEY, "must be an object");
+  const version2 = forkPoint["version"];
+  if (version2 !== void 0 && version2 !== NEUTRAL_FORK_POINT_VERSION) {
+    throw invalid("version", `version must be ${NEUTRAL_FORK_POINT_VERSION} when present`);
+  }
+  const messageId = forkPoint["messageId"];
+  if (typeof messageId !== "string" || messageId.trim().length === 0) {
+    throw invalid("messageId", "messageId must be a non-empty string");
+  }
+  const messageFingerprint = forkPoint["messageFingerprint"];
+  if (messageFingerprint !== void 0 && (typeof messageFingerprint !== "string" || !SHA256_FINGERPRINT.test(messageFingerprint))) {
+    throw invalid("messageFingerprint", "messageFingerprint must be sha256: and 64 lowercase hex digits");
+  }
+  const messageOccurrence = forkPoint["messageOccurrence"] ?? 1;
+  if (!Number.isSafeInteger(messageOccurrence) || messageOccurrence < 1) {
+    throw invalid("messageOccurrence", "messageOccurrence must be a positive integer");
+  }
+  return {
+    messageId: messageId.trim(),
+    ...typeof messageFingerprint === "string" && { messageFingerprint },
+    messageOccurrence
+  };
+}
+var SHA256_FINGERPRINT = /^sha256:[0-9a-f]{64}$/;
 function readAirForkPoint(meta3) {
   const jetbrains = meta3?.["jetbrains"];
   if (!isUnknownRecord(jetbrains)) return void 0;
@@ -40985,7 +41064,7 @@ function readAirForkPoint(meta3) {
     throw RequestError.invalidParams(void 0, "AIR fork messageId must be a non-empty string");
   }
   const messageFingerprint = fork["messageFingerprint"];
-  if (messageFingerprint !== void 0 && (typeof messageFingerprint !== "string" || !/^sha256:[0-9a-f]{64}$/.test(messageFingerprint))) {
+  if (messageFingerprint !== void 0 && (typeof messageFingerprint !== "string" || !SHA256_FINGERPRINT.test(messageFingerprint))) {
     throw RequestError.invalidParams(void 0, "AIR fork messageFingerprint must be a SHA-256 fingerprint");
   }
   const messageOccurrence = fork["messageOccurrence"] ?? 1;
@@ -52061,6 +52140,8 @@ var CodexAcpServer = class {
   /** The capability choices of the client for tool call and plan reports. */
   capabilities;
   booleanConfigOptionsSupported;
+  /** Whether the client opted into the client-neutral `session/fork` `_meta.forkPoint`. */
+  neutralForkPointSupported = false;
   /** Last `authStatus` pushed to the client; used to suppress duplicates. */
   currentAuthStatus;
   /**
@@ -52323,6 +52404,7 @@ var CodexAcpServer = class {
     if (appServer) await appServer;
     this.reportingConnection.reports.compareMeta = this.capabilities.airToolCallContract;
     this.booleanConfigOptionsSupported = clientSupportsBooleanConfigOptions(_params.clientCapabilities);
+    this.neutralForkPointSupported = clientRequestsNeutralForkPoint(_params.clientCapabilities);
     this.sessionIndex.configure(_params.clientCapabilities);
     this.hookReview.configure(_params.clientCapabilities?._meta?.["codexHooks"], this.capabilities.airClient);
     await this.runWithProcessCheck(() => this.codexAcpClient.initialize(_params));
@@ -52382,6 +52464,7 @@ var CodexAcpServer = class {
     if (appServer) await appServer;
     this.reportingConnection.reports.compareMeta = this.capabilities.airToolCallContract;
     this.booleanConfigOptionsSupported = true;
+    this.neutralForkPointSupported = clientRequestsNeutralForkPoint(clientCapabilities);
     this.sessionIndex.configure(clientCapabilities, { neutral: false });
     await this.runWithProcessCheck(() => this.codexAcpClient.initialize({ clientInfo: params.info }));
     this.sessionIndex.observe(this.codexAcpClient);
@@ -52466,6 +52549,10 @@ var CodexAcpServer = class {
         "async-tasks": asyncTaskCapability()
       } : {},
       ...this.hookReview.enabled ? { codexHooks: { version: 1, reviewToken: true } } : {},
+      // The client-neutral fork point, see `docs/air-extensions.md`.
+      ...this.neutralForkPointSupported ? {
+        [NEUTRAL_FORK_POINT_META_KEY]: neutralForkPointCapability()
+      } : {},
       // The session index for a client that opted in without AIR, see `docs/air-extensions.md`.
       ...neutralSessionIndex ? {
         [NEUTRAL_SESSION_INDEX_META_KEY]: neutralSessionIndex
@@ -52759,7 +52846,7 @@ You have been logged out. Please try again.`);
     this.sessionGenerations.set(sessionId, generation);
     return generation;
   }
-  async tryCreateSession(request, operation = "sessionId" in request ? "resume" : "new") {
+  async tryCreateSession(request, operation = "sessionId" in request ? "resume" : "new", onForked) {
     clientSystemPromptText(request.systemPrompt);
     const existingSessionRequest = request;
     const previousInstructions = "sessionId" in request ? this.sessions.get(request.sessionId)?.instructions : void 0;
@@ -52810,6 +52897,7 @@ You have been logged out. Please try again.`);
           previousInstructions
         );
       });
+      onForked?.(sessionMetadata);
     } else {
       logger.log(`Create new session...`);
       sessionMetadata = await this.runWithProcessCheck(() => {
@@ -53378,6 +53466,9 @@ You have been logged out. Please try again.`);
   async forkSession(params) {
     params = this.withV1SessionInstructionAppend(params);
     clientSystemPromptText(params.systemPrompt);
+    if (hasNeutralForkPoint(params._meta) && !this.neutralForkPointSupported) {
+      throw forkPointNotNegotiatedError();
+    }
     this.assertInstructionsReady(params.sessionId);
     return this.hookReview.run(
       params.cwd,
@@ -53393,12 +53484,16 @@ You have been logged out. Please try again.`);
     if (appServer) await appServer;
     logger.log("Forking session...", { sessionId: params.sessionId });
     try {
-      const [sessionId, , modeState] = await this.tryCreateSession(params, "fork");
+      let forkPoint;
+      const [sessionId, , modeState] = await this.tryCreateSession(params, "fork", (metadata) => {
+        forkPoint = metadata.forkPoint;
+      });
       logger.log("Session forked", { sourceSessionId: params.sessionId, sessionId });
       return {
         sessionId,
         modes: modeState,
-        ...this.createSessionConfigOptionsResponse(this.getSessionState(sessionId))
+        ...this.createSessionConfigOptionsResponse(this.getSessionState(sessionId)),
+        ...forkPoint ? { _meta: { [NEUTRAL_FORK_POINT_META_KEY]: forkPoint } } : {}
       };
     } catch (e) {
       const error62 = e instanceof Error ? e : new Error(String(e));
@@ -53409,10 +53504,11 @@ You have been logged out. Please try again.`);
   async forkSessionV2(params) {
     const { systemPrompt, ...rest } = params;
     const request = { ...rest, systemPrompt: toV1SystemPrompt(systemPrompt) };
-    const { sessionId } = await this.forkSession(request);
+    const { sessionId, _meta } = await this.forkSession(request);
     return {
       sessionId,
-      ...this.createSessionSetupResponseV2(this.getSessionState(sessionId))
+      ...this.createSessionSetupResponseV2(this.getSessionState(sessionId)),
+      ..._meta ? { _meta } : {}
     };
   }
   async listSessions(params) {

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "2.5.0-alas.2",
+  "version": "2.5.0-alas.3",
   "description": "",
   "main": "dist/index.js",
   "bin": {
@@ -81,6 +81,6 @@
   "alasDownstream": {
     "upstreamVersion": "2.5.0",
     "upstreamCommit": "34e08970aa324a2be985f5080674d5aa91d7666f",
-    "sourceCommit": "0f50c0b0345fd0e67b91ffc3c49d6b998d27da0c"
+    "sourceCommit": "de8d4c961871fc0584ca1bd89f31a8de95066c65"
   }
 }