Add session-stable prompt_cache_key (patch 0006)

Main turns now set prompt_cache_key to the session/conv id. Responses
already sent that via the conv-id fallback; Chat Completions now puts
the same value in `user`. Recap and /btw keep sharing the parent
session key — not an agent-scoped suffix.

.github/workflows/build.yml

@@ -1,9 +1,20 @@
-# Native release builds of the patched grok binary.
+# CI for the patched grok binary.
 #
-# Matrix is host=target (no cross): Windows/Linux amd64 and macOS arm64.
+# Regular push / pull_request: test job only.
-# work/ is derived the same way as `make apply`, but the upstream checkout is
+# workflow_dispatch or a v* tag: test, then the three release builds.
-# a depth-1 fetch of the pinned SHA so CI does not clone full grok-build history.
+# Tags also publish the artifacts as a GitHub Release.
-name: Build
+#
+# Windows is cross-compiled from Ubuntu (cargo-xwin → x86_64-pc-windows-msvc),
+# in its own job — not mixed into the native linux-amd64 build. Official proto
+# codegen is Unix-host-only (/dev/stdout, Linux protoc); native windows-latest
+# is the path that broke.
+#
+# Cache budget (GitHub's repo cap is 10 GB):
+#   - cargo registry/git is shared across the Ubuntu jobs (no target/)
+#   - test keeps a separate debug work/target (small crates only)
+#   - xwin's MSVC splat is cached on its own
+#   - release target/ is never cached (multi-GB)
+name: CI
 
 on:
   push:
@@ -13,8 +24,10 @@ on:
   workflow_dispatch:
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
+  # Distinguish test-only runs from dispatch/tag builds so a release does not
-  cancel-in-progress: true
+  # cancel an in-flight PR test on the same branch name, and vice versa.
+  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' || (github.event_name == 'push' && !startsWith(github.ref, 'refs/tags/')) }}
 
 env:
   CARGO_TERM_COLOR: always
@@ -25,30 +38,75 @@ permissions:
   contents: read
 
 jobs:
-  build:
+  test:
-    name: ${{ matrix.artifact }}
+    name: test
-    runs-on: ${{ matrix.os }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Disable CRLF conversion
+        run: git config --global core.autocrlf false
+
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@1.94.0
+
+      - uses: arduino/setup-protoc@v3
+        with:
+          version: "29.3"
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Apply patches onto pinned upstream
+        run: ./scripts/ci-apply.sh
+
+      - name: Export PROTOC
+        run: echo "PROTOC=$(command -v protoc)" >> "$GITHUB_ENV"
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: work
+          shared-key: ubuntu-cargo
+          cache-targets: false
+          save-if: ${{ github.ref == 'refs/heads/main' && github.event_name == 'push' }}
+
+      - name: Restore test target cache
+        id: test-target
+        uses: actions/cache/restore@v4
+        with:
+          path: work/target
+          key: test-target-1.94-${{ hashFiles('work/Cargo.lock') }}
+          restore-keys: |
+            test-target-1.94-
+
+      - name: Test
+        working-directory: work
+        # make test default + the proto crate (exercises protoc / build.rs).
+        # pager/shell stay off this job: their debug target/ would blow the
+        # 10 GB cache budget and the runner disk.
+        run: cargo test --locked -p xai-grok-version -p xai-grok-tools-api
+
+      - name: Save test target cache
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push' && steps.test-target.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: work/target
+          key: test-target-1.94-${{ hashFiles('work/Cargo.lock') }}
+
+  build-linux-amd64:
+    name: grok-linux-amd64
+    if: github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/')
+    needs: test
+    runs-on: ubuntu-latest
     timeout-minutes: 180
     defaults:
       run:
         shell: bash
-    strategy:
+    env:
-      fail-fast: false
+      TARGET: x86_64-unknown-linux-gnu
-      matrix:
+      ARTIFACT: grok-linux-amd64
-        include:
+      EXE: xai-grok-pager
-          - os: ubuntu-latest
-            target: x86_64-unknown-linux-gnu
-            artifact: grok-linux-amd64
-            exe: xai-grok-pager
-          - os: windows-latest
-            target: x86_64-pc-windows-msvc
-            artifact: grok-windows-amd64
-            exe: xai-grok-pager.exe
-          - os: macos-14
-            target: aarch64-apple-darwin
-            artifact: grok-macos-arm64
-            exe: xai-grok-pager
-
     steps:
       - name: Disable CRLF conversion
         run: git config --global core.autocrlf false
@@ -57,7 +115,7 @@ jobs:
 
       - uses: dtolnay/rust-toolchain@1.94.0
         with:
-          targets: ${{ matrix.target }}
+          targets: x86_64-unknown-linux-gnu
 
       - uses: arduino/setup-protoc@v3
         with:
@@ -65,79 +123,153 @@ jobs:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Apply patches onto pinned upstream
-        run: |
+        run: ./scripts/ci-apply.sh
-          set -euo pipefail
-          REV="$(grep -vE '^\s*(#|$)' upstream.rev | head -n1 | tr -d '[:space:]')"
-          [[ -n "$REV" ]] || { echo "upstream.rev has no revision" >&2; exit 1; }
 
-          git init work
+      - name: Export PROTOC
-          git -C work remote add origin https://github.com/xai-org/grok-build.git
+        run: echo "PROTOC=$(command -v protoc)" >> "$GITHUB_ENV"
-          git -C work fetch --depth 1 origin "$REV"
-          git -C work checkout --force --detach FETCH_HEAD
-          git -C work checkout -B fork
-          git -C work tag -f base
-          git -C work config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git -C work config user.name "github-actions[bot]"
-
-          shopt -s nullglob
-          patches=("$GITHUB_WORKSPACE"/patches/*.patch)
-          if ((${#patches[@]})); then
-            git -C work am --3way --keep-cr --whitespace=nowarn "${patches[@]}"
-          fi
-          echo "work/ ready: upstream ${REV:0:12} + ${#patches[@]} patch(es)"
 
       - uses: Swatinem/rust-cache@v2
         with:
           workspaces: work
-          key: ${{ matrix.target }}
+          shared-key: ubuntu-cargo
           cache-targets: false
 
       - name: Release build
         working-directory: work
-        run: cargo build --release --locked -p xai-grok-pager-bin --target ${{ matrix.target }}
+        run: cargo build --release --locked -p xai-grok-pager-bin --target "$TARGET"
 
       - name: Package
-        env:
+        run: ./scripts/ci-package.sh
-          TARGET: ${{ matrix.target }}
-          ARTIFACT: ${{ matrix.artifact }}
-          EXE: ${{ matrix.exe }}
-        run: |
-          set -euo pipefail
-          src="work/target/${TARGET}/release/${EXE}"
-          [[ -f "$src" ]] || { echo "missing $src" >&2; ls -la "work/target/${TARGET}/release" >&2; exit 1; }
-
-          mkdir -p dist
-          if [[ "$EXE" == *.exe ]]; then
-            dest="dist/${ARTIFACT}.exe"
-          else
-            dest="dist/${ARTIFACT}"
-            strip "$src" || true
-          fi
-          cp "$src" "$dest"
-
-          {
-            echo "artifact=$(basename "$dest")"
-            echo "target=${TARGET}"
-            echo "git=${GITHUB_SHA}"
-            echo "upstream=$(grep -vE '^\s*(#|$)' upstream.rev | head -n1 | tr -d '[:space:]')"
-            echo "rustc=$(rustc --version)"
-          } > "dist/${ARTIFACT}.txt"
-
-          if command -v sha256sum >/dev/null; then
-            (cd dist && sha256sum "$(basename "$dest")" "${ARTIFACT}.txt" > "${ARTIFACT}.sha256")
-          else
-            (cd dist && shasum -a 256 "$(basename "$dest")" "${ARTIFACT}.txt" > "${ARTIFACT}.sha256")
-          fi
 
       - uses: actions/upload-artifact@v4
         with:
-          name: ${{ matrix.artifact }}
+          name: grok-linux-amd64
+          path: dist/*
+          if-no-files-found: error
+
+  build-windows-amd64:
+    name: grok-windows-amd64
+    if: github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/')
+    needs: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 180
+    defaults:
+      run:
+        shell: bash
+    env:
+      TARGET: x86_64-pc-windows-msvc
+      ARTIFACT: grok-windows-amd64
+      EXE: xai-grok-pager.exe
+      XWIN_CACHE_DIR: ${{ github.workspace }}/.xwin-cache
+    steps:
+      - name: Disable CRLF conversion
+        run: git config --global core.autocrlf false
+
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@1.94.0
+        with:
+          targets: x86_64-pc-windows-msvc
+
+      - uses: arduino/setup-protoc@v3
+        with:
+          version: "29.3"
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Apply patches onto pinned upstream
+        run: ./scripts/ci-apply.sh
+
+      - name: Export PROTOC
+        run: echo "PROTOC=$(command -v protoc)" >> "$GITHUB_ENV"
+
+      - name: Install clang / lld / llvm
+        run: sudo apt-get update && sudo apt-get install -y clang lld llvm
+
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-xwin
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: work
+          shared-key: ubuntu-cargo
+          cache-targets: false
+
+      - name: Cache xwin MSVC splat
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.XWIN_CACHE_DIR }}
+          key: xwin-x86_64-msvc-v1
+
+      - name: Release build (cross)
+        working-directory: work
+        run: cargo xwin build --release --locked -p xai-grok-pager-bin --target "$TARGET"
+
+      - name: Package
+        run: ./scripts/ci-package.sh
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: grok-windows-amd64
+          path: dist/*
+          if-no-files-found: error
+
+  build-macos-arm64:
+    name: grok-macos-arm64
+    if: github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/')
+    needs: test
+    runs-on: macos-14
+    timeout-minutes: 180
+    defaults:
+      run:
+        shell: bash
+    env:
+      TARGET: aarch64-apple-darwin
+      ARTIFACT: grok-macos-arm64
+      EXE: xai-grok-pager
+    steps:
+      - name: Disable CRLF conversion
+        run: git config --global core.autocrlf false
+
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@1.94.0
+        with:
+          targets: aarch64-apple-darwin
+
+      - uses: arduino/setup-protoc@v3
+        with:
+          version: "29.3"
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Apply patches onto pinned upstream
+        run: ./scripts/ci-apply.sh
+
+      - name: Export PROTOC
+        run: echo "PROTOC=$(command -v protoc)" >> "$GITHUB_ENV"
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: work
+          key: macos-arm64
+          cache-targets: false
+
+      - name: Release build
+        working-directory: work
+        run: cargo build --release --locked -p xai-grok-pager-bin --target "$TARGET"
+
+      - name: Package
+        run: ./scripts/ci-package.sh
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: grok-macos-arm64
           path: dist/*
           if-no-files-found: error
 
   release:
     if: startsWith(github.ref, 'refs/tags/')
-    needs: build
+    needs: [build-linux-amd64, build-windows-amd64, build-macos-arm64]
     runs-on: ubuntu-latest
     permissions:
       contents: write

patches/0006-Pin-a-session-stable-prompt_cache_key-on-main-turns.patch

@@ -0,0 +1,134 @@
+From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
+From: iceBear67 <icebear67@sfclub.cc>
+Date: Sun, 16 Aug 2026 03:13:22 +0000
+Subject: [PATCH] Pin a session-stable prompt_cache_key on main turns
+
+Main turns already reached the Responses wire as prompt_cache_key via
+the x_grok_conv_id fallback. Set the field explicitly so Chat Completions
+can put the same session id in `user`, and so recap /btw keep sharing
+one key. Do not agent-scope: that would split the prefix those side
+calls are built to ride.
+
+diff --git a/crates/codegen/xai-chat-state/src/actor/request_builder.rs b/crates/codegen/xai-chat-state/src/actor/request_builder.rs
+index 4d9ce755a316ab0cca430aa3126d3ceb18e541b5..7c787b6dce09682445438274ed5a35008f242a6d 100644
+--- a/crates/codegen/xai-chat-state/src/actor/request_builder.rs
++++ b/crates/codegen/xai-chat-state/src/actor/request_builder.rs
+@@ -105,7 +105,10 @@ impl ChatStateActor {
+             x_grok_deployment_id: None,
+             x_grok_user_id: None,
+             trace,
+-            prompt_cache_key: None,
++            // Same session id the Responses mapping already fell back to via
++            // `x_grok_conv_id`. Set it explicitly so Chat Completions `user`
++            // and side-calls share one key without depending on that fallback.
++            prompt_cache_key: Some(conv_id.clone()),
+             reasoning_effort: self.state.sampling_config.reasoning_effort,
+             json_schema: None,
+         }
+diff --git a/crates/codegen/xai-chat-state/src/actor/tests.rs b/crates/codegen/xai-chat-state/src/actor/tests.rs
+index 604a121b4897d1e245a15f99318130af0ad02462..e9899af98ecf80eb541ce120f4aad489e0e25dae 100644
+--- a/crates/codegen/xai-chat-state/src/actor/tests.rs
++++ b/crates/codegen/xai-chat-state/src/actor/tests.rs
+@@ -1576,6 +1576,7 @@ async fn build_request_includes_all_messages() {
+     assert_eq!(request.items.len(), 2);
+     assert_eq!(request.x_grok_conv_id, Some("conv-1".to_string()));
+     assert_eq!(request.x_grok_req_id, Some("req-1".to_string()));
++    assert_eq!(request.prompt_cache_key, Some("conv-1".to_string()));
+ }
+ 
+ #[tokio::test]
+diff --git a/crates/codegen/xai-grok-sampling-types/src/conversation.rs b/crates/codegen/xai-grok-sampling-types/src/conversation.rs
+index 982839bbe822874651bc37e257e4e4a7442f6f87..91d61f3a46524cdf5c11cb753c739abe8481f503 100644
+--- a/crates/codegen/xai-grok-sampling-types/src/conversation.rs
++++ b/crates/codegen/xai-grok-sampling-types/src/conversation.rs
+@@ -623,10 +623,29 @@ pub struct ConversationRequest {
+     /// JSON Schema for structured output (strict mode).
+     pub json_schema: Option<serde_json::Value>,
+     /// Sticky routing key for prompt-cache reuse; overrides `x_grok_conv_id` for routing.
++    ///
++    /// Session-scoped, not agent-scoped: recap and `/btw` replay the parent
++    /// conversation under this key. A per-agent suffix would split the prefix
++    /// cache those side-calls are built to share. Only the Responses mapping
++    /// puts this field on the wire; Chat Completions surfaces the same value
++    /// as `user` (see [`Self::session_cache_key`]).
+     pub prompt_cache_key: Option<String>,
+ }
+ 
+ impl ConversationRequest {
++    /// Session-stable key for prompt-cache sticky routing.
++    ///
++    /// Prefer an explicit [`Self::prompt_cache_key`], then session id, then
++    /// conv id. Callers that share a conversation prefix (main turn, recap,
++    /// `/btw`) must resolve to the same string.
++    pub fn session_cache_key(&self) -> Option<&str> {
++        self.prompt_cache_key
++            .as_deref()
++            .or(self.x_grok_session_id.as_deref())
++            .or(self.x_grok_conv_id.as_deref())
++            .filter(|s| !s.is_empty())
++    }
++
+     /// Strip every image; returns the stripped URLs.
+     pub fn strip_images(&mut self) -> Vec<Arc<str>> {
+         strip_images_where(&mut self.items, |_| true)
+@@ -2399,6 +2418,35 @@ mod tests {
+     use crate::tool_overrides::*;
+     use assert_matches::assert_matches;
+ 
++    #[test]
++    fn session_cache_key_prefers_explicit_then_session_then_conv() {
++        let mut req = ConversationRequest {
++            x_grok_conv_id: Some("conv".into()),
++            x_grok_session_id: Some("session".into()),
++            prompt_cache_key: Some("explicit".into()),
++            ..Default::default()
++        };
++        assert_eq!(req.session_cache_key(), Some("explicit"));
++        req.prompt_cache_key = None;
++        assert_eq!(req.session_cache_key(), Some("session"));
++        req.x_grok_session_id = None;
++        assert_eq!(req.session_cache_key(), Some("conv"));
++        req.x_grok_conv_id = Some(String::new());
++        assert_eq!(req.session_cache_key(), None);
++    }
++
++    #[test]
++    fn chat_completions_user_carries_session_cache_key() {
++        let req = ConversationRequest {
++            items: vec![ConversationItem::user("hi")],
++            model: Some("test-model".into()),
++            prompt_cache_key: Some("sess-1".into()),
++            ..Default::default()
++        };
++        let mapped = ChatCompletionRequest::from(req);
++        assert_eq!(mapped.user.as_deref(), Some("sess-1"));
++    }
++
+     /// Keeps `forwards_prompt_cache_key()` honest against each mapping: a key that never reaches the wire looks like a 0% cache hit, not a bug.
+     #[test]
+     fn prompt_cache_key_reaches_the_wire_only_where_the_backend_claims() {
+diff --git a/crates/codegen/xai-grok-sampling-types/src/conversation/chat_completions.rs b/crates/codegen/xai-grok-sampling-types/src/conversation/chat_completions.rs
+index dac77d82f7f96836f5f4ed26f2e12eb13164e4f5..b80820fbbf3c96e348f44880c432361eb537817a 100644
+--- a/crates/codegen/xai-grok-sampling-types/src/conversation/chat_completions.rs
++++ b/crates/codegen/xai-grok-sampling-types/src/conversation/chat_completions.rs
+@@ -295,7 +295,7 @@ impl From<ConversationRequest> for ChatCompletionRequest {
+             top_p: req.top_p,
+             frequency_penalty: None,
+             presence_penalty: None,
+-            user: None,
++            user: req.session_cache_key().map(str::to_owned),
+             tools,
+             tool_choice,
+             search_parameters: None,
+diff --git a/crates/codegen/xai-grok-sampling-types/src/conversation/chat_completions_tests.rs b/crates/codegen/xai-grok-sampling-types/src/conversation/chat_completions_tests.rs
+index 8d2afa36362471676804bfa8676d0294ca56049d..1a29113ca0e467b9a5e39faa06cd468d4f45a242 100644
+--- a/crates/codegen/xai-grok-sampling-types/src/conversation/chat_completions_tests.rs
++++ b/crates/codegen/xai-grok-sampling-types/src/conversation/chat_completions_tests.rs
+@@ -52,6 +52,7 @@ fn test_conversation_request_to_chat_completion() {
+     assert_eq!(chat_req.model, Some("grok-3".to_string()));
+     assert_eq!(chat_req.temperature, Some(0.7));
+     assert_eq!(chat_req.messages.len(), 2);
++    assert_eq!(chat_req.user, None);
+ }
+ 
+ #[test]

scripts/ci-apply.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Shallow work/ checkout for GitHub Actions.
+#
+# Unlike apply-patches.sh this does not clone upstream/ (that copy is a full
+# history clone for make update). CI only needs the pinned SHA + patches/.
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+REV="$(read_rev)"
+
+info "Fetching upstream ${REV:0:12} -> work/"
+rm -rf "$WORK_DIR"
+git init "$WORK_DIR"
+git -C "$WORK_DIR" remote add origin "$UPSTREAM_URL"
+git -C "$WORK_DIR" fetch --depth 1 origin "$REV"
+git -C "$WORK_DIR" checkout --force --detach FETCH_HEAD
+git -C "$WORK_DIR" checkout -B "$WORK_BRANCH"
+git -C "$WORK_DIR" tag -f "$BASE_TAG"
+git -C "$WORK_DIR" config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+git -C "$WORK_DIR" config user.name "github-actions[bot]"
+
+shopt -s nullglob
+patches=("$PATCHES_DIR"/*.patch)
+shopt -u nullglob
+if ((${#patches[@]})); then
+  git -C "$WORK_DIR" am --3way --keep-cr --whitespace=nowarn "${patches[@]}"
+fi
+
+info "work/ ready: upstream ${REV:0:12} + ${#patches[@]} patch(es)"

scripts/ci-package.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# Copy a cargo --target release binary into dist/ with a checksum sidecar.
+#
+# Required env:
+#   TARGET    rustc triple (selects work/target/$TARGET/release/)
+#   ARTIFACT  basename without extension (grok-linux-amd64, …)
+#   EXE       filename cargo wrote (xai-grok-pager or xai-grok-pager.exe)
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+: "${TARGET:?TARGET is required}"
+: "${ARTIFACT:?ARTIFACT is required}"
+: "${EXE:?EXE is required}"
+
+src="$WORK_DIR/target/$TARGET/release/$EXE"
+[[ -f "$src" ]] || {
+  echo "missing $src" >&2
+  ls -la "$WORK_DIR/target/$TARGET/release" >&2 || true
+  exit 1
+}
+
+mkdir -p "$ROOT/dist"
+if [[ "$EXE" == *.exe ]]; then
+  dest="$ROOT/dist/${ARTIFACT}.exe"
+else
+  dest="$ROOT/dist/${ARTIFACT}"
+  strip "$src" || true
+fi
+cp "$src" "$dest"
+
+{
+  echo "artifact=$(basename "$dest")"
+  echo "target=${TARGET}"
+  echo "git=${GITHUB_SHA:-}"
+  echo "upstream=$(read_rev)"
+  echo "rustc=$(rustc --version)"
+} > "$ROOT/dist/${ARTIFACT}.txt"
+
+if command -v sha256sum >/dev/null; then
+  (cd "$ROOT/dist" && sha256sum "$(basename "$dest")" "${ARTIFACT}.txt" > "${ARTIFACT}.sha256")
+else
+  (cd "$ROOT/dist" && shasum -a 256 "$(basename "$dest")" "${ARTIFACT}.txt" > "${ARTIFACT}.sha256")
+fi
+
+info "packaged $dest"