diff --git a/.github/scripts/release-evidence-policy.json b/.github/scripts/release-evidence-policy.json index 7d0c61c3bd6..d54057e1e50 100644 --- a/.github/scripts/release-evidence-policy.json +++ b/.github/scripts/release-evidence-policy.json @@ -636,5 +636,345 @@ "desktop/scripts/appimage-patchelf.py": "63e78ef74160bc48fbcdd882065f1d416db6d13c", "desktop/scripts/linux-packaged-e2e.ts": "9ca92352668ff881c85caea44a9b4747bedc7e2d" } + }, + { + "kind": "ci", + "version": 1, + "windowsShards": 14, + "files": { + ".github/workflows/ci.yml": "74f5dfb883786792c872c58f2311b0299818b702", + ".github/actions/setup-project-bun/action.yml": "cf28f6f9d4385d69784f4e3610914f6952ce789d", + ".github/scripts/release-evidence.cjs": "ace2b9006b2d58ef84ed0996b4e179ff4be15900", + ".github/scripts/release-evidence.test.cjs": "9cc686390e5c37d8e693b98d049e8b505d0273cf", + "scripts/ci/select-test-lane.sh": "b25836cb55f962d1ffd9e68ed00f45f8b45becc8", + "scripts/ci/windows-sensitive-diff.sh": "03495f256c671aff57e750febffe19ca7face6a1", + "scripts/ci/run-bun-test-batches.sh": "f8aa18e80aff1c95c584cd2c879dfbb6806c11fb", + "scripts/ci/bun-crash-signatures.sh": "d34662ddd07864d97bed909135095db33fe42c9e", + "scripts/ci/bun-install-frozen.sh": "e6d7bc3aec044e12297c7c4c04015a33df0eb22b", + "scripts/ci/docker-smoke.ts": "4eea7637d8658156feeaa356c0c3086c00d75fa5", + "scripts/ci/test-durations.tsv": "6ff82545debbd95286928a7a99abfdeb10020a7a", + "scripts/ci/test-durations.windows.tsv": "523cef871c3e17fc0344c98fb15eef79feb04c84", + "scripts/test.ts": "37a8b3cf3fc895826844ab0b29d06cef028fc63a", + "scripts/lib/test-runner-bun.ts": "8763806104a851dbdefeea8cffe8d7dd8d1c8da1", + "scripts/test-temp-lock.ts": "ee83fb254b728de119028f52b9894bf52d7aea15", + "scripts/git-repository-env.ts": "267950490fffb4c48d9adb90bdcf5a873733b324", + "scripts/ci/run-changed-tests.sh": "9a54d3a5db9849bcbe0dd766954a840185419fa5", + "scripts/keyring-smoke.ts": "cd3be07ad57796172696dfa053ea1fb129f29365", + "scripts/privacy-scan.ts": "86314e891b45e49739b94c76cddd9e4cc2d4340f", + "scripts/structure-ssot.ts": "5b2d2918dae877fddfb16cdba6e89f0d10e82298", + "scripts/generate-ocx-skill-surface.ts": "155e866656ba2d71e8fd48adda857451caf16322", + "desktop/scripts/prepare-sidecar.ts": "20f7eec61f73635ea681e25f13dd850b62bb41e2", + "desktop/scripts/build-widget.sh": "38e0eb9d713804b603aa75c32383aa18ef01d06c", + "desktop/scripts/verify-macos-runtime.sh": "43f1a31375c6f6fe7dcafb9d96c231b98d1f6ba4", + "desktop/scripts/verify-linux-sidecar.sh": "c502bb5c8ba8346c722a8f5274f2274bb325a934", + "desktop/scripts/appimage-patchelf.py": "63e78ef74160bc48fbcdd882065f1d416db6d13c", + "desktop/scripts/linux-packaged-e2e.ts": "9ca92352668ff881c85caea44a9b4747bedc7e2d" + } + }, + { + "kind": "ci", + "version": 1, + "windowsShards": 14, + "files": { + ".github/workflows/ci.yml": "74f5dfb883786792c872c58f2311b0299818b702", + ".github/actions/setup-project-bun/action.yml": "cf28f6f9d4385d69784f4e3610914f6952ce789d", + ".github/scripts/release-evidence.cjs": "ace2b9006b2d58ef84ed0996b4e179ff4be15900", + ".github/scripts/release-evidence.test.cjs": "9cc686390e5c37d8e693b98d049e8b505d0273cf", + "scripts/ci/select-test-lane.sh": "b25836cb55f962d1ffd9e68ed00f45f8b45becc8", + "scripts/ci/windows-sensitive-diff.sh": "03495f256c671aff57e750febffe19ca7face6a1", + "scripts/ci/run-bun-test-batches.sh": "f8aa18e80aff1c95c584cd2c879dfbb6806c11fb", + "scripts/ci/bun-crash-signatures.sh": "d34662ddd07864d97bed909135095db33fe42c9e", + "scripts/ci/bun-install-frozen.sh": "e6d7bc3aec044e12297c7c4c04015a33df0eb22b", + "scripts/ci/docker-smoke.ts": "a8424f93986a31625a0a236cdab5667db67b3405", + "scripts/ci/test-durations.tsv": "1cb9486669444fd84202add64f4c3622ffc736e1", + "scripts/ci/test-durations.windows.tsv": "523cef871c3e17fc0344c98fb15eef79feb04c84", + "scripts/test.ts": "4f2567a666ddc01ca5d321e3e193b2e6d1688555", + "scripts/lib/test-runner-bun.ts": "8763806104a851dbdefeea8cffe8d7dd8d1c8da1", + "scripts/test-temp-lock.ts": "ee83fb254b728de119028f52b9894bf52d7aea15", + "scripts/git-repository-env.ts": "267950490fffb4c48d9adb90bdcf5a873733b324", + "scripts/ci/run-changed-tests.sh": "9a54d3a5db9849bcbe0dd766954a840185419fa5", + "scripts/keyring-smoke.ts": "cd3be07ad57796172696dfa053ea1fb129f29365", + "scripts/privacy-scan.ts": "86314e891b45e49739b94c76cddd9e4cc2d4340f", + "scripts/structure-ssot.ts": "5b2d2918dae877fddfb16cdba6e89f0d10e82298", + "scripts/generate-ocx-skill-surface.ts": "155e866656ba2d71e8fd48adda857451caf16322", + "desktop/scripts/prepare-sidecar.ts": "20f7eec61f73635ea681e25f13dd850b62bb41e2", + "desktop/scripts/build-widget.sh": "38e0eb9d713804b603aa75c32383aa18ef01d06c", + "desktop/scripts/verify-macos-runtime.sh": "43f1a31375c6f6fe7dcafb9d96c231b98d1f6ba4", + "desktop/scripts/verify-linux-sidecar.sh": "c502bb5c8ba8346c722a8f5274f2274bb325a934", + "desktop/scripts/appimage-patchelf.py": "63e78ef74160bc48fbcdd882065f1d416db6d13c", + "desktop/scripts/linux-packaged-e2e.ts": "9ca92352668ff881c85caea44a9b4747bedc7e2d" + } + }, + { + "kind": "ci", + "version": 1, + "windowsShards": 14, + "files": { + ".github/workflows/ci.yml": "74f5dfb883786792c872c58f2311b0299818b702", + ".github/actions/setup-project-bun/action.yml": "cf28f6f9d4385d69784f4e3610914f6952ce789d", + ".github/scripts/release-evidence.cjs": "ace2b9006b2d58ef84ed0996b4e179ff4be15900", + ".github/scripts/release-evidence.test.cjs": "9cc686390e5c37d8e693b98d049e8b505d0273cf", + "scripts/ci/select-test-lane.sh": "b25836cb55f962d1ffd9e68ed00f45f8b45becc8", + "scripts/ci/windows-sensitive-diff.sh": "03495f256c671aff57e750febffe19ca7face6a1", + "scripts/ci/run-bun-test-batches.sh": "f8aa18e80aff1c95c584cd2c879dfbb6806c11fb", + "scripts/ci/bun-crash-signatures.sh": "d34662ddd07864d97bed909135095db33fe42c9e", + "scripts/ci/bun-install-frozen.sh": "e6d7bc3aec044e12297c7c4c04015a33df0eb22b", + "scripts/ci/docker-smoke.ts": "054e52935e17b0ac4d9cf2112fc5c0180903df84", + "scripts/ci/test-durations.tsv": "1cb9486669444fd84202add64f4c3622ffc736e1", + "scripts/ci/test-durations.windows.tsv": "523cef871c3e17fc0344c98fb15eef79feb04c84", + "scripts/test.ts": "4f2567a666ddc01ca5d321e3e193b2e6d1688555", + "scripts/lib/test-runner-bun.ts": "8763806104a851dbdefeea8cffe8d7dd8d1c8da1", + "scripts/test-temp-lock.ts": "ee83fb254b728de119028f52b9894bf52d7aea15", + "scripts/git-repository-env.ts": "267950490fffb4c48d9adb90bdcf5a873733b324", + "scripts/ci/run-changed-tests.sh": "9a54d3a5db9849bcbe0dd766954a840185419fa5", + "scripts/keyring-smoke.ts": "cd3be07ad57796172696dfa053ea1fb129f29365", + "scripts/privacy-scan.ts": "86314e891b45e49739b94c76cddd9e4cc2d4340f", + "scripts/structure-ssot.ts": "5b2d2918dae877fddfb16cdba6e89f0d10e82298", + "scripts/generate-ocx-skill-surface.ts": "155e866656ba2d71e8fd48adda857451caf16322", + "desktop/scripts/prepare-sidecar.ts": "20f7eec61f73635ea681e25f13dd850b62bb41e2", + "desktop/scripts/build-widget.sh": "38e0eb9d713804b603aa75c32383aa18ef01d06c", + "desktop/scripts/verify-macos-runtime.sh": "43f1a31375c6f6fe7dcafb9d96c231b98d1f6ba4", + "desktop/scripts/verify-linux-sidecar.sh": "c502bb5c8ba8346c722a8f5274f2274bb325a934", + "desktop/scripts/appimage-patchelf.py": "63e78ef74160bc48fbcdd882065f1d416db6d13c", + "desktop/scripts/linux-packaged-e2e.ts": "9ca92352668ff881c85caea44a9b4747bedc7e2d" + } + }, + { + "kind": "ci", + "version": 1, + "windowsShards": 14, + "files": { + ".github/workflows/ci.yml": "74f5dfb883786792c872c58f2311b0299818b702", + ".github/actions/setup-project-bun/action.yml": "cf28f6f9d4385d69784f4e3610914f6952ce789d", + ".github/scripts/release-evidence.cjs": "ace2b9006b2d58ef84ed0996b4e179ff4be15900", + ".github/scripts/release-evidence.test.cjs": "9cc686390e5c37d8e693b98d049e8b505d0273cf", + "scripts/ci/select-test-lane.sh": "b25836cb55f962d1ffd9e68ed00f45f8b45becc8", + "scripts/ci/windows-sensitive-diff.sh": "03495f256c671aff57e750febffe19ca7face6a1", + "scripts/ci/run-bun-test-batches.sh": "59b1783aadf8109c0fa2d37047ff0d90300aa267", + "scripts/ci/bun-crash-signatures.sh": "d34662ddd07864d97bed909135095db33fe42c9e", + "scripts/ci/bun-install-frozen.sh": "e6d7bc3aec044e12297c7c4c04015a33df0eb22b", + "scripts/ci/docker-smoke.ts": "4eea7637d8658156feeaa356c0c3086c00d75fa5", + "scripts/ci/test-durations.tsv": "9dd8d4194c7950c9aaa2e3f96f9225869c854b72", + "scripts/ci/test-durations.windows.tsv": "523cef871c3e17fc0344c98fb15eef79feb04c84", + "scripts/test.ts": "1388addd67e9226de711425081a2723dd521efd8", + "scripts/lib/test-runner-bun.ts": "8763806104a851dbdefeea8cffe8d7dd8d1c8da1", + "scripts/test-temp-lock.ts": "ee83fb254b728de119028f52b9894bf52d7aea15", + "scripts/git-repository-env.ts": "267950490fffb4c48d9adb90bdcf5a873733b324", + "scripts/ci/run-changed-tests.sh": "9a54d3a5db9849bcbe0dd766954a840185419fa5", + "scripts/keyring-smoke.ts": "cd3be07ad57796172696dfa053ea1fb129f29365", + "scripts/privacy-scan.ts": "86314e891b45e49739b94c76cddd9e4cc2d4340f", + "scripts/structure-ssot.ts": "5b2d2918dae877fddfb16cdba6e89f0d10e82298", + "scripts/generate-ocx-skill-surface.ts": "155e866656ba2d71e8fd48adda857451caf16322", + "desktop/scripts/prepare-sidecar.ts": "20f7eec61f73635ea681e25f13dd850b62bb41e2", + "desktop/scripts/build-widget.sh": "38e0eb9d713804b603aa75c32383aa18ef01d06c", + "desktop/scripts/verify-macos-runtime.sh": "43f1a31375c6f6fe7dcafb9d96c231b98d1f6ba4", + "desktop/scripts/verify-linux-sidecar.sh": "c502bb5c8ba8346c722a8f5274f2274bb325a934", + "desktop/scripts/appimage-patchelf.py": "63e78ef74160bc48fbcdd882065f1d416db6d13c", + "desktop/scripts/linux-packaged-e2e.ts": "9ca92352668ff881c85caea44a9b4747bedc7e2d" + } + }, + { + "kind": "ci", + "version": 1, + "windowsShards": 14, + "files": { + ".github/workflows/ci.yml": "74f5dfb883786792c872c58f2311b0299818b702", + ".github/actions/setup-project-bun/action.yml": "cf28f6f9d4385d69784f4e3610914f6952ce789d", + ".github/scripts/release-evidence.cjs": "ace2b9006b2d58ef84ed0996b4e179ff4be15900", + ".github/scripts/release-evidence.test.cjs": "9cc686390e5c37d8e693b98d049e8b505d0273cf", + "scripts/ci/select-test-lane.sh": "b25836cb55f962d1ffd9e68ed00f45f8b45becc8", + "scripts/ci/windows-sensitive-diff.sh": "03495f256c671aff57e750febffe19ca7face6a1", + "scripts/ci/run-bun-test-batches.sh": "59b1783aadf8109c0fa2d37047ff0d90300aa267", + "scripts/ci/bun-crash-signatures.sh": "d34662ddd07864d97bed909135095db33fe42c9e", + "scripts/ci/bun-install-frozen.sh": "e6d7bc3aec044e12297c7c4c04015a33df0eb22b", + "scripts/ci/docker-smoke.ts": "4eea7637d8658156feeaa356c0c3086c00d75fa5", + "scripts/ci/test-durations.tsv": "9dd8d4194c7950c9aaa2e3f96f9225869c854b72", + "scripts/ci/test-durations.windows.tsv": "523cef871c3e17fc0344c98fb15eef79feb04c84", + "scripts/test.ts": "5b73037fb54e685b1d3485ea664e82a1eb418606", + "scripts/lib/test-runner-bun.ts": "8763806104a851dbdefeea8cffe8d7dd8d1c8da1", + "scripts/test-temp-lock.ts": "ee83fb254b728de119028f52b9894bf52d7aea15", + "scripts/git-repository-env.ts": "267950490fffb4c48d9adb90bdcf5a873733b324", + "scripts/ci/run-changed-tests.sh": "9a54d3a5db9849bcbe0dd766954a840185419fa5", + "scripts/keyring-smoke.ts": "cd3be07ad57796172696dfa053ea1fb129f29365", + "scripts/privacy-scan.ts": "86314e891b45e49739b94c76cddd9e4cc2d4340f", + "scripts/structure-ssot.ts": "5b2d2918dae877fddfb16cdba6e89f0d10e82298", + "scripts/generate-ocx-skill-surface.ts": "155e866656ba2d71e8fd48adda857451caf16322", + "desktop/scripts/prepare-sidecar.ts": "20f7eec61f73635ea681e25f13dd850b62bb41e2", + "desktop/scripts/build-widget.sh": "38e0eb9d713804b603aa75c32383aa18ef01d06c", + "desktop/scripts/verify-macos-runtime.sh": "43f1a31375c6f6fe7dcafb9d96c231b98d1f6ba4", + "desktop/scripts/verify-linux-sidecar.sh": "c502bb5c8ba8346c722a8f5274f2274bb325a934", + "desktop/scripts/appimage-patchelf.py": "63e78ef74160bc48fbcdd882065f1d416db6d13c", + "desktop/scripts/linux-packaged-e2e.ts": "9ca92352668ff881c85caea44a9b4747bedc7e2d" + } + }, + { + "kind": "ci", + "version": 1, + "windowsShards": 14, + "files": { + ".github/workflows/ci.yml": "74f5dfb883786792c872c58f2311b0299818b702", + ".github/actions/setup-project-bun/action.yml": "cf28f6f9d4385d69784f4e3610914f6952ce789d", + ".github/scripts/release-evidence.cjs": "ace2b9006b2d58ef84ed0996b4e179ff4be15900", + ".github/scripts/release-evidence.test.cjs": "9cc686390e5c37d8e693b98d049e8b505d0273cf", + "scripts/ci/select-test-lane.sh": "b25836cb55f962d1ffd9e68ed00f45f8b45becc8", + "scripts/ci/windows-sensitive-diff.sh": "03495f256c671aff57e750febffe19ca7face6a1", + "scripts/ci/run-bun-test-batches.sh": "59b1783aadf8109c0fa2d37047ff0d90300aa267", + "scripts/ci/bun-crash-signatures.sh": "d34662ddd07864d97bed909135095db33fe42c9e", + "scripts/ci/bun-install-frozen.sh": "e6d7bc3aec044e12297c7c4c04015a33df0eb22b", + "scripts/ci/docker-smoke.ts": "4eea7637d8658156feeaa356c0c3086c00d75fa5", + "scripts/ci/test-durations.tsv": "a07f90e6098082e1452ea5cc075c801271321eca", + "scripts/ci/test-durations.windows.tsv": "523cef871c3e17fc0344c98fb15eef79feb04c84", + "scripts/test.ts": "5b73037fb54e685b1d3485ea664e82a1eb418606", + "scripts/lib/test-runner-bun.ts": "8763806104a851dbdefeea8cffe8d7dd8d1c8da1", + "scripts/test-temp-lock.ts": "ee83fb254b728de119028f52b9894bf52d7aea15", + "scripts/git-repository-env.ts": "267950490fffb4c48d9adb90bdcf5a873733b324", + "scripts/ci/run-changed-tests.sh": "9a54d3a5db9849bcbe0dd766954a840185419fa5", + "scripts/keyring-smoke.ts": "cd3be07ad57796172696dfa053ea1fb129f29365", + "scripts/privacy-scan.ts": "86314e891b45e49739b94c76cddd9e4cc2d4340f", + "scripts/structure-ssot.ts": "5b2d2918dae877fddfb16cdba6e89f0d10e82298", + "scripts/generate-ocx-skill-surface.ts": "155e866656ba2d71e8fd48adda857451caf16322", + "desktop/scripts/prepare-sidecar.ts": "20f7eec61f73635ea681e25f13dd850b62bb41e2", + "desktop/scripts/build-widget.sh": "38e0eb9d713804b603aa75c32383aa18ef01d06c", + "desktop/scripts/verify-macos-runtime.sh": "43f1a31375c6f6fe7dcafb9d96c231b98d1f6ba4", + "desktop/scripts/verify-linux-sidecar.sh": "c502bb5c8ba8346c722a8f5274f2274bb325a934", + "desktop/scripts/appimage-patchelf.py": "63e78ef74160bc48fbcdd882065f1d416db6d13c", + "desktop/scripts/linux-packaged-e2e.ts": "9ca92352668ff881c85caea44a9b4747bedc7e2d" + } + }, + { + "kind": "ci", + "version": 1, + "windowsShards": 14, + "files": { + ".github/workflows/ci.yml": "4ae44e193c6813a0378700f37c1cebaca7327cf1", + ".github/actions/setup-project-bun/action.yml": "cf28f6f9d4385d69784f4e3610914f6952ce789d", + ".github/scripts/release-evidence.cjs": "ace2b9006b2d58ef84ed0996b4e179ff4be15900", + ".github/scripts/release-evidence.test.cjs": "9cc686390e5c37d8e693b98d049e8b505d0273cf", + "scripts/ci/select-test-lane.sh": "b25836cb55f962d1ffd9e68ed00f45f8b45becc8", + "scripts/ci/windows-sensitive-diff.sh": "03495f256c671aff57e750febffe19ca7face6a1", + "scripts/ci/run-bun-test-batches.sh": "59b1783aadf8109c0fa2d37047ff0d90300aa267", + "scripts/ci/bun-crash-signatures.sh": "d34662ddd07864d97bed909135095db33fe42c9e", + "scripts/ci/bun-install-frozen.sh": "e6d7bc3aec044e12297c7c4c04015a33df0eb22b", + "scripts/ci/docker-smoke.ts": "4eea7637d8658156feeaa356c0c3086c00d75fa5", + "scripts/ci/test-durations.tsv": "a07f90e6098082e1452ea5cc075c801271321eca", + "scripts/ci/test-durations.windows.tsv": "523cef871c3e17fc0344c98fb15eef79feb04c84", + "scripts/test.ts": "5b73037fb54e685b1d3485ea664e82a1eb418606", + "scripts/lib/test-runner-bun.ts": "8763806104a851dbdefeea8cffe8d7dd8d1c8da1", + "scripts/test-temp-lock.ts": "ee83fb254b728de119028f52b9894bf52d7aea15", + "scripts/git-repository-env.ts": "267950490fffb4c48d9adb90bdcf5a873733b324", + "scripts/ci/run-changed-tests.sh": "9a54d3a5db9849bcbe0dd766954a840185419fa5", + "scripts/keyring-smoke.ts": "cd3be07ad57796172696dfa053ea1fb129f29365", + "scripts/privacy-scan.ts": "86314e891b45e49739b94c76cddd9e4cc2d4340f", + "scripts/structure-ssot.ts": "5b2d2918dae877fddfb16cdba6e89f0d10e82298", + "scripts/generate-ocx-skill-surface.ts": "155e866656ba2d71e8fd48adda857451caf16322", + "desktop/scripts/prepare-sidecar.ts": "20f7eec61f73635ea681e25f13dd850b62bb41e2", + "desktop/scripts/build-widget.sh": "38e0eb9d713804b603aa75c32383aa18ef01d06c", + "desktop/scripts/verify-macos-runtime.sh": "43f1a31375c6f6fe7dcafb9d96c231b98d1f6ba4", + "desktop/scripts/verify-linux-sidecar.sh": "c502bb5c8ba8346c722a8f5274f2274bb325a934", + "desktop/scripts/appimage-patchelf.py": "63e78ef74160bc48fbcdd882065f1d416db6d13c", + "desktop/scripts/linux-packaged-e2e.ts": "9ca92352668ff881c85caea44a9b4747bedc7e2d" + } + }, + { + "kind": "ci", + "version": 1, + "windowsShards": 14, + "files": { + ".github/workflows/ci.yml": "74f5dfb883786792c872c58f2311b0299818b702", + ".github/actions/setup-project-bun/action.yml": "cf28f6f9d4385d69784f4e3610914f6952ce789d", + ".github/scripts/release-evidence.cjs": "ace2b9006b2d58ef84ed0996b4e179ff4be15900", + ".github/scripts/release-evidence.test.cjs": "9cc686390e5c37d8e693b98d049e8b505d0273cf", + "scripts/ci/select-test-lane.sh": "b25836cb55f962d1ffd9e68ed00f45f8b45becc8", + "scripts/ci/windows-sensitive-diff.sh": "03495f256c671aff57e750febffe19ca7face6a1", + "scripts/ci/run-bun-test-batches.sh": "f8aa18e80aff1c95c584cd2c879dfbb6806c11fb", + "scripts/ci/bun-crash-signatures.sh": "d34662ddd07864d97bed909135095db33fe42c9e", + "scripts/ci/bun-install-frozen.sh": "e6d7bc3aec044e12297c7c4c04015a33df0eb22b", + "scripts/ci/docker-smoke.ts": "4eea7637d8658156feeaa356c0c3086c00d75fa5", + "scripts/ci/test-durations.tsv": "6ff82545debbd95286928a7a99abfdeb10020a7a", + "scripts/ci/test-durations.windows.tsv": "523cef871c3e17fc0344c98fb15eef79feb04c84", + "scripts/test.ts": "58c52fd2002c2692b9744dc5ea032af247807367", + "scripts/lib/test-runner-bun.ts": "8763806104a851dbdefeea8cffe8d7dd8d1c8da1", + "scripts/test-temp-lock.ts": "ee83fb254b728de119028f52b9894bf52d7aea15", + "scripts/git-repository-env.ts": "267950490fffb4c48d9adb90bdcf5a873733b324", + "scripts/ci/run-changed-tests.sh": "9a54d3a5db9849bcbe0dd766954a840185419fa5", + "scripts/keyring-smoke.ts": "cd3be07ad57796172696dfa053ea1fb129f29365", + "scripts/privacy-scan.ts": "86314e891b45e49739b94c76cddd9e4cc2d4340f", + "scripts/structure-ssot.ts": "5b2d2918dae877fddfb16cdba6e89f0d10e82298", + "scripts/generate-ocx-skill-surface.ts": "155e866656ba2d71e8fd48adda857451caf16322", + "desktop/scripts/prepare-sidecar.ts": "20f7eec61f73635ea681e25f13dd850b62bb41e2", + "desktop/scripts/build-widget.sh": "38e0eb9d713804b603aa75c32383aa18ef01d06c", + "desktop/scripts/verify-macos-runtime.sh": "43f1a31375c6f6fe7dcafb9d96c231b98d1f6ba4", + "desktop/scripts/verify-linux-sidecar.sh": "c502bb5c8ba8346c722a8f5274f2274bb325a934", + "desktop/scripts/appimage-patchelf.py": "63e78ef74160bc48fbcdd882065f1d416db6d13c", + "desktop/scripts/linux-packaged-e2e.ts": "9ca92352668ff881c85caea44a9b4747bedc7e2d" + } + }, + { + "kind": "ci", + "version": 1, + "windowsShards": 14, + "files": { + ".github/workflows/ci.yml": "74f5dfb883786792c872c58f2311b0299818b702", + ".github/actions/setup-project-bun/action.yml": "cf28f6f9d4385d69784f4e3610914f6952ce789d", + ".github/scripts/release-evidence.cjs": "ace2b9006b2d58ef84ed0996b4e179ff4be15900", + ".github/scripts/release-evidence.test.cjs": "9cc686390e5c37d8e693b98d049e8b505d0273cf", + "scripts/ci/select-test-lane.sh": "b25836cb55f962d1ffd9e68ed00f45f8b45becc8", + "scripts/ci/windows-sensitive-diff.sh": "03495f256c671aff57e750febffe19ca7face6a1", + "scripts/ci/run-bun-test-batches.sh": "59b1783aadf8109c0fa2d37047ff0d90300aa267", + "scripts/ci/bun-crash-signatures.sh": "d34662ddd07864d97bed909135095db33fe42c9e", + "scripts/ci/bun-install-frozen.sh": "e6d7bc3aec044e12297c7c4c04015a33df0eb22b", + "scripts/ci/docker-smoke.ts": "4eea7637d8658156feeaa356c0c3086c00d75fa5", + "scripts/ci/test-durations.tsv": "9dd8d4194c7950c9aaa2e3f96f9225869c854b72", + "scripts/ci/test-durations.windows.tsv": "523cef871c3e17fc0344c98fb15eef79feb04c84", + "scripts/test.ts": "b29da2511aae387c13cace2e66f697b7092e42f2", + "scripts/lib/test-runner-bun.ts": "8763806104a851dbdefeea8cffe8d7dd8d1c8da1", + "scripts/test-temp-lock.ts": "ee83fb254b728de119028f52b9894bf52d7aea15", + "scripts/git-repository-env.ts": "267950490fffb4c48d9adb90bdcf5a873733b324", + "scripts/ci/run-changed-tests.sh": "9a54d3a5db9849bcbe0dd766954a840185419fa5", + "scripts/keyring-smoke.ts": "cd3be07ad57796172696dfa053ea1fb129f29365", + "scripts/privacy-scan.ts": "86314e891b45e49739b94c76cddd9e4cc2d4340f", + "scripts/structure-ssot.ts": "5b2d2918dae877fddfb16cdba6e89f0d10e82298", + "scripts/generate-ocx-skill-surface.ts": "155e866656ba2d71e8fd48adda857451caf16322", + "desktop/scripts/prepare-sidecar.ts": "20f7eec61f73635ea681e25f13dd850b62bb41e2", + "desktop/scripts/build-widget.sh": "38e0eb9d713804b603aa75c32383aa18ef01d06c", + "desktop/scripts/verify-macos-runtime.sh": "43f1a31375c6f6fe7dcafb9d96c231b98d1f6ba4", + "desktop/scripts/verify-linux-sidecar.sh": "c502bb5c8ba8346c722a8f5274f2274bb325a934", + "desktop/scripts/appimage-patchelf.py": "63e78ef74160bc48fbcdd882065f1d416db6d13c", + "desktop/scripts/linux-packaged-e2e.ts": "9ca92352668ff881c85caea44a9b4747bedc7e2d" + } + }, + { + "kind": "ci", + "version": 1, + "windowsShards": 14, + "files": { + ".github/workflows/ci.yml": "4ae44e193c6813a0378700f37c1cebaca7327cf1", + ".github/actions/setup-project-bun/action.yml": "cf28f6f9d4385d69784f4e3610914f6952ce789d", + ".github/scripts/release-evidence.cjs": "ace2b9006b2d58ef84ed0996b4e179ff4be15900", + ".github/scripts/release-evidence.test.cjs": "9cc686390e5c37d8e693b98d049e8b505d0273cf", + "scripts/ci/select-test-lane.sh": "b25836cb55f962d1ffd9e68ed00f45f8b45becc8", + "scripts/ci/windows-sensitive-diff.sh": "03495f256c671aff57e750febffe19ca7face6a1", + "scripts/ci/run-bun-test-batches.sh": "59b1783aadf8109c0fa2d37047ff0d90300aa267", + "scripts/ci/bun-crash-signatures.sh": "d34662ddd07864d97bed909135095db33fe42c9e", + "scripts/ci/bun-install-frozen.sh": "e6d7bc3aec044e12297c7c4c04015a33df0eb22b", + "scripts/ci/docker-smoke.ts": "4eea7637d8658156feeaa356c0c3086c00d75fa5", + "scripts/ci/test-durations.tsv": "a07f90e6098082e1452ea5cc075c801271321eca", + "scripts/ci/test-durations.windows.tsv": "523cef871c3e17fc0344c98fb15eef79feb04c84", + "scripts/test.ts": "c18e561ba35cb72ff83d8e592146dcea8bd1b27f", + "scripts/lib/test-runner-bun.ts": "8763806104a851dbdefeea8cffe8d7dd8d1c8da1", + "scripts/test-temp-lock.ts": "ee83fb254b728de119028f52b9894bf52d7aea15", + "scripts/git-repository-env.ts": "267950490fffb4c48d9adb90bdcf5a873733b324", + "scripts/ci/run-changed-tests.sh": "9a54d3a5db9849bcbe0dd766954a840185419fa5", + "scripts/keyring-smoke.ts": "cd3be07ad57796172696dfa053ea1fb129f29365", + "scripts/privacy-scan.ts": "86314e891b45e49739b94c76cddd9e4cc2d4340f", + "scripts/structure-ssot.ts": "5b2d2918dae877fddfb16cdba6e89f0d10e82298", + "scripts/generate-ocx-skill-surface.ts": "155e866656ba2d71e8fd48adda857451caf16322", + "desktop/scripts/prepare-sidecar.ts": "20f7eec61f73635ea681e25f13dd850b62bb41e2", + "desktop/scripts/build-widget.sh": "38e0eb9d713804b603aa75c32383aa18ef01d06c", + "desktop/scripts/verify-macos-runtime.sh": "43f1a31375c6f6fe7dcafb9d96c231b98d1f6ba4", + "desktop/scripts/verify-linux-sidecar.sh": "c502bb5c8ba8346c722a8f5274f2274bb325a934", + "desktop/scripts/appimage-patchelf.py": "63e78ef74160bc48fbcdd882065f1d416db6d13c", + "desktop/scripts/linux-packaged-e2e.ts": "9ca92352668ff881c85caea44a9b4747bedc7e2d" + } } ] diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 034232e333f..abc76c795ca 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -626,10 +626,14 @@ jobs: needs: changes if: github.event_name != 'pull_request' || (needs.changes.outputs.ci == 'true' && needs.changes.outputs.fast != 'true') runs-on: ${{ vars.LIDGE_RUNNERS == 'on' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository || contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.pull_request.author_association)) && fromJSON('["self-hosted","linux","x64","lidge"]') || 'ubuntu-latest' }} - # A fifth of the suite. A shard that needs longer than this is wedged, not - # slow — the old 30-minute ceiling was margin for the Windows leg, which no - # longer runs here (see platform-windows). - timeout-minutes: 15 + # A fifth of the suite. 20 rather than 15 is headroom for hosted runners: + # ubuntu-latest shards were cancelled at the 15-minute wall in their last + # batches with no failing tests (#8651 shard 1 at batch 62/65 and shard 5 at + # 66/66; also #8585, #8645, #8841, #8861, #8887), and a cancelled shard is + # neither a pass nor a fail. A shard far beyond 20 minutes is still wedged, + # not slow. The old 30-minute ceiling was margin for the Windows leg, which + # no longer runs here (see platform-windows). + timeout-minutes: 20 strategy: fail-fast: false matrix: @@ -820,9 +824,7 @@ jobs: - name: Install dependencies run: bash scripts/ci/bun-install-frozen.sh . gui - - name: Gateway quota and cache guardrails - run: bun run test:gateway-quota - + - { name: Gateway quota and cache guardrails, run: bun run test:gateway-quota } - name: GUI lint if: needs.changes.outputs.gui == 'true' run: | diff --git a/.gitignore b/.gitignore index b07c5979db3..ec63a4f047b 100644 --- a/.gitignore +++ b/.gitignore @@ -49,6 +49,12 @@ devlog/**/security-advisory-draft* .omo/ **/.omo/ +# Bun's on-disk build cache. Bun writes it into whichever directory it runs in, and +# `git add -A` has swept two 59 MB copies of it into this history — see +# tests/ci-workflows/repo-hygiene.test.ts, which fails if any path here becomes +# tracked again. +*.bun-build + # Local development worktrees .worktrees/ diff --git a/README.md b/README.md index 191c3df18db..cf3b4b23655 100644 --- a/README.md +++ b/README.md @@ -307,7 +307,7 @@ see the [installation docs](https://opencodex.me/getting-started/installation/). OpenCodex tracks process-retained state in the categories below. Each has a documented bound: -- **14 retained stores** (request log, debug rings, image cache, model cache, vision +- **15 retained stores** (request log, debug rings, image cache, model cache, vision descriptions, cursor blobs, responses continuation, etc.) are byte-accounted and evicted by the app-owned memory budget (default 256 MiB), except the native control replay store, which is pinned and never evicted. diff --git a/bin/ocx.mjs b/bin/ocx.mjs index ab7dd8b6659..a156f0fc00e 100755 --- a/bin/ocx.mjs +++ b/bin/ocx.mjs @@ -1580,6 +1580,8 @@ function createNodeLaunchContext() { version: 1, proof: launchProof, anthropicEnvSlots: preBunAnthropicSlots, + // Running this shim under Bun can already have loaded project dotenv. + managedRelease: process.versions.bun === undefined && process.env.OCX_MANAGED_RELEASE === "1", codexCliInspectionEnv: codexCliUpdateInspectionContext ? { codexCliPath: preBunCodexCliPath, path: preBunPath, diff --git a/bunfig.toml b/bunfig.toml index 7376005a5c5..4f04f9db58b 100644 --- a/bunfig.toml +++ b/bunfig.toml @@ -16,10 +16,6 @@ root = "tests" # # That qualifier is load-bearing. Bun resolves bunfig.toml from the CURRENT WORKING # DIRECTORY, so `cd /tmp && bun test /tests/x.test.ts` loads no preload at all: nothing -# is sandboxed, and every `getConfigDir()` in that process returns the developer's real -# `~/.opencodex`. On 2026-09-15 such a run deleted one, and in #7407 another wrote auth.json. -# The write guard now arms itself from the test-file entry in that case (src/lib/test-home-guard.ts), -# so such writes throw instead of landing, but a test that needs a config directory still pins its -# own OPENCODEX_HOME instead of trusting this line, and `tests/ci-workflows/test-home-guard.test.ts` -# enforces that for the destructive case. +# is sandboxed. The guard still arms from the test-file entry (src/lib/test-home-guard.ts) +# and refuses writes to the real home. Tests that write config must pin an isolated OPENCODEX_HOME. preload = ["./tests/preload.ts"] diff --git a/desktop/src-tauri/Cargo.lock b/desktop/src-tauri/Cargo.lock index 9eaa7580eaa..e8372b53288 100644 --- a/desktop/src-tauri/Cargo.lock +++ b/desktop/src-tauri/Cargo.lock @@ -2633,7 +2633,7 @@ dependencies = [ [[package]] name = "opencodex-desktop" -version = "2.100.0-vadymhimself.2" +version = "2.100.0" dependencies = [ "base64 0.22.1", "dbus", diff --git a/desktop/src-tauri/Cargo.toml b/desktop/src-tauri/Cargo.toml index 901345b3f27..cc960d1bdc9 100644 --- a/desktop/src-tauri/Cargo.toml +++ b/desktop/src-tauri/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "opencodex-desktop" -version = "2.100.0-vadymhimself.2" +version = "2.100.0" description = "OpenCodex desktop shell" authors = ["OpenCodex contributors"] license = "MIT" diff --git a/desktop/src-tauri/src/provider_icons.rs b/desktop/src-tauri/src/provider_icons.rs index 515d9b9f643..6335d809c46 100644 --- a/desktop/src-tauri/src/provider_icons.rs +++ b/desktop/src-tauri/src/provider_icons.rs @@ -44,9 +44,11 @@ const ALIASES: &[(&str, &str)] = &[ ("fireworks", "fireworks-color.svg"), ("github", "github-copilot-color.svg"), ("github-copilot", "copilot-color.svg"), + ("m365-copilot", "copilot-color.svg"), ("gitlab-duo", "gitlab-duo-color.svg"), ("google", "gemini-color.svg"), ("google-antigravity", "antigravity-color.svg"), + ("antigravity-acp", "antigravity-color.svg"), ("google-vertex", "gemini-color.svg"), ("groq", "groq-color.svg"), ("huggingface", "huggingface-color.svg"), diff --git a/desktop/src-tauri/tauri.conf.json b/desktop/src-tauri/tauri.conf.json index b8c12e3f7e2..a9325d3a6fd 100644 --- a/desktop/src-tauri/tauri.conf.json +++ b/desktop/src-tauri/tauri.conf.json @@ -1,7 +1,7 @@ { "$schema": "https://schema.tauri.app/config/2", "productName": "OpenCodex", - "version": "2.100.0-vadymhimself.2", + "version": "2.100.0", "identifier": "com.opencodex.desktop", "build": { "frontendDist": "../ui", diff --git a/devlog/_fin/261117_terminal_repair_ci_comparison/010_bounded_comparison.md b/devlog/_fin/261117_terminal_repair_ci_comparison/010_bounded_comparison.md new file mode 100644 index 00000000000..09455941a70 --- /dev/null +++ b/devlog/_fin/261117_terminal_repair_ci_comparison/010_bounded_comparison.md @@ -0,0 +1,159 @@ +# Terminal-repair PR: bounded credential-masking comparison + +This is the initial record at `dad1813b3`. The subsequent production fix and +new base/head measurements are in [the profiled follow-up](020_profiled_redaction_fix.md). + +## Question and result + +PR #8774 reuses the incremental SSE buffer in Responses terminal repair. Its +`test changed` job failed the existing large-terminal credential-excerpt test. +This record answers the maintainer's request to compare the original PR head +with its base without skipping assertions, increasing deadlines, or retrying CI +until it passes. + +The focused comparison reproduces the same 1,500 ms failure on **both** commits. +It does not establish a regression caused by terminal-repair buffering, and it +does not establish the exact scheduling cause of the Linux CI failure. All +observed target-test failures were at the elapsed-time assertion, after the +credential-content assertion. The failing CI remains a hold. + +No production code, test assertions, test deadlines, test selection rules, or +workflow configuration were changed for this follow-up. + +## Revisions and original CI evidence + +- Base: `1d10758fa6ced80cdd780cb000bc5c4b83f84703`. +- Original PR head: `ada6a63b052da9b95f71f23e738ddaee08c78303`. +- CI: run `43721018165`, job `133247879390` (`test changed`), Ubuntu hosted + runner, Bun `1.4.4` (`38afee6c8`), four test workers. +- CI result: 23,214 passed, 75 skipped, one failed. The existing + `tests/responses/sse-untyped-credential-mask.test.ts:552` assertion observed + `1555.7457600000198 ms`, requiring `<1500 ms`. Its content assertion passed. +- This follow-up did not dispatch or rerun hosted CI. + +## Comparison protocol + +The comparison ran on one native Windows machine with eight logical processors, +using Bun `1.4.4` and the same installed dependencies. The base used a detached +worktree with junctions to the head checkout's dependency directories; nothing +was installed or upgraded for the comparison. Each invocation used a fresh +process and the repository's ordinary test wrapper and home isolation. No other +agent test or build was run concurrently with these measurements. + +The sample count and order were fixed before measurement: three pairs per +scenario, in the order **base, head, head, base, base, head**. No sample was +discarded and no failed invocation was retried to obtain green output. + +Two focused scenarios used the same command on both revisions: + +1. The complete, unchanged credential-masking test file, with four workers + configured; one selected file means there is no other test-file worker load. +2. The same file plus three fixed companion files, with four workers: + `responses-terminal-repair.test.ts`, `sse-payload-rewrite.test.ts`, and + `sse-failed-tail.test.ts`, all under `tests/responses/`. The head includes its + four new terminal-repair cases; this intentionally compares the actual PR + workload, rather than removing its new tests. + +An identical diagnostic preload on both revisions captured the two real +`performance.now()` values used by the target assertion. It returned the +original clock values and restored its spy after each case. Stack attribution +was checked before the first timestamp, using the unchanged line 548 call site; +only that case emitted a measurement, so parallel companion output could not +be mistaken for its timer. No fake clock or altered expectation was used. + +The preload was: + +```ts +import { beforeEach, afterEach, spyOn } from "bun:test"; +let reads: number[] = []; +let target = false; +let clock: ReturnType | undefined; +beforeEach(() => { + reads = []; + target = false; + const now = performance.now.bind(performance); + clock = spyOn(performance, "now").mockImplementation(() => { + if (reads.length === 0) target = new Error().stack?.includes("sse-untyped-credential-mask.test.ts:548:") ?? false; + const value = now(); + reads.push(value); + return value; + }); +}); +afterEach(() => { + clock?.mockRestore(); + if (target && reads.length === 2) console.error(`PR8774_ELAPSED_MS=${reads[1]! - reads[0]!}`); +}); +``` + +Save it outside test discovery and pass its absolute path as `PROBE` in each +checkout. The commands were equivalent to: + +```sh +bun run test -- --parallel=4 --preload "$PROBE" \ + tests/responses/sse-untyped-credential-mask.test.ts +bun run test -- --parallel=4 --preload "$PROBE" \ + tests/responses/sse-untyped-credential-mask.test.ts \ + tests/responses/responses-terminal-repair.test.ts \ + tests/responses/sse-payload-rewrite.test.ts \ + tests/responses/sse-failed-tail.test.ts +``` + +## Every measured sample + +Values below are the target assertion's elapsed milliseconds, in per-revision +execution order, rounded only for display. Every invocation exited 1; every +target sample exceeded the unchanged 1,500 ms deadline. + +| Scenario | Base samples (ms) | PR samples (ms) | Base median | PR median | +| --- | --- | --- | ---: | ---: | +| Single file | 3851.76, 2714.90, 2859.51 | 3173.92, 2656.73, 2833.17 | 2859.51 | 2833.17 | +| Four files | 3052.95, 3447.86, 2847.55 | 3417.38, 3320.02, 2955.70 | 3052.95 | 3320.02 | + +The single-file PR median is 0.9% lower; the four-file PR median is 8.7% higher. +The sample ranges overlap in each scenario. Three samples per revision on +Windows are not enough to declare statistical equivalence, diagnose Linux +runner contention, or dismiss the original failure as a flake. + +The single-file runs all reported 95 passed / 3 failed. Four-file base runs +reported 405/3, 405/3, and 406/2; head runs reported 410/2, 409/3, and 409/3. +Other observed failures were the existing elapsed-time assertions for repeated +or self-overlapping credentials and for registry lookup. No content assertion +failed. The four new terminal-repair regression cases passed in every head +bundle. + +## Control without measurement instrumentation + +After the fixed comparison, one original single-file invocation per revision +omitted the diagnostic preload, with all other command arguments unchanged. +This was an instrumentation control, not a retry policy. + +| Revision | Original assertion elapsed | Bun case duration | Full-file result | +| --- | ---: | ---: | --- | +| Base | 2875.48 ms | 2968.08 ms | 95 passed / 3 failed, exit 1 | +| PR | 2621.31 ms | 2710.52 ms | 96 passed / 2 failed, exit 1 | + +Both controls failed the original target's elapsed-time assertion; its failure +output supplied the original clock measurement directly. Bun case durations +also include fixture/assertion overhead. The baseline failure persists without +the diagnostic spy. + +## Scope and disposition + +Between these commits the failing test and its synchronous masking path are +unchanged: `src/server/responses/terminal-error-redaction.ts`, +`src/lib/outbound-credential-registry.ts`, `src/lib/redact.ts`, +`src/server/sse-payload-rewrite.ts`, `src/server/bare-upstream-error.ts`, and +`src/lib/errors.ts` have no diff. The timed callback calls the terminal-error +rewrite; it does not call `relayResponsesSseWithTerminalRepair`. The original PR +changes that relay, its tests, and the byte-accounting documentation. + +This supports reporting baseline timing sensitivity rather than claiming a +confirmed terminal-repair regression. It does not justify changing credential +handling or weakening its content or bounded-work contracts. This follow-up +therefore adds the comparison record only. The existing required CI failure +and maintainer hold are retained; passing local runtime/structure checks from +the original PR are not presented as a replacement for that failed CI. + +Raw logs, the detached worktree, and machine-specific results remain in ignored +scratch space; no credentials, user paths, profiler data, or CI log dumps are +committed. diff --git a/devlog/_fin/261117_terminal_repair_ci_comparison/020_profiled_redaction_fix.md b/devlog/_fin/261117_terminal_repair_ci_comparison/020_profiled_redaction_fix.md new file mode 100644 index 00000000000..26a1e4abbdd --- /dev/null +++ b/devlog/_fin/261117_terminal_repair_ci_comparison/020_profiled_redaction_fix.md @@ -0,0 +1,170 @@ +# Terminal-repair PR: profiled redaction follow-up + +## Scope and revisions + +PR #8774 originally changed terminal-repair buffering. Its failing CI assertion +exercises the shared credential masker, unchanged between the original base and +head. The initial bounded comparison remains in `010_bounded_comparison.md`; +this follow-up fixes measured work without changing assertions or deadlines. + +- Original base: `1d10758fa6ced80cdd780cb000bc5c4b83f84703`. +- Original PR code: `ada6a63b052da9b95f71f23e738ddaee08c78303`. +- Refreshed comparison base: `c36793a9336b70cfe5bc3b7f6e6f751e730fb6fc`. +- Refreshed dev merge: `cb8f180d2ac174447abc0ffe937cf94101048afe`. +- Lazy ASCII offsets: `56bc8e92b`. +- Complete redaction fix: `16d3b83be0c1380038f77ae967c5b9231a5b988c`. + +Registry, folding, redaction and the failing test have no source change between +the original and refreshed bases. The branch includes dev through a normal merge. + +## Profile and counted work + +A Bun 1.4.4 CPU profile on Windows used the original four 16,000-character fixture +credentials and 3,900,001-character message. The diagnostic driver separately +invoked exact masking, pattern masking, excerpt masking, the complete rewrite and +a 20,000-value registry check. This deliberately repeats work and is not a +breakdown of the test's timer. The excerpt closure, `markSubstringSpans` and +`containsIndexedSecret` accounted for approximately 71% of self time; each sliced +eight characters at every position before its Set/Map lookup. Folding also +initialized large offset arrays even when no label matched. Profiler-enabled +times are not used as speed evidence. + +A separate source-counter experiment counted ASCII identity-array constructions +larger than one million entries. Temporary copies redirected folding/redaction/ +registry imports, preserving real other helpers; counters ran only at allocation. +Counting and timing runs were separate. The original full rewrite created: + +| Identity-array size | Original count | Lazy-map count | +| --- | ---: | ---: | +| 3,900,002 entries | 10 | 0 | +| 3,836,046 entries | 10 | 0 | +| Total initialized entries | 77,360,480 | 0 | + +The complete output SHA-256 matched with original, lazy-map-only and combined +implementations: `9d4440072fee38f7e34a66e12877b610751506ec331c131aaaf05fa4ea0b04d9`. +Entries are counted, not converted into a claimed engine-specific heap saving. + +## Changes and bounds + +1. ASCII folding caches its identity map on first access; four pattern consumers + request offsets only after matching. Unicode/escape folding and offset + fallbacks are unchanged. Repeated access returns the same array. No repository + consumer assigns the `map` property. +2. Literal ASCII without label delimiters (`:`, `=`, `<`) or escape introducers + bypasses label folding. Every labelled grammar requires those delimiters; + Unicode and escaped input keeps both matching views. Token-pattern masking, + including unlabelled bearers and JWTs, still runs. +3. Window/prefix indexes reject impossible first-two-code-unit pairs before + slicing. Each nonempty index adds an 8 KiB UTF-16 low-byte bitset. Collisions + still require the original exact lookup; no filter match grants acceptance. +4. The prefix walk stops once every deduplicated long secret has had its full + overlapping KMP scan. Short matches are already marked; unscanned/non-overlapping + secrets prevent the return. Work-budget charges and fail-closed results remain. + +Worst-case time stays O(n). An ASCII nonmatch needs O(1) offset-map space instead +of O(n). Prefix slices become O(c), for c candidate starts <= n, while the filter +still scans O(n) characters. Deterministic regressions count 4,089 -> 0 slices on +a 4,096-character impossible-prefix input in four paths, and 4,089 -> 1 prefix +lookup for a fully scanned repeated key. + +The lazy-map-only Bun variant removed the arrays but still failed the original +elapsed assertion locally. An intermediate combined variant exceeded the +eight-file deadlines too (target 1,547.85 ms; repeated-key case 1,537.24 ms). +This motivated delimiter rejection. Those failures were retained, not retried +until green or hidden by weakening assertions. + +## Regression and differential evidence + +Seven deterministic work checks fail on unchanged base code: five prefix/lookup +checks and two folding checks. Their focused negative controls select test names +only to prove the new regressions are red on old code. Successful validation runs +entire files. New coverage includes raw/escaped control characters, quotes, +backslashes, lone surrogates, low-byte collisions, cached-index reuse, multiple +overlapping secrets, safe surrounding copy and later short matches. Existing +credential-content, protocol, classification, scan-cap, overflow, bounded-work +and elapsed-time assertions remain in place. + +Temporary differential drivers compared complete outputs rather than selected +credential excerpts: + +- Seed 41: 20,006 comparisons of masks, guards and indexed containment, including + short/overlapping values, UTF-16, cached reuse, scan boundaries and overflow. +- Seed `0x8774da`: 2,048 complete pattern-redaction outputs, 4,096 complete folded + strings/offset arrays across both decode modes, and 256 complete terminal SSE + rewrites with nested output/metadata: 6,400 comparisons. +- All 26,406 comparisons matched. Digests of the result sequences: + `91462475c6365181e26e33b6915e3b235275f7904b002afae60682be35c7bb8a` + and `e80e31c7fa760a441fd80ab36caf68618787b3a857d9e047f4a4f6da53850831`. + +## Fixed-order full-file comparison + +Both revisions used one native Windows machine, Bun 1.4.4, the same installed +dependencies, repository wrapper and home isolation, with fresh processes and +four workers configured. The detached base shared dependency directories by +junction; neither dependencies nor runtime changed. No other agent test, build +or profile ran concurrently with these samples. + +Sample count/order were fixed before starting: three pairs per scenario, +**base, head, head, base, base, head**. Both checkout hashes were checked first. +Every sample/exit code is retained. The initial comparison's clock preload +captured real timestamps at unchanged line 548; no clock or assertion was faked. +The new counter tests run after the original timed tests in that file. + +The commands use the initial document's preload as an absolute PROBE path: + +```sh +bun run test -- --parallel=4 --preload "$PROBE" tests/responses/sse-untyped-credential-mask.test.ts +bun run test -- --parallel=4 --preload "$PROBE" tests/responses/sse-untyped-credential-mask.test.ts tests/responses/responses-terminal-repair.test.ts tests/responses/sse-payload-rewrite.test.ts tests/responses/sse-failed-tail.test.ts +``` + +The one-file scenario has no other test-file worker load. The four-file scenario +includes the actual terminal-repair tests on each revision, including PR cases. + +The elapsed column is the original assertion's measurement, not runner test time: + +| Run | Scenario | Revision | Elapsed ms | Pass / fail | Exit | +| ---: | --- | --- | ---: | --- | ---: | +| 1 | One file | Base | 3194.34 | 96 / 2 | 1 | +| 2 | One file | Head | 406.46 | 116 / 0 | 0 | +| 3 | One file | Head | 393.22 | 116 / 0 | 0 | +| 4 | One file | Base | 2414.40 | 97 / 1 | 1 | +| 5 | One file | Base | 2358.95 | 97 / 1 | 1 | +| 6 | One file | Head | 398.84 | 116 / 0 | 0 | +| 7 | Four files | Base | 2476.73 | 407 / 1 | 1 | +| 8 | Four files | Head | 443.71 | 430 / 0 | 0 | +| 9 | Four files | Head | 452.78 | 430 / 0 | 0 | +| 10 | Four files | Base | 2395.23 | 407 / 1 | 1 | +| 11 | Four files | Base | 2633.43 | 407 / 1 | 1 | +| 12 | Four files | Head | 378.49 | 430 / 0 | 0 | + +Medians: one file **2414.40 -> 398.84 ms**; four files **2476.73 -> 443.71 ms**. +All six base invocations failed the unchanged target assertion. All six head +invocations passed every selected test. No samples were discarded or retried. +These are bounded local measurements, not a cross-machine speed guarantee. + +## Other verification and limits + +The final full eight-file related set at four workers passed 633 tests, with +0 failures and 2,600 assertions (58.76 s): the four comparison files plus +`tests/lib/redact.test.ts`, `tests/usage/upstream-failure-diagnostics.test.ts`, +`tests/responses/responses-fetch-helpers-boundary.test.ts`, and +`tests/responses/responses-request-compression.test.ts`. Additional framing/provider +coverage passed 69 tests and 420 assertions (18.82 s): +`tests/responses/sse-payload-rewrite-continuation.test.ts`, +`tests/responses/sse-carriage-return.test.ts`, +`tests/providers/deepseek-inbound-wire.test.ts`, +`tests/providers/opencode-muse-terminal-repair.test.ts`. + +A synthetic bearer fixture initially tripped privacy scanning. It was replaced +with the existing allowed test sentinel; the entire library file then passed +53 tests/306 assertions. Scanner rules and exceptions were unchanged. + +Typecheck passed for 2,564 files; structure, privacy and whitespace checks passed. + +Full-suite scope exception: the common redactor's import graph is broad (previous +CI selected 903 files and over 23,000 tests). This run uses the focused full-file +suites above rather than another full repository or `test:changed` run on Windows. +It does not claim full cross-platform coverage or explain the Linux scheduling/GC +conditions. Required CI must succeed on the new PR head; the existing CI hold +remains. No hosted dispatch or retry was requested. Credential handling requires +explicit maintainer security review before merge. diff --git a/devlog/_plan/261112_account_probe_and_model_discovery/010_design.md b/devlog/_plan/261112_account_probe_and_model_discovery/010_design.md new file mode 100644 index 00000000000..cabf4e2c54d --- /dev/null +++ b/devlog/_plan/261112_account_probe_and_model_discovery/010_design.md @@ -0,0 +1,86 @@ +# Per-account probe and manual model discovery + +Status: contributor design for PR #8740. + +## Problem + +1. `POST /api/providers/test` resolves only the active account's token, so an operator with a + pool of Google Antigravity accounts cannot tell which individual accounts still work. Accounts + that started returning `permission_denied` could only be checked with an out-of-tree script. +2. Model discovery runs implicitly (catalog convergence, `liveModels`). There is no per-provider + "discover now" action, and recent arrivals only show as small NEW badges on the Models page. + +## 1. Per-account probe + +`POST /api/oauth/accounts/probe` — body `{ "provider": "google-antigravity", "accountId"?: string }`. +Omitting `accountId` probes every stored account (concurrency 4). Response: + +```json +{ "provider": "google-antigravity", "probedAt": "", + "results": [{ "accountId": "…", "maskedLabel": "a***b@example.com", "active": true, "paused": false, + "status": "ok", "httpStatus": 200, "reason": null, "message": null, + "expiresAt": 0, "latencyMs": 412, "quota": { "customWindows": [] } }] } +``` + +`status` is one of: + +| status | meaning | rule | +| --- | --- | --- | +| `ok` | usable | HTTP 200 | +| `paused` | account is paused by the operator; not tested | `account.paused === true`; no request is sent | +| `token_expired` | stored access token expired, not refreshed | `credential.expires <= now`; no request is sent | +| `suspended` | upstream says the account is suspended/disabled | 403 whose reason/message names suspension, disablement or ToS | +| `verification_required` | upstream asks the user to verify the account | 403 with `details[].reason == VALIDATION_REQUIRED` or "verify your account" wording | +| `rate_limited` | throttled / quota exhausted | 429 or `RESOURCE_EXHAUSTED` | +| `permission_denied` | other 403 | 403 | +| `error` | anything else (401, 5xx, transport, missing project) | `httpStatus` and `reason` carry the detail | + +Read-only by construction: + +- Uses the account's stored access token exactly as read through `getAccountSet()`; never calls + `getValidAccessToken`, never refreshes, never writes the auth store, never changes pause, + active, cooldown or health state. Paused accounts are skipped with status `paused` and no + request: an operator who parked an account has said not to use it, and a probe is still a use. + To test one, resume it first. +- One request: `POST https://daily-cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary` + with `{ "project": }` and `User-Agent: antigravityCliUserAgent()`. Unlike the quota + poller there is no 403 retry under the IDE UA and no `fetchAvailableModels` fallback: the + first answer is the evidence, and the CLI fingerprint is the one that reports the Gemini group. +- Goes through the pinned provider-outbound transport used by the quota poller. +- The response uses closed reason codes and recognized quota-window labels. + The management API serializes probe runs and allows up to four requests per batch. + +Only `google-antigravity` is supported for now; other providers get HTTP 400 +`account probe is not supported for this provider`. The request/response shape is provider-neutral +so another provider can plug in a probe function later. + +CLI: `ocx account probe [] [--json]` (capability registered in +`src/cli/capabilities-accounts.ts`). + +GUI: Providers → Google Antigravity → Available accounts. Each account row gets a **Test** button; +the result renders under the row as a coloured badge plus `HTTP · `. +The section head gets **Test all**. + +## 2. Manual model discovery + +`POST /api/model-discovery/refresh` — body `{ "provider": "" }`. + +1. 404 for an unknown provider; `{ ok: false, applicable: false, reason: "static_catalog" }` when the + provider has `liveModels: false` (no live endpoint to ask). +2. Snapshot the provider's `recentArrivals` ids, `expireModelCache(provider)`, then run the normal + catalog convergence (`convergeCodexCatalog`), which re-fetches the provider and records new + arrivals through the existing new-model policy. +3. Respond with `{ ok, provider, discovery, liveModelCount, newArrivals, recentArrivals, catalogRefresh }`, + where `newArrivals` are the arrivals recorded by this call and `discovery` is the provider's + discovery status (`ok` / `failed` + reason / http status). + +CLI: `ocx models discover [--json]`. + +GUI: provider settings, directly under the "Discover models from provider" toggle: a +**Discover now** button and a "Recently added" list (newest first, with date and whether the model +was auto-disabled by the new-model policy). + +## Not changed + +- `POST /api/providers/test` and the active-account path. +- Token refresh, re-login, pause/resume semantics. diff --git a/devlog/_plan/261115_google_protocol_cpa_parity/000_plan.md b/devlog/_plan/261115_google_protocol_cpa_parity/000_plan.md new file mode 100644 index 00000000000..3fccc201c66 --- /dev/null +++ b/devlog/_plan/261115_google_protocol_cpa_parity/000_plan.md @@ -0,0 +1,85 @@ +# 000 — Google protocol parity with CLIProxyAPI: plan + +## Objective + +Bring opencodex's Google protocol support to parity with CLIProxyAPI (CPA, +`router-for-me/CLIProxyAPI`) where parity helps users, and deliver it as one branch +(`feat/google-protocol-cpa-parity`) with ordered commits and one pull request to `dev`. +"Google protocols" means the three native APIs Google ships (generateContent, the Interactions API, the +Live API; [002](002_google_docs_notes.md)) on both sides of the proxy: what clients may send to opencodex +(inbound) and what opencodex sends to AI Studio, Vertex and Antigravity (outbound). + +## Baseline and dependency + +- `dev` at d842c1352e has no Gemini-shaped inbound surface; outbound Google runs over raw HTTP + generateContent, with the Cloud Code Assist envelope for Antigravity. +- PR #8742 (head d21ed22ea8, owner-accepted, pending security review) adds generateContent inbound + and the Antigravity/agy connectors. Phases 010–030 build on it. Until it lands, the branch carries + a merge of its head as its first commit, and the PR says so; every later commit is separable. + Phases 040–060 do not touch #8742's files. + +## Scope boundaries + +In scope: the gap rows selected in [001](001_parity_matrix.md), their tests, `structure/` ownership and +docs, the English `docs-site` page and locale consistency. + +Out of scope: the Live API (L-01, neither side has it), a native Interactions upstream provider +(INT-16/17), background execution, the deferred rows in 001 (each lists its reason), anything in +`src/lab/`, releases, merging, force-pushing and `ci.yml lane=all` dispatches. + +## Decisions + +| id | decision | why | +| --- | --- | --- | +| D1 | Interactions inbound translates onto the internal Chat Completions path through a new codec, like #8742 does for generateContent | one routing path for every provider; reuses admission, logging, refusal vocabulary and the stream pump in `native-chat-bridge.ts` | +| D2 | `previous_interaction_id` is served from a bounded, process-local, owner-scoped store of Chat history | CPA silently drops it for translated targets (A-I14), which loses the conversation; refusing it breaks the documented default flow (`store` defaults to true) | +| D3 | Requests opencodex cannot honor are 400, never silently changed: `agent`, `background:true`, hosted tools on the new Interactions surface, non-text response modalities | follows #8742's codec rule and Google's semantics | +| D4 | Interaction usage uses Google's `total_*` names in both buffered and streamed bodies | the reference names them so; CPA's buffered `input_tokens` naming is a CPA quirk | +| D5 | Google output tokens include thinking tokens on the internal usage model | every other adapter's `outputTokens` includes reasoning; telemetry already clamps reasoning to output (`src/telemetry/aggregate.ts:185`) | +| D6 | Structured `ErrorInfo.reason` outranks prose needles when classifying Google errors; prose stays as the fallback | reasons are Google's stable contract; prose changes | +| D7 | Implementation order follows the owner's priority: Interactions inbound, then outbound translation, then streaming and tool fidelity | stated by the owner | + +## Phase map (dependency order) + +| phase | doc | rows | depends on | class | +| --- | --- | --- | --- | --- | +| 010 | [010_phase1_interactions_inbound.md](010_phase1_interactions_inbound.md) | INT-01..12, 18, 19 | #8742 merge | C4 (new public wire surface) | +| 020 | [020_phase2_interactions_state.md](020_phase2_interactions_state.md) | INT-13, 14, 15 | 010 | C4 (new persisted-in-memory caller state, owner binding) | +| 030 | [030_phase3_gemini_inbound_fidelity.md](030_phase3_gemini_inbound_fidelity.md) | IN-09, CW-01, IN-05, IN-12, IN-03, IN-13 | #8742 merge | C3 | +| 040 | [040_phase4_google_error_classification.md](040_phase4_google_error_classification.md) | AG-X1, AG-X2, AG-X3 | — | C3 (credential pause path) | +| 050 | [050_phase5_google_response_fidelity.md](050_phase5_google_response_fidelity.md) | OUT-V38, AG-R7, OUT-V42, OUT-V40, OUT-V43 | — | C3 (usage is shared) | +| 060 | [060_phase6_google_request_fidelity.md](060_phase6_google_request_fidelity.md) | AG-M1, OUT-V04, OUT-V27, OUT-V29 | — | C2 | +| 070 | [070_phase7_docs_review_delivery.md](070_phase7_docs_review_delivery.md) | docs-site, structure, full suite, review, PR | 010–060 | C4 gate | + +## Per-phase verification floor + +Failing test first, deterministic (no sleeps). Then, wrapped with `/usr/bin/lockf -k /tmp/ocx-test.lock`: +the focused test files, `bun run test:changed`, `bun run typecheck`, `bun run structure:check`, +`bun run privacy:scan`. New test files are registered in `scripts/test-layout/layout*.json` and a +`tests/fixtures/test-layout-expected*.json` shard. The file-size ratchet is respected by moving code into +new files, never by raising a cap. The full `bun run test` runs once, in 070. + +Ratchet facts (d842c1352e): files over 2,000 lines must be in `tests/fixtures/file-size-baseline.json` +(`scripts/file-size-ratchet.ts:5`). Near that line: `src/oauth/index.ts` 1,980, `src/server/responses/adapter-dispatch.ts` +1,970, `src/server/index/serve-options.ts` 1,957 on #8742, `src/adapters/google.ts` 1,850 — edits there stay +net zero or move code out. `src/server/index.ts` is capped at 893 (882 with #8742). + +Base drift: `origin/dev` moved to 4cbe4beb00 during cycle 1 (test-layout registry files only); the branch +merges `dev` before phase 010 and resolves the registry by keeping both sides' entries. + +## Outcomes + +DONE: every selected row shipped with a test that failed before, all gates green on the final head, an +independent review folded, the PR open and reported. NEEDS_HUMAN: a deferred row turns out to need a +public-contract decision. BLOCKED: #8742 conflicts that cannot be resolved without the owner. + +## Status (branch `feat/google-protocol-cpa-parity`) + +- 000 roadmap and matrix: b662d4d788. +- 010 Interactions inbound: 9c48809348. 020 Interactions state: baa5dfbadb. +- 030 Gemini inbound fidelity on #8742: 3374a52e28 (plus 7464b83dd7, the Spanish mirror of #8742's connector docs, + and b2738d88fe, #8742's GUI headless-parity gap). +- 040 Google error classification and TOS quarantine: c07d7cc259. +- 050 Google response fidelity: 3dccfa700f. 060 Google request fidelity: 430882ffa3 (6a, AG-M1, deferred). +- 070 user docs (`reference/proxy-formats.md` Gemini section, `reference/adapters.md`, `reference/cli/providers-accounts.md`, + English and Spanish), review and delivery: in progress. The unit moves to `devlog/_fin/` after the PR merges. diff --git a/devlog/_plan/261115_google_protocol_cpa_parity/001_parity_matrix.md b/devlog/_plan/261115_google_protocol_cpa_parity/001_parity_matrix.md new file mode 100644 index 00000000000..2ca75056847 --- /dev/null +++ b/devlog/_plan/261115_google_protocol_cpa_parity/001_parity_matrix.md @@ -0,0 +1,141 @@ +# 001 — Google protocol parity matrix: CPA vs opencodex + +Heads compared: opencodex `dev` **d842c1352e**, PR #8742 head **d21ed22ea8** (Gemini generateContent +inbound and the Antigravity/agy connectors, accepted by the owner), CLIProxyAPI (CPA) **e96d4c4** +(2026-11-15, shallow clone in the gitignored `devlog/_chase/_cca/`). Method: source reading plus +Google's primary docs ([002](002_google_docs_notes.md)). Nothing here was exercised at runtime. + +Row evidence (CPA `file:line`, opencodex `file:line`) lives in the lane appendices, keyed by the +same ids: [003](003_lane_a_inbound_interactions.md) (A-, inbound and Interactions), +[004](004_lane_b_antigravity_outbound.md) (B-, Antigravity outbound), +[005](005_lane_c_aistudio_vertex_outbound.md) (C-, AI Studio and Vertex outbound). This table is the +decision layer: status, priority, and which phase takes the row. + +A **have ()** status names the branch commit that closed a row; the rest of the row keeps the research-time note. + +Status vocabulary: **have** (parity), **gap** (CPA does it, opencodex should), **diff** (intentionally +different, with the reason), **n-a** (neither side, or outside this unit), **defer** (a real gap left for a +later unit, with the reason). + +## Coverage summary + +| Surface | CPA | opencodex dev | opencodex dev + #8742 | After this unit | +| --- | --- | --- | --- | --- | +| `GET /v1beta/models[/{m}]` | yes | no | yes | yes, plus token limits | +| `:generateContent` / `:streamGenerateContent` | yes (SSE even without `alt`) | no | yes (SSE or JSON array) | yes, thought signatures carried | +| `:countTokens` | yes, every provider | no | 501 | local estimate | +| `:embedContent` | empty 200 (inferred) | no | 501 | 501 | +| `POST /v1beta/interactions` | yes, translated to every provider | no | no | yes, translated through Chat | +| `previous_interaction_id` | native passthrough only, silently dropped elsewhere | no | no | local bounded store | +| `GET/DELETE /v1beta/interactions/{id}` | no | no | no | yes (stored interactions) | +| Live API (`BidiGenerateContent`) | no | no | no | no (L-01) | +| Outbound Google: generateContent + Antigravity `v1internal` envelope | yes | yes | yes | yes, with the fidelity gaps below fixed | +| Outbound native Interactions provider | yes (`gemini-interactions`) | no | no | no (INT-16, deferred) | + +## Inbound: generateContent family (baseline #8742) + +| id | behaviour | lane ids | status | priority | phase | +| --- | --- | --- | --- | --- | --- | +| IN-01 | Routes: models list/get, generateContent, streamGenerateContent on `/v1beta`, generation also on `/v1/models/{m}:{method}` | A-R01 R02 R03 R12 R14 | have (#8742) | — | — | +| IN-02 | Stream without `alt=sse` is one JSON array (Google's REST default); CPA sends SSE regardless | A-R04 | diff: opencodex follows Google | — | — | +| IN-03 | `$alt` alias for `alt` | A-R05 | have (3374a52e28) | P3 | 030 | +| IN-04 | `: keep-alive` SSE comments before the first token | A-R06 | defer: bridge-wide change shared with Ollama; opencodex already disables the idle timeout for generation | P3 | — | +| IN-05 | `:countTokens` answers `{totalTokens}` | A-R07, C-V-10 | have (3374a52e28) | P2 | 030 | +| IN-06 | Embed methods | A-R08 | diff: 501 is honest, CPA's empty 200 is not | — | — | +| IN-07 | Error body `{error:{code,message,status}}` with fixed text; CPA emits OpenAI-shaped bodies and forwards upstream text | A-R17 R18 R19 | diff: opencodex follows Google and never forwards upstream text | — | — | +| IN-08 | Credential forms: `x-goog-api-key`, `?key=` moved onto the proxy header; CPA also takes `?auth_token=`, `X-Api-Key` | A-R15 R16 | diff: narrower on purpose | — | — | +| IN-09 | `thoughtSignature` round-trip on `functionCall` and text parts | A-R23, C-V-37 | partial: function-call parts round-trip (3374a52e28); text-part signatures are a gap | P1 | 030 | +| IN-10 | Hosted tools (`googleSearch`, `urlContext`, `codeExecution`) are dropped silently | A-R24 | defer: changing to 400 can break the owner-accepted connectors; needs a mapping onto opencodex's search relay first | P2 | — | +| IN-11 | `fileData` and non-image `inlineData` are 400 | A-R22 | defer: needs Chat IR document/audio parts end to end (C-V-29 lands the outbound half in 060) | P2 | — | +| IN-12 | Model resources carry `inputTokenLimit`/`outputTokenLimit` | A-R11 | have (3374a52e28) | P2 | 030 | +| IN-13 | `STATUS_NAMES` covers 402/408/409/422/500/502 | A-R17 | have (3374a52e28) | P3 | 030 | +| IN-14 | `usageMetadata.candidatesTokenCount` = Chat completion − reasoning | A-R29 | have (exact since OUT-V38, 3dccfa700f) | — | 050 | +| IN-15 | Tool config, structured output, thinking config, finish reasons, streamed tool calls, body limits, ingress isolation | A-R25 R27 R28 R29 R30 R31 R33 | have (#8742) | — | — | +| IN-16 | CORS: data-plane origin policy; CPA sends `*` | A-R32 | diff | — | — | + +## Inbound: Interactions API + +| id | behaviour | lane ids / doc | status | priority | phase | +| --- | --- | --- | --- | --- | --- | +| INT-01 | `POST /v1beta/interactions` create | A-I01; 002 Methods | have (9c48809348) | P1 | 010 | +| INT-02 | Exactly one of `model`/`agent`; `agent` needs a native upstream | A-I02 | have (9c48809348); opencodex answers 400 for `agent` (no native Interactions upstream) | P1 | 010 | +| INT-03 | `stream` must be boolean; true = SSE, false = JSON | A-I03 | have (9c48809348) | P1 | 010 | +| INT-04 | `input`: string, content, content list, step list, turn object | A-I04; 002 Interaction | have (9c48809348) | P1 | 010 | +| INT-05 | Input steps: `user_input`, `model_output`, `thought` (signature), `function_call`, `function_result` | A-I05 | have (9c48809348) | P1 | 010 | +| INT-06 | `system_instruction` string (or `{text}`/`{parts}`) | A-I06 | have (9c48809348) | P1 | 010 | +| INT-07 | `generation_config`: temperature, top_p, seed, stop_sequences, max_output_tokens, thinking_level, thinking_summaries, tool_choice; `response_format` | A-I07 A-R27; 002 | have (9c48809348) | P1 | 010 | +| INT-08 | `tools`: `function` entries; hosted tools | A-I08 | have (9c48809348); function tools mapped, hosted tools 400 (new surface, so no silent drop) | P1 | 010 | +| INT-09 | Non-stream body: `id`, `status`, `created`, `updated`, `model`, `steps`, `usage` with Google's `total_*` names | A-I09 A-I11; 002 usage | have (9c48809348); diff from CPA's `input_tokens` naming | P1 | 010 | +| INT-10 | SSE vocabulary: `interaction.created`, `step.start`, `step.delta`, `step.stop`, `interaction.completed`, `error` (`interaction.status_update` is not emitted: nothing runs in the background) | A-I10; 002 events | have (9c48809348) | P1 | 010 | +| INT-11 | Terminal event only after usage and settlement; exactly once | A-I12 | have (9c48809348); (bridge already guarantees it) | P1 | 010 | +| INT-12 | `status`: `requires_action` when the turn ends in function calls, `incomplete` on length, `completed` otherwise | A-I13; 002 status | have (9c48809348); diff: CPA reports `completed` for tool turns | P1 | 010 | +| INT-13 | `previous_interaction_id` resolves earlier history | A-I14 A-I15; 002 State | have (baa5dfbadb); diff: CPA has no local store and silently drops it for translated targets; opencodex keeps a bounded, owner-scoped local store | P1 | 020 | +| INT-14 | `store` (default true), `GET` and `DELETE /v1beta/interactions/{id}` | A-I16; 002 Methods | have (baa5dfbadb); (CPA has no GET/DELETE) | P2 | 020 | +| INT-15 | `background`, `POST …/{id}/cancel` | A-I16 | diff: 400 / 501, no background execution without a native upstream | — | 020 | +| INT-16 | Native Interactions upstream (`/v1beta/interactions` with `Api-Revision`) as a provider | A-I17, C-V-14 | defer: new provider adapter and catalog surface; separate unit | P3 | — | +| INT-17 | Other inbound protocols → Interactions upstream | A-I20 | defer: depends on INT-16 | P3 | — | +| INT-18 | Error envelope in Google shape, fixed text, `event: error` after commit | A-I18 | have (9c48809348) | P1 | 010 | +| INT-19 | Stable `/v1/interactions` alias | 002 Methods (v1 capture) | have (9c48809348); (opencodex-only addition; `/v1/interactions` is unused in opencodex; the v1 reference has the same methods and fields) | P3 | 010 | +| L-01 | Live API WebSocket | 002 Live | n-a: neither CPA nor opencodex; audio realtime is outside this unit | — | — | + +## Chat wire carrier used by the Google paths + +| id | behaviour | lane ids | status | priority | phase | +| --- | --- | --- | --- | --- | --- | +| CW-01 | Chat `tool_calls[].extra_content.google.thought_signature` read on input and emitted on output (CPA does both) | C-V-34 C-V-35, A-R23 | have (3374a52e28); the Chat wire now carries it both ways, as Responses already did | P1 | 030 | + +## Outbound: Antigravity (Cloud Code Assist `v1internal`) + +| id | behaviour | lane ids | status | priority | phase | +| --- | --- | --- | --- | --- | --- | +| AG-ENV | Envelope `model`, `userAgent:"antigravity"`, `project`, `request.sessionId`, `toolConfig` placement, `safetySettings` removed, Claude `VALIDATED` | B-E1 E2 E5 E7 E8 E10 | have | — | — | +| AG-SESSION | Session id derivation (opencodex adds account scope and a compaction-stable anchor) | B-E6 S2 | diff | — | — | +| AG-HTTP | Single daily endpoint, no cross-tier fallback; `?alt=sse`; `response` unwrapping | B-H1 H2 R1 | have (R1: opencodex fails closed on an unwrapped frame; diff) | — | — | +| AG-UA | User-Agent family (CPA hub UA auto-versioned; opencodex IDE UA, CLI UA for Gemini 4 codenames) | B-H4 H5 H7 | diff: each side has its own served-model evidence | — | — | +| AG-REPLAY | Thought-signature replay cache, clear-on-invalid, bypass sentinel, foreign-id filtering | B-S1 S4 S5 S6 | have | — | — | +| AG-X1 | 429 classification by `google.rpc.ErrorInfo.reason` (`QUOTA_EXHAUSTED`, `RATE_LIMIT_EXCEEDED`, `INSUFFICIENT_G1_CREDITS_BALANCE`) | B-X1 | have (c07d7cc259) | P1 | 040 | +| AG-X2 | Retry delay from `RetryInfo.retryDelay` / `quotaResetDelay` in full duration syntax (`1h2m3s`, `0.5s`), used by the transient retry loop, not only the quota branch | B-X2, C-V-46 | have (c07d7cc259) | P1 | 040 | +| AG-X3 | `PERMISSION_DENIED` + `ErrorInfo.reason=TOS_VIOLATION` is a credential-scoped terminal refusal, HTTP and in-stream | B-X3 R2 | partial: HTTP 403 has typed account handling (c07d7cc259); a TOS error in HTTP-200 SSE takes the generic stream-error path | P1 | 040 | +| AG-R4 | A stream with only a signature and usage (no text, no call) is a failure, not an empty success | B-R4 | diff: opencodex's empty-completion guard (`src/server/responses/empty-completion-guard.ts`) owns zero-output turns (one retry when enabled, a notice otherwise); a signature-only stream is that shape | — | — | +| AG-R7 | Input tokens include `toolUsePromptTokenCount` | B-R7 | have (3dccfa700f) | P2 | 050 | +| AG-M1 | Tool-result images nested in `functionResponse.parts` | B-M1, C-V-28 | defer: CPA nests on CCA, but ADR-7279 extends nesting only with live upstream evidence per route, and the pinned CCA Claude "responses before images" layout was a live fix; needs an Antigravity live run | P2 | 060 | +| AG-TOSPOOL | Opt-in pool-wide pause after a TOS suspension (CPA `antigravity_executor_credits.go:884-905`, off by default since e96d4c4) | B-X3 | defer: opencodex quarantines the one account (040); a pool-wide stop is a separate operator policy | P3 | — | +| AG-ACP | Official `agy acp` transport as a separate provider (#8480): the CLI owns the credential; one account, no rotation, local only, Gemini only, interactive only | issue #8480 + owner decision; ACP v1 spec; Google staff answers (080) | gap: CPA has no ACP client; opencodex adds it as its own PR | P1 | 080 | +| AG-S7 | Claude-on-CCA signature format validation | B-S7 | defer: needs a corpus of real Claude/Gemini carrier signatures to avoid dropping valid ones | P2 | — | +| AG-TL3 | Required `reason` placeholder for argument-less tools under Claude `VALIDATED` | B-TL3 | defer: needs a live check; opencodex already repairs schema 400s once | P2 | — | +| AG-E3 | `requestType` `image_gen`/`web_search` and their id shapes | B-E3 E4 | defer: upstream effect unverified | P3 | — | +| AG-E9 | CPA deletes `maxOutputTokens` for non-Claude models | B-E9 | defer: no stated reason in CPA; changing it could remove a needed cap | P3 | — | +| AG-E11 | `enabledCreditTypes:["GOOGLE_ONE_AI"]` credits fallback | B-E11 | defer: spends the user's paid credits; needs an explicit opt-in design | P3 | — | +| AG-MISC | countTokens on CCA, onboarding `X-Goog-Api-Client`, split-JSON SSE, non-stream via stream, replay identity with call id, Claude budget thinking, `webSearchModelIds` | B-H3 H5 R3 R6 S3 T2 D3 | defer | P3 | — | +| AG-OCX | opencodex-only: thinking-config 400 repair, schema 400 repair, model-denial rotation, transient retries | B-T3 TL4 X4 X5 | diff (opencodex ahead) | — | — | +| AG-DISC | `loadCodeAssist`, `onboardUser`, `fetchAvailableModels`, token refresh | B-D1 D2 D3 D4 | have (D1 host differs: diff) | — | — | + +## Outbound: AI Studio (API key) and Vertex + +| id | behaviour | lane ids | status | priority | phase | +| --- | --- | --- | --- | --- | --- | +| OUT-EP | Endpoints, auth headers, Vertex project/express URLs, ADC chain | C-V-01 V-03 V-05 V-07 V-08 | have (opencodex ADC chain is broader) | — | — | +| OUT-V04 | Vertex `us`/`eu` multi-region hosts `aiplatform.{us,eu}.rep.googleapis.com` | C-V-04 | have (430882ffa3) | P2 | 060 | +| OUT-V38 | Output tokens = `candidatesTokenCount + thoughtsTokenCount` (every other adapter's output includes reasoning; telemetry clamps reasoning to output) | C-V-38 V-39 | have (3dccfa700f) | P1 | 050 | +| OUT-V42 | `MALFORMED_FUNCTION_CALL` fails closed on AI Studio too; `UNEXPECTED_TOOL_CALL` and `MALFORMED_RESPONSE` with no output fail closed everywhere | C-V-42 | have (3dccfa700f); fail-closed errors carry 502 `upstream_error` | P1 | 050 | +| OUT-V40 | `IMAGE_SAFETY` → `content_filter` | C-V-40 V-41 | have (3dccfa700f); also `IMAGE_PROHIBITED_CONTENT` and `MALFORMED_RESPONSE` with output | P2 | 050 | +| OUT-V43 | `promptFeedback.blockReason` becomes a typed, non-retryable block error (stream and buffered) | C-V-43 | have (3dccfa700f); 400 `invalid_prompt`, a terminal refusal | P2 | 050 | +| OUT-V27 | Tool error results (`isError`) → `functionResponse.response.error` | C-V-27 | have (430882ffa3) | P3 | 060 | +| INT-20 | Interactions `function_result.is_error` reaches Google as `functionResponse.response.error` | review r1 (R2); Google Interactions reference `is_error` | defer: the Chat and Responses wires that every inbound lane crosses have no tool-error flag, so carrying it is a new private Chat-wire contract in both lanes; today the error reaches every provider as `{"error": …}` result text | P3 | — | +| OUT-V29 | Audio input parts sent as `inline_data` | C-V-29 | have (430882ffa3); Claude on CCA keeps the marker | P2 | 060 | +| OUT-V31 | `thinkingBudget` for the 2.5 family | C-V-31 | defer: effort ladders are catalog-owned (`structure/catalog.md`); the existing 400 repair keeps 2.5 requests working | P2 | — | +| OUT-V23 | Native `googleSearch` grounding on user keys | C-V-23 | defer: overlaps the hosted search relay (`structure/data-planes/search.md`) | P2 | — | +| OUT-V22 | `parametersJsonSchema` instead of the sanitized `parameters` subset | C-V-22 | defer: design decision, current path has loss reporting and repair | P2 | — | +| OUT-V26 | Strip call ids on Vertex | C-V-26 | defer: needs a live Vertex probe; opencodex ids are normalized | P2 | — | +| OUT-V21 | Default `safetySettings` (CPA sends `OFF`) | C-V-21 | diff: policy, Google defaults apply | — | — | +| OUT-V32 | `includeThoughts` from client request vs provider setting | C-V-32 | diff | — | — | +| OUT-P3 | countTokens passthrough, Imagen, Vertex MaaS, `topK`, `imageConfig`, `input_file` URIs, text-part signatures, partial args | C-V-10 V-12 V-13 V-17 V-20 V-30 V-36 V-45 | defer | P3 | — | +| OUT-HAVE | systemInstruction, turn guards, max-output clamp, structured output, tool_choice, thought parts, signature surfacing, stream truncation, retries, 400 repair, model discovery | C-V-15 V-16 V-18 V-19 V-24 V-33 V-35 V-44 V-46 V-47 V-48 | have | — | — | + +## Totals + +Computed from the tables above (75 rows): 34 rows taken by phases 010-060 and shipped: 33 gaps (P1: 21, P2: 8, +P3: 4) plus INT-15, an intentional difference implemented in 020; 19 deferred, each with its reason (AG-M1 moved +from 060 to deferred during the build, and INT-20 was added from review round 1); +11 intentionally different; 9 at parity; 1 outside both projects. Grouped rows (AG-MISC, OUT-P3, +OUT-HAVE, AG-OCX) stand for several lane rows each; the appendices keep the per-row evidence. AG-ACP (owner decision on #8480) is taken by 080 and ships as its own PR. diff --git a/devlog/_plan/261115_google_protocol_cpa_parity/002_google_docs_notes.md b/devlog/_plan/261115_google_protocol_cpa_parity/002_google_docs_notes.md new file mode 100644 index 00000000000..75940a33e59 --- /dev/null +++ b/devlog/_plan/261115_google_protocol_cpa_parity/002_google_docs_notes.md @@ -0,0 +1,71 @@ +# 002 — Google primary-doc facts used by this unit + +Captured 2026-11-15 through Aside (`browse.readText`, fetch source, `complete=true`) from the +`.md.txt` renditions of ai.google.dev. Line references point into those captures; the canonical +pages are the URLs below. Only facts this unit relies on are recorded. + +## Interactions API + +Sources: , , +, . + +- Status: generally available since June 2026 and "the recommended interface for all new projects"; + `generateContent` is called legacy but "remains fully supported" (guide, intro). +- Methods (reference, "Methods"): `POST /v1beta/interactions` (create), `POST /v1beta/interactions/{id}/cancel`, + `GET /v1beta/interactions/{id}`, `DELETE /v1beta/interactions/{id}`. A stable `v1` version also exists. +- Auth: `x-goog-api-key` header in every REST sample (guide, REST tabs). +- Streaming: `"stream": true` in the body; the REST sample also sets `?alt=sse` + (function-calling guide, REST streaming sample). Events are SSE. +- Interaction resource (reference, "Interaction"): output-only `id`, `status`, `created`, `updated`, `steps`; + `model` or `agent`; input-only `input` (Content, content list, or string), `system_instruction` (string), + `tools`, `generation_config`, `response_format`, `stream`, `store`, `background`, + `previous_interaction_id`, `agent_config`; output `usage`, `errors`, `continuation_token`. +- `status` values: `in_progress`, `requires_action`, `completed`, `failed`, `cancelled`, `incomplete` + (completed but truncated, e.g. max tokens), `requires_continuation`. +- `generation_config`: `seed`, `stop_sequences`, `max_output_tokens`, + `thinking_level` (`minimal|low|medium|high|xhigh`), `thinking_summaries` (`auto|none`), + `tool_choice` (string `auto|any|none|validated` or `{allowed_tools:{mode,tools[]}}`), plus media configs. + `temperature` and `top_p` appear in the guide's samples, not in the reference's GenerationConfig list. +- The stable `v1` reference (`?api-version=v1`, captured the same way, 156,304 chars) lists the same four + methods under `/v1/interactions` and the same create fields this unit reads. +- `usage` fields: `total_input_tokens`, `input_tokens_by_modality[]`, `total_cached_tokens`, + `total_output_tokens`, `total_tool_use_tokens`, `total_thought_tokens`, `total_tokens`, + `grounding_tool_count[]`. (CPA uses `input_tokens`/`output_tokens` in non-stream bodies; the reference + does not, so this unit follows the reference.) +- Step types (reference, "Step"): `user_input`, `model_output`, `thought`, `function_call`, + `function_result`, and hosted-tool pairs (`google_search_*`, `url_context_*`, `code_execution_*`, + `file_search_*`, `google_maps_*`, `mcp_server_tool_*`, `processing_*`). `interactions.create` returns only + model-generated steps; `interactions.get` also returns `user_input` steps (guide, "How it works"). +- SSE event types (reference, "InteractionSseEvent"): `interaction.created`, `interaction.status_update`, + `step.start` (`index`, `step`), `step.delta` (`index`, `delta`), `step.stop` (`index`), + `interaction.completed` (`interaction` with usage), `error` (`error:{code,message}`). Each event may carry + `event_id` for stream resumption. Delta types include `text`, `thought_summary`, `thought_signature`, + `arguments_delta`, `function_result`, `image`, `audio`, `text_annotation_delta`, plus hosted-tool deltas. +- State: `previous_interaction_id` preserves only conversation history; `tools`, `system_instruction` and + `generation_config` are interaction-scoped and must be re-sent (guide, "Server-side state management"). + `store=false` "prevents using `previous_interaction_id` for subsequent turns" and is incompatible with + `background` (guide, "Data storage and retention"). +- Thought signatures: in stateful mode the server keeps them; in stateless mode they live inside `thought` + steps, not on user/model/function parts (thought-signatures page). +- Not yet in Interactions: Batch API, Python automatic function calling, explicit caching (guide, "Limitations"). + +## generateContent (legacy, still supported) + +Source: . + +- `POST /v1beta/models/{model}:generateContent` and `:streamGenerateContent` (reference, "Methods"); + streamed responses are a JSON array by default, or SSE with `alt=sse` (as implemented by #8742 and by + opencodex's outbound adapter, which always requests `?alt=sse`). +- `Part.thoughtSignature` is a string field on content parts (reference, Part). + +## Live API + +Sources: , . + +- Transport: stateful WebSocket, `WSS /ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent`; + ephemeral tokens via `POST /v1beta/auth_tokens` (reference, "Methods"). +- Audio in: raw 16-bit PCM 16 kHz; audio out: 24 kHz PCM; images JPEG at most 1 FPS (guide, "Technical specifications"). +- Messages: `BidiGenerateContentSetup`, `ClientContent`, `RealtimeInput`, `ToolResponse` from the client; + `SetupComplete`, `ServerContent`, `ToolCall`, `ToolCallCancellation`, `GoAway`, `SessionResumptionUpdate` + from the server. +- CPA has no Live support (`rg -i bidigenerate` in the CPA tree finds nothing); see matrix row L-01. diff --git a/devlog/_plan/261115_google_protocol_cpa_parity/003_lane_a_inbound_interactions.md b/devlog/_plan/261115_google_protocol_cpa_parity/003_lane_a_inbound_interactions.md new file mode 100644 index 00000000000..37340a79ed1 --- /dev/null +++ b/devlog/_plan/261115_google_protocol_cpa_parity/003_lane_a_inbound_interactions.md @@ -0,0 +1,98 @@ + +# A — CPA inbound Google surface + Interactions API vs opencodex + +Scope: CPA inbound `/v1beta` (generateContent family, models, Interactions) compared with opencodex `dev` (d842c1352e) and PR #8742 (`pr/8742` = d21ed22ea8). +CPA paths are relative to `devlog/_chase/_cca` (HEAD e96d4c4, 2026-11-15). opencodex paths are relative to the repo root; `#8742:` means read with `git show pr/8742:`. +Method: read-only source inspection with rg/sed. Nothing was executed, so runtime behaviour is inferred from source. Rows marked *(inferred)* are my reading of the code and have not been exercised. + +Baseline: **opencodex dev has no inbound Gemini or Interactions surface at all.** `rg -i 'v1beta|interactions' src` only hits upstream discovery/adapter code (src/adapters/google.ts:1309-1312, src/oauth/index.ts:1240-1244). `rg -i '/interactions|previous_interaction|interaction\.created' src gui/src docs-site/src` finds nothing. All "have" rows below exist only because of #8742. + +## Matrix + +| id | area | CPA behaviour (file:line) | opencodex dev / #8742 behaviour (file:line) | status | notes / priority | +|---|---|---|---|---|---| +| R01 | Route table | The `/v1beta` group has `GET /models`, `POST /interactions`, `POST /models/*action`, and `GET /models/*action`, with `AuthMiddleware` on all four (internal/api/server_routes.go:149-155). There is no `/v1/models/{m}:method` route. | dev: none. #8742 adds `GET /v1beta/models`, `GET /v1beta/models/{m}`, and `POST /v1beta/models/{m}:{method}`. It also accepts `POST /v1/models/{m}:{method}`, but only when the method is known (#8742:src/server/gemini-native-paths.ts:25-40). It is wired in serve-options (#8742:src/server/index/serve-options.ts:667). | have (generation) / gap (interactions) | The `/v1` alias is an opencodex extra. | +| R02 | `:generateContent` buffered | Runs `ExecuteWithAuthManager` and writes the raw upstream-translated body as `application/json` (sdk/api/handlers/gemini/gemini_handlers.go:349-364). A non-stream keep-alive writes bare `"\n"` bytes on a ticker before the body (sdk/api/handlers/handlers.go:754-787). | #8742 translates to an internal Chat request, runs `handleChatCompletions`, and maps the result back with `chatToGeminiResponse` (#8742:src/server/gemini-inbound.ts:122-128,147-165). It has no keep-alive bytes; Bun's idle timeout is disabled instead (#8742:src/server/index/gemini-routes.ts:47; src/server/responses/fetch-helpers.ts:108-116). | have | P3. Leading newlines are legal JSON whitespace. opencodex has no protection against proxies that close idle connections (for example, a CDN's 100 s idle limit). | +| R03 | `:streamGenerateContent?alt=sse` | Frames are `data: \n\n` with headers `Content-Type: text/event-stream`, `Cache-Control: no-cache`, `Connection: keep-alive`, and `Access-Control-Allow-Origin: *` (gemini_handlers.go:201-206,299-302,374-378). | #8742 writes `data: \r\n\r\n` as `text/event-stream` (#8742:src/server/gemini-inbound.ts:176-179). | have | — | +| R04 | Stream without `alt` | `GetAlt` returns `""` for both `alt=sse` and a missing `alt`, so **a missing alt still produces SSE** (handlers.go:600-611; gemini_handlers.go:213-215). Any other `alt` value writes raw chunks back to back, with no `[`/`,`/`]` framing (gemini_handlers.go:303-305,379-381). | #8742 streams one JSON array, `[\n{..},\n{..}\n]`, as `application/json` (#8742:src/server/gemini-inbound.ts:181-189). | intentionally-different | opencodex matches the Google REST default here, which uses a JSON array when there is no `alt=sse`. CPA's `alt=json` stream output is not valid JSON *(inferred)*. Keep opencodex as is. | +| R05 | `$alt` alias | Accepts `$alt` when `alt` is absent (handlers.go:603-606). | #8742 reads only `alt` (#8742:src/server/index/gemini-routes.ts:73). | gap | P3. Discovery-style clients use `$alt`. The fix is one line. | +| R06 | Keep-alive before the first token | Writes SSE comment `: keep-alive\n\n` frames before the first chunk (gemini_handlers.go:219-229,311-312). Interactions does the same (interactions_handlers.go:154-185). | #8742: none. `streamNativeFromChat` emits only translated frames (#8742:src/server/native-chat-bridge.ts:152-210). | gap | P3. This matters for slow-thinking models behind proxies with idle limits. | +| R07 | `:countTokens` | Routed to the executor's `CountTokens` for every provider family (gemini_handlers.go:171-172,325-338). Implementations include internal/runtime/executor/gemini_executor.go:996, claude_executor_tokens.go:22, codex_executor_tokens.go:19, and openai_compat_executor.go:878. | #8742 answers 501 `UNIMPLEMENTED` after admission (#8742:src/server/index/gemini-routes.ts:56). | gap | **P2.** The google-genai SDK `models.count_tokens` and Gemini-CLI context management call this method *(inferred for CLI)*. opencodex could answer from its own estimator or a provider count endpoint. | +| R08 | `:embedContent` / `:batchEmbedContents` | The method switch has no case and no `default` (gemini_handlers.go:166-173). The handler returns without writing anything, so gin answers an empty 200 *(inferred)*. | #8742 answers 501 `UNIMPLEMENTED` (#8742:src/server/gemini-native-paths.ts:7,14; gemini-routes.ts:56). | intentionally-different | opencodex is better here. P3 if embeddings are ever routed. | +| R09 | Malformed action | An action without exactly one `:` returns 404 with body `{"error":{"message":" not found.","type":"invalid_request_error"}}` (gemini_handlers.go:143-152). | #8742: an unknown method or no colon means the path is not native and falls through to other dispatch (#8742:src/server/gemini-native-paths.ts:33-39). | n-a | P3 | +| R10 | Wrong HTTP verb | `GET /v1beta/models/x:generateContent` reaches the GET handler and returns 404 with `{"error":{"message":"Not Found","type":"not_found"}}` (gemini_handlers.go:83-126). | #8742 returns 405 in Gemini shape, with an `Allow:` header (#8742:src/server/index/gemini-routes.ts:41-45). | intentionally-different | — | +| R11 | `GET /v1beta/models` shape | Returns registry models with `name` forced to `models/`, `displayName`/`description` defaulting to the name, and `supportedGenerationMethods` defaulting to `["generateContent"]` (gemini_handlers.go:51-79). Registry entries carry `inputTokenLimit`/`outputTokenLimit` (internal/registry/model_registry_cache_test.go:105-120). Home mode has its own list (internal/api/server_routes.go:1026-1035). | #8742 returns `{models:[{name:"models//", displayName, supportedGenerationMethods:["generateContent","streamGenerateContent"]}]}`, filtered by the key's model scope (#8742:src/server/gemini-inbound.ts:59-73). | partial | **P2.** opencodex omits `inputTokenLimit`, `outputTokenLimit`, `description`, and `thinking`. Clients size context and compression from these limits *(inferred)*. | +| R12 | `GET /v1beta/models/{m}` | Matches `name == action` or `models/`+action. A miss is 404 in OpenAI-ish shape (gemini_handlers.go:96-125). | #8742 looks up through `findOllamaRoute` plus scope. A miss is 404 `NOT_FOUND` in Google shape (#8742:src/server/gemini-inbound.ts:75-80). | have | — | +| R13 | List pagination (`pageSize`/`pageToken`/`nextPageToken`) | Not implemented: rg over sdk/api and internal/api finds no `pageToken`. | Not implemented (#8742:src/server/gemini-inbound.ts:71-73). | n-a | P3. Both return the full list. | +| R14 | Model name normalization | Interactions strips a `models/` prefix (interactions_handlers.go:51-72). generateContent uses `action[0]` raw (gemini_handlers.go:143,168). | #8742 URL-decodes, strips `models/`, and allows `/` inside the model for `provider/model` selectors (#8742:src/server/gemini-native-paths.ts:17-22,31-35). | have | It is unclear whether a bare model id resolves; see Open questions. | +| R15 | Inbound credential forms | Accepts `Authorization: Bearer ` (or a raw value), `X-Goog-Api-Key`, `X-Api-Key`, `?key=`, and `?auth_token=` (internal/access/config_access/provider.go:61-101). The CORS request allowlist includes `X-Goog-Api-Key` (internal/api/server_middleware.go:51-58). | #8742 moves `x-goog-api-key` or `?key=` onto `x-opencodex-api-key` and deletes it from the headers and URL (#8742:src/server/index/gemini-routes.ts:24-34). Generation admission accepts the dedicated header or Bearer, but not `x-api-key` (src/server/auth-cors.ts:774-787). Discovery also accepts `x-api-key` (src/server/auth-cors.ts:746-758). | have | `?auth_token=` is unsupported (P3, intentional). | +| R16 | Credential precedence | Tries each present credential until one matches the key set (provider.go:76-101). | #8742: the header beats `?key=`, and an already-present `x-opencodex-api-key` beats both (#8742:src/server/index/gemini-routes.ts:26-28). | intentionally-different | — | +| R17 | Error envelope (generateContent) | Locally generated errors use OpenAI shape `{"error":{"message","type","code"}}`, mapping 401→`authentication_error/invalid_api_key`, 403→`permission_error/insufficient_quota`, 429→`rate_limit_error/rate_limit_exceeded`, and 404→`model_not_found` (sdk/api/handlers/handlers.go:69-140). **Upstream JSON error text passes through compacted and verbatim** (handlers.go:115-121), so a Claude or OpenAI upstream error reaches a Gemini client in that vendor's shape *(inferred)*. | #8742 always returns Google shape `{"error":{"code","message","status"}}`, with a fixed message per HTTP status and upstream text never forwarded (#8742:src/server/gemini-inbound.ts:33-51; native-chat-bridge.ts:98-127). | intentionally-different | opencodex is closer to what google-genai parses. P3 nit: `STATUS_NAMES` lacks 402/408/409/422/500/502, so these become `"INTERNAL"` (#8742:src/server/gemini-inbound.ts:33-36,39). Google would use `FAILED_PRECONDITION`, `DEADLINE_EXCEEDED`, `ABORTED`, and `INVALID_ARGUMENT`. | +| R18 | Retry-After | Copies `Retry-After` from the error, keeping trusted local deadlines (handlers_errors.go:126-140). | #8742 reformats it through `nativeRetryAfter` (#8742:src/server/gemini-inbound.ts:46-50,140). | have | — | +| R19 | Error after the stream is committed | SSE: `event: error\ndata: \n\n`. Non-SSE alt: the raw body. Before commit it is a plain JSON error with the real status (gemini_handlers.go:246-267,383-401). | #8742 emits a failure record `{"error":{"code":502,"message",...}}` as a `data:` frame or as an array element. The code is always 502 (#8742:src/server/gemini-inbound.ts:201; native-chat-bridge.ts:162-181). Pre-commit errors keep their status (gemini-inbound.ts:135-141). | have (different) | P3. opencodex emits no `event:` line, which matches Google, whose SSE errors are data-only. | +| R20 | Bootstrap failover (zero-output rotation) | Covered by tests (sdk/api/handlers/gemini/issue7513_bootstrap_failover_test.go:22,110). Exhausted retries give HTTP 502. | #8742 inherits whatever the Chat path does (#8742:src/server/gemini-inbound.ts:128). | n-a | Out of scope. Noted for the routing lane. | +| R21 | Gemini inbound to non-Gemini providers | Per-target translators: internal/translator/{antigravity,claude,codex,gemini,openai}/gemini. | #8742 goes Gemini → Chat Completions → any configured route (#8742:src/protocols/codecs/gemini.ts:267-280; structure/data-planes/gemini-inbound.md:3-6). | have | The mechanism differs and the effect is the same. | +| R22 | Roles and parts | — | #8742 allows roles `user`, `model`, `function`, and `tool`; anything else is 400 (#8742:src/protocols/codecs/gemini.ts:194-195). `fileData`, `executableCode`, and `codeExecutionResult` are 400 (gemini.ts:197-199). Non-image `inlineData` is 400 (gemini.ts:171-178). | gap | **P2.** CPA carries `file_data`/URI parts through its translators (internal/translator/gemini/interactions/interactions_gemini_uri_test.go:43-90). PDF, audio, and Files-API URIs are common in genai SDK use. | +| R23 | `thoughtSignature` | Carries signatures across Interactions↔Gemini with pending-signature carrier parts (internal/translator/gemini/interactions/interactions_gemini_common.go:1082-1240). For native requests it validates them and drops invalid or foreign ones (internal/runtime/executor/helps/gemini_interactions.go:58-97). | #8742's codec never reads or emits `thoughtSignature`, and it drops thought parts from history (#8742:src/protocols/codecs/gemini.ts:205-206,253). dev has a server-side replay store for the Responses path (src/responses/thought-signature-replay.ts:1-21). | gap | **P1.** Gemini 3 rejects a replayed `functionCall` that has no signature (src/responses/thought-signature-replay.ts:4-10). A google-genai client does echo the signature, but #8742 throws it away and does not emit it. It is unverified whether the Chat path's store rescues these calls when the upstream is Google. | +| R24 | Hosted tools | Interactions `google_search`/`web_search`, `url_context`, and `code_execution` map to `googleSearch`/`urlContext`/`codeExecution` (interactions_gemini_common.go:910-960). The reverse direction is at :401-450. | #8742 **silently ignores** hosted tools; only `functionDeclarations` are kept (#8742:src/protocols/codecs/gemini.ts:58-63). | gap | **P2.** Dropping search grounding changes the answer, which conflicts with the codec's own rule to return 400 rather than silently change an answer (gemini.ts:4-6). Either pass these through when the route is Google-native or return 400. | +| R25 | `toolConfig.functionCallingConfig` | Interactions `tool_choice` maps to `mode` `NONE`/`AUTO`/`ANY` plus `allowedFunctionNames` (interactions_gemini_common.go:757-807). | #8742: `NONE`→`"none"`; `AUTO`/`VALIDATED`/`MODE_UNSPECIFIED`→`allowed_tools{mode:auto}` when names are listed; `ANY` with one name→a named function; `ANY` with several→`allowed_tools{mode:required}`; any other mode is 400 (#8742:src/protocols/codecs/gemini.ts:83-100). | have | — | +| R26 | Other `generationConfig` keys | Native Gemini upstreams pass them through *(inferred from the gemini/gemini translator)*. | #8742 maps `temperature`, `topP`, `presencePenalty`, `frequencyPenalty`, `maxOutputTokens`, `seed`, and `stopSequences`. `candidateCount` other than 1 is 400 (#8742:src/protocols/codecs/gemini.ts:132-159). `topK`, `responseModalities`, `imageConfig`, `speechConfig`, `mediaResolution`, and `responseLogprobs` are ignored *(inferred from absence)*. | partial | P3. `responseModalities:["IMAGE"]` is silently text-only, which may deserve a 400. | +| R27 | Structured output | Interactions inbound: **top-level `response_format` is not mapped** when the target is Gemini (absent from interactions_gemini_common.go:39-55). Gemini→Interactions builds `response_format:{type:"text",mime_type,schema}` (and image entries) (:222-318). | #8742: `responseMimeType: application/json` plus `responseJsonSchema`/`responseSchema` becomes `response_format:{type:"json_schema",json_schema:{name:"response",schema}}`. Mime only becomes `json_object`. Any other mime is 400 (#8742:src/protocols/codecs/gemini.ts:102-110). | have | CPA's dropping of `response_format` toward Gemini looks like a bug *(inferred)*. Avoid copying it if opencodex adds Interactions. | +| R28 | Thinking config | Interactions `thinking_level`/`thinking_budget`/`include_thoughts`/`thinking_summaries` normalize into `thinkingConfig` (interactions_gemini_common.go:694-730). Budget becomes a level, and summaries become `auto`/`none` (internal/thinking/provider/interactions/apply.go:68-130). | #8742: `thinkingLevel` becomes `reasoning_effort` when it is in {none, minimal, low, medium, high, xhigh}. `thinkingBudget` 0→none, ≤2048→low, ≤12288→medium, larger→high, and -1 keeps the default. `includeThoughts:true` becomes `include_reasoning` (#8742:src/protocols/codecs/gemini.ts:112-130). | have | — | +| R29 | Finish reasons and usage | The openai→gemini translator builds `usageMetadata.totalTokenCount` and related fields (internal/translator/openai/gemini/openai_gemini_response.go:694-702). | #8742: `stop`/`tool_calls`→`STOP`, `length`→`MAX_TOKENS`, `content_filter`→`SAFETY`. An unknown or missing finish is an error (#8742:src/protocols/codecs/gemini.ts:306-315,336). Usage maps to `promptTokenCount`, `candidatesTokenCount` (completion minus reasoning), `totalTokenCount`, `thoughtsTokenCount`, and `cachedContentTokenCount` (gemini.ts:286-304). | have | — | +| R30 | Streamed tool calls | — | #8742 accumulates deltas and emits one complete `functionCall` part at finish. The id is the Chat call id or the synthetic `call_gemini_response_` (#8742:src/protocols/codecs/gemini.ts:321-328,394-423). | have | — | +| R31 | Body limits and admission | Uses `maxRequestBodyBytes` (internal/api/server_middleware.go:65-70). | #8742 uses raised-body admission (#8742:src/server/inbound-body-admission.ts:167) and returns 413 Google errors (#8742:src/server/gemini-inbound.ts:110,123). | have | — | +| R32 | CORS | Sends `Access-Control-Allow-Origin: *` on SSE and Interactions streams (gemini_handlers.go:205; interactions_handlers.go:150). | #8742 uses `withCors` with data-plane origin policy and returns 403 for disallowed origins (#8742:src/server/index/gemini-routes.ts:53,62,80-84). | intentionally-different | | +| R33 | Ingress isolation | — | #8742 denies `/v1beta/*` on management/Tailscale ingress (#8742:src/server/index.ts:460). The data loopback admits each Gemini path with its own verb only (#8742:src/server/index.ts:424). | n-a | — | +| I01 | `POST /v1beta/interactions` | Handled at interactions_handlers.go:93-119 (route at server_routes.go:153). | dev: none. #8742: none; only `/v1beta/models*` is classified (#8742:src/server/gemini-native-paths.ts:26-27). | gap | **P2.** This is the largest missing surface. | +| I02 | `model` vs `agent` | Exactly one is required; otherwise 400 `"request requires exactly one of model or agent"` (interactions_handlers.go:27-39). `agent` forces provider `gemini-interactions` and picks auth with model `gemini-2.5-flash` (interactions_handlers.go:19,74-91). | — | gap | Agents (deep-research and similar) are only possible with a native Google Interactions upstream. | +| I03 | `stream` | Must be a JSON boolean; otherwise 400 `"stream must be a boolean"` (interactions_handlers.go:40-47). `true` gives SSE and `false` gives JSON (interactions_handlers.go:114-118). | — | gap | — | +| I04 | `input` shapes | A string becomes one user text turn. An array is a list of steps. An object with `steps` plus `role` is a turn. A single step or content object is also accepted (interactions_gemini_common.go:1044-1080). | — | gap | — | +| I05 | Step types (input) | `model_output`, `thought` (`signature`/`thought_signature`/`thoughtSignature`), `function_call` (`id`, `name`, `arguments`), `function_result` (`call_id`, `name`, `result`), and `user_input` (`content[]` or native `parts`) (interactions_gemini_common.go:1082-1222). `developer`/`system` role steps count as instructions (internal/translator/common/parts.go:111-123). | — | gap | Native upstreams need `function_call.id` without `call_id`, and `function_result.call_id` without `id` (helps/gemini_interactions.go:24-29,98-124). | +| I06 | `system_instruction` | A string, `{text}`, or `{parts}` becomes Gemini `systemInstruction` (interactions_gemini_common.go:658-676). | — | gap | — | +| I07 | `generation_config` and friends | snake_case keys become camelCase. `thinking_*` is normalized. `response_modalities` maps to `TEXT`/`IMAGE`/`AUDIO`. `tool_choice` (top level or inside generation_config) maps to `toolConfig`. `service_tier` passes through (interactions_gemini_common.go:678-815). | — | gap | — | +| I08 | `tools` (Interactions) | Typed entries `function` (`name`/`description`/`parameters`), `google_search`, `url_context`, and `code_execution` (interactions_gemini_common.go:910-960). | — | gap | — | +| I09 | Non-stream response | `{"id","object":"interaction","status":"completed","model","steps":[...],"usage":{input_tokens,output_tokens,reasoning_tokens,total_tokens,cached_tokens}}`. The id is the Gemini `responseId` or `interaction_` (interactions_gemini_common.go:631-656,1706-1728). Steps are `model_output{content[]}`, `thought{signature,summary}`, `function_call{id,name,arguments}`, and `function_result{name,result}` (:1876-1986). | — | gap | — | +| I10 | Stream event names and payloads | Each frame is `event: \ndata: \n\n` (internal/translator/common/bytes.go:87-95). The sequence is: `interaction.created` `{interaction:{id,status:"in_progress",object,model},event_type}`; `interaction.status_update` `{interaction_id,status}`; `step.start` `{index,step:{type[,id,name,arguments:{}]}}`; `step.delta` with `delta.type` ∈ `text`, `thought_summary`(`content.text`), `arguments_delta`(`arguments`), `function_result`(`name`,`result`), `thought_signature`(`signature`); `step.stop` `{index}`; `interaction.completed` `{interaction:{id,status,usage,created,updated,service_tier:"standard",object,model}}`; then `event: done` / `data: [DONE]` (interactions_gemini_common.go:594-629,1758-1797,1799-1856). | — | gap | The event vocabulary is consistent across all 5 translated providers (rg counts: 6× each `event_type`). | +| I11 | Stream usage fields | `interaction.completed.usage` = `total_tokens`, `total_input_tokens`, `input_tokens_by_modality[{modality:"text",tokens}]`, `total_cached_tokens`, `total_output_tokens`, `total_tool_use_tokens:0`, `total_thought_tokens` (interactions_gemini_common.go:1730-1756). Readers try `interaction.usage`, `usage`, `metadata.total_usage`, `metadata.usage`, … (internal/translator/common/interactions_usage.go:5-19). | — | gap | Stream usage names (`total_*`) differ from non-stream names (`input_tokens`…) in CPA *(observed)*. Decide on one before copying. | +| I12 | Stream completion gating | Completes only on usage seen at or after the finish frame. `[DONE]` with no usage still completes once (interactions_gemini_common.go:497-546). | — | gap | Worth copying as tests (see fixtures). | +| I13 | `status` values | `in_progress` and `completed`. `requires_action` appears only from the native upstream (internal/runtime/executor/helps/antigravity_interactions_state.go:158). Translated providers always report `completed`, even for tool calls (internal/translator/claude/interactions/interactions_claude_response.go:64,82,517). `incomplete` is handled for length (internal/translator/openai/interactions/chat-completions/openai_interactions_response.go:104). | — | gap | If opencodex builds this, emit `requires_action` when the turn ends in a function call *(suggested)*. | +| I14 | `previous_interaction_id` | **No local store.** It passes through unchanged to native `gemini-interactions` (the Interactions→Interactions passthrough at internal/translator/gemini/interactions/init.go:10-18). For OpenAI targets it is renamed to `previous_response_id` (internal/translator/openai/interactions/chat-completions/interactions_openai_request.go:222-224; responses/interactions_openai_responses_request.go:128). It is **silently dropped** for Claude, Gemini-generateContent, Codex, and Antigravity-generate translators (rg finds no reference in those request files). There is no local 404 for an unknown id. `environment_id` and `agent_config` are forwarded to OpenAI targets (interactions_openai_request.go:225-230). | — | gap | **Design decision.** Silently dropping the id loses the whole conversation. opencodex should return 400 when it cannot honor the id, or keep its own bounded store. | +| I15 | Antigravity continuation cache | Used when the model has the `antigravity` prefix on the gemini-interactions executor and the request has no explicit `previous_interaction_id`. A trailing run of `function_result` steps is looked up in a cache keyed by `sha256(caller, auth.ID, provider, api_key, base_url, model, identity)` plus the sorted call ids. On a hit, the request is rewritten to `previous_interaction_id` plus only the results (internal/runtime/executor/helps/antigravity_interactions_state.go:55-132). The cache only records `interaction.completed` events with `status:"requires_action"` (:134-174). TTL is 30 min and the cap is 1024 entries with oldest eviction; ambiguous or duplicate call ids are rejected (internal/cache/antigravity_interactions_session.go:21-76). | — | gap | P3. This only matters with a native Interactions upstream. | +| I16 | `store` / `background` / GET / DELETE | The handler does nothing special, so the fields pass through to native. The Codex translator copies `store` (internal/translator/codex/interactions/interactions_codex_request.go:23,432-436), but the codex executor forces `store:false` (internal/runtime/executor/codex_executor_request.go:419). **There are no `GET`/`DELETE /v1beta/interactions/{id}` routes** (internal/api/server_routes.go:149-155). | — | gap / n-a | `background:true` cannot be polled through CPA *(inferred)*. Parity here is cheap: return 400 for `background:true` unless the upstream is native and GET is proxied. | +| I17 | Native upstream wire | Calls `POST {base}/v1beta/interactions` with `x-goog-api-key` (internal/runtime/executor/gemini_executor.go:35,752,762). Sends `Api-Revision: 2026-05-20` by default and forwards the client's own `Api-Revision` (helps/gemini_interactions.go:17-19,203-221). SSE parsing accepts bare JSON, multiline `data:`, and `[DONE]`/`event: done` (helps/gemini_interactions.go:223-276). | dev: no Interactions upstream adapter (rg). | gap | P3 (outbound lane). | +| I18 | Interactions error envelope | Parse errors are 400 `{"error":{"message","type":"invalid_request_error"}}` (interactions_handlers.go:95-104). Upstream errors use `WriteErrorResponse` (:126-129). After commit: `event: error\ndata: ` (:237-252). | — | gap | If opencodex builds this, reuse the Google `{code,message,status}` body from #8742 (#8742:src/server/gemini-inbound.ts:38-51). | +| I19 | Interactions provider routing | An Interactions entry prefers `gemini-interactions`. OpenAI, Responses, Claude, and Gemini entries may also use it; other entry protocols exclude it (sdk/api/handlers/handlers_routing.go:60-77). Translator pairs from Interactions go to Gemini, Claude, Codex, Antigravity, OpenAI Chat, and OpenAI Responses (each internal/translator/*/interactions/init.go:10-18). | — | gap | opencodex can do the same through one Interactions→Chat codec, like #8742 does for generateContent. | +| I20 | Other inbound protocols → Interactions upstream | Claude→Interactions (internal/translator/interactions/claude/init.go:10-18), OpenAI Chat/Responses→Interactions (internal/translator/openai/interactions/*/init.go:10-18), and Gemini→Interactions (internal/translator/gemini/interactions/init.go:28-36). | — | gap | P3. Outbound lane. | + +## Highest-value gaps (ranked) + +1. **R23, thoughtSignature round-trip in #8742 (P1).** The codec discards `thoughtSignature` on inbound `functionCall`/text parts and never emits it outbound (#8742:src/protocols/codecs/gemini.ts:197-264,331-356). A Gemini-3 upstream returns 400 on the second tool turn unless the Chat path's server-side store (src/responses/thought-signature-replay.ts) happens to rescue it. Smallest fix: map `part.thoughtSignature` to `tool_calls[].extra_content.google.thought_signature`, and back out on response and stream chunks. The wire shape already exists (src/responses/provider-opaque-metadata.ts:17,57-60). +2. **I01–I13, no `/v1beta/interactions` (P2).** Build one Interactions→Chat codec beside `src/protocols/codecs/gemini.ts` and reuse the #8742 bridge (`native-chat-bridge.ts`) and error body. Copy the CPA event vocabulary (I10) and the completion gating (I12). Return 400 for `agent`, `background:true`, and `previous_interaction_id` unless they can be honored (I02, I14, I16). +3. **R24, silently dropped hosted tools (P2).** `googleSearch`, `urlContext`, and `codeExecution` vanish (#8742:src/protocols/codecs/gemini.ts:62-63), which violates the codec's own rule against silently changing an answer. Return 400, or pass the tools through when the selected route is a Google adapter. +4. **R07, `countTokens` returns 501 (P2).** CPA serves it for every provider. Answer `{"totalTokens":N}` from opencodex's estimator, or from the provider's endpoint when one exists. +5. **R22, `fileData` and non-image `inlineData` return 400 (P2).** PDFs, audio, and Files-API URIs are common genai-SDK inputs. CPA forwards them. +6. **R11, model metadata (P2).** Add `inputTokenLimit`, `outputTokenLimit`, and `description` from the catalog so Gemini clients can budget context. +7. **R05/R06 (P3).** Add the `$alt` alias and an optional SSE `: keep-alive` comment before the first token. +8. **R17 nit (P3).** Fill in `STATUS_NAMES` for 402, 408, 409, 422, 500, and 502. + +## Test fixtures worth copying (CPA test file:line) + +- sdk/api/handlers/gemini/interactions_handlers_test.go:26 (`TestParseInteractionsRequestTarget`: model/agent/stream validation), :109/:126/:143/:160 (400 cases), :61/:75 (`models/` normalization), :364 (bare JSON wrapped as `data:`), and :383 (keep-alive, then an SSE error on failure). +- sdk/api/handlers/gemini/gemini_handlers_stream_error_test.go:55 (an error before the first payload is not lost) and :122 (keep-alive before the first token, then `event: error`). +- sdk/api/handlers/gemini/issue7513_bootstrap_failover_test.go:22,110 (zero-output rotation and 502 on exhaustion, for both stream and non-stream). +- internal/translator/gemini/interactions/interactions_gemini_common_test.go:317 (step lifecycle), :377/:397/:416/:452/:488/:533 (completion gating: usage after finish, split finish/usage, terminal once, `[DONE]` without usage), :1152/:1184/:1212/:1324/:1353/:1389 (thought-signature preservation; directly relevant to R23), :1117 (parallel tool-call history), :1285 (response→request round trip). +- internal/translator/gemini/interactions/interactions_gemini_stream_lines_test.go:10/:39/:51 (SSE line parsing, control lines ignored, prefixed `[DONE]` completes once). +- internal/translator/gemini/interactions/interactions_gemini_uri_test.go:43-151 (fileData URI round trip; an attachment-only turn that cannot be represented is refused; relevant to R22). +- internal/translator/openai/interactions/chat-completions/interactions_openai_request_test.go:9,28,63,95,190 (Interactions↔Chat field mapping; out-of-order tool results; `previous_interaction_id` preservation). This is the closest analogue to an opencodex Interactions→Chat codec. +- internal/translator/claude/interactions/interactions_claude_user_turn_test.go:88-234 (refusing media that cannot be represented and keeping text beside it). +- internal/runtime/executor/helps/antigravity_interactions_state_test.go:12 (`TestIssue5190ContinuationIsolation`: continuation cache key isolation). + +## Open questions + +1. Does the inner Chat path in #8742 (`handleChatCompletions` with `suppressProtocolTrace`) apply the thought-signature replay store when the route is a Google adapter, given that the inbound call ids are synthetic `call_gemini__` when the client omits `functionCall.id` (#8742:src/protocols/codecs/gemini.ts:218)? A runtime test against a Gemini-3 route would settle R23. +2. Does `findOllamaRoute` resolve a bare `gemini-2.5-pro`, or only `provider/model`? google-genai and agy send bare names by default. +3. Do google-genai SDKs accept a mid-stream `data: {"error":...}` record (the #8742 failure frame) as a raised error, or do they treat it as a malformed chunk? This is unverified for both opencodex and CPA. +4. For Interactions, should `previous_interaction_id` be refused (400), resolved from a local bounded store (CPA keeps none except the antigravity tool-result suffix), or passed only to a native upstream? This is a product decision for the parent. +5. Which `Api-Revision` would an opencodex Interactions surface claim? CPA pins `2026-05-20` (helps/gemini_interactions.go:19). +6. CPA's Interactions usage uses `total_*` names in streams but `input_tokens`/`output_tokens` in non-stream bodies (I11). Which one does the real Google API use for the pinned revision? Check this against Google docs before copying. diff --git a/devlog/_plan/261115_google_protocol_cpa_parity/004_lane_b_antigravity_outbound.md b/devlog/_plan/261115_google_protocol_cpa_parity/004_lane_b_antigravity_outbound.md new file mode 100644 index 00000000000..1c806b72745 --- /dev/null +++ b/devlog/_plan/261115_google_protocol_cpa_parity/004_lane_b_antigravity_outbound.md @@ -0,0 +1,98 @@ + +# B — CPA Antigravity outbound (Cloud Code Assist v1internal) vs opencodex + +Scope: outbound Antigravity only. CPA = router-for-me/CLIProxyAPI at devlog/_chase/_cca HEAD e96d4c4 (2026-11-15); CPA paths are relative to devlog/_chase/_cca. opencodex = branch feat/google-protocol-cpa-parity at d842c1352e (== origin/dev); PR #8742 = pr/8742 head d21ed22ea8. Read-only source review; nothing was executed against Google. "(inferred)" marks conclusions not directly stated by code. + +PR #8742 does not touch the outbound Antigravity adapter: its diff adds Gemini inbound (src/protocols/codecs/gemini.ts, src/server/gemini-inbound.ts) and gateway connectors that point the Antigravity app / agy CLI at opencodex (pr/8742:structure/clients/antigravity-gateway.md:8-18). So every "opencodex" cell below is dev, which #8742 leaves unchanged. + +| id | area | CPA behaviour (file:line) | opencodex dev / #8742 behaviour (file:line) | status | notes / priority | +|---|---|---|---|---|---| +| E1 | envelope model | top-level "model" = route model (internal/runtime/executor/antigravity_executor_request.go:728) | "model": wireModelId (src/adapters/google.ts:1235) | have | — | +| E2 | envelope userAgent | body "userAgent":"antigravity" (antigravity_executor_request.go:729) | "userAgent":"antigravity" (src/adapters/google.ts:1239) | have | — | +| E3 | envelope requestType | default "agent"; model id containing "image" → "image_gen"; caller-supplied "web_search" kept (antigravity_executor_request.go:731-740); Claude web search builds requestType "web_search" + tools[0].googleSearch.enhancedContent.imageSearch (internal/translator/antigravity/claude/web_search.go:103-110) | always "agent": chat (src/adapters/google.ts:1240), image route (src/server/images.ts:321), google_search sidecar (src/web-search/gemini-executor.ts:56) | gap | P2. Image and search requests carry the wrong requestType vs native client. Effect upstream unverified. | +| E4 | envelope requestId | "agent-"+uuid (antigravity_executor_request.go:769-771); image: "image_gen///12" (:773-775); web_search: no requestId and no request.sessionId (:750; test antigravity_executor_buildrequest_test.go:237-248) | "agent-"+uuid everywhere (src/adapters/google.ts:1242; src/server/images.ts:323; src/web-search/gemini-executor.ts:58); image sends sessionId "ocx-img-…" (src/server/images.ts:327), search sends random UUID sessionId (gemini-executor.ts:63) | gap | P3, ships with E3. | +| E5 | envelope project | set from auth metadata project_id, deleted when empty (antigravity_executor_request.go:742-746); missing → 400 "antigravity auth missing project_id" (antigravity_executor_auth.go:251-270) | required provider.project, throws "re-run ocx login" (src/adapters/google.ts:1155-1156) | have | — | +| E6 | request.sessionId | explicit request.sessionId > derived session metadata > "-"+int63(sha256(first user parts.0.text)[:8]) > random (antigravity_executor_request.go:752-759, 803-826) | Codex parent/own thread anchor, else first user text incl. document parts, hashed with "acct:\0" prefix when an account scope exists (src/adapters/google-antigravity-wire.ts:92-123, 137-170) | intentionally-different | Same derivation shape; ocx adds account scoping and compaction-stable anchor. | +| E7 | safetySettings | deleted from request (antigravity_executor_request.go:762) | wire compiler whitelist never emits it (src/adapters/google-wire-compiler.ts:220-248) | have | — | +| E8 | toolConfig placement | top-level toolConfig moved to request.toolConfig (antigravity_executor_request.go:763-766) | built directly inside request (src/adapters/google.ts:1091-1092, 1187) | have | — | +| E9 | maxOutputTokens | capped to registry max_completion_tokens (antigravity_executor_request.go:70-77) and DELETED for every non-Claude model (:88-90) | clamped and sent for all models incl. Gemini on CCA (src/adapters/google.ts:1095-1096; :144) | gap (unverified) | P3. CPA drops the cap for Gemini on CCA; reason not stated in code. See Open questions. | +| E10 | Claude VALIDATED | Claude → request.toolConfig.functionCallingConfig.mode="VALIDATED" unless prompt structured output (antigravity_executor_request.go:84-87) | Claude wire → VALIDATED; tool_choice "none" drops tools+toolConfig instead (src/adapters/google.ts:1189-1199) | have | ocx handles tool_choice none explicitly. | +| E11 | enabledCreditTypes | sets top-level "enabledCreditTypes":["GOOGLE_ONE_AI"] when conductor requests credits fallback and config quota-exceeded.antigravity-credits is on (antigravity_executor_credits.go:212-217, 290-292; antigravity_executor_execute.go:108-118); balance from loadCodeAssist paidTier.availableCredits[creditType=GOOGLE_ONE_AI].creditAmount >= minimumCreditAmountForUsage (antigravity_executor_credits.go:665-700); INSUFFICIENT_G1_CREDITS_BALANCE disables credits (:338-356, 306-329) | none (rg for enabledCreditTypes / GOOGLE_ONE_AI / availableCredits in src finds no Antigravity hit) | gap | P2. Feature: spend Google One AI credits after quota exhaustion. Opt-in in CPA. | +| H1 | base URL + fallback | single endpoint, default daily https://daily-cloudcode-pa.googleapis.com, per-auth base_url override, "without cross-tier fallback" (antigravity_executor_request.go:649-656, 698-716); sandbox/prod constants remain (antigravity_executor.go:35-37); test asserts exactly one daily request on transport error (antigravity_executor_signature_test.go:995-1050) | registry baseUrl daily, allowBaseUrlOverride (src/providers/registry/entries-core.ts:1262); no fallback | have | CPA dropped daily→sandbox→prod fallback; ocx already single-endpoint. | +| H2 | paths | POST /v1internal:generateContent; stream /v1internal:streamGenerateContent?alt=sse; opts.Alt → ?$alt= (antigravity_executor_request.go:44-61) | same two paths, ?alt=sse (src/adapters/google.ts:1143-1154) | have | — | +| H3 | countTokens | /v1internal:countTokens, strips project, request.toolConfig, request.sessionId (antigravity_executor.go:38; antigravity_executor_tokens.go:77-84) | none for CCA (only a Vertex probe: src/adapters/google-vertex-key-project.ts:19) | gap | P3. Codex does not call it; useful only for a Gemini/Claude count_tokens inbound. | +| H4 | User-Agent (inference) | "antigravity/hub/ (aidev_client; os_type=darwin; arch=arm64[; cl=])", version from hub auto-updater manifest refreshed every 3h, fallback 2.29.0 (internal/misc/antigravity_version.go:18-33, 64-133); per-auth user_agent override (antigravity_executor_request.go:673-696) | IDE UA "antigravity/ide/2.5.5 (os_type=windows; arch=amd64; aidev_client; auth_method=oauth)"; CLI UA "antigravity/cli/1.3.4 (...darwin/arm64...)" for ^gemini-4-(-tier)?$ (src/adapters/client-fingerprint.ts:78-125; src/adapters/google-antigravity-wire.ts:12-42); env GOOGLE_ANTIGRAVITY_USER_AGENT override (client-fingerprint.ts:97-98) | intentionally-different | P2 to re-verify: CPA uses the hub family with a live version and notes Cloud Code rejects newer models below 2.23.0 (antigravity_version.go:19-22); ocx pins IDE 2.5.5 + CLI split. Different evidence for the same gating. | +| H5 | X-Goog-Api-Client | not sent on inference or loadCodeAssist (tests: antigravity_executor_buildrequest_test.go:289-290, antigravity_executor_credits_test.go:973-974); onboardUser sends "gl-node/22.21.1" and UA suffix " google-api-nodejs-client/10.3.0" (internal/auth/antigravity/auth.go:343-347; antigravity_version.go:27-28, 170-183) | never sent; onboardUser UA = plain IDE UA (src/oauth/google-antigravity.ts:144-152) | gap | P3 fingerprint nit on onboarding only. | +| H6 | Client-Metadata header | not sent | not sent | have | — | +| H7 | transport | forced HTTP/1.1, keep-alive pool, no Connection: close (antigravity_executor.go:285-312, 364-397; antigravity_executor_request.go:107-110) | optional "antigravity-browser" TLS profile for CCA hosts (src/lib/provider-tls-profile.ts:13-22) | intentionally-different | — | +| R1 | response wrapper | unwraps "response"; also accepts bare root with candidates, and usage-only roots (antigravity_executor_execute.go:677-688; helps/usage_helpers.go:3969-3975) | requires object "response", else terminal "google-antigravity response missing response wrapper" (src/adapters/google.ts:1415-1424, 1726-1731) | intentionally-different | P3. ocx fails closed on an unwrapped frame; CPA tolerates it. | +| R2 | in-stream error frame | {"error":{code}} on HTTP 200 → status = error.code if 400-599 else 502; 403 runs TOS handling (antigravity_executor_stream.go:326-342; Claude non-stream path antigravity_executor_execute.go:492-508) | chunk.error → terminal error event with error.status + last finishReason, clears replay signatures (src/adapters/google.ts:1402-1413) | have | No status code carried; no TOS check (see X3). | +| R3 | split JSON across SSE lines | accumulates invalid JSON into pendingJSON until valid (antigravity_executor_stream.go:304-322) | unparseable data frame → "malformed upstream SSE data frame" terminate (src/adapters/google.ts:1383-1389) | gap (unverified) | P3. Only matters if CCA splits one JSON over multiple events; multi-line data within one event is handled by the SSE parser (inferred). | +| R4 | empty / zero-output stream | GeminiZeroOutputStreamGuard → 502; payload with only thoughtSignature + usage counts as zero output (antigravity_executor_stream.go:278-292; helps/gemini_zero_output_test.go:89) | error if no frame or no terminal signal (src/adapters/google.ts:1612); usageMetadata alone sets sawTerminalSignal (:1427-1433) | gap (inferred) | P2. A signature-only + usage stream likely completes as an empty success in ocx (inferred from :1432). | +| R5 | filter/safety block | GeminiFilterBlockMessage → HTTP 400 with Google's message (antigravity_executor_execute.go:515-537) | finishReason SAFETY/RECITATION/BLOCKLIST/PROHIBITED_CONTENT/SPII → stop reason (src/adapters/google.ts:1618, 1839) | have | Different surface, same signal. | +| R6 | non-stream path | Claude, gemini-3-pro, gemini-3.1-flash-image use streamGenerateContent and aggregate (antigravity_executor_execute.go:60-63, 377, 581-700) | non-stream uses :generateContent (src/adapters/google.ts:1143) | gap | P3. Codex always streams. | +| R7 | usage mapping | input = promptTokenCount + toolUsePromptTokenCount; output = candidatesTokenCount; reasoning = thoughtsTokenCount; cached = cachedContentTokenCount; keeps serviceTier/trafficType and modality details (helps/usage_helpers.go:3209-3288) | input = promptTokenCount only; output, cached, reasoning same (src/adapters/google.ts:679-687) | gap | P2. Undercounts input when toolUsePromptTokenCount > 0 (search/tool grounding). | +| R8 | usage only on terminal chunk | FilterSSEUsageMetadata keeps usage only on the terminal chunk (antigravity_executor_stream.go:343-349) | keeps latest usage, emits one done (src/adapters/google.ts:1425-1433) | have | — | +| T1 | Gemini thinking | level mode → thinkingLevel; budget/auto → thinkingBudget; client includeThoughts preserved (internal/thinking/provider/antigravity/apply.go:88-145) | effort → wire id suffix and/or thinkingLevel; includeThoughts only when provider.showThinkingSummary (src/adapters/google.ts:1158-1181; src/providers/antigravity-models.ts:794-885) | intentionally-different | ocx never sends thinkingBudget on CCA (compiler allows it only without a level: src/adapters/google-wire-compiler.ts:175-178). | +| T2 | Claude thinking on CCA | -high Claude 5.5 models expose levels low/medium/high (internal/registry/models/models.json:4407-4426); budget mode clamps budget to maxOutputTokens-1, drops thinkingConfig below min 1024, defaults maxOutputTokens to model max 128000 (apply.go:162-196) | thinkingLevel only; ladder claude-*-5-5-{low,medium,high} (src/providers/antigravity-models.ts:93-98, 210-220, 877-881) | have / gap | P3: budget path absent. Level path matches. | +| T3 | thinking 400 repair | not observed in executor | drops thinkingConfig on INVALID_ARGUMENT naming thinking config and replays once (src/adapters/google-wire-compiler.ts:270-305; src/adapters/google-http.ts:107-134) | intentionally-different (ocx-only) | — | +| S1 | replay cache store | key (model, sessionKey); TTL 1h; 10240 entries; 4096 items / 16 MiB per entry; optional home-KV with CAS + tombstones (internal/cache/antigravity_reasoning_replay_cache.go:20-44, 558-571) | sha256(model, sessionId) (src/adapters/google-antigravity-replay.ts:344-349); TTL 1h, 10240 entries, 256 calls / 2 MiB per session, 64 MiB total, durable snapshot file (:37-57) | have | — | +| S2 | replay session key | Claude Code scope(+system lane) > Session-Id header > body session_id > execution session > prompt_cache_key > client session > derived (internal/runtime/executor/antigravity_reasoning_replay.go:242-284) | the request.sessionId itself (src/adapters/google.ts:1157, 1207-1208) | intentionally-different | ocx deliberately avoids prompt_cache_key (src/adapters/google-antigravity-wire.ts:102-106). | +| S3 | replay match identity | sha256(name, canonical args, callID) + context fingerprint of preceding contents (antigravity_reasoning_replay.go:1236-1246, 1880-1903) | sha256(name, canonical args) only (src/adapters/google-antigravity-replay.ts:476-489) | gap (low) | P3. ocx comments argue name+args collisions are harmless (google-antigravity-wire.ts:93-96). | +| S4 | clear-on-invalid | only HTTP 400 whose body mentions signature/thoughtSignature/thought_signature; CAS delete of the scope snapshot (antigravity_reasoning_replay.go:563-576) | any HTTP 400, or error text matching signature; also on in-stream and buffered error bodies; evicts durable entries for injected call ids (src/adapters/google.ts:956-981, 1004-1005, 1408, 1722) | have | ocx is broader (clears on any 400). | +| S5 | bypass sentinel | "skip_thought_signature_validator" on the FIRST functionCall of each model turn lacking one; siblings stay unsigned (antigravity_reasoning_replay.go:2290-2336) | same constant and first-call rule (src/adapters/google-antigravity-replay.ts:642-705); sentinel never re-ingested (src/adapters/google-antigravity-wire.ts:60-72) | have | — | +| S6 | foreign-id signature filtering | SanitizeNonVertexGeminiRequestThoughtSignatures (antigravity_executor.go:536-545) | isLikelyRealThoughtSignature rejects fc_/call_/toolu_/rs_ … prefixes and non-base64 (src/adapters/google-antigravity-wire.ts:60-72) | have | — | +| S7 | Claude-on-CCA signatures | validates Claude signature trees and Gemini carrier envelopes (direction/target kind), drops incompatible thinking, resolves signatures from a thinking-text cache (internal/translator/antigravity/claude/signature_validation.go:67-97, 186-329; internal/translator/antigravity/claude/antigravity_claude_request.go:22-150, 419-475) | drops thought parts with no signature, strips signatures on non-model turns; no format validation (src/adapters/google-antigravity-wire.ts:218-235) | gap | P2. A malformed or cross-provider signature on a Claude thought part reaches CCA and 400s. | +| S8 | degraded Claude tool ids | reserved Claude provenance ids rewritten to call_, stale signature → sentinel (antigravity_reasoning_replay.go:2188-2279) | request-scoped id allocator keeps call/response pairing (src/adapters/google.ts:204-223, 404-416, 505-523) | n-a | Different id model. | +| TL1 | schema sanitization scope | cleans only schema locations; renames parametersJsonSchema→parameters; Claude + gemini-3-pro/3.1-pro use the Antigravity schema profile (antigravity_executor_request.go:79-83, 144-176, 547-616) | cloud-code-assist profile; local $ref/$defs inlined; unsupported keywords dropped with loss report (src/adapters/google-tool-schema.ts:3-58, 172-231) | have | — | +| TL2 | Claude unions | flattens multi-branch anyOf/oneOf for Claude (antigravity_executor_request.go:159-162) | widens a non-collapsible union to {} for CCA Claude (src/adapters/google-tool-schema.ts:578-581) | have | Different mechanism. | +| TL3 | empty object placeholder | adds required "reason" property ("Brief explanation of why you are calling this tool") to empty object schemas for Claude VALIDATED (internal/util/gemini_schema.go:18, 188; antigravity_executor_request.go:527-533) | root coerced to {type:object, properties:{}} with no required field (src/adapters/google-tool-schema.ts:810-819) | gap (unverified) | P2. CPA says VALIDATED needs at least one required property; ocx sends VALIDATED with argument-less tools. Needs a live check. | +| TL4 | schema 400 repair | not observed in executor | opens the rejected declaration (or all) to an empty object schema and replays once (src/adapters/google-wire-compiler.ts:265-329; src/adapters/google-http.ts:107-134) | intentionally-different (ocx-only) | — | +| TL5 | intrinsic tool-name collision | prefixes client tools named like Interactions sandbox tools (internal/translator/common/antigravity_tools.go:5-51) | name codec for wire-safe names (src/adapters/google-wire-compiler.ts:39-77) | n-a | CPA's prefixing applies to the Interactions API only. | +| M1 | tool-result images | moves inlineData siblings into functionResponse.parts (leading images attach to the first response); defaults mimeType image/png (internal/translator/antigravity/gemini/antigravity_gemini_request.go:889-955; claude request :671-701) | nests only for Vertex Argon; otherwise sibling inline_data parts after functionResponse (src/adapters/google.ts:337-355, 1070-1081) | gap | P2. Native client shape is nested parts. | +| M2 | user media | inlineData camelCase; OpenAI file/video/audio inline; imageConfig.aspectRatio/imageSize (internal/translator/antigravity/openai/chat-completions/antigravity_openai_request.go:126-134, 176-202, 448-458) | inline_data snake_case for image/video/document; file_data only for YouTube/Files URIs (src/adapters/google.ts:425-470) | have | Proto JSON accepts both spellings. imageConfig not mapped (P3). | +| M3 | Claude structured output | Claude 5.5: schema moved into a system-instruction prompt, responseMimeType removed, ANY/VALIDATED → AUTO (internal/runtime/executor/helps/antigravity_structured_output.go:13, 30-88) | rejects text.format for non-Gemini CCA models with an explicit error (src/adapters/google.ts:1021-1032) | intentionally-different | P3. Fail-closed vs best effort. | +| X1 | 429 classification | ErrorInfo.reason: QUOTA_EXHAUSTED / INSUFFICIENT_G1_CREDITS_BALANCE → quota exhausted; RATE_LIMIT_EXCEEDED: retry <3s → retry same auth, <5m → cooldown and switch auth, else exhausted; keyword fallback (internal/runtime/executor/antigravity_executor_credits.go:219-288; antigravity_executor.go:47-48) | prose needles on error.message (src/adapters/google-errors.ts:34-69, 142-146); no ErrorInfo.reason parse | gap | P1. Structured reasons are the reliable discriminator. | +| X2 | retry delay | RetryInfo.retryDelay → ErrorInfo.metadata.quotaResetDelay → message "after Ns" / "after 1h2m3s", Go durations (internal/runtime/executor/helps/json_retry_helpers.go:35-80) | parses only ^N(.N)?s$ (src/adapters/google-errors.ts:152-178), used only on the quota-exhausted branch (src/adapters/google-http.ts:141-155); transient 429 backoff reads only the Retry-After header, 250 ms→2 s (google-http.ts:25-26, 161-172; src/lib/upstream-retry.ts:421-425) | gap | P1. A body-only retryDelay "30s" gets a ~250 ms retry (inferred); "1h2m3s" style quotaResetDelay is ignored. | +| X3 | 403 TOS_VIOLATION | error.code 403 + PERMISSION_DENIED + ErrorInfo reason TOS_VIOLATION (metadata appeal_url, appeal_url_link_text) → terminal credential-scoped error; optional pool pause, off by default; also checked in-stream (antigravity_executor_credits.go:358-439, 884-940; antigravity_executor_stream.go:331-333) | handles VALIDATION_REQUIRED (src/adapters/google-errors.ts:4-15, 114-116) and "verify your account" (src/adapters/antigravity-refusal.ts:36-57); TOS_VIOLATION classed as generic access denied | gap | P1. Account keeps receiving traffic after a suspension (inferred). | +| X4 | 404 model not found | not observed | ResourceInfo models/ provenance → model-denial account rotation (src/adapters/antigravity-refusal.ts:12-31; src/server/responses/antigravity-model-denial-recovery.ts:24-54) | intentionally-different (ocx-only) | — | +| X5 | retries / rotation | one upstream request per credential; conductor owns rotation; short per-(auth,model) cooldown answers 429 with retryAfter (antigravity_executor_execute.go:50-57, 113-118) | up to 3 sends on 429/500/502/503/504 with jittered backoff (src/adapters/google-http.ts:88-197; src/adapters/google-errors.ts:132-134); dispatch-level OAuth account rotation on 429 (src/server/responses/adapter-dispatch.ts:90, 598-613) | intentionally-different | Per-model cooldown keyed on ErrorInfo depends on X1. | +| D1 | loadCodeAssist | daily base, body {"metadata":{"ideType":"ANTIGRAVITY"}}, UA hub (internal/auth/antigravity/auth.go:79-83, 248-267) | PROD base cloudcode-pa, same body, IDE UA (src/oauth/google-antigravity.ts:26, 105-109) | intentionally-different | P3 drift: host differs. | +| D2 | onboardUser | tier = allowedTiers[isDefault].id → currentTier.id → "free-tier"; body {tier_id, metadata:{ide_type, ide_version, ide_name}}; 5 polls, 30 s each, until done:true (auth.go:85-91, 114-139, 312-371) | same body and polling on daily (src/oauth/google-antigravity.ts:141-176) | have | — | +| D3 | fetchAvailableModels | POST {"project"}; models map keys + webSearchModelIds; 8 MiB cap; 401/403 → auth error (sdk/auth/antigravity_models.go:98-136, 161-212); internal ids skipped (cmd/fetch_antigravity_models/main.go:294-297) | POST {project} with CLI UA, sibling-account union, roster (src/codex/catalog/antigravity-discovery.ts:46-69; src/oauth/index.ts:1234; src/adapters/google-antigravity-wire.ts:26); quotaInfo remainingFraction/resetTime (src/providers/quota/antigravity.ts:24-120) | have | webSearchModelIds not read (P3). | +| D4 | token refresh | POST oauth2.googleapis.com/token with UA "Go-http-client/2.0"; refresh 5 min before expiry (antigravity_executor_auth.go:160-167; antigravity_executor.go:44) | refresh_token grant (src/oauth/google-antigravity.ts:24, 281-284) | have | UA on refresh not checked. | +| P1 | PR #8742 gateway | — | writes ~/.antigravity/settings.json gateway block and agy AGY_LLM_GATEWAY_* env (pr/8742:structure/clients/antigravity-gateway.md:8-18; pr/8742:src/integrations/gateway-clients/antigravity.ts:1-33) | n-a | Inbound/client lane. | + +## Highest-value gaps (ranked) + +1. X1 + X2: parse google.rpc.ErrorInfo.reason (QUOTA_EXHAUSTED, RATE_LIMIT_EXCEEDED, INSUFFICIENT_G1_CREDITS_BALANCE) and use RetryInfo.retryDelay / metadata.quotaResetDelay (full Go-duration syntax) for in-place backoff, cooldown and the client Retry-After. Today a body-only delay is invisible to the transient retry loop. +2. X3: recognise 403 TOS_VIOLATION (code 403, PERMISSION_DENIED, ErrorInfo reason TOS_VIOLATION) on HTTP and in-stream errors, and pause the account the way VALIDATION_REQUIRED / verify-account already do. +3. S7: validate Claude-on-CCA thinking signatures by format before forwarding, not only by presence. +4. R7: add toolUsePromptTokenCount to input tokens. +5. M1: nest tool-result images under functionResponse.parts for CCA (not only Vertex Argon). +6. TL3: confirm whether Claude VALIDATED rejects argument-less tool schemas; if so add CPA's required "reason" placeholder. +7. R4: treat a stream with no text/tool output (signature + usage only) as a failure. +8. E3/E4: requestType "image_gen" / "web_search" and their requestId/sessionId shapes for the image route and the search sidecar. +9. E11: optional GOOGLE_ONE_AI credits fallback (enabledCreditTypes) after quota exhaustion. + +## Test fixtures worth copying (CPA test file:line) + +- internal/runtime/executor/antigravity_executor_credits_test.go:149 (TestClassifyAntigravity429 — ErrorInfo reasons and retry thresholds), :246 (TestParseRetryDelay_HumanReadableDuration), :231 (TestInjectEnabledCreditTypes), :952 (loadCodeAssist UA, no X-Goog-Api-Client). +- internal/runtime/executor/antigravity_executor_tos_test.go:40 (TOS_VIOLATION body with appeal_url), :171 and :219 (SSE error frame, multi-line SSE error). +- internal/runtime/executor/antigravity_executor_buildrequest_test.go:19 (single daily base URL), :176 (sessionId derived vs explicit), :210 (web_search keeps requestType, no requestId/sessionId), :365 (Claude 5.5 explicit thinkingLevel). +- internal/runtime/executor/antigravity_executor_finish_reason_test.go:73 (trailing backend error), :198 (empty upstream stream not finalized), :257 (terminal chunk with usage), :350 (filter notice with usage). +- internal/runtime/executor/helps/gemini_zero_output_test.go:89 (signature-only + usage counts as zero output), :200 (split usage frame). +- internal/runtime/executor/helps/usage_helpers_test.go:497 (thoughtsTokenCount + toolUsePromptTokenCount), :1642 (full usageMetadata with modality details). +- internal/runtime/executor/antigravity_executor_signature_test.go:995-1050 (no cross-tier fallback on transport error), :1508-1530 (countTokens strips toolConfig/labels/sessionId). +- internal/cache/antigravity_reasoning_replay_cache_test.go and internal/runtime/executor/antigravity_reasoning_replay_test.go for replay ordering and clear-on-invalid cases. + +## Open questions + +- Why does CPA delete request.generationConfig.maxOutputTokens for every non-Claude model (antigravity_executor_request.go:88-90)? If CCA Gemini mis-handles the cap, ocx's clamp (src/adapters/google.ts:1095-1096) may truncate turns. +- UA family: does CCA currently serve gemini-3.7/3.8 and gemini-4 codenames to CPA's antigravity/hub/2.29.0 UA? ocx evidence says IDE vs CLI matters (src/adapters/google-antigravity-wire.ts:28-42); the two projects disagree on which family is canonical. +- Does CCA send a Retry-After header on 429, or only RetryInfo in the body? X2's severity depends on it. +- Does Claude VALIDATED reject a tool whose schema has no required properties (TL3)? +- Does CCA ever split one JSON payload across separate SSE events (R3)? +- loadCodeAssist host: CPA moved to daily; ocx calls prod (D1). Any account-tier difference between the two answers? + +NOT RUN: no tests, typecheck, or live Google requests; every claim is from source reading at the stated heads. diff --git a/devlog/_plan/261115_google_protocol_cpa_parity/005_lane_c_aistudio_vertex_outbound.md b/devlog/_plan/261115_google_protocol_cpa_parity/005_lane_c_aistudio_vertex_outbound.md new file mode 100644 index 00000000000..aff52934e62 --- /dev/null +++ b/devlog/_plan/261115_google_protocol_cpa_parity/005_lane_c_aistudio_vertex_outbound.md @@ -0,0 +1,99 @@ + +# C — CPA vs opencodex: outbound Gemini API (AI Studio key) and Vertex + +Heads: opencodex `dev` = `d842c1352e` (worktree HEAD == origin/dev), PR #8742 = `pr/8742` `d21ed22ea8`, CPA = `devlog/_chase/_cca` `e96d4c4` (2026-11-15). +Method: source reading with `rg`/`sed` only. No tests, servers, or upstream calls were run. +NOT RUN: any runtime/wire capture against Google, `bun run test`, CPA `go test`. +CPA paths are relative to `devlog/_chase/_cca`; opencodex paths are relative to the repo root. "(inferred)" marks a conclusion drawn from code shape rather than read directly. + +Scope note: CPA's `aistudio_executor.go` is a **websocket relay to the AI Studio web app** (`wsrelay`, aistudio_executor.go:1-49,96-102), not the public key-based API. The key-based Gemini API path is `gemini_executor.go`. Rows below compare opencodex's `google` adapter (googleMode `ai-studio` / `vertex`) with `gemini_executor.go` and `gemini_vertex_executor.go`. PR #8742 adds only a Gemini **inbound** surface that "never talks to Google itself" (structure/data-planes/gemini-inbound.md:3-6 on pr/8742), so its column is "no outbound change" unless noted. + +| id | area | CPA behaviour (file:line) | opencodex dev / #8742 behaviour (file:line) | status | notes / priority | +|---|---|---|---|---|---| +| V-01 | AI Studio endpoint | `https://generativelanguage.googleapis.com` + `/v1beta/models/{model}:{action}`; `base_url` attribute overrides host (internal/runtime/executor/gemini_executor.go:32,35,193,1121-1132) | `${provider.baseUrl}/v1beta/models/${routedModelId}:{method}` (src/adapters/google.ts:1309-1313); Go/Zen variants use Bearer (google.ts:1316-1322) | have | | +| V-02 | Stream transport | `:streamGenerateContent?alt=sse`, line scanner over `data:` frames; a caller `alt` becomes `?$alt=` (gemini_executor.go:357-362, 503-) | Always `?alt=sse` (google.ts:1143-1144); SSE parser with incomplete-frame and missing-terminal guards (google.ts:1595-1614) | have | Neither parses the non-SSE JSON-array stream outbound; both always request SSE. | +| V-03 | Vertex project endpoint | `{host}/v1/projects/{p}/locations/{l}/publishers/google/models/{m}:{action}`, `vertexAPIVersion="v1"` (gemini_vertex_executor.go:36,486,830) | Same shape, v1 (src/adapters/google-vertex-endpoint.ts:73-74) | have | | +| V-04 | Vertex host per location | `global`→`aiplatform.googleapis.com`; `us`/`eu`→`aiplatform.{us,eu}.rep.googleapis.com`; other→`{loc}-aiplatform.googleapis.com` (gemini_vertex_executor.go:1836-1844; test gemini_vertex_executor_test.go:519) | `global` or `{loc}-aiplatform.googleapis.com` only (google-vertex-endpoint.ts:73). `us`/`eu` pass the DNS-label check (src/providers/google-vertex-location.ts:7-13), so the request goes to `us-aiplatform.googleapis.com` | **gap** | P2. Multi-region config builds the wrong authority. Fix in `vertexInferenceUrl`, and give discovery the same rule. | +| V-05 | Vertex API-key (express) URL | `vertexAPIKeyModelsURL`: default `https://aiplatform.googleapis.com/v1/publishers/google/models/{m}:{a}`; honours a `base_url` that already has `/publishers/` or a `/v1*` suffix (gemini_vertex_executor.go:1798-1834; test :322) | Fixed authority `https://aiplatform.googleapis.com/v1/publishers/google/models/...` (google-vertex-endpoint.ts:68-69). Optional project mode, plus `project:"auto"` that resolves key→project from a countTokens 404 probe (src/adapters/google-vertex-key-project.ts:11-23,90-104; google.ts:1263-1273) | intentionally-different | opencodex pins the authority and has no Vertex `base_url`. CPA has no key→project resolution. | +| V-06 | Default location | Missing `location` → `global` (gemini_vertex_executor.go:1748-1752) | API key + project → `global` default; ADC requires `provider.location` or `GOOGLE_CLOUD_LOCATION`, otherwise it throws (google-vertex-endpoint.ts:30,36-39) | intentionally-different | P3. Consider defaulting ADC to `global` the way CPA does. | +| V-07 | AI Studio auth header | `x-goog-api-key`; deletes `Authorization` (gemini_executor.go:82-93,209) | `x-goog-api-key` (google.ts:1323) | have | | +| V-08 | Vertex auth | API key → `x-goog-api-key`; else service-account JSON → `google.CredentialsFromJSON(..., "https://www.googleapis.com/auth/cloud-platform")` → `Authorization: Bearer` (gemini_vertex_executor.go:196-218,1846-1863). No ADC or metadata server | API key, or an ADC chain: `gcp-sa:` keychain marker, `GOOGLE_APPLICATION_CREDENTIALS` (service_account JWT / authorized_user), gcloud ADC file, GCE metadata server (google.ts:1292-1302; src/lib/gcp-adc.ts:6-13,38-41,219,344) | have | opencodex is a superset. | +| V-09 | Token-exchange proxy | Token exchange uses the credential/global proxy, never the per-request proxy (gemini_vertex_executor.go:1846-1852; test vertex_proxy_token_test.go:22) | Not inspected | open question | See open questions. | +| V-10 | countTokens outbound | `:countTokens` on AI Studio and Vertex; strips `tools`, `generationConfig`, `safetySettings` (gemini_executor.go:996-1037, 1020-1022; gemini_vertex_executor.go:1510-1560,1623-1671) | No outbound countTokens. `/v1/messages/count_tokens` on non-Anthropic routes returns a local estimate (src/server/claude-messages.ts:1695-1713). #8742 inbound `:countTokens` → 501 UNIMPLEMENTED (pr/8742 src/server/gemini-inbound.ts:2-4) | gap | P3. Exact counts would help Claude Code compaction on Gemini routes. | +| V-11 | embedContent / batchEmbedContents | Not implemented in these executors (rg: no `embedContent`) | Not implemented; #8742 inbound answers 501 | n-a | | +| V-12 | Imagen on Vertex | Model names containing `imagen` → `:predict`; request/response converted to the Gemini shape (gemini_vertex_executor.go:41-56,61,115,422,567) | Imagen explicitly excluded (google.ts:699-700) | gap | P3. | +| V-13 | Vertex MaaS partner models | `publisher/model` ids other than `google/` → `.../endpoints/openapi` chat/completions with an SA token (gemini_vertex_executor.go:244,343-399; internal/runtime/executor/helps/vertex_openapi.go:20-40,502-527) | Vertex model id must be one path segment, so `/` is rejected (google-vertex-endpoint.ts:55-60) | gap | P3. Serves Llama/DeepSeek/Claude on Vertex. Could reuse the openai-chat adapter. | +| V-14 | Interactions API | Native `v1beta/interactions` (AI Studio) and `v1beta1/projects/{p}/locations/global/interactions` (Vertex) (gemini_executor.go:727-889; gemini_vertex_executor.go:1897-1911) | None | n-a | Separate protocol, outside this lane. | +| V-15 | systemInstruction | `systemInstruction:{role:"user",parts}` from chat system messages / Claude `system` / Responses `instructions` (internal/translator/gemini/openai/chat-completions/gemini_openai_request.go:297-300; gemini/claude/gemini_claude_request.go:70-79; gemini/openai/responses/gemini_openai-responses_request.go:74-78) | `body.systemInstruction` from `messagesToGeminiFormat` (google.ts:1087) | have | | +| V-16 | Turn-boundary guards | Leading user turn always, trailing user turn (gemini_executor.go:175-177); Vertex also drops a trailing thought-only model turn (gemini_vertex_executor.go:470) | Head `(continue)` only when turn 0 is a model functionCall; tail `(continue)` when the last turn is model (google.ts:606-621) | have | Different trigger with the same intent. | +| V-17 | generationConfig scalars | chat: `temperature`, `top_p`→`topP`, `top_k`→`topK`, `max_tokens`/`max_completion_tokens`→`maxOutputTokens`, `n`→`candidateCount` (gemini_openai_request.go:64-87); Responses `max_output_tokens` (responses_request.go:486-489). Chat `stop` and Claude `stop_sequences` not mapped (rg: no hits) | `maxOutputTokens` (clamped), `temperature`, `topP`, `stopSequences` (google.ts:1094-1099). The wire compiler whitelists only maxOutputTokens / temperature≤2 / topP≤1 / stopSequences≤5 / thinkingConfig / responseModalities / responseMimeType / responseJsonSchema (src/adapters/google-wire-compiler.ts:150-201) | gap (minor) | P3. `topK` is dropped. opencodex is ahead on stop sequences. Neither maps seed or penalties. | +| V-18 | maxOutputTokens cap | Clamps to registry `OutputTokenLimit` (gemini_executor.go:1292-1312; test gemini_executor_test.go:23-97) | `clampGoogleMaxOutputTokens` (google.ts:1095) | have | | +| V-19 | Structured output | `json_object`→`responseMimeType:"application/json"`; `json_schema`→ plus `responseJsonSchema` (gemini_openai_request.go:603-616) | Same, plus refusals for image models and schema-less json_schema (google.ts:1020-1047,1134-1139) | have | | +| V-20 | Image output config | chat `modalities`→`responseModalities` (upper-cased); `image_config.aspect_ratio/image_size`→`generationConfig.imageConfig` (gemini_openai_request.go:92-117); white-canvas workaround for gemini-2.5-flash-image-preview (gemini_executor.go:1314-1366) | `responseModalities:["TEXT","IMAGE"]` for image-capable models without thinkingConfig (google.ts:1123-1125); `imageConfig` is not whitelisted (google-wire-compiler.ts:185-201) | gap | P3. | +| V-21 | safetySettings | Attaches defaults when absent: HARASSMENT, HATE_SPEECH, SEXUALLY_EXPLICIT, DANGEROUS_CONTENT = `OFF`; CIVIC_INTEGRITY = `BLOCK_NONE` (gemini/common/safety.go:8-31,49-54; called at gemini_openai_request.go:535, gemini_claude_request.go:391, responses_request.go:529) | Never sends safetySettings; the compiler would drop them (google-wire-compiler.ts:220-249) | intentionally-different | P2 policy decision. Google's server defaults apply. Interacts with V-41/V-44 (more SAFETY stops). | +| V-22 | Tool declaration schema | `functionDeclarations[].parametersJsonSchema` (full JSON Schema) cleaned by `CleanJSONSchemaForGeminiJSONSchema`, which keeps `pattern`/`minLength`/`additionalProperties` (gemini_openai_request.go:364-391; internal/util/responses_tools.go:515-527; internal/util/gemini_schema.go:116-129) | `parameters` (OpenAPI subset) through a lossy sanitizer with loss report and `reject-lossy` policy; on a schema 400 it opens the schema to `{type:object,properties:{}}` and replays once (google.ts:627-637; google-wire-compiler.ts:84-104,220-249,281-330; src/adapters/google-tool-schema.ts:782-825) | intentionally-different | P2. `parametersJsonSchema` could remove most loss and repair traffic on AI Studio/Vertex. Needs per-endpoint evidence. | +| V-23 | Built-in tools / grounding | chat `google_search`/`code_execution`/`url_context` → `googleSearch`/`codeExecution`/`urlContext` (gemini_openai_request.go:411-440); Responses `web_search` → `{googleSearch:{includedDomains}}`, gated by model and tool_choice (responses_request.go:39-49; responses/gemini_openai-responses_web_search.go:18-92); sets `toolConfig.includeServerSideToolInvocations:true` when mixed with functions (gemini_openai_request.go:453-457; responses_request.go:68-71); `groundingMetadata` → `web_search_call` item and url citations (web_search.go:213-300) | Compiler keeps only `functionDeclarations` (google-wire-compiler.ts:84-104). Gemini web search exists only as a sidecar through Antigravity CCA (src/web-search/gemini-executor.ts:1-5; src/web-search/sidecar-providers.ts:73-86) | **gap** | P2. Native grounding on a user's own AI Studio/Vertex key is missing. | +| V-24 | tool_choice | `none`→`NONE`, `required`→`ANY`, named→`ANY` + `allowedFunctionNames`, `allowed_tools`, strict→`VALIDATED`, unknown→`NONE` fail-closed (gemini_openai_request.go:469-533; gemini_claude_request.go:315-346) | Equivalent; strict→`VALIDATED` only when choice is auto (google.ts:654-671) | have | | +| V-25 | functionCall / functionResponse history | chat: `functionCall{name,args}` + `thoughtSignature`, no `id`; responses for one assistant turn grouped into one user turn `{functionResponse:{name,response:{result}}}`; missing result → `"{}"` (gemini_openai_request.go:229-290). Claude/Responses set `functionCall.id`/`functionResponse.id` (gemini_claude_request.go:170-206; responses_request.go:869-870,1660,1732) | Always sends injective `functionCall.id` and `functionResponse.id`; groups parallel responses; missing result → `[missing tool_result ...]` placeholder; orphans as text (google.ts:326-366,505-537,560-594) | have | | +| V-26 | Vertex call-id stripping | Deletes `functionCall.id`/`functionResponse.id` on Vertex when the source is `openai-response` ("Vertex rejects", internal/runtime/executor/helps/vertex_payload_helpers.go:10-53; applied at gemini_vertex_executor.go:482-484) | Sends ids on Vertex too (google.ts:519-522) | open question | P2 to verify. opencodex ids are normalized to `[A-Za-z0-9_-]` (google.ts:205-223). CPA may be reacting to raw `fc_...`/`call_...` length or charset. | +| V-27 | Tool error result | Claude `is_error:true` → `functionResponse.response.error` (gemini_claude_request.go:201-207) | `isError` ignored; always `response.result` (google.ts:343-347; `isError` at src/types/request.ts:291) | gap | P3. Small fix. | +| V-28 | Tool-result images | Claude path nests as `functionResponse.parts[].inlineData` (gemini_claude_request.go:214-217) | Sibling `inline_data` parts; nested only for Vertex gemini-4-argon/carbon/hydrogen (google.ts:349-354,1077-1081) | intentionally-different | | +| V-29 | User media parts | Data URLs for `image_url`, `video_url`, `file` → `inlineData{mime_type,data}`; `input_audio` → `inlineData` with `audio/wav|mpeg|ogg|flac|aac`; a remote URL is dropped, and a turn left with no sendable part → 400 `UnsupportedPartError` (gemini_openai_request.go:161-190,577-590; internal/translator/common/parts.go:12-28) | Data URL → `inline_data`; documents → `inline_data`; remote image → text `[image: url]`; YouTube and Files API video → `file_data{file_uri}` + `media_processing` (google.ts:426-472,270-292). **Audio parts (`OcxAudioContent`, src/types/request.ts:349-365) have no Gemini branch and fall through to the text marker** (inferred from google.ts:420-472) | gap | P2 for audio; Gemini accepts audio `inlineData`. P3 for remote image text vs refusal. | +| V-30 | Responses `input_file` file URL | `file_url` → `fileData{mimeType,fileUri}` (responses_request.go:1302-1363,1773-1777) | Only video becomes `file_data` (google.ts:455-460) | gap | P3. | +| V-31 | thinkingConfig family | Per-model registry `thinking.levels` → `thinkingLevel`; else `thinkingBudget`; `auto` → `thinkingBudget:-1`; `none` clears config; user-defined models choose by request shape (internal/thinking/provider/gemini/apply.go:44-130; internal/thinking/convert.go:13,31,66-82) | Sends only `thinkingLevel`. Eligible only with a configured effort ladder, or gemini-3.5/3.6-flash on AI Studio; Vertex only with a ladder; `xhigh`→`high` when unladdered (google.ts:1057-1122). The compiler would pass a `thinkingBudget` (google-wire-compiler.ts:175-178), but the adapter never sets one. A thinking-config 400 drops thinkingConfig and replays (google-wire-compiler.ts:270-308) | **gap** | P2. No budget control for the gemini-2.5 family; a configured ladder there sends `thinkingLevel`, gets a 400, then repairs. | +| V-32 | includeThoughts | Derived from the client request: chat `reasoning_effort`≠none, Responses `reasoning.summary`, Claude `thinking.display`, `extra_body.google.thinking_config.include_thoughts`, native includeThoughts (internal/thinking/summary.go:60-128,254-270); the applier preserves it (provider/gemini/apply.go:85-113) | Only provider `showThinkingSummary===true` and not `hideThinkingSummary` (google.ts:1113-1121) | intentionally-different | P3. Honouring the Google `extra_body.google.thinking_config` passthrough is cheap. | +| V-33 | Thought parts in response | `thought:true` → `reasoning_content` (chat) / `thinking` block + `signature_delta` (Claude) (gemini_openai_response.go:306-335; gemini_claude_response.go:209-226,333-345) | `thinking_delta` or `reasoning_raw_delta` (google.ts:765-774) | have | | +| V-34 | Outbound thoughtSignature on functionCall | Reads `extra_content.google.thought_signature` / `thoughtSignature`, otherwise uses the sentinel (gemini_openai_request.go:563-575); non-Vertex sanitizer rejects bare Tink (internal/signature/gemini_sanitize.go:56-66); sentinel only on the first call of a synthetic turn (internal/signature/gemini_validation.go:19-25,84-85) | providerMetadata → legacy field → durable store at serialization (google.ts:527-537); `skip_thought_signature_validator` on the first unsigned functionCall per model turn (src/adapters/google-antigravity-replay.ts:642-643,691-704); Vertex replay cache (google.ts:1276-1290); clear-on-400 (google.ts:1004-1007) | have | | +| V-35 | Signature surfaced to client | chat `tool_calls[].extra_content.google.thought_signature` (gemini_openai_response.go:238,336,383,420,624,656) | `providerMetadata.google.thoughtSignature` → Responses `extra_content.google.thought_signature` (google.ts:751-758; src/responses/provider-opaque-metadata.ts:17,57-60) | have | | +| V-36 | Text-part / trailing signatures | Keeps signatures on visible text and trailing signature-only parts (gemini/openai/responses/trailing_signature.go; tests gemini_claude_response_test.go:869-1193, gemini_openai_response_test.go:582) | Captures a signature only from a `thought:true` part before a functionCall, or from the call part itself; text-part signatures are not carried (google.ts:1782-1810,751-758) | gap | P3. Google validates function-call signatures strictly, so this matters less. | +| V-37 | #8742 inbound → Gemini outbound signatures | n-a | pr/8742 `src/protocols/codecs/gemini.ts` has no `thoughtSignature` handling (rg). Missing ids become `call_gemini_${ci}_${pi}` (gemini.ts:218), which never match the outbound `call_xxxxxxxx` ids, so durable lookup misses (inferred) | **gap (#8742)** | P2. Gemini-native clients (agy, genai SDK) on a Gemini 3 route get the sentinel instead of a real signature on every turn. | +| V-38 | usage → OpenAI / Responses | `completion_tokens`/`output_tokens` = `candidatesTokenCount + thoughtsTokenCount`; `reasoning_tokens` = thoughts; `cached_tokens` = `cachedContentTokenCount`; `total_tokens` = `totalTokenCount` (gemini_openai_response.go:733-750; gemini_openai-responses_response.go:84-91; test gemini_openai_response_test.go:11-34) | `outputTokens` = `candidatesTokenCount` only; `reasoningOutputTokens` = thoughts; `totalTokenCount` ignored (google.ts:679-686). Pinned by tests/adapters/adapter-usage.test.ts:296-311 and tests/adapters/google/google-vertex-stream.test.ts:66-79. Responses `output_tokens` = `outputTokens` (src/bridge/internal.ts:84), so `reasoning_tokens` can exceed `output_tokens`; telemetry clamps reasoning to output, then subtracts it (src/telemetry/aggregate.ts:185-186). #8742 inbound assumes completion includes reasoning and subtracts again (pr/8742 gemini.ts:297-298) | **gap** | **P1**. Output is undercounted for every Gemini thinking turn, which affects cost and context accounting and the #8742 `candidatesTokenCount`. Fix: `outputTokens = candidates + thoughts`, and update the two pinned tests. | +| V-39 | usage → Claude | `input_tokens = prompt − cached`; `output_tokens = candidates + thoughts`; `cache_read_input_tokens = cached` (gemini_claude_response.go:646-653,722-735; test :429-516) | Input: `input − cached − cacheWrite` (src/claude/outbound.ts:209-221). Output: Responses `output_tokens`, which excludes thoughts (follows from V-38) | **gap** | P1. Same root cause and fix as V-38. | +| V-40 | finishReason → OpenAI / Responses | tool call → `tool_calls`; `MAX_TOKENS`→`length`; `SAFETY`/`RECITATION`/`BLOCKLIST`/`PROHIBITED_CONTENT`/`SPII`/`IMAGE_SAFETY`/`MALFORMED_RESPONSE`/`MALFORMED_FUNCTION_CALL`→`content_filter`; lower-cased `native_finish_reason` (gemini_openai_response.go:715-760). Responses: `response.incomplete` with `{reason:"max_output_tokens"}` or `{reason:"content_filter"}` (gemini_openai-responses_response.go:94-102) | `MAX_TOKENS`→`max_tokens`; `SAFETY`/`RECITATION`/`BLOCKLIST`/`PROHIBITED_CONTENT`/`SPII`→`content_filter`; everything else, including `IMAGE_SAFETY`, `MALFORMED_RESPONSE`, `UNEXPECTED_TOOL_CALL`, `LANGUAGE`, `OTHER`, is a clean `done` (google.ts:1616-1620,1836-1841) | **gap** | P2. Add `IMAGE_SAFETY` and `MALFORMED_RESPONSE` to the filter set; see V-42 for tool-call reasons. | +| V-41 | finishReason → Claude | `MAX_TOKENS`→`max_tokens`, filter set→`refusal`, tool→`tool_use`, else `end_turn`; `MALFORMED_FUNCTION_CALL` with no visible output → `event: error` api_error (gemini_claude_response.go:50-87; tests :517-866) | Through `stopReason` and the Messages encoder (inferred) | have (partial) | Shares V-40's reason set. | +| V-42 | Abnormal zero-output finish | `MALFORMED_FUNCTION_CALL`, `UNEXPECTED_TOOL_CALL`, or `MALFORMED_RESPONSE` with no visible output → 502 before the HTTP 200 is committed, on both AI Studio and Vertex (helps/gemini_zero_output.go:39-46,187-193,198-222; gemini_executor.go:263-270,484-501; tests gemini_executor_test.go:1445-1658) | Fail-closed only when `googleMode` is `vertex` or `cloud-code-assist` (google.ts:1606-1610,1820-1830; src/adapters/google-truncation.ts:6,23-25). **AI Studio `MALFORMED_FUNCTION_CALL` yields a clean empty `done`.** `UNEXPECTED_TOOL_CALL` and `MALFORMED_RESPONSE` are not handled in any mode | **gap** | **P1**. A silent empty success on the most common Gemini direct route. Drop the googleMode gate and extend `TRUNCATION_REASONS`. | +| V-43 | Prompt blocked | No candidates + `promptFeedback.blockReason` → 502 `upstream blocked the prompt: - ` (gemini_executor.go:274-279,681-701; stream :545-554; tests gemini_executor_test.go:1659, gemini_vertex_executor_test.go:416); a mid-stream filter block with no finish → 400 (gemini_executor.go:555-559,595-605) | Non-stream: `google response contained no candidates` (google.ts:1748-1749). Stream: a promptFeedback-only frame ends as `upstream stream ended without a terminal signal — possible truncation` (google.ts:1612-1613). `promptFeedback` is parsed only in src/server/images.ts:430-439 | **gap** | P2. The message is misleading. If "possible truncation" is retried or failed over, a deterministic block is resent (inferred). | +| V-44 | Stream closed without finishReason | 502 `upstream stream closed before finishReason` (`streamTruncated`) for Claude/OpenAI output (gemini_executor.go:643-653; test :1870) | Error event `ended without a terminal signal` (google.ts:1612-1614) | have | | +| V-45 | Vertex streamed function arguments | Assembles `functionCall.partialArgs[{jsonPath,...}]` + `willContinue` into valid JSON deltas (internal/translator/common/vertex_partial_args.go:75-211; gemini_claude_response.go:63; tests vertex_partial_args_test.go:10-180, gemini_openai_response_test.go:353). Does not request `streamFunctionCallArguments` itself (rg: none) | Never requests it; the compiler would drop it (google-wire-compiler.ts:203-215); a partial functionCall would be read as a whole call (inferred) | n-a | P3. Only relevant if opencodex opts in later. | +| V-46 | HTTP errors and retries | Upstream status and raw body passed through as `statusErr`; no retry inside the executor; `RetryInfo.retryDelay` parsed only on Antigravity paths (gemini_executor.go:243-255; helps/json_retry_helpers.go:35-87, callers antigravity_executor_*.go) | Retries 429/500/502/503/504 with jittered backoff and `Retry-After` (including from `RetryInfo`); a quota-exhausted 429 is not retried; classified and sanitized messages (src/adapters/google-http.ts:70-198,209-230; src/adapters/google-errors.ts:72-160) | have | opencodex is a superset. | +| V-47 | INVALID_ARGUMENT repair | None | One changed replay for schema or thinking 400s (google-wire-compiler.ts:265-330) | have | opencodex extra. | +| V-48 | Model list | Static embedded catalog refreshed from `router-for-me/models`, with per-model `thinking{min,max,dynamic_allowed,levels}` (internal/registry/model_definitions.go:52-64; model_updater.go:19-24; models/models.json:635-672) | Live discovery. AI Studio: `GET /v1beta/models?pageSize=1000`, filtered to `generateContent`, maps `inputTokenLimit`/`outputTokenLimit` (src/oauth/index.ts:1244; src/providers/google-ai-studio-model-discovery.ts:27-73). Vertex: `GET /v1beta1/publishers/google/models?pageSize=300` with `pageToken` (src/providers/google-vertex-model-discovery.ts:259-285,393). Thinking capability is not mapped | intentionally-different | P3. Mapping AI Studio's `thinking` flag would feed V-31. | +| V-49 | #8742 models list/get | n-a (outbound) | Inbound only: eligible routes as `models//` (pr/8742 src/server/gemini-inbound.ts:66-78) | n-a | | + +## Highest-value gaps (ranked) + +1. **V-38/V-39 (P1). Gemini output tokens leave out thinking.** `usageFromGemini` sets `outputTokens = candidatesTokenCount` (src/adapters/google.ts:682-685), while every other adapter and the Responses, Claude, and telemetry layers treat output as including reasoning. Results: Responses `reasoning_tokens` can exceed `output_tokens`, Claude `output_tokens` comes out low, telemetry subtracts reasoning from an output that never contained it, and #8742's inbound `candidatesTokenCount` is undercounted twice. CPA adds candidates and thoughts (gemini_openai_response.go:735). The fix is one line plus updates to the two pinned tests. +2. **V-42 (P1). AI Studio silently succeeds on `MALFORMED_FUNCTION_CALL`.** The fail-closed truncation check is gated to vertex and CCA (google.ts:1606-1610,1820-1830). Add `UNEXPECTED_TOOL_CALL` and `MALFORMED_RESPONSE` the way CPA's zero-output guard does (helps/gemini_zero_output.go:39-46). +3. **V-43 + V-40 (P2). Prompt blocks and unmapped finish reasons.** Parse `promptFeedback.blockReason`/`blockReasonMessage` into a typed, non-retryable error, and map `IMAGE_SAFETY` and `MALFORMED_RESPONSE` to `content_filter`. +4. **V-31 (P2). No `thinkingBudget` path for the gemini-2.5 family.** Choose level or budget per model family, as CPA's registry-driven applier does (provider/gemini/apply.go:58-68). +5. **V-04 (P2). Vertex `us`/`eu` multi-region host** must be `aiplatform.{us,eu}.rep.googleapis.com`. +6. **V-29 (P2). Audio input to Gemini is sent as a text marker** although Gemini accepts audio `inlineData`. +7. **V-23 (P2). Native `googleSearch` grounding on AI Studio/Vertex keys,** with `includeServerSideToolInvocations` and a `groundingMetadata` → `web_search_call`/citations mapping. +8. **V-37 (P2, #8742). The Gemini inbound codec drops `thoughtSignature`** both ways, so native Gemini clients on Gemini 3 routes always run on the sentinel. +9. **V-22 (P2). Evaluate `parametersJsonSchema`** to cut schema loss and repair replays. **V-26:** check whether Vertex rejects opencodex's normalized call ids. +10. **P3 batch.** countTokens passthrough (V-10), `is_error`→`response.error` (V-27), `topK` (V-17), `imageConfig` (V-20), Responses `input_file` URIs (V-30), Imagen (V-12), Vertex MaaS openapi (V-13), includeThoughts from `extra_body.google` (V-32). + +## Test fixtures worth copying (CPA test file:line) + +- internal/translator/gemini/openai/chat-completions/gemini_openai_response_test.go:11, :25: completion tokens include thoughts (stream and non-stream). Use as the V-38 regression. +- internal/translator/gemini/claude/gemini_claude_response_test.go:429, :481: Claude usage with `cachedContentTokenCount` (input = prompt − cached). +- internal/runtime/executor/gemini_executor_test.go:1445, :1525, :1590: `MALFORMED_FUNCTION_CALL` becomes a retryable error, with split usage and cancel-after-error (V-42). +- internal/runtime/executor/helps/gemini_zero_output_test.go:9, :116: zero-output payload inspection and shell-frame buffering. +- internal/runtime/executor/gemini_executor_test.go:1659 and gemini_vertex_executor_test.go:416: promptFeedback block without candidates (V-43). +- internal/runtime/executor/gemini_executor_test.go:1870: stream truncation before finishReason (V-44). +- internal/translator/gemini/openai/chat-completions/gemini_openai_response_test.go:162: non-STOP finish reasons map to `content_filter` (V-40). +- internal/runtime/executor/gemini_vertex_executor_test.go:519 (`TestVertexBaseURL`, us/eu rep hosts) and :322 (`TestVertexAPIKeyModelsURL`) (V-04/V-05). +- internal/translator/gemini/openai/responses/gemini_openai-responses_web_search_test.go:63, :102, :127, :148, :234, :355, :486: googleSearch gating, includedDomains, grounding → web_search_call, citation offsets (V-23). +- internal/translator/common/vertex_partial_args_test.go:10-180: partialArgs assembly, if V-45 is ever enabled. +- internal/runtime/executor/gemini_executor_signature_test.go:176, :240, :305, :553: sentinel replacement, native signature preserved, unsigned request untouched (V-34 cross-check). +- internal/translator/gemini/claude/gemini_claude_response_test.go:869-1193 (Issue6409): signed visible text and trailing signature parts (V-36). +- internal/translator/gemini/openai/chat-completions/gemini_openai_media_url_test.go:24, :49: refusing an attachment-only turn it cannot send (V-29 policy). + +## Open questions + +1. V-26: does Vertex actually reject `functionCall.id`/`functionResponse.id`, or only CPA's raw Responses ids? opencodex sends normalized ids on Vertex today and has no reported failure in the code comments I read. A live Vertex probe is needed (NOT RUN). +2. V-21: should opencodex send `safetySettings` defaults? It is a product and policy call. Current Google server defaults for gemini-2.5+/3 were not verified in this lane (NOT RUN). +3. V-09: does opencodex's ADC token exchange (src/lib/gcp-adc.ts:38-41) go through the same proxy as inference, and should it? Not inspected. +4. V-43: does the router retry or fail over on the stream error "ended without a terminal signal — possible truncation"? If it does, a prompt block is resent to every credential. Not traced. +5. V-38: was the candidates-only `outputTokens` deliberate, for example to match Google's billing display? The pinned tests carry no rationale. Confirm before changing. +6. V-37: should #8742's codec carry `thoughtSignature` (and Gemini `functionCall.id`) through Chat `extra_content.google.thought_signature`, which opencodex Responses already understands (src/responses/provider-opaque-metadata.ts:17)? diff --git a/devlog/_plan/261115_google_protocol_cpa_parity/010_phase1_interactions_inbound.md b/devlog/_plan/261115_google_protocol_cpa_parity/010_phase1_interactions_inbound.md new file mode 100644 index 00000000000..29c32f0fb92 --- /dev/null +++ b/devlog/_plan/261115_google_protocol_cpa_parity/010_phase1_interactions_inbound.md @@ -0,0 +1,230 @@ +# 010 — Phase 1: Gemini Interactions API inbound (stateless) + +Status: implemented in cycle 2 (see "As built" at the end). + +Rows: INT-01..12, INT-18, INT-19 ([001](001_parity_matrix.md)). Class C4: a new public wire surface. +Depends on the #8742 merge (it reuses `gemini-native-paths.ts`, `gemini-inbound.ts`'s error body, +`native-chat-bridge.ts` and `native-final-log`). `previous_interaction_id` answers 400 in this phase; +phase 020 replaces that with the store. + +## Stale check before B + +Re-read on the merged tree: `src/server/gemini-native-paths.ts`, `src/server/index/gemini-routes.ts`, +`src/server/gemini-inbound.ts` (exports `geminiError`, `geminiErrorBody`, `toGeminiRefusal`), +`src/server/native-chat-bridge.ts` (`internalChatRequest`, `streamNativeFromChat`, +`drainedInnerErrorMessage`, `commitCancelled`), `src/server/ollama-route-policy.ts` +(`preflightOllamaRoute`), `src/server/inbound-body-admission.ts` (`isGeminiGenerationPath`), the +loopback allowlist and management denial in `src/server/index.ts` (both keyed on `parseGeminiNativePath`), +and `tests/fixtures/file-size-baseline.json` for every file below. Capture the stable-version reference +(`https://ai.google.dev/api/interactions-api.md.txt?api-version=v1` through Aside) and keep +`/v1/interactions` only if the fields this codec reads are identical there; otherwise drop INT-19 to defer. + +## Changes + +### MODIFY `src/server/gemini-native-paths.ts` + +Add Interactions routes to the same classifier, so the package-tree fence, loopback allowlist, +management denial and raised-body admission all pick them up through the existing callers. + +```diff +-export type GeminiNativeRoute = +- | { kind: "models"; httpMethod: "GET" } +- | { kind: "model"; httpMethod: "GET"; model: string } +- | { kind: "method"; httpMethod: "POST"; model: string; method: GeminiMethod }; ++export type GeminiNativeRoute = ++ | { kind: "models"; httpMethod: "GET" } ++ | { kind: "model"; httpMethod: "GET"; model: string } ++ | { kind: "method"; httpMethod: "POST"; model: string; method: GeminiMethod } ++ | { kind: "interactions"; httpMethod: "POST" }; +@@ export function parseGeminiNativePath(pathname: string): GeminiNativeRoute | undefined { ++ if (pathname === "/v1beta/interactions" || pathname === "/v1/interactions") return { kind: "interactions", httpMethod: "POST" }; + const beta = pathname.startsWith("/v1beta/models"); +@@ export function isGeminiGenerationPath(pathname: string): boolean { + const route = parseGeminiNativePath(pathname); +- return route?.kind === "method" && (route.method === "generateContent" || route.method === "streamGenerateContent"); ++ return route?.kind === "interactions" ++ || (route?.kind === "method" && (route.method === "generateContent" || route.method === "streamGenerateContent")); + } +``` + +Phase 020 extends the union with the by-id routes. `/v1/interactions` is the stable-version path +(002); `rg '/v1/interactions' src` is empty on d842c1352e, so it collides with nothing. + +### NEW `src/protocols/codecs/gemini-interactions.ts` (pure, no server imports) + +```ts +export class InteractionsCodecError extends Error { readonly status = 400; readonly code = "invalid_interactions_request"; } +export interface InteractionsRequestPlan { + model: string; // after stripping a leading "models/" + stream: boolean; + store: boolean; // default true (Google default) + previousInteractionId?: string; // phase 1: presence is a 400 from the handler + unmatchedResultIds: string[]; // function_result call_ids with no function_call in this input + chat: Record; // the internal Chat Completions body +} +export function interactionsToChat(input: unknown): InteractionsRequestPlan; +export function chatToInteraction(meta: InteractionMeta, chatResponse: unknown): Record; +export interface InteractionMeta { id: string; model: string; created: string } +export function createInteractionsStreamState(meta: InteractionMeta): InteractionsStreamState; +export function interactionsStreamStart(state): InteractionsSseEvent[]; // interaction.created +export function consumeInteractionsChatChunk(state, parsedChunk: unknown): InteractionsSseEvent[]; +export function interactionsStreamTerminal(state): InteractionsSseEvent[] | undefined; // step.stop(s) + interaction.completed +export function interactionsErrorEvent(code: number, message: string): InteractionsSseEvent; +export type InteractionsSseEvent = { event: string; data: Record }; +``` + +Request mapping (Interactions → Chat). Unknown top-level fields are ignored, as in #8742. + +| Interactions | Chat | Notes | +| --- | --- | --- | +| `model` (string, required unless `agent`) | `model` | `models/x` → `x`; empty → 400 | +| `agent` | — | 400 `agent interactions require a native Interactions upstream`; both or neither of model/agent → 400 `request requires exactly one of model or agent` (A-I02) | +| `stream` | `stream` (+ `stream_options.include_usage:true`) | non-boolean → 400 `stream must be a boolean` (A-I03) | +| `background: true` | — | 400 | +| `store` | — | boolean or absent; recorded on the plan | +| `previous_interaction_id` | — | string; recorded on the plan | +| `system_instruction` string, `{text}`, or `{parts:[{text}]}` | leading `system` message | other shapes 400 | +| `input` string | one `user` message | | +| `input` content object or content array (`{type:"text",text}`, `{type:"image",data,mime_type}`) | one `user` message (string when text-only, parts when an image is present) | image needs base64 `data` and an `image/*` `mime_type`; `uri`, audio, video, document → 400 `unsupported content type` | +| `input` step array, or turn objects `{role,content}` | messages in order | see step table | +| `tools[]` `{type:"function",name,description?,parameters?}` | `tools[]` function entries | schema types lower-cased with #8742's `normalizeSchema` rule (depth 64); any other `type` → 400 `unsupported tool type` (D3) | +| `generation_config.temperature/top_p/seed/stop_sequences` | `temperature/top_p/seed/stop` | finite numbers / safe integers / string array | +| `generation_config.max_output_tokens` | `max_tokens` | positive safe integer | +| `generation_config.thinking_level` | `reasoning_effort` | `minimal|low|medium|high|xhigh` | +| `generation_config.thinking_summaries: "auto"` | `include_reasoning: true` | `none` → omitted | +| `generation_config.tool_choice` (or top-level `tool_choice`) | `tool_choice` | `auto`/`validated` → omitted (auto), `any` → `required`, `none` → `none`, `{allowed_tools:{mode,tools}}` → `{type:"allowed_tools",allowed_tools:{mode:auto|required,tools:[{type:"function",function:{name}}]}}` (#8742 `toolChoice` semantics) | +| `response_format` `{type:"text",mime_type:"application/json",schema?}` (object or one-element array) | `response_format` `json_schema` / `json_object` | `type` image/audio/video → 400 (D3) | +| `response_modalities` other than `["TEXT"]` / `["text"]` | — | 400 (CPA-derived field, absent from the current reference; non-text output is refused through `response_format` above) | + +Steps → messages: + +| step | Chat | +| --- | --- | +| `user_input{content[]}` / `{role:"user",content}` | `user` message (content table above) | +| `model_output{content[]}` / `{role:"model",content}` | `assistant` text, merged with following `function_call` steps into one assistant message | +| `thought{signature?,summary?}` | not conversation text; a `signature` is held and attached to the next `function_call` as `extra_content.google.thought_signature` (consumed once CW-01 lands in 030) | +| `function_call{id,name,arguments}` | assistant `tool_calls[]` entry, `arguments` JSON-stringified (object required) | +| `function_result{call_id,name?,result,is_error?}` | `tool` message, `tool_call_id: call_id`; `result` string as is, object → `JSON.stringify`, text-content array joined, image content → 400; `is_error: true` wraps the text as `{"error": }` (the Gemini functionResponse convention). A `call_id` with no matching `function_call` in this input is **not** a codec error: it is returned in `plan.unmatchedResultIds` (Google's chained tool flow sends only the result plus `previous_interaction_id`, function-calling guide). The handler answers 400 `unmatched function_result` for ids still unmatched after history is applied (phase 1: no history, so any unmatched id is 400) | +| `developer`/`system` role turn | `system` message | +| any other step type | 400 `unsupported step type: ` | + +Limits copied from #8742: at most 1,024 function calls, schema depth 64. + +Response mapping (Chat → Interaction), buffered: + +```json +{ "id": "", "status": "", "created": "", "updated": "", "model": "", + "steps": [ + { "type": "thought", "summary": [{ "type": "text", "text": "" }] }, + { "type": "model_output", "content": [{ "type": "text", "text": "" }] }, + { "type": "function_call", "id": "", "name": "", "arguments": { } } + ], + "usage": { "total_input_tokens": 5, "total_cached_tokens": 0, "total_output_tokens": 2, "total_thought_tokens": 0, "total_tokens": 7 } } +``` + +- `status` from `finish_reason`: `tool_calls`/`function_call` → `requires_action`, `length` and + `content_filter` → `incomplete`, `stop` → `completed`; anything else → 502 (as #8742 refuses an + unknown finish). (INT-12; CPA reports `completed` for tool turns.) `content_filter` maps to + `incomplete` because the reference defines it as "completed, but contains incomplete results" and a + filtered answer is exactly that: the turn ended and its partial text is valid; `failed` is kept for + turns with no usable result (proxy or upstream errors). +- `usage`: `total_input_tokens = prompt_tokens`, `total_cached_tokens = prompt_tokens_details.cached_tokens`, + `total_thought_tokens = completion_tokens_details.reasoning_tokens`, + `total_output_tokens = max(0, completion_tokens − thought)`, `total_tokens = prompt + completion` (D4). + On Google routes this is exact only after 050 (D5), because Google completion counts exclude + thoughts until then; the clamp keeps it non-negative meanwhile. +- A thought signature on a Chat tool call (`extra_content.google.thought_signature`, emitted once CW-01 + lands) becomes `thought.signature` on a thought step placed before that call. +- `id`: `ocx-int-` + 32 lowercase hex chars from `crypto.getRandomValues(new Uint8Array(16))` (128 random + bits; `randomUUID` carries only 122); `created` = `updated` = ISO second precision. + +Streaming events, each framed `event: \ndata: \n\n` and each `data` carrying +`event_type` (002): + +1. `interaction.created` `{interaction:{id,status:"in_progress",model,created,updated}}` — first frame. + #8742's `NativeStreamTranslator` has no start hook, so the codec emits it lazily: the first `chunk()` + call prepends it, and `failure()` / the terminal frames prepend it when no chunk produced it. No #8742 + file changes for this. +2. reasoning delta → `step.start {index:n, step:{type:"thought"}}` once, then + `step.delta {index:n, delta:{type:"thought_summary", content:{type:"text",text}}}`. +3. content delta → close an open thought step (`step.stop {index:n}`), `step.start {index:n+1, + step:{type:"model_output"}}` once, then `step.delta {delta:{type:"text",text}}`. +4. tool calls accumulate as in #8742 and are emitted at `finish_reason`: per call + `step.start {step:{type:"function_call",id,name,arguments:{}}}`, + `step.delta {delta:{type:"arguments_delta",arguments:""}}`, `step.stop`; a signature becomes + `step.delta {delta:{type:"thought_signature",signature}}` on a preceding thought step. +5. terminal (only after Chat EOF and settlement, via `streamNativeFromChat`): close the open step, then + `interaction.completed {interaction:{id,status,model,created,updated,usage}}`. +6. failure after commit: `event: error`, `{event_type:"error", error:{code:"",message}}`. + +### NEW `src/server/gemini-interactions-inbound.ts` + +`handleGeminiInteraction(req, config, logCtx, ids): Promise` mirrors +`handleGeminiGeneration` step for step: read the JSON body under `resolveInboundBodyLimitBytes` and a +translator budget; `interactionsToChat`; 400 for `previous_interaction_id` (phase 1 only: +`previous_interaction_id is not supported`); `preflightOllamaRoute(config, plan.model, req)`; 413 when the +Chat JSON exceeds the limit; `handleChatCompletions(internalChatRequest(...), config, logCtx, {...ids, +suppressProtocolTrace:true})`; buffered → `chatToInteraction`; streamed → +`streamNativeFromChat` with SSE framing and `content-type: text/event-stream`. Errors use +`geminiError` (Google `{error:{code,message,status}}`, fixed text) so both Gemini surfaces share one +error vocabulary (INT-18). + +### MODIFY `src/server/index/gemini-routes.ts` + +```diff +- const generation = route.kind === "method" && (route.method === "generateContent" || route.method === "streamGenerateContent"); ++ const interaction = route.kind === "interactions"; ++ const generation = interaction || (route.kind === "method" && (route.method === "generateContent" || route.method === "streamGenerateContent")); +@@ +- await handleGeminiGeneration(method, route.model, sse, sessionReq, config, logCtx, { requestId, start, turnAdmissionLease, admission, advisorAdmissionPolicy }), ++ interaction ++ ? await handleGeminiInteraction(sessionReq, config, logCtx, { requestId, start, turnAdmissionLease, admission, advisorAdmissionPolicy }) ++ : await handleGeminiGeneration(method, route.model, sse, sessionReq, config, logCtx, { requestId, start, turnAdmissionLease, admission, advisorAdmissionPolicy }), +``` + +The `route.method` cast moves inside the non-interaction branch. + +## Tests (written first, must fail before the change) + +- NEW `tests/responses/responses-gemini-interactions-codec.test.ts` (domain `responses`): string input; + content array with an image; step history with `function_call`/`function_result` and a held thought + signature; `system_instruction` forms; generation_config mapping incl. `thinking_level`, + `thinking_summaries`, `tool_choice` (string and `allowed_tools`); `response_format`; every 400 in the + tables (agent, both model+agent, non-boolean stream, background, hosted tool, unsupported step, + unmatched result, image uri); buffered response for stop / tool_calls / length with usage names; the + stream event sequence for text, reasoning-then-text, and tool calls; terminal refused before finish. +- NEW `tests/server/server-gemini-interactions-inbound.test.ts` (domain `server`, harness copied from + `server-gemini-inbound.test.ts`): buffered and streamed create on `/v1beta/interactions` and + `/v1/interactions`; `x-goog-api-key` admission and 401 without it on a public bind; 405 for GET; + upstream 400 → Google error body with fixed text; `previous_interaction_id` → 400; one request-log row. +- Register both in `scripts/test-layout/layout-server-inbound.json` and + `tests/fixtures/test-layout-expected.json` (the shard `tests/test-layout-tooling.test.ts` names). + +## Docs + +- `structure/data-planes/gemini-inbound.md`: new "Interactions" section (routes, mapping summary, D3 + refusals, events, usage names, coverage list) and ownership of the two new source files in + `structure/manifest.json`, then `bun run structure:index`. +- `docs-site` integrations guide (070). + +## Verify + +`bun test tests/responses/responses-gemini-interactions-codec.test.ts tests/server/server-gemini-interactions-inbound.test.ts tests/server/server-gemini-inbound.test.ts tests/responses/responses-gemini-codec.test.ts`, +then the per-phase floor in [000](000_plan.md). + + + +## As built (cycle 2, after the focused audit `.tmp/research/audit-010.md`, NEAR-PASS) + +- The classifier owns `/v1beta|v1/interactions/{id}` (GET, DELETE → Google 404 `interaction not found`) + and `…/{id}/cancel` (POST → 501) in this phase, so the commit stands alone; `geminiRouteAllows` and + `geminiRouteAllowHeader` moved here from 020. The loopback allowlist line in `src/server/index.ts` + calls `geminiRouteAllows` (net zero lines, 882/893). +- `normalizeSchema` is exported from `src/protocols/codecs/gemini.ts` and wrapped so its error is this + codec's 400. `stream_options.include_usage` is not added: the Chat path puts usage on the finish frame. +- `any` with one allowed function forces that function, as in the generateContent codec; `text/plain` and + a bare `{type:"text"}` format are omitted; `webhook_config`, `environment` and `agent_config` are 400; + `service_tier` and `safety_settings` are ignored. Bodies and stream interactions carry + `object: "interaction"`. Check order: codec 400s, then `previous_interaction_id`, then unmatched results. +- Listener-level coverage is at the classifier (`tests/server/gemini-native-paths.test.ts`) plus the + source oracle in `tests/server/loopback-listener-admission.test.ts`, the way #8742 pins its routes. diff --git a/devlog/_plan/261115_google_protocol_cpa_parity/020_phase2_interactions_state.md b/devlog/_plan/261115_google_protocol_cpa_parity/020_phase2_interactions_state.md new file mode 100644 index 00000000000..0448b644bae --- /dev/null +++ b/devlog/_plan/261115_google_protocol_cpa_parity/020_phase2_interactions_state.md @@ -0,0 +1,154 @@ +# 020 — Phase 2: Interactions state (`previous_interaction_id`, get, delete) + +Status: implemented in cycle 3 (see "As built" at the end). + +Rows: INT-13, INT-14, INT-15. Class C4: new caller state with an ownership rule. Depends on 010. + +## Design (decision D2) + +CPA keeps no local state: it forwards `previous_interaction_id` to a native Interactions upstream and +drops it for every translated target (A-I14). opencodex translates every Interactions request onto Chat, +so without local state a chained turn would silently lose its history. This phase adds a store with these +rules: + +- **Process-local memory only.** Nothing is written to disk or the request log; a restart forgets + every interaction (stored interactions then answer 404, and the client resends history). +- **Owner-scoped.** The owner key is `contextPrincipalIdOf(admission)` (`src/server/auth-cors.ts:549`, + a salted HMAC of the matched data-plane secret). Loopback admission has no principal, so loopback + callers share the single owner `"loopback"`; that matches the trust model of the unauthenticated + loopback listener. Admission without either is not stored. A lookup with a different owner is + indistinguishable from a missing id (404). +- **Unguessable ids.** `ocx-int-` + 128 random bits from `crypto.getRandomValues` (010). +- **Bounded.** TTL 24 hours from the last write (same span as `RESPONSE_TTL_MS` in + `src/responses/state.ts:71`), at most 1,000 entries and 64 MiB in total, and per owner at most 200 + entries and 16 MiB, so one key's traffic cannot evict another owner's conversations; 8 MiB per entry + (serialized history). Eviction removes only the writing owner's own oldest entries; when the store is full and + the writer owns nothing to evict, the new interaction is not kept (CodeRabbit round on #8771; the original + "then the globally oldest" fallback broke the isolation guarantee). Only the app-owned memory budget evicts + across owners. + An entry that cannot be stored (over the per-entry cap) still returns its answer, with the response + header `x-opencodex-interaction-stored: false` so a client can tell a later chain will 404. +- **Memory budget.** The store registers with `registerRetainedStore` (`src/lib/app-owned-memory.ts:100`) + like the Responses continuation store, so the shared app-owned budget can evict it. +- **What is stored**: the Chat history needed to continue (prior history without system messages, the + new input messages, and the assistant message with text, tool calls and their + `extra_content.google.thought_signature`), plus the Interaction resource for GET (steps including + `user_input`, status, usage, model, timestamps). +- **Interaction-scoped fields are not inherited** (002 "Server-side state management"): + `system_instruction`, `tools`, `generation_config` come only from the current request. +- **`store:false`**: the turn is served and not stored; a later `previous_interaction_id` naming it is 404. + +## Stale check before B + +`src/lib/app-owned-memory.ts:100` (`registerRetainedStore` signature, as used for +`responseContinuationRetainedStoreSnapshot` in `src/responses/state.ts:1002`); the 010 handler and codec as merged; the loopback allowlist in +`src/server/index.ts` that keys on `parseGeminiNativePath`. + +## Changes + +### NEW `src/server/gemini-interactions-store.ts` + +```ts +export const INTERACTION_TTL_MS = 24 * 60 * 60 * 1_000; +export const MAX_STORED_INTERACTIONS = 1_000; +export const MAX_INTERACTION_BYTES = 8 * 1024 * 1024; +export const MAX_INTERACTION_STORE_BYTES = 64 * 1024 * 1024; +export interface StoredInteraction { + id: string; owner: string; model: string; created: string; updated: string; status: string; + history: Record[]; // Chat messages, no system role + resource: Record; // GET body: steps incl. user_input, usage + bytes: number; expiresAt: number; +} +export function interactionOwner(admission: DataPlaneAdmission): string | undefined; // principal | "loopback" | undefined +export function rememberInteraction(entry: Omit, now?: number): boolean; +export function recallInteraction(id: string, owner: string | undefined, now?: number): StoredInteraction | undefined; +export function forgetInteraction(id: string, owner: string | undefined): boolean; +export function clearInteractionsForTests(): void; +``` + +A `Map` in insertion order plus per-owner counters; `rememberInteraction` deletes then re-inserts, +sweeps expired entries, evicts the owner's oldest until the per-owner caps hold, then the globally +oldest until the global caps hold. Registered with `registerRetainedStore`. + +### MODIFY `src/protocols/codecs/gemini-interactions.ts` + +- `interactionsToChat` returns `inputMessages` and `systemMessages` separately on the plan so the + handler can splice stored history between them. +- NEW `interactionsStreamAssistant(state)` / `chatResponseAssistant(chatResponse)`: the assistant + message to store (content, tool_calls with signatures). +- NEW `interactionInputSteps(plan)`: `user_input`/`function_result` steps for the GET resource. + +### MODIFY `src/server/gemini-native-paths.ts` + +```diff ++ | { kind: "interaction"; httpMethod: "GET"; allow: readonly ["GET", "DELETE"]; id: string } ++ | { kind: "interaction-cancel"; httpMethod: "POST"; id: string }; ++/** Whether `method` is served on the route (by-id routes answer GET and DELETE). */ ++export function geminiRouteAllows(route: GeminiNativeRoute, method: string): boolean { ++ return "allow" in route ? (route.allow as readonly string[]).includes(method) : method === route.httpMethod; ++} +``` + +Paths: `/v1beta/interactions/{id}` and `/v1/interactions/{id}` (id = one URL-decoded segment matching +`^[A-Za-z0-9_-]{1,128}$`, else not a native path), and `…/{id}/cancel`. `isGeminiGenerationPath` stays +true only for create. Callers that compare `req.method === route.httpMethod` (`src/server/index.ts` +loopback allowlist, `src/server/index/gemini-routes.ts` 405 check) switch to `geminiRouteAllows`, and +the 405 `Allow` header lists `allow.join(", ")` when present. + +### MODIFY `src/server/gemini-interactions-inbound.ts` + +- Remove the phase-1 400 for `previous_interaction_id`. When present: `recallInteraction(id, owner)`; + missing → 404 `interaction not found`; otherwise `messages = [...systemMessages, ...stored.history, + ...inputMessages]`. Then resolve `plan.unmatchedResultIds` against the tool calls in + `stored.history`; only ids still unmatched are 400 `unmatched function_result`. +- After a successful terminal, when `plan.store` and an owner exist, `rememberInteraction`. Buffered: + after `finalLog.waitForInner()` reports settled and before the 200 is returned. Streamed: inside the + `frames()` closure returned by `terminal()`, never in `terminal()` itself — #8742's bridge evaluates + `terminal()` "before settlement is known" and calls `frames()` only on success + (`native-chat-bridge.ts`, `NativeStreamTranslator`). A failed, cancelled or unsettled turn is not stored. + The `x-opencodex-interaction-stored` header is buffered-only (stream headers are sent first). +- NEW `handleGeminiInteractionResource(method, id, admission)`: GET → `stored.resource` or 404; + DELETE → `{}` 200 or 404. NEW cancel handler: 404 when unknown, else 400 `only background interactions + can be cancelled` (INT-15). + +### MODIFY `src/server/index/gemini-routes.ts` + +By-id and cancel routes take data-plane admission without a turn lease (`resolveResponsesApiAuth`, +origin check), never forward anything upstream, and write no request-log row. + +## Tests (first, failing) + +- NEW `tests/server/gemini-interactions-store.test.ts` (domain `server`): owner isolation (other + principal → undefined), loopback owner, TTL with an injected clock, per-entry cap refusal, total-cap + eviction order, delete. +- EXTEND `tests/server/server-gemini-interactions-inbound.test.ts`: two-turn chain (the second upstream + Chat body contains turn-1 user text, assistant answer and the new input, and the turn-2 + `system_instruction` only); chain after a tool turn carries the call and the `function_result`; + a chained request whose input is only a `function_result` (no repeated `function_call`) succeeds; + a stream whose Chat EOF arrives but settlement fails stores nothing; per-owner eviction leaves another + owner's entries intact; + `store:false` turn → later chain 404; GET returns `user_input` + output steps; DELETE then GET 404; + a different data key → 404 on GET and chain; cancel → 400 / 404; GET wrong method → 405 with + `Allow: GET, DELETE`. +- Register the new file in the layout shard and expected-layout shard. + +## Docs + +`structure/data-planes/gemini-inbound.md` "Interactions state" subsection with every rule above, and +the manifest entry for the store file. + + + +## As built (cycle 3, after the focused audit `.tmp/research/audit-020.md`, NEAR-PASS) + +- Owner: `interactionOwner(req, config, admission)` in `src/server/gemini-interactions-inbound.ts` = + `resolveContextPrincipal(...) ?? "loopback"` (keyless loopback only); the store takes a plain owner string. +- Chaining: `chainInput` in the codec resolves results only against the pending calls of the stored turn's + last answer, only as leading input, and drops a leading resend of those calls. +- The store (`writtenAt`, lazy expiry with `continue` instead of `break`, per-entry cap = min(8 MiB, inbound + limit)) is `gemini_interactions` on `APP_OWNED_RETAINED_STORE_REGISTRATIONS`; README retained-store count + 14 → 15 in all eight pages, memory-watchdog id list updated. +- Storing happens inside `frames()` with a try/catch; `x-opencodex-interaction-stored` is `true|false` when a + store was requested and is listed in `Access-Control-Expose-Headers`. +- The codec records `plan.inputSteps`; GET returns them before the output steps, with + `previous_interaction_id` when chained. By-id routes use `resolveResponsesApiAuth`. diff --git a/devlog/_plan/261115_google_protocol_cpa_parity/030_phase3_gemini_inbound_fidelity.md b/devlog/_plan/261115_google_protocol_cpa_parity/030_phase3_gemini_inbound_fidelity.md new file mode 100644 index 00000000000..2f5d1900c41 --- /dev/null +++ b/devlog/_plan/261115_google_protocol_cpa_parity/030_phase3_gemini_inbound_fidelity.md @@ -0,0 +1,168 @@ +# 030 — Phase 3: Gemini generateContent inbound fidelity (on #8742) + +Rows: IN-09 + CW-01 (P1), IN-05, IN-12 (P2), IN-03, IN-13 (P3). Class C3: touches the shared Chat codec +and encoder. Depends on the #8742 merge. Each row is its own commit. + +## 3a — CW-01: Chat carries `extra_content.google.thought_signature` + +Today the Responses wire carries a Gemini signature on `function_call` items +(`src/responses/provider-opaque-metadata.ts:17-61`, read in `src/responses/parser.ts:532-536` with a +fallback to the proxy-side store), but the Chat wire drops it both ways: `pushToolCall` in +`src/protocols/codecs/chat-ir.ts:260-265` builds `OcxToolCall` without `providerMetadata`, and +`emitToolCall` in `src/protocols/encoders/chat.ts:112-129` never writes `extra_content`. CPA reads and +writes this field on Chat (C-V-34, C-V-35). + +```diff +// src/protocols/codecs/chat-ir.ts +- const pushToolCall = (callId: string, name: string, args: string): void => { ++ const pushToolCall = (callId: string, name: string, args: string, extra?: unknown): void => { + emitted = true; +- const call: OcxToolCall = { type: "toolCall", id: callId, name, arguments: functionCallArgumentsFromText(callId, args) }; ++ const providerMetadata = providerMetadataFromResponsesFunctionCall({ extra_content: extra }); ++ const call: OcxToolCall = { type: "toolCall", id: callId, name, arguments: functionCallArgumentsFromText(callId, args), ++ ...(providerMetadata ? { providerMetadata } : {}) }; +@@ (tool_calls loop) +- pushToolCall(callId, name, args); ++ pushToolCall(callId, name, args, entry.extra_content); +``` + +No parse-time store fallback is added: `lookupReplayThoughtSignature` requires a bound replay scope for +a hit (`src/responses/parser.ts:36-42`), and the scope is not bound when a request is parsed. The +scoped durable lookup already happens at serialization in the adapter (`src/adapters/google.ts:527-535`, +#1926), which covers clients that do not echo the field. The carrier only reads what the client sent. + +```diff +// src/protocols/encoders/chat.ts +- const emitToolCall = (toolIndex: number, callId: string, name: string, args: string) => { ++ const emitToolCall = (toolIndex: number, callId: string, name: string, args: string, extra?: Record) => { +@@ +- function: { name, arguments: args }, ++ function: { name, arguments: args }, ++ ...(extra ? { extra_content: extra } : {}), +@@ toolDone(call) +- emitToolCall(toolIndex, call.callId, call.name || toolNameByIndex.get(toolIndex) || "", call.arguments); ++ emitToolCall(toolIndex, call.callId, call.name || toolNameByIndex.get(toolIndex) || "", call.arguments, call.extraContent); +``` + +Stale check: the shape of the `call` the converter hands to `toolDone` and whether the serialized +Responses item's `extra_content` is already on it; if not, add an `extraContent` field where the +converter reads the finished `function_call` item. The buffered Chat response path gets the same field +on `message.tool_calls[]`. + +Tests: EXTEND `tests/responses/protocol-chat-ir-parity.test.ts` — an assistant `tool_calls[].extra_content.google.thought_signature` reaches +`OcxToolCall.providerMetadata`; an oversized signature is dropped. EXTEND the Chat encoder tests — a +tool call with provider metadata emits `extra_content` in the stream and in the buffered body. + +## 3b — IN-09: Gemini inbound codec carries `thoughtSignature` + +```diff +// src/protocols/codecs/gemini.ts (chatMessages, model role) +- calls.push({ id, type: "function", function: { name, arguments: JSON.stringify(args) } }); ++ const signature = field(part, "thoughtSignature") ?? pendingThoughtSignature; ++ pendingThoughtSignature = undefined; ++ calls.push({ id, type: "function", function: { name, arguments: JSON.stringify(args) }, ++ ...(typeof signature === "string" && signature ? { extra_content: { google: { thought_signature: signature } } } : {}) }); +``` + +A `thoughtSignature` on a `thought:true` text part or a signature-only part is held as +`pendingThoughtSignature` for the next call in the same turn (Gemini 3 puts it on the first call). +Response side (`functionCallPart`, buffered and stream): copy `tool_calls[].extra_content.google.thought_signature` +onto the part as `thoughtSignature`. Unsigned calls stay unsigned (the outbound adapter's sentinel rule +applies on the Google side). + +Tests (EXTEND `tests/responses/responses-gemini-codec.test.ts`): request with a signed `functionCall` +→ Chat `tool_calls[0].extra_content`; buffered and streamed Chat responses with `extra_content` → +`functionCall` part with `thoughtSignature`. EXTEND `tests/server/server-gemini-inbound.test.ts` with a +two-turn tool loop through a `google` provider fixture that returns a signature on turn 1 and asserts the +turn-2 upstream `functionCall` part carries it — this is the end-to-end failing test that settles A's open +question 1. + +## 3c — IN-05: `:countTokens` returns a local estimate + +Build the Chat body with `geminiToChat(model, body.generateContentRequest ?? body, false)`, parse it with +the Chat IR (`src/protocols/codecs/chat-ir.ts`), and estimate with `estimateInputTokens(parsed, model)` +(`src/server/responses/input-admission.ts:124`; the Messages estimator in `messages-shared.ts:570` takes a +Messages body and does not fit). Answer `{ "totalTokens": n }`. `dispatchGeminiRoute` keeps +model-discovery admission for this method (no upstream call) and enforces the key's model scope exactly +as `handleGeminiModel` does (unknown or out-of-scope model → 404). Tests: `server-gemini-inbound.test.ts` 501 case becomes a 200 with a positive integer +`totalTokens` for `contents` and for `generateContentRequest`; embed methods stay 501. + +## 3d — IN-12: model resources carry token limits + +`modelResource(selector)` in `src/server/gemini-inbound.ts` adds `inputTokenLimit` and +`outputTokenLimit` when the catalog knows the route's context window and max output (stale check: the +accessor `listOllamaRoutes` rows expose, or the catalog lookup Ollama's `/api/show` uses). Unknown → the +fields are omitted, never guessed. Test: the list and lookup carry the configured limits for a fixture +model with `contextWindow`/`maxOutputTokens`. + +## 3e — IN-03 and IN-13 + +- `dispatchGeminiRoute`: `const sse = (url.searchParams.get("alt") ?? url.searchParams.get("$alt")) === "sse";` +- `STATUS_NAMES`: add `402: "FAILED_PRECONDITION"`, `408: "DEADLINE_EXCEEDED"`, `409: "ABORTED"`, + `422: "INVALID_ARGUMENT"`, `500: "INTERNAL"`, `502: "UNAVAILABLE"` (google.rpc.Code mapping). +- Tests: `$alt=sse` streams SSE; `geminiErrorBody(409, …).error.status === "ABORTED"`. + +## Docs + +Update `structure/data-planes/gemini-inbound.md` (signatures, countTokens, token limits, `$alt`) and +`structure/data-planes/inbound-compat.md` (Chat `extra_content` carrier). + + + +## Stale check (cycle 4, at baa5dfbadb), revised after audit `.tmp/research/audit-030.md` (FAIL) + +3a replaces the earlier 3a diff. Carrier rule everywhere: a client value is normalized with +`providerMetadataFromResponsesFunctionCall` and re-serialized with `responsesExtraContentFromProviderMetadata`, +so a malformed or oversized `extra_content` becomes absent and never fails the request (`responses/schema.ts:111` +is strict and `parser.ts:232` throws on a miss). + +- Inbound, bridge lane (all Chat→AI Studio/Vertex traffic and all Gemini-inbound traffic): + `src/chat/inbound.ts:224` `toolCallsToItems` spreads the normalized `extra_content` onto each pushed + `function_call` item; `parser.ts:532` already turns it into `providerMetadata`. +- Inbound, Antigravity direct lane: `chat-ir.ts` `pushToolCall` gets the same normalized metadata (keeps the + chat-ir/bridge parity contract); one `extra_content` fixture joins `tests/responses/protocol-chat-ir-parity.test.ts`. +- Outbound, `src/chat/outbound.ts` (primary: `directEncoders` defaults off, `src/protocols/settings.ts:104`): + stream `emitToolCall` gains an `extra` argument fed from `output_item.done` `item.extra_content` (normalized); + buffered `function_call` branch (~:970) copies it; `collectChatCompletion` (~:1220-1294) keeps it per tool index + so SSE-folded bodies (also the direct lane's non-stream `collectChatCompletionResponse`) carry it. +- Outbound, direct lane: `adapter-events.ts` passes `providerMetadata` from `tool_call_start` on `toolDone`; + `encoders/chat.ts` `emitToolCall` writes it. Emission is self-gating: only `google.ts` sets provider metadata. +- The direct lane does remember signatures server-side (`client-encoder-delivery.ts:167` folds through + `buildResponseJSON`, `response-json.ts:376`), so the combined two-turn test calls + `resetThoughtSignatureReplayForTests()` between turns; the echo-only test uses a fresh call id. +- Native Chat isolation: `src/server/chat-native-eligibility.ts:45-49` forwards message objects verbatim; a body + whose assistant `tool_calls[]` carry `extra_content` declines native Chat with the existing + `opaque-state-stripped` reason, so Google opaque state never reaches another vendor (the bridge drops it, + no non-Google adapter serializes provider metadata). + +3b details: capture `pendingThoughtSignature` before the thought-text and signature-only early returns, scoped +per content (reset each turn); `StreamTool` gains `signature` from `delta.tool_calls[].extra_content`; buffered +reads `call.extra_content`; parallel calls sign only the call that carried it. + +3c details: read with `readJsonRequestBody` + `createTranslatorBudget` under the inbound limit; resolve the route with +`findOllamaRoute` + `routeAllowedByScope` (404 unknown or out of scope); parse with the bridge Chat path +`chatConversationToIr` (cheaper than `chatToResponsesBody` → `parseRequest`), then +`estimateInputTokens({ ...parsed, modelId })` with the route's provider; 400 for codec/Chat errors, 413 for size; +wired only for `countTokens` (embed stays 501); `supportedGenerationMethods` gains `countTokens`. + +3d precedence (never guessed): `inputTokenLimit` = configured max input / context window +(`src/codex/catalog/model-hints.ts`) ?? `customModels[].contextWindow` ?? `getModelMetadata(provider, model)?.contextWindow`; +`outputTokenLimit` = `customModels[].maxOutputTokens` ?? `getModelMetadata(...)?.maxTokens`; absent when unknown. + +3e: also `405: "UNIMPLEMENTED"`. + +Tests (first, failing on baa5dfbadb): `tests/responses/chat-google-thought-signature.test.ts` covers both lanes × +stream/buffered surfacing, echo-only signing, store reset between turns, malformed and oversized echoes answering +200 without a signature, and no `extra_content` on non-Google routes; a native-Chat decline test; the Gemini inbound +two-turn signature test, countTokens and token-limit tests in a sibling of `server-gemini-inbound.test.ts`. + + +## As built (cycle 4) + +Implemented as the revised stale-check section describes, after two audit rounds (FAIL, then NEAR-PASS). +`normalizedClientExtraContent` (in `src/responses/provider-opaque-metadata.ts`) is the one normalizer every site +uses. The structure doc for the Chat carrier is `structure/data-planes/chat-reasoning-details.md` (moved there +because `inbound-compat.md` is at its 600-line budget), which now also owns `src/server/chat-native-eligibility.ts`. +Red evidence: `.tmp/t030-red-all.log` (13 of 26 new or extended cases fail with the source changes set aside). +Residual: a client that does not echo `extra_content` still relies on the server-side store, which the bridge and the +direct lane both write; the Antigravity chat-ir inbound path is covered by the parity fixture. diff --git a/devlog/_plan/261115_google_protocol_cpa_parity/040_phase4_google_error_classification.md b/devlog/_plan/261115_google_protocol_cpa_parity/040_phase4_google_error_classification.md new file mode 100644 index 00000000000..eb570825411 --- /dev/null +++ b/devlog/_plan/261115_google_protocol_cpa_parity/040_phase4_google_error_classification.md @@ -0,0 +1,180 @@ +# 040 — Phase 4: Google error classification (ErrorInfo, RetryInfo, TOS_VIOLATION) + +Rows: AG-X1, AG-X2, AG-X3 (all P1). Class C3: the TOS part writes durable account state through the +existing fenced `markAccountNeedsReauthIfGeneration` path. Independent of #8742. + +## Current behaviour (d842c1352e) + +- `src/adapters/google-errors.ts`: classification reads only `error.message`/`error.status` prose + (`GOOGLE_QUOTA_EXHAUSTED_NEEDLES`, `GOOGLE_TRANSIENT_RATE_LIMIT_PATTERNS`); the only structured reason + read is `VALIDATION_REQUIRED` (`hasAntigravityValidationReason`). `extractGoogleRetryAfterSeconds` + accepts only `^\d+(\.\d+)?s$`. +- `src/adapters/google-http.ts:139-172`: the body delay is used only on the quota-exhausted branch; the + transient 429 backoff calls `retryBackoffDelayMs` with `res.headers` only, so a body-only + `RetryInfo.retryDelay` gives the 250 ms → 2 s ladder. +- `src/adapters/antigravity-refusal.ts:50-57`: only the "verify your account" prose convicts an account. + +CPA reference: `internal/runtime/executor/antigravity_executor_credits.go:219-288` (429 reasons), +`:358-439` (TOS), `internal/runtime/executor/helps/json_retry_helpers.go:35-80` (delays). Tests to +mirror: `antigravity_executor_credits_test.go:149` (`TestClassifyAntigravity429`), `:246` +(`TestParseRetryDelay_HumanReadableDuration`), `antigravity_executor_tos_test.go:40,171,219`. + +## 4a — structured details (X1, X2) + +NEW `src/adapters/google-error-details.ts` (a separate module so the parsing is testable on its own; +`google-errors.ts` is 179 lines with no baseline entry, under the 2,000-line threshold): + +```ts +export interface GoogleErrorDetails { reason?: string; domain?: string; retryDelayMs?: number } +/** google.rpc details from {error:{details:[...]}} or [{error:{...}}]; bounded input, never throws. */ +export function googleErrorDetails(payloadText: string): GoogleErrorDetails; +/** Google duration text: "30s", "0.5s", "1h2m3s", "1.5h", "500ms", "2m". Returns ms or undefined; rejects negatives, >30 days, garbage. */ +export function parseGoogleDurationMs(raw: string): number | undefined; +``` + +`reason` comes from the `@type …google.rpc.ErrorInfo` entry; `reasonUntyped` separately records a string +`reason` on a detail with no `@type` (CCA sometimes omits it), usable for retry classification only and +never for the durable TOS mark; `retryDelayMs` from `RetryInfo.retryDelay`, then +`ErrorInfo.metadata.quotaResetDelay`, then the message pattern `reset after ` (CPA's fallback). + +MODIFY `src/adapters/google-errors.ts`: + +```diff + export function isQuotaExhaustedBody(payloadText: string): boolean { ++ const { reason } = googleErrorDetails(payloadText); ++ if (reason === "QUOTA_EXHAUSTED" || reason === "INSUFFICIENT_G1_CREDITS_BALANCE") return true; ++ if (reason === "RATE_LIMIT_EXCEEDED") return false; + const { message, status } = googleErrorDetail(payloadText); +@@ export function extractGoogleRetryAfterSeconds(payloadText: string): string | undefined { +- …regex /^\s*(\d+(?:\.\d+)?)\s*s\s*$/i over details… ++ const ms = googleErrorDetails(payloadText).retryDelayMs; ++ return ms !== undefined && ms > 0 ? String(Math.ceil(ms / 1000)) : undefined; + } +@@ function classifyGoogle(label, status, enumStatus, text, reason?) ++ if (reason === "QUOTA_EXHAUSTED" || reason === "INSUFFICIENT_G1_CREDITS_BALANCE") return `${label} quota exhausted`; ++ if (reason === "RATE_LIMIT_EXCEEDED") return `${label} rate limit exceeded`; +``` + +`safeGoogleHttpErrorMessage` passes `googleErrorDetails(payloadText).reason` into `classifyGoogle`. +Prose stays as the fallback for bodies without details (D6). Scope: `QUOTA_EXHAUSTED` and +`INSUFFICIENT_G1_CREDITS_BALANCE` convict quota exhaustion on every Google label; the +`RATE_LIMIT_EXCEEDED` → transient override applies to `label === "Antigravity"` only, matching CPA, which +reads ErrorInfo only on Antigravity (C-V-46). On AI Studio and Vertex the daily-quota prose needles still +win over `RATE_LIMIT_EXCEEDED`. `isQuotaExhaustedBody` gains a `label` parameter for that. + +MODIFY `src/adapters/google-http.ts` (transient 429 path): + +```diff ++ let delayHeaders: Headers = res.headers; ++ if (res.status === 429 && !res.headers.has("retry-after")) { ++ const bodyRetryAfter = extractGoogleRetryAfterSeconds(peek); // peek moves out of the quota branch ++ if (bodyRetryAfter) { delayHeaders = new Headers(res.headers); delayHeaders.set("retry-after", bodyRetryAfter); } ++ } + const delayMs = retryBackoffDelayMs(attempt, { + baseDelayMs: GOOGLE_RETRY_BASE_MS, + maxDelayMs: GOOGLE_RETRY_MAX_MS, +- headers: res.headers, ++ headers: delayHeaders, + retryAfterIsLowerBound: true, + }); + if (delayMs > RETRY_AFTER_CEILING_MS) { +- return … normalizeFinalGoogleError(label, res, …); ++ return … withBodyRetryAfter(normalizeFinalGoogleError(label, res, …), peek); // client sees the stated wait + } +``` + +`withBodyRetryAfter` sets `retry-after` from the body when the header is absent, mirroring the quota +branch. Stale check: how existing Retry-After tests in `tests/adapters/google/` observe the computed +delay without sleeping (an injected sleep or the `beforeDispatch` hook); the new tests use the same seam. + +## 4b — TOS_VIOLATION (X3) + +- `google-errors.ts`: `export const ANTIGRAVITY_TOS_VIOLATION_PREFIX = "Antigravity account suspended (TOS_VIOLATION)"`; + `safeGoogleHttpErrorMessage` uses it for `label === "Antigravity" && status === 403 && reason === "TOS_VIOLATION"`. + The appeal URL in `ErrorInfo.metadata` is never copied into the message (only the sanitized + `error.message` is). +- `antigravity-refusal.ts`: `AntigravityRefusalKind = "verify_account" | "tos_violation" | "other"`; + `classifyAntigravityRefusal` returns `tos_violation` only when the bounded body parses to + `error.code === 403`, `status === "PERMISSION_DENIED"` and a detail with + `@type: "type.googleapis.com/google.rpc.ErrorInfo"` and `reason: "TOS_VIOLATION"`, as CPA requires + (`antigravity_executor_credits.go:376-391`). Prose or an untyped reason never convicts. +- `src/server/responses/adapter-dispatch.ts:1666` loop: pass `refusal.kind` as the reason to + `markAccountNeedsReauthIfGeneration` (today a literal `"verify_account"`). +- One closed type in `src/oauth/types.ts`: `export const NEEDS_REAUTH_REASONS = ["verify_account", + "tos_violation"] as const; export type NeedsReauthReason = typeof NEEDS_REAUTH_REASONS[number]; + export function isNeedsReauthReason(v: unknown): v is NeedsReauthReason`. Every literal + `"verify_account"` check on this field becomes a membership check, at each site found by + `rg -n 'verify_account' src` on d842c1352e: + - `src/oauth/types.ts:118` (field type), `src/oauth/store.ts:699-700` (load), `:1610` (serialize), + `:1656-1665` (`markAccountNeedsReauth`), `:1673` (`mergeAccountCredential`: a silent refresh keeps + `needsReauth` only for a held reason — this is what preserves quarantine across refresh, the + contract in `structure/transports/inventory.md:80`), `:1676` (`markAccountNeedsReauthIfGeneration`, the + function dispatch calls); + - `src/oauth/index.ts:1795,1836` (file at 1,980 lines: edits stay net zero by swapping literals for the + helper), `src/cli/account-api.ts:45,473,519`, `src/cli/account-auth.ts:130`; + - `src/oauth/health.ts:26,117,140` (`OAuthReauthReason` gains `tos_violation`, label "Account suspended"); + - `src/cli/account.ts:126` label `needs-reauth(tos)`; + - `src/server/responses/adapter-dispatch.ts:1676` passes `refusal.kind` (1,970 lines: net zero). +- Downgrade limit, stated plainly: a build older than this change drops an unknown reason on load + (`store.ts:699`), and its next silent refresh then clears `needsReauth` (`store.ts:1673`), so after a + downgrade a suspended account can rejoin that older build's pool until it is refused again. The + release note says so; no migration can prevent it from the newer side. +- In-stream: `src/adapters/google.ts:1402-1413` already ends the turn on `chunk.error`; when + `chunk.error.status === "PERMISSION_DENIED"` and the details carry `TOS_VIOLATION`, the error message + uses the TOS prefix. Account marking stays HTTP-only (dispatch has no fenced snapshot mid-stream). + +## Tests (first, failing) + +- EXTEND `tests/adapters/google/google-errors.test.ts`: `parseGoogleDurationMs` table (`30s`, `0.5s`, + `1h2m3s`, `500ms`, `2m`, `-1s`, `abc`, `999999h`); `extractGoogleRetryAfterSeconds` for `1h2m3s` + quotaResetDelay → `"3723"`; `isQuotaExhaustedBody` true for `QUOTA_EXHAUSTED` with transient prose on + every label; for `RATE_LIMIT_EXCEEDED` with "daily limit reached" prose: false on Antigravity, true on + AI Studio and Vertex; classification strings for each reason; + TOS body → TOS prefix, no appeal URL in the message. +- EXTEND the Google retry tests: 429 with body-only `retryDelay: "3s"` waits ≥ 3000 ms before the second + send (observed through the test seam, no real sleep); a body delay over the ceiling returns the 429 with + `retry-after` set. +- EXTEND `tests/adapters/google/antigravity-refusal.test.ts` and the dispatch test that covers + `verify_account` marking: a TOS 403 marks `tos_violation` and rotates; prose "terms of service" or an + untyped `reason` does not convict. +- NEW store test: after a `tos_violation` mark, `mergeAccountCredential` with a refreshed credential keeps + `needsReauth: true` and the reason; serialization round-trips it; `ocx account list` shows + `needs-reauth(tos)`. + +## Docs + +`structure/providers-and-adapters.md` (Google error classification), `structure/transports/inventory.md` +(quarantine across refresh now covers `tos_violation`), `structure/providers/generic-account-pool.md`, and +the docs-site pages listed in 070. + + + +## Stale check (cycle 5, at 7464b83dd7) + +- Dispatch sees the normalized body: `fetchGoogleWithRetry` replaces a final error body with + `safeGoogleHttpErrorMessage` text unless `returnRawErrors`, and `adapter-dispatch.ts:1666` classifies that + text. The structured `ErrorInfo` is gone by then, so the trusted signal is the prefix + `ANTIGRAVITY_TOS_VIOLATION_PREFIX`, emitted only when the original body carries a typed + `google.rpc.ErrorInfo` with `reason: TOS_VIOLATION` on a 403 `PERMISSION_DENIED` (the same trust boundary + `ANTIGRAVITY_VALIDATION_REQUIRED_PREFIX` uses, `google-errors.ts:113-116`). `classifyAntigravityRefusal` returns + `tos_violation` when the normalized text starts with `: `; the sidecar raw path normalizes first, as + `isAntigravityRawValidationRefusal` does. +- Retry-delay test seam: `spyOn(retry, "sleepWithAbort")` (`tests/adapters/google/google-vertex-http.test.ts:258`). +- `isQuotaExhaustedBody(payloadText, label?)`: the only caller is `google-http.ts:144`, which passes its label. +- Files near the 2,000-line threshold edited here stay net zero: `src/oauth/index.ts` (1,980) and + `src/server/responses/adapter-dispatch.ts` (1,970). +- Existing coverage to extend: `tests/adapters/google/google-errors.test.ts`, `google-vertex-http.test.ts`, + `antigravity-refusal.test.ts`, `tests/oauth/oauth-health.test.ts`, `tests/cli/cli-account-verify-status.test.ts`; the + dispatch marking test is a NEW sibling `tests/server/server-google-antigravity-tos-refusal.test.ts` + (harness of `server-google-antigravity-oauth-401-replay.test.ts`). +- NEW `src/adapters/google-error-details.ts` drafted at `.tmp/draft/google-error-details.ts`. + + +## As built (cycle 5) + +After the focused audit (`.tmp/research/audit-040.md`, NEAR-PASS), the suspension is stored downgrade-safe: the hold +stays `needsReauthReason: "verify_account"` and the cause rides in `needsReauthCause: "tos_violation"` +(`applyReauthReason` in `src/oauth/store.ts`); `markAccountNeedsReauth*` accept `"tos_violation"` and translate it. +The prefix gate is `isAntigravityTosViolationBody` (object root, code 403, `PERMISSION_DENIED`, any typed `ErrorInfo` +entry); the message is fixed. Health adds reason `tos_violation` / label "Account suspended" with an appeal action. +Residuals: the sidecar path and in-stream errors keep today's behavior for a TOS 403; docs pages land in 070. diff --git a/devlog/_plan/261115_google_protocol_cpa_parity/050_phase5_google_response_fidelity.md b/devlog/_plan/261115_google_protocol_cpa_parity/050_phase5_google_response_fidelity.md new file mode 100644 index 00000000000..117958eec70 --- /dev/null +++ b/devlog/_plan/261115_google_protocol_cpa_parity/050_phase5_google_response_fidelity.md @@ -0,0 +1,128 @@ +# 050 — Phase 5: Google response fidelity (usage, finish reasons, prompt blocks) + +Rows: OUT-V38 (P1), OUT-V42 (P1), AG-R7, OUT-V40, OUT-V43 (P2). Class C3: usage feeds pricing, +telemetry and every inbound encoder. Independent of #8742 (IN-14 benefits automatically). + +## 5a — usage (OUT-V38, AG-R7) + +```diff +// src/adapters/google.ts:679 + function usageFromGemini(usage: Record | undefined): OcxUsage | undefined { + if (!usage) return undefined; ++ const thoughts = usage.thoughtsTokenCount ?? 0; + return { +- inputTokens: usage.promptTokenCount ?? 0, +- outputTokens: usage.candidatesTokenCount ?? 0, ++ // Google reports tool-use prompt tokens (search grounding, URL context) beside the prompt. ++ inputTokens: (usage.promptTokenCount ?? 0) + (usage.toolUsePromptTokenCount ?? 0), ++ // Google reports thinking beside candidates; every other adapter's output includes reasoning ++ // (telemetry clamps reasoning to output, src/telemetry/aggregate.ts:185), and Google bills it as output. ++ outputTokens: (usage.candidatesTokenCount ?? 0) + thoughts, + ...(usage.cachedContentTokenCount !== undefined ? { cachedInputTokens: usage.cachedContentTokenCount } : {}), + ...(usage.thoughtsTokenCount !== undefined ? { reasoningOutputTokens: usage.thoughtsTokenCount } : {}), + }; + } +``` + +Pinned expectations change with a stated reason (D5): `tests/adapters/adapter-usage.test.ts:296` +("Google usage maps cached and thoughts tokens", output 5 → 7) and the thoughts cases in +`tests/adapters/google/google-vertex-stream.test.ts`, `google-adapter.test.ts`, +`gemini-4-argon-antigravity.test.ts`, `tests/responses/responses-show-thinking-summary.test.ts`, +`protocol-argon-thought-boundary.test.ts` (each found by `rg -l thoughtsTokenCount tests`; update only the +output/input numbers, never loosen an assertion). Stale check before B: `rg -n 'reasoningOutputTokens' +src/pricing* src/usage` to confirm no consumer adds reasoning on top of output for Google (none on +d842c1352e outside the generic sums listed in the research pass). + +New failing tests first: candidates 5 + thoughts 2 → output 7, reasoning 2; prompt 10 + +toolUsePrompt 4 → input 14; absent thoughts → unchanged. + +## 5b — fail-closed finishes on every Google mode (OUT-V42) + +Today the fail-closed check is gated on `googleMode === "vertex" || "cloud-code-assist"` +(`google.ts:1607`, `google.ts:1822`), so AI Studio turns ending in `MALFORMED_FUNCTION_CALL` complete +empty. CPA fails all three zero-output reasons on every Gemini path +(`internal/runtime/executor/helps/gemini_zero_output.go:39-46`). + +```diff +// src/adapters/google-truncation.ts + const TRUNCATION_REASONS = new Set(["MAX_TOKENS", "MALFORMED_FUNCTION_CALL"]); ++/** Finishes that mean the model's output was dropped upstream; they fail only when nothing visible arrived. */ ++const DROPPED_OUTPUT_REASONS = new Set(["UNEXPECTED_TOOL_CALL", "MALFORMED_RESPONSE"]); +-export function isVertexTruncatedTurn(finishReason: string | undefined, toolCallsStarted: number): boolean { +- if (!isVertexTruncationReason(finishReason)) return false; +- return toolCallsStarted > 0 || finishReason === "MALFORMED_FUNCTION_CALL"; ++export function isGoogleTruncatedTurn(finishReason: string | undefined, toolCallsStarted: number, sawVisibleOutput = false): boolean { ++ if (finishReason === undefined) return false; ++ if (isVertexTruncationReason(finishReason)) return toolCallsStarted > 0 || finishReason === "MALFORMED_FUNCTION_CALL"; ++ return DROPPED_OUTPUT_REASONS.has(finishReason) && toolCallsStarted === 0 && !sawVisibleOutput; + } +``` + +The existing `MALFORMED_FUNCTION_CALL` rule is kept as it is (it fails even after text, because a dropped +call leaves the turn incomplete). The two new reasons follow CPA's rule and fail only when no text or +call arrived. With visible output: `MALFORMED_RESPONSE` maps to `content_filter` (5c) and +`UNEXPECTED_TOOL_CALL` ends as a plain stop with no stop reason (a tool-misuse finish is not a content +filter; the text the client already has is the answer). `isVertexTruncatedTurn` stays as a +re-export for existing imports. `vertexTruncationErrorEvent` marks `replaySafeBeforeOutput` for every +zero-call failure. Both call sites in `google.ts` drop the `googleMode` condition and pass +`sawVisibleOutput`. Dropping the gate also makes AI Studio (and its Go/Zen variants) fail closed on +`MAX_TOKENS` after a started tool call, as Vertex and Antigravity already do; that is intended (a +half-written call is never a valid tool call) and gets its own test. NEW `googleTruncationErrorMessage(mode, reason)` names "Gemini API", "Vertex AI" or +"Antigravity" by mode; the vertex wording is unchanged. + +## 5c — finish reasons (OUT-V40) and prompt blocks (OUT-V43) + +- Both stop-reason tables (`google.ts:1617-1620` stream, `google.ts:1838-1841` buffered) move to one + helper in `google-truncation.ts`: `googleStopReason(finishReason)` with `MAX_TOKENS → max_tokens` and a + new constant `GOOGLE_CONTENT_FILTER_FINISHES = SAFETY, RECITATION, BLOCKLIST, PROHIBITED_CONTENT, SPII, + IMAGE_SAFETY, IMAGE_PROHIBITED_CONTENT, MALFORMED_RESPONSE` → `content_filter`; everything else → no stop + reason. +- `src/lib/failure-detail.ts:42-46` `FAILURE_DETAIL_FINISH_REASONS` (the request-log finish-reason enum, + which `withProviderFailureFacts` filters against) gains `MALFORMED_RESPONSE` and + `MISSING_THOUGHT_SIGNATURE` (both in Google's FinishReason enum, `doc-generate-content-ref` capture), + so the new fail-closed events keep their #8446 log fact; `structure/data-planes/error-detail.md` lists + them. +- Prompt blocks: a buffered body with no candidates and `promptFeedback.blockReason`, or a stream frame + with `promptFeedback.blockReason` and no candidates, ends the turn with + `{type:"error", message:"