From ad8f97901618d59a732570ed3de694ffe1d67fd2 Mon Sep 17 00:00:00 2001 From: kt Date: Wed, 30 Sep 2026 20:09:42 -0700 Subject: [PATCH 001/267] build darwin x64 on the m-pool (#3236) The x86_64-apple-darwin legs in continuous.yml and release.yml move from the macos-15-intel pool to the macos-15 Apple-silicon pool, cross-compiling for x86_64 (the target stays x86_64-apple-darwin). The M1 links this binary ~2.2x faster than the intel pool with far tighter variance (484 s vs 1046 s same-commit link tail), killing the 29-minute outliers; the livecheck runs the x64 artifact under Rosetta 2, the runtime install-rust.sh gives an x86_64 payload on an Apple-Silicon Mac. --- .github/workflows/continuous.yml | 19 +++++++++++++++++-- .github/workflows/release.yml | 15 ++++++++++++++- 2 files changed, 31 insertions(+), 3 deletions(-) diff --git a/.github/workflows/continuous.yml b/.github/workflows/continuous.yml index dabe1976221..03572028373 100644 --- a/.github/workflows/continuous.yml +++ b/.github/workflows/continuous.yml @@ -234,8 +234,17 @@ jobs: include: - target: aarch64-apple-darwin runs-on: macos-14 + # The x86_64 leg cross-compiles on the Apple-silicon pool: rustc + # and the Xcode linker build either darwin arch from an M-series + # host, and the M-pool links this binary ~2.2x faster than the + # macos-15-intel pool with far tighter variance (484 s vs 1046 s + # same-commit link tail, 2026-09-30). The livecheck below runs + # the assembled x64 artifact under Rosetta 2 — the macos-15 + # arm64 image installs it, and install-rust.sh ships the x64 + # build to an Apple-Silicon Mac's Rosetta shell, so the gate + # still boots the binary on its delivery runtime. - target: x86_64-apple-darwin - runs-on: macos-15-intel # macos-13 is retired; this is the Intel runner now + runs-on: macos-15 env: # AppleDouble resource forks must not leak into the archive; the # assembler additionally enforces plain-file payloads. @@ -272,7 +281,13 @@ jobs: --catalog-assets "target/${{ matrix.target }}/catalog-assets" \ --out-dir "target/${{ matrix.target }}/dist" cat "target/${{ matrix.target }}/dist/manifest.json" - - name: Livecheck the assembled continuous artifact on its native runner + # The livecheck extracts the tarball and runs the payload binary's + # `--version` from a scratch cwd (verify_release.py). The aarch64 leg + # executes it natively; the x86_64 leg, cross-compiled on the + # Apple-silicon pool, executes it under Rosetta 2 — the runtime the + # x64 payload runs on for an Apple-Silicon Mac customer, so the gate + # still boots the artifact on its delivery runtime. + - name: Livecheck the assembled continuous artifact on its build runner run: | set -euo pipefail version="$(sed -n 's/^version *= *"\([^"]*\)".*/\1/p' Cargo.toml | head -1)" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 86bf9a05532..486bf6befca 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -234,8 +234,17 @@ jobs: include: - target: aarch64-apple-darwin runs-on: macos-14 + # The x86_64 leg cross-compiles on the Apple-silicon pool: rustc + # and the Xcode linker build either darwin arch from an M-series + # host, and the M-pool links this binary ~2.2x faster than the + # macos-15-intel pool with far tighter variance (484 s vs 1046 s + # same-commit link tail, 2026-09-30). The livecheck below runs + # the assembled x64 artifact under Rosetta 2 — the macos-15 + # arm64 image installs it, and install-rust.sh ships the x64 + # build to an Apple-Silicon Mac's Rosetta shell, so the gate + # still boots the binary on its delivery runtime. - target: x86_64-apple-darwin - runs-on: macos-15-intel # macos-13 is retired; this is the Intel runner now + runs-on: macos-15 env: # AppleDouble resource forks must not leak into the archive; the # assembler additionally enforces plain-file payloads. @@ -253,6 +262,10 @@ jobs: key: ${{ matrix.target }} - name: Build (release, locked) run: cargo build --release --locked --target ${{ matrix.target }} -j 4 + # The aarch64 leg livechecks natively; the x86_64 leg, + # cross-compiled on the Apple-silicon pool, livechecks under + # Rosetta 2 — the runtime install-rust.sh gives the x64 payload on + # an Apple-Silicon Mac. - name: "Livecheck gate: --version prints the tag version" run: | set -euo pipefail From 583b603119e2b21f719d4196b9b6b86efb396975 Mon Sep 17 00:00:00 2001 From: kt Date: Wed, 30 Sep 2026 20:09:59 -0700 Subject: [PATCH 002/267] remove the faux provider and the hillclimb perf tooling (#3223) The hillclimb era's measurement cluster dies whole: the TS-side faux-provider driver (scripts/ts_faux_extension.js) and the perf battery it drove - scripts/battery/ in its entirety (stream_throughput.py, streaming_render.py-era survivors, sustained_cpu.py, perf_wave.py, perf_gate.py, ci_perf_wave.sh, run_perf_wave.sh, the recorded perf-baseline.json, and the support libs that served nothing else: batterylib.py, mock_provider.py, perf.py, scale_corpus.py, ts_identity.py) - plus the Makefile perf-wave target and its .PHONY entry. Every member had zero live references: no workflow invocation (benchmark.yml is long gone, only the dead Makefile mirror remained), no test shells out to them, the crontab and the fleet tooling never touch them. The benchmark campaign harness on the bench node is the modern performance tooling. Folded onto main after the scripts purge (#3178) merged: that purge already removed the parity harnesses this lane's map had found importing the faux (acp_compaction_parity.py, compact_parity.py, mcp_hint_parity.py, paste_stream_parity.py, spinner_cadence.py, streaming_render.py and the visual-parity cluster), so those deletions fold to no-ops; the purge's merged form kept the wave serving only itself - the faux header named exactly the two wave dimensions as its consumers - so the whole battery directory goes here instead. The golden regeneration harness (crates/pa-core/tests/golden/harness.mjs) is not needed post-port either: the replay tests assert against the frozen corpus at runtime, and the TS checkout remains the reference if a golden ever needs re-derivation. The corpus stays, frozen provenance noted in the replay module doc. Doc/comment repairs where kept files named a removed script: the Makefile drops the perf-wave mirror, golden_replay.rs's harness.mjs cites become the corpus's provenance notes, and differential_cli.rs's TMPDIR comment no longer cites batterylib's scrubbed_env. --- Makefile | 10 +- crates/pa-cli/tests/differential_cli.rs | 2 +- crates/pa-core/src/tools/golden_replay.rs | 6 +- crates/pa-core/tests/golden/harness.mjs | 663 ------------- scripts/battery/README.md | 62 -- scripts/battery/batterylib.py | 715 -------------- scripts/battery/ci_perf_wave.sh | 106 --- scripts/battery/mock_provider.py | 297 ------ scripts/battery/perf-baseline.json | 235 ----- scripts/battery/perf.py | 250 ----- scripts/battery/perf_gate.py | 116 --- scripts/battery/perf_wave.py | 1026 --------------------- scripts/battery/run_perf_wave.sh | 46 - scripts/battery/scale_corpus.py | 183 ---- scripts/battery/stream_throughput.py | 258 ------ scripts/battery/sustained_cpu.py | 573 ------------ scripts/battery/ts_identity.py | 108 --- scripts/ts_faux_extension.js | 112 --- 18 files changed, 5 insertions(+), 4763 deletions(-) delete mode 100644 crates/pa-core/tests/golden/harness.mjs delete mode 100644 scripts/battery/README.md delete mode 100644 scripts/battery/batterylib.py delete mode 100755 scripts/battery/ci_perf_wave.sh delete mode 100644 scripts/battery/mock_provider.py delete mode 100644 scripts/battery/perf-baseline.json delete mode 100644 scripts/battery/perf.py delete mode 100644 scripts/battery/perf_gate.py delete mode 100644 scripts/battery/perf_wave.py delete mode 100755 scripts/battery/run_perf_wave.sh delete mode 100644 scripts/battery/scale_corpus.py delete mode 100755 scripts/battery/stream_throughput.py delete mode 100644 scripts/battery/sustained_cpu.py delete mode 100644 scripts/battery/ts_identity.py delete mode 100644 scripts/ts_faux_extension.js diff --git a/Makefile b/Makefile index 0b87aa7276f..0905902c962 100644 --- a/Makefile +++ b/Makefile @@ -51,14 +51,6 @@ glibc-gate: fi \ ;; esac -# Perf wave + regression gate (benchmark.yml job, the local mirror): runs the -# TS binary and a fresh release build side by side in a fresh Prime sandbox -# (both sides on one quiet machine, the methodology BENCHMARKS.md requires) -# and gates the rust medians against scripts/battery/perf-baseline.json. -# PA_BENCH_NO_SANDBOX=1 runs it on the bare runner instead. -perf-wave: - scripts/battery/ci_perf_wave.sh - # Local mirror of the release build-job gates: # release build against the committed lockfile, deterministic tarball assembly, # then end-to-end verification of the host-target artifact. The vendored @@ -180,4 +172,4 @@ shard-gates: python3 scripts/test_ci_test_shard.py python3 scripts/test_ci_pr_crates.py -.PHONY: check deny windows-cross actionlint perf-wave glibc-gate release-dry-run continuous-dry-run audit-build package catalog-assets catalog-assets-fixture catalog-assets-gates fold-gates restamp-gates shard-gates +.PHONY: check deny windows-cross actionlint glibc-gate release-dry-run continuous-dry-run audit-build package catalog-assets catalog-assets-fixture catalog-assets-gates fold-gates restamp-gates shard-gates diff --git a/crates/pa-cli/tests/differential_cli.rs b/crates/pa-cli/tests/differential_cli.rs index c5fc0024e78..c36e7a22f94 100644 --- a/crates/pa-cli/tests/differential_cli.rs +++ b/crates/pa-cli/tests/differential_cli.rs @@ -356,7 +356,7 @@ fn run(binary: &Path, args: &[&str], sandbox: &Path) -> InvocationOutput { // through passwd rather than $HOME, so the env override is the only // reliable isolation for both binaries. .env("PRIME_AGENT_CODING_AGENT_DIR", sandbox.join("agent")) - // Isolate TMPDIR too (batterylib.scrubbed_env parity): without it the + // Isolate TMPDIR too: without it the // TS daemon census escapes into the box's ambient daemons and // `shutdown --force` kills unrelated sockets (containment contract). .env("TMPDIR", sandbox.join("tmp")) diff --git a/crates/pa-core/src/tools/golden_replay.rs b/crates/pa-core/src/tools/golden_replay.rs index 307de2704ab..34d0b3c0cfd 100644 --- a/crates/pa-core/src/tools/golden_replay.rs +++ b/crates/pa-core/src/tools/golden_replay.rs @@ -1,5 +1,5 @@ //! Golden differential tests: replay the corpus recorded from the REAL -//! TypeScript tools (see `tests/golden/harness.mjs`) against the Rust port +//! TypeScript tools (frozen in `tests/golden/corpus/`) against the Rust port //! and assert identical model-facing output. //! //! Corpus cases cover fuzzy edits, file-not-found, bash timeouts and @@ -30,7 +30,7 @@ fn corpus(name: &str) -> serde_json::Value { serde_json::from_str(&std::fs::read_to_string(path).expect("corpus file")).expect("corpus JSON") } -/// Normalize temp paths the same way harness.mjs does. +/// Normalize temp paths to the forms the recorded corpus uses. fn norm_string(s: &str, tmp: &str) -> String { let out = s.replace(&format!("{tmp}/"), "/"); let re = regex_lite("golden-[A-Za-z0-9_]{6}"); @@ -127,7 +127,7 @@ async fn golden_edit_group_matches_ts() { let mut input = case["input"].clone(); if case["applyPrepareArguments"].as_bool().unwrap_or(false) { input = crate::tools::edit::prepare_edit_arguments(input); - // The TS harness records the prepared input for such cases. + // The TS harness recorded the prepared input for such cases. assert_json_eq( &input.clone(), &case["preparedInput"].clone(), diff --git a/crates/pa-core/tests/golden/harness.mjs b/crates/pa-core/tests/golden/harness.mjs deleted file mode 100644 index 07c940613fb..00000000000 --- a/crates/pa-core/tests/golden/harness.mjs +++ /dev/null @@ -1,663 +0,0 @@ -#!/usr/bin/env node -/** - * Golden differential harness (lane core-tools). - * - * Runs the REAL TypeScript tools from the /tmp/pa-golden copy of prime-agent - * and records their results as a JSON corpus, so a Rust port can assert - * byte-identical parity. - * - * - cwd for execution: /tmp/pa-golden (node_modules resolution via jiti). - * - Output: corpus/*.json next to this file. - * - Every case sets up its fixture in a fresh mkdtemp dir; the fixture setup - * is recorded as replayable shell commands. - * - Normalization: os.tmpdir() prefix -> "", random tmp ids -> "". - * No timestamps, durations, or random ids are recorded. - * - * Determinism: two runs produce identical corpus files. - */ -import { spawnSync } from "node:child_process"; -import fs from "node:fs"; -import os from "node:os"; -import path from "node:path"; -import { fileURLToPath, pathToFileURL } from "node:url"; -import { createRequire } from "node:module"; - -const PA_ROOT = "/tmp/pa-golden"; -const __filename = fileURLToPath(import.meta.url); -const OUT_DIR = path.dirname(__filename); -const CORPUS = path.join(OUT_DIR, "corpus"); - -const TMP = os.tmpdir(); - -const req = createRequire(path.join(PA_ROOT, "package.json")); -const { createJiti } = req("jiti"); -const jiti = createJiti(pathToFileURL(path.join(PA_ROOT, "harness-entry.mjs")).href, { - interopDefault: true, - alias: { - "@earendil-works/pi-agent-core": path.join(PA_ROOT, "packages/agent/src/index.ts"), - "@earendil-works/pi-ai": path.join(PA_ROOT, "packages/ai/src/index.ts"), - "@earendil-works/pi-tui": path.join(PA_ROOT, "packages/tui/src/index.ts"), - }, -}); - -async function loadTs(rel) { - const mod = await jiti.import(path.join(PA_ROOT, rel)); - return mod.default ?? mod; -} - -// ---------------------------------------------------------------- normalizing -function normString(s) { - let out = s.split(TMP + "/").join("/"); - out = out.replace(/golden-[A-Za-z0-9_]{6}/g, "golden-"); - out = out.replace(/\bpi-(?:bash|output)-[0-9a-f]+\.log/g, "pi-.log"); - out = out.replace(/tmp-stdout-[0-9A-Za-z_]+/g, "tmp-stdout-"); - return out; -} - -function deepNorm(value) { - if (typeof value === "string") return normString(value); - if (Array.isArray(value)) return value.map(deepNorm); - if (value && typeof value === "object") { - const out = {}; - for (const [k, v] of Object.entries(value)) out[k] = deepNorm(v); - return out; - } - return value; -} - -function writeCorpus(name, cases) { - const doc = deepNorm({ group: name, caseCount: cases.length, cases }); - fs.writeFileSync(path.join(CORPUS, name + ".json"), JSON.stringify(doc, null, 2) + "\n"); -} - -// ------------------------------------------------------------------- fixtures -function makeFixture(tc) { - const dir = fs.mkdtempSync(path.join(TMP, "golden-")); - for (const [name, content] of Object.entries(tc.files ?? {})) { - const abs = path.join(dir, name); - fs.mkdirSync(path.dirname(abs), { recursive: true }); - fs.writeFileSync(abs, Buffer.from(String(content), "utf-8")); - } - for (const cmd of tc.fixture ?? []) { - const r = spawnSync("/bin/bash", ["-c", cmd], { cwd: dir, encoding: "utf-8" }); - if (r.status !== 0) { - throw new Error(`fixture command failed (${r.status}): ${cmd}\nstdout: ${r.stdout}\nstderr: ${r.stderr}`); - } - } - return dir; -} - -function stripCaseRuntimeFields(tc) { - const { files, fixture, ...rest } = tc; - return rest; -} - -// ================================================================== GROUP 1 -async function editGroup() { - const mod = await loadTs("packages/coding-agent/src/core/tools/edit.ts"); - - const gitless = { - files: { - "file.txt": "alpha\nbeta\ngamma\ndelta\n", - }, - }; - - const cases = [ - { - name: "unique-replacement", - ...gitless, - applyPrepareArguments: false, - input: { path: "file.txt", edits: [{ oldText: "beta", newText: "BETA" }] }, - }, - { - name: "two-edits", - files: { "file.txt": "alpha\nbeta\ngamma\ndelta\n" }, - applyPrepareArguments: false, - input: { - path: "file.txt", - edits: [ - { oldText: "alpha", newText: "ALPHA" }, - { oldText: "gamma", newText: "GAMMA" }, - ], - }, - }, - { - name: "not-found", - ...gitless, - applyPrepareArguments: false, - input: { path: "file.txt", edits: [{ oldText: "missing", newText: "x" }] }, - }, - { - name: "ambiguous", - files: { "file.txt": "repeat\nmiddle\nrepeat\n" }, - applyPrepareArguments: false, - input: { path: "file.txt", edits: [{ oldText: "repeat", newText: "x" }] }, - }, - { - name: "overlapping-edits", - files: { "file.txt": "abcdef\n" }, - applyPrepareArguments: false, - input: { - path: "file.txt", - edits: [ - { oldText: "abcd", newText: "X" }, - { oldText: "cdef", newText: "Y" }, - ], - }, - }, - { - name: "file-not-found", - applyPrepareArguments: false, - input: { path: "missing.txt", edits: [{ oldText: "a", newText: "b" }] }, - }, - { - name: "empty-edits", - ...gitless, - applyPrepareArguments: false, - input: { path: "file.txt", edits: [] }, - }, - { - name: "legacy-oldText-newText", - ...gitless, - applyPrepareArguments: true, - input: { path: "file.txt", oldText: "beta", newText: "BETA" }, - }, - { - name: "edits-as-json-string", - ...gitless, - applyPrepareArguments: true, - input: { path: "file.txt", edits: JSON.stringify([{ oldText: "beta", newText: "BETA" }]) }, - }, - { - name: "bom-file", - files: { "file.txt": "hello world\nsecond line\n" }, - applyPrepareArguments: false, - input: { path: "file.txt", edits: [{ oldText: "world", newText: "planet" }] }, - }, - { - name: "crlf-file", - files: { "file.txt": "line1\r\nline2\r\nline3\r\n" }, - applyPrepareArguments: false, - input: { path: "file.txt", edits: [{ oldText: "line2", newText: "LINE2" }] }, - }, - { - name: "fuzzy-trailing-whitespace", - files: { "file.txt": "alpha \nbeta\nkeep \n" }, - applyPrepareArguments: false, - input: { path: "file.txt", edits: [{ oldText: "alpha\n", newText: "ALPHA\n" }] }, - }, - { - name: "fuzzy-smart-quotes", - files: { "file.txt": "it’s a “test” line\n" }, - applyPrepareArguments: false, - input: { path: "file.txt", edits: [{ oldText: "it's a \"test\" line", newText: "plain quotes" }] }, - }, - { - name: "empty-oldtext", - ...gitless, - applyPrepareArguments: false, - input: { path: "file.txt", edits: [{ oldText: "", newText: "x" }] }, - }, - { - name: "no-change", - ...gitless, - applyPrepareArguments: false, - input: { path: "file.txt", edits: [{ oldText: "beta", newText: "beta" }] }, - }, - { - name: "directory-path", - fixture: ["mkdir -p adir"], - applyPrepareArguments: false, - input: { path: "adir", edits: [{ oldText: "a", newText: "b" }] }, - }, - ]; - - const out = []; - for (const tc of cases) { - const dir = makeFixture(tc); - const def = mod.createEditToolDefinition(dir); - let input = structuredClone(tc.input); - let preparedInput; - if (tc.applyPrepareArguments) { - input = def.prepareArguments(input); - preparedInput = input; - } - let result; - try { - const r = await def.execute("id", input, undefined); - result = { ok: true, text: r.content[0].text, details: r.details ?? null }; - } catch (err) { - result = { ok: false, error: err.message }; - } - let finalContent = null; - try { - finalContent = fs.readFileSync(path.resolve(dir, String(tc.input.path)), "utf-8"); - } catch { - finalContent = null; - } - out.push({ - name: tc.name, - files: tc.files ?? {}, - fixture: tc.fixture ?? [], - applyPrepareArguments: tc.applyPrepareArguments, - input: tc.input, - ...(preparedInput !== undefined ? { preparedInput } : {}), - result, - finalContent, - }); - } - writeCorpus("edit", out); - return out.length; -} - -// ================================================================== GROUP 2 -// Fixed commit dates keep commit hashes (printed by `git reset --hard`) -// deterministic across runs. -const FIXED_DATE = "GIT_AUTHOR_DATE='2005-04-07T22:13:13' GIT_COMMITTER_DATE='2005-04-07T22:13:13'"; - -const dirtyRepoFixture = [ - "git init -q .", - "git config user.email t@t", - "git config user.name t", - "echo original > tracked.txt", - "git add tracked.txt", - FIXED_DATE + " git commit -qm init", - "echo modified > tracked.txt", - "echo untracked > untracked.txt", -]; - -const cleanRepoFixture = [ - "git init -q .", - "git config user.email t@t", - "git config user.name t", - "echo original > tracked.txt", - "git add tracked.txt", - FIXED_DATE + " git commit -qm init", -]; - -function bashCase(name, opts) { - return { name, ...opts }; -} - -async function runBashCase(tc) { - let dir; - if (tc.cwdIsDeleted) { - dir = makeFixture({ files: tc.files ?? {}, fixture: tc.fixture ?? [] }); - fs.rmSync(dir, { recursive: true }); - } else { - dir = makeFixture(tc); - } - const bashMod = await loadTs("packages/coding-agent/src/core/tools/bash.ts"); - const def = bashMod.createBashToolDefinition(dir, tc.options); - const input = { command: tc.command }; - if (tc.timeout !== undefined) input.timeout = tc.timeout; - if (tc.allowDestructiveGit !== undefined) input.allowDestructiveGit = tc.allowDestructiveGit; - let result; - try { - const r = await def.execute("id", input, undefined); - result = { ok: true, isError: false, text: r.content[0].text, details: r.details ?? null }; - } catch (err) { - result = { ok: false, isError: true, error: err.message }; - } - const out = { - name: tc.name, - files: tc.files ?? {}, - fixture: tc.fixture ?? [], - command: tc.command, - ...(tc.timeout !== undefined ? { timeout: tc.timeout } : {}), - ...(tc.allowDestructiveGit !== undefined ? { allowDestructiveGit: tc.allowDestructiveGit } : {}), - ...(tc.envBypass ? { envBypass: tc.envBypass } : {}), - ...(tc.cwdIsDeleted ? { cwdIsDeleted: true } : {}), - result, - }; - // Normalize + probe details of fullOutputPath (existence is checked pre-normalization). - const rawPath = result.ok ? result.details?.fullOutputPath : undefined; - if (rawPath) { - let exists = false; - let bytes = null; - try { - const st = fs.statSync(rawPath); - exists = true; - bytes = st.size; - } catch { - exists = false; - } - result.fullOutputFile = { exists, bytes }; - } - return out; -} - -function bashCaseDefs() { - return [ - bashCase("echo-hello", { command: "echo hello" }), - bashCase("exit-code-3", { command: "echo out; exit 3" }), - bashCase("no-output", { command: "true" }), - bashCase("timeout", { command: "sleep 5", timeout: 1 }), - bashCase("stdout-stderr-both", { command: "echo out; echo err1 1>&2; echo out2; echo err2 1>&2" }), - bashCase("line-truncation", { command: "seq 1 2500" }), - bashCase("byte-truncation-multiline", { - command: "for i in $(seq 1 100); do head -c 600 /dev/zero | tr '\\0' x; echo; done", - }), - bashCase("single-huge-line", { - command: "python3 -c \"print('x'*60000)\"", - }), - bashCase("unicode-output", { - command: - "python3 -c \"import sys,time; sys.stdout.write('\\u00e9\\u00e9\\u00e9'); sys.stdout.flush(); time.sleep(0.05); sys.stdout.write('\\u2713'); sys.stdout.flush()\"", - }), - bashCase("destructive-checkout-dirty", { - fixture: dirtyRepoFixture, - command: "git checkout -- .", - }), - bashCase("destructive-allow-bypass", { - fixture: dirtyRepoFixture, - command: "git checkout -- .", - allowDestructiveGit: true, - }), - bashCase("destructive-reset-clean", { - fixture: cleanRepoFixture, - command: "git reset --hard", - }), - bashCase("destructive-quoted", { - command: "echo 'git reset --hard'", - }), - bashCase("destructive-cd-sub", { - fixture: [ - ...cleanRepoFixture, - "mkdir sub", - "cd sub && git init -q . && git config user.email t@t && git config user.name t && echo orig > subfile.txt && git add subfile.txt && " + FIXED_DATE + " git commit -qm subinit", - "cd sub && echo dirty > subfile.txt", - ], - command: "cd sub && git checkout -- .", - }), - bashCase("destructive-comment", { - fixture: cleanRepoFixture, - command: "echo done # git reset --hard", - }), - bashCase("env-bypass", { - fixture: dirtyRepoFixture, - command: "git checkout -- .", - envBypass: true, - }), - bashCase("cwd-missing", { - cwdIsDeleted: true, - command: "echo hi", - }), - ]; -} - -async function bashGroup() { - const defs = bashCaseDefs(); - const out = []; - // env-bypass needs PI_BASH_ALLOW_DESTRUCTIVE_GIT in process.env; run it in a - // child node process (getShellEnv() inherits process.env). - for (const tc of defs) { - if (!tc.envBypass) { - out.push(await runBashCase(tc)); - } - } - // Child run: only the env-bypass case. - const envBypassDef = defs.find((d) => d.envBypass); - const childEnv = { - ...process.env, - PI_BASH_ALLOW_DESTRUCTIVE_GIT: "1", - HARNESS_ONLY_BYPASS: "1", - HARNESS_OUT: path.join(CORPUS, "_env-bypass-part.json"), - }; - const r = spawnSync(process.execPath, [__filename], { encoding: "utf-8", env: childEnv, cwd: process.cwd() }); - if (r.status !== 0) { - throw new Error("env-bypass child run failed:\n" + r.stdout + "\n" + r.stderr); - } - const part = JSON.parse(fs.readFileSync(childEnv.HARNESS_OUT, "utf-8")); - fs.rmSync(childEnv.HARNESS_OUT, { force: true }); - out.push(part); - - writeCorpus("bash", out); - return out.length; -} - -// ================================================================== GROUP 3 -async function previewGroup() { - const cp = await loadTs("packages/coding-agent/src/core/tools/code-preview.ts"); - const inputs = [ - "npm run test -- --watch", - "git add -A && git commit -m x", - "python3 <<'EOF'\nprint('hello')\nEOF", - "%%bash\ncd sub && make", - "curl -s https://api.example.com/v1 -H 'Authorization: Bearer abc123def456'", - "cd sub && make", - "uv run python3 -m pytest tests/x.rs", - "tee -a out.log", - "API_TOKEN = \"abc123\"\nrequests.get(\"https://example.com\", headers={\"Authorization\": \"Bearer sk-live-0123456789\"})", - "python3 -c \"import base64; print(base64.b64encode(b'0123456789'*12))\"", - "cat data.bin", - "echo qwertyuiopasdfghjklzxcvbnm1234567890QWERTYUIOPASDFGHJKLZXCVBNM+/0987654321qazwsxedcrfvtgbyhnujmikolp", - "for i in $(ls /very/long/path/with/many/components/here); do echo processing $i; done", - "from pathlib import Path\nout = Path('out.txt')\nout.write_text('hello')\nimport subprocess\nsubprocess.run('git status', shell=True)", - "print('just printing')", - "%%bash\necho in-bash-cell", - ]; - const out = inputs.map((input) => ({ - input, - bash: cp.previewBashCommand(input), - ipython: cp.previewIpythonCode(input), - })); - writeCorpus("preview", out); - return out.length; -} - -// ================================================================== GROUP 4 -async function truncateGroup() { - const tr = await loadTs("packages/coding-agent/src/core/tools/truncate.ts"); - const cases = [ - { name: "exact-boundary-equal-limits", content: "a\nb\nc", maxLines: 3, maxBytes: 10 }, - { name: "one-line-over-head", content: "a\nb\nc\nd", maxLines: 3, maxBytes: 100 }, - { name: "one-line-over-tail", content: "a\nb\nc\nd", maxLines: 3, maxBytes: 100 }, - { - name: "multibyte-at-byte-boundary", - content: "éééééééééé\néééééééééé\néééééééééé\n", - maxLines: 100, - maxBytes: 24, - }, - { name: "first-line-exceeds-bytes-head", content: "xxxxxxxxxxxxxxxxxxxxxxxx\nshort\n", maxLines: 10, maxBytes: 16 }, - { name: "first-line-exceeds-bytes-tail", content: "xxxxxxxxxxxxxxxxxxxxxxxx\nshort\n", maxLines: 10, maxBytes: 16 }, - { - name: "tail-trailing-blank-partial-rescue", - content: "y".repeat(100) + "\n\n\n", - maxLines: 10, - maxBytes: 50, - }, - { name: "empty-string", content: "", maxLines: 5, maxBytes: 50 }, - { name: "no-trailing-newline", content: "a\nb\nc", maxLines: 2, maxBytes: 100 }, - { name: "byte-limit-tail-simple", content: Array.from({ length: 40 }, (_, i) => "line" + i).join("\n") + "\n", maxLines: 2000, maxBytes: 60 }, - ]; - const out = cases.map((tc) => ({ - name: tc.name, - content: tc.content, - maxLines: tc.maxLines, - maxBytes: tc.maxBytes, - head: tr.truncateHead(tc.content, { maxLines: tc.maxLines, maxBytes: tc.maxBytes }), - tail: tr.truncateTail(tc.content, { maxLines: tc.maxLines, maxBytes: tc.maxBytes }), - })); - writeCorpus("truncate", out); - return out.length; -} - -// ================================================================== GROUP 5 -async function ipythonGroup() { - const ip = await loadTs("packages/coding-agent/src/core/tools/ipython.ts"); - const kernelShared = await loadTs("packages/coding-agent/src/core/kernel/shared.ts"); - const BusyErr = kernelShared.KernelBusyAfterInterruptError; - - function makeProvisioner(executions) { - const calls = { ensure: 0, execute: 0, kill: 0 }; - let i = 0; - const manager = { - execute: async (code, opts) => { - calls.execute++; - const item = executions[Math.min(i++, executions.length - 1)]; - if (item instanceof Error) throw item; - return item; - }, - }; - return { - calls, - ensure: async (_onProgress, _signal) => { - calls.ensure++; - return manager; - }, - kill: async () => { - calls.kill++; - }, - }; - } - - const okResult = (over = {}) => ({ status: "ok", stdout: "", stderr: "", durationMs: 123, ...over }); - - const caseDefs = [ - { - name: "stdout-stderr-result-ordering", - code: "print('out')", - mockResults: [okResult({ stdout: "out\n", stderr: "err\n", result: "42" })], - ctxMode: "none", - }, - { - name: "error-status-traceback", - code: "1/0", - mockResults: [ - { - status: "error", - stdout: "before\n", - stderr: "", - result: undefined, - error: { - ename: "ZeroDivisionError", - evalue: "division by zero", - traceback: ["Traceback (most recent call last):", " File ...: division by zero"], - }, - durationMs: 5, - }, - ], - ctxMode: "none", - }, - { - name: "empty-output", - code: "x = 1", - mockResults: [okResult()], - ctxMode: "none", - }, - { - name: "background-output", - code: "import time; time.sleep(0.01)", - mockResults: [okResult({ stdout: "x", backgroundOutput: "late output\nfrom background" })], - ctxMode: "none", - }, - { - name: "aborted-status", - code: "import time; time.sleep(10)", - mockResults: [okResult({ status: "aborted", stdout: "partial output" })], - ctxMode: "none", - }, - { - name: "busy-then-cancel-no-ui", - code: "print('never')", - mockResults: [new BusyErr()], - ctxMode: "none", - }, - { - name: "busy-then-kill-restart-notice", - code: "print('after restart')", - mockResults: [new BusyErr(), okResult({ stdout: "after restart\n" })], - ctxMode: "ui-kill", - }, - ]; - - const out = []; - for (const tc of caseDefs) { - const prov = makeProvisioner(tc.mockResults); - const def = ip.createIpythonToolDefinition("/tmp", { provisioner: prov }); - const ctx = - tc.ctxMode === "ui-kill" - ? { - hasUI: true, - ui: { - async select(_prompt, _choices, _opts) { - return "Kill kernel and restart"; - }, - setWorkingMessage() {}, - }, - } - : undefined; - let result; - try { - const r = await def.execute("id", { code: tc.code }, undefined, undefined, ctx); - result = { ok: true, isError: r.isError === true, outputText: r.content[0].text }; - } catch (err) { - result = { ok: false, isError: true, error: err.message }; - } - out.push({ - name: tc.name, - code: tc.code, - ctxMode: tc.ctxMode, - mockResults: tc.mockResults.map((m) => (m instanceof Error ? { thrown: m.name, message: m.message } : m)), - provisionerCalls: prov.calls, - result, - }); - } - writeCorpus("ipython", out); - return out.length; -} - -// ================================================================== GROUP 6 -async function schemaGroup() { - const edit = await loadTs("packages/coding-agent/src/core/tools/edit.ts"); - const bash = await loadTs("packages/coding-agent/src/core/tools/bash.ts"); - const ipython = await loadTs("packages/coding-agent/src/core/tools/ipython.ts"); - const defs = { - bash: bash.createBashToolDefinition("/tmp"), - edit: edit.createEditToolDefinition("/tmp"), - ipython: ipython.createIpythonToolDefinition("/tmp"), - }; - const out = []; - for (const [tool, def] of Object.entries(defs)) { - out.push({ - tool, - name: def.name, - label: def.label, - description: def.description, - promptSnippet: def.promptSnippet, - ...(def.executionMode !== undefined ? { executionMode: def.executionMode } : {}), - parameters: def.parameters, - }); - } - writeCorpus("schema", out); - return out.length; -} - -// ======================================================================= main -async function main() { - fs.mkdirSync(CORPUS, { recursive: true }); - if (process.env.HARNESS_ONLY_BYPASS === "1") { - // Child run: execute only the env-bypass bash case, write it to HARNESS_OUT. - const defs = bashCaseDefs().filter((d) => d.envBypass); - const results = []; - for (const tc of defs) results.push(await runBashCase(tc)); - fs.writeFileSync(process.env.HARNESS_OUT, JSON.stringify(deepNorm(results[0]), null, 2) + "\n"); - process.exit(0); - } - const counts = {}; - counts.edit = await editGroup(); - counts.bash = await bashGroup(); - counts.preview = await previewGroup(); - counts.truncate = await truncateGroup(); - counts.ipython = await ipythonGroup(); - counts.schema = await schemaGroup(); - - const total = Object.values(counts).reduce((a, b) => a + b, 0); - console.log("corpus written:", JSON.stringify(counts), "total", total); -} - -main().catch((err) => { - console.error(err); - process.exit(1); -}); diff --git a/scripts/battery/README.md b/scripts/battery/README.md deleted file mode 100644 index e322b1a8655..00000000000 --- a/scripts/battery/README.md +++ /dev/null @@ -1,62 +0,0 @@ -# Perf-wave battery - -The perf wave measures the interactive TUI against the deployed TS -binary (the "ts" side) and a release build of this repo (the "rust" -side), gates the rust medians against the recorded baseline, and is -driven by the Makefile `perf-wave` target: - - make perf-wave - -`perf-wave` runs `ci_perf_wave.sh`, the CI-shaped entry: it creates an -ephemeral Prime sandbox (4 CPU / 16 GB, the spec class the baseline was -recorded on), installs the deployed TS binary plus a fresh release build -of the checkout, runs the wave there, downloads the results, and gates -them (`perf_gate.py` against `perf-baseline.json`). Every timing comes -from the same quiet machine for both sides, which is the whole point of -the sandbox. `PA_BENCH_NO_SANDBOX=1` runs the wave directly on the host -instead (`run_perf_wave.sh` + `perf_wave.py`). - -Files: - -- `ci_perf_wave.sh` — the Makefile entry (sandbox lifecycle, results - download, the gate call) -- `run_perf_wave.sh` — the local runner (same shape as the CI entry, - without the sandbox dance) -- `perf_wave.py` — the driver (dimensions below; accepts --ts-bin / - --rust-bin) -- `sustained_cpu.py` — the sustained-CPU dimension: the interactive TUI - driven through the faux provider — a 30s idle window, a paced plain-text - stream, a paced markdown/code stream, and a long tool-execution turn — - with %CPU sampled per process from /proc and ASSERTED: idle <5% and - streaming <30% of one core, keystroke-to-render mid-stream <50ms, the - paused viewport stable mid-stream, and a double Ctrl+C mid-scroll - terminating the process (bug #6's no-escape invariant) -- `stream_throughput.py` — the stream-throughput dimension (token - throughput of the live render loop, both binaries) -- `perf.py` — the perf measurement helpers the dimensions share: - startup launch-to-ready, keystroke-to-render typing latency, and - cold-resume-to-ready over the same tmux pane channel a real user - types through (both product sides) -- `scale_corpus.py` — the deterministic heavy-scale corpus the resume - dimension replays (the 350-turn / 1078-row corpus perf_wave.py - generates via scale_corpus for its resume dim) -- `perf_gate.py` — the gate (medians vs `perf-baseline.json`, default - threshold 1.10) -- `perf-baseline.json` — the recorded baseline the gate compares against -- `batterylib.py` — the shared harness (side sessions, the deterministic - mock provider, the daemon-reap sweep every harness reuses: - `reap_daemons(needles=[...])` sweeps any `--mode daemon` process whose - argv references the given paths — the graceful `sd` shutdown first, then - the SIGTERM/SIGKILL rounds until a respawned main is gone; the harness - sandboxes pin an isolated per-side TMPDIR so a supervisor's socket lands - under the sandbox root the sweep can name) -- `mock_provider.py` — the deterministic mock provider batterylib drives - (responses are session-scoped queues — a queue is selected per request - by markers in the request's user-message text, so a parent session and - a concurrently running spawned child each get their own scripted - responses deterministically) -- `ts_identity.py` — the shared ts-identity guard: every PATH-driven - harness refuses to run when its "ts" binary is this repo's Rust product -- `../ts_faux_extension.js` — the faux-provider driver extension the TS - side loads (scripted responses read from PRIME_AGENT_FAUX_SCRIPT); - verification harness only, never installed for real users diff --git a/scripts/battery/batterylib.py b/scripts/battery/batterylib.py deleted file mode 100644 index 55940f47650..00000000000 --- a/scripts/battery/batterylib.py +++ /dev/null @@ -1,715 +0,0 @@ -#!/usr/bin/env python3 -"""Shared helpers for the parity battery: isolated per-side environments, -tmux frame capture, a JSONL daemon-wire client, and evidence-file helpers. - -The battery drives the TS binary (ground truth) and the Rust binary side by -side against a deterministic mock provider (mock_provider.py). Nothing here -is part of the product. -""" - -from __future__ import annotations - -import json -import os -import re -import shutil -import socket -import subprocess -import time -from dataclasses import dataclass, field -from pathlib import Path - -NL = chr(10) -# Environment keys set by this box's own prime-agent session/worker; they must -# never leak into spawned daemons, workers, or interactive sessions. -SCRUB_ENV_PREFIXES = ("PRIME_AGENT_INTERNAL", "RLM_") -SCRUB_ENV_KEYS = ( - "TMUX", - "TMUX_PANE", - "PRIME_AGENT_SESSION_DIR", - "PRIME_AGENT_CODING_AGENT_DIR", - "PRIME_AGENT_CODING_AGENT_SESSION_DIR", - "PRIME_AGENT_KERNEL_OWNER_PID", - "PI_CODING_AGENT_DIR", - "PI_CODING_AGENT", -) - -TMUX_SIZE = (120, 36) - - -def scrubbed_env(agent_dir: Path, tmpdir: Path, extra: dict | None = None) -> dict: - """A clean env: no worker/role markers, isolated agent dir + TMPDIR.""" - env = { - k: v - for k, v in os.environ.items() - if not k.startswith(SCRUB_ENV_PREFIXES) and k not in SCRUB_ENV_KEYS - } - env["PRIME_AGENT_CODING_AGENT_DIR"] = str(agent_dir) - env["TMPDIR"] = str(tmpdir) - if extra: - env.update(extra) - return env - - -def rust_binary_staleness(binary: Path, repo_root: Path) -> str | None: - """Why a built Rust binary cannot include this checkout's current - product code (`None` = fresh or unknown). A stale build reports false - divergences against the TS ground truth (run 20260920: the - compaction-abort harness "failed" on main only because the checkout's - target/release binary predates the auto-compaction merge), so the - harnesses fail fast instead of wasting a run. The binary's mtime must - postdate the newest commit touching the product sources; set - PA_BATTERY_ALLOW_STALE_RUST=1 to skip the guard (deliberate - old-build testing). - """ - if os.environ.get("PA_BATTERY_ALLOW_STALE_RUST") == "1": - return None - try: - binary = Path(binary) - if not binary.exists(): - return None # a missing binary is the caller's own error - out = subprocess.run( - ["git", "log", "-1", "--format=%ct", "--", "crates", "prime-agent-runtime"], - cwd=repo_root, - capture_output=True, - text=True, - timeout=10, - ).stdout.strip() - if not out: - return None - newest_product_commit = int(out) - built = binary.stat().st_mtime - # One minute of slack: a build started at the commit's timestamp - # still includes it. - if built + 60 < newest_product_commit: - age_min = int((newest_product_commit - built) / 60) - return ( - f"{binary} predates the newest product commit in {repo_root} " - f"(binary built ~{age_min} min before the newest crates/ or " - "prime-agent-runtime/ change): a stale build reports false " - "divergences. Rebuild (cargo build --release -p pa-cli) or " - "point --rust-bin/PA_PARITY_RUST at a current build; set " - "PA_BATTERY_ALLOW_STALE_RUST=1 to override." - ) - except Exception: - return None - return None - - -def run_cmd( - argv: list[str], - env: dict, - cwd: Path, - timeout: float = 120.0, - stdin_text: str | None = "", -) -> dict: - """Run a command, returning a record with stdout/stderr/exit/duration.""" - start = time.time() - try: - proc = subprocess.run( - argv, - env=env, - cwd=str(cwd), - input=stdin_text, - capture_output=True, - text=True, - timeout=timeout, - ) - return { - "argv": argv, - "exit_code": proc.returncode, - "stdout": proc.stdout, - "stderr": proc.stderr, - "duration_s": round(time.time() - start, 2), - "timeout": False, - } - except subprocess.TimeoutExpired as exc: - return { - "argv": argv, - "exit_code": None, - "stdout": exc.stdout.decode() if isinstance(exc.stdout, bytes) else (exc.stdout or ""), - "stderr": exc.stderr.decode() if isinstance(exc.stderr, bytes) else (exc.stderr or ""), - "duration_s": round(time.time() - start, 2), - "timeout": True, - } - - -class MockProvider: - """One mock-provider process per side, so request logs never interleave.""" - - def __init__(self, battery_dir: Path, port_offset_holder: list[int]): - self.script_path = battery_dir / "mock-script.json" - self.requests_path = Path(str(self.script_path) + ".requests.jsonl") - for path in (self.script_path, self.requests_path): - if path.exists(): - path.unlink() - self.port = None - self._holder = port_offset_holder - self._proc = None - - def set_responses(self, responses: list[dict], queues: list[dict] | None = None) -> None: - """Write the mock script. `responses` is the default queue; each - entry of `queues` is a session-scoped queue ({"name", "match", - "matchModels", "responses"}) served to requests whose model id - (matchModels) or user-message text (match markers) selects it - (mock_provider.py picks per request). An entry may also be a - scripted provider failure: {"error": "", "status": 400}.""" - script = {"responses": responses} - if queues: - script["queues"] = queues - with open(self.script_path, "w") as f: - json.dump(script, f) - - def start(self) -> int: - here = Path(__file__).parent - for _ in range(20): - self._proc = subprocess.Popen( - ["python3", str(here / "mock_provider.py"), str(self.script_path)], - stdout=subprocess.PIPE, - stderr=subprocess.DEVNULL, - text=True, - ) - line = self._proc.stdout.readline() - try: - self.port = int(line.strip()) - return self.port - except ValueError: - self._proc.kill() - time.sleep(0.1) - raise RuntimeError("mock provider failed to start") - - def url(self) -> str: - return f"http://127.0.0.1:{self.port}/v1" - - def requests(self) -> list[dict]: - if not self.requests_path.exists(): - return [] - out = [] - for line in self.requests_path.read_text().splitlines(): - if line.strip(): - out.append(json.loads(line)) - return out - - def stop(self) -> None: - if self._proc: - self._proc.terminate() - try: - self._proc.wait(timeout=5) - except subprocess.TimeoutExpired: - self._proc.kill() - - -@dataclass -class Side: - """One product side (ts or rust) with fully isolated state.""" - - name: str - binary: str - root: Path # evidence/ - agent_dir: Path - work_dir: Path - daemon_socket: Path - mock: MockProvider - env: dict = field(default_factory=dict) - daemon_proc: subprocess.Popen | None = None - - @property - def base_url(self) -> str: - return self.mock.url() - - def write_models_json(self) -> None: - self.agent_dir.mkdir(parents=True, exist_ok=True) - models = { - "providers": { - "prime-inference": { - "api": "openai-completions", - "baseUrl": self.base_url, - "apiKey": "sk-battery", - "models": [ - { - "id": "mock-1", - "name": "Mock 1", - "api": "openai-completions", - "baseUrl": self.base_url, - "contextWindow": 128000, - "maxTokens": 4096, - } - ], - } - } - } - (self.agent_dir / "models.json").write_text(json.dumps(models, indent=1)) - - # -- evidence helpers --------------------------------------------------- - - def evidence(self, flow: str, name: str, text: str) -> Path: - path = self.root / flow / name - path.parent.mkdir(parents=True, exist_ok=True) - path.write_text(text) - return path - - def evidence_json(self, flow: str, name: str, obj) -> Path: - path = self.root / flow / name - path.parent.mkdir(parents=True, exist_ok=True) - path.write_text(json.dumps(obj, indent=1, sort_keys=False)) - return path - - def sessions_dir(self) -> Path: - return self.agent_dir / "sessions" - - def session_files(self) -> list[Path]: - d = self.sessions_dir() - if not d.exists(): - return [] - return sorted(d.glob("*.jsonl"), key=lambda p: p.stat().st_mtime) - - # -- daemon -------------------------------------------------------------- - - def start_daemon(self, timeout: float = 30.0) -> None: - """Start the daemon on this side's socket (identical argv both sides).""" - log = self.root / "daemon.log" - log.parent.mkdir(parents=True, exist_ok=True) - with open(log, "ab") as logfile: - self.daemon_proc = subprocess.Popen( - [self.binary, "--mode", "daemon", "--daemon-socket", str(self.daemon_socket)], - env=self.env, - cwd=str(self.work_dir), - stdin=subprocess.DEVNULL, - stdout=logfile, - stderr=logfile, - ) - deadline = time.time() + timeout - while time.time() < deadline: - if self.daemon_socket.exists(): - try: - with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as probe: - probe.connect(str(self.daemon_socket)) - return - except OSError: - pass - if self.daemon_proc.poll() is not None: - raise RuntimeError( - f"{self.name} daemon exited early: {log.read_text(errors='replace')[-2000:]}" - ) - time.sleep(0.2) - raise RuntimeError(f"{self.name} daemon socket never appeared") - - def stop_daemon(self) -> None: - """Shut this side's daemon down and reap its whole tree (the - shared `reap_daemons` sweep; see its docstring for the leak - history). Only processes whose argv references this side's unique - socket paths are touched, never unrelated daemons.""" - needles = [str(self.daemon_socket)] - tmpdir = self.env.get("TMPDIR") - if tmpdir: - needles.append(tmpdir.rstrip("/")) - reap_daemons(socket_paths=[self.daemon_socket], needles=needles, proc=self.daemon_proc) - - def own_daemon_pids(self) -> list[int]: - """Daemon processes whose argv references this side's daemon - socket or its TMPDIR (the supervisor's socket lives there).""" - exclude = {self.daemon_proc.pid} if self.daemon_proc else set() - needles = [str(self.daemon_socket)] - tmpdir = self.env.get("TMPDIR") - if tmpdir: - needles.append(tmpdir.rstrip("/")) - return daemon_pids_matching(needles, exclude_pids=exclude) - - -def daemon_pids_matching(needles, exclude_pids=()) -> list[int]: - """Live `--mode daemon` processes whose argv references any of - `needles` (daemon socket paths, isolated TMPDIR roots, or a harness - sandbox root containing either). Empty-string needles are dropped: a - bare "" would match every process. The scan walks /proc on Linux and - `ps` on macOS (a harness must reap on both).""" - seen: list[int] = [] - live_needles = [needle for needle in needles if needle] - if Path("/proc").is_dir(): - for proc_dir in Path("/proc").iterdir(): - if not proc_dir.name.isdigit(): - continue - pid = int(proc_dir.name) - if pid in (1, os.getpid()) or pid in exclude_pids: - continue - try: - argv = [ - part.decode(errors="replace") - for part in (proc_dir / "cmdline").read_bytes().split(b"\0") - if part - ] - except OSError: - continue - if "--mode" not in argv or "daemon" not in argv: - continue - if any(needle in part for part in argv for needle in live_needles): - seen.append(pid) - return seen - scan = subprocess.run( - ["ps", "-axo", "pid=,command="], - capture_output=True, - text=True, - env=dict(os.environ, COLUMNS="4096"), - ) - for line in scan.stdout.splitlines(): - parts = line.strip().split(None, 1) - if len(parts) < 2 or not parts[0].isdigit(): - continue - pid = int(parts[0]) - if pid in (1, os.getpid()) or pid in exclude_pids: - continue - argv = parts[1].split() - if "--mode" not in argv or "daemon" not in argv: - continue - # Needles can span argv splits (a socket, sandbox, or TMPDIR path - # with spaces), so they match against the full rendered command - # line, never against the fragments. - if any(needle in parts[1] for needle in live_needles): - seen.append(pid) - return seen - - -def worker_pids_under(cwd_roots=(), exclude_pids=()) -> list[int]: - """Processes whose working directory sits under any of `cwd_roots` - (normalized, trailing-separator-safe). The products' detached session - workers run as ` worker` with no sandbox path in their argv, - but with the session's cwd (the side's work dir), so cwd is the only - scope that reaches them. /proc-only: the macOS fallback reaps the - daemon pair (the argv scan above) and leaves the detached workers to - their own exit paths.""" - if not Path("/proc").is_dir(): - return [] - roots = [] - for root in cwd_roots: - if root: - text = str(root).rstrip("/") + "/" - roots.append(text) - seen: list[int] = [] - for proc_dir in Path("/proc").iterdir(): - if not proc_dir.name.isdigit(): - continue - pid = int(proc_dir.name) - if pid in (1, os.getpid()) or pid in exclude_pids: - continue - try: - cwd = os.readlink(proc_dir / "cwd") - except OSError: - continue - if any(cwd.startswith(root) for root in roots): - seen.append(pid) - return seen - - -def reap_daemons(socket_paths=(), needles=(), proc=None, cwd_roots=()) -> None: - """Reap a harness's daemon tree (the #221 pattern, lifted so every - standalone harness shares it). - - A bare terminate() leaks: the TS product runs a per-run supervisor - (its own `--mode daemon` process on a socket under the side's TMPDIR) - that RESPAWNS a killed main daemon, so SIGTERM alone leaves the pair - behind (run 20260920: every wire-harness pass leaked two daemons; the - #223 close-out: a standalone harness rmtree'd its tempdir and left a - daemon spinning at 74% CPU on the deleted socket). The graceful `sd` wire - shutdown (both products implement it) goes first for every - `socket_paths` entry; `proc` (a directly spawned daemon) is then - terminated; then the sweep kills every `--mode daemon` process whose - argv references any of `needles` — a respawned main or a detached - supervisor — and finally every process whose cwd sits under any of - `cwd_roots` (the detached session workers: ` worker` carries - no sandbox path in its argv, only in its cwd). SIGTERM first, - escalate to SIGKILL, re-check for a respawned main until the - supervisor is gone.""" - for socket_path in socket_paths: - try: - wire = Wire(Path(socket_path)) - wire.send_command("sd", {"type": "shutdown"}) - wire.close() - time.sleep(2) - except Exception: - pass - if proc and proc.poll() is None: - proc.terminate() - try: - proc.wait(timeout=10) - except subprocess.TimeoutExpired: - proc.kill() - exclude = {proc.pid} if proc else set() - for _ in range(3): - pids = daemon_pids_matching(needles, exclude_pids=exclude) - pids += worker_pids_under(cwd_roots, exclude_pids=exclude) - if not pids: - return - for pid in pids: - try: - os.kill(pid, 15) - except (ProcessLookupError, PermissionError): - pass - time.sleep(1.0) - for pid in daemon_pids_matching(needles, exclude_pids=exclude) + worker_pids_under( - cwd_roots, exclude_pids=exclude - ): - try: - os.kill(pid, 9) - except (ProcessLookupError, PermissionError): - pass - time.sleep(0.5) - - -class Wire: - """JSONL daemon-protocol client (protocol 7, the TS wire format).""" - - def __init__(self, socket_path: Path): - self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) - self.sock.settimeout(90) - self.sock.connect(str(socket_path)) - self.buf = b"" - self.events: list = [] - self.hello = self.read_line() - - def send_command(self, command_id: str, command: dict) -> None: - envelope = { - "type": "command", - "id": command_id, - "protocol": {"name": "prime-agent.daemon", "version": 7}, - "command": command, - } - self.sock.sendall((json.dumps(envelope) + chr(10)).encode()) - - def read_line(self, timeout: float = 60.0) -> dict: - """Read one JSON line; raises TimeoutError when nothing arrives.""" - deadline = time.time() + timeout - while bytes([10]) not in self.buf: - remaining = deadline - time.time() - if remaining <= 0: - raise TimeoutError("daemon line timeout") - self.sock.settimeout(max(0.1, remaining)) - chunk = self.sock.recv(65536) - if not chunk: - raise EOFError("daemon closed the connection") - self.buf += chunk - line, self.buf = self.buf.split(bytes([10]), 1) - return json.loads(line.decode()) - - def request(self, command_id: str, command: dict, timeout: float = 60.0) -> dict: - """Send a command; return the response carrying the matching id. - - Side events (non-matching lines) are recorded into `self.events`. - """ - self.send_command(command_id, command) - deadline = time.time() + timeout - while True: - remaining = deadline - time.time() - if remaining <= 0: - raise TimeoutError(f"no response for command {command_id}") - line = self.read_line(timeout=remaining) - if line.get("id") == command_id: - return line - self.events.append(line) - - def drain(self, timeout: float = 3.0) -> list: - """Read whatever the daemon sends for up to `timeout` seconds, - buffering side events into `self.events`; returns the new events.""" - deadline = time.time() + timeout - fresh = [] - while True: - remaining = deadline - time.time() - if remaining <= 0: - return fresh - try: - line = self.read_line(timeout=remaining) - except TimeoutError: - return fresh - fresh.append(line) - self.events.append(line) - - def close(self) -> None: - try: - self.sock.close() - except OSError: - pass - - -# -- tmux --------------------------------------------------------------------- - -def tmux(*args: str, check: bool = True) -> subprocess.CompletedProcess: - """Run tmux on the default socket (never the agentui socket).""" - env = {k: v for k, v in os.environ.items() if k not in ("TMUX", "TMUX_PANE")} - proc = subprocess.run( - ["env", "-u", "TMUX", "-u", "TMUX_PANE", "tmux", *args], - env=env, - capture_output=True, - text=True, - ) - if check and proc.returncode != 0: - raise RuntimeError(f"tmux {args} failed: {proc.stderr}") - return proc - - -def tmux_launch( - session: str, - command: list[str], - env: dict, - cwd: Path, - size: tuple[int, int] = TMUX_SIZE, - unset_keys: tuple[str, ...] = (), -) -> None: - """Create a detached session of `size` running `command` with `env`. - - tmux panes inherit the tmux server's environment, not the client's, so - the pane command is wrapped in `env KEY=VALUE ...` (and TMUX unset) to - guarantee isolation from the ambient agent session. - - `unset_keys` names keys the pane must never see even though they - inherit from the server (dropping them from `env` is not enough: an - inherited key is neither an assignment nor on the scrub list). - - The pane runs with `-c cwd` as its working directory, so a relative - `command[0]` (e.g. `target/release/prime-agent` passed from the repo - root) would resolve against the pane cwd and vanish instantly. Resolve - the binary to an absolute path before it reaches the pane. - """ - if command and not os.path.isabs(command[0]) and "/" in command[0]: - resolved = Path(command[0]).resolve() - if not resolved.exists(): - raise RuntimeError(f"tmux_launch: binary {command[0]} not found at {resolved}") - command = [str(resolved), *command[1:]] - # The pane inherits the tmux server env, so only the deltas (the scrubbed - # overrides) need explicit assignment; everything else stays inherited. - assignment = [ - f"{key}={value}" - for key, value in sorted(env.items()) - if os.environ.get(key) != value or key in ("PRIME_AGENT_CODING_AGENT_DIR", "TMPDIR") - ] - unset = ["-u", "TMUX", "-u", "TMUX_PANE"] - for key in SCRUB_ENV_KEYS: - if key not in ("TMUX", "TMUX_PANE"): - unset += ["-u", key] - # The tmux server inherited this session's worker markers; unset every - # one of them so pane processes never see daemon-worker identity. - for key in list(os.environ): - if key.startswith(SCRUB_ENV_PREFIXES): - unset += ["-u", key] - # The caller's keys ride the same unset (a key that only inherits from - # the server reaches the pane unless it is named here). - for key in unset_keys: - unset += ["-u", key] - # tmux runs multi-argument pane commands through its default shell, so - # wrap explicitly: sh -c 'exec env -u ... KEY=V ... '. - words = ( - ["exec", "/usr/bin/env"] - + unset - + assignment - + list(command) - ) - import shlex - - shell_command = " ".join(shlex.quote(w) for w in words) - tmux( - "new-session", - "-d", - "-x", - str(size[0]), - "-y", - str(size[1]), - "-s", - session, - "-c", - str(cwd), - "/bin/sh", - "-c", - shell_command, - ) - - -def tmux_resize(session: str, size: tuple[int, int]) -> None: - """Resize a detached session's window (frame-parity captures at a - second terminal size).""" - tmux("resize-window", "-t", session, "-x", str(size[0]), "-y", str(size[1]), check=False) - - -def tmux_capture(session: str, pane: str = "0") -> str: - return tmux("capture-pane", "-p", "-t", f"{session}:{pane}").stdout - - -def tmux_send(session: str, keys: str, enter: bool = True) -> None: - tmux("send-keys", "-t", session, keys, "Enter" if enter else "") - - -def children_of(pid: int) -> list[int]: - """Live child pids of `pid` (youngest last), by /proc traversal.""" - out = [] - for proc_dir in Path("/proc").iterdir(): - if not proc_dir.name.isdigit(): - continue - try: - stat = (proc_dir / "stat").read_text() - except OSError: - continue - # The comm field can contain spaces/parens: split after the last ')'. - rest = stat[stat.rfind(")") + 1 :].split() - if len(rest) >= 2 and rest[1] == str(pid): - out.append(int(proc_dir.name)) - return sorted(out) - - -def tmux_kill(session: str) -> None: - tmux("kill-session", "-t", session, check=False) - - -def tmux_wait_text(session: str, pattern: str, timeout: float = 60.0, poll: float = 0.5) -> str: - """Poll a pane until `pattern` appears; returns the final frame.""" - deadline = time.time() + timeout - frame = "" - while time.time() < deadline: - frame = tmux_capture(session) - if re.search(pattern, frame): - return frame - time.sleep(poll) - return frame - - -# -- normalization + diff helpers --------------------------------------------- - -def normalize(value, skip_keys=("timestamp", "id", "parentId", "sessionId", "socketPath", "pid")): - """Recursively normalize volatile keys for cross-side comparisons.""" - - def norm(v): - if isinstance(v, dict): - return {k: ("" if k in skip_keys else norm(val)) for k, val in v.items()} - if isinstance(v, list): - return [norm(x) for x in v] - return v - - return norm(value) - - -def shape_of(value): - """A structural fingerprint: dict keys / list shapes / type names.""" - - def shp(v): - if isinstance(v, dict): - return {k: shp(val) for k, val in sorted(v.items())} - if isinstance(v, list): - return [shp(v[0])] if v else [] - return type(v).__name__ - - return shp(value) - - -def copy_dir_contents(src: Path, dst: Path) -> None: - if not src.exists(): - return - if dst.exists(): - shutil.rmtree(dst) - shutil.copytree(src, dst) - - -def write_report(path: Path, title: str, sections: list[dict]) -> None: - """Write the markdown gap report.""" - lines = [f"# {title}", ""] - for section in sections: - lines.append(f"## {section['title']}") - lines.append("") - for row in section.get("rows", []): - lines.append(f"- {row}") - lines.append("") - path.write_text(NL.join(lines)) diff --git a/scripts/battery/ci_perf_wave.sh b/scripts/battery/ci_perf_wave.sh deleted file mode 100755 index 1b29a9cab99..00000000000 --- a/scripts/battery/ci_perf_wave.sh +++ /dev/null @@ -1,106 +0,0 @@ -#!/usr/bin/env bash -# CI entry for the perf wave (driven by the benchmark workflow on main's tree). -# -# Creates an ephemeral Prime sandbox (4 CPU / 16 GB, the same spec class the -# baseline was recorded on), installs the deployed TS binary plus a fresh -# release build of the checkout, runs scripts/battery/run_perf_wave.sh -# there, downloads the results, gates them against the recorded baseline, -# and terminates the sandbox. Every timing comes from the same quiet -# machine for both sides, which is the whole point of the sandbox. -# -# Requirements on the runner: the `prime` CLI, docker-image access to -# rust:1, tmux/python3 inside the sandbox image, network access. -# -# Environment: -# PA_BENCH_NO_SANDBOX=1 run the wave directly on this runner instead -# PRIME_SANDBOX_NAME sandbox name (default build-perf-benchmark) -# PRIME_BENCH_TRIALS trial count (default 5) -set -euo pipefail -cd "$(dirname "$0")/../.." - -SANDBOX_NAME="${PRIME_SANDBOX_NAME:-build-perf-benchmark}" -TRIALS="${PRIME_BENCH_TRIALS:-5}" - -if [ -n "${PA_BENCH_NO_SANDBOX:-}" ]; then - PRIME_BENCH_TRIALS="$TRIALS" scripts/battery/run_perf_wave.sh - exit $? -fi - -SANDBOX_ID="$( - PRIME_DISABLE_VERSION_CHECK=1 prime sandbox --plain create \ - --name "$SANDBOX_NAME" rust:1 \ - --cpu-cores 4 --memory-gb 16 --disk-size-gb 80 \ - --timeout-minutes 300 -y | - grep -oE '[0-9a-z]{20,}' | tail -1 -)" -cleanup() { - PRIME_DISABLE_VERSION_CHECK=1 prime sandbox --plain delete "$SANDBOX_ID" >/dev/null 2>&1 || true -} -trap cleanup EXIT -echo "== sandbox $SANDBOX_ID" - -run_in_sandbox() { - # 300s exec cap: long work runs detached with a DONE-marker poll. - PRIME_DISABLE_VERSION_CHECK=1 prime sandbox --plain run "$SANDBOX_ID" "$1" -} - -# 1. ship the checkout + the deployed TS release into the sandbox. -git bundle create /tmp/benchmark.bundle --all -prime sandbox --plain upload "$SANDBOX_ID" /tmp/benchmark.bundle /tmp/benchmark.bundle -RELEASE_TREE="$(dirname "$(readlink -f "$(command -v prime-agent)")")/.." -# shellcheck disable=SC2012 -TS_RELEASE_TAR=/tmp/ts-release.tar -tar cf "$TS_RELEASE_TAR" -C "$RELEASE_TREE" . -prime sandbox --plain upload "$SANDBOX_ID" "$TS_RELEASE_TAR" /tmp/ts-release.tar - -cat > /tmp/sb-benchmark.sh <<'EOF' -#!/bin/bash -set -euo pipefail -mkdir -p /opt/repo /opt/ts-release -cd /opt/repo -git clone /tmp/benchmark.bundle repo -cd repo -git checkout "${GITHUB_HEAD_REF:-main}" -git log --oneline -1 -tar xf /tmp/ts-release.tar -C /opt/ts-release -TS_BIN=$(find /opt/ts-release -maxdepth 3 -name prime-agent -type f | head -1) -ln -sf "$TS_BIN" /usr/local/bin/prime-agent -prime-agent --version | head -1 -apt-get update -qq && apt-get install -y -qq tmux procps time -# 2. fresh release build + the wave, detached (the 300s exec cap). -nohup bash -c ' - cd /opt/repo/repo && - PRIME_BENCH_TRIALS="'"$PRIME_BENCH_TRIALS"'" \ - PA_WAVE_RUST_BIN=/opt/repo/repo/target/release/prime-agent \ - scripts/battery/run_perf_wave.sh - echo $? > /opt/wave.exit -' > /opt/wave.log 2>&1 & -echo detached-started -EOF -prime sandbox --plain upload "$SANDBOX_ID" /tmp/sb-benchmark.sh /tmp/sb-benchmark.sh - -# 3. poll the detached wave to completion. -DEADLINE=$(( $(date +%s) + 14400 )) -while true; do - STATUS=$(run_in_sandbox "if [ -f /opt/wave.exit ]; then cat /opt/wave.exit; else echo running; fi" | tail -1 | tr -d '[:space:]') - [ "$STATUS" != "running" ] && break - if [ "$(date +%s)" -gt "$DEADLINE" ]; then - echo "FATAL: sandbox wave exceeded the 4h poll deadline" >&2 - exit 2 - fi - sleep 60 -done -run_in_sandbox "tail -n 40 /opt/wave.log" || true -if [ "$STATUS" != "0" ]; then - echo "FATAL: sandbox wave exited with $STATUS (log above)" >&2 - exit 2 -fi - -# 4. pull the results back and gate them on the runner. -mkdir -p scripts/battery/runs -RUN_DIR="scripts/battery/runs/perf-wave-$(date -u +%Y%m%dT%H%M%SZ)" -mkdir -p "$RUN_DIR" -RUN_IN_SANDBOX_DIR=$(run_in_sandbox "ls -1dt /opt/repo/repo/scripts/battery/runs/perf-wave-* | head -1" | grep perf-wave | head -1) -prime sandbox --plain download "$SANDBOX_ID" "$RUN_IN_SANDBOX_DIR/results.json" "$RUN_DIR/results.json" -python3 scripts/battery/perf_gate.py --results "$RUN_DIR/results.json" -echo "== wave results: $RUN_DIR" diff --git a/scripts/battery/mock_provider.py b/scripts/battery/mock_provider.py deleted file mode 100644 index e392238012a..00000000000 --- a/scripts/battery/mock_provider.py +++ /dev/null @@ -1,297 +0,0 @@ -#!/usr/bin/env python3 -"""Deterministic OpenAI-compatible mock provider for the parity battery. - -Serves `/v1/chat/completions` (SSE streaming) and `/v1/models` from a JSON -script file, so the TS binary and the Rust binary can be driven side by side -with identical model responses. Not part of the product; battery harness -only. - -Script file format: - { - "responses": [ - {"text": "hello"}, - {"toolCall": {"name": "bash", "arguments": {"command": "echo hi"}}}, - {"error": "prompt is too long: 213462 tokens > 200000 maximum", "status": 400}, - {"text": "done", "delayMs": 500, "usage": {"prompt_tokens": 100, "completion_tokens": 10, "total_tokens": 110, "prompt_tokens_details": {"cached_tokens": 80}}} - ], - "queues": [ - {"name": "child", "match": ["child task text"], "matchModels": ["mock-1"], "responses": [{"text": "child reply"}]} - ] - } -Optional per-response keys: `delayMs` (stream starts after the delay), `usage` -(overrides the reported token usage, so a flow can push the session past a -context/compaction threshold deterministically), and `error`/`status` (a -scripted provider failure: the non-2xx answer carries the OpenAI error body, -so a flow can script overflow probes identically for both binaries). - -Responses are SESSION-SCOPED, not global. The chat-completions wire carries -no session id, so a queue is selected per request: the first queue whose -`matchModels` entry equals the request's model id, or whose `match` marker -appears in the concatenated text of the request's user-role messages, serves -the request; a request that matches no queue falls through to the default -`responses` queue. This keeps a parent session and a spawned child session -(which race the provider concurrently) on independent scripted response -cursors instead of popping one shared queue in arrival order, and keeps -model-routed flows (a scripted turn model vs a dashboard status-line model) -off each other's cursors. User-role text is the discriminator because a -parent's post-tool continuation embeds the child's task text in tool-call -arguments and tool results; matching those would misroute the parent. -Each queue pops its next scripted response per matching request -(round-robin when a queue runs dry: its last entry repeats). Every request, -the raw request body, and the serving queue's name are logged to -`"); - // The angle brackets escape too: the payload renders fully - // entity-encoded, never as raw markup. + // The payload renders fully entity-encoded, never as raw + // markup. assert!( page.contains("<script>&"'</script>"), "{page}" diff --git a/crates/pa-ai/src/oauth/github_copilot.rs b/crates/pa-ai/src/oauth/github_copilot.rs index 1d60534ef0b..d68397e63b4 100644 --- a/crates/pa-ai/src/oauth/github_copilot.rs +++ b/crates/pa-ai/src/oauth/github_copilot.rs @@ -1,18 +1,6 @@ -//! The GitHub Copilot OAuth flow — the port of -//! `packages/ai/src/utils/oauth/github-copilot.ts` (+ -//! `copilot-client-version.ts`): the optional GitHub Enterprise -//! domain prompt, the device-code flow against the GitHub login -//! endpoints (with the client impersonation headers and the -//! `slow_down` backoff), the Copilot internal token exchange, the -//! model-policy enabling after login, and the token refresh. The -//! credentials the flow returns carry the TS shape (`access`, the -//! GitHub `refresh` token, `expires`, the `enterpriseUrl`) and -//! persist under the provider id `github-copilot`. -//! -//! Cancellation follows the fleet's cooperative pattern (#2770): the -//! driving surface marks a shared flag when it exits; the poll loop -//! checks it between its wait steps, so an exited surface never -//! receives a completed login. +//! The GitHub Copilot OAuth flow: the enterprise-domain prompt, the +//! device-code flow (impersonation headers, `slow_down` backoff), the +//! Copilot token exchange, the model-policy enabling, and the refresh. use std::time::Duration; @@ -21,62 +9,47 @@ use url::Url; use super::provider_http::{ProviderHttp, ProviderHttpMethod, ProviderHttpRequest}; use super::types::{OAuthLoginUi, OAuthPrompt}; -/// The OAuth app the TS flow ships (TS stores the id base64-encoded; -/// the decoded value is the wire value). +/// TS stores the id base64-encoded; the decoded value is the wire value. pub const COPILOT_CLIENT_ID: &str = "Iv1.b507a08c87ecfe98"; -/// TS `COPILOT_CLIENT_USER_AGENT` (the client identity the flow and -/// the generated catalog both send — keep both in sync by editing the -/// catalog generator too). +/// The client identity the flow and the generated catalog both send +/// — keep both in sync by editing the catalog generator too. pub const COPILOT_CLIENT_USER_AGENT: &str = "GitHubCopilotChat/0.48.1"; -/// TS `COPILOT_CLIENT_HEADERS`. pub const COPILOT_CLIENT_HEADERS: [(&str, &str); 4] = [ ("User-Agent", COPILOT_CLIENT_USER_AGENT), ("Editor-Version", "vscode/1.136.1"), ("Editor-Plugin-Version", "copilot-chat/0.48.1"), ("Copilot-Integration-Id", "vscode-chat"), ]; -/// TS `INITIAL_POLL_INTERVAL_MULTIPLIER`. const INITIAL_POLL_INTERVAL_MULTIPLIER: f64 = 1.2; -/// TS `SLOW_DOWN_POLL_INTERVAL_MULTIPLIER`. const SLOW_DOWN_POLL_INTERVAL_MULTIPLIER: f64 = 1.4; -/// One request's bound (the port's request-timeout norm; TS `fetch` -/// carries no explicit timeout here). +/// The port's request bound; TS `fetch` carries no explicit timeout +/// here. pub const DEFAULT_TOKEN_TIMEOUT_MS: u64 = 30_000; -/// The refresh grant's request bound: the refresh runs under the auth -/// store's file lock, which a peer declares stale after 10 seconds — the -/// request must fit inside that window so a slow endpoint fails the -/// refresh (kept for a retry) instead of holding the lock past its -/// staleness. +/// The refresh runs under the auth store's file lock, which a peer declares stale after 10 seconds; +/// the request must fit inside that window. pub const REFRESH_TIMEOUT_MS: u64 = 8_000; -/// The credential's expiry skew (TS `5 * 60 * 1000`). const EXPIRY_SKEW_MS: i64 = 5 * 60 * 1000; -/// The device flow's requested scope (TS `scope: "read:user"`). const DEVICE_SCOPE: &str = "read:user"; /// The cancel error the driving surface maps to the silent cancelled /// outcome. pub const LOGIN_CANCELLED: &str = "Login cancelled"; -/// The poll's cancel-check step (#2770 — the flag is checked between -/// the wait steps). const CANCEL_POLL_INTERVAL: Duration = Duration::from_millis(250); -/// The credentials the flow returns and persists (TS -/// `OAuthCredentials` plus the Copilot provider's `enterpriseUrl`). #[derive(Debug, Clone, PartialEq, Eq)] pub struct CopilotCredentials { /// The Copilot internal token (the API's bearer). pub access: String, /// The GitHub OAuth access token (the refresh source). pub refresh: String, - /// Wall-clock epoch milliseconds (TS `expires_at * 1000 - 5 - /// minutes`). + /// Wall-clock epoch milliseconds. pub expires: i64, - /// The GitHub Enterprise domain the login ran against (`None` for - /// github.com; TS `enterpriseUrl`). + /// The GitHub Enterprise domain the login ran against (`None` + /// for github.com). pub enterprise_url: Option, } -/// TS `normalizeDomain`: a URL or bare domain reduced to its hostname -/// (`None` on an empty input or an unparseable one). +/// A URL or bare domain reduced to its hostname (`None` on an empty +/// or unparseable input). pub fn normalize_domain(input: &str) -> Option { let trimmed = input.trim(); if trimmed.is_empty() { @@ -92,7 +65,6 @@ pub fn normalize_domain(input: &str) -> Option { .map(|url| url.host_str().unwrap_or_default().to_string()) } -/// The provider's endpoint set for one domain (TS `getUrls`). fn urls_for(domain: &str) -> DeviceUrls { DeviceUrls { device_code_url: format!("https://{domain}/login/device/code"), @@ -109,10 +81,9 @@ struct DeviceUrls { copilot_token_url: String, } -/// TS `getBaseUrlFromToken`: the API base URL the Copilot token -/// carries (`proxy-ep` rewritten onto `api.`), if any. +/// The API base URL the Copilot token carries (`proxy-ep` rewritten +/// onto `api.`), if any. pub fn get_base_url_from_token(token: &str) -> Option { - // TS matches `/proxy-ep=([^;]+)/` on the token string. let start = token.find("proxy-ep=")?; let rest = &token[start + "proxy-ep=".len()..]; let proxy_host = rest.split(';').next().unwrap_or_default(); @@ -125,8 +96,8 @@ pub fn get_base_url_from_token(token: &str) -> Option { Some(format!("https://{api_host}")) } -/// TS `getGitHubCopilotBaseUrl`: the token's carried endpoint wins, -/// then the enterprise domain, then the individual default. +/// The token's carried endpoint wins, then the enterprise domain, +/// then the individual default. pub fn get_github_copilot_base_url(token: Option<&str>, enterprise_domain: Option<&str>) -> String { if let Some(url) = token.and_then(get_base_url_from_token) { return url; @@ -137,22 +108,16 @@ pub fn get_github_copilot_base_url(token: Option<&str>, enterprise_domain: Optio "https://api.individual.githubcopilot.com".to_string() } -/// Run the login (TS `loginGitHubCopilot`): the optional enterprise -/// domain prompt, the device flow, the Copilot token exchange, and -/// the model-policy enabling. -/// +/// The enterprise-domain prompt, the device flow, the token exchange, and the model-policy +/// enabling. /// # Errors /// -/// Returns an error when the surface cancelled the login -/// ([`LOGIN_CANCELLED`]), the enterprise input is not a domain, the -/// device flow fails or times out, or the Copilot token exchange -/// fails. +/// Returns an error when the login is cancelled ([`LOGIN_CANCELLED`]), the +/// enterprise input is not a domain, the device flow fails, or the exchange fails. pub async fn login_github_copilot( http: &dyn ProviderHttp, ui: &dyn OAuthLoginUi, ) -> Result { - // An exited surface never starts: no prompt, no browser launch (the - // #2770 flag is the seam). if ui.is_cancelled() { return Err(LOGIN_CANCELLED.to_string()); } @@ -190,9 +155,7 @@ pub async fn login_github_copilot( Ok(credentials) } -/// Refresh an expired credential (TS `refreshGitHubCopilotToken`): -/// the stored GitHub token exchanges for a fresh Copilot internal -/// token. +/// Refresh: the stored GitHub token exchanges for a fresh Copilot internal token. /// /// # Errors /// @@ -214,8 +177,6 @@ pub async fn refresh_github_copilot_token( for (name, value) in COPILOT_CLIENT_HEADERS { headers.push((name.to_string(), value.to_string())); } - // The refresh runs under the auth store's lock: the request fits - // inside the lock's staleness window (REFRESH_TIMEOUT_MS). let response = http .request( ProviderHttpRequest { @@ -260,9 +221,8 @@ pub async fn refresh_github_copilot_token( }) } -/// TS `enableAllGitHubCopilotModels`: enable every catalog model's -/// policy after login so the subscription models are usable -/// (failures are ignored — the account may already carry some). +/// Enable every catalog model's policy after login so the subscription models are usable; failures +/// are ignored (the account may already carry some). async fn enable_all_github_copilot_models( http: &dyn ProviderHttp, token: &str, @@ -287,14 +247,12 @@ async fn enable_all_github_copilot_models( body: Some(r#"{"state":"enabled"}"#.to_string()), follow_redirects: true, }; - // TS swallows both the failed status and the thrown request. if let Ok(response) = http.request(request, DEFAULT_TOKEN_TIMEOUT_MS).await { let _ = response.ok(); } } } -/// One device-code response (TS `DeviceCodeResponse`). // Field names mirror the TS `DeviceCodeResponse` wire payload; renaming is a contract change. #[allow(clippy::struct_field_names)] struct DeviceCode { @@ -305,8 +263,6 @@ struct DeviceCode { expires_in: u64, } -/// TS `startDeviceFlow`: the device authorization request with the -/// client's user agent. async fn start_device_flow(http: &dyn ProviderHttp, domain: &str) -> Result { let urls = urls_for(domain); let body = url::form_urlencoded::Serializer::new(String::new()) @@ -387,11 +343,7 @@ async fn start_device_flow(http: &dyn ProviderHttp, domain: &str) -> Result Result<(), String> { let deadline = std::time::Instant::now() + total; loop { @@ -523,7 +473,6 @@ async fn cancel_aware_sleep(ui: &dyn OAuthLoginUi, total: Duration) -> Result<() } } -/// TS `response.statusText` (a reason phrase per status). fn status_text(status: u16) -> &'static str { match status { 400 => "Bad Request", @@ -550,9 +499,8 @@ mod tests { use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::{Arc, Mutex}; - /// A scripted transport: queued responses per url (popped in - /// order), a static map, and a catch-all default for the model - /// policy POSTs; every request is recorded. + /// Queued responses per url (popped in order), a static map, and a + /// catch-all default for the model-policy POSTs. struct ScriptedHttp { queued: Mutex>>, fixed: HashMap, @@ -628,7 +576,6 @@ mod tests { } } - /// One scripted UI answer. enum ScriptedAnswer { Once(Option), } @@ -652,8 +599,6 @@ mod tests { } } - /// The scripted login surface: the enterprise prompt, the auth - /// block, the progress lines, and the cancel flag. struct ScriptedUi { prompt: ScriptedAnswer, auth_url: Mutex>, @@ -723,8 +668,8 @@ mod tests { } } - /// The github.com happy flow's scripted endpoints (a fast poll: - /// interval 0, pending once, then the token). + /// The github.com happy flow (a fast poll: interval 0, pending + /// once, then the token). fn github_http() -> ScriptedHttp { ScriptedHttp::new() .queue( @@ -759,7 +704,6 @@ mod tests { assert_eq!(credentials.access, "copilot-token"); assert_eq!(credentials.refresh, "gh-token"); assert_eq!(credentials.enterprise_url, None); - // The device-code request: the client id and the scope. let device = &http.bodies_for("https://github.com/login/device/code")[0]; assert!(device .body @@ -771,12 +715,10 @@ mod tests { .as_deref() .unwrap() .contains("scope=read%3Auser")); - // The poll request: the device-code grant. let poll = &http.bodies_for("https://github.com/login/oauth/access_token")[1]; let body = poll.body.as_deref().unwrap(); assert!(body.contains("device_code=dev-1")); assert!(body.contains("grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code")); - // The Copilot token exchange: the impersonation headers ride. let internal = &http.bodies_for("https://api.github.com/copilot_internal/v2/token")[0]; assert_eq!(internal.method, ProviderHttpMethod::Get); let header = |name: &str| { @@ -790,14 +732,11 @@ mod tests { assert_eq!(header("Authorization"), "Bearer gh-token"); assert_eq!(header("Editor-Version"), "vscode/1.136.1"); assert_eq!(header("Copilot-Integration-Id"), "vscode-chat"); - // The auth block carries the TS user-code line. let (url, instructions) = ui.captured_auth(); assert_eq!(url, "https://github.com/login/device"); assert_eq!(instructions.as_deref(), Some("Enter code: ABCD-1234")); // TS: expires = expires_at * 1000 - 5 minutes. assert_eq!(credentials.expires, 4_000_000_000_000 - EXPIRY_SKEW_MS); - // The model-policy pass runs for every catalog model with the - // policy body. let policies = http.bodies_for("https://api.individual.githubcopilot.com/models/"); let models = crate::models_generated::get_models("github-copilot"); assert_eq!( @@ -848,7 +787,6 @@ mod tests { Some("company.ghe.com") ); assert_eq!(credentials.access, "copilot-e"); - // The policy pass routes onto the enterprise base URL. assert!(!http .bodies_for("https://copilot-api.company.ghe.com/models/") .is_empty()); @@ -881,8 +819,7 @@ mod tests { r#"{"device_code":"dev-1","user_code":"CODE-1","verification_uri":"https://github.com/login/device","interval":0,"expires_in":900}"#, )], ) - // The poll never answers a token; the cancel flips after the - // auth block lands. + // The poll never answers a token. .catch_all(ScriptedHttp::entry( 200, r#"{"error":"authorization_pending"}"#, @@ -896,8 +833,8 @@ mod tests { async move { login_github_copilot(flow_http.as_ref(), flow_ui.as_ref()).await }, ) }; - // Readiness-wait for the URL (bounded: a missing URL fails the - // test instead of hanging the cancel flip). + // Readiness-wait for the URL (bounded: a missing URL fails + // the test). let deadline = std::time::Instant::now() + Duration::from_secs(5); while ui.auth_url.lock().unwrap().is_none() { assert!( @@ -1009,7 +946,6 @@ mod tests { Some("company.ghe.com") ); assert_eq!(normalize_domain("not a domain"), None); - // The token's proxy endpoint rewrites onto api. assert_eq!( get_base_url_from_token("tid=1;exp=2;proxy-ep=proxy.individual.githubcopilot.com;x=3") .as_deref(), diff --git a/crates/pa-ai/src/oauth/mod.rs b/crates/pa-ai/src/oauth/mod.rs index a239aa1307a..fbb99afbe39 100644 --- a/crates/pa-ai/src/oauth/mod.rs +++ b/crates/pa-ai/src/oauth/mod.rs @@ -1,18 +1,7 @@ -//! The AI library's OAuth flows (TS `packages/ai/src/utils/oauth`): -//! the `ChatGPT` Plus/Pro (Codex Subscription) provider — the PKCE -//! authorization request, the localhost callback server, the token -//! exchange, the JWT account-id claim, and the token refresh — plus the -//! Anthropic (Claude Pro/Max) PKCE flow with its own localhost -//! callback, the GitHub Copilot device flow with the client -//! impersonation headers and the post-login model-policy pass, and the -//! xAI (Grok) device flow with strict response validation. -//! -//! The flows are transport-agnostic: the Codex flow issues its token -//! requests through the [`CodexHttp`] seam, the other three through -//! [`ProviderHttp`] (the JSON bodies, the GETs, and the custom -//! headers their TS `fetch` shapes carry), so tests script the -//! endpoints (the TS suite stubs `fetch` the same way) and the -//! product plugs in one reqwest client. +//! The subscription OAuth flows: Codex, Anthropic, GitHub Copilot, and +//! xAI. Transport-agnostic: the Codex flow issues its token requests +//! through [`CodexHttp`], the other three through [`ProviderHttp`]; +//! tests script the endpoints. mod anthropic; mod anthropic_callback; @@ -49,8 +38,6 @@ pub use xai::{ use std::future::Future; use std::time::Duration; -/// One token-endpoint POST's outcome (TS `fetch`'s `response.status` + -/// `response.text()`). #[derive(Debug, Clone, PartialEq, Eq)] pub struct CodexHttpResponse { pub status: u16, @@ -58,20 +45,16 @@ pub struct CodexHttpResponse { } impl CodexHttpResponse { - /// Whether the endpoint answered success (TS `response.ok`). fn ok(&self) -> bool { (200..300).contains(&self.status) } } -/// The HTTP transport the OAuth flows issue their token requests -/// through: one form-encoded POST per call (TS `fetch` with -/// `Content-Type: application/x-www-form-urlencoded`). Dyn-dispatch on -/// purpose: the product plugs in a reqwest client, tests script the -/// responses. +/// The HTTP transport for the Codex flow's token requests: one form-encoded POST per call. +/// Dyn-dispatch on purpose: the product plugs in a reqwest client, tests script the responses. pub trait CodexHttp: Send + Sync { /// One POST of a form-encoded body; the error string is the - /// transport's failure (TS the `fetch` throw). + /// transport's failure. fn post_form<'a>( &'a self, url: &'a str, @@ -80,8 +63,7 @@ pub trait CodexHttp: Send + Sync { ) -> std::pin::Pin> + Send + 'a>>; } -/// The production transport: one reqwest client per request, bounded by -/// the request timeout (the port's prime transport shape). +/// The production transport: one reqwest client per request. pub struct ReqwestCodexHttp; impl Default for ReqwestCodexHttp { @@ -91,8 +73,6 @@ impl Default for ReqwestCodexHttp { } impl ReqwestCodexHttp { - /// Construction is trivial: the client is built per request, so - /// there is nothing to fail here. #[must_use] pub fn new() -> Self { ReqwestCodexHttp @@ -136,8 +116,6 @@ impl CodexHttp for ReqwestCodexHttp { mod tests { use super::*; - /// A scripted transport (url -> response); unknown urls fail the - /// request (the TS suite throws on unexpected fetches). struct ScriptedHttp(std::collections::HashMap); impl ScriptedHttp { @@ -183,7 +161,6 @@ mod tests { assert_eq!(response.status, 200); assert_eq!(response.body, r#"{"ok":true}"#); assert!(response.ok()); - // An unscripted url fails the request. assert!(http .post_form("https://other.example/token", "", 1) .await diff --git a/crates/pa-ai/src/oauth/openai_codex.rs b/crates/pa-ai/src/oauth/openai_codex.rs index fd0ae7790ba..5fc0dcb0552 100644 --- a/crates/pa-ai/src/oauth/openai_codex.rs +++ b/crates/pa-ai/src/oauth/openai_codex.rs @@ -1,16 +1,7 @@ -//! The `ChatGPT` Plus/Pro (Codex Subscription) OAuth flow — the port of -//! `packages/ai/src/utils/oauth/openai-codex.ts` (+ `pkce.ts`): the PKCE -//! authorization request against the app registration, the localhost -//! callback server raced against the manual paste, the token exchange, -//! the JWT account-id claim, and the token refresh. The credentials the -//! flow returns carry the TS shape (`access`, `refresh`, `expires`, -//! `accountId`) and persist under the provider id `openai-codex`. -//! -//! Cancellation follows the fleet's cooperative pattern (#2770): the -//! driving surface marks a shared flag when it exits; the flow checks it -//! between the race's poll steps and before its network steps, so an -//! exited surface never receives a completed login (a task abort cannot -//! reach a started blocking body). +//! The `ChatGPT` (Codex Subscription) OAuth flow: the PKCE request, the +//! localhost callback server raced against the manual paste, the token +//! exchange, and the refresh. Cancellation is cooperative: the surface +//! marks a shared flag on exit; the flow checks it between poll steps. use std::fmt::Write as _; use std::future::Future; @@ -25,96 +16,61 @@ use url::Url; use super::callback::CodexCallbackServer; use super::CodexHttp; -/// The app registration the TS flow ships (TS `CLIENT_ID`). pub const OPENAI_CODEX_CLIENT_ID: &str = "app_EMoamEEZ73f0CkXaXp7hrann"; -/// TS `AUTHORIZE_URL`. const AUTHORIZE_URL: &str = "https://auth.openai.com/oauth/authorize"; -/// TS `TOKEN_URL`. const TOKEN_URL: &str = "https://auth.openai.com/oauth/token"; -/// The registered redirect (TS `REDIRECT_URI`): the callback server's -/// own address. +/// The registered redirect: the callback server's own address. const REDIRECT_URI: &str = "http://localhost:1455/auth/callback"; -/// TS `SCOPE`. const SCOPE: &str = "openid profile email offline_access"; -/// The TS flow's default originator. pub const DEFAULT_ORIGINATOR: &str = "pi"; -/// One token request's bound (the port's request-timeout norm). pub const DEFAULT_TOKEN_TIMEOUT_MS: u64 = 30_000; -/// The refresh grant's tighter bound: the auth storage runs it under its -/// file lock, which a peer declares stale after 10 seconds — the request -/// must fit inside that window so a slow endpoint fails the refresh -/// (kept for a retry) instead of holding the lock past its staleness. +/// The refresh runs under the auth storage's file lock, which a peer declares stale after 10 +/// seconds; the request must fit inside that window. pub const REFRESH_TIMEOUT_MS: u64 = 8_000; -/// TS the `onAuth` instructions line. const AUTH_INSTRUCTIONS: &str = "A browser window should open. Complete login to finish."; -/// TS the `onPrompt` fallback line. const PROMPT_MESSAGE: &str = "Paste the authorization code (or full redirect URL):"; -/// The cancel error the driving surface maps to the silent cancelled -/// outcome (TS the dialog throws the same text; `auth-flows.ts` matches -/// it). +/// The cancel error the driving surface maps to the silent cancelled outcome. pub const LOGIN_CANCELLED: &str = "Login cancelled"; -/// The race's poll step: how often the loop re-checks the cooperative -/// cancel flag (the #2770 pattern — the flag is checked between poll -/// steps). const CANCEL_POLL_INTERVAL: Duration = Duration::from_millis(250); -/// The credentials the flow returns and persists (TS `OAuthCredentials` -/// plus the codex provider's `accountId`). #[derive(Debug, Clone, PartialEq, Eq)] pub struct OAuthCredentials { pub access: String, pub refresh: String, - /// Wall-clock epoch milliseconds (TS `Date.now() + expires_in * 1000`). + /// Wall-clock epoch milliseconds. pub expires: i64, pub account_id: String, } -/// The login's UI surface (TS `OAuthLoginCallbacks`): the browser URL -/// block, the manual paste racing the browser callback, and the -/// fallback prompt. Implementations render the inline auth panel (the -/// TUI) or script the flow (tests). +/// The login's UI surface: present the authorization URL, take the +/// manual paste racing the browser callback, and the fallback prompt. pub trait CodexLoginUi: Send + Sync { - /// TS `onAuth`: the authorization URL to open, plus the flow's - /// instructions line. fn on_auth(&self, url: &str, instructions: &str); - /// TS `onManualCodeInput`: the paste racing the browser callback; - /// `None` when the surface offers none. Resolving `None` cancels + /// The paste racing the browser callback; resolving `None` cancels /// the login. fn on_manual_code_input(&self) -> Option> + Send>>>; - /// TS `onPrompt`: the fallback prompt when neither the callback - /// nor the paste produced a code. Resolving `None` cancels the - /// login. + /// The fallback prompt when neither the callback nor the paste + /// produced a code; resolving `None` cancels the login. fn on_prompt(&self, message: &str) -> Pin> + Send>>; - /// The driving surface's cooperative cancel state: `true` once the - /// pane that mounted the login exited. The flow checks it between - /// the race's poll steps and before its network steps — a task - /// abort cannot reach a started blocking body, so the pane marks - /// this instead (#2770). The default (`false`) serves the surfaces - /// that never cancel mid-flow. + /// `true` once the pane that mounted the login exited: a task abort + /// cannot reach a started blocking body, so the pane marks this. fn is_cancelled(&self) -> bool { false } } -/// Run the login (TS `loginOpenAICodex`): build the PKCE request, start -/// the callback server, present the URL, race the browser callback -/// against the manual paste, exchange the code, and return the -/// credentials to persist. +/// Race the browser callback against the manual paste, exchange the +/// code, and return the credentials to persist. /// /// # Errors /// -/// Returns an error when the surface cancelled the login -/// ([`LOGIN_CANCELLED`]), the pasted redirect's state mismatches, no -/// authorization code ever arrives, the token exchange fails, or the -/// access token carries no account id. +/// Returns an error when the login is cancelled ([`LOGIN_CANCELLED`]), the +/// paste mismatches, the exchange fails, or the token carries no account id. pub async fn login_openai_codex( http: &dyn CodexHttp, ui: &dyn CodexLoginUi, originator: &str, ) -> Result { - // The surface exited before the flow started: no server, no - // browser launch — the exit ends the flow (the first of the - // between-poll cancel checks, #2770). if ui.is_cancelled() { return Err(LOGIN_CANCELLED.to_string()); } @@ -125,9 +81,6 @@ pub async fn login_openai_codex( ui.on_auth(&url, AUTH_INSTRUCTIONS); let code = wait_for_code(&callback, ui, &state).await?; - // The pane exited while the login waited: no exchange, no - // credential — the exit ends the flow (TS the dialog's abort - // signal; #2770: the flag is the seam). if ui.is_cancelled() { return Err(LOGIN_CANCELLED.to_string()); } @@ -141,12 +94,11 @@ pub async fn login_openai_codex( }) } -/// Refresh an expired credential (TS `refreshOpenAICodexToken`). +/// Refresh an expired credential. /// /// # Errors /// -/// Returns an error when the token refresh fails or the fresh access -/// token carries no account id. +/// Returns an error when the token refresh fails or the fresh access token carries no account id. pub async fn refresh_openai_codex_token( http: &dyn CodexHttp, refresh_token: &str, @@ -161,16 +113,12 @@ pub async fn refresh_openai_codex_token( }) } -/// One token response (TS `TokenSuccess`). struct TokenSuccess { access: String, refresh: String, expires: i64, } -/// The race + the fallbacks (TS `loginOpenAICodex`'s middle): the -/// browser callback against the manual paste, then the prompt fallback. -/// The tick re-checks the cooperative cancel between poll steps. async fn wait_for_code( callback: &CodexCallbackServer, ui: &dyn CodexLoginUi, @@ -188,8 +136,6 @@ async fn wait_for_code( let wait = callback.wait_for_code(); tokio::pin!(wait); let mut tick = tokio::time::interval(CANCEL_POLL_INTERVAL); - // The outcome of the race: the callback's settled code (its state - // was validated by the server), or the manual paste's answer. let raced = loop { if ui.is_cancelled() { return Err(LOGIN_CANCELLED.to_string()); @@ -201,17 +147,12 @@ async fn wait_for_code( } }; let code: Option = match raced { - // A settled callback (the server validated the state). CallbackOutcome::Code(Some(code)) => Some(code), - // A settled-empty wait (a bind failure leaves the dead server): - // with a paste surface TS awaits the manual promise before the - // prompt fallback; without one the prompt is the only path. + // A settled-empty wait (a bind failure leaves the dead server). CallbackOutcome::Code(None) => { if manual_available { match answer_or_cancelled(ui, manual_answer).await { Ok(Some(input)) => parse_paste(&input, state)?, - // A cancelled paste answer and a cancelled wait both - // end the login. Ok(None) | Err(_) => return Err(LOGIN_CANCELLED.to_string()), } } else { @@ -224,16 +165,13 @@ async fn wait_for_code( if let Some(code) = code { return Ok(code); } - // The fallback prompt (TS `onPrompt`): neither the callback nor the - // paste produced a code. let answer = answer_or_cancelled(ui, ui.on_prompt(PROMPT_MESSAGE)).await?; let input = answer.ok_or_else(|| LOGIN_CANCELLED.to_string())?; parse_paste(&input, state)?.ok_or_else(|| "Missing authorization code".to_string()) } -/// Await one answer while re-checking the cooperative cancel between -/// poll steps (the surface may exit without ever answering — a pending -/// paste or prompt must not hold a cancelled flow). +/// Await one answer while re-checking the cancel flag: the surface may +/// exit without ever answering. async fn answer_or_cancelled( ui: &dyn CodexLoginUi, answer: impl Future, @@ -251,8 +189,6 @@ async fn answer_or_cancelled( } } -/// Parse one pasted input and check its echoed state (TS -/// `parseAuthorizationInput` + the state guard). fn parse_paste(input: &str, expected_state: &str) -> Result, String> { let (code, echoed) = parse_authorization_input(input); if let Some(echoed) = echoed { @@ -263,25 +199,22 @@ fn parse_paste(input: &str, expected_state: &str) -> Result, Stri Ok(code) } -/// What the race settled on. enum CallbackOutcome { - /// The callback wait settled: the code, or `None` when it settled - /// empty (a dead server or a cancelled wait). + /// The code, or `None` on a settled-empty wait (a dead server). Code(Option), - /// The manual paste answered: the input, or `None` when cancelled. + /// The paste input, or `None` when cancelled. Manual(Option), } -/// A PKCE pair (TS `generatePKCE`): the verifier is the token-exchange -/// secret, the challenge travels in the authorization URL. +/// The verifier is the token-exchange secret; the challenge travels in +/// the authorization URL. fn generate_pkce() -> (String, String) { let verifier = base64url(&random_bytes(32)); let challenge = base64url(Sha256::digest(verifier.as_bytes()).as_slice()); (verifier, challenge) } -/// A random, hex CSRF `state` (TS `createState`: 16 random bytes as -/// hex). +/// A random, hex CSRF `state`. fn create_state() -> String { let mut state = String::with_capacity(32); for byte in random_bytes(16) { @@ -300,9 +233,6 @@ fn base64url(bytes: &[u8]) -> String { base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(bytes) } -/// The authorization URL (TS `createAuthorizationFlow`'s URL: the -/// challenge, the CSRF state, the registration's redirect and scope, -/// the simplified-flow flags, and the originator). fn authorization_url(challenge: &str, state: &str, originator: &str) -> String { let mut url = Url::parse(AUTHORIZE_URL).expect("the authorize url parses"); for (name, value) in [ @@ -322,10 +252,6 @@ fn authorization_url(challenge: &str, state: &str, originator: &str) -> String { url.to_string() } -/// Parse a pasted authorization input (TS `parseAuthorizationInput`): a -/// full redirect URL, a `code#state` pair, `code=`-shaped parameters, or -/// a bare code. Returns the code and the echoed state (`None` when the -/// input carries none — TS's falsy state skips the check). fn parse_authorization_input(input: &str) -> (Option, Option) { let value = input.trim(); if value.is_empty() { @@ -364,20 +290,12 @@ fn parse_authorization_input(input: &str) -> (Option, Option) { (non_empty(Some(value.to_string())), None) } -/// The account id the access token carries (TS `getAccountId`: the -/// `chatgpt_account_id` claim under the JWT auth claim path — the -/// provider's own extraction is the one owner). +/// The provider's own extraction is the one owner of the claim path. fn account_id_of(access_token: &str) -> Result { crate::providers::openai_codex_responses::request::extract_account_id(access_token) .map_err(|_| "Failed to extract accountId from token".to_string()) } -/// One token POST's outcome validation (TS `exchangeAuthorizationCode` / -/// `refreshAccessToken` share the shape): a 2xx answer with the three -/// fields the flow requires. -/// One token POST with an explicit request bound (the login keeps the -/// port's default; the refresh runs under the storage lock and takes the -/// tighter one). async fn token_post_bounded( http: &dyn CodexHttp, params: &[(&str, &str)], @@ -430,20 +348,17 @@ async fn token_post_bounded( }; if !expires_in.is_finite() { // A NaN/`inf` lifetime is not a lifetime (TS's arithmetic yields - // a never-expiring credential; the port refuses it as a broken - // response instead). + // a never-expiring credential; the port refuses it). return Err(format!( "OpenAI Codex token {label} response missing fields: {json}" )); } - // Epoch millis fit i64 for ~292 million years; the u128 duration's millis are the i64 convention here. + // Epoch millis fit i64 for ~292 million years. #[allow(clippy::cast_possible_truncation)] let now = std::time::SystemTime::now() .duration_since(std::time::UNIX_EPOCH) .map_or(i64::MAX, |elapsed| elapsed.as_millis() as i64); - // Saturating: an oversized `expires_in` cannot overflow the - // epoch-millisecond sum (the worst case saturates at the never - // until it refreshes). + // Saturating: an oversized `expires_in` cannot overflow the sum. // The wire's expires_in is a second count read through JSON f64; i64 ms is the credentials' convention. #[allow(clippy::cast_possible_truncation)] let expires = now.saturating_add((expires_in * 1000.0) as i64); @@ -454,8 +369,6 @@ async fn token_post_bounded( }) } -/// TS `exchangeAuthorizationCode`: the authorization-code grant with the -/// PKCE verifier against the registered redirect. async fn exchange_authorization_code( http: &dyn CodexHttp, code: &str, @@ -476,7 +389,6 @@ async fn exchange_authorization_code( .await } -/// TS `refreshAccessToken`: the refresh-token grant. async fn refresh_access_token( http: &dyn CodexHttp, refresh_token: &str, @@ -503,18 +415,10 @@ mod tests { use std::sync::{Arc, Mutex}; use tokio::io::AsyncWriteExt as _; - /// The app registration's redirect port is one fixed socket and every - /// `login_openai_codex` flow binds it, while the default harness runs - /// this module's tests on parallel threads: each flow stages the - /// port under this lock, so a sibling's bind can never land in the - /// browser race's probe-to-bind window and leave its flow's listener - /// dead. The lock is the async-aware one — the guard is held across - /// the flow's awaits by design (and never poisons). + /// Every flow binds the one fixed redirect port while the tests run on parallel threads: each + /// flow stages it under this lock. The guard is held across the flow's awaits by design. static REDIRECT_PORT: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(()); - /// A scripted transport: url -> response, recording every posted - /// body. Unknown urls fail the request (the TS suite throws on - /// unexpected fetches). struct ScriptedHttp { responses: std::collections::HashMap, seen: Mutex>, @@ -566,10 +470,6 @@ mod tests { } } - /// One scripted UI answer: an immediate value (`Some`), an - /// immediate cancel (`None`), a never-resolving surface, or a - /// surface that marks the cancel flag on its first poll and then - /// never resolves. enum ScriptedAnswer { Once(Option), Pending, @@ -585,8 +485,6 @@ mod tests { ScriptedAnswer::Once(Some(text.to_string())) } - /// The answer future; `cancel` is the surface's own shared flag - /// (the marks-then-pends mode sets it on the first poll). fn future( &self, cancel: &Arc, @@ -608,8 +506,6 @@ mod tests { } } - /// The scripted login surface: the captured authorization URL, the - /// paste racing the callback, and the fallback prompt. struct ScriptedUi { auth_url: Mutex>, manual: Option, @@ -629,9 +525,8 @@ mod tests { } } - /// The captured authorization URL: waits for the flow's - /// `onAuth` — observable readiness, bounded by a deadline that - /// fails the test (never a green-on-timeout retry loop). + /// Waits for the flow's `onAuth`, bounded by a deadline that + /// fails the test. async fn captured_url(&self) -> String { let deadline = std::time::Instant::now() + Duration::from_secs(5); loop { @@ -675,9 +570,8 @@ mod tests { } } - /// One fake access token: a three-segment JWT whose payload carries - /// the account id under the TS claim path (no signature — the flow - /// never verifies one, like the TS `atob` decode). + /// A fake three-segment JWT with the account id claim; no signature + /// — the flow never verifies one. fn account_jwt(account_id: Option<&str>) -> String { let payload = match account_id { Some(account_id) => json!({ @@ -703,7 +597,6 @@ mod tests { .to_string() } - /// The scripted token endpoint: one answer for the whole flow. fn token_http(access: &str) -> ScriptedHttp { ScriptedHttp::new(vec![(TOKEN_URL, 200, &token_body(access))]) } @@ -715,16 +608,10 @@ mod tests { .unwrap_or_default() } - /// Stage the app registration's redirect port busy for a - /// dead-callback flow, on the same host the flow itself binds (the - /// `PI_OAUTH_CALLBACK_HOST` override, default `127.0.0.1`). - /// `Some(listener)` means the caller actively holds the port, so - /// the flow's own bind cannot succeed against it (an active - /// listener blocks the same-address bind — both sockets set - /// `SO_REUSEADDR`, neither sets `SO_REUSEPORT`) and the flow's - /// callback server is dead by construction; `None` means the port - /// cannot be staged this run and the caller skips rather than run - /// a login against a listener it does not own. + /// Stage the registered redirect port busy on the flow's own host (`PI_OAUTH_CALLBACK_HOST`): + /// an active listener blocks the same-address bind (both sockets set `SO_REUSEADDR`, neither + /// sets `SO_REUSEPORT`), so the flow's callback server is dead. `None`: the port cannot be + /// staged this run. fn stage_busy_registered_port() -> Option { let host = std::env::var(crate::oauth::callback::CALLBACK_HOST_ENV) .unwrap_or_else(|_| "127.0.0.1".to_string()); @@ -756,8 +643,6 @@ mod tests { 43, "the PKCE verifier is 32 base64url bytes" ); - // The manual paste carried no state: TS's falsy state skips the - // echo check and the code is used as-is. } #[tokio::test] @@ -814,8 +699,7 @@ mod tests { #[tokio::test] async fn an_unreachable_token_endpoint_surfaces_a_transport_error() { - // Nothing scripted: the transport fails the request (the - // scripted stand-in for the request timeout). + // Nothing scripted: the transport fails the request. let http = ScriptedHttp::new(Vec::new()); let error = refresh_openai_codex_token(&http, "r-old") .await @@ -843,8 +727,8 @@ mod tests { #[tokio::test] async fn a_cancelled_surface_ends_the_login_between_polls() { let _registered_port = REDIRECT_PORT.lock().await; - // The flag flips when the url lands: the race loop's first - // poll-step check ends the flow before any code arrives. + // The flag flips when the url lands: the first poll-step check + // ends the flow. let http = token_http(&account_jwt(Some("acct-1"))); let mut ui = ScriptedUi::new(Some(ScriptedAnswer::Pending), ScriptedAnswer::Pending); ui.cancel_on_auth = true; @@ -852,7 +736,6 @@ mod tests { .await .unwrap_err(); assert_eq!(error, LOGIN_CANCELLED); - // No token request ever posted. assert!(http.seen_bodies(TOKEN_URL).is_empty()); } @@ -889,7 +772,6 @@ mod tests { #[tokio::test] async fn a_paste_without_a_code_falls_back_to_the_prompt() { let _registered_port = REDIRECT_PORT.lock().await; - // The redirect carries no code: the prompt fallback answers it. let http = token_http(&account_jwt(Some("acct-1"))); let ui = ScriptedUi::new( Some(ScriptedAnswer::value(REDIRECT_URI)), @@ -936,14 +818,8 @@ mod tests { #[tokio::test] async fn a_dead_callback_falls_to_the_prompt_without_a_paste_surface() { let _registered_port = REDIRECT_PORT.lock().await; - // The app registration's redirect port is the flow's wire - // contract (a bind-anywhere test would not exercise it): the - // staged listener blocks the flow's own bind, so its server is - // dead by construction and the paste-free prompt is the only - // path, settling in microseconds. A port that cannot be staged - // this run skips the flow rather than races it. let Some(held) = stage_busy_registered_port() else { - return; // the registered port is busy: this run cannot stage it. + return; }; let http = token_http(&account_jwt(Some("acct-1"))); let ui = ScriptedUi::new(None, ScriptedAnswer::value("the-code")); @@ -962,19 +838,13 @@ mod tests { drop(held); } - /// The staging contract, pinned with the flow's own bind call: a - /// listener from `stage_busy_registered_port` actively holds the - /// registered port, so the flow's callback bind fails against it — - /// the dead-server premise is a fact, not an assumption — and the - /// released port hosts the bind again. Any staging that stops - /// blocking (a probe-and-release shape, a freed port) reds here - /// deterministically: that is the load window the registered - /// settle red came from. + /// Pins the staging premise: a staged listener blocks the flow's bind and the released port + /// hosts it again, so any staging that stops blocking reds here. #[tokio::test] async fn the_staged_registered_port_blocks_the_flow_bind() { let _registered_port = REDIRECT_PORT.lock().await; let Some(held) = stage_busy_registered_port() else { - return; // the registered port is busy: this run cannot stage it. + return; }; let blocked = CodexCallbackServer::bind("127.0.0.1", 1455, "the-state").await; assert!( @@ -989,18 +859,13 @@ mod tests { ); } - /// The cancellation-aware-wait regression: a dead callback server - /// plus a paste that never resolves — the surface's cancel flag (set - /// by the paste's own first poll, standing in for the pane exit) - /// must end the flow with the cancel, never hang the wait. + /// Regression: a dead callback server plus a never-resolving paste + /// must end on the cancel flag, never hang the wait. #[tokio::test] async fn a_pending_paste_never_holds_a_cancelled_flow() { let _registered_port = REDIRECT_PORT.lock().await; - // The same verified staging as the dead-callback test: the - // premise must not be silent, and an unstaged port skips - // instead of handing the flow a listener of its own. let Some(held) = stage_busy_registered_port() else { - return; // the registered port is busy: this run cannot stage it. + return; }; let http = token_http(&account_jwt(Some("acct-1"))); let ui = ScriptedUi::new( @@ -1019,13 +884,8 @@ mod tests { drop(held); } - /// A login without a paste surface has no settle of its own while - /// its callback server waits (the browser path is the only - /// settler, live or dead), so the surface's cancel flag is the - /// only bound. The flag flips from outside the flow here — the - /// pane-exit shape (#2770) — and the login must end cancelled - /// inside the poll bound with no exchange, whichever way its - /// callback server's bind went. + /// Without a paste surface the cancel flag is the only bound on the callback wait: the login + /// must end cancelled with no exchange, whichever way its callback server's bind went. #[tokio::test] async fn a_cancelled_surface_ends_a_login_without_a_paste_surface() { let _registered_port = REDIRECT_PORT.lock().await; @@ -1050,13 +910,10 @@ mod tests { #[tokio::test] async fn the_browser_callback_wins_the_race() { let _registered_port = REDIRECT_PORT.lock().await; - // The app registration's redirect port is the flow's wire - // contract (a bind-anywhere test would not exercise the real - // listener): the flow binds its callback server and the browser - // redirect settles the code. Skip when another process holds the - // port — the bind-failure path is covered above. + // Skip when another process holds the registered port; the + // bind-failure path is covered above. let Ok(probe) = std::net::TcpListener::bind(("127.0.0.1", 1455)) else { - return; // the registered port is busy: this run cannot stage it. + return; }; drop(probe); let http = Arc::new(token_http(&account_jwt(Some("acct-live")))); @@ -1078,11 +935,8 @@ mod tests { .find(|(key, _)| key == "state") .map(|(_, value)| value.to_string()) .expect("the authorization url carries the state"); - // The captured url implies the flow's bind already resolved (the - // server starts before the url is presented), so a refused - // connect here is a port stolen after the probe: wait for the - // listener itself — observable readiness, bounded by a deadline - // that fails the test (never a green-on-timeout retry loop). + // A refused connect here is a port stolen after the probe: wait for the listener itself, + // bounded by a deadline that fails the test. let deadline = std::time::Instant::now() + Duration::from_secs(1); let mut stream = loop { match tokio::net::TcpStream::connect(("127.0.0.1", 1455)).await { @@ -1155,34 +1009,27 @@ mod tests { #[test] fn the_pasted_input_parses_like_the_ts_table() { - // A full redirect URL. assert_eq!( parse_authorization_input("https://auth.example/cb?code=a&state=b"), (Some("a".to_string()), Some("b".to_string())) ); - // A percent-decoded code. assert_eq!( parse_authorization_input("https://auth.example/cb?code=a%20b"), (Some("a b".to_string()), None) ); - // A `code#state` pair. assert_eq!( parse_authorization_input("the-code#the-state"), (Some("the-code".to_string()), Some("the-state".to_string())) ); - // `code=`-shaped parameters. assert_eq!( parse_authorization_input("code=a+b&state=c"), (Some("a b".to_string()), Some("c".to_string())) ); - // A bare code. assert_eq!( parse_authorization_input(" bare "), (Some("bare".to_string()), None) ); - // Empty input carries neither. assert_eq!(parse_authorization_input(" "), (None, None)); - // A redirect without a code. assert_eq!( parse_authorization_input("https://auth.example/cb?state=b"), (None, Some("b".to_string())) diff --git a/crates/pa-ai/src/oauth/pkce.rs b/crates/pa-ai/src/oauth/pkce.rs index 9b69d761afa..9b37450769e 100644 --- a/crates/pa-ai/src/oauth/pkce.rs +++ b/crates/pa-ai/src/oauth/pkce.rs @@ -1,8 +1,5 @@ -//! PKCE pair generation (TS `packages/ai/src/utils/oauth/pkce.ts`): -//! a random 43-character verifier and its S256 challenge. The -//! Anthropic flow uses it for the authorization-code exchange (the -//! Codex flow keeps its own copy; TS duplicates the helper per -//! module the same way). +//! PKCE pair generation: a random 43-character verifier and its S256 challenge. The Codex flow +//! keeps its own copy (TS duplicates the helper per module the same way). use base64::Engine as _; use rand::Rng; @@ -30,8 +27,6 @@ fn base64url(bytes: &[u8]) -> String { mod tests { use super::*; - /// TS `generatePKCE`: a 43-character URL-safe verifier whose S256 - /// challenge is deterministic over it. #[test] fn the_verifier_and_challenge_have_the_ts_shape() { let (verifier, challenge) = generate_pkce(); @@ -40,7 +35,7 @@ mod tests { let expected = base64::engine::general_purpose::URL_SAFE_NO_PAD .encode(Sha256::digest(verifier.as_bytes()).as_slice()); assert_eq!(challenge, expected); - // A fresh pair is a fresh secret (TS `crypto.getRandomValues`). + // A fresh pair is a fresh secret. assert_ne!(verifier, generate_pkce().0); } } diff --git a/crates/pa-ai/src/oauth/provider_http.rs b/crates/pa-ai/src/oauth/provider_http.rs index 7c314942422..bc74ba9920c 100644 --- a/crates/pa-ai/src/oauth/provider_http.rs +++ b/crates/pa-ai/src/oauth/provider_http.rs @@ -1,42 +1,31 @@ -//! The HTTP transport seam for the subscription OAuth flows (TS -//! `packages/ai/src/utils/oauth`'s plain `fetch` calls): the -//! JSON-body token exchange and refresh (Anthropic), the form-encoded -//! device flows with the client impersonation headers (GitHub -//! Copilot), and the strict-validated device flow that refuses -//! redirects (xAI). The Codex flow keeps its own narrower seam -//! (`CodexHttp`: one form POST per call); this one carries the method, -//! the headers, and the body the three providers' `fetch` shapes need. +//! The shared HTTP transport seam for the Anthropic, GitHub Copilot, +//! and xAI flows (the Codex flow keeps its own narrower `CodexHttp`). //! Dyn-dispatch on purpose: the product plugs in a reqwest client, -//! tests script the responses (the TS suite stubs `fetch` the same -//! way). +//! tests script the responses. use std::future::Future; use std::pin::Pin; use std::time::Duration; -/// One request's HTTP method. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum ProviderHttpMethod { Get, Post, } -/// One OAuth request (TS `fetch(url, init)`'s method, headers, and -/// body; the body is sent verbatim — form-encoded and JSON bodies are -/// built by the caller). +/// One OAuth request; the body is sent verbatim (form-encoded and +/// JSON bodies are built by the caller). #[derive(Debug, Clone, PartialEq, Eq)] pub struct ProviderHttpRequest { pub method: ProviderHttpMethod, pub url: String, pub headers: Vec<(String, String)>, pub body: Option, - /// Whether a redirect is followed (TS `fetch` follows by default; - /// the xAI flow passes `redirect: "error"` so a redirected token - /// request fails instead of silently following). + /// Whether redirects are followed (TS `fetch` follows by default; + /// the xAI flow passes `redirect: "error"`). pub follow_redirects: bool, } -/// One OAuth response (TS `response.status` + the read body). #[derive(Debug, Clone, PartialEq, Eq)] pub struct ProviderHttpResponse { pub status: u16, @@ -44,7 +33,6 @@ pub struct ProviderHttpResponse { } impl ProviderHttpResponse { - /// Whether the endpoint answered success (TS `response.ok`). #[must_use] pub fn ok(&self) -> bool { (200..300).contains(&self.status) @@ -53,8 +41,7 @@ impl ProviderHttpResponse { /// The transport the OAuth flows issue their requests through. pub trait ProviderHttp: Send + Sync { - /// One request; the error string is the transport's failure (TS - /// the `fetch` throw). + /// One request; the error string is the transport's failure. fn request( &self, request: ProviderHttpRequest, @@ -62,8 +49,7 @@ pub trait ProviderHttp: Send + Sync { ) -> Pin> + Send + '_>>; } -/// The production transport: one reqwest client per request, bounded -/// by the request timeout (the port's prime transport shape). +/// The production transport: one reqwest client per request. pub struct ReqwestProviderHttp; impl Default for ReqwestProviderHttp { @@ -73,8 +59,6 @@ impl Default for ReqwestProviderHttp { } impl ReqwestProviderHttp { - /// Construction is trivial: the client is built per request, so - /// there is nothing to fail here. #[must_use] pub fn new() -> Self { ReqwestProviderHttp diff --git a/crates/pa-ai/src/oauth/types.rs b/crates/pa-ai/src/oauth/types.rs index 174ea2dac76..9d46450001c 100644 --- a/crates/pa-ai/src/oauth/types.rs +++ b/crates/pa-ai/src/oauth/types.rs @@ -1,15 +1,10 @@ -//! The shared login-UI shapes of the subscription OAuth flows (TS -//! `packages/ai/src/utils/oauth/types.ts`: the callbacks interface one -//! login drives). The TUI renders the inline auth panel behind it and -//! tests script the answers; the flows themselves stay -//! surface-agnostic (TS `auth-flows.ts` mounts the login dialog). +//! The shared login-UI shapes of the subscription OAuth flows. The +//! TUI renders the inline auth panel behind them, tests script the +//! answers; the flows stay surface-agnostic. use std::future::Future; use std::pin::Pin; -/// One prompt a login asks (TS `OAuthPrompt`): the message, an optional -/// example placeholder, and whether an empty answer is a valid submit -/// (TS the Copilot domain prompt's `allowEmpty`). #[derive(Debug, Clone, PartialEq, Eq)] pub struct OAuthPrompt { pub message: String, @@ -17,33 +12,24 @@ pub struct OAuthPrompt { pub allow_empty: bool, } -/// The interactive surface one login drives (TS -/// `OAuthLoginCallbacks`): the browser URL block, the prompts, the -/// progress lines, and the manual paste racing a local callback -/// server. `None` answers cancel (TS the dialog's abort signal; the -/// port's cooperative cancel answers the same way). +/// The interactive surface one login drives: the auth URL block, the prompts, the progress lines, +/// and the manual paste racing a local callback server. `None` answers cancel the login. pub trait OAuthLoginUi: Send + Sync { - /// TS `onAuth`: the authorization URL to open, plus the flow's - /// instructions line. fn on_auth(&self, url: &str, instructions: Option<&str>); - /// TS `onPrompt`: one prompt; `None` cancels the login. + /// One prompt; `None` cancels the login. fn on_prompt( &self, prompt: &OAuthPrompt, ) -> Pin> + Send + '_>>; - /// TS `onProgress` (fire-and-forget narration). + /// Fire-and-forget narration. fn on_progress(&self, message: &str); - /// TS `onManualCodeInput`: the paste racing the browser callback; - /// `None` when the surface offers none. Resolving `None` cancels + /// The paste racing the browser callback; resolving `None` cancels /// the login. fn on_manual_code_input( &self, ) -> Option> + Send + '_>>>; - /// The driving surface's cooperative cancel state (#2770): the - /// pane that mounted the login marks it on exit and the flow - /// checks it between its poll steps and before its network steps. - /// The default (`false`) serves the surfaces that never cancel - /// mid-flow. + /// `true` once the pane that mounted the login exited: the flow + /// checks it between poll steps and before network steps. fn is_cancelled(&self) -> bool { false } diff --git a/crates/pa-ai/src/oauth/xai.rs b/crates/pa-ai/src/oauth/xai.rs index 4532d25b60b..2354f2fd4a0 100644 --- a/crates/pa-ai/src/oauth/xai.rs +++ b/crates/pa-ai/src/oauth/xai.rs @@ -1,16 +1,7 @@ -//! The xAI (Grok) OAuth flow — the port of -//! `packages/ai/src/utils/oauth/xai.ts`: the device-code flow against -//! the xAI auth endpoints with strict response validation (a -//! https-only verification URI, validated field types, the bounded -//! `expires_in`), the `slow_down` backoff, and the token refresh that -//! keeps the prior refresh token when the endpoint omits one. The -//! credentials the flow returns carry the TS shape (`access`, -//! `refresh`, `expires`) and persist under the provider id `xai`. -//! -//! Cancellation follows the fleet's cooperative pattern (#2770): the -//! driving surface marks a shared flag when it exits; the poll loop -//! checks it between its wait steps and the request wrapper checks it -//! around every network step. +//! The xAI (Grok) OAuth flow: the device-code flow with strict response +//! validation (https-only verification URI, typed fields, bounded +//! `expires_in`), the `slow_down` backoff, and a refresh that keeps the +//! prior refresh token when the endpoint omits one. use std::future::Future; use std::pin::Pin; @@ -21,69 +12,48 @@ use url::Url; use super::provider_http::{ProviderHttp, ProviderHttpMethod, ProviderHttpRequest}; use super::types::OAuthLoginUi; -/// The app registration the TS flow ships (TS `CLIENT_ID`). pub const XAI_CLIENT_ID: &str = "b1a00492-073a-47ea-816f-4c329264a828"; -/// TS `SCOPE`. const SCOPE: &str = "openid profile email offline_access grok-cli:access api:access"; -/// TS `DEVICE_CODE_URL`. const DEVICE_CODE_URL: &str = "https://auth.x.ai/oauth2/device/code"; -/// TS `TOKEN_URL`. const TOKEN_URL: &str = "https://auth.x.ai/oauth2/token"; -/// TS `REQUEST_TIMEOUT_MS` (the per-request bound). pub const REQUEST_TIMEOUT_MS: u64 = 30_000; -/// TS `REFRESH_SKEW_MS` (the credential's expiry skew, capped at half -/// the token's lifetime). +/// The credential's expiry skew, capped at half the token's lifetime. const REFRESH_SKEW_MS: i64 = 5 * 60 * 1000; -/// The device poll's default interval (TS: 5000 when the response -/// carries none). +/// The poll interval when the response carries none. const DEFAULT_POLL_INTERVAL_MS: u64 = 5000; -/// The refresh grant's request bound: the refresh runs under the auth -/// store's file lock, which a peer declares stale after 10 seconds — the -/// request must fit inside that window so a slow endpoint fails the -/// refresh (kept for a retry) instead of holding the lock past its -/// staleness. +/// The refresh runs under the auth store's file lock, which a peer declares stale after 10 seconds; +/// the request must fit inside that window. pub const REFRESH_TIMEOUT_MS: u64 = 8_000; -/// The cancel error the driving surface maps to the silent cancelled -/// outcome. +/// The cancel error the driving surface maps to the silent cancelled outcome. pub const LOGIN_CANCELLED: &str = "Login cancelled"; -/// The poll's cancel-check step (#2770). const CANCEL_POLL_INTERVAL: Duration = Duration::from_millis(250); -/// The credentials the flow returns and persist (TS -/// `OAuthCredentials` for the xAI provider). #[derive(Debug, Clone, PartialEq, Eq)] pub struct XaiCredentials { pub access: String, pub refresh: String, - /// Wall-clock epoch milliseconds (TS `Date.now() + lifetime - - /// min(REFRESH_SKEW_MS, lifetime / 2)`). + /// Wall-clock epoch milliseconds. pub expires: i64, } -/// One endpoint response (TS `OAuthResponse`: the status plus the -/// parsed object — an empty object when the body is not one). +/// The status plus the parsed body (an empty object when the body is +/// not one). struct XaiResponse { ok: bool, status: u16, body: serde_json::Map, } -/// Run the login (TS `loginXai`): the device authorization, the user -/// code, and the token poll with the TS backoff and the strict -/// validation. +/// The device authorization, the user code, and the token poll. /// /// # Errors /// -/// Returns an error when the surface cancelled the login -/// ([`LOGIN_CANCELLED`]), the device authorization fails, the device -/// code expires, the authorization is denied, or a token response -/// fails validation. +/// Returns an error when the login is cancelled ([`LOGIN_CANCELLED`]), the device +/// authorization fails, the code expires, or the token response fails validation. pub async fn login_xai( http: &dyn ProviderHttp, ui: &dyn OAuthLoginUi, ) -> Result { - // An exited surface never starts: no device request, no browser - // launch (the #2770 flag is the seam). if ui.is_cancelled() { return Err(LOGIN_CANCELLED.to_string()); } @@ -181,7 +151,7 @@ pub async fn login_xai( Err("xAI device code expired; sign in again".to_string()) } -/// Refresh an expired credential (TS `refreshXaiToken`). +/// Refresh an expired credential. /// /// # Errors /// @@ -208,8 +178,7 @@ pub async fn refresh_xai_token( credentials_from_response(&response.body, Some(refresh_token)) } -/// A surface that never cancels (the refresh runs detached from any -/// interactive surface). +/// The refresh runs detached from any interactive surface. struct NoCancel; impl OAuthLoginUi for NoCancel { @@ -228,9 +197,6 @@ impl OAuthLoginUi for NoCancel { } } -/// TS `postForm`: the form POST with the TS error taxonomy — the -/// cancelled surface, the timeout, the failed request, and the -/// invalid-JSON status line. async fn post_form( http: &dyn ProviderHttp, ui: &dyn OAuthLoginUi, @@ -286,8 +252,6 @@ async fn post_form( }) } -/// TS `requestFailure`: the action's status line; the -/// `invalid_grant` suffix names the expired-or-revoked cause. fn request_failure(action: &str, response: &XaiResponse) -> String { let suffix = if response .body @@ -305,8 +269,6 @@ fn request_failure(action: &str, response: &XaiResponse) -> String { ) } -/// TS `credentialsFromResponse`: the validated fields and the expiry -/// arithmetic (`lifetime - min(5 minutes, lifetime / 2)`). fn credentials_from_response( body: &serde_json::Map, previous_refresh: Option<&str>, @@ -327,15 +289,13 @@ fn credentials_from_response( Ok(XaiCredentials { access, refresh, - // Saturating: a hostile `expires_in` must not overflow the sum - // (the NaN/inf gate already answered the field error). + // Saturating: a hostile `expires_in` must not overflow the sum. expires: now_ms() .saturating_add(lifetime_ms) .saturating_sub(REFRESH_SKEW_MS.min(lifetime_ms / 2)), }) } -/// TS `requiredString`. fn required_string( body: &serde_json::Map, field: &str, @@ -347,7 +307,6 @@ fn required_string( .ok_or_else(|| format!("Invalid xAI OAuth response field: {field}")) } -/// TS `positiveSeconds` (the field's own name rides the error). // The wire's expires_in is an integer second count read through JSON f64; i64 is the port's unit. #[allow(clippy::cast_possible_truncation)] fn positive_seconds(value: Option<&serde_json::Value>) -> Result { @@ -358,8 +317,7 @@ fn positive_seconds(value: Option<&serde_json::Value>) -> Result { Ok(seconds as i64) } -/// TS `verificationUri`: a parsed https URL without credentials or -/// control characters. +/// A parsed https URL without credentials or control characters. fn verification_uri(raw: &str) -> Result { let url = Url::parse(raw) .map_err(|_| "Untrusted verification URI in xAI OAuth response".to_string())?; @@ -377,8 +335,7 @@ fn verification_uri(raw: &str) -> Result { Ok(url.to_string()) } -/// One abortable wait (TS `wait`): the cooperative cancel ends it -/// mid-wait instead of the abort signal. +/// The cooperative cancel flag ends the wait mid-sleep. async fn cancel_aware_sleep(ui: &dyn OAuthLoginUi, total: Duration) -> Result<(), String> { let deadline = std::time::Instant::now() + total; loop { @@ -393,8 +350,7 @@ async fn cancel_aware_sleep(ui: &dyn OAuthLoginUi, total: Duration) -> Result<() } } -/// Wall-clock milliseconds since the epoch (the `expires` convention). -// Epoch millis fit i64 for ~292 million years; the u128 duration's millis are the i64 convention here. +// Epoch millis fit i64 for ~292 million years. #[allow(clippy::cast_possible_truncation)] fn now_ms() -> i64 { std::time::SystemTime::now() @@ -411,8 +367,7 @@ mod tests { type ScriptedResponse = super::super::provider_http::ProviderHttpResponse; - /// A scripted transport: queued responses per url (popped in - /// order); every request is recorded. + /// Queued responses per url (popped in order). struct ScriptedHttp { queued: Mutex>>, requests: Mutex>, @@ -471,8 +426,6 @@ mod tests { } } - /// The scripted login surface: the captured auth block and the - /// cancel flag. struct ScriptedUi { auth_url: Mutex>, auth_instructions: Mutex>, @@ -527,8 +480,7 @@ mod tests { } } - /// The device authorization step's scripted response (a fast poll: - /// interval 0). + /// The device authorization response (a fast poll: interval 0). fn device_response(body: &str) -> ScriptedResponse { let json = serde_json::json!({ "device_code": "dev-1", @@ -571,7 +523,6 @@ mod tests { .as_millis() as i64; let skew = (credentials.expires - now - (3600 * 1000 - 300_000)).abs(); assert!(skew < 10_000, "the expiry arithmetic: {skew}"); - // The device request carries the TS body (scope + referrer). let device = &http.bodies_for(DEVICE_CODE_URL)[0]; let body = device.body.as_deref().unwrap(); assert!(body.contains("client_id=b1a00492-073a-47ea-816f-4c329264a828")); @@ -582,7 +533,6 @@ mod tests { "{body}" ); assert!(body.contains("referrer=pi")); - // The poll request carries the device-code grant. let poll = &http.bodies_for(TOKEN_URL)[1]; let body = poll.body.as_deref().unwrap(); assert!(body.contains("device_code=dev-1")); @@ -590,7 +540,6 @@ mod tests { body.contains("grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code"), "{body}" ); - // The auth block: the validated https URI + the user code. let (url, instructions) = ui.captured_auth(); assert_eq!(url, "https://auth.x.ai/activate"); assert_eq!(instructions.as_deref(), Some("Enter code: GROK-1234")); @@ -676,7 +625,6 @@ mod tests { let ui = ScriptedUi::new(); let error = login_xai(&http, &ui).await.unwrap_err(); assert_eq!(error, "Untrusted verification URI in xAI OAuth response"); - // A URL with credentials is untrusted too. let http = ScriptedHttp::new().queue( DEVICE_CODE_URL, vec![ScriptedHttp::entry( @@ -739,8 +687,8 @@ mod tests { let flow_ui = Arc::clone(&ui); tokio::spawn(async move { login_xai(flow_http.as_ref(), flow_ui.as_ref()).await }) }; - // Readiness-wait for the URL (bounded: a missing URL fails the - // test instead of hanging the cancel flip). + // Readiness-wait for the URL (bounded: a missing URL fails + // the test). let deadline = std::time::Instant::now() + Duration::from_secs(5); while ui.auth_url.lock().unwrap().is_none() { assert!( @@ -833,7 +781,7 @@ mod tests { #[tokio::test] async fn a_missing_field_token_fails_the_field() { // The login path carries no prior refresh token (the refresh - // path keeps the stored one — TS `credentialsFromResponse`). + // path keeps the stored one). let http = ScriptedHttp::new() .queue(DEVICE_CODE_URL, vec![device_response("")]) .queue( diff --git a/crates/pa-ai/src/prime_inference_differential_test.rs b/crates/pa-ai/src/prime_inference_differential_test.rs index feb7d8bd83d..e263ceb8b6c 100644 --- a/crates/pa-ai/src/prime_inference_differential_test.rs +++ b/crates/pa-ai/src/prime_inference_differential_test.rs @@ -1,12 +1,8 @@ //! Live differential test against the prime-inference endpoint. //! -//! Streams the captured real SSE exchange with `z-ai/glm-5.3-flash` (saved in -//! `tests/testdata/prime_inference_glm53_flash.sse`) through a local replay -//! server, runs both the TS reference provider (via `tests/differential/`) -//! and this Rust port against it, and requires identical assistant text and -//! usage accounting. -//! -//! Ignored by default (needs the replay server and the TS baseline). Run: +//! Streams the captured `z-ai/glm-5.3-flash` SSE exchange through a local replay server, runs the +//! TS reference provider and this Rust port against it, and requires identical text and usage. +//! Ignored by default; run: //! //! ```sh //! tests/differential/run.sh @@ -17,8 +13,7 @@ use serde_json::{json, Map, Value}; use crate::providers::openai_completions::{stream_openai_completions, OpenAICompletionsOptions}; use crate::types::{AssistantContent, Model, StopReason, StreamOptions}; -/// Model entry mirroring the prime-inference catalog entry for -/// `z-ai/glm-5.3-flash`. +/// Mirrors the prime-inference catalog entry for `z-ai/glm-5.3-flash`. fn glm_53_flash(base_url: &str) -> Model { let compat_json = json!({ "supportsStore": false, @@ -143,7 +138,6 @@ async fn differential_prime_inference_glm_53_flash() { let model = glm_53_flash(&replay_base_url); let actual = normalized_result(&model).await; - // Compare content and identity fields exactly. assert_eq!( actual["content"], expected["content"], "assistant content differs from the TS reference" @@ -181,7 +175,6 @@ async fn differential_prime_inference_glm_53_flash() { ); } - // Stop reason should be a clean stop for the captured stream. assert_eq!(expected["stopReason"], json!("stop")); let _ = StopReason::Stop; } diff --git a/crates/pa-ai/src/providers/anthropic/convert.rs b/crates/pa-ai/src/providers/anthropic/convert.rs index 82eb3f197cf..1b9aa84a6e8 100644 --- a/crates/pa-ai/src/providers/anthropic/convert.rs +++ b/crates/pa-ai/src/providers/anthropic/convert.rs @@ -1,5 +1,4 @@ //! Anthropic Messages conversion: content blocks, messages, and tools. -//! Section of the port of `packages/ai/src/providers/anthropic.ts`. use serde_json::{json, Map, Value}; @@ -69,7 +68,7 @@ pub(crate) fn convert_content_blocks(content: &[UserOrToolContent]) -> Value { json!(blocks) } -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] pub fn convert_messages( context: &Context, diff --git a/crates/pa-ai/src/providers/anthropic/mod.rs b/crates/pa-ai/src/providers/anthropic/mod.rs index 1d622149ddc..e54caa95220 100644 --- a/crates/pa-ai/src/providers/anthropic/mod.rs +++ b/crates/pa-ai/src/providers/anthropic/mod.rs @@ -1,10 +1,7 @@ -//! Anthropic Messages streaming provider. -//! -//! Full port of `packages/ai/src/providers/anthropic.ts`, split across -//! submodules: request headers and options here, message/tool conversion in -//! [`convert`], params assembly in [`params`], and the SSE streaming core in -//! [`stream`]. OAuth/Claude-Code header modes, beta headers, and adaptive vs -//! budget-based thinking selection live here. +//! Anthropic Messages streaming provider: request headers and options here, message/tool conversion +//! in [`convert`], params assembly in [`params`], and the SSE streaming core in [`stream`]. +//! OAuth/Claude-Code header modes, beta headers, and adaptive vs budget-based thinking selection +//! live here. use serde_json::{json, Map, Value}; @@ -32,9 +29,9 @@ mod stream_tests; pub const API_ANTHROPIC_MESSAGES: &str = "anthropic-messages"; -/// Claude Code version mimicked in OAuth mode. The API gates newer models -/// on the claimed client version (e.g. claude-opus-5.5 requires >= 2.280), -/// so keep this at or above the latest released Claude Code. +/// Claude Code version mimicked in OAuth mode. The API gates newer models on the claimed client +/// version (e.g. claude-opus-5.5 requires >= 2.280), so keep this at or above the latest released +/// Claude Code. const CLAUDE_CODE_VERSION: &str = "2.1.281"; const FINE_GRAINED_TOOL_STREAMING_BETA: &str = "fine-grained-tool-streaming-2025-05-14"; const INTERLEAVED_THINKING_BETA: &str = "interleaved-thinking-2025-05-14"; @@ -138,7 +135,7 @@ impl AnthropicToolChoice { } } -/// Provider-native options (`AnthropicOptions` in the TS reference). +/// Provider-native options. #[derive(Clone, Default)] pub struct AnthropicOptions { pub base: StreamOptions, @@ -225,9 +222,8 @@ pub(crate) fn get_cache_control( (retention, Some(CacheControl { ttl })) } -/// Fable/Mythos models — and Claude Opus 5.5 — think every turn and reject an -/// explicit `thinking: {type: "disabled"}` (and any sampling params) with a -/// 400. +/// Fable/Mythos models — and Claude Opus 5.5 — think every turn and reject an explicit `thinking: +/// {type: "disabled"}` (and any sampling params) with a 400. pub(crate) fn is_always_on_adaptive_thinking_model(model_id: &str) -> bool { model_id.contains("fable-5") || model_id.contains("mythos-5") @@ -316,9 +312,8 @@ pub(crate) fn headers_to_pairs(headers: &Map) -> Vec<(String, Str .collect() } -/// Build the request headers for the messages endpoint, mirroring the SDK -/// client configurations (OAuth/Claude Code mode, cloudflare gateway, -/// github-copilot, plain API key). +/// Build the request headers for the messages endpoint, mirroring the SDK client configurations +/// (OAuth/Claude Code mode, cloudflare gateway, github-copilot, plain API key). pub(crate) fn build_request_headers( model: &Model, api_key: &str, @@ -433,7 +428,6 @@ pub(crate) fn build_request_headers( (pairs, is_oauth) } -/// Port of `streamSimpleAnthropic`. pub fn stream_simple_anthropic( model: &Model, context: &Context, @@ -592,10 +586,9 @@ mod subscription_identity_tests { use super::build_request_headers; use crate::types::{zero_model_cost, Model, ModelInput}; - // TS #2645's wire-contract assertions (anthropic-thinking-disable.test.ts): - // subscription requests claim the Claude Code client identity, and the - // claimed version must stay at or above what the API's model gates require - // (the opus-5.5 family rejects anything below 2.280). + // TS #2645's wire-contract assertions (anthropic-thinking-disable.test.ts): subscription + // requests claim the Claude Code client identity, and the claimed version must stay at or above + // what the API's model gates require (the opus-5.5 family rejects anything below 2.280). fn test_model() -> Model { Model { id: "claude-opus-5-5".into(), diff --git a/crates/pa-ai/src/providers/anthropic/params.rs b/crates/pa-ai/src/providers/anthropic/params.rs index 30375d790ef..bedf9e963ea 100644 --- a/crates/pa-ai/src/providers/anthropic/params.rs +++ b/crates/pa-ai/src/providers/anthropic/params.rs @@ -1,5 +1,4 @@ //! Anthropic Messages request params assembly. -//! Section of the port of `packages/ai/src/providers/anthropic.ts`. use serde_json::{json, Map, Value}; @@ -11,7 +10,7 @@ use crate::providers::anthropic::{ use crate::types::{Context, Model}; use crate::utils_inner::sanitize_unicode::sanitize_surrogates; -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] pub(crate) fn build_params( model: &Model, @@ -80,8 +79,8 @@ pub(crate) fn build_params( params.insert("system".into(), json!([entry])); } - // Temperature is incompatible with extended thinking (adaptive or - // budget-based), and always-on models reject sampling params outright. + // Temperature is incompatible with extended thinking (adaptive or budget-based), and always-on + // models reject sampling params outright. if let Some(temperature) = base.temperature { if options.map(|options| options.thinking_enabled) != Some(Some(true)) && !is_always_on_adaptive_thinking_model(&model.id) diff --git a/crates/pa-ai/src/providers/anthropic/stream.rs b/crates/pa-ai/src/providers/anthropic/stream.rs index 351a60f9327..fd9fcbd9dbd 100644 --- a/crates/pa-ai/src/providers/anthropic/stream.rs +++ b/crates/pa-ai/src/providers/anthropic/stream.rs @@ -1,6 +1,5 @@ -//! Anthropic Messages streaming core: SSE iteration, event handling, and the -//! provider stream function. Section of the port of -//! `packages/ai/src/providers/anthropic.ts`. +//! Anthropic Messages streaming core: SSE iteration, event handling, and the provider stream +//! function. use serde_json::{json, Map, Value}; @@ -85,8 +84,8 @@ fn anthropic_sse_error(data: &str, request_id: Option<&str>) -> StreamFailureErr /// Marker error for an unhandled Anthropic stop reason. struct StopReasonError(String); -/// Per-block streaming state kept outside the output: the wire index and -/// the tool-JSON scratch, parallel to `output.content` by position. +/// Per-block streaming state kept outside the output: the wire index and the tool-JSON scratch, +/// parallel to `output.content` by position. struct IndexedBlocks { indices: Vec, partial_json: Vec, @@ -104,8 +103,8 @@ impl IndexedBlocks { self.indices.iter().position(|existing| *existing == index) } - /// Port of the TS catch settle: finalize tool-call blocks whose parsed - /// preview may lag the accumulated text under the growth throttle. + /// Port of the TS catch settle: finalize tool-call blocks whose parsed preview may lag the + /// accumulated text under the growth throttle. fn settle_partial_tool_calls(&mut self, content: &mut [AssistantContent]) { for (position, block) in content.iter_mut().enumerate() { let AssistantContent::ToolCall(tool_call) = block else { @@ -123,7 +122,6 @@ impl IndexedBlocks { } } -/// Port of `streamAnthropic`. pub fn stream_anthropic( model: &Model, context: &Context, @@ -184,7 +182,7 @@ pub fn stream_anthropic( reader } -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] async fn run_stream( model: &Model, @@ -250,9 +248,8 @@ async fn run_stream( on_response( crate::types::ProviderResponse { status: response.status, - // Collected into the ordered map: the hook payload can - // serialize, and the HTTP header arrival order is not a - // stable serialization order. + // Collected into the ordered map: the hook payload can serialize, and the HTTP + // header arrival order is not a stable serialization order. headers: response.headers.clone().into_iter().collect(), }, model, @@ -642,9 +639,8 @@ async fn run_stream( }}; } - // The TS try/catch encloses this whole streaming section, including the - // abort and stop-reason checks; the catch settles partial tool calls - // before the error event carries the message (TS PR #2783). + // The TS try/catch encloses this whole streaming section, including the abort and stop-reason + // checks; the catch settles partial tool calls before the error event carries the message. let stream_result: Result<(), ProviderError> = async { loop { let Some(chunk) = response.next_text().await? else { @@ -710,8 +706,8 @@ fn recalculate_cost(model: &Model, output: &mut AssistantMessage, cache_write_co calculate_cost(model, &mut output.usage, overrides.as_ref()); } -/// Handle one SSE event: error events become classified failures; message -/// events are parsed and forwarded. +/// Handle one SSE event: error events become classified failures; message events are parsed and +/// forwarded. fn handle_sse( sse: &ServerSentEvent, request_id: Option<&str>, diff --git a/crates/pa-ai/src/providers/azure_openai_responses.rs b/crates/pa-ai/src/providers/azure_openai_responses.rs index 9f37c9cc07e..55c5cb63d5f 100644 --- a/crates/pa-ai/src/providers/azure_openai_responses.rs +++ b/crates/pa-ai/src/providers/azure_openai_responses.rs @@ -1,8 +1,6 @@ -//! Azure `OpenAI` Responses API streaming provider. -//! Port of `packages/ai/src/providers/azure-openai-responses.ts`: deployment -//! name resolution (options/env map), base-URL normalization with the -//! /openai/v1 path, api-version query parameter, and the shared Responses -//! stream processor. +//! Azure `OpenAI` Responses API streaming provider: deployment name resolution (options/env map), +//! base-URL normalization with the /openai/v1 path, api-version query parameter, and the shared +//! Responses stream processor. use std::collections::HashMap; @@ -73,7 +71,7 @@ fn resolve_deployment_name(model: &Model, options: Option<&AzureOpenAIResponsesO mapped.unwrap_or_else(|| model.id.clone()) } -/// Provider-native options (`AzureOpenAIResponsesOptions` in the TS reference). +/// Provider-native options. #[derive(Clone, Default)] pub struct AzureOpenAIResponsesOptions { pub base: StreamOptions, @@ -108,8 +106,8 @@ fn normalize_azure_base_url(base_url: &str) -> Result { host.ends_with(".openai.azure.com") || host.ends_with(".cognitiveservices.azure.com"); let normalized_path = url.path().trim_end_matches('/'); - // Ensure Azure hosts have /openai/v1 as base path so the deployment URL - // resolves as /deployments//responses?api-version=. + // Ensure Azure hosts have /openai/v1 as base path so the deployment URL resolves as + // /deployments//responses?api-version=. if is_azure_host && (normalized_path.is_empty() || normalized_path == "/openai") { let mut normalized = url.clone(); normalized.set_path("/openai/v1"); @@ -182,10 +180,8 @@ fn build_params( params.insert("model".into(), json!(deployment_name)); params.insert("input".into(), json!(messages)); params.insert("stream".into(), json!(true)); - // TS #2948: Azure stores responses server-side by default — pin - // `store: false` (the d1fce2ba1 fix the OpenAI Responses provider got and - // this Azure copy never did), and drop `prompt_cache_key` when the caller - // pinned cacheRetention to none. Azure does not send + // TS #2948: Azure stores responses server-side by default — pin `store: false`, and drop + // `prompt_cache_key` when the caller pinned cacheRetention to none; Azure does not send // `prompt_cache_retention` (support unclear) — that stays as-is. if options.base.cache_retention != Some(CacheRetention::None) { if let Some(session_id) = &options.base.session_id { @@ -244,7 +240,6 @@ fn build_params( Value::Object(params) } -/// Port of `streamAzureOpenAIResponses`. pub fn stream_azure_openai_responses( model: &Model, context: &Context, @@ -305,7 +300,7 @@ pub fn stream_azure_openai_responses( reader } -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] async fn run_stream( model: &Model, @@ -365,9 +360,6 @@ async fn run_stream( on_response( crate::types::ProviderResponse { status: response.status, - // Collected into the ordered map: the hook payload can - // serialize, and the HTTP header arrival order is not a - // stable serialization order. headers: response.headers.clone().into_iter().collect(), }, model, @@ -395,9 +387,8 @@ async fn run_stream( crate::providers::openai_responses_shared::ResponsesStreamProcessor::new( model, output, writer, hooks, ); - // The TS try/catch encloses the streaming section and the abort and - // stop-reason checks; the catch settles partial tool calls before the - // error event carries the message (TS PR #2783). + // The TS try/catch encloses the streaming section and the abort and stop-reason checks; the + // catch settles partial tool calls before the error event carries the message. stream_result = async { let mut decoder = SseDecoder::new(); loop { @@ -457,7 +448,6 @@ async fn run_stream( Ok(()) } -/// Port of `streamSimpleAzureOpenAIResponses`. pub fn stream_simple_azure_openai_responses( model: &Model, context: &Context, @@ -539,10 +529,10 @@ impl Provider for AzureOpenAIResponsesProvider { mod tests { use super::*; - /// A `reasoning: false` model whose map addresses levels (the live - /// catalog's `gpt-5.3-chat-latest` azure shape) is thinking-capable: - /// the requested effort reaches the request with the map's value. The - /// flag alone must not veto a route that declares addressable levels. + /// A `reasoning: false` model whose map addresses levels (the live catalog's + /// `gpt-5.3-chat-latest` azure shape) is thinking-capable: the requested effort reaches the + /// request with the map's value. The flag alone must not veto a route that declares addressable + /// levels. #[test] fn a_map_addressable_model_sends_the_reasoning_effort_without_the_flag() { let model = serde_json::from_value::(json!({ @@ -563,9 +553,9 @@ mod tests { ); } - /// TS #2948: the request pins `store: false` (Azure stores responses - /// server-side by default) and drops `prompt_cache_key` when the caller - /// set cacheRetention to none; the key still ships by default. + /// The request pins `store: false` (Azure stores responses server-side by default) and drops + /// `prompt_cache_key` when the caller set cacheRetention to none; the key still ships by + /// default. #[test] fn pins_store_false_and_gates_prompt_cache_key_on_cache_retention() { let model = serde_json::from_value::(json!({ diff --git a/crates/pa-ai/src/providers/bedrock/auth.rs b/crates/pa-ai/src/providers/bedrock/auth.rs index 5b17cf54cc4..e4f036d8fb9 100644 --- a/crates/pa-ai/src/providers/bedrock/auth.rs +++ b/crates/pa-ai/src/providers/bedrock/auth.rs @@ -1,8 +1,6 @@ -//! Bedrock authentication and endpoint resolution. -//! -//! Ports the `SigV4` request signing used by `@aws-sdk/client-bedrock-runtime` -//! for `POST /model/{modelId}/converse-stream`, plus the region / endpoint / -//! credential resolution rules from `packages/ai/src/providers/amazon-bedrock.ts`. +//! Bedrock authentication and endpoint resolution: the `SigV4` request signing used by +//! `@aws-sdk/client-bedrock-runtime` for `POST /model/{modelId}/converse-stream`, plus the region / +//! endpoint / credential resolution rules from the TS provider. use std::fmt::Write as _; @@ -26,8 +24,8 @@ fn env(name: &str) -> Option { std::env::var(name).ok().filter(|value| !value.is_empty()) } -/// Parse an AWS credentials-style ini file: `[section-name]` headers with -/// `key = value` pairs (only the two credential lines are needed). +/// Parse an AWS credentials-style ini file: `[section-name]` headers with `key = value` pairs (only +/// the two credential lines are needed). fn parse_ini_credentials(text: &str, section: &str) -> Option { let mut in_section = false; let mut access_key_id = None; @@ -64,9 +62,8 @@ fn parse_ini_credentials(text: &str, section: &str) -> Option { }) } -/// Port of the SDK credential chain used by the TS provider: SigV4-skip dummy -/// keys, static env credentials, then the shared credentials file (default or -/// `AWS_PROFILE` / `options.profile`). +/// The SDK credential chain used by the TS provider: SigV4-skip dummy keys, static env credentials, +/// then the shared credentials file (default or `AWS_PROFILE` / `options.profile`). pub fn resolve_credentials(profile: Option<&str>) -> Option { if std::env::var("AWS_BEDROCK_SKIP_AUTH").as_deref() == Ok("1") { return Some(AwsCredentials { @@ -104,8 +101,8 @@ fn hmac_sha256(key: &[u8], data: &[u8]) -> Vec { mac.finalize().into_bytes().to_vec() } -/// UTC timestamp in `SigV4` formats: `x-amz-date` (20250101T000000Z) and date -/// stamp (20250101). Uses std time to avoid a chrono dependency. +/// UTC timestamp in `SigV4` formats: `x-amz-date` (20250101T000000Z) and date stamp (20250101). +/// Uses std time to avoid a chrono dependency. fn now_utc_parts() -> (String, String) { let seconds = std::time::SystemTime::now() .duration_since(std::time::UNIX_EPOCH) @@ -143,8 +140,8 @@ fn civil_from_unix(secs: u64) -> (i64, u32, u32, u32, u32, u32) { ) } -/// Produce the `SigV4` auth headers for a request. -/// Returns `(x-amz-date, authorization, x-amz-security-token)`. +/// Produce the `SigV4` auth headers for a request. Returns `(x-amz-date, authorization, +/// x-amz-security-token)`. pub struct SigV4Params<'a> { pub method: &'a str, /// Path with query string, starting with `/`. @@ -157,8 +154,8 @@ pub struct SigV4Params<'a> { pub extra_signed_headers: &'a [(String, String)], } -/// Produce the `SigV4` auth headers for a request. -/// Returns `(x-amz-date, authorization, x-amz-security-token)`. +/// Produce the `SigV4` auth headers for a request. Returns `(x-amz-date, authorization, +/// x-amz-security-token)`. pub fn sigv4_headers( params: &SigV4Params<'_>, credentials: &AwsCredentials, @@ -223,7 +220,6 @@ pub fn sigv4_headers( (amz_date, authorization, credentials.session_token.clone()) } -/// Port of `getConfiguredBedrockRegion`. pub fn get_configured_bedrock_region(region: Option<&str>) -> Option { region .map(std::string::ToString::to_string) @@ -231,12 +227,10 @@ pub fn get_configured_bedrock_region(region: Option<&str>) -> Option { .or_else(|| env("AWS_DEFAULT_REGION")) } -/// Port of `hasConfiguredBedrockProfile`. pub fn has_configured_bedrock_profile() -> bool { env("AWS_PROFILE").is_some() } -/// Port of `getStandardBedrockEndpointRegion`. pub fn get_standard_bedrock_endpoint_region(base_url: &str) -> Option { let hostname = url::Url::parse(base_url).ok()?.host_str()?.to_lowercase(); let suffix_stripped = hostname @@ -256,7 +250,6 @@ pub fn get_standard_bedrock_endpoint_region(base_url: &str) -> Option { Some(region.to_string()) } -/// Port of `shouldUseExplicitBedrockEndpoint`. pub fn should_use_explicit_bedrock_endpoint( base_url: &str, configured_region: Option<&str>, @@ -269,8 +262,8 @@ pub fn should_use_explicit_bedrock_endpoint( } } -/// Resolve the request endpoint and region: explicit model baseUrl (custom -/// gateways, fips, `GovCloud`) or the standard regional endpoint. +/// Resolve the request endpoint and region: explicit model baseUrl (custom gateways, fips, +/// `GovCloud`) or the standard regional endpoint. pub(crate) fn resolve_endpoint(model: &Model, options: &BedrockOptions) -> (String, String) { let configured_region = get_configured_bedrock_region(options.region.as_deref()); let has_profile = has_configured_bedrock_profile(); @@ -281,8 +274,8 @@ pub(crate) fn resolve_endpoint(model: &Model, options: &BedrockOptions) -> (Stri ); if use_explicit_endpoint && !model.base_url.is_empty() { - // Region resolution mirrors the TS: explicit option > env vars > - // endpoint hostname > (profile-resolved) > us-east-1. + // Region resolution mirrors the TS: explicit option > env vars > endpoint hostname > + // (profile-resolved) > us-east-1. let region = configured_region .or_else(|| { crate::providers::bedrock::auth::get_standard_bedrock_endpoint_region( diff --git a/crates/pa-ai/src/providers/bedrock/convert.rs b/crates/pa-ai/src/providers/bedrock/convert.rs index 60b1903eed5..d3679cd0b27 100644 --- a/crates/pa-ai/src/providers/bedrock/convert.rs +++ b/crates/pa-ai/src/providers/bedrock/convert.rs @@ -1,7 +1,5 @@ -//! Bedrock Converse request conversion: messages, system prompt, tool config, -//! and model-capability classification. -//! Port of the conversion section of -//! `packages/ai/src/providers/amazon-bedrock.ts`. +//! Bedrock Converse request conversion: messages, system prompt, tool config, and model-capability +//! classification. use base64::Engine as _; use serde_json::{json, Map, Value}; @@ -14,7 +12,6 @@ use crate::types::{ }; use crate::utils_inner::sanitize_unicode::sanitize_surrogates; -/// Port of `getModelMatchCandidates`. fn get_model_match_candidates(model_id: &str, model_name: Option<&str>) -> Vec { let mut values = vec![model_id.to_string()]; if let Some(name) = model_name { @@ -33,7 +30,7 @@ fn get_model_match_candidates(model_id: &str, model_name: Option<&str>) -> Vec) -> bool { get_model_match_candidates(model_id, model_name) .iter() @@ -50,8 +47,8 @@ pub fn supports_adaptive_thinking(model_id: &str, model_name: Option<&str>) -> b }) } -/// Port of `supportsAlwaysOnAdaptiveThinking`: Fable/Mythos models — and -/// Claude Opus 5.5 — think every turn and reject sampling params with a 400. +/// Fable/Mythos models — and Claude Opus 5.5 — think every turn and reject sampling params with a +/// 400. pub fn supports_always_on_adaptive_thinking(model_id: &str, model_name: Option<&str>) -> bool { get_model_match_candidates(model_id, model_name) .iter() @@ -64,7 +61,6 @@ pub fn supports_always_on_adaptive_thinking(model_id: &str, model_name: Option<& }) } -/// Port of `isAnthropicClaudeModel`. pub fn is_anthropic_claude_model(model: &Model) -> bool { let id = model.id.to_lowercase(); let name = model.name.to_lowercase(); @@ -75,13 +71,12 @@ pub fn is_anthropic_claude_model(model: &Model) -> bool { || name.contains("claude") } -/// Port of `supportsPromptCaching`. pub fn supports_prompt_caching(model: &Model) -> bool { let candidates = get_model_match_candidates(&model.id, Some(&model.name)); let has_claude_ref = candidates.iter().any(|s| s.contains("claude")); if !has_claude_ref { - // Application inference profiles don't contain the model name in the - // ARN. Allow users to force cache points via environment variable. + // Application inference profiles don't contain the model name in the ARN. Allow users to + // force cache points via environment variable. return std::env::var("AWS_BEDROCK_FORCE_CACHE").as_deref() == Ok("1"); } candidates.iter().any(|s| { @@ -89,12 +84,11 @@ pub fn supports_prompt_caching(model: &Model) -> bool { }) } -/// Port of `supportsThinkingSignature`. pub fn supports_thinking_signature(model: &Model) -> bool { is_anthropic_claude_model(model) } -/// Port of `normalizeToolCallId`: Bedrock tool-use IDs are `[a-zA-Z0-9_-]{1,64}`. +/// Bedrock tool-use IDs are `[a-zA-Z0-9_-]{1,64}`. pub fn normalize_tool_call_id(id: &str) -> String { let sanitized: String = id .chars() @@ -113,8 +107,8 @@ pub fn normalize_tool_call_id(id: &str) -> String { } } -/// Port of `createImageBlock`: validates the mime type and passes the base64 -/// bytes straight through (the AWS JSON protocol transmits blobs as base64). +/// Validates the mime type and passes the base64 bytes straight through (the AWS JSON protocol +/// transmits blobs as base64). fn create_image_block(mime_type: &str, data: &str) -> Value { let format = match mime_type { "image/jpeg" | "image/jpg" => "jpeg", @@ -136,7 +130,6 @@ fn create_image_block(mime_type: &str, data: &str) -> Value { }) } -/// Port of `buildSystemPrompt`. pub fn build_system_prompt( system_prompt: Option<&str>, model: &Model, @@ -157,8 +150,7 @@ pub fn build_system_prompt( Some(blocks) } -/// Port of `convertMessages`. -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] pub fn convert_messages( context: &Context, @@ -224,16 +216,14 @@ pub fn convert_messages( if thinking.thinking.trim().is_empty() { continue; } - // Only Anthropic models support the signature field - // in reasoningText. For other models we omit it to - // avoid: "This model doesn't support the + // Only Anthropic models support the signature field in reasoningText. + // For other models we omit it to avoid: "This model doesn't support the // reasoningContent.reasoningText.signature field". if supports_thinking_signature(model) { - // Signatures arrive after thinking deltas. If a - // partial or externally persisted message lacks - // a signature, Bedrock rejects the replayed - // reasoning block. Fall back to plain text, - // matching Anthropic. + // Signatures arrive after thinking deltas. If a partial or + // externally persisted message lacks a signature, Bedrock rejects + // the replayed reasoning block. Fall back to plain text, matching + // Anthropic. let signature = thinking .thinking_signature .as_deref() @@ -271,8 +261,8 @@ pub fn convert_messages( i += 1; } Message::ToolResult(_) => { - // Collect all consecutive toolResult messages into a single - // user message: Bedrock requires all tool results in one message. + // Collect all consecutive toolResult messages into a single user message: Bedrock + // requires all tool results in one message. let mut tool_results: Vec = Vec::new(); let mut j = i; while j < transformed.len() { @@ -304,8 +294,8 @@ pub fn convert_messages( } } - // Add a cache point to the last user message for supported Claude models - // when caching is enabled. + // Add a cache point to the last user message for supported Claude models when caching is + // enabled. if cache_retention != CacheRetention::None && supports_prompt_caching(model) && !result.is_empty() @@ -327,7 +317,6 @@ pub fn convert_messages( result } -/// Port of `convertToolConfig`. pub fn convert_tool_config( tools: Option<&[Tool]>, tool_choice: Option<&BedrockToolChoice>, @@ -368,7 +357,7 @@ pub fn convert_tool_config( Some(Value::Object(config)) } -/// Tool selection (`toolChoice` in the TS reference). +/// Tool selection. #[allow(dead_code)] // full TS option surface; variants set by callers #[derive(Clone, Debug, PartialEq)] pub enum BedrockToolChoice { @@ -378,10 +367,9 @@ pub enum BedrockToolChoice { Tool { name: String }, } -/// Port of `mapThinkingLevelToEffort`. pub fn map_thinking_level_to_effort(model: &Model, level: ModelThinkingLevel) -> &'static str { - // Clamp to what the model actually supports so callers that bypass - // clampThinkingLevel can't send an effort the model lacks. + // Clamp to what the model actually supports so callers that bypass clampThinkingLevel can't + // send an effort the model lacks. let effective = clamp_thinking_level(model, level); let mapped = model .thinking_level_map @@ -405,7 +393,6 @@ pub fn map_thinking_level_to_effort(model: &Model, level: ModelThinkingLevel) -> } } -/// Port of `mapStopReason`. pub fn map_stop_reason(reason: Option<&str>) -> crate::types::StopReason { use crate::types::StopReason; match reason { diff --git a/crates/pa-ai/src/providers/bedrock/events.rs b/crates/pa-ai/src/providers/bedrock/events.rs index b491a13dd59..0062045245f 100644 --- a/crates/pa-ai/src/providers/bedrock/events.rs +++ b/crates/pa-ai/src/providers/bedrock/events.rs @@ -1,6 +1,4 @@ -//! Converse Stream event handling: content-block slots, deltas, metadata, and -//! exception mapping. Section of the port of -//! `packages/ai/src/providers/amazon-bedrock.ts`. +//! Converse Stream event handling: content-block slots, deltas, metadata, and exception mapping. use std::collections::HashMap; @@ -41,8 +39,8 @@ impl BedrockStreamState { } } - /// Port of the TS catch settle: finalize tool-call blocks whose parsed - /// preview may lag the accumulated text under the growth throttle. + /// Port of the TS catch settle: finalize tool-call blocks whose parsed preview may lag the + /// accumulated text under the growth throttle. pub(crate) fn settle_partial_tool_calls(&mut self, output: &mut AssistantMessage) { for slot in self.slots.values_mut() { let BlockSlot::ToolUse { @@ -73,9 +71,9 @@ pub(crate) fn handle_event( let payload = String::from_utf8_lossy(&message.payload); let parsed: Value = serde_json::from_str(payload.trim()).unwrap_or(Value::Null); - // Exception events carry :exception-type and a JSON payload with message. - // TS rethrows the modeled SDK exception, so `formatBedrockError` composes - // `{prefix}: {message}` and the diagnostic records the exception name. + // Exception events carry :exception-type and a JSON payload with message. TS rethrows the + // modeled SDK exception, so `formatBedrockError` composes `{prefix}: {message}` and the + // diagnostic records the exception name. if let Some(exception_type) = &message.exception_type { let detail = parsed .get("message") @@ -84,8 +82,8 @@ pub(crate) fn handle_event( return Err(ProviderError::Http( crate::utils_inner::stream_failure::ProviderHttpError { message: bedrock_exception_message(exception_type, detail), - // AWS SDK stream exceptions carry no HTTP status for the - // classifier; the exception name is the classification key. + // AWS SDK stream exceptions carry no HTTP status for the classifier; the exception + // name is the classification key. status: None, body: None, headers: HashMap::default(), @@ -188,7 +186,7 @@ fn handle_content_block_start( } } -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] fn handle_content_block_delta( event: &Value, @@ -213,8 +211,7 @@ fn handle_content_block_delta( let reasoning = delta.and_then(|delta| delta.get("reasoningContent")); if let Some(text) = text { - // If no text block exists yet, create one: contentBlockStart is not - // sent for text blocks. + // If no text block exists yet, create one: contentBlockStart is not sent for text blocks. let slot = if let Some(slot) = state.slots.get(&content_block_index) { slot } else { @@ -407,10 +404,9 @@ fn handle_metadata( .get("cacheWriteInputTokens") .and_then(Value::as_u64) .unwrap_or(0); - // TS `totalTokens || input + output`: an explicitly reported zero is - // falsy, so only a positive reported total is kept. The sum - // saturates — TS doubles never wrap, and a Rust u64 must not - // panic (debug) or wrap to a wrong total (release). + // TS `totalTokens || input + output`: an explicitly reported zero is falsy, so only a + // positive reported total is kept. The sum saturates — TS doubles never wrap, and a Rust + // u64 must not panic (debug) or wrap to a wrong total (release). output.usage.total_tokens = usage .get("totalTokens") .and_then(Value::as_u64) @@ -426,10 +422,8 @@ mod tests { use crate::types::{zero_model_cost, ModelInput, Usage}; use serde_json::json; - /// TS `amazon-bedrock.ts` `handleMetadata` assigns - /// `usage.totalTokens = event.usage.totalTokens || input + output`, so an - /// explicitly reported zero total is falsy and falls back to the - /// input/output sum; a positive reported total is kept verbatim. + /// TS `handleMetadata` assigns `usage.totalTokens = event.usage.totalTokens || input + output`: + /// an explicitly reported zero total is falsy and falls back to the input/output sum. #[test] fn metadata_usage_total_tokens_explicit_zero_falls_back_to_sum() { let model = Model { diff --git a/crates/pa-ai/src/providers/bedrock/eventstream.rs b/crates/pa-ai/src/providers/bedrock/eventstream.rs index 2725d5d00bc..3ebe589d6b9 100644 --- a/crates/pa-ai/src/providers/bedrock/eventstream.rs +++ b/crates/pa-ai/src/providers/bedrock/eventstream.rs @@ -1,9 +1,8 @@ //! AWS `vnd.amazon.eventstream` binary framing decoder. //! -//! Bedrock `converse-stream` responses use the AWS event-stream wire format: -//! a prelude (total length, headers length, CRC), a header section, a JSON -//! payload, and a message CRC. Only the payload and the `:event-type` / -//! `:exception-type` headers are needed by the provider. +//! Bedrock `converse-stream` responses use the AWS event-stream wire format (prelude + headers + +//! JSON payload + CRC); only the payload and the `:event-type` / `:exception-type` headers are +//! needed. /// One decoded event-stream message. #[derive(Debug, Clone)] @@ -55,9 +54,8 @@ fn read_u32(bytes: &[u8]) -> u32 { u32::from_be_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]) } -/// Parse the header section: name (u8 len + bytes), value type u8, value. -/// Value type 7 is a length-prefixed (u16) string; other types are skipped -/// by their fixed or encoded widths. +/// Parse the header section: name (u8 len + bytes), value type u8, value. Value type 7 is a +/// length-prefixed (u16) string; other types are skipped by their fixed or encoded widths. fn parse_headers(bytes: &[u8]) -> Vec<(String, Option)> { let mut headers = Vec::new(); let mut offset = 0usize; diff --git a/crates/pa-ai/src/providers/bedrock/goaway.rs b/crates/pa-ai/src/providers/bedrock/goaway.rs index 7845e49a46b..e5abe7bf2e2 100644 --- a/crates/pa-ai/src/providers/bedrock/goaway.rs +++ b/crates/pa-ai/src/providers/bedrock/goaway.rs @@ -1,15 +1,8 @@ //! Passive inbound GOAWAY tracking for the bedrock h2c transport. //! -//! The `h2` crate files a received GOAWAY as the connection's pending error, -//! but any later connection-level failure (a TCP reset from a peer that -//! closes with unread request data — exactly what the provider-error probe -//! drives, and what broken middleboxes do in the wild) overwrites it before -//! a mid-body stream read can observe it. The TS transport (bun's -//! node:http2) reports the session error even then, so this module observes -//! the inbound wire directly: a pass-through frame-boundary scanner that -//! records the last GOAWAY error code the peer sent. It never interprets -//! anything else (no HPACK, no flow control) and feeds only the failure -//! classification in [`super::h2`]. +//! The `h2` crate files a received GOAWAY as the connection's pending error, but a later +//! failure overwrites it before a mid-body read observes it; this module scans the wire for +//! GOAWAYs and feeds the classification to [`super::h2`]. use std::sync::{Arc, Mutex}; @@ -19,21 +12,16 @@ use crate::utils_inner::stream_failure::H2Failure; const H2_FRAME_HEADER_LEN: usize = 9; const H2_FRAME_GOAWAY: u8 = 0x7; -/// The inbound frame scanner. `h2` reads through it, so every inbound byte is -/// observed in order; frame headers are self-delimiting so no HPACK -/// knowledge is needed to track boundaries. +/// The inbound frame scanner. `h2` reads through it, so every inbound byte is observed in order; +/// frame headers are self-delimiting so no HPACK knowledge is needed to track boundaries. #[derive(Default)] struct GoAwayTracker { - /// Bytes of the current frame header collected so far. header: [u8; H2_FRAME_HEADER_LEN], header_filled: usize, - /// Payload bytes still expected for the current frame. payload_remaining: usize, - /// The current frame is a connection-level GOAWAY. tracking_goaway: bool, /// First bytes of a GOAWAY payload (`last_stream_id` + error code prefix). goaway_prefix: Vec, - /// The last GOAWAY error code received from the peer. last_goaway_code: Option, } @@ -107,9 +95,9 @@ impl GoAwayObserver { .map_or(None, |tracker| tracker.last_goaway_code) } - /// The mid-body failure detail behind an `h2` error, preferring a - /// received GOAWAY over the stream/socket failure that followed it (the - /// TS transport reports the session error even when a reset clobbers it). + /// The mid-body failure detail behind an `h2` error, preferring a received GOAWAY over the + /// stream/socket failure that followed it (the TS transport reports the session error even when + /// a reset clobbers it). pub(crate) fn classify_mid_body(&self, error: &h2::Error) -> H2Failure { if let Some(code) = self.last_goaway_code() { return H2Failure::SessionClosed { code }; @@ -118,8 +106,7 @@ impl GoAwayObserver { } } -/// The pass-through read half: observes the inbound bytes, then hands them -/// to the socket untouched. +/// The pass-through read half: observes the inbound bytes, then hands them to the socket untouched. pub(crate) struct TrackedReadHalf { inner: tokio::net::tcp::OwnedReadHalf, observer: GoAwayObserver, @@ -155,8 +142,7 @@ impl tokio::io::AsyncRead for TrackedReadHalf { } } -/// The stream handed to `h2::client::handshake`: tracked inbound half, -/// pass-through outbound half. +/// The stream handed to `h2::client::handshake`: tracked inbound half, pass-through outbound half. pub(crate) struct TrackedStream { read: TrackedReadHalf, write: tokio::net::tcp::OwnedWriteHalf, @@ -218,8 +204,8 @@ mod tests { out } - /// Byte-chunked observation: HEADERS, DATA, then GOAWAY(1) split across - /// arbitrary read boundaries is still recognized. + /// Byte-chunked observation: HEADERS, DATA, then GOAWAY(1) split across arbitrary read + /// boundaries is still recognized. #[test] fn tracks_goaway_across_chunk_boundaries() { let observer = GoAwayObserver::default(); @@ -241,8 +227,8 @@ mod tests { assert_eq!(tracker.last_goaway_code, Some(1)); } - /// A connection-level GOAWAY (stream 0) only; a stream-scoped frame with - /// the same type is ignored (reserved-bit stripped on read). + /// A connection-level GOAWAY (stream 0) only; a stream-scoped frame with the same type is + /// ignored (reserved-bit stripped on read). #[test] fn ignores_non_connection_frames() { let observer = GoAwayObserver::default(); diff --git a/crates/pa-ai/src/providers/bedrock/h2.rs b/crates/pa-ai/src/providers/bedrock/h2.rs index 26a4186d084..231849b8e25 100644 --- a/crates/pa-ai/src/providers/bedrock/h2.rs +++ b/crates/pa-ai/src/providers/bedrock/h2.rs @@ -1,15 +1,7 @@ -//! The bedrock default transport: h2c prior-knowledge HTTP/2 over cleartext. -//! -//! The TS bedrock client (bun) runs the AWS SDK's `NodeHttp2Handler`: HTTP/2 -//! with prior knowledge over cleartext (`http2.connect`, no upgrade), an -//! isolated session per event-stream request, no transport retries -//! (`maxAttempts: 1`), and no transport timeout. The TS-visible failure -//! surface is bun's node:http2 error text (`Protocol error`, -//! `The pending stream has been canceled`, ...), pinned byte-for-byte by the -//! provider-error probe. This module drives the same protocol directly on -//! the `h2` crate — one connection per request — so the failure classes the -//! TS surfaces (stream reset, session GOAWAY, socket failure, protocol -//! violations) classify into the same texts (see `utils_inner::h2_classify`). +//! The bedrock default transport: h2c prior-knowledge HTTP/2 over cleartext, mirroring the TS +//! bedrock client's `NodeHttp2Handler` (isolated session per request, no transport retries or +//! timeout); failure texts are pinned by the provider-error probe and classify via +//! `utils_inner::h2_classify`. use std::future::Future; @@ -21,9 +13,8 @@ use crate::utils_inner::stream_failure::{ ConnectionErrorKind, ConnectionErrorProfile, H2Failure, ProviderConnectionError, ProviderError, }; -/// The bedrock wire transport, mirroring the TS request-handler selection: -/// the AWS SDK's `NodeHttp2Handler` by default; `NodeHttpHandler` (http1) when -/// `AWS_BEDROCK_FORCE_HTTP1=1` or a proxy environment is configured. +/// The bedrock wire transport, mirroring the TS request-handler selection: `NodeHttp2Handler` by +/// default; `NodeHttpHandler` (http1) for `AWS_BEDROCK_FORCE_HTTP1=1` or a proxy environment. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) enum BedrockTransport { /// The node http1 handler (`AWS_BEDROCK_FORCE_HTTP1=1`, proxy env). @@ -34,9 +25,6 @@ pub(crate) enum BedrockTransport { H2TlsAlpn, } -/// Port of the TS request-handler selection: `NodeHttp2Handler` (http2) by -/// default; the http1 `NodeHttpHandler` for `AWS_BEDROCK_FORCE_HTTP1=1` or any -/// configured proxy environment (the product's own proxy path). pub(crate) fn select_transport( scheme: &str, force_http1: bool, @@ -96,8 +84,8 @@ impl H2Response { }; match chunk { Some(Ok(bytes)) => { - // h2 flow control: the connection window must be released or - // long event streams stall once the default window drains. + // h2 flow control: the connection window must be released or long event streams + // stall once the default window drains. let _ = self.body.flow_control().release_capacity(bytes.len()); Ok(Some(bytes.to_vec())) } @@ -117,11 +105,9 @@ impl H2Response { /// Classify a mid-body h2 failure into the TS transport's failure texts. fn body_error(&self, error: &h2::Error) -> ProviderError { - // A peer GOAWAY does not fail streams at or below its last-stream-id; - // the stream only dies when the socket then closes — and a reset can - // clobber the h2 crate's pending GOAWAY error before it is observed. - // The wire observer (see `goaway`) keeps the session error the TS - // transport reports. + // A peer GOAWAY does not fail streams at or below its last-stream-id; the stream only dies + // when the socket then closes — and a reset can clobber the h2 crate's pending GOAWAY error + // before it is observed; the wire observer (see `goaway`) keeps the session error. let failure = self.observer.classify_mid_body(error); ProviderError::Connection(ProviderConnectionError { kind: ConnectionErrorKind::H2MidStream(failure), @@ -147,8 +133,8 @@ async fn select_cancel( } } -/// A pre-response transport failure: the h2 failure detail, no -/// deserialization hint (the AWS SDK has no response to deserialize yet). +/// A pre-response transport failure: the h2 failure detail, no deserialization hint (the AWS SDK +/// has no response to deserialize yet). fn h2_request_error(error: &h2::Error, connection: &ConnectionErrorProfile) -> ProviderError { ProviderError::Connection(ProviderConnectionError { kind: ConnectionErrorKind::H2Request(classify_h2_error(error)), @@ -157,9 +143,8 @@ fn h2_request_error(error: &h2::Error, connection: &ConnectionErrorProfile) -> P }) } -/// A TCP connect failure: refused connects surface the TS stream-cancel -/// text with the node-style cause embedded; other connect failures surface -/// the bare stream-cancel text. +/// A TCP connect failure: refused connects surface the TS stream-cancel text with the node-style +/// cause embedded; others the bare text. fn connect_error(error: &std::io::Error, connection: &ConnectionErrorProfile) -> ProviderError { let kind = if error.kind() == std::io::ErrorKind::ConnectionRefused { ConnectionErrorKind::Connect @@ -182,10 +167,9 @@ fn timeout_error(connection: &ConnectionErrorProfile, timeout_ms: u64) -> Provid }) } -/// Issue one h2c prior-knowledge request: connect, handshake, send the -/// request, and resolve once the response HEADERS arrive. The body is read -/// through the returned [`H2Response`]. -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +/// Issue one h2c prior-knowledge request: connect, handshake, send the request, and resolve once +/// the response HEADERS arrive. The body is read through the returned [`H2Response`]. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] pub(crate) async fn send_h2(options: H2RequestOptions) -> Result { let H2RequestOptions { @@ -222,8 +206,7 @@ pub(crate) async fn send_h2(options: H2RequestOptions) -> Result Result, pub interleaved_thinking: Option, pub thinking_display: Option, - /// Ordered (`BTreeMap`): the metadata serializes into the provider - /// request body (`requestMetadata`), and unordered iteration would leak - /// random key order into the bytes (the request body feeds the - /// provider's cacheable prefix). + /// Ordered (`BTreeMap`): the metadata serializes into the request body (`requestMetadata`), and + /// unordered iteration would leak random key order into the cacheable prefix. pub request_metadata: Option>, pub bearer_token: Option, } @@ -95,9 +88,8 @@ impl BedrockOptions { } } -/// Human-readable prefixes for Bedrock SDK exception names (see the TS -/// comment: the downstream retry logic in agent-session matches patterns like -/// `server.?error`, so the legacy prefix format is preserved). +/// Human-readable prefixes for Bedrock SDK exception names: the downstream retry logic matches +/// patterns like `server.?error`, so the legacy prefix format is preserved. const BEDROCK_ERROR_PREFIXES: [(&str, &str); 5] = [ ("InternalServerException", "Internal server error"), ("ModelStreamErrorException", "Model stream error"), @@ -115,9 +107,9 @@ pub(crate) fn bedrock_error_prefix(exception_name: &str) -> String { exception_name.to_string() } -/// Port of `formatBedrockError`'s composed form for an AWS SDK exception: -/// `{prefix}: {message}` with the human-readable prefix for known exception -/// names (`prefix` falls back to the raw SDK exception name). +/// `formatBedrockError`'s composed form for an AWS SDK exception: `{prefix}: {message}` with the +/// human-readable prefix for known exception names (`prefix` falls back to the raw SDK exception +/// name). pub(crate) fn bedrock_exception_message(exception_name: &str, message: &str) -> String { format!("{}: {}", bedrock_error_prefix(exception_name), message) } @@ -130,13 +122,9 @@ fn bedrock_endpoint_port(endpoint: &str) -> u16 { .unwrap_or(443) } -/// Port of the AWS SDK error deserialization for a non-2xx HTTP response: -/// the error name comes from the body `__type`/`code` (after the `#` -/// namespace separator, like the SDK's error-code parser) and the message -/// from the body `message` (defaulting to "`UnknownError`", like -/// `decorateServiceException`); unknown names fall through -/// `throwDefaultError`'s `parsedBody.code || errorCode || statusCode` chain. -/// The result is what `formatBedrockError` composes for it. +/// The AWS SDK error deserialization for a non-2xx response: the error name comes from the body +/// `__type`/`code`, the message from the body `message` (defaulting to "`UnknownError`"); unknown +/// names fall through `parsedBody.code || errorCode || statusCode`. fn bedrock_http_error( status: u16, body: &str, @@ -184,9 +172,8 @@ fn bedrock_http_error( }) } -/// The opened bedrock response, whichever transport produced it: the reqwest -/// path (http1 handler, https ALPN) or the direct h2c prior-knowledge path -/// (the TS default cleartext transport). +/// The opened bedrock response, whichever transport produced it: the reqwest path (http1 handler, +/// https ALPN) or the direct h2c path. enum BedrockResponse { Http(HttpResponse), H2(crate::providers::bedrock::h2::H2Response), @@ -229,14 +216,13 @@ impl BedrockResponse { } } -/// Port of the TS `AWS_BEDROCK_FORCE_HTTP1` request-handler switch. +/// The TS `AWS_BEDROCK_FORCE_HTTP1` request-handler switch. fn bedrock_force_http1() -> bool { std::env::var("AWS_BEDROCK_FORCE_HTTP1").as_deref() == Ok("1") } -/// Port of the TS proxy-env request-handler switch: any configured proxy -/// environment variable selects the node http1 handler with the proxy -/// agent (reqwest honors the proxy environment natively). +/// The TS proxy-env request-handler switch: any configured proxy environment variable selects the +/// http1 handler (reqwest honors the proxy environment natively). fn bedrock_proxy_configured() -> bool { [ "HTTP_PROXY", @@ -250,7 +236,6 @@ fn bedrock_proxy_configured() -> bool { .any(|key| std::env::var(key).is_ok_and(|value| !value.is_empty())) } -/// Port of `streamBedrock`. pub fn stream_bedrock( model: &Model, context: &Context, @@ -293,8 +278,8 @@ pub fn stream_bedrock( } else { StopReason::Error }; - // TS surfaces `formatBedrockError(error)`: the SDK exception - // name prefix form, not the classified stream-failure rewrite. + // TS surfaces `formatBedrockError(error)`: the SDK exception name prefix form, not + // the classified stream-failure rewrite. output.error_message = Some(error.to_string()); record_stream_failure( (&model.provider, &model.id, &model.api), @@ -313,7 +298,6 @@ pub fn stream_bedrock( reader } -/// Port of `resolveCacheRetention`. fn resolve_cache_retention(cache_retention: Option) -> CacheRetention { if let Some(retention) = cache_retention { return retention; @@ -324,7 +308,6 @@ fn resolve_cache_retention(cache_retention: Option) -> CacheRete CacheRetention::Short } -/// Port of `isGovCloudBedrockTarget`. fn is_gov_cloud_bedrock_target(model: &Model, options: &BedrockOptions) -> bool { if options .region @@ -337,7 +320,6 @@ fn is_gov_cloud_bedrock_target(model: &Model, options: &BedrockOptions) -> bool model_id.starts_with("us-gov.") || model_id.starts_with("arn:aws-us-gov:") } -/// Port of `buildAdditionalModelRequestFields`. fn build_additional_model_request_fields(model: &Model, options: &BedrockOptions) -> Option { let reasoning = options.reasoning?; if !model.reasoning { @@ -345,8 +327,8 @@ fn build_additional_model_request_fields(model: &Model, options: &BedrockOptions } if is_anthropic_claude_model(model) { - // GovCloud Bedrock currently rejects the Claude thinking.display field. - // Omit it there until the GovCloud Converse schema catches up. + // GovCloud Bedrock currently rejects the Claude thinking.display field. Omit it there until + // the GovCloud Converse schema catches up. let display = if is_gov_cloud_bedrock_target(model, options) { None } else { @@ -380,8 +362,8 @@ fn build_additional_model_request_fields(model: &Model, options: &BedrockOptions // Budget-based Claude has no max tier, clamp to high (ModelThinkingLevel::Max, 16384), ]; - // Custom budgets are keyed by the clamped level; xhigh/max - // resolve through the `high` entry, matching the TS. + // Custom budgets are keyed by the clamped level; xhigh/max resolve through the `high` + // entry, matching the TS. let clamped_level = clamp_reasoning(reasoning); let custom_budget = options @@ -422,8 +404,8 @@ fn build_additional_model_request_fields(model: &Model, options: &BedrockOptions use serde_json::Map; -/// Percent-encode the model id for the `/model/{modelId}/converse-stream` -/// path, matching the SDK's URI-component encoding of path labels. +/// Percent-encode the model id for the `/model/{modelId}/converse-stream` path, matching the SDK's +/// URI-component encoding of path labels. fn encode_model_id(model_id: &str) -> String { let mut encoded = String::new(); for byte in model_id.bytes() { @@ -437,7 +419,7 @@ fn encode_model_id(model_id: &str) -> String { encoded } -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] async fn run_stream( model: &Model, @@ -571,12 +553,9 @@ async fn run_stream( } } - // The TS request-handler selection: NodeHttp2Handler (http2) by default, - // NodeHttpHandler (http1) for AWS_BEDROCK_FORCE_HTTP1 or a proxy - // environment. Cleartext endpoints speak h2c prior-knowledge HTTP/2 - // directly (bun's node:http2 surface); https endpoints negotiate h2 via - // TLS ALPN through reqwest. The connection profile carries the endpoint - // address so the failure texts name the target. + // The TS request-handler selection: http2 by default, http1 for AWS_BEDROCK_FORCE_HTTP1 or a + // proxy environment. Cleartext endpoints speak h2c prior-knowledge HTTP/2 directly; https + // endpoints negotiate h2 via TLS ALPN through reqwest. let scheme = url::Url::parse(&url) .map(|parsed| parsed.scheme().to_string()) .unwrap_or_default(); @@ -641,9 +620,8 @@ async fn run_stream( on_response( crate::types::ProviderResponse { status: response.status(), - // Collected into the ordered map: the hook payload can - // serialize, and the HTTP header arrival order is not a - // stable serialization order. + // Collected into the ordered map: the hook payload can serialize, and the HTTP + // header arrival order is not a stable serialization order. headers: response.headers().into_iter().collect(), }, model, @@ -662,9 +640,8 @@ async fn run_stream( .or_else(|| response.header("x-amzn-request-id")); let mut state = BedrockStreamState::new(); - // The TS try/catch encloses this whole streaming section, including the - // abort and stop-reason checks; the catch settles partial tool calls - // before the error event carries the message (TS PR #2783). + // The TS try/catch encloses this whole streaming section, including the abort and stop-reason + // checks; the catch settles partial tool calls before the error event carries the message. let stream_result: Result<(), ProviderError> = async { let mut decoder = EventStreamDecoder::new(); let mut stream_error: Option = None; @@ -727,7 +704,6 @@ async fn run_stream( use crate::providers::bedrock::convert::build_system_prompt as build_system_prompt_blocks; -/// Port of `streamSimpleBedrock`. pub fn stream_simple_bedrock( model: &Model, context: &Context, @@ -867,9 +843,9 @@ mod tests { get_standard_bedrock_endpoint_region, should_use_explicit_bedrock_endpoint, }; - /// The TS `formatBedrockError` shape for an HTTP-level failure: the AWS - /// SDK exception name (from the body `__type` after the namespace) maps to - /// a stable human-readable prefix; unknown names keep the raw name. + /// The TS `formatBedrockError` shape for an HTTP-level failure: the AWS SDK exception name + /// (from the body `__type` after the namespace) maps to a stable human-readable prefix; unknown + /// names keep the raw name. #[test] fn bedrock_http_error_prefix_shape() { let error = bedrock_http_error( @@ -893,8 +869,8 @@ mod tests { assert_eq!(diagnostic.name.as_deref(), Some("ValidationException")); } - /// Throttling exceptions keep their name as the classification key - /// ("throttl" -> `rate_limit`), like the TS rethrown stream exception. + /// Throttling exceptions keep their name as the classification key ("throttl" -> `rate_limit`), + /// like the TS rethrown stream exception. #[test] fn bedrock_throttling_error_classifies() { let error = bedrock_http_error( @@ -910,19 +886,17 @@ mod tests { ); } - /// An unrecognized error body names the generic fallback by the raw - /// status text (smithy `throwDefaultError`: `parsedBody.code || - /// errorCode || statusCode || "UnknownError"`), and a missing message - /// defaults to "`UnknownError`" like `decorateServiceException`. + /// An unrecognized error body names the generic fallback by the raw status text + /// (`parsedBody.code || errorCode || statusCode || "UnknownError"`), and a missing message + /// defaults to "`UnknownError`". #[test] fn bedrock_http_error_generic_fallback() { let error = bedrock_http_error(400, "{\"foo\":1}", &HashMap::default()); assert_eq!(error.to_string(), "400: UnknownError"); } - /// Connection failures surface undici's raw `TypeError` message, like the - /// TS raw-`fetch` path (the AWS SDK does not wrap them). - /// The in-stream exception message composition (`{prefix}: {message}`). + /// Connection failures surface undici's raw `TypeError` message (the AWS SDK does not wrap + /// them). The in-stream exception message composition (`{prefix}: {message}`). #[test] fn bedrock_exception_message_shape() { assert_eq!( diff --git a/crates/pa-ai/src/providers/faux/mod.rs b/crates/pa-ai/src/providers/faux/mod.rs index 6533a6a5dc6..cc250d1c125 100644 --- a/crates/pa-ai/src/providers/faux/mod.rs +++ b/crates/pa-ai/src/providers/faux/mod.rs @@ -1,7 +1,6 @@ -//! Faux provider: deterministic in-process responses for tests and tooling. -//! Full port of `providers/faux.ts`, including usage estimation, per-session -//! prompt-cache simulation, token-paced streaming with aborts, and queued -//! response factories. +//! Faux provider: deterministic in-process responses for tests and tooling: usage estimation, +//! per-session prompt-cache simulation, token-paced streaming with aborts, and queued response +//! factories. use std::collections::{BTreeMap, HashMap}; use std::sync::{Arc, Mutex}; @@ -82,8 +81,7 @@ fn normalize_faux_assistant_content(content: &str) -> Vec { vec![faux_text(content)] } -/// Build a faux assistant message from plain text (mirrors the TS -/// `fauxAssistantMessage` string overload). +/// Build a faux assistant message from plain text (TS `fauxAssistantMessage` string overload). #[must_use] pub fn faux_assistant_text_message( text: &str, @@ -92,7 +90,7 @@ pub fn faux_assistant_text_message( faux_assistant_message(normalize_faux_assistant_content(text), options) } -/// Build a faux assistant message (helper mirroring `fauxAssistantMessage`). +/// Build a faux assistant message. pub fn faux_assistant_message( content: Vec, options: FauxAssistantMessageOptions, @@ -133,9 +131,8 @@ pub type FauxResponseFactory = Arc< #[allow(clippy::large_enum_variant)] // the TS shape is a tagged union of the same payloads pub enum FauxResponseStep { Message(AssistantMessage), - /// A message whose stream starts after `delay_ms` (harness pacing: the - /// delay holds the request in flight so verification harnesses can - /// capture mid-turn states). Verification harness only. + /// A message whose stream starts after `delay_ms` (harness pacing: the delay holds the request + /// in flight so harnesses can capture mid-turn states). Delayed { message: AssistantMessage, delay_ms: u64, @@ -157,31 +154,22 @@ struct FauxSharedState { received_api_keys: Mutex>>, pending: Mutex>, prompt_cache: Mutex>, - /// The last served step, recorded on every serve: an exhausted queue - /// re-serves it in repeat-last mode instead of erroring (the record - /// is kept regardless of the mode, so repeat-last switched on after - /// serving still has a step to re-serve). Verification harness only; - /// see [`FauxProviderRegistration::set_repeat_last_response`]. + /// The last served step, recorded on every serve: an exhausted queue re-serves it in + /// repeat-last mode, even one switched on after serving. Verification harness only. last_served: Mutex>, - /// Repeat-last mode (verification harness only): `false` by default, - /// so an exhausted queue keeps erroring with "No more faux responses - /// queued" — the response-budget contract every existing harness - /// scripts against. + /// Repeat-last mode (verification harness only): `false` by default — the finite queue and its + /// exhaustion error are the response-budget contract harnesses script against. repeat_last_response: std::sync::atomic::AtomicBool, } impl FauxSharedState { - /// The next scripted step: the queued front, or — in repeat-last mode - /// — the last served step again once the queue ran dry, or `None` - /// (the caller's exhaustion error). The dequeue and the last-served - /// publish share one hold of the pending `Mutex`, so overlapping - /// stream calls cannot observe an emptied queue with a stale or - /// missing last-served step. + /// The next scripted step: the queued front, or — in repeat-last mode — the last served step + /// once the queue ran dry, or `None` (the caller's exhaustion error). The dequeue and the + /// last-served publish share one hold of the pending `Mutex`. /// /// # Panics /// - /// Panics if the pending or last-served `Mutex` is poisoned (a thread - /// panicked while holding it). + /// Panics if the pending or last-served `Mutex` is poisoned. fn next_step(&self) -> Option { let repeat = self .repeat_last_response @@ -218,20 +206,18 @@ impl FauxProviderRegistration { /// /// # Panics /// - /// Panics if the counter `Mutex` is poisoned (a thread panicked while - /// holding the lock). + /// Panics if the counter `Mutex` is poisoned. #[must_use] pub fn call_count(&self) -> u64 { *self.state.call_count.lock().unwrap() } - /// The API key each recorded request carried (per call, in order): - /// summarizer arms that must follow the session's live key pin on it. + /// The API key each recorded request carried (per call, in order): summarizer arms that must + /// follow the session's live key pin on it. /// /// # Panics /// - /// Panics if the recorded-keys `Mutex` is poisoned (a thread panicked - /// while holding the lock). + /// Panics if the recorded-keys `Mutex` is poisoned. #[must_use] pub fn received_api_keys(&self) -> Vec> { self.state.received_api_keys.lock().unwrap().clone() @@ -241,8 +227,7 @@ impl FauxProviderRegistration { /// /// # Panics /// - /// Panics if the pending `Mutex` is poisoned (a thread panicked while - /// holding the lock). + /// Panics if the pending `Mutex` is poisoned. pub fn set_responses(&self, responses: Vec) { *self.state.pending.lock().unwrap() = responses; } @@ -251,8 +236,7 @@ impl FauxProviderRegistration { /// /// # Panics /// - /// Panics if the pending `Mutex` is poisoned (a thread panicked while - /// holding the lock). + /// Panics if the pending `Mutex` is poisoned. pub fn append_responses(&self, responses: Vec) { self.state.pending.lock().unwrap().extend(responses); } @@ -261,26 +245,17 @@ impl FauxProviderRegistration { /// /// # Panics /// - /// Panics if the pending `Mutex` is poisoned (a thread panicked while - /// holding the lock). + /// Panics if the pending `Mutex` is poisoned. #[must_use] pub fn get_pending_response_count(&self) -> usize { self.state.pending.lock().unwrap().len() } - /// Switch the registration into repeat-last mode: once the queued - /// responses run out, the provider serves the last response again on - /// every further call instead of erroring with "No more faux - /// responses queued". Verification harness only — the goal-continuation - /// churn of a scripted session can mint one model turn per natural - /// turn end for as long as an arrival latency keeps a pause in - /// flight, so a harness that must never run dry opts in - /// (`register_faux_provider_from_script`, the `repeatLastResponse` - /// script key). The last served step is recorded on every serve, so - /// switching the mode on after responses have already been served - /// still has a step to re-serve. The default stays `false`: the - /// finite queue and its exhaustion error are the response-budget - /// contract the existing harnesses script against. + /// Switch the registration into repeat-last mode: once the queued responses run out, the + /// provider serves the last response again on every further call instead of erroring. + /// Verification harness only (`register_faux_provider_from_script`, the `repeatLastResponse` + /// script key). The default stays `false`: the finite queue and its exhaustion error are the + /// response-budget contract. pub fn set_repeat_last_response(&self, repeat: bool) { self.state .repeat_last_response @@ -478,11 +453,9 @@ fn clone_message( cloned.api = api.to_string(); cloned.provider = provider.to_string(); cloned.model = model_id.to_string(); - // The served message is produced at serve time — a real provider stamps - // its assistant messages when the stream starts, while a scripted - // template carries its parse-time stamp. Harness pacing (`delayMs`) - // resolves before this, so a delayed response lands with its post-delay - // timestamp. + // The served message is produced at serve time — a real provider stamps its assistant messages + // when the stream starts, while a scripted template carries its parse-time stamp; the `delayMs` + // pacing resolves before this, so a delayed response lands post-delay. cloned.timestamp = now_ms(); cloned } @@ -531,7 +504,7 @@ async fn schedule_chunk(chunk: &str, tokens_per_second: Option) { } #[allow(clippy::too_many_arguments)] -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] async fn stream_with_deltas( writer: &AssistantMessageEventWriter, @@ -727,7 +700,7 @@ pub struct RegisterFauxProviderOptions { /// Register a faux provider and return its handle. #[must_use] -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] pub fn register_faux_provider(options: RegisterFauxProviderOptions) -> FauxProviderRegistration { struct FauxStream { @@ -744,7 +717,7 @@ pub fn register_faux_provider(options: RegisterFauxProviderOptions) -> FauxProvi &self.api } - // Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. + // Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] fn stream( &self, @@ -806,12 +779,9 @@ pub fn register_faux_provider(options: RegisterFauxProviderOptions) -> FauxProvi let resolved = match step { FauxResponseStep::Message(message) => Ok(message), - // The harness pacing delay holds the stream closed - // before the first delta: in-flight states (loaders, - // spinners) stay visible for the harness's capture - // window. The token races the hold, so a turn abort - // mid-wait cancels the request like the real transport - // (the fetch dies before any event streams). + // The harness pacing delay holds the stream closed before the first delta so + // in-flight states (loaders, spinners) stay visible; the token races the hold, + // so a mid-wait abort cancels the request like the real transport. FauxResponseStep::Delayed { message, delay_ms } => { if delay_ms > 0 { let hold = @@ -828,9 +798,8 @@ pub fn register_faux_provider(options: RegisterFauxProviderOptions) -> FauxProvi false }; if cancelled { - // The real providers' abort path: the request - // dies mid-flight (ProviderError::Aborted), - // the stream settles on the aborted message. + // The real providers' abort path: the request dies mid-flight, the + // stream settles on the aborted message. let mut partial = message.clone(); partial.content = Vec::new(); let aborted = create_aborted_message(&partial); @@ -982,7 +951,7 @@ impl PopFront for Vec { } } -/// Helper: build an image content block (kept next to the other faux helpers). +/// Helper: build an image content block. #[must_use] pub fn faux_image(data: &str, mime_type: &str) -> ImageContent { ImageContent { diff --git a/crates/pa-ai/src/providers/faux/script.rs b/crates/pa-ai/src/providers/faux/script.rs index bc5bbe8e3ef..5ccc62e9076 100644 --- a/crates/pa-ai/src/providers/faux/script.rs +++ b/crates/pa-ai/src/providers/faux/script.rs @@ -18,29 +18,24 @@ pub struct FauxScript { pub model: FauxModelDefinition, pub tokens_per_second: Option, pub responses: Vec, - /// The `repeatLastResponse` script key: once the queued responses run - /// out, the provider re-serves the last one on every further call - /// instead of erroring. Opt-in for harnesses whose flow keeps calling - /// the model past the script's depth (an active goal's continuation - /// churn); the default stays the finite response budget. + /// The `repeatLastResponse` script key: once the queued responses run out, the provider + /// re-serves the last one on every further call instead of erroring (the default stays the + /// finite response budget). pub repeat_last_response: bool, } -/// Parse a `{"responses": [...], "modelId": ..., "tokensPerSecond": ..., -/// "repeatLastResponse": ...}` script. +/// Parse a `{"responses": [...], "modelId": ..., "tokensPerSecond": ..., "repeatLastResponse": +/// ...}` script. /// -/// Entry forms: a plain string, `{"text": "..."}`, or -/// `{"content": [{"type": "thinking"|"text"|"toolCall", ...}], "stopReason"?}`. -/// The stop reason defaults to `toolUse` when the entry carries a tool call. +/// Entry forms: a plain string, `{"text": "..."}`, or `{"content": [{"type": +/// "thinking"|"text"|"toolCall", ...}], "stopReason"?}`. The stop reason defaults to `toolUse` when +/// the entry carries a tool call. /// /// # Errors /// -/// Returns `Err` when the script is not a JSON object, when `responses` is -/// not an array, when a response entry is neither a string nor an object, -/// when a `content` block is malformed, or when `stopReason` is unknown. -/// Entry objects whose `content` is not an array and whose `text` is not a -/// string (for example `{"content": 1}` or `{"text": 1}`) are accepted as -/// empty text responses rather than errors. +/// Returns `Err` when the script is not a JSON object, `responses` is not an array, a response +/// entry is neither a string nor an object, a `content` block is malformed, or `stopReason` is +/// unknown; entry objects without a usable `content`/`text` are accepted as empty responses. pub fn parse_faux_script(script: &Value) -> Result { let Some(object) = script.as_object() else { return Err("the faux script must be a JSON object".to_string()); @@ -75,9 +70,8 @@ pub fn parse_faux_script(script: &Value) -> Result { .and_then(Value::as_u64) .unwrap_or(128_000), ), - // The default request budget mirrors the registry faux model; - // scripts override it (the combined input+output ceiling fixtures - // need a small window and a small output budget). + // The default request budget mirrors the registry faux model; scripts override it (the + // combined input+output ceiling fixtures need a small window and a small output budget). max_tokens: Some( object .get("maxTokens") @@ -136,9 +130,8 @@ fn parse_script_step(entry: &Value) -> Result { Some(other) => return Err(format!("unknown faux script stopReason {other}")), None => None, }; - // Optional scripted error text (verification harness only): rides the - // message with `stopReason: "error"`, so overflow-recovery harnesses can - // script provider overflow responses. + // Optional scripted error text (verification harness only): rides the message with `stopReason: + // "error"`, so overflow-recovery harnesses can script provider overflow responses. let error_message = entry .get("errorMessage") .and_then(Value::as_str) @@ -153,8 +146,8 @@ fn parse_script_step(entry: &Value) -> Result { StopReason::Stop } }); - // Optional harness pacing: `delayMs` holds the stream closed before - // the first delta (verification harness only). + // Optional harness pacing: `delayMs` holds the stream closed before the first delta + // (verification harness only). let delay_ms = entry .get("delayMs") .and_then(Value::as_u64) diff --git a/crates/pa-ai/src/providers/faux/tests.rs b/crates/pa-ai/src/providers/faux/tests.rs index 3e8183212a0..30c7897700e 100644 --- a/crates/pa-ai/src/providers/faux/tests.rs +++ b/crates/pa-ai/src/providers/faux/tests.rs @@ -307,8 +307,8 @@ async fn parses_the_repeat_last_response_script_key_into_the_registration() { assert_eq!(registration.call_count(), 2); registration.unregister(); - // The knob stays off unless the script opts in: the finite queue and - // its exhaustion error are the response-budget contract. + // The knob stays off unless the script opts in: the finite queue and its exhaustion error are + // the response-budget contract. let parsed = script::parse_faux_script(&serde_json::json!({ "responses": ["only"] })) .expect("script parses"); assert!(!parsed.repeat_last_response); @@ -330,8 +330,8 @@ async fn repeat_last_response_switched_on_after_serving_replays_the_last_step() let last = complete(®istration.get_model(), &context, None) .await .unwrap(); - // The queue is dry and the mode was off while it drained; switching - // repeat-last on now still has the last served step recorded. + // The queue is dry and the mode was off while it drained; switching repeat-last on now still + // has the last served step recorded. registration.set_repeat_last_response(true); let replay = complete(®istration.get_model(), &context, None) .await @@ -1139,10 +1139,9 @@ async fn supports_aborting_mid_toolcall_stream_when_paced() { #[tokio::test] async fn unregisters_the_provider() { - // No registry reset here: clearing the process-wide registry races with - // the other faux tests' registrations. The registration's api id is - // unique (`random_id`) and `unregister` removes by source id, so the - // lookup below is deterministic without nuking parallel tests. + // No registry reset here: clearing the process-wide registry races with the other faux tests' + // registrations. The registration's api id is unique (`random_id`) and `unregister` removes by + // source id, so the lookup below is deterministic without nuking parallel tests. let registration = register(); registration.set_responses(vec![text_msg("hello")]); let api = registration.api.clone(); diff --git a/crates/pa-ai/src/providers/google.rs b/crates/pa-ai/src/providers/google.rs index 0b1348efded..904cce4e937 100644 --- a/crates/pa-ai/src/providers/google.rs +++ b/crates/pa-ai/src/providers/google.rs @@ -1,7 +1,6 @@ -//! Google Generative AI (Gemini API) streaming provider. -//! Port of `packages/ai/src/providers/google.ts` (the `@google/genai` SDK): REST -//! `streamGenerateContent` SSE streaming, thinking config (levels for Gemini 3, -//! budgets for Gemini 2.5), tool config, and usage accounting. +//! Google Generative AI (Gemini API) streaming provider (the `@google/genai` SDK): REST +//! `streamGenerateContent` SSE streaming, thinking config (levels for Gemini 3, budgets for Gemini +//! 2.5), tool config, and usage accounting. use serde_json::{json, Map, Value}; @@ -60,7 +59,7 @@ impl GoogleToolChoice { } } -/// Provider-native options (`GoogleOptions` in the TS reference). +/// Provider-native options. #[derive(Clone, Default)] pub struct GoogleOptions { pub base: StreamOptions, @@ -78,7 +77,6 @@ impl GoogleOptions { } } -/// Port of `streamGoogle`. pub fn stream_google( model: &Model, context: &Context, @@ -206,7 +204,7 @@ fn build_params(model: &Model, context: &Context, options: &GoogleOptions) -> Va Value::Object(body) } -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] async fn run_stream( model: &Model, @@ -239,8 +237,8 @@ async fn run_stream( } } - // @google/genai default: https://generativelanguage.googleapis.com with - // the v1beta version path; a model baseUrl replaces both. + // @google/genai default: https://generativelanguage.googleapis.com with the v1beta version + // path; a model baseUrl replaces both. let (base_url, api_version) = if model.base_url.is_empty() { ( "https://generativelanguage.googleapis.com".to_string(), @@ -297,9 +295,6 @@ async fn run_stream( on_response( crate::types::ProviderResponse { status: response.status, - // Collected into the ordered map: the hook payload can - // serialize, and the HTTP header arrival order is not a - // stable serialization order. headers: response.headers.clone().into_iter().collect(), }, model, @@ -308,9 +303,9 @@ async fn run_stream( if response.status >= 400 { let body = response.read_all_text().await.unwrap_or_default(); - // The genai `ApiError` carries no `.error` object for the TS - // classifier (its `code` is numeric): the class name is the - // provider error type and the classified form carries no detail. + // The genai `ApiError` carries no `.error` object for the TS classifier (its `code` is + // numeric): the class name is the provider error type and the classified form carries no + // detail. let mut error = ProviderError::from_http_status_body(response.status, &body, response.headers.clone()); if let ProviderError::Http(http) = &mut error { @@ -373,7 +368,6 @@ async fn run_stream( Ok(()) } -/// Port of `streamSimpleGoogle`. pub fn stream_simple_google( model: &Model, context: &Context, diff --git a/crates/pa-ai/src/providers/google_shared.rs b/crates/pa-ai/src/providers/google_shared.rs index 41f30563e85..5950f17c709 100644 --- a/crates/pa-ai/src/providers/google_shared.rs +++ b/crates/pa-ai/src/providers/google_shared.rs @@ -1,8 +1,6 @@ -//! Google Generative AI / Vertex shared utilities. -//! Port of `packages/ai/src/providers/google-shared.ts`: message/tool -//! conversion with thought-signature replay, thinking budgets and levels, -//! finish-reason and tool-choice mapping. The shared stream-chunk processor -//! lives in [`crate::providers::google_stream`]. +//! Google Generative AI / Vertex shared utilities: message/tool conversion with thought-signature +//! replay, thinking budgets and levels, finish-reason and tool-choice mapping. The shared +//! stream-chunk processor lives in [`crate::providers::google_stream`]. use serde_json::{json, Map, Value}; @@ -98,15 +96,15 @@ pub fn get_google_thinking_budget( /// Whether a streamed Gemini part should be treated as thinking content. /// -/// Protocol note: `thought: true` is the definitive marker; `thoughtSignature` -/// can appear on ANY part type and does NOT indicate thinking content. +/// Protocol note: `thought: true` is the definitive marker; `thoughtSignature` can appear on ANY +/// part type and does NOT indicate thinking content. pub fn is_thinking_part(part: &Value) -> bool { part.get("thought") == Some(&json!(true)) } -/// Retain thought signatures during streaming: some backends only send -/// `thoughtSignature` on the first delta of a block; keep the last non-empty -/// one. Never merges or moves signatures across distinct parts. +/// Retain thought signatures during streaming: some backends only send `thoughtSignature` on the +/// first delta of a block; keep the last non-empty one. Never merges or moves signatures across +/// distinct parts. pub fn retain_thought_signature(existing: Option<&str>, incoming: Option<&str>) -> Option { if let Some(incoming) = incoming { if !incoming.is_empty() { @@ -130,8 +128,7 @@ fn is_valid_thought_signature(signature: Option<&str>) -> bool { .all(|b| b.is_ascii_alphanumeric() || b == b'+' || b == b'/' || b == b'=') } -/// Retain a thought signature only for the originating provider/model and when -/// it is valid base64. +/// Retain a thought signature only for the originating provider/model and when it is valid base64. fn resolve_thought_signature( is_same_provider_and_model: bool, signature: Option<&str>, @@ -165,9 +162,9 @@ fn supports_multimodal_function_response(model_id: &str) -> bool { } } -/// Convert internal context to Google `contents[]`, preserving replayable -/// signatures only when protocol-valid. -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +/// Convert internal context to Google `contents[]`, preserving replayable signatures only when +/// protocol-valid. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] pub fn convert_messages(model: &Model, context: &Context) -> Vec { use crate::types::{Message, UserMessageContent, UserOrToolContent}; @@ -252,8 +249,8 @@ pub fn convert_messages(model: &Model, context: &Context) -> Vec { if thinking.thinking.trim().is_empty() { continue; } - // Only keep as thinking block if same provider AND - // same model; otherwise convert to plain text. + // Only keep as thinking block if same provider AND same model; + // otherwise convert to plain text. let mut part = Map::new(); if is_same_provider_and_model { part.insert("thought".into(), json!(true)); @@ -361,8 +358,8 @@ pub fn convert_messages(model: &Model, context: &Context) -> Vec { "functionResponse": Value::Object(function_response), }); - // Cloud Code Assist requires all function responses in a single - // user turn: merge into the previous one when possible. + // Cloud Code Assist requires all function responses in a single user turn: merge + // into the previous one when possible. if let Some(last) = contents.last_mut() { let is_user = last.get("role").and_then(|value| value.as_str()) == Some("user"); let has_function_response = last @@ -437,9 +434,8 @@ fn sanitize_for_openapi(schema: &Value) -> Value { /// Convert tools to Gemini function declarations. /// -/// By default uses `parametersJsonSchema` (full JSON Schema). `use_parameters` -/// switches to the legacy `OpenAPI` `parameters` field (needed for Cloud Code -/// Assist with Claude models). +/// By default uses `parametersJsonSchema` (full JSON Schema). `use_parameters` switches to the +/// legacy `OpenAPI` `parameters` field (needed for Cloud Code Assist with Claude models). pub fn convert_tools(tools: &[Tool], use_parameters: bool) -> Option> { if tools.is_empty() { return None; @@ -495,10 +491,6 @@ pub fn map_google_stop_reason(reason: &str) -> Result { } } -// --------------------------------------------------------------------------- -// Model classification + thinking config -// --------------------------------------------------------------------------- - pub fn is_gemma4_model(model_id: &str) -> bool { let lower = model_id.to_lowercase(); lower.contains("gemma-4") || lower.contains("gemma4") @@ -519,9 +511,9 @@ fn regex_is_match(model_id: &str, pattern: &str) -> bool { /// Thinking config for disabled reasoning, per model family. pub fn get_disabled_thinking_config(model_id: &str) -> Value { - // Gemini 3.1 Pro cannot disable thinking, and Gemini 3 Flash / Flash-Lite - // do not support full thinking-off: use the lowest supported level without - // includeThoughts so hidden thinking remains invisible. + // Gemini 3.1 Pro cannot disable thinking, and Gemini 3 Flash / Flash-Lite do not support full + // thinking-off: use the lowest supported level without includeThoughts so hidden thinking + // remains invisible. if is_gemini3_pro_model(model_id) { return json!({ "thinkingLevel": "LOW" }); } diff --git a/crates/pa-ai/src/providers/google_stream.rs b/crates/pa-ai/src/providers/google_stream.rs index efe80795681..a55de078a60 100644 --- a/crates/pa-ai/src/providers/google_stream.rs +++ b/crates/pa-ai/src/providers/google_stream.rs @@ -1,9 +1,6 @@ -//! Shared Google stream-chunk processing. -//! -//! The chunk handler in the TS reference is duplicated across `google.ts` and -//! `google-vertex.ts`; this module is the single Rust implementation used by -//! both providers: text/thinking part transitions with thought-signature -//! retention, function-call tool calls, finish-reason mapping, and usage +//! Shared Google stream-chunk processing: the single Rust implementation of the chunk handler the +//! TS duplicates across `google.ts` and `google-vertex.ts` — text/thinking part transitions with +//! thought-signature retention, function-call tool calls, finish-reason mapping, and usage //! accounting. use serde_json::{Map, Value}; @@ -65,7 +62,7 @@ impl GoogleStreamState { } /// Process one streamed `GenerateContentResponse` chunk. - // Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. + // Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] pub fn handle_chunk( &mut self, diff --git a/crates/pa-ai/src/providers/google_vertex.rs b/crates/pa-ai/src/providers/google_vertex.rs index 49e45a39840..f4d8a8181fc 100644 --- a/crates/pa-ai/src/providers/google_vertex.rs +++ b/crates/pa-ai/src/providers/google_vertex.rs @@ -1,7 +1,6 @@ -//! Google Vertex AI streaming provider. -//! Port of `packages/ai/src/providers/google-vertex.ts`: project/location -//! resolution, API-key or OAuth (ADC) authentication, the Vertex -//! `streamGenerateContent` endpoint, and the shared Google stream processor. +//! Google Vertex AI streaming provider: project/location resolution, API-key or OAuth (ADC) +//! authentication, the Vertex `streamGenerateContent` endpoint, and the shared Google stream +//! processor. use serde_json::{json, Map, Value}; @@ -35,7 +34,7 @@ use crate::utils_inner::stream_failure::{ pub const VERTEX_API_VERSION: &str = "v1"; const GCP_VERTEX_CREDENTIALS_MARKER: &str = "gcp-vertex-credentials"; -/// Provider-native options (`GoogleVertexOptions` in the TS reference). +/// Provider-native options. #[derive(Clone, Default)] pub struct GoogleVertexOptions { pub base: StreamOptions, @@ -95,9 +94,9 @@ fn resolve_location(options: &GoogleVertexOptions) -> Result { /// Resolve an OAuth access token for Application Default Credentials. /// -/// The TS reference uses google-auth-library ADC. Here the token comes from an -/// explicit `GOOGLE_OAUTH_ACCESS_TOKEN` env var, or from the gcloud CLI's -/// credential source; failures surface as provider errors. +/// Divergence from the TS google-auth-library ADC: the token comes from an explicit +/// `GOOGLE_OAUTH_ACCESS_TOKEN` env var or the gcloud CLI's credential source; failures surface as +/// provider errors. fn resolve_adc_access_token() -> Result { if let Ok(token) = std::env::var("GOOGLE_OAUTH_ACCESS_TOKEN") { if !token.trim().is_empty() { @@ -141,7 +140,6 @@ fn base_url_includes_api_version(base_url: &str) -> bool { }) } -/// Port of `streamGoogleVertex`. pub fn stream_google_vertex( model: &Model, context: &Context, @@ -268,7 +266,7 @@ fn build_params(model: &Model, context: &Context, options: &GoogleVertexOptions) Value::Object(body) } -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] async fn run_stream( model: &Model, @@ -354,9 +352,6 @@ async fn run_stream( on_response( crate::types::ProviderResponse { status: response.status, - // Collected into the ordered map: the hook payload can - // serialize, and the HTTP header arrival order is not a - // stable serialization order. headers: response.headers.clone().into_iter().collect(), }, model, @@ -365,9 +360,9 @@ async fn run_stream( if response.status >= 400 { let body = response.read_all_text().await.unwrap_or_default(); - // The genai `ApiError` carries no `.error` object for the TS - // classifier (its `code` is numeric): the class name is the - // provider error type and the classified form carries no detail. + // The genai `ApiError` carries no `.error` object for the TS classifier (its `code` is + // numeric): the class name is the provider error type and the classified form carries no + // detail. let mut error = ProviderError::from_http_status_body(response.status, &body, response.headers.clone()); if let ProviderError::Http(http) = &mut error { @@ -430,7 +425,6 @@ async fn run_stream( Ok(()) } -/// Port of `streamSimpleGoogleVertex`. pub fn stream_simple_google_vertex( model: &Model, context: &Context, @@ -447,11 +441,9 @@ pub fn stream_simple_google_vertex( stream_google_vertex(model, context, Some(&stream_options)) } -/// The thinking arm `stream_simple_google_vertex` picks for a model + -/// reasoning level: disabled, level-based, or budget-based. Level-based covers -/// Gemini 3 Pro/Flash and Gemma 4 (TS #2946: the Gemini API rejects -/// `thinkingBudget` with a 400 for Gemma 4, so it must ride `thinkingLevel` -/// like the Generative AI provider has since ee2483cd3). +/// The thinking arm `stream_simple_google_vertex` picks for a model + reasoning level: disabled, +/// level-based, or budget-based. Level-based covers Gemini 3 Pro/Flash and Gemma 4 (the Gemini API +/// rejects `thinkingBudget` with a 400 for Gemma 4, so it must ride `thinkingLevel`). fn resolve_simple_thinking( model: &Model, options: Option<&SimpleStreamOptions>, @@ -551,9 +543,8 @@ mod tests { } } - /// TS #2946: Gemma 4 on Vertex rides `thinkingLevel` (like the Generative - /// AI provider since ee2483cd3), never `thinkingBudget` — the Gemini API - /// answers a budget for Gemma 4 with a 400. + /// Gemma 4 on Vertex rides `thinkingLevel`, never `thinkingBudget` — the Gemini API answers a + /// budget for Gemma 4 with a 400 (TS #2946). #[test] fn gemma4_reasoning_uses_thinking_levels_not_budgets() { let model = gemma4_model(); @@ -587,8 +578,8 @@ mod tests { ); } - /// A budget-based model keeps the budget arm (the level list must not - /// swallow the default path). + /// A budget-based model keeps the budget arm (the level list must not swallow the default + /// path). #[test] fn gemini2_keeps_the_budget_arm() { let model = serde_json::from_value::(json!({ diff --git a/crates/pa-ai/src/providers/mistral/convert.rs b/crates/pa-ai/src/providers/mistral/convert.rs index 02915e44898..0b14b2567ba 100644 --- a/crates/pa-ai/src/providers/mistral/convert.rs +++ b/crates/pa-ai/src/providers/mistral/convert.rs @@ -1,6 +1,5 @@ //! Mistral Conversations conversion: tools, chat messages, tool-result text, //! chat payload assembly, and tool-call-id derivation/normalization. -//! Section of the port of `packages/ai/src/providers/mistral.ts`. use std::cell::RefCell; use std::collections::HashMap; @@ -14,8 +13,7 @@ use crate::utils_inner::sanitize_unicode::sanitize_surrogates; const MISTRAL_TOOL_CALL_ID_LENGTH: usize = 9; -/// Stateful tool-call-id normalizer port -/// (`createMistralToolCallIdNormalizer` in the TS reference). +/// Stateful tool-call-id normalizer (TS `createMistralToolCallIdNormalizer`). #[derive(Default)] pub(crate) struct MistralToolCallIdNormalizer { id_map: RefCell>, @@ -45,7 +43,6 @@ impl MistralToolCallIdNormalizer { } } -/// Port of `deriveMistralToolCallId`. pub(crate) fn derive_mistral_tool_call_id(id: &str, attempt: u32) -> String { let normalized: String = id.chars().filter(char::is_ascii_alphanumeric).collect(); if attempt == 0 && normalized.len() == MISTRAL_TOOL_CALL_ID_LENGTH { @@ -115,7 +112,6 @@ pub(crate) fn build_chat_payload( Value::Object(payload) } -/// Port of `toFunctionTools`. fn to_function_tools(tools: &[Tool]) -> Vec { tools .iter() @@ -133,7 +129,7 @@ fn to_function_tools(tools: &[Tool]) -> Vec { .collect() } -/// Port of `stripSymbolKeys`: rebuild the JSON tree as plain objects. +/// Rebuild the JSON tree as plain objects (TS `stripSymbolKeys`). fn strip_symbol_keys(value: &Value) -> Value { match value { Value::Array(items) => Value::Array(items.iter().map(strip_symbol_keys).collect()), @@ -148,8 +144,7 @@ fn strip_symbol_keys(value: &Value) -> Value { } } -/// Port of `toChatMessages`. -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] fn to_chat_messages(messages: &[Message], supports_images: bool) -> Vec { let mut result: Vec = Vec::new(); @@ -308,7 +303,6 @@ fn to_chat_messages(messages: &[Message], supports_images: bool) -> Vec { result } -/// Port of `buildToolResultText`. fn build_tool_result_text( text: &str, has_images: bool, diff --git a/crates/pa-ai/src/providers/mistral/mod.rs b/crates/pa-ai/src/providers/mistral/mod.rs index 94e2e256c3b..d3ec0a7284a 100644 --- a/crates/pa-ai/src/providers/mistral/mod.rs +++ b/crates/pa-ai/src/providers/mistral/mod.rs @@ -1,14 +1,7 @@ -//! Mistral Conversations streaming provider. -//! Port of `packages/ai/src/providers/mistral.ts`: `chat/completions` SSE -//! streaming with camelCase-free `snake_case` wire keys (verified against the -//! `@mistralai/mistralai` SDK outbound schemas), thinking text-block -//! accumulation, tool-call argument streaming, `x-affinity` KV-cache header, -//! and usage accounting. -//! -//! Split across submodules mirroring the `anthropic/openai_completions` -//! layout: request options, headers, and the simple-stream entry live here, -//! message/tool conversion and payload assembly in [`convert`], and the SSE -//! streaming core in [`stream`]. +//! Mistral Conversations streaming provider: `chat/completions` SSE streaming with camelCase-free +//! `snake_case` wire keys (verified against the `@mistralai/mistralai` SDK outbound schemas), +//! thinking text-block accumulation, tool-call argument streaming, the `x-affinity` KV-cache +//! header, and usage accounting. Conversion lives in [`convert`], the streaming core in [`stream`]. use serde_json::Map; @@ -33,7 +26,7 @@ pub use stream::stream_mistral; pub const API_MISTRAL_CONVERSATIONS: &str = "mistral-conversations"; -/// Mistral reasoning-effort values (`MistralReasoningEffort` in the TS). +/// Mistral reasoning-effort values. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum MistralReasoningEffort { None, @@ -63,7 +56,7 @@ impl MistralPromptMode { } } -/// Tool selection (`toolChoice` in the TS reference). +/// Tool selection. #[allow(dead_code)] // full TS option surface; variants set by callers #[derive(Clone, Debug, PartialEq)] pub enum MistralToolChoice { @@ -88,7 +81,7 @@ impl MistralToolChoice { } } -/// Provider-specific request options (`MistralOptions` in the TS reference). +/// Provider-specific request options. #[derive(Clone, Default)] pub struct MistralOptions { pub base: StreamOptions, @@ -123,8 +116,8 @@ pub(crate) fn build_request_headers( headers.push((name.clone(), value.clone())); } } - // Mistral infrastructure uses `x-affinity` for KV-cache reuse (prefix - // caching). Respect explicit caller-provided header values. + // Mistral infrastructure uses `x-affinity` for KV-cache reuse (prefix caching). Respect + // explicit caller-provided header values. if let Some(session_id) = &options.base.session_id { if !headers.iter().any(|(name, _)| name == "x-affinity") { headers.push(("x-affinity".into(), session_id.clone())); @@ -156,7 +149,6 @@ fn map_reasoning_effort(model: &Model, level: ModelThinkingLevel) -> MistralReas } } -/// Port of `streamSimpleMistral`. pub fn stream_simple_mistral( model: &Model, context: &Context, diff --git a/crates/pa-ai/src/providers/mistral/stream.rs b/crates/pa-ai/src/providers/mistral/stream.rs index 4c85139491f..325d1699c20 100644 --- a/crates/pa-ai/src/providers/mistral/stream.rs +++ b/crates/pa-ai/src/providers/mistral/stream.rs @@ -1,6 +1,5 @@ //! Mistral Conversations streaming core: the provider stream function, SSE //! iteration, chunk handling, and stream-state accumulation. -//! Section of the port of `packages/ai/src/providers/mistral.ts`. use std::fmt::Write as _; @@ -36,7 +35,6 @@ use crate::utils_inner::stream_failure::{ const MAX_MISTRAL_ERROR_BODY_CHARS: usize = 4000; -/// Port of `streamMistral`. pub fn stream_mistral( model: &Model, context: &Context, @@ -79,8 +77,8 @@ pub fn stream_mistral( } else { StopReason::Error }; - // TS surfaces `formatMistralError(error)`: the SDK's - // statusCode/body composition, not the classified rewrite. + // TS surfaces `formatMistralError(error)`: the SDK's statusCode/body composition, + // not the classified rewrite. output.error_message = Some(error.to_string()); record_stream_failure( (&model.provider, &model.id, &model.api), @@ -99,8 +97,8 @@ pub fn stream_mistral( reader } -/// Coerce a parsed streaming JSON value into an object map (non-object -/// partial parses decode to `{}`, matching `parseStreamingJson>`). +/// Coerce a parsed streaming JSON value into an object map (non-object partial parses decode to +/// `{}`, matching `parseStreamingJson>`). fn json_object(value: Value) -> Map { match value { Value::Object(map) => map, @@ -108,7 +106,6 @@ fn json_object(value: Value) -> Map { } } -/// Port of `mapChatStopReason`. fn map_chat_stop_reason(reason: Option<&str>) -> StopReason { match reason { Some("length" | "model_length") => StopReason::Length, @@ -118,9 +115,8 @@ fn map_chat_stop_reason(reason: Option<&str>) -> StopReason { } } -/// JS `String.prototype.length` semantics (UTF-16 code units) so the -/// truncation limit and the reported remainder match the TS binary -/// byte-for-byte on the body text. +/// JS `String.prototype.length` semantics (UTF-16 code units) so the truncation limit and the +/// reported remainder match the TS binary byte-for-byte. fn truncate_error_text(text: &str, max_chars: usize) -> String { let total: usize = text.chars().map(char::len_utf16).sum(); if total <= max_chars { @@ -146,17 +142,16 @@ fn truncate_error_text(text: &str, max_chars: usize) -> String { ) } -/// The `@mistralai/mistralai` SDK error class name for HTTP failures -/// (`SDKError`, the fallback class the stream error matcher throws). +/// The `@mistralai/mistralai` SDK error class name for HTTP failures (`SDKError`, the fallback +/// class the stream error matcher throws). const MISTRAL_SDK_ERROR_NAME: &str = "SDKError"; -/// The `SDKError` message the mistral SDK composes -/// (`"{prefix}: Status {N}[ Content-Type ...]. |\nBody: {body}"`), used both -/// where TS surfaces it verbatim (empty-body error path) and in diagnostics. +/// The `SDKError` message the mistral SDK composes (`"{prefix}: Status {N}[ Content-Type ...]. +/// |\nBody: {body}"`), used both where TS surfaces it verbatim (empty-body error path) and in +/// diagnostics. fn mistral_sdk_error_message(status: u16, content_type: Option<&str>, body: &str) -> String { let mut message = format!("API error occurred: Status {status}"); - // The SDK reads the raw content-type header; a missing one renders as - // the literal string `""`. + // The SDK reads the raw content-type header; a missing one renders as the literal string `""`. let content_type = content_type.unwrap_or(r#""""#); if content_type != "application/json" { let quoted = if content_type.contains(' ') { @@ -168,8 +163,7 @@ fn mistral_sdk_error_message(status: u16, content_type: Option<&str>, body: &str } let body_utf16_len: usize = body.chars().map(char::len_utf16).sum(); let body_display = if body_utf16_len > 10_000 { - // JS `substring(0, 10000)` cuts on UTF-16 code units; walk to the - // enclosing char boundary and report the remainder in code units. + // JS `substring(0, 10000)` cuts on UTF-16 code units; walk to the enclosing char boundary. let mut consumed = 0usize; let mut end = body.len(); for (index, char) in body.char_indices() { @@ -195,9 +189,8 @@ fn mistral_sdk_error_message(status: u16, content_type: Option<&str>, body: &str message.trim().to_string() } -/// Port of the error the mistral SDK throws for a 4XX/5XX response -/// (`SDKError` carrying `statusCode` and the raw body), with the -/// user-facing message pre-composed through `formatMistralError`. +/// The error the mistral SDK throws for a 4XX/5XX response (`SDKError` carrying `statusCode` and +/// the raw body), with the user-facing message pre-composed through `formatMistralError`. fn mistral_http_error(status: u16, body: &str, headers: &HashMap) -> ProviderError { let body_text = body.trim(); let content_type = headers @@ -228,7 +221,7 @@ fn mistral_http_error(status: u16, body: &str, headers: &HashMap }) } -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] async fn run_stream( model: &Model, @@ -270,8 +263,8 @@ async fn run_stream( } } - // The mistralai SDK defaults to https://api.mistral.ai and posts to - // /v1/chat/completions; a model baseUrl replaces the server URL only. + // The mistralai SDK defaults to https://api.mistral.ai and posts to /v1/chat/completions; a + // model baseUrl replaces the server URL only. let base_url = if model.base_url.is_empty() { "https://api.mistral.ai".to_string() } else { @@ -299,9 +292,6 @@ async fn run_stream( on_response( crate::types::ProviderResponse { status: response.status, - // Collected into the ordered map: the hook payload can - // serialize, and the HTTP header arrival order is not a - // stable serialization order. headers: response.headers.clone().into_iter().collect(), }, model, @@ -322,9 +312,8 @@ async fn run_stream( }); let mut state = MistralStreamState::new(); - // The TS try/catch encloses this whole streaming section, including the - // abort and stop-reason checks; the catch settles partial tool calls - // before the error event carries the message (TS PR #2783). + // The TS try/catch encloses this whole streaming section, including the abort and stop-reason + // checks; the catch settles partial tool calls before the error event carries the message. let stream_result: Result<(), ProviderError> = async { let mut decoder = SseDecoder::new(); loop { @@ -399,8 +388,8 @@ impl MistralStreamState { } } - /// Port of the TS catch settle: finalize tool-call blocks whose parsed - /// preview may lag the accumulated text under the growth throttle. + /// The TS catch settle: finalize tool-call blocks whose parsed preview may lag the accumulated + /// text under the growth throttle. fn settle_partial_tool_calls(&mut self, output: &mut AssistantMessage) { for (block_index, accumulator) in &mut self.tool_partial_args { let Some(AssistantContent::ToolCall(block)) = output.content.get_mut(*block_index) @@ -495,7 +484,7 @@ impl MistralStreamState { } /// Port of the `consumeChatStream` chunk loop body. - // Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. + // Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] fn handle_chunk( &mut self, @@ -526,10 +515,9 @@ impl MistralStreamState { output.usage.output = completion; output.usage.cache_read = 0; output.usage.cache_write = 0; - // TS `totalTokens || input + output`: an explicitly reported zero - // is falsy, so only a positive reported total is kept. The sum - // saturates — TS doubles never wrap, and a Rust u64 must not - // panic (debug) or wrap to a wrong total (release). + // TS `totalTokens || input + output`: an explicitly reported zero is falsy, so only a + // positive reported total is kept. The sum saturates — TS doubles never wrap, and a + // Rust u64 must not panic (debug) or wrap to a wrong total (release). output.usage.total_tokens = usage .get("total_tokens") .and_then(Value::as_u64) @@ -734,8 +722,8 @@ impl MistralStreamState { mod tests { use super::*; - /// The TS `formatMistralError` shape: "Mistral API error (N): ", - /// truncated at 4000 chars (UTF-16 units) with the JS remainder count. + /// The TS `formatMistralError` shape: "Mistral API error (N): ", truncated at 4000 chars + /// (UTF-16 units) with the JS remainder count. #[test] fn mistral_http_error_body_shape() { let headers = HashMap::new(); @@ -757,8 +745,8 @@ mod tests { ); } - /// An empty error body falls back to the SDK's own composed message, per - /// `formatMistralError`'s statusCode-without-body branch. + /// An empty error body falls back to the SDK's own composed message, per `formatMistralError`'s + /// statusCode-without-body branch. #[test] fn mistral_http_error_empty_body_falls_back_to_sdk_message() { let mut headers = HashMap::new(); @@ -794,9 +782,9 @@ mod tests { ); } - /// Connection-level failures carry the mistral SDK's wrapper shape: the - /// `UnexpectedClientError` fixed prefix over the runtime's refused-connect - /// text, and the `RequestTimeoutError` fixed prefix with the raw cause. + /// Connection-level failures carry the mistral SDK's wrapper shape: the `UnexpectedClientError` + /// fixed prefix over the runtime's refused-connect text, and the `RequestTimeoutError` fixed + /// prefix with the raw cause. #[test] fn mistral_connection_error_texts() { let connect = ProviderError::Connection( @@ -840,10 +828,8 @@ mod tests { assert_eq!(map_chat_stop_reason(Some("whatever")), StopReason::Stop); } - /// TS `mistral.ts` assigns `usage.totalTokens = chunk.usage.totalTokens || - /// input + output`, so an explicitly reported zero total is falsy and - /// falls back to the prompt/completion sum; a positive reported total is - /// kept verbatim. + /// TS assigns `usage.totalTokens = chunk.usage.totalTokens || input + output`, so an explicitly + /// reported zero total is falsy and falls back to the prompt/completion sum. #[test] fn usage_total_tokens_explicit_zero_falls_back_to_sum() { use serde_json::json; diff --git a/crates/pa-ai/src/providers/openai_codex_responses/errors.rs b/crates/pa-ai/src/providers/openai_codex_responses/errors.rs index 0885c036969..e47a7b45257 100644 --- a/crates/pa-ai/src/providers/openai_codex_responses/errors.rs +++ b/crates/pa-ai/src/providers/openai_codex_responses/errors.rs @@ -1,6 +1,4 @@ //! Codex API error types and event mapping. -//! Section of the port of -//! `packages/ai/src/providers/openai-codex-responses.ts`. use std::collections::HashMap; @@ -12,8 +10,7 @@ use crate::utils_inner::diagnostics::now_ms; use crate::utils_inner::http::HttpResponse; use crate::utils_inner::stream_failure::ProviderError; -/// Codex API error (`CodexApiError` in the TS reference). Carries the wire -/// error code, HTTP status, and retry delay parsed from headers/body. +/// Codex API error. #[derive(Debug, Clone)] #[allow(dead_code)] // full TS error surface; fields are read by future retry plumbing pub struct CodexApiError { @@ -36,16 +33,14 @@ impl CodexApiError { } } - /// The TS provider surfaces `CodexApiError.message` verbatim (its catch - /// sets `output.errorMessage = error.message`, keeping the usage-limit - /// friendly text); the structured pieces ride along for the - /// `provider_stream_failure` diagnostic and retry classification. + /// The TS provider surfaces `CodexApiError.message` verbatim (the usage-limit friendly text + /// included) instead of the classified rewrite. pub fn into_provider_error(self) -> ProviderError { ProviderError::Http(crate::utils_inner::stream_failure::ProviderHttpError { message: self.message, status: self.status, - // The TS error carries its wire `code` and no body/error field: - // the classification reads the code, not a parsed body. + // The TS error carries its wire `code` and no body/error field: the classification + // reads the code, not a parsed body. body: None, headers: HashMap::new(), request_id: None, @@ -62,21 +57,19 @@ impl std::fmt::Display for CodexApiError { } } -/// Codex protocol (framing/JSON) error (`CodexProtocolError` in the TS). +/// Codex protocol (framing/JSON) error. #[derive(Debug, Clone)] pub struct CodexProtocolError { pub message: String, - /// The invalid frame the TS error keeps for debugging; user-facing text - /// never embeds it. + /// The invalid frame the TS error keeps for debugging; user-facing text never embeds it. #[allow(dead_code)] // full TS error surface; parity helper for debugging pub payload: Option, } impl CodexProtocolError { pub fn into_provider_error(self) -> ProviderError { - // TS surfaces `CodexProtocolError.message` verbatim; the payload - // stays on the error (here: nowhere user-facing), and the class name - // is recorded for the diagnostic. + // TS surfaces `CodexProtocolError.message` verbatim; the payload stays non-user-facing and + // the class name is recorded for the diagnostic. ProviderError::Http(crate::utils_inner::stream_failure::ProviderHttpError { message: self.message, status: None, @@ -90,23 +83,20 @@ impl CodexProtocolError { } } -/// The TS WebSocket transport-error surface, probe-verified against the TS -/// binary (bun runtime): close-event failures compose the -/// `WebSocket closed {code} {reason}` message, carry the numeric close code -/// the diagnostics record, and record the `WebSocketCloseError` class name; -/// every other runtime failure (connect, send) is a plain `Error` with no -/// close code. +/// The TS WebSocket transport-error surface, probe-verified against the TS binary (bun runtime): +/// close-event failures compose `WebSocket closed {code} {reason}` and record the +/// `WebSocketCloseError` class name; every other runtime failure is a plain `Error` with no close +/// code. #[derive(Debug, Clone, PartialEq, Eq)] pub enum WebSocketTransportError { - /// A close-event failure (`WebSocketCloseError` in the TS): the composed - /// close message plus the numeric close code. + /// A close-event failure: the composed close message plus the numeric close code. Close { message: String, code: u16 }, - /// A connect- or send-phase runtime failure (plain `Error` in the TS). + /// A connect- or send-phase runtime failure. Runtime { message: String }, } -/// Close code the TS runtime reports for a close frame that carries none -/// (WHATWG `Status`; probe-pinned as "WebSocket closed 1005"). +/// Close code the TS runtime reports for a close frame that carries none (WHATWG `Status`; +/// probe-pinned as "WebSocket closed 1005"). pub const WEBSOCKET_CLOSE_CODE_STATUS: u16 = 1005; /// Close code the runtime reports for a socket death without a close frame. pub const WEBSOCKET_CLOSE_CODE_ABNORMAL: u16 = 1006; @@ -118,9 +108,8 @@ pub const WEBSOCKET_CLOSE_CODE_TOO_BIG: u16 = 1009; pub const WEBSOCKET_CONNECTION_ENDED_REASON: &str = "Connection ended"; impl WebSocketTransportError { - /// Port of `extractWebSocketCloseError`'s composition: - /// `WebSocket closed {code} {reason}` (trimmed), with the 1009 no-reason - /// special case (`"message too big"`). + /// `extractWebSocketCloseError`'s composition: `WebSocket closed {code} {reason}` (trimmed), + /// with the 1009 no-reason special case (`"message too big"`). pub fn close(code: u16, reason: &str) -> Self { let mut reason_text = if reason.is_empty() { String::new() @@ -179,8 +168,7 @@ impl std::fmt::Display for WebSocketTransportError { pub enum CodexStreamError { Api(CodexApiError), Protocol(CodexProtocolError), - /// Transport-level failure (WebSocket close/connect error) with the TS - /// runtime's error surface. + /// Transport-level failure with the TS runtime's error surface. Transport(WebSocketTransportError), /// Abort requested by the cancellation token. Aborted, @@ -216,7 +204,6 @@ impl CodexStreamError { } } - /// Port of `isCodexNonTransportError`. pub fn is_non_transport_error(&self) -> bool { matches!( self, @@ -236,8 +223,8 @@ impl std::fmt::Display for CodexStreamError { } } -/// Port of `isStaleCodexContinuationError`: a `previous_response_not_found` -/// API error means the request must be resent in full instead of chained. +/// A `previous_response_not_found` API error means the request must be resent in full instead of +/// chained. pub fn is_stale_codex_continuation_error(error: &CodexStreamError) -> bool { match error { CodexStreamError::Api(api) => api @@ -250,7 +237,6 @@ pub fn is_stale_codex_continuation_error(error: &CodexStreamError) -> bool { const STALE_CONTINUATION_ERROR_CODE: &str = "previous_response_not_found"; -/// Codex error payload fields (`CodexErrorPayload` in the TS). struct CodexErrorPayload<'a> { code: Option<&'a str>, type_: Option<&'a str>, @@ -270,7 +256,6 @@ fn error_payload(value: &Value) -> CodexErrorPayload<'_> { } } -/// Port of `codexUsageLimitMessage`. fn codex_usage_limit_message( error: &CodexErrorPayload<'_>, status: Option, @@ -320,9 +305,8 @@ fn code_regex_match(code: &str) -> bool { || code.contains("rate_limit_exceeded") } -/// Port of `parseErrorResponse`: map an HTTP error response to a -/// [`CodexApiError`], honoring usage-limit friendly messages and the -/// max(Retry-After header, `resets_at`) rule. +/// Map an HTTP error response to a [`CodexApiError`], honoring usage-limit friendly messages and +/// the max(Retry-After header, `resets_at`) rule. pub async fn parse_error_response(response: &mut HttpResponse) -> CodexApiError { let status = response.status; let mut message; @@ -330,8 +314,8 @@ pub async fn parse_error_response(response: &mut HttpResponse) -> CodexApiError let mut retry_after_ms = parse_retry_after_ms(&response.headers); let raw = response.read_all_text().await.unwrap_or_default(); - // TS: `raw || response.statusText || "Request failed"`. The HTTP reason - // phrase is the canonical one (what real servers send). + // TS: `raw || response.statusText || "Request failed"`. The HTTP reason phrase is the canonical + // one (what real servers send). message = if raw.is_empty() { reqwest::StatusCode::from_u16(status) .ok() @@ -350,8 +334,7 @@ pub async fn parse_error_response(response: &mut HttpResponse) -> CodexApiError codex_usage_limit_message(&payload, Some(status)) { message = friendly; - // Neither server delay (Retry-After header, resets_at body) - // may undercut the other. + // Neither server delay (Retry-After header, resets_at body) may undercut the other. if let Some(body_retry_after_ms) = body_retry_after_ms { retry_after_ms = Some(retry_after_ms.unwrap_or(0).max(body_retry_after_ms)); } @@ -378,8 +361,7 @@ pub struct MappedCodexEvent { pub done: bool, } -/// Port of `mapCodexEvents` for one event. Errors arrive flat -/// (`{ code, message }`) or nested under `event.error`. +/// Errors arrive flat (`{ code, message }`) or nested under `event.error`. pub fn map_codex_event(event: Value) -> Result { let Some(event_type) = event.get("type").and_then(Value::as_str) else { return Ok(MappedCodexEvent { event, done: false }); @@ -484,7 +466,6 @@ pub fn map_codex_event(event: Value) -> Result Option<&'static str> { match status.as_str() { Some("completed") => Some("completed"), @@ -497,9 +478,7 @@ fn normalize_codex_status(status: &Value) -> Option<&'static str> { } } -/// Multipliers per -/// (retrieved 2026-08-21). Takes the wire-tier string to match the shared -/// Responses hook signature. +/// Multipliers per (retrieved 2026-08-21). pub fn get_codex_service_tier_cost_multiplier(model_id: &str, service_tier: Option<&str>) -> f64 { match service_tier { Some("flex") => 0.5, @@ -514,7 +493,6 @@ pub fn get_codex_service_tier_cost_multiplier(model_id: &str, service_tier: Opti } } -/// Port of `applyServiceTierPricing` (codex variant). pub fn apply_codex_service_tier_pricing( usage: &mut Usage, service_tier: Option<&str>, @@ -537,7 +515,6 @@ pub fn apply_codex_service_tier_pricing( .into(); } -/// Port of `resolveCodexServiceTier`. pub fn resolve_codex_service_tier( response_service_tier: Option, request_service_tier: Option, @@ -550,12 +527,9 @@ pub fn resolve_codex_service_tier( response_service_tier.or(request_service_tier) } -/// Port of the transport-failure diagnostic payload. The TS attaches it via -/// `appendAssistantMessageDiagnostic(output, createAssistantMessageDiagnostic(...))`, -/// and `extractDiagnosticError` records the thrown error's runtime class -/// name (`WebSocketCloseError` for close events, plain `Error` otherwise) -/// and, for close events, the numeric close code as `error.code` -/// (TS-binary probe-verified). +/// The transport-failure diagnostic payload (TS-binary probe-verified): the thrown error's runtime +/// class name (`WebSocketCloseError` for close events, plain `Error` otherwise) and, for close +/// events, the numeric close code as `error.code`. pub fn append_transport_failure_diagnostic( output: &mut AssistantMessage, error: &WebSocketTransportError, @@ -583,9 +557,8 @@ pub fn append_transport_failure_diagnostic( crate::utils_inner::diagnostics::append_assistant_message_diagnostic(output, diagnostic); } -/// Port of the diagnostic's `details`: the TS sets `fallbackTransport: -/// websocketStarted ? undefined : "sse"`, and `JSON.stringify` omits the -/// undefined key entirely, so the after-start diagnostic carries no key. +/// The diagnostic's `details`: after start the TS leaves `fallbackTransport` undefined, and +/// `JSON.stringify` omits the key entirely. fn transport_failure_details( configured_transport: &str, events_emitted: bool, @@ -636,8 +609,8 @@ mod tests { panic!("expected API error"); }; assert_eq!(api.status, Some(429)); - // Flat errors surface the raw message with the codex prefix (the TS - // only builds friendly usage-limit text from nested payloads). + // Flat errors surface the raw message with the codex prefix; friendly usage-limit text is + // built only from nested payloads. assert_eq!(api.message, "Codex error: limit hit"); } @@ -727,10 +700,8 @@ mod tests { assert_eq!(resolve_codex_service_tier(None, None), None); } - /// The TS provider surfaces `CodexApiError.message` verbatim — the - /// usage-limit friendly text included — instead of the classified - /// stream-failure rewrite, while the diagnostic keeps the structured - /// classification (kind, provider type, status, retry delay). + /// The TS provider surfaces `CodexApiError.message` verbatim instead of the classified rewrite, + /// while the diagnostic keeps the structured classification. #[test] fn api_error_message_stays_verbatim_with_structured_info() { let api_error = CodexApiError { @@ -756,14 +727,12 @@ mod tests { crate::utils_inner::stream_failure::StreamFailureKind::RateLimit, info.kind ); - // The diagnostic records the TS SDK error class name. let diagnostic = crate::utils_inner::stream_failure::diagnostic_error_info(&error); assert_eq!(diagnostic.name.as_deref(), Some("CodexApiError")); } - /// A plain HTTP-level codex error keeps the server's error message text - /// (the classified rewrite would turn it into - /// "Provider rejected the request (400): ..."). + /// A plain HTTP-level codex error keeps the server's error message text (the classified rewrite + /// would turn it into "Provider rejected the request (400): ..."). #[test] fn api_error_http_message_stays_verbatim() { let api_error = CodexApiError { @@ -783,8 +752,8 @@ mod tests { ); } - /// A flat mid-stream error event keeps its "Codex error: ..." composed - /// message through the provider error. + /// A flat mid-stream error event keeps its "Codex error: ..." composed message through the + /// provider error. #[test] fn flat_error_event_message_survives_provider_error() { let error = map_codex_event(json!({ @@ -803,8 +772,8 @@ mod tests { ); } - /// Protocol errors surface their message verbatim and record the TS - /// `CodexProtocolError` class name. + /// Protocol errors surface their message verbatim and record the TS `CodexProtocolError` class + /// name. #[test] fn protocol_error_message_and_name() { let error = CodexStreamError::Protocol(CodexProtocolError { @@ -835,10 +804,8 @@ mod tests { assert_eq!(mapped.event["type"], "response.output_text.delta"); } - /// The transport-failure diagnostic for a close event, before the SSE - /// fallback (TS-binary probe ground truth): the `WebSocketCloseError` - /// name, the numeric close code as `error.code`, and the fallback - /// details; `error.code` is absent for non-close runtime failures. + /// The transport-failure diagnostic for a close event before the SSE fallback (TS-binary probe + /// ground truth); `error.code` is absent for non-close runtime failures. #[test] fn transport_failure_diagnostic_shapes() { let close = WebSocketTransportError::close(1011, "mock server reason"); @@ -901,11 +868,9 @@ mod tests { ); } - /// A transport error thrown mid-stream (after events were emitted) - /// carries its TS surface through the provider error: the verbatim - /// runtime text, the `WebSocketCloseError` name, and the close code — - /// exactly what the TS `provider_stream_failure` diagnostic records - /// (TS-binary probe ground truth). + /// A transport error thrown mid-stream carries its TS surface through the provider error, + /// exactly what the TS `provider_stream_failure` diagnostic records (TS-binary probe ground + /// truth). #[test] fn transport_error_provider_stream_failure_shape() { let error = diff --git a/crates/pa-ai/src/providers/openai_codex_responses/mod.rs b/crates/pa-ai/src/providers/openai_codex_responses/mod.rs index ec81d7e437d..712bab1827e 100644 --- a/crates/pa-ai/src/providers/openai_codex_responses/mod.rs +++ b/crates/pa-ai/src/providers/openai_codex_responses/mod.rs @@ -1,11 +1,6 @@ -//! `OpenAI` Codex Responses streaming provider (`openai-codex-responses`). -//! -//! Port of `packages/ai/src/providers/openai-codex-responses.ts`: the `ChatGPT` -//! backend Codex endpoint over WebSocket (session-cached connections with -//! connection-anchored continuation deltas, SSE fallback on transport -//! failures) and plain SSE, JWT `chatgpt-account-id` extraction, usage-limit -//! friendly errors, and service-tier pricing. The stream processing itself is -//! the shared Responses processor ([`crate::providers::openai_responses_shared`]). +//! `OpenAI` Codex Responses streaming provider (`openai-codex-responses`): the `ChatGPT` backend +//! Codex endpoint over WebSocket (session-cached connections with connection-anchored continuation +//! deltas, SSE fallback on transport failures) and plain SSE. use serde_json::{json, Map, Value}; @@ -55,7 +50,7 @@ pub(crate) mod websocket; pub const API_OPENAI_CODEX_RESPONSES: &str = "openai-codex-responses"; -/// Provider-native options (`OpenAICodexResponsesOptions` in the TS). +/// Provider-native options. #[derive(Clone, Default)] pub struct OpenAICodexResponsesOptions { pub base: StreamOptions, @@ -96,8 +91,7 @@ impl CodexTextVerbosity { } } -/// `reasoningSummary` option: the TS also accepts raw string forms -/// ("on"/"off"/null); map them through the shared enum. +/// `reasoningSummary` option; the TS also accepts raw string forms ("on"/"off"/null). fn reasoning_summary_value(summary: Option) -> &'static str { match summary { Some(ReasoningSummary::Auto) | None => "auto", @@ -106,7 +100,6 @@ fn reasoning_summary_value(summary: Option) -> &'static str { } } -/// Port of `streamOpenAICodexResponses`. pub fn stream_openai_codex_responses( model: &Model, context: &Context, @@ -149,9 +142,8 @@ pub fn stream_openai_codex_responses( } else { StopReason::Error }; - // The TS provider surfaces `error.message` verbatim (including - // the usage-limit friendly text), not the classified - // stream-failure rewrite other providers apply. + // The TS provider surfaces `error.message` verbatim (including the usage-limit + // friendly text), not the classified stream-failure rewrite other providers apply. output.error_message = Some(error.to_string()); record_stream_failure( (&model.provider, &model.id, &model.api), @@ -170,7 +162,7 @@ pub fn stream_openai_codex_responses( reader } -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] async fn run_stream( model: &Model, @@ -236,10 +228,8 @@ async fn run_stream( if transport != Transport::Sse && !websocket_disabled_for_session { let mut websocket_started = false; - // Retry a stale previous_response_id once on a fresh connection: the - // failed attempt's error cleanup already dropped the cached - // connection, so the retry resends the full request body. Any further - // failure takes the shared error handling below. + // Retry a stale previous_response_id once on a fresh connection (the failed attempt's + // cleanup dropped the cached one); the retry resends the full request body. let mut chain_reset_retried = false; loop { let attempt = run_websocket_attempt( @@ -270,28 +260,24 @@ async fn run_stream( .signal .as_ref() .is_some_and(tokio_util::sync::CancellationToken::is_cancelled); - // Only reset the chain while nothing was streamed yet: - // after the first event the retry would duplicate - // "start"/content events. + // Only reset the chain while nothing was streamed yet: after the first event + // the retry would duplicate "start"/content events. if !aborted && !websocket_started && !chain_reset_retried && is_stale_codex_continuation_error(&error) { chain_reset_retried = true; - // A failed attempt may have supplied response - // metadata before rejecting the continuation. Do - // not retain that dead anchor (TS #2374 - // `delete output.responseId`). + // A failed attempt may have supplied response metadata before rejecting the + // continuation; do not retain that dead anchor (TS #2374). output.response_id = None; continue; } if aborted || error.is_non_transport_error() { return Err(error.into_provider_error()); } - // Aborts and non-transport errors (API/protocol) were - // handled above; only transport failures reach the SSE - // fallback with their diagnostic. + // Aborts and non-transport errors were handled above; only transport failures + // reach the SSE fallback. let transport_error = match &error { CodexStreamError::Transport(transport) => transport, CodexStreamError::Api(_) | CodexStreamError::Protocol(_) => { @@ -343,9 +329,8 @@ async fn run_stream( on_response( crate::types::ProviderResponse { status: response.status, - // Collected into the ordered map: the hook payload can - // serialize, and the HTTP header arrival order is not a - // stable serialization order. + // Collected into the ordered map: the hook payload can serialize, and the HTTP + // header arrival order is not a stable serialization order. headers: response.headers.clone().into_iter().collect(), }, model, @@ -374,20 +359,15 @@ async fn run_stream( Ok(()) } -/// Whether one parsed Codex WebSocket event can produce assistant output -/// consumed by the shared responses processor (TS #2374 -/// `isCodexVisibleResponseEvent`): the terminal families plus the output, -/// reasoning, content, refusal, and function streams. Lifecycle -/// (`response.created`/`response.in_progress`), telemetry, and vendor -/// metadata cannot, so they stay internal and never mark the attempt as -/// user-visible. +/// Whether one parsed Codex WebSocket event can produce assistant output: lifecycle, +/// telemetry, and vendor metadata stay internal and never mark the attempt user-visible. fn is_codex_visible_response_event(event: &Value) -> bool { let Some(event_type) = event.get("type").and_then(Value::as_str) else { return false; }; - // `response.done` normalizes to `response.completed` before the TS - // classifier sees a mapped event, so the raw-type check here must - // accept it too (a terminal-only stream still starts visibly). + // `response.done` normalizes to `response.completed` before the TS classifier sees a mapped + // event, so the raw-type check here must accept it too (a terminal-only stream still starts + // visibly). event_type == "response.completed" || event_type == "response.done" || event_type == "response.incomplete" @@ -398,9 +378,9 @@ fn is_codex_visible_response_event(event: &Value) -> bool { || event_type.starts_with("response.function_") } -/// One WebSocket attempt (port of the websocket branch of `streamOpenAICodexResponses`). +/// One WebSocket attempt. #[allow(clippy::too_many_arguments)] -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] async fn run_websocket_attempt( model: &Model, @@ -425,9 +405,8 @@ async fn run_websocket_attempt( options.base.transport, Some(Transport::WebsocketCached | Transport::Auto) | None ); - // ChatGPT Codex Responses rejects `store: true` ("Store must be set to - // false"). WebSocket continuation still works via connection-scoped - // previous_response_id state. + // ChatGPT Codex Responses rejects `store: true` ("Store must be set to false"). WebSocket + // continuation still works via connection-scoped previous_response_id state. let full_body = body; let continuation = if use_cached_context && connection.cached { take_continuation_for( @@ -468,17 +447,14 @@ async fn run_websocket_attempt( }; let mut start_emitted = false; let mut processor = ResponsesStreamProcessor::new(model, output, writer, hooks); - // The TS catch settles partial tool calls before the error event - // carries the message (TS PR #2783). + // The TS catch settles partial tool calls before the error event carries the message. let streamed: Result<(), CodexStreamError> = async { while let Some(event) = events.recv().await { match event { websocket::WorkerEvent::Event(event) => { - // Codex can emit lifecycle, telemetry, or vendor - // metadata before rejecting a stale continuation. - // Keep the attempt retryable until an event can - // produce output consumed by the shared processor - // (TS #2374's visible-event gate). + // Codex can emit lifecycle, telemetry, or vendor metadata before rejecting + // a stale continuation; keep the attempt retryable until a visible event + // arrives. if !start_emitted && is_codex_visible_response_event(&event) { start_emitted = true; *websocket_started = true; @@ -558,13 +534,13 @@ async fn run_websocket_attempt( } } -/// Rebuild an `AssistantMessage` as a `Message` for continuation-item -/// conversion (the TS passes `{ messages: [output] }` directly). +/// Rebuild an `AssistantMessage` as a `Message` for continuation-item conversion (the TS passes `{ +/// messages: [output] }` directly). fn assistant_as_message(output: &AssistantMessage) -> crate::types::Message { crate::types::Message::Assistant(output.clone()) } -/// Port of `processStream`: SSE decoding + shared processor with codex hooks. +/// SSE decoding + shared processor with codex hooks. async fn run_sse_stream( response: &mut HttpResponse, model: &Model, @@ -581,8 +557,7 @@ async fn run_sse_stream( })), }; let mut processor = ResponsesStreamProcessor::new(model, output, writer, hooks); - // The TS catch settles partial tool calls before the error event carries - // the message (TS PR #2783). + // The TS catch settles partial tool calls before the error event carries the message. let stream_result: Result<(), ProviderError> = async { let mut decoder = SseDecoder::new(); loop { @@ -641,7 +616,6 @@ fn process_sse_chunk( Ok(()) } -/// Port of `buildRequestBody`. fn build_request_body( model: &Model, context: &Context, @@ -757,7 +731,6 @@ fn transport_debug_name(transport: Transport) -> &'static str { } } -/// Port of `streamSimpleOpenAICodexResponses`. pub fn stream_simple_openai_codex_responses( model: &Model, context: &Context, @@ -839,10 +812,8 @@ mod tests { use super::*; use std::collections::HashMap; - /// The user-facing text for a failed codex stream is the verbatim error - /// message; the raw-`fetch` SSE connection failure surfaces the - /// runtime's own refused-connect text (the codex provider uses no HTTP - /// SDK). + /// The user-facing text for a failed codex stream is the verbatim error message; the + /// raw-`fetch` connection failure surfaces the runtime's own refused-connect text. #[test] fn codex_error_message_shapes() { let usage_limit = @@ -915,10 +886,8 @@ mod tests { } } - /// Replay a codex wire turn that issues one function call (the event - /// shapes the #222 codex suite replays) and return the recorded - /// assistant message. `item_id` omits the `fc_` item id from the wire - /// items, the degenerate shape that produced the dogfood + /// Replay a codex wire turn that issues one function call and return the recorded assistant + /// message. `item_id` omits the `fc_` item id, the degenerate shape that produced the /// `[ApiParam][invalid_id]` rejection on the follow-up turn. fn replay_codex_tool_call_turn(model: &Model, item_id: Option<&str>) -> AssistantMessage { let function_call_item = |arguments: &str| { @@ -1072,16 +1041,13 @@ mod tests { .unwrap_or_else(|| panic!("missing function_call item in {items:?}")) } - /// Wire-level verifier: after a codex tool-call turn, the follow-up - /// request replays the recorded rows and every input item carries valid - /// ids (the dogfood bug sent `input[2].id: ""` and the API rejected the - /// turn with `[ApiParam][invalid_id]`). + /// The follow-up request replays the recorded rows and every input item carries valid ids (the + /// dogfood bug sent `input[2].id: ""`, rejected with `[ApiParam][invalid_id]`). #[test] fn codex_tool_call_followup_request_carries_valid_ids() { let model = codex_wire_model(); let output = replay_codex_tool_call_turn(&model, Some("fc_123")); - // The recorded rows carry the `call_id|item_id` encoding and the - // streamed arguments. + // The recorded rows carry the `call_id|item_id` encoding and the streamed arguments. let tool_call = match output.content.last() { Some(crate::types::AssistantContent::ToolCall(tool_call)) => tool_call, other => panic!("expected a recorded tool call, got {other:?}"), @@ -1100,9 +1066,9 @@ mod tests { assert_eq!(function_call.get("call_id"), Some(&json!("call_abc"))); } - /// Degenerate wire shape: `function_call` items without an `fc_` item id. - /// The recorded tool call id carries an empty item segment; the - /// follow-up request must omit the `id` key (never `id: ""`). + /// Degenerate wire shape: `function_call` items without an `fc_` item id. The recorded tool + /// call id carries an empty item segment; the follow-up request must omit the `id` key (never + /// `id: ""`). #[test] fn codex_followup_omits_missing_item_id_instead_of_sending_empty() { let model = codex_wire_model(); @@ -1122,12 +1088,7 @@ mod tests { assert_eq!(function_call.get("call_id"), Some(&json!("call_abc"))); } - // --- TS #2374: the stale-chain retry gate arms on real output only --- - - /// Whether an event family can produce assistant output (the TS - /// `isCodexVisibleResponseEvent` classifier): the terminal, output, - /// reasoning, content, refusal, and function families do; lifecycle, - /// telemetry, and vendor metadata do not. + // TS #2374: the stale-chain retry gate arms on real output only. #[test] fn codex_visible_event_classifier() { let visible = [ @@ -1166,10 +1127,9 @@ mod tests { assert!(!is_codex_visible_response_event(&json!({ "other": 1 }))); } - /// A mock Codex websocket server: one listener serving connections - /// sequentially, each connection answering its scripted requests. The - /// `response.create` bodies are captured (masked client frames), so - /// the tests can assert the continuation anchoring. + /// A mock Codex websocket server: one listener serving connections sequentially, + /// each answering its scripted requests; the `response.create` bodies are captured so + /// tests can assert the continuation anchoring. struct ScriptedCodexServer { port: u16, sent_bodies: std::sync::Arc>>, @@ -1195,10 +1155,9 @@ mod tests { "content_index": 0, "delta": text, }), - // No `output_index` on the done item (the recorded-turn shape): - // the processor retires the slot keyed by the done event's own - // index before reading it back, so a done event carrying one - // would skip the item's text-signature capture. + // No `output_index` on the done item (the recorded-turn shape): the processor retires + // the slot keyed by the done event's own index before reading it back, so a done event + // carrying one would skip the item's text-signature capture. json!({ "type": "response.output_item.done", "item": { "type": "message", "id": message_id, "role": "assistant", "status": "completed", "content": [{ "type": "output_text", "text": text }] }, @@ -1281,9 +1240,9 @@ mod tests { Ok(()) } - /// Spawn the scripted server: `scripts[connection][request]` is the - /// event list the server answers that request with. A connection whose - /// scripts are exhausted is held until the client closes it. + /// Spawn the scripted server: `scripts[connection][request]` is the event list the server + /// answers that request with. A connection whose scripts are exhausted is held until the client + /// closes it. async fn spawn_scripted_codex_server(scripts: Vec>>) -> ScriptedCodexServer { use base64::Engine as _; use sha1::Digest as _; @@ -1329,11 +1288,8 @@ mod tests { .expect("mock write"); let mut request_number = 0usize; loop { - // One frame per iteration: requests answer their - // script in order; a close frame ends the connection - // (answered, so the client's close handshake - // completes) and anything after the scripted - // requests holds without a response. + // One frame per iteration: requests answer their script in order; a close + // frame ends the connection (answered, so the close handshake completes). let Some((opcode, payload)) = read_client_frame(&mut socket).await? else { break; }; @@ -1348,10 +1304,8 @@ mod tests { for event in script { write_server_frame(&mut socket, event).await?; } - // A script that ends in an error closes the - // connection (the real server ends the request - // with the error; the client's read loop needs - // the close to finish its terminal bookkeeping). + // A script that ends in an error closes the connection: the client's + // read loop needs the close to finish its terminal bookkeeping. let ends_in_error = script .last() .and_then(|event| event.get("type")) @@ -1415,9 +1369,8 @@ mod tests { } } - /// The follow-up turn's context: the full conversation (the first - /// user row, the first assistant row, then the new user row), like - /// the TS fixture (`[...firstContext.messages, first, { user }]`). + /// The follow-up turn's context: the full conversation (the first user row, the first assistant + /// row, then the new user row). fn codex_followup_context(first: &AssistantMessage, text: &str) -> Context { Context { system_prompt: Some("You are a helpful assistant.".to_string()), @@ -1446,17 +1399,14 @@ mod tests { }) } - /// TS #2374 regression: lifecycle and vendor metadata events before a - /// stale `previous_response_id` rejection keep the attempt retryable — - /// the provider retries once on a fresh socket with the full request - /// body (no `previous_response_id`), the consumer sees exactly one - /// `start`, and the recovered response id lands. + /// Lifecycle and vendor metadata events before a stale `previous_response_id` rejection + /// keep the attempt retryable; the provider retries once on a fresh socket with the full + /// request body. #[tokio::test] async fn recovers_stale_chain_after_metadata_events() { let server = spawn_scripted_codex_server(vec![ - // Connection 1: request 1 completes (the cached chain anchor), - // request 2 rejects the stale continuation after lifecycle and - // vendor metadata events. + // Connection 1: request 1 completes (the cached chain anchor), request 2 rejects the + // stale continuation after metadata events. vec![ codex_response_events("resp_1", "msg_1", "Hello"), vec![ @@ -1464,8 +1414,6 @@ mod tests { json!({ "type": "response.in_progress", "response": { "id": "resp_stale" } }), json!({ "type": "codex.response.metadata", "headers": {} }), json!({ "type": "responsesapi.websocket_timing", "elapsed_ms": 1 }), - // The pre-fix gate died here: metadata armed the - // start flag, the stale rejection surfaced. codex_error_events( "previous_response_not_found", "Previous response with id 'resp_1' not found.", @@ -1508,7 +1456,6 @@ mod tests { assert_eq!(second.stop_reason, StopReason::Stop); assert_eq!(codex_message_text(&second).as_deref(), Some("Done")); assert_eq!(second.response_id.as_deref(), Some("resp_2")); - // Exactly one start on the recovered attempt, and a final done. assert_eq!( events .iter() @@ -1531,14 +1478,12 @@ mod tests { bodies[2].get("previous_response_id").is_none(), "the retry sends the full context without the dead anchor: {bodies:?}" ); - // The metadata-supplied stale response id must not survive into - // the surfaced message. + // The metadata-supplied stale response id must not survive into the surfaced message. assert_eq!(second.response_id.as_deref(), Some("resp_2")); } - /// The second half of the TS #2374 fix: when the chain-reset retry also - /// fails, the surfaced error carries no dead continuation anchor (the - /// stale attempt's `response.created` id was cleared before retrying). + /// The second half of the TS #2374 fix: when the chain-reset retry also fails, the surfaced + /// error carries no dead continuation anchor. #[tokio::test] async fn retry_failure_surfaces_no_stale_response_id() { let server = spawn_scripted_codex_server(vec![ @@ -1580,7 +1525,6 @@ mod tests { second.error_message.as_deref(), Some("Codex error: Previous response with id 'resp_9' not found.") ); - // The pre-fix bug kept the stale attempt's response id. assert!( second.response_id.is_none(), "the dead continuation anchor must not survive the surfaced error" diff --git a/crates/pa-ai/src/providers/openai_codex_responses/request.rs b/crates/pa-ai/src/providers/openai_codex_responses/request.rs index 60891d5da22..05f137fff78 100644 --- a/crates/pa-ai/src/providers/openai_codex_responses/request.rs +++ b/crates/pa-ai/src/providers/openai_codex_responses/request.rs @@ -1,7 +1,5 @@ //! Request assembly for the Codex Responses provider: URL resolution, //! headers (SSE and WebSocket), JWT account-id extraction, and request ids. -//! Section of the port of -//! `packages/ai/src/providers/openai-codex-responses.ts`. use base64::Engine as _; use serde_json::Value; @@ -13,7 +11,6 @@ use crate::providers::openai_codex_responses::websocket::OPENAI_BETA_RESPONSES_W pub const DEFAULT_CODEX_BASE_URL: &str = "https://chatgpt.com/backend-api"; pub const JWT_CLAIM_PATH: &str = "https://api.openai.com/auth"; -/// Port of `resolveCodexUrl`. pub fn resolve_codex_url(base_url: &str) -> String { let raw = if base_url.trim().is_empty() { DEFAULT_CODEX_BASE_URL @@ -30,15 +27,13 @@ pub fn resolve_codex_url(base_url: &str) -> String { } } -/// Port of `resolveCodexWebSocketUrl`. pub fn resolve_codex_websocket_url(base_url: &str) -> String { resolve_codex_url(base_url) .replacen("https://", "wss://", 1) .replacen("http://", "ws://", 1) } -/// Port of `extractAccountId`: decode the JWT payload and read the -/// `chatgpt_account_id` claim. +/// Decode the JWT payload and read the `chatgpt_account_id` claim. pub fn extract_account_id(token: &str) -> Result { let parts: Vec<&str> = token.split('.').collect(); if parts.len() != 3 { @@ -57,7 +52,6 @@ pub fn extract_account_id(token: &str) -> Result { Ok(account_id.to_string()) } -/// Port of `createCodexRequestId`. pub fn create_codex_request_id() -> String { format!( "codex_{}_{}", @@ -69,7 +63,6 @@ pub fn create_codex_request_id() -> String { ) } -/// Port of `buildBaseCodexHeaders` + `buildSSEHeaders`. pub fn build_sse_headers( model_headers: Option<&std::collections::BTreeMap>, additional_headers: Option<&std::collections::HashMap>, @@ -98,7 +91,6 @@ pub fn build_sse_headers( headers } -/// Port of `buildWebSocketHeaders`. pub fn build_websocket_headers( model_headers: Option<&std::collections::BTreeMap>, additional_headers: Option<&std::collections::HashMap>, @@ -117,8 +109,8 @@ pub fn build_websocket_headers( set_header(&mut headers, "chatgpt-account-id", account_id); set_header(&mut headers, "originator", "pi"); set_header(&mut headers, "User-Agent", &platform_user_agent()); - // The WebSocket handshake drops the SSE beta header (matches the TS - // `delete wsHeaders["OpenAI-Beta"]`). + // The WebSocket handshake drops the SSE beta header (matches the TS `delete + // wsHeaders["OpenAI-Beta"]`). set_header( &mut headers, "OpenAI-Beta", @@ -135,7 +127,7 @@ fn set_header(headers: &mut Vec<(String, String)>, name: &str, value: &str) { headers.push((name.to_string(), value.to_string())); } -/// Port of the `User-Agent` builder: `pi ( ; )`. +/// The `User-Agent` builder: `pi ( ; )`. fn platform_user_agent() -> String { let os = std::env::consts::OS; let arch = std::env::consts::ARCH; diff --git a/crates/pa-ai/src/providers/openai_codex_responses/session.rs b/crates/pa-ai/src/providers/openai_codex_responses/session.rs index 5cba92b1fde..54db58fd40e 100644 --- a/crates/pa-ai/src/providers/openai_codex_responses/session.rs +++ b/crates/pa-ai/src/providers/openai_codex_responses/session.rs @@ -1,6 +1,5 @@ -//! Codex WebSocket session state: connection cache, SSE-fallback pinning, -//! debug stats, continuation bookkeeping, and idle expiry. Section of the -//! port of `packages/ai/src/providers/openai-codex-responses.ts`. +//! Codex WebSocket session state: connection cache, SSE-fallback pinning, debug stats, continuation +//! bookkeeping, and idle expiry. use std::collections::{HashMap, HashSet}; use std::sync::{Mutex, OnceLock}; @@ -40,7 +39,6 @@ pub fn session_state() -> &'static Mutex { STATE.get_or_init(|| Mutex::new(SessionState::default())) } -/// Port of `isWebSocketSseFallbackActive`. pub fn is_websocket_sse_fallback_active(session_id: Option<&str>) -> bool { match session_id { Some(session_id) => session_state() @@ -50,7 +48,6 @@ pub fn is_websocket_sse_fallback_active(session_id: Option<&str>) -> bool { } } -/// Port of `recordWebSocketSseFallback`. pub fn record_websocket_sse_fallback(session_id: Option<&str>) { let Some(session_id) = session_id else { return; @@ -64,10 +61,7 @@ pub fn record_websocket_sse_fallback(session_id: Option<&str>) { session_stats.websocket_fallback_active = Some(active); } -/// Port of `recordWebSocketFailure`: pins the session to SSE fallback and -/// records the failure in the debug stats. -/// Port of `recordWebSocketFailure`: pins the session to SSE fallback and -/// records the failure in the debug stats. +/// Pins the session to SSE fallback and records the failure in the debug stats. pub fn record_websocket_failure(session_id: Option<&str>, error: &CodexStreamError) { let Some(session_id) = session_id else { return; @@ -82,13 +76,11 @@ pub fn record_websocket_failure(session_id: Option<&str>, error: &CodexStreamErr session_stats.websocket_fallback_active = Some(true); } -/// Port of `getOpenAICodexWebSocketDebugStats`. #[must_use] pub fn get_debug_stats(session_id: &str) -> Option { session_state().lock().ok()?.stats.get(session_id).cloned() } -/// Port of `resetOpenAICodexWebSocketDebugStats`. pub fn reset_debug_stats(session_id: Option<&str>) { let Ok(mut state) = session_state().lock() else { return; @@ -102,12 +94,8 @@ pub fn reset_debug_stats(session_id: Option<&str>) { } } -/// Port of `closeOpenAICodexWebSocketSessions`: close the cached connection -/// for one session or all of them. The TS registers this as a session -/// resource cleanup; in Rust the agent layer calls it when a session ends. -/// Port of `closeOpenAICodexWebSocketSessions`: close the cached connection -/// for one session or all of them. The TS registers this as a session -/// resource cleanup; in Rust the agent layer calls it when a session ends. +/// Close the cached connection for one session or all of them; the agent layer calls it when a +/// session ends (the TS registers a session resource cleanup). pub fn close_websocket_sessions(session_id: Option<&str>) { let Ok(mut state) = session_state().lock() else { return; @@ -129,10 +117,7 @@ pub fn close_websocket_sessions(session_id: Option<&str>) { } } -/// Record debug stats for a request (mirrors the stats block in -/// `processWebSocketStream`). -/// Record debug stats for a request (mirrors the stats block in -/// `processWebSocketStream`). +/// Record debug stats for a request (mirrors the stats block in `processWebSocketStream`). pub fn record_request_stats( session_id: &str, reused: bool, @@ -174,10 +159,7 @@ pub fn record_request_stats( } } -/// Port of `acquireWebSocket`: reuse the session's idle connection when -/// possible, otherwise open a fresh connection (cached per session). -/// Port of `scheduleSessionWebSocketExpiry`: close the cached connection -/// after the TTL if it stayed idle. +/// Close the cached connection after the TTL if it stayed idle. pub fn schedule_session_websocket_expiry(session_id: &str) { let Ok(mut state) = session_state().lock() else { return; @@ -207,10 +189,8 @@ pub fn schedule_session_websocket_expiry(session_id: &str) { }); } -/// Take the continuation for `connection_id`, if one is anchored to it -/// (part of `buildCachedWebSocketRequestBody` in the TS). -/// Take the continuation for `connection_id`, if one is anchored to it -/// (part of `buildCachedWebSocketRequestBody` in the TS). +/// Take the continuation for `connection_id`, if one is anchored to it (part of +/// `buildCachedWebSocketRequestBody` in the TS). pub fn take_continuation_for(session_id: &str, connection_id: u64) -> Option { session_state() .lock() @@ -243,8 +223,8 @@ mod tests { let session = format!("test-session-{}", std::process::id()); reset_debug_stats(Some(&session)); assert!(!is_websocket_sse_fallback_active(Some(&session))); - // Recording a fallback bump does not pin the session (only a - // transport failure does, matching the TS semantics). + // Recording a fallback bump does not pin the session (only a transport failure does, + // matching the TS semantics). record_websocket_sse_fallback(Some(&session)); assert!(!is_websocket_sse_fallback_active(Some(&session))); let stats = get_debug_stats(&session).expect("stats recorded"); diff --git a/crates/pa-ai/src/providers/openai_codex_responses/websocket.rs b/crates/pa-ai/src/providers/openai_codex_responses/websocket.rs index da3ca6b9686..238ae76b2da 100644 --- a/crates/pa-ai/src/providers/openai_codex_responses/websocket.rs +++ b/crates/pa-ai/src/providers/openai_codex_responses/websocket.rs @@ -1,13 +1,7 @@ //! Codex WebSocket transport: connections and the per-request event loop. -//! Section of the port of -//! `packages/ai/src/providers/openai-codex-responses.ts`. //! -//! Each connection owns a worker task that holds the socket; requests talk to -//! it over a command channel and receive events over a fresh channel per -//! request. The handshake sends the same beta header the codex-rs client -//! sends (`OpenAI-Beta: responses_websockets=2026-02-06`) plus custom -//! headers via an explicit `http::Request` (plain `connect_async` accepts -//! `http::Request`, which carries headers). +//! Each connection owns a worker task that holds the socket; requests talk to it over a command +//! channel and receive events over a fresh channel per request. use std::sync::atomic::{AtomicU64, Ordering}; @@ -55,24 +49,20 @@ pub(crate) enum WorkerCommand { /// Events a worker forwards to the active request. pub enum WorkerEvent { - /// A parsed stream event. Event(Value), /// Terminal marker after the completion event (Ok) or an error (Err). Terminal(Result<(), CodexStreamError>), } -/// Connection-scoped continuation state -/// (`CachedWebSocketContinuationState` in the TS). pub struct ContinuationState { pub last_request_body: Value, pub last_response_id: String, pub last_response_items: Vec, - /// Id of the connection whose server-side response state this chain is - /// anchored to. + /// Id of the connection whose server-side response state this chain is anchored to. pub connection_id: u64, } -/// Debug counters (`OpenAICodexWebSocketDebugStats` in the TS). +/// Debug counters. #[derive(Debug, Clone, Default)] pub struct WebSocketDebugStats { pub requests: u64, @@ -96,20 +86,15 @@ fn next_connection_id() -> u64 { NEXT.fetch_add(1, Ordering::SeqCst) } -/// Port of the TS runtime's (bun) WebSocket connect-failure surface, -/// probe-verified against the TS binary: every connect-phase failure is a -/// plain `Error` whose message is `WebSocket connection to '' failed: -/// ` with the runtime's own cause texts — `Failed to connect` for -/// socket-level failures, `Expected 101 status code` for a non-101 answer, -/// `Mismatch websocket accept header` for a bad accept key, and -/// `TLS handshake failed` for TLS failures. +/// Port of the TS runtime's (bun) WebSocket connect-failure surface, probe-verified against the TS +/// binary: every connect-phase failure is a plain `Error` whose message is `WebSocket connection to +/// '' failed: ` with the runtime's own cause texts. fn bun_connect_failure(url: &str, error: &WsError) -> WebSocketTransportError { let cause = match error { WsError::Io(io) => { - // tokio-tungstenite surfaces the rustls handshake failure as a - // plain io error, so on wss URLs any socket failure after the - // refused connect maps to the runtime's TLS-handshake text - // (probe-verified against a plain-speaking wss peer). + // tokio-tungstenite surfaces the rustls handshake failure as a plain io error, so on + // wss URLs any socket failure after the refused connect maps to the runtime's + // TLS-handshake text. if url.starts_with("wss://") && !matches!( io.kind(), @@ -123,9 +108,8 @@ fn bun_connect_failure(url: &str, error: &WsError) -> WebSocketTransportError { } WsError::Tls(_) => "TLS handshake failed".to_string(), WsError::Http(_) => "Expected 101 status code".to_string(), - // The runtime checks the status code before the HTTP shape, so a - // response the transport rejects for its version or method carries - // the same non-101 text. + // The runtime checks the status code before the HTTP shape, so a response the transport + // rejects for its version or method carries the same non-101 text. WsError::Protocol(ProtocolError::WrongHttpVersion | ProtocolError::WrongHttpMethod) => { "Expected 101 status code".to_string() } @@ -137,18 +121,14 @@ fn bun_connect_failure(url: &str, error: &WsError) -> WebSocketTransportError { WebSocketTransportError::runtime(format!("WebSocket connection to '{url}' failed: {cause}")) } -/// Port of the TS runtime's (bun) WebSocket read-failure surface, -/// probe-verified against the TS binary: every socket or frame failure -/// surfaces as a close event composing `WebSocket closed {code} {reason}` — -/// code 1006 (`Connection ended`) for socket death, per-case codes for frame -/// violations (1002 `Protocol error - unsupported control frame` for -/// reserved opcodes, 1011 `Compression not implemented yet` for reserved -/// bits). Unprobed violations compose the runtime's protocol-error envelope -/// with the transport's own detail text. +/// Port of the TS runtime's (bun) WebSocket read-failure surface, probe-verified against the TS +/// binary: every socket or frame failure surfaces as a close event composing `WebSocket closed +/// {code} {reason}`. Unprobed violations compose the runtime's protocol-error envelope with the +/// transport's own detail text. fn bun_read_failure(error: &WsError) -> WebSocketTransportError { match error { - // The transport's EOF-without-close-frame error is the same socket - // death the runtime reports as the 1006 close event. + // The transport's EOF-without-close-frame error is the same socket death the runtime + // reports as the 1006 close event. WsError::Protocol(ProtocolError::ResetWithoutClosingHandshake) => { WebSocketTransportError::close( WEBSOCKET_CLOSE_CODE_ABNORMAL, @@ -188,10 +168,6 @@ fn bun_read_failure(error: &WsError) -> WebSocketTransportError { } } -/// Port of `connectWebSocket` + worker spawn: handshake with custom headers, -/// then run the reader loop until the channel closes. -/// Port of `connectWebSocket` + worker spawn: handshake with custom headers, -/// then run the reader loop until the channel closes. async fn spawn_connection_worker( url: &str, headers: &[(String, String)], @@ -241,12 +217,7 @@ async fn spawn_connection_worker( Ok((command_tx, connection_id)) } -/// Port of `parseWebSocket`: per-request event forwarding with completion -/// tracking, error extraction, and close-code reporting. The worker parks -/// between requests so a session can reuse one connection. -/// Port of `parseWebSocket`: per-request event forwarding with completion -/// tracking, error extraction, and close-code reporting. The worker parks -/// between requests so a session can reuse one connection. +/// The worker parks between requests so a session can reuse one connection. async fn connection_worker( stream: WsStream, mut commands: mpsc::Receiver, @@ -264,9 +235,8 @@ async fn connection_worker( } WorkerCommand::Send { body, events } => { if sink.send(Message::Text(body.into())).await.is_err() { - // A dead socket surfaces through its close event (the TS - // runtime's send on a closed socket is a silent no-op; the - // close event carries the failure). + // A dead socket surfaces through its close event (the TS runtime's send on a + // closed socket is a silent no-op; the close event carries the failure). let _ = events .send(WorkerEvent::Terminal(Err(CodexStreamError::Transport( WebSocketTransportError::close( @@ -312,8 +282,8 @@ async fn read_request_events( None => next.await, }; match message { - // Peer EOF without a close frame: the runtime fires a close event - // with code 1006 ("Connection ended" in the TS runtime). + // Peer EOF without a close frame: the runtime fires a close event with code 1006 + // ("Connection ended" in the TS runtime). None => { return Err(CodexStreamError::Transport(WebSocketTransportError::close( WEBSOCKET_CLOSE_CODE_ABNORMAL, @@ -332,8 +302,8 @@ async fn read_request_events( saw_completion = true; } if events.send(WorkerEvent::Event(event)).await.is_err() { - // The request consumer is gone (its receiver was - // dropped); nobody observes this text. + // The request consumer is gone (its receiver was dropped); nobody + // observes this text. return Err(CodexStreamError::Transport( WebSocketTransportError::runtime("WebSocket request cancelled"), )); @@ -342,8 +312,8 @@ async fn read_request_events( return Ok(()); } } - // Port of `parseWebSocket`'s JSON failure: a non-transport - // protocol error, thrown without SSE fallback. + // Port of `parseWebSocket`'s JSON failure: a non-transport protocol error, + // thrown without SSE fallback. Err(error) => { return Err(CodexStreamError::Protocol(CodexProtocolError { message: format!("Invalid Codex WebSocket JSON: {error}"), @@ -375,8 +345,8 @@ async fn read_request_events( if saw_completion { return Ok(()); } - // A close frame without a status code surfaces as the - // runtime's 1005 close event (probe-verified). + // A close frame without a status code surfaces as the runtime's 1005 close event + // (probe-verified). let error = match close { Some(frame) => { WebSocketTransportError::close(u16::from(frame.code), frame.reason.as_str()) @@ -393,7 +363,7 @@ async fn read_request_events( } } -/// A session-acquired connection handle (`{ socket, entry, reused, release }`). +/// A session-acquired connection handle. pub struct AcquiredConnection { worker: mpsc::Sender, pub session_id: Option, @@ -426,8 +396,8 @@ impl AcquiredConnection { }) .await .map_err(|_| { - // The worker (socket) is gone; in the TS the socket's close - // event would surface with the 1006 close text. + // The worker (socket) is gone; in the TS the socket's close event would surface + // with the 1006 close text. CodexStreamError::Transport(WebSocketTransportError::close( WEBSOCKET_CLOSE_CODE_ABNORMAL, WEBSOCKET_CONNECTION_ENDED_REASON, @@ -436,15 +406,14 @@ impl AcquiredConnection { Ok(event_rx) } - /// Port of `closeWebSocketSilently`: ask the worker to close the socket. + /// Ask the worker to close the socket. pub async fn close(&self) { let _ = self.worker.send(WorkerCommand::Close).await; } } -/// Port of `isWebSocketSseFallbackActive`. -/// Port of `acquireWebSocket`: reuse the session's idle connection when -/// possible, otherwise open a fresh connection (cached per session). +/// Reuse the session's idle connection when possible, otherwise open a fresh connection (cached per +/// session). pub async fn acquire_websocket( url: &str, headers: &[(String, String)], @@ -463,7 +432,6 @@ pub async fn acquire_websocket( }); }; - // Reuse the session's idle connection. let cached_worker = { let mut state = session_state().lock().ok(); match state @@ -531,10 +499,6 @@ pub async fn acquire_websocket( }) } -/// Port of `release`: return the connection to the cache with its new -/// continuation state, or close it. `keep` mirrors the TS `{ keep }` option. -/// Port of `release`: return the connection to the cache with its new -/// continuation state, or close it. `keep` mirrors the TS `{ keep }` option. pub async fn release_connection( connection: AcquiredConnection, keep: bool, @@ -568,11 +532,8 @@ pub async fn release_connection( } } -/// Port of `scheduleSessionWebSocketExpiry`: close the cached connection -/// after the TTL if it stayed idle. -/// Port of `requestBodiesMatchExceptInput` + `getCachedWebSocketInputDelta`: -/// compute the continuation delta (input items beyond the cached baseline) -/// for an otherwise-identical request body. +/// Compute the continuation delta (input items beyond the cached baseline) for an +/// otherwise-identical request body. pub fn get_cached_websocket_input_delta( body: &Value, continuation: &ContinuationState, @@ -607,7 +568,6 @@ pub fn get_cached_websocket_input_delta( Some(current_input[baseline.len()..].to_vec()) } -/// Port of `buildCachedWebSocketRequestBody`. pub fn build_cached_websocket_request_body( continuation: Option<&ContinuationState>, body: &Value, @@ -616,8 +576,8 @@ pub fn build_cached_websocket_request_body( let Some(continuation) = continuation else { return body.clone(); }; - // Continuations are anchored to the connection that produced the - // response; a different socket cannot resolve their previous_response_id. + // Continuations are anchored to the connection that produced the response; a different socket + // cannot resolve their previous_response_id. if continuation.connection_id != connection_id { return body.clone(); } @@ -689,10 +649,8 @@ mod tests { } } -/// Raw-socket WebSocket mocks for the transport tests: one connection, one -/// scripted wire sequence per scenario (the `provider_error` probe drives the -/// TS binary through the same sequences; these pin the texts and the -/// diagnostic error surface in-crate). +/// Raw-socket WebSocket mocks for the transport tests: one connection, one scripted wire sequence +/// per scenario, pinning the TS-binary-verified texts and the diagnostic error surface in-crate. #[cfg(test)] mod ws_wire_tests { use super::*; @@ -709,8 +667,7 @@ mod ws_wire_tests { const OP_TEXT: u8 = 0x1; const OP_CLOSE: u8 = 0x8; - /// The scripted wire sequence the mock serves after the handshake - /// request is read. + /// The scripted wire sequence the mock serves after the handshake request is read. enum MockAction { /// Answer the upgrade request with a plain HTTP error. RejectHttp(u16), @@ -847,8 +804,8 @@ mod ws_wire_tests { format!("ws://127.0.0.1:{port}/codex/responses") } - /// Drive one acquire+send+read cycle and return the terminal transport - /// error (the read loop surfaces it after the scripted wire sequence). + /// Drive one acquire+send+read cycle and return the terminal transport error (the read loop + /// surfaces it after the scripted wire sequence). async fn request_terminal_error(action: MockAction) -> CodexStreamError { let url = spawn_ws_mock(action).await; let connection = acquire_websocket(&url, &[], None, None) @@ -866,8 +823,8 @@ mod ws_wire_tests { } } - /// Drive one acquire against a mock that fails before the handshake - /// completes and return the connect-phase error. + /// Drive one acquire against a mock that fails before the handshake completes and return the + /// connect-phase error. async fn acquire_connect_error(action: MockAction) -> WebSocketTransportError { let url = spawn_ws_mock(action).await; match acquire_websocket(&url, &[], None, None).await { @@ -877,9 +834,6 @@ mod ws_wire_tests { } } - /// A refused connect (the probe's dead port): the runtime's own - /// connect-failure envelope with the "Failed to connect" cause and a - /// plain `Error` name (TS-binary verified). #[tokio::test] async fn refused_connect_text() { let url = "ws://127.0.0.1:1/codex/responses".to_string(); @@ -896,8 +850,7 @@ mod ws_wire_tests { assert_eq!(error.close_code(), None); } - /// A non-101 upgrade answer: the "Expected 101 status code" cause - /// (TS-binary verified for 401 and 500). + /// A non-101 upgrade answer: the "Expected 101 status code" cause (probed for 401 and 500). #[tokio::test] async fn handshake_rejection_text() { for status in [401u16, 500u16] { @@ -918,8 +871,6 @@ mod ws_wire_tests { } } - /// A wrong Sec-WebSocket-Accept: the "Mismatch websocket accept header" - /// cause (TS-binary verified). #[tokio::test] async fn bad_accept_key_text() { let error = acquire_connect_error(MockAction::BadAcceptKey).await; @@ -929,9 +880,6 @@ mod ws_wire_tests { assert_eq!(error.error_name(), "Error"); } - /// A close frame with code + reason: `WebSocket closed {code} {reason}` - /// with the `WebSocketCloseError` name and the numeric code the - /// diagnostic records (TS-binary verified). #[tokio::test] async fn close_frame_with_reason_text() { let error = request_terminal_error(MockAction::CloseCode { @@ -950,8 +898,7 @@ mod ws_wire_tests { assert_eq!(transport.close_code(), Some(1011)); } - /// The 1009 no-reason special case composes "message too big" - /// (TS-binary verified). + /// The 1009 no-reason special case composes "message too big". #[tokio::test] async fn close_1009_no_reason_text() { let error = request_terminal_error(MockAction::CloseCode { @@ -969,8 +916,6 @@ mod ws_wire_tests { assert_eq!(transport.close_code(), Some(1009)); } - /// A close frame without a status code surfaces as the runtime's 1005 - /// close event (TS-binary verified). #[tokio::test] async fn close_no_code_text() { let error = request_terminal_error(MockAction::CloseNoCode).await; @@ -981,8 +926,6 @@ mod ws_wire_tests { assert_eq!(transport.close_code(), Some(1005)); } - /// A TCP close without a close frame: code 1006 "Connection ended" - /// (TS-binary verified for both FIN and RST). #[tokio::test] async fn fin_without_close_frame_text() { let error = request_terminal_error(MockAction::Fin).await; @@ -997,8 +940,6 @@ mod ws_wire_tests { assert_eq!(transport.close_code(), Some(WEBSOCKET_CLOSE_CODE_ABNORMAL)); } - /// Reserved opcodes (data or control): code 1002 with the runtime's - /// protocol-error reason (TS-binary verified). #[tokio::test] async fn reserved_opcode_text() { for action in [ @@ -1017,8 +958,6 @@ mod ws_wire_tests { } } - /// Reserved bits on a frame: the runtime's 1011 "Compression not - /// implemented yet" close (TS-binary verified). #[tokio::test] async fn rsv_bits_text() { let error = request_terminal_error(MockAction::RsvBits).await; @@ -1032,16 +971,14 @@ mod ws_wire_tests { assert_eq!(transport.close_code(), Some(1011)); } - /// A wss peer that speaks no TLS: the runtime's "TLS handshake failed" - /// cause (TS-binary verified). #[tokio::test] async fn wss_to_plain_tls_text() { let listener = TcpListener::bind("127.0.0.1:0").await.expect("mock bind"); let port = listener.local_addr().unwrap().port(); tokio::spawn(async move { let (mut socket, _) = listener.accept().await.expect("mock accept"); - // Read the TLS ClientHello then answer plain HTTP: the handshake - // fails against a non-TLS peer. + // Read the TLS ClientHello then answer plain HTTP: the handshake fails against a + // non-TLS peer. let mut buf = [0u8; 512]; let _ = socket.read(&mut buf).await; socket @@ -1062,9 +999,7 @@ mod ws_wire_tests { assert_eq!(error.error_name(), "Error"); } - /// An invalid JSON frame is a non-transport protocol error (`isCodexNonTransportError` - /// in the TS): it throws without the SSE fallback, surfacing the - /// `CodexProtocolError` name in the `provider_stream_failure` diagnostic. + /// An invalid JSON frame is a non-transport protocol error: thrown without the SSE fallback. #[tokio::test] async fn invalid_json_is_non_transport_error() { let error = request_terminal_error(MockAction::InvalidJson).await; diff --git a/crates/pa-ai/src/providers/openai_completions/convert.rs b/crates/pa-ai/src/providers/openai_completions/convert.rs index 22bd60a3758..bb757754033 100644 --- a/crates/pa-ai/src/providers/openai_completions/convert.rs +++ b/crates/pa-ai/src/providers/openai_completions/convert.rs @@ -1,5 +1,4 @@ //! `OpenAI` Completions conversion: reasoning-details signatures, messages, and tools. -//! Section of the port of `packages/ai/src/providers/openai-completions.ts`. use serde_json::{json, Map, Value}; @@ -12,9 +11,9 @@ use crate::types::{ }; use crate::utils_inner::sanitize_unicode::sanitize_surrogates; -/// Convert a conversation into Chat Completions `messages` params. -/// Port of `convertMessages` including tool-result bridging and image replay. -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +/// Convert a conversation into Chat Completions `messages` params, including tool-result bridging +/// and image replay. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] pub fn convert_messages(model: &Model, context: &Context, compat: &ResolvedCompat) -> Vec { use crate::types::Message; @@ -423,9 +422,8 @@ pub(crate) fn parse_chunk_usage( // Normalize to the provider-layer usage accounting semantics: // - cacheRead: hits from cache created by previous requests only // - cacheWrite: tokens written to cache in this request - // Some OpenAI-compatible providers (observed on OpenRouter) report - // cached_tokens as (previous hits + current writes). Remove cacheWrite from - // cacheRead in that case. + // Some OpenAI-compatible providers (observed on OpenRouter) report cached_tokens as (previous + // hits + current writes). Remove cacheWrite from cacheRead in that case. let cache_read_tokens = if cache_write_tokens > 0 { reported_cached_tokens.saturating_sub(cache_write_tokens) } else { @@ -454,10 +452,9 @@ pub(crate) fn parse_chunk_usage( }) .as_ref(), ); - // OpenRouter reports billing truth in usage, already priced by the endpoint - // and service tier that served the request - // (https://openrouter.ai/docs/api-reference/overview). Trust it over the - // catalog-rate estimate, scaling the component breakdown to match. + // OpenRouter reports billing truth in usage, already priced by the endpoint and service tier + // that served the request (https://openrouter.ai/docs/api-reference/overview). Trust it over + // the catalog-rate estimate, scaling the component breakdown to match. let reported_cost = if model.provider == "openrouter" { openrouter_reported_cost(raw_usage) } else { @@ -486,12 +483,11 @@ pub(crate) fn parse_chunk_usage( usage } -/// The user's real spend for an `OpenRouter` request, or `None` to keep the -/// catalog estimate. `usage.cost` only carries what `OpenRouter` charged the -/// account's credits: for BYOK requests that is just `OpenRouter`'s fee, so -/// real spend is the upstream provider's bill plus that fee. A cost of 0 can -/// mean not-billed-via-credits (e.g. `:free` endpoints) rather than free, so -/// it keeps the catalog estimate. +/// The user's real spend for an `OpenRouter` request, or `None` to keep the catalog estimate. +/// `usage.cost` only carries what `OpenRouter` charged the account's credits: for BYOK requests +/// that is just `OpenRouter`'s fee, so real spend is the upstream provider's bill plus that fee. A +/// cost of 0 can mean not-billed-via-credits (e.g. `:free` endpoints) rather than free, so it keeps +/// the catalog estimate. fn openrouter_reported_cost(raw_usage: &Value) -> Option { let credits = raw_usage .get("cost") @@ -589,8 +585,8 @@ mod tests { #[test] fn openrouter_zero_reported_cost_keeps_catalog_estimate() { let model = model("openrouter", 0.5, 0.5); - // A cost of 0 can mean not-billed-via-credits (:free endpoints) - // rather than free, so the catalog estimate stays. + // A cost of 0 can mean not-billed-via-credits (:free endpoints) rather than free, so the + // catalog estimate stays. let usage = parse_chunk_usage(&raw_usage(0.0, ByokBilling::NotByok), &model, None); assert!((usage.cost.total.as_f64() - 0.05).abs() < 1e-9); } @@ -598,8 +594,8 @@ mod tests { #[test] fn openrouter_byok_without_upstream_keeps_catalog_estimate() { let model = model("openrouter", 0.5, 0.5); - // BYOK credits are only OpenRouter's fee; without the upstream bill - // the real spend is unknown, so the catalog estimate stays. + // BYOK credits are only OpenRouter's fee; without the upstream bill the real spend is + // unknown, so the catalog estimate stays. let usage = parse_chunk_usage(&raw_usage(0.003, ByokBilling::FeeOnly), &model, None); assert!((usage.cost.total.as_f64() - 0.05).abs() < 1e-9); } diff --git a/crates/pa-ai/src/providers/openai_completions/errors.rs b/crates/pa-ai/src/providers/openai_completions/errors.rs index 8241d02a360..0b1b27ac487 100644 --- a/crates/pa-ai/src/providers/openai_completions/errors.rs +++ b/crates/pa-ai/src/providers/openai_completions/errors.rs @@ -1,37 +1,32 @@ -//! `OpenAI` Completions error surface. -//! Section of the port of `packages/ai/src/providers/openai-completions.ts`: -//! the user-facing error message for a failed request, composed exactly like -//! the `openai` npm SDK (`APIError.makeMessage`, openai 6.47.0) whose message -//! the TS provider surfaces verbatim — unlike the anthropic/responses -//! providers, which classify through `formatStreamFailureMessage`. +//! `OpenAI` Completions error surface: the user-facing error message for a failed request, composed +//! exactly like the `openai` npm SDK (`APIError.makeMessage`, openai 6.47.0), which the TS provider +//! surfaces verbatim. use serde_json::Value; use crate::utils_inner::stream_failure::{ProviderError, ProviderHttpError}; -/// Build the user-facing message for a non-OK provider response, mirroring the -/// `openai` SDK's `APIError` text (which `streamOpenAICompletions` copies into -/// the assistant message's error message as-is): +/// Build the user-facing message for a non-OK provider response, mirroring the `openai` SDK's +/// `APIError` text (which `streamOpenAICompletions` copies into the assistant message's error +/// message as-is): /// /// - JSON body whose `error.message` is a non-empty string: `"{status} {message}"`. -/// - JSON body whose `error` is present without a usable message: -/// `"{status} {error}"` (stringified). +/// - JSON body whose `error` is present without a usable message: `"{status} {error}"` +/// (stringified). /// - JSON body without a usable `error` field: `"{status} status code (no body)"`. -/// - Non-JSON body: `"{status} {raw body}"`; empty body: `"{status} status code -/// (no body)"`. +/// - Non-JSON body: `"{status} {raw body}"`; empty body: `"{status} status code (no body)"`. /// -/// JS truthiness decides "usable" (`null`/`false`/`0`/`""` are falsy). Two -/// stringification divergences are accepted for non-string payloads and -/// key-less-order objects (real provider error bodies carry a string -/// `error.message`): serde renders `1.0` as `1.0` where `JSON.stringify` -/// renders `1`, and object keys sort alphabetically where JS keeps body order. +/// JS truthiness decides "usable" (`null`/`false`/`0`/`""` are falsy). Two accepted stringification +/// divergences (real provider error bodies carry a string `error.message`): serde renders `1.0` as +/// `1.0` where `JSON.stringify` renders `1`, and object keys sort alphabetically where JS keeps +/// body order. pub fn openai_sdk_error_message(status: u16, body: &str) -> String { let parsed = match serde_json::from_str::(body) { Ok(value) if js_truthy(&value) => Some(value), _ => None, }; - // The SDK's message argument only carries the raw text when the body did - // not parse as (truthy) JSON. + // The SDK's message argument only carries the raw text when the body did not parse as (truthy) + // JSON. let err_message = parsed.is_none().then_some(body); let error = parsed .as_ref() @@ -51,9 +46,9 @@ pub fn openai_sdk_error_message(status: u16, body: &str) -> String { } } -/// Build the error for a non-OK provider response: the SDK-style message plus -/// the structured pieces (`status`, body, headers) the stream-failure -/// classification reads for diagnostics and retry decisions. +/// Build the error for a non-OK provider response: the SDK-style message plus the structured pieces +/// (`status`, body, headers) the stream-failure classification reads for diagnostics and retry +/// decisions. pub fn openai_http_error( status: u16, body: &str, @@ -65,17 +60,17 @@ pub fn openai_http_error( body: Some(body.to_string()), headers, request_id: None, - // The openai SDK errors do not set `error.name`: the TS diagnostic - // records the inherited plain JS "Error". + // The openai SDK errors do not set `error.name`: the TS diagnostic records the inherited + // plain JS "Error". sdk_name: None, retry_after_ms: None, provider_error_type: None, }) } -/// The `OpenRouter` extra-information field the TS provider appends to the -/// error message: `error.metadata.raw` on the SDK error (the response body's -/// `error` object). `None` unless truthy per JS rules. +/// The `OpenRouter` extra-information field the TS provider appends to the error message: +/// `error.metadata.raw` on the SDK error (the response body's `error` object). `None` unless truthy +/// per JS rules. pub fn openrouter_raw_metadata(error: &ProviderError) -> Option { let body = match error { ProviderError::Http(http) => http.body.as_deref()?, @@ -98,9 +93,9 @@ fn js_truthy(value: &Value) -> bool { } } -/// JS `String(value)` coercion for the template-literal append in the TS -/// provider. Objects stringify as `"[object Object]"`, arrays join their -/// elements with `,` (recursively, `null`/`undefined` as empty). +/// JS `String(value)` coercion for the template-literal append in the TS provider. Objects +/// stringify as `"[object Object]"`, arrays join their elements with `,` (recursively, +/// `null`/`undefined` as empty). fn js_to_string(value: &Value) -> String { match value { Value::String(text) => text.clone(), @@ -124,9 +119,9 @@ mod tests { use super::*; use std::collections::HashMap; - /// The exact composition the TS `openai` SDK produces for an `OpenAI` error - /// body and the TS provider surfaces verbatim (the parity harness's - /// scripted overflow probe: `{"error": {"message": ...}}` with status 400). + /// The exact composition the TS `openai` SDK produces for an `OpenAI` error body and the TS + /// provider surfaces verbatim (the parity harness's scripted overflow probe: `{"error": + /// {"message": ...}}` with status 400). #[test] fn sdk_message_from_error_body_message() { let body = @@ -177,8 +172,8 @@ mod tests { openai_sdk_error_message(400, r#"{"error": {"message": 42}}"#), "400 42" ); - // Falsy `error` (JSON null) leaves the message argument, which a JSON - // body leaves undefined. + // Falsy `error` (JSON null) leaves the message argument, which a JSON body leaves + // undefined. assert_eq!( openai_sdk_error_message(400, r#"{"error": null}"#), "400 status code (no body)" diff --git a/crates/pa-ai/src/providers/openai_completions/mod.rs b/crates/pa-ai/src/providers/openai_completions/mod.rs index c9d12bb1917..2acbffe935e 100644 --- a/crates/pa-ai/src/providers/openai_completions/mod.rs +++ b/crates/pa-ai/src/providers/openai_completions/mod.rs @@ -1,12 +1,6 @@ -//! `OpenAI` Chat Completions streaming provider. -//! -//! Full port of `packages/ai/src/providers/openai-completions.ts`, split -//! across submodules: compat detection and options here, message/tool/usage -//! conversion in [`convert`], params and header assembly in [`params`], the -//! SDK-shaped user-facing error surface in [`errors`], and the chunk-driven -//! streaming core in [`stream`]. Compat detection -//! (provider/baseUrl heuristics plus explicit `model.compat`) and reasoning -//! effort mapping live here. +//! `OpenAI` Chat Completions streaming provider: compat detection and options here, +//! message/tool/usage conversion in [`convert`], params and header assembly in [`params`], the +//! SDK-shaped error surface in [`errors`], and the chunk-driven streaming core in [`stream`]. use serde_json::{json, Map, Value}; @@ -58,7 +52,7 @@ impl ToolChoice { } } -/// Provider-native options (`OpenAICompletionsOptions` in the TS reference). +/// Provider-native options. #[derive(Clone, Default)] pub struct OpenAICompletionsOptions { pub base: StreamOptions, @@ -199,8 +193,7 @@ pub fn detect_compat(model: &Model) -> ResolvedCompat { } } -/// Resolve compat for a model: explicit `model.compat` fields override the -/// detected defaults. +/// Resolve compat for a model: explicit `model.compat` fields override the detected defaults. pub fn get_compat(model: &Model) -> ResolvedCompat { let detected = detect_compat(model); let Some(compat) = model.compat_kind() else { @@ -305,10 +298,6 @@ pub(crate) fn has_tool_history(messages: &[crate::types::Message]) -> bool { false } -// --------------------------------------------------------------------------- -// Reasoning details signatures -// --------------------------------------------------------------------------- - pub(crate) fn encode_reasoning_details(details: &[Value]) -> String { json!({ "type": REASONING_DETAILS_SIGNATURE_TYPE, @@ -335,7 +324,6 @@ pub(crate) fn decode_reasoning_details(signature: Option<&str>) -> Option { - // OpenRouter distinguishes an omitted reasoning preference (use - // the model default), an explicit toggle, and an explicit - // effort selection. + // OpenRouter distinguishes an omitted reasoning preference (use the model default), + // an explicit toggle, and an explicit effort selection. let declared_effort = options .reasoning_effort .filter(|_| compat.supports_reasoning_effort); @@ -145,9 +143,8 @@ pub(crate) fn build_params( .thinking_level_map .as_ref() .and_then(|map| map.get(&ModelThinkingLevel::Off)); - // TS `thinkingLevelMap?.off !== null`: only an explicit - // null suppresses the disable; a missing key or map still - // disables reasoning. + // TS `thinkingLevelMap?.off !== null`: only an explicit null suppresses the + // disable; a missing key or map still disables reasoning. if !off.is_some_and(std::option::Option::is_none) { if compat.supports_reasoning_effort { let off_value = off @@ -178,9 +175,8 @@ pub(crate) fn build_params( .thinking_level_map .as_ref() .and_then(|map| map.get(&ModelThinkingLevel::Off)); - // TS `thinkingLevelMap?.off !== null`: only an explicit - // null suppresses the disable; a missing key or map still - // sends the off value. + // TS `thinkingLevelMap?.off !== null`: only an explicit null suppresses the + // disable; a missing key or map still sends the off value. if !off.is_some_and(std::option::Option::is_none) { let off_value = off .and_then(|value| value.as_deref()) @@ -193,12 +189,10 @@ pub(crate) fn build_params( } } - // OpenAI and OpenRouter accept a top-level service_tier (OpenRouter: - // flex and priority for every model, - // https://openrouter.ai/docs/guides/features/service-tiers). Prime - // Inference tolerates but ignores the field (probed 2026-09-01), so it - // is not forwarded; other OpenAI-compatible gateways may reject - // unknown fields (TS #2144). + // OpenAI and OpenRouter accept a top-level service_tier + // (https://openrouter.ai/docs/guides/features/service-tiers). Prime Inference tolerates but + // ignores the field (probed 2026-09-01), so it is not forwarded; other OpenAI-compatible + // gateways may reject unknown fields. if let Some(service_tier) = options.base.service_tier { if model.provider == "openai" || model.provider == "openrouter" { params.insert( @@ -365,11 +359,9 @@ mod tests { use crate::models_generated; use crate::types::{Message, StreamOptions, UserMessage, UserMessageContent}; - /// Port of the TS #2497 pin: the provider layer owns no Prime - /// Inference team lookup — a prime-inference request with - /// `PRIME_TEAM_ID` set and no caller header carries no - /// `X-Prime-Team-ID` (the auth storage is the single owner of the - /// team header). + /// TS #2497 pin: the provider layer owns no Prime Inference team lookup — a prime-inference + /// request with `PRIME_TEAM_ID` set and no caller header carries no `X-Prime-Team-ID` (the auth + /// storage is the single owner of the team header). #[test] fn prime_inference_adds_no_team_header_the_caller_did_not_pass() { std::env::set_var("PRIME_TEAM_ID", "cli-profile-team"); @@ -399,11 +391,9 @@ mod tests { ); } - /// Assemble params for a compiled catalog model with a reasoning level - /// requested. Mirrors `streamSimpleOpenAICompletions`: the requested - /// level clamps through the model's thinking-level map, the effort - /// rides along as `reasoning_effort` unless clamped to off, and the - /// explicit on/off toggle rides along as `reasoning_enabled`. + /// Assemble params for a compiled catalog model with a reasoning level requested, mirroring + /// `streamSimpleOpenAICompletions`: the level clamps through the model's thinking-level map; + /// the effort and the on/off toggle ride along unless clamped to off. fn reasoning_params_for(model: &Model, level: ModelThinkingLevel) -> Map { let context = Context { system_prompt: None, @@ -435,9 +425,8 @@ mod tests { } } - /// Assemble params with a service tier requested over the base - /// stream options (the shape the daemon's provider adapter and - /// `stream_simple` both hand the completions path). + /// Assemble params with a service tier requested over the base stream options (the shape the + /// daemon's provider adapter and `stream_simple` both hand the completions path). fn tiered_params( provider: &str, model_id: &str, @@ -473,9 +462,7 @@ mod tests { } } - /// TS #2144: the completions path forwards `service_tier` for `OpenAI` - /// and `OpenRouter` only — other OpenAI-compatible gateways may reject - /// unknown fields, and Prime Inference tolerates but ignores the field. + /// TS #2144: `service_tier` forwards for `OpenAI` and `OpenRouter` only. #[test] fn forwards_service_tier_for_openai_and_openrouter_only() { use crate::types::ServiceTier; @@ -506,8 +493,8 @@ mod tests { ); } - /// A compiled fallback catalog entry, straight from `models_generated` - /// (the conservative offline floor). + /// A compiled fallback catalog entry, straight from `models_generated` (the conservative + /// offline floor). fn compiled_params( provider: &str, model_id: &str, @@ -518,19 +505,13 @@ mod tests { reasoning_params_for(model, level) } - /// Port of the TS regression (#2519, gateway-verified 2026-09-21): - /// a Prime Inference route sends only the reasoning parameters its live - /// catalog declaration selects — an effort-declared route sends - /// `reasoning_effort` values, a toggle-declared route the `reasoning` - /// object — and `enable_thinking` never reaches a Prime Inference - /// route. The live declarations rebuild each model's compat and - /// thinking levels (pa-models `build_prime_inference_models`); these - /// fixtures hold the two rebuilt shapes, so the request shaping keeps - /// its #2519 coverage independent of the compiled fallback catalog. + /// A Prime Inference route sends only the reasoning parameters its live catalog declaration + /// selects (effort-declared → `reasoning_effort`, toggle-declared → the `reasoning` object); + /// `enable_thinking` never reaches a Prime Inference route (TS regression #2519). #[test] fn sends_only_the_declared_reasoning_parameters_for_live_rebuilt_routes() { - // Effort-declared route (the glm-5.3 shape): reasoning_effort with - // the declared levels, no reasoning object, no enable_thinking. + // Effort-declared route (the glm-5.3 shape): reasoning_effort with the declared levels, no + // reasoning object, no enable_thinking. let mut effort_model = models_generated::get_model("prime-inference", "z-ai/glm-5.3") .expect("compiled template") .clone(); @@ -554,8 +535,8 @@ mod tests { assert_eq!(params.get("reasoning_effort"), Some(&json!("high"))); } - // Toggle-declared route (the glm-4.7 shape): the reasoning object - // only, with the declared on and off arms. + // Toggle-declared route (the glm-4.7 shape): the reasoning object only, with the declared + // on and off arms. let mut toggle_model = effort_model; toggle_model.compat = Some(crate::types::ModelCompat::from_kind( crate::types::CompatKind::OpenAiCompletions(Box::new( @@ -588,11 +569,9 @@ mod tests { assert_eq!(params.get("reasoning"), Some(&json!({ "enabled": false }))); } - /// The compiled fallback catalog is conservative (TS #2519: the live - /// catalog owns the reasoning declarations): offline, a Prime - /// Inference route declares neither the effort selector nor a thinking - /// format, so a reasoning request sends no reasoning parameter at all - /// — and `enable_thinking` still never reaches the route. + /// The compiled fallback catalog is conservative (TS #2519: the live catalog owns the reasoning + /// declarations): offline, a Prime Inference route declares neither the effort selector nor a + /// thinking format, so a reasoning request sends no reasoning parameter at all. #[test] fn compiled_fallback_prime_inference_routes_send_no_reasoning_parameters() { for (model_id, level) in [ @@ -616,19 +595,18 @@ mod tests { } } - /// The direct z.ai routes keep the toggle: their compat still selects the - /// zai thinking format, so reasoning requests send `enable_thinking`. + /// The direct z.ai routes keep the toggle: their compat still selects the zai thinking format, + /// so reasoning requests send `enable_thinking`. #[test] fn keeps_the_zai_thinking_toggle_on_direct_zai_routes() { let params = compiled_params("zai", "glm-4.7", ModelThinkingLevel::High); assert_eq!(params.get("enable_thinking"), Some(&json!(true))); } - /// A `reasoning: false` model whose map addresses levels (the live - /// catalog's `gpt-5.3-chat-latest` / `openai/gpt-5.2-chat` shape) is - /// thinking-capable: the requested level clamps through the map and - /// the request carries the mapped reasoning parameter. The flag alone - /// must not veto a route that declares addressable levels. + /// A `reasoning: false` model whose map addresses levels (the live catalog's + /// `gpt-5.3-chat-latest` / `openai/gpt-5.2-chat` shape) is thinking-capable: the requested + /// level clamps through the map and the request carries the mapped reasoning parameter. The + /// flag alone must not veto a route that declares addressable levels. #[test] fn a_map_addressable_model_sends_reasoning_without_the_flag() { let model = serde_json::from_value::(json!({ diff --git a/crates/pa-ai/src/providers/openai_completions/stream.rs b/crates/pa-ai/src/providers/openai_completions/stream.rs index 62134a38822..8aa3d5bb172 100644 --- a/crates/pa-ai/src/providers/openai_completions/stream.rs +++ b/crates/pa-ai/src/providers/openai_completions/stream.rs @@ -1,7 +1,5 @@ -//! `OpenAI` Completions streaming core. -//! Section of the port of `packages/ai/src/providers/openai-completions.ts`: -//! chunk-driven block state (`text/thinking/toolcalls/reasoning_details`), SSE -//! decoding, and the provider stream function. +//! `OpenAI` Completions streaming core: chunk-driven block state +//! (`text/thinking/toolcalls/reasoning_details`), SSE decoding, and the provider stream function. use std::collections::HashMap; @@ -202,7 +200,7 @@ fn finish_blocks(state: &mut StreamingState, writer: &AssistantMessageEventWrite } /// Handle one parsed SSE chunk. Returns the chunk value for testability. -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] fn handle_chunk( chunk: &Value, @@ -266,7 +264,6 @@ fn handle_chunk( return; }; - // Text content. if let Some(content) = delta.get("content").and_then(|value| value.as_str()) { if !content.is_empty() { let index = state.ensure_text_block(writer); @@ -281,9 +278,8 @@ fn handle_chunk( } } - // Some endpoints return reasoning in reasoning_content (llama.cpp), - // or reasoning (other openai compatible endpoints). Use the first - // non-empty reasoning field to avoid duplication. + // Some endpoints return reasoning in reasoning_content (llama.cpp), or reasoning (other openai + // compatible endpoints). Use the first non-empty reasoning field to avoid duplication. let mut found_reasoning_field: Option<(&str, &str)> = None; for field in REASONING_FIELDS { if let Some(value) = delta.get(field).and_then(|value| value.as_str()) { @@ -305,7 +301,6 @@ fn handle_chunk( }); } - // Tool calls. if let Some(tool_calls) = delta.get("tool_calls").and_then(|value| value.as_array()) { for tool_call in tool_calls { let stream_index = tool_call.get("index").and_then(serde_json::Value::as_u64); @@ -407,8 +402,8 @@ fn handle_chunk( } } } - // The signature is encoded once at stream end (and on the error path) - // by `encode_reasoning_details_signature`, not per delta (TS PR #2783). + // The signature is encoded once at stream end (and on the error path) by + // `encode_reasoning_details_signature`, not per delta. if !state.reasoning_details_by_index.is_empty() && state.reasoning_details_block.is_none() { state .output @@ -429,9 +424,8 @@ fn handle_chunk( } } -/// Port of the TS `encodeReasoningDetailsSignature`: encode the merged -/// reasoning-details signature once at stream end and on the error path, -/// instead of on every `reasoning_details` delta. +/// Encode the merged reasoning-details signature once at stream end and on the error path, not on +/// every `reasoning_details` delta (TS `encodeReasoningDetailsSignature`). fn encode_reasoning_details_signature(state: &mut StreamingState) { let Some(block_index) = state.reasoning_details_block else { return; @@ -447,8 +441,8 @@ fn encode_reasoning_details_signature(state: &mut StreamingState) { } } -/// Port of the TS catch settle: finalize tool-call blocks whose parsed -/// preview may lag the accumulated text under the growth throttle. +/// Port of the TS catch settle: finalize tool-call blocks whose parsed preview may lag the +/// accumulated text under the growth throttle. fn settle_partial_tool_calls(state: &mut StreamingState) { for (index, accumulator) in &mut state.tool_call_partial_args { let Some(AssistantContent::ToolCall(block)) = state.output.content.get_mut(*index) else { @@ -473,7 +467,6 @@ fn error_to_message(error: &ProviderError) -> String { message } -/// Port of `streamOpenAICompletions`. pub fn stream_openai_completions( model: &Model, context: &Context, @@ -534,7 +527,7 @@ pub fn stream_openai_completions( reader } -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] async fn run_stream( model: &Model, @@ -614,18 +607,15 @@ async fn run_stream( on_response( crate::types::ProviderResponse { status: response.status, - // Collected into the ordered map: the hook payload can - // serialize, and the HTTP header arrival order is not a - // stable serialization order. headers: response.headers.clone().into_iter().collect(), }, model, ); } - // The TS provider goes through the `openai` SDK, which throws on every - // non-OK status (2xx only) and whose `APIError` message the provider - // surfaces verbatim as the assistant message's error message. + // The TS provider goes through the `openai` SDK, which throws on every non-OK status (2xx only) + // and whose `APIError` message the provider surfaces verbatim as the assistant message's error + // message. if !(200..300).contains(&response.status) { let body = response.read_all_text().await.unwrap_or_default(); return Err(openai_http_error( @@ -646,9 +636,8 @@ async fn run_stream( Ok(Some(chunk)) => chunk, Ok(None) => break, Err(error) => { - // TS catch: encode the reasoning-details signature, then - // settle the partial tool calls before the error event - // carries the message (TS PR #2783). + // TS catch: encode the reasoning-details signature, then settle the partial tool + // calls before the error event carries the message. encode_reasoning_details_signature(&mut state); settle_partial_tool_calls(&mut state); *output = state.output; @@ -775,8 +764,6 @@ mod tests { use std::net::SocketAddr; use tokio::io::{AsyncReadExt, AsyncWriteExt}; - // The thinking-channel pins (the two provider envelopes) live in - // their own child module with this file's test harness. #[path = "stream_pins.rs"] mod stream_pins; @@ -807,8 +794,7 @@ mod tests { addr } - /// Run the provider stream against the SSE body and return the final - /// assistant message. + /// Run the provider stream against the SSE body and return the final assistant message. async fn stream_final_message(mut model: Value, body: String) -> AssistantMessage { let addr = serve_sse(body).await; model["baseUrl"] = json!(format!("http://{addr}")); @@ -851,9 +837,8 @@ mod tests { }) } - // Captured chat-completions chunk shapes: OpenAI echoes `service_tier` on - // the chunks that served the request; the final usage-only chunk carries - // the token accounting. + // Captured chat-completions chunk shapes: OpenAI echoes `service_tier` on the chunks that + // served the request; the final usage-only chunk carries the token accounting. const TIERED_CONTENT_CHUNK: &str = "data: {\"id\":\"chatcmpl-1\",\"object\":\"chat.completion.chunk\",\"model\":\"gpt-5.5\",\"service_tier\":\"priority\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":\"Hi\"},\"finish_reason\":null}]}\n\n"; const USAGE_CHUNK: &str = "data: {\"id\":\"chatcmpl-1\",\"object\":\"chat.completion.chunk\",\"model\":\"gpt-5.5\",\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":\"stop\"}],\"usage\":{\"prompt_tokens\":1000000,\"completion_tokens\":1000000,\"total_tokens\":2000000,\"prompt_tokens_details\":{\"cached_tokens\":0}}}\n\n"; const DONE: &str = "data: [DONE]\n\n"; @@ -864,8 +849,8 @@ mod tests { format!("{content}{usage}{DONE}") } - // Captured OpenRouter chunk shapes: the gateway echoes the upstream - // model and tier, and reports billing in the final usage chunk. + // Captured OpenRouter chunk shapes: the gateway echoes the upstream model and tier, and reports + // billing in the final usage chunk. fn openrouter_sse(usage_fields: &str) -> String { let content = "data: {\"id\":\"gen-01\",\"object\":\"chat.completion.chunk\",\"model\":\"anthropic/claude-fable-5\",\"service_tier\":\"priority\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":\"Hi\"}}]}\n\n"; let usage = format!("data: {{\"id\":\"gen-01\",\"object\":\"chat.completion.chunk\",\"choices\":[],\"usage\":{{\"prompt_tokens\":50000,\"completion_tokens\":50000,\"total_tokens\":100000,\"prompt_tokens_details\":{{\"cached_tokens\":0}}{usage_fields}}}}}\n\n"); @@ -915,8 +900,6 @@ mod tests { async fn gateway_service_tier_not_applied_to_openrouter() { let model = completions_model("anthropic/claude-fable-5", "openrouter", 0.5, 0.5); let message = stream_final_message(model, openrouter_sse("")).await; - // The tier multiplier table is OpenAI's own; gateways price their - // tiers per endpoint, so the catalog estimate stands. assert!((message.usage.cost.input.as_f64() - 0.025).abs() < 1e-9); assert!((message.usage.cost.output.as_f64() - 0.025).abs() < 1e-9); assert!((message.usage.cost.total.as_f64() - 0.05).abs() < 1e-9); diff --git a/crates/pa-ai/src/providers/openai_completions/stream/tests/stream_pins.rs b/crates/pa-ai/src/providers/openai_completions/stream/tests/stream_pins.rs index e63cfdff87b..d769ee824ab 100644 --- a/crates/pa-ai/src/providers/openai_completions/stream/tests/stream_pins.rs +++ b/crates/pa-ai/src/providers/openai_completions/stream/tests/stream_pins.rs @@ -1,17 +1,13 @@ -//! The thinking-channel pins: a GLM-5.3-style response arrives either with -//! its reasoning in `delta.reasoning_content` (the healthy envelope — -//! the thinking block's signature is the field name) or with its -//! reasoning merged into `delta.content` (the content-only envelope — -//! no thinking block at all, the reasoning rides the text block). The -//! stream maps whichever envelope the provider sends; these two pins -//! document that BOTH assemblies are faithful, so stored rows whose -//! reasoning rides the text block are the provider's envelope, not a -//! local reclassification of a thinking stream. +//! The thinking-channel pins: a GLM-5.3-style response arrives either with its reasoning in +//! `delta.reasoning_content` (the healthy envelope — the thinking block's signature is the field +//! name) or with its reasoning merged into `delta.content` (the content-only envelope — no thinking +//! block at all). Both assemblies are faithful: a stored row's reasoning riding the text block is +//! the provider's envelope, not a local reclassification. use super::*; -/// The diagnosed session's model entry (the internal GLM-5.3 fast -/// route: reasoning mandatory, catalog `reasoning: true`). +/// The diagnosed session's model entry (the internal GLM-5.3 fast route: reasoning mandatory, +/// catalog `reasoning: true`). fn glm_fast_model() -> Value { json!({ "id": "internal/glm-5.3-fast", @@ -26,8 +22,7 @@ fn glm_fast_model() -> Value { }) } -/// Stream one SSE body end-to-end, collecting every event plus the -/// final assistant message. +/// Stream one SSE body end-to-end, collecting every event plus the final assistant message. async fn stream_events( model: Value, body: String, @@ -76,12 +71,9 @@ fn sse_body(chunks: &[Value]) -> String { body } -/// THE CONTENT-ONLY ENVELOPE: the reasoning arrives ONLY inside `content` -/// deltas — no `reasoning_content` delta — so the assembled message -/// carries no thinking block and the text block holds the reasoning -/// merged with the response. No thinking events fire: the stored rows -/// this assembly produces are the store being faithful to the envelope, -/// not a misclassification. +/// THE CONTENT-ONLY ENVELOPE: the reasoning arrives ONLY inside `content` deltas — no +/// `reasoning_content` delta — so the assembled message carries no thinking block and the text +/// block holds the reasoning merged with the response. #[tokio::test] async fn reasoning_in_content_deltas_assembles_no_thinking_block() { let reasoning_prose = "The domain-flip PR (#3142) is green. The plan:\n1. Create the worktree.\n2. Start the rebase.\nActually — the smarter route: let me execute."; @@ -148,10 +140,9 @@ async fn reasoning_in_content_deltas_assembles_no_thinking_block() { assert_eq!(message.usage.input, 244_064); } -/// THE HEALTHY ENVELOPE: the reasoning arrives in `delta.reasoning_content`, -/// the answer in `delta.content`, and the assembled message carries the -/// thinking block whose signature is the field name (the wire shape the -/// session rows' `thinkingSignature: "reasoning_content"` records), +/// THE HEALTHY ENVELOPE: the reasoning arrives in `delta.reasoning_content`, the answer in +/// `delta.content`, and the assembled message carries the thinking block whose signature is the +/// field name (the wire shape the session rows' `thinkingSignature: "reasoning_content"` records), /// followed by the text block. Thinking events fire. #[tokio::test] async fn reasoning_content_deltas_assemble_the_thinking_block_with_the_field_signature() { diff --git a/crates/pa-ai/src/providers/openai_responses.rs b/crates/pa-ai/src/providers/openai_responses.rs index 5185e7c0aad..d37a329a4fc 100644 --- a/crates/pa-ai/src/providers/openai_responses.rs +++ b/crates/pa-ai/src/providers/openai_responses.rs @@ -1,7 +1,6 @@ -//! `OpenAI` Responses API streaming provider. -//! Port of `packages/ai/src/providers/openai-responses.ts`: session-affinity -//! headers, prompt-cache retention, reasoning params with encrypted-content -//! include, service-tier pricing, and the shared Responses stream processor. +//! `OpenAI` Responses API streaming provider: session-affinity headers, prompt-cache retention, +//! reasoning params with encrypted-content include, service-tier pricing, and the shared Responses +//! stream processor. use serde_json::{json, Map, Value}; @@ -50,11 +49,9 @@ pub struct ResolvedResponsesCompat { } pub fn get_responses_compat(model: &Model) -> ResolvedResponsesCompat { - // TS reads the responses compat directly: the wire object cannot tag - // its shape, and a shared-key-only object (the xAI subscription's - // `supportsLongCacheRetention: false`) still decodes — every field is - // optional and unknown keys are ignored, so the responses view of any - // compat object is lossless for this API. + // TS reads the responses compat directly: the wire object cannot tag its shape, and a + // shared-key-only object still decodes — every field is optional and unknown keys are ignored, + // so the responses view of any compat object is lossless for this API. let compat = model.compat.as_ref().and_then(|compat| { serde_json::from_value::(compat.raw.clone().into()) .ok() @@ -82,7 +79,7 @@ fn get_prompt_cache_retention( } } -/// Provider-native options (`OpenAIResponsesOptions` in the TS reference). +/// Provider-native options. #[derive(Clone, Default)] pub struct OpenAIResponsesOptions { pub base: StreamOptions, @@ -102,7 +99,6 @@ impl OpenAIResponsesOptions { } } -/// Port of `streamOpenAIResponses`. pub fn stream_openai_responses( model: &Model, context: &Context, @@ -276,7 +272,7 @@ fn build_params(model: &Model, context: &Context, options: &OpenAIResponsesOptio Value::Object(params) } -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] async fn run_stream( model: &Model, @@ -324,9 +320,6 @@ async fn run_stream( on_response( crate::types::ProviderResponse { status: response.status, - // Collected into the ordered map: the hook payload can - // serialize, and the HTTP header arrival order is not a - // stable serialization order. headers: response.headers.clone().into_iter().collect(), }, model, @@ -362,9 +355,8 @@ async fn run_stream( crate::providers::openai_responses_shared::ResponsesStreamProcessor::new( model, output, writer, hooks, ); - // The TS try/catch encloses the streaming section and the abort and - // stop-reason checks; the catch settles partial tool calls before the - // error event carries the message (TS PR #2783). + // The TS try/catch encloses the streaming section and the abort and stop-reason checks; the + // catch settles partial tool calls before the error event carries the message. stream_result = async { let mut decoder = SseDecoder::new(); loop { @@ -424,7 +416,6 @@ async fn run_stream( Ok(()) } -/// Port of `streamSimpleOpenAIResponses`. pub fn stream_simple_openai_responses( model: &Model, context: &Context, @@ -503,8 +494,8 @@ impl Provider for OpenAIResponsesProvider { mod tests { use super::*; - /// A responses-served model with a wire `compat` object (the whole - /// model need not be responses-shaped for the compat resolution). + /// A responses-served model with a wire `compat` object (the whole model need not be + /// responses-shaped for the compat resolution). // Test-only helper; adapting its signature and call sites would churn test fixtures. #[allow(clippy::needless_pass_by_value)] fn compat_model(raw: serde_json::Value) -> Model { @@ -520,10 +511,9 @@ mod tests { #[test] fn the_shared_key_only_compat_decodes_for_responses_models() { - // TS `getXaiSubscriptionModel`'s compat carries only - // `supportsLongCacheRetention: false`; the responses provider - // reads the responses view directly (the wire object cannot tag - // its shape). + // TS `getXaiSubscriptionModel`'s compat carries only `supportsLongCacheRetention: false`; + // the responses provider reads the responses view directly (the wire object cannot tag its + // shape). let model = compat_model(serde_json::json!({ "supportsLongCacheRetention": false })); let compat = get_responses_compat(&model); assert!(!compat.supports_long_cache_retention); @@ -554,11 +544,10 @@ mod tests { assert!(compat.supports_long_cache_retention); } - /// A `reasoning: false` model whose map addresses levels (the live - /// catalog's `gpt-5.3-chat-latest` shape, served over the Responses - /// API) is thinking-capable: the requested effort reaches the request - /// with the map's value. The flag alone must not veto a route that - /// declares addressable levels. + /// A `reasoning: false` model whose map addresses levels (the live catalog's + /// `gpt-5.3-chat-latest` shape, served over the Responses API) is thinking-capable: the + /// requested effort reaches the request with the map's value. The flag alone must not veto a + /// route that declares addressable levels. #[test] fn a_map_addressable_model_sends_the_reasoning_effort_without_the_flag() { let model = serde_json::from_value::(json!({ diff --git a/crates/pa-ai/src/providers/openai_responses_hooks.rs b/crates/pa-ai/src/providers/openai_responses_hooks.rs index 51f0174748d..836641b4f72 100644 --- a/crates/pa-ai/src/providers/openai_responses_hooks.rs +++ b/crates/pa-ai/src/providers/openai_responses_hooks.rs @@ -1,6 +1,4 @@ -//! `OpenAI` Responses stream hooks, reasoning-summary options, and service-tier -//! pricing. Section of the port of -//! `packages/ai/src/providers/openai-responses.ts`. +//! `OpenAI` Responses stream hooks, reasoning-summary options, and service-tier pricing. use crate::types::Usage; diff --git a/crates/pa-ai/src/providers/openai_responses_shared.rs b/crates/pa-ai/src/providers/openai_responses_shared.rs index 3359765a810..d26d893a93a 100644 --- a/crates/pa-ai/src/providers/openai_responses_shared.rs +++ b/crates/pa-ai/src/providers/openai_responses_shared.rs @@ -1,9 +1,5 @@ -//! `OpenAI` Responses API message and tool conversion. -//! -//! Port of the conversion half of -//! `packages/ai/src/providers/openai-responses-shared.ts`: reasoning item -//! replay via thinkingSignature, text signatures, foreign tool-call id -//! normalization. The stream event processor lives in +//! `OpenAI` Responses API message and tool conversion: reasoning item replay via thinkingSignature, +//! text signatures, foreign tool-call id normalization. The stream event processor lives in //! [`crate::providers::openai_responses_stream`]. use serde_json::{json, Map, Value}; @@ -62,12 +58,7 @@ fn parse_text_signature(signature: Option<&str>) -> Option }) } -// --------------------------------------------------------------------------- -// Message conversion -// --------------------------------------------------------------------------- - -/// Providers whose tool-call IDs may carry the `call_id|item_id` Responses -/// encoding natively. +/// Providers whose tool-call IDs may carry the `call_id|item_id` Responses encoding natively. pub const OPENAI_TOOL_CALL_PROVIDERS: [&str; 3] = ["openai", "openai-codex", "opencode"]; pub const AZURE_TOOL_CALL_PROVIDERS: [&str; 4] = [ "openai", @@ -117,7 +108,7 @@ fn build_foreign_responses_item_id(item_id: &str) -> String { } /// Convert a conversation to Responses API `input` items. -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] pub fn convert_responses_messages( model: &Model, @@ -230,10 +221,9 @@ pub fn convert_responses_messages( AssistantContent::Text(text) => { let parsed_signature = parse_text_signature(text.text_signature.as_deref()); - // OpenAI requires id to be max 64 characters and - // rejects empty ids ([ApiParam][invalid_id]); a - // message without a usable signature id falls - // back to its index in the converted history. + // OpenAI requires id to be max 64 characters and rejects empty ids + // ([ApiParam][invalid_id]); a message without a usable signature id + // falls back to its index in the converted history. let msg_id = match parsed_signature .as_ref() .filter(|signature| !signature.id.is_empty()) @@ -268,11 +258,10 @@ pub fn convert_responses_messages( output.push(Value::Object(entry)); } AssistantContent::ToolCall(tool_call) => { - // The item id is the `fc_` segment after the `|`. - // Without a `|` there is no item id: the `id` key - // is omitted (an empty id is rejected by the API - // with [ApiParam][invalid_id]) and the whole id - // serves as the call id. + // The item id is the `fc_` segment after the `|`. Without a `|` there + // is no item id: the `id` key is omitted (an empty id is rejected by + // the API with [ApiParam][invalid_id]) and the whole id serves as the + // call id. let (call_id, item_id) = match tool_call.id.split_once('|') { Some((call_id, item_id)) => { (call_id, (!item_id.is_empty()).then_some(item_id)) @@ -281,9 +270,8 @@ pub fn convert_responses_messages( }; let mut entry = Map::new(); entry.insert("type".into(), json!("function_call")); - // For different-model messages, omit the id to - // avoid pairing validation against rs_ reasoning - // items tracked by the provider. + // For different-model messages, omit the id to avoid pairing validation + // against rs_ reasoning items tracked by the provider. let omit_id = item_id.is_none() || (is_different_model && item_id.is_some_and(|id| id.starts_with("fc_"))); @@ -494,8 +482,8 @@ mod tests { ) } - /// Every input item that carries an `id` or `call_id` must be non-empty: - /// the Responses API rejects empty ids with `[ApiParam][invalid_id]`. + /// Every input item that carries an `id` or `call_id` must be non-empty: the Responses API + /// rejects empty ids with `[ApiParam][invalid_id]`. fn assert_no_empty_ids(items: &[Value]) { for item in items { for key in ["id", "call_id"] { @@ -506,10 +494,9 @@ mod tests { } } - /// A tool call without the `call_id|item_id` encoding omits the item - /// `id` entirely and keeps the whole id as `call_id` (TS evidence: - /// `convertResponsesMessages` with a pipe-less toolCall.id; the dogfood - /// bug emitted `id: ""` here and the API rejected the turn). + /// A tool call without the `call_id|item_id` encoding omits the item `id` entirely and keeps + /// the whole id as `call_id` (TS evidence: `convertResponsesMessages` with a pipe-less + /// toolCall.id; the dogfood bug emitted `id: ""` here and the API rejected the turn). #[test] fn pipe_less_tool_call_id_omits_item_id() { let items = convert( @@ -543,8 +530,8 @@ mod tests { ); } - /// A tool call id with an empty `fc_` segment (stream items without an - /// id) omits the item `id` instead of emitting `id: ""`. + /// A tool call id with an empty `fc_` segment (stream items without an id) omits the item `id` + /// instead of emitting `id: ""`. #[test] fn empty_item_id_segment_omits_item_id() { let items = convert( @@ -566,10 +553,9 @@ mod tests { assert_eq!(function_call.get("call_id"), Some(&json!("call_x"))); } - /// A fully-empty tool call id omits the item `id`; the `call_id` fields - /// stay empty on both items, matching the TS reference exactly (the - /// reachable dogfood shape never produces an empty tool call id because - /// tool results inherit the tool call id verbatim). + /// A fully-empty tool call id omits the item `id`; the `call_id` fields stay empty on both + /// items, matching the TS reference exactly (the reachable dogfood shape never produces an + /// empty tool call id because tool results inherit the tool call id verbatim). #[test] fn empty_tool_call_id_omits_item_id() { let items = convert( @@ -590,9 +576,8 @@ mod tests { assert_eq!(function_call.get("call_id"), Some(&json!(""))); } - /// Same-provider messages from a different model omit the `fc_` item id - /// so the API does not pair it against `rs_` reasoning items tracked for - /// this model (TS: `itemId = undefined`). + /// Same-provider messages from a different model omit the `fc_` item id so the API does not + /// pair it against `rs_` reasoning items tracked for this model (TS: `itemId = undefined`). #[test] fn different_model_fc_item_id_is_omitted() { let items = convert( @@ -635,8 +620,8 @@ mod tests { assert_eq!(function_call.get("call_id"), Some(&json!("call_x"))); } - /// Assistant text without a signature id falls back to its converted - /// history index instead of an empty message id (TS: `msg_${msgIndex}`). + /// Assistant text without a signature id falls back to its converted history index instead of + /// an empty message id (TS: `msg_${msgIndex}`). #[test] fn message_without_signature_uses_index_fallback_id() { let items = convert( diff --git a/crates/pa-ai/src/providers/openai_responses_stream.rs b/crates/pa-ai/src/providers/openai_responses_stream.rs index c5c37a6ea4b..ea687478258 100644 --- a/crates/pa-ai/src/providers/openai_responses_stream.rs +++ b/crates/pa-ai/src/providers/openai_responses_stream.rs @@ -1,15 +1,7 @@ -//! `OpenAI` Responses stream event processor. -//! -//! Port of `processResponsesStream` from -//! `packages/ai/src/providers/openai-responses-shared.ts`: output-item slots, -//! reasoning summary/text deltas, refusal deltas, function-call argument -//! accumulation, xai encrypted-reasoning merge, and usage accounting. Hook -//! types and service-tier pricing live in +//! `OpenAI` Responses stream event processor: hook types and service-tier pricing live in //! [`super::openai_responses_hooks`]. //! -//! Size note: `handle_event` is intentionally kept as one large function. It -//! is a 1:1 port of the single `processResponsesStream` event match in -//! `openai-responses-shared.ts`, and splitting its arms would break +//! `handle_event` stays one large function: a 1:1 port of the TS event match, kept whole for //! traceability to the TS source. use std::collections::HashMap; @@ -38,7 +30,6 @@ struct Slot { item: Value, /// Scratch for tool-call argument accumulation. partial_json: StreamingJsonAccumulator, - /// Assistant content index for this slot. content_index: usize, } @@ -86,9 +77,8 @@ impl<'a> ResponsesStreamProcessor<'a> { } } - /// Process one parsed stream event. Errors mirror the TS thrown - /// `StreamFailureError`s. - // Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. + /// Process one parsed stream event. Errors mirror the TS thrown `StreamFailureError`s. + // Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] pub fn handle_event(&mut self, event: &Value) -> Result<(), ProviderError> { let event_type = event @@ -901,9 +891,8 @@ impl<'a> ResponsesStreamProcessor<'a> { Ok(()) } - /// Terminal stop reason of the message under construction (read through - /// the processor so error-path checks can run while the borrow of the - /// output message lives here). + /// Terminal stop reason of the message under construction (read through the processor so + /// error-path checks can run while the borrow of the output message lives here). pub fn stop_reason(&self) -> StopReason { self.output.stop_reason } @@ -913,10 +902,9 @@ impl<'a> ResponsesStreamProcessor<'a> { self.output.stop_reason_raw.as_deref() } - /// Port of the TS catch settle: finalize tool-call blocks whose parsed - /// preview may lag the accumulated text under the growth throttle. The - /// outer providers call this on their error paths before the error event - /// carries the message. + /// The TS catch settle: finalize tool-call blocks whose parsed preview may lag the accumulated + /// text under the growth throttle. The outer providers call this on their error paths before + /// the error event carries the message. pub fn settle_partial_tool_calls(&mut self) { for slot in self.slots.values_mut() { let Some(parsed) = slot.partial_json.flush() else { diff --git a/crates/pa-ai/src/providers/simple_options.rs b/crates/pa-ai/src/providers/simple_options.rs index 08a4cd50dfd..3bbba62454a 100644 --- a/crates/pa-ai/src/providers/simple_options.rs +++ b/crates/pa-ai/src/providers/simple_options.rs @@ -1,5 +1,4 @@ //! Shared simple-stream option assembly. -//! Ported from `packages/ai/src/providers/simple-options.ts`. use crate::types::{ Model, ModelThinkingLevel, SimpleStreamOptions, StreamOptions, ThinkingBudgets, @@ -11,8 +10,8 @@ use crate::types::{ /// was configured explicitly. pub const REQUEST_MAX_TOKENS_CAP: u64 = 32_000; -/// The smallest output budget a request may keep after clamping (TS -/// `adjustMaxTokensForThinking`: `minOutputTokens`). +/// The smallest output budget a request may keep after clamping (TS `adjustMaxTokensForThinking`: +/// `minOutputTokens`). pub const MIN_OUTPUT_TOKENS: u64 = 1_024; /// The default per-request output budget for a model (TS `resolveMaxTokens`): @@ -74,8 +73,8 @@ pub fn clamp_reasoning(effort: ModelThinkingLevel) -> ModelThinkingLevel { /// Budget-based thinking token adjustment (mirrors `adjustMaxTokensForThinking`). /// -/// Returns an error mirroring the TS throw when there is not enough room for -/// thinking tokens plus the response. +/// Returns an error mirroring the TS throw when there is not enough room for thinking tokens plus +/// the response. pub fn adjust_max_tokens_for_thinking( base_max_tokens: u64, model_max_tokens: u64, @@ -129,15 +128,12 @@ pub fn adjust_max_tokens_for_thinking( Ok((max_tokens, thinking_budget)) } -/// The `max_tokens` the provider will actually send for a request against -/// `model` with this reasoning level: budget-folding providers (Anthropic -/// and Bedrock models without adaptive thinking) add the level's thinking -/// budget on top of the base per-request budget, capped at the model's -/// declared max output ([`adjust_max_tokens_for_thinking`]); every other -/// provider (and reasoning off) sends the base budget itself. Compaction -/// thresholds must reserve this effective budget, or a request can claim -/// `input + max_tokens > contextWindow` while the trigger still says -/// "not due". +/// The `max_tokens` the provider will actually send for a request against `model` with this +/// reasoning level: budget-folding providers (Anthropic and Bedrock models without adaptive +/// thinking) add the level's thinking budget on top of the base per-request budget, capped at the +/// model's declared max output ([`adjust_max_tokens_for_thinking`]); every other provider sends the +/// base budget itself. Compaction thresholds must reserve this effective budget, or a request can +/// claim `input + max_tokens > contextWindow` while the trigger still says "not due". #[must_use] pub fn effective_request_max_tokens(model: &Model, reasoning: ModelThinkingLevel) -> u64 { let base = default_request_max_tokens(model).unwrap_or(0); @@ -146,8 +142,8 @@ pub fn effective_request_max_tokens(model: &Model, reasoning: ModelThinkingLevel } let budget_folds = match model.api.as_str() { "anthropic" => !crate::providers::anthropic::supports_adaptive_thinking(&model.id), - // The Bedrock fold runs only on Claude models without adaptive - // thinking (`streamSimpleBedrock`'s own gate). + // The Bedrock fold runs only on Claude models without adaptive thinking + // (`streamSimpleBedrock`'s own gate). "bedrock" => { crate::providers::bedrock::is_anthropic_claude_model(model) && !crate::providers::bedrock::supports_adaptive_thinking( @@ -285,8 +281,8 @@ mod tests { #[test] fn budget_folding_providers_add_the_thinking_budget_on_top() { - // A non-adaptive Anthropic model: `high` folds 16_384 thinking - // tokens onto the 32_000 base budget (adjustMaxTokensForThinking). + // A non-adaptive Anthropic model: `high` folds 16_384 thinking tokens onto the 32_000 base + // budget (adjustMaxTokensForThinking). let anthropic = model("anthropic", "claude-sonnet-4-5", 65_536); assert_eq!( effective_request_max_tokens(&anthropic, ModelThinkingLevel::Off), @@ -320,8 +316,7 @@ mod tests { effective_request_max_tokens(&adaptive, ModelThinkingLevel::High), 32_000 ); - // OpenAI-style reasoning consumes the budget from within, never on - // top of it. + // OpenAI-style reasoning consumes the budget from within, never on top of it. let openai = model("openai-completions", "gpt-x", 65_536); assert_eq!( effective_request_max_tokens(&openai, ModelThinkingLevel::High), diff --git a/crates/pa-ai/src/providers/transform_messages.rs b/crates/pa-ai/src/providers/transform_messages.rs index d99a9158e0d..78ab8e14fb7 100644 --- a/crates/pa-ai/src/providers/transform_messages.rs +++ b/crates/pa-ai/src/providers/transform_messages.rs @@ -1,5 +1,4 @@ //! Message normalization shared by providers. -//! Ported from `packages/ai/src/providers/transform-messages.ts`. use std::collections::{HashMap, HashSet}; @@ -72,10 +71,9 @@ fn downgrade_unsupported_images(messages: &[Message], model: &Model) -> Vec = dyn Fn(&str, &Model, &AssistantMessage) -> Option + 'a; -/// Core port of `transformMessages`: tool-call ID normalization plus -/// synthetic tool results for unanswered calls, dropping errored assistant -/// turns. -// Long by design (a 1:1 port of the upstream provider shape); refactoring is out of scope for the zero-behavior pedantic sweep. +/// Tool-call ID normalization plus synthetic tool results for unanswered calls, dropping errored +/// assistant turns (TS `transformMessages`). +// Long by design: mirrors the provider's stream shape. #[allow(clippy::too_many_lines)] pub fn transform_messages_with_normalizer( messages: &[Message], @@ -204,8 +202,8 @@ pub fn transform_messages_with_normalizer( &mut existing_tool_result_ids, ); - // Skip errored/aborted assistant messages entirely. - // These are incomplete turns that shouldn't be replayed. + // Skip errored/aborted assistant messages entirely. These are incomplete turns that + // shouldn't be replayed. if matches!( assistant.stop_reason, StopReason::Error | StopReason::Aborted diff --git a/crates/pa-ai/src/registry.rs b/crates/pa-ai/src/registry.rs index a8789a2da08..9f6c33c302c 100644 --- a/crates/pa-ai/src/registry.rs +++ b/crates/pa-ai/src/registry.rs @@ -1,8 +1,5 @@ -//! API provider registry. -//! -//! Ported from `packages/ai/src/api-registry.ts`: providers register stream -//! functions per `api` identifier; `stream()`/`complete()` resolve the -//! provider for a model and forward. +//! API provider registry: providers register stream functions per `api` identifier; +//! `stream()`/`complete()` resolve the provider for a model and forward. use std::collections::HashMap; use std::sync::{Arc, OnceLock, RwLock}; @@ -10,7 +7,7 @@ use std::sync::{Arc, OnceLock, RwLock}; use crate::event_stream::AssistantMessageEventStream; use crate::types::{Context, Model, SimpleStreamOptions, StreamOptions}; -/// A provider implementation for one API (the TS `ApiProvider`). +/// A provider implementation for one API. pub trait Provider: Send + Sync { /// The `api` identifier this provider serves, e.g. "openai-completions". fn api(&self) -> &str; @@ -44,8 +41,7 @@ fn registry() -> &'static RwLock> { /// /// # Panics /// -/// Panics if the registry `RwLock` is poisoned (a thread panicked while -/// holding it). +/// Panics if the registry `RwLock` is poisoned (a thread panicked while holding it). pub fn register_api_provider(provider: Arc, source_id: Option<&str>) { let mut registry = registry().write().unwrap(); registry.insert( @@ -61,8 +57,7 @@ pub fn register_api_provider(provider: Arc, source_id: Option<&str /// /// # Panics /// -/// Panics if the registry `RwLock` is poisoned (a thread panicked while -/// holding it). +/// Panics if the registry `RwLock` is poisoned (a thread panicked while holding it). #[must_use] pub fn get_api_provider(api: &str) -> Option> { registry() @@ -76,8 +71,7 @@ pub fn get_api_provider(api: &str) -> Option> { /// /// # Panics /// -/// Panics if the registry `RwLock` is poisoned (a thread panicked while -/// holding it). +/// Panics if the registry `RwLock` is poisoned (a thread panicked while holding it). #[must_use] pub fn get_api_providers() -> Vec> { registry() @@ -92,8 +86,7 @@ pub fn get_api_providers() -> Vec> { /// /// # Panics /// -/// Panics if the registry `RwLock` is poisoned (a thread panicked while -/// holding it). +/// Panics if the registry `RwLock` is poisoned (a thread panicked while holding it). pub fn unregister_api_providers(source_id: &str) { let mut registry = registry().write().unwrap(); registry.retain(|_, entry| entry.source_id.as_deref() != Some(source_id)); @@ -103,23 +96,19 @@ pub fn unregister_api_providers(source_id: &str) { /// /// # Panics /// -/// Panics if the registry `RwLock` is poisoned (a thread panicked while -/// holding it). +/// Panics if the registry `RwLock` is poisoned (a thread panicked while holding it). pub fn clear_api_providers() { registry().write().unwrap().clear(); } -/// Register the built-in providers (explicit Rust equivalent of the TS -/// side-effect import in `stream.ts` / `register-builtins.ts`). +/// Register the built-in providers (the explicit Rust equivalent of the TS side-effect import). /// /// # Panics /// -/// Panics if the registry `RwLock` is poisoned (a thread panicked while -/// holding it). +/// Panics if the registry `RwLock` is poisoned (a thread panicked while holding it). pub fn register_builtin_api_providers() { let mut registry = registry().write().unwrap(); - // Providers are registered here as they are ported; each entry mirrors the - // corresponding import in `providers/register-builtins.ts`. + // Each entry mirrors the corresponding import in `providers/register-builtins.ts`. let builtins: Vec> = vec![ Arc::new(crate::providers::anthropic::AnthropicMessagesProvider), Arc::new(crate::providers::openai_completions::OpenAICompletionsProvider), @@ -154,9 +143,8 @@ pub fn ensure_builtins() { ENSURED.get_or_init(register_builtin_api_providers); } -/// Registry facade over the process-wide provider map: the type consumers -/// hold and call (the free functions below remain for parity with the TS -/// module surface). +/// Registry facade over the process-wide provider map (the free functions below remain for parity +/// with the TS module surface). pub struct ProviderRegistry; impl ProviderRegistry { diff --git a/crates/pa-ai/src/stream.rs b/crates/pa-ai/src/stream.rs index a44959f3d1a..975c832cf70 100644 --- a/crates/pa-ai/src/stream.rs +++ b/crates/pa-ai/src/stream.rs @@ -1,5 +1,4 @@ //! Public streaming facade. -//! Ported from `packages/ai/src/stream.ts`. use std::sync::Arc; @@ -15,26 +14,18 @@ fn resolve_provider(api: &str) -> Result, Pro .ok_or_else(|| ProviderError::Message(format!("No API provider registered for api: {api}"))) } -// --------------------------------------------------------------------------- -// Combined-ceiling output clamp -// --------------------------------------------------------------------------- - -/// Estimate a request's input tokens before it is sent: chars/4 over the -/// text the provider will serialize, images at 1,200 tokens each. The same -/// conservative policy the session engine's compaction estimator applies -/// (`pa-core` cannot be a dependency here, so the heuristic is restated). +/// Estimate a request's input tokens before it is sent: chars/4 over the text the provider will +/// serialize, images at 1,200 tokens each (the session engine's compaction policy, restated: +/// `pa-core` cannot be a dependency here). fn estimated_input_tokens(context: &Context) -> u64 { const TOOL_ENVELOPE_CHARS: u64 = 48; let mut chars = context .system_prompt .as_deref() .map_or(0, |text| text.chars().count()) as u64; - // Tool definitions serialize into every request (the provider sends - // each schema on every call), so they claim input room like the - // tool-call arguments below. Providers wrap each schema in their own - // envelope on the wire (OpenAI-completions: - // `{"type":"function","function":...}` plus flags like `strict`), so - // every tool also counts the widest envelope's chars. + // Tool definitions serialize into every request, so they claim input room like the tool-call + // arguments below. Providers wrap each schema in their own envelope on the wire, so every tool + // also counts the widest envelope's chars. for tool in context.tools.iter().flatten() { chars = chars.saturating_add( serde_json::to_string(tool) @@ -86,22 +77,13 @@ fn user_content_block_chars(blocks: &[crate::types::UserOrToolContent]) -> u64 { .sum() } -/// Clamp the requested output budget against the model's combined -/// input+output ceiling: a provider that enforces `input + max_tokens <= -/// contextWindow` rejects an unsatisfiable request outright (the live -/// 400: 1,017,457 input + 32,000 requested output on a 1,048,576 window), -/// so the facade shrinks the output budget to whatever room the estimated -/// input leaves. The estimate covers the full serialized request — system -/// prompt, tool schemas, message text, raw blocks, images — so it tracks -/// the provider's own input count instead of leaving uncounted bytes to -/// overflow it. +/// Clamp the requested output budget against the model's combined input+output ceiling: a provider +/// enforcing `input + max_tokens <= contextWindow` rejects an unsatisfiable request outright, so +/// the facade shrinks the output budget to whatever room the estimated input leaves. /// -/// The TS facade never clamps (`packages/ai/src/providers/simple-options.ts` -/// caps only at `min(model.maxTokens, 32000)`); this is a deliberate -/// Rust-side guard. Budget-folding thinking providers (Anthropic, Bedrock) -/// add their thinking budget after this clamp and cap it at -/// `model.max_tokens`; the compaction threshold's headroom and the overflow -/// recovery arm remain the guards for that corner. +/// The TS facade never clamps; this is a deliberate Rust-side guard. Budget-folding thinking +/// providers (Anthropic, Bedrock) add their budget after this clamp and cap it at +/// `model.max_tokens`. fn clamp_output_budget(model: &Model, context: &Context, options: Option<&mut StreamOptions>) { let Some(options) = options else { return; @@ -118,8 +100,8 @@ fn clamp_output_budget(model: &Model, context: &Context, options: Option<&mut St let available = model .context_window .saturating_sub(estimated_input_tokens(context)); - // Zero room means the input alone fills the window — no budget can - // save the request, so it stays as sent for the overflow recovery arm. + // Zero room means the input alone fills the window — no budget can save the request, so it + // stays as sent for the overflow recovery arm. if requested > available && available > 0 { options.max_tokens = Some(available); } @@ -234,8 +216,7 @@ mod tests { let serialized = serde_json::to_string(&tool).expect("tool serializes"); let mut context = text_context(3_000); context.tools = Some(vec![tool]); - // The tool schema's serialized bytes plus its wire envelope join - // the text under chars/4. + // The tool schema's serialized bytes plus its wire envelope join the text under chars/4. assert_eq!( estimated_input_tokens(&context), (3_000 + 48 + serialized.chars().count() as u64).div_ceil(4) @@ -244,8 +225,8 @@ mod tests { #[test] fn the_estimate_counts_raw_blocks_as_their_serialized_json() { - // Raw blocks reach the prompt as text (`user_block_payload`'s - // opaque arm), so their serialized bytes claim input room. + // Raw blocks reach the prompt as text (`user_block_payload`'s opaque arm), so their + // serialized bytes claim input room. let value = json!({"unmodeled": "y".repeat(4_000)}); let serialized = serde_json::to_string(&value).expect("value serializes"); let mut context = text_context(3_000); @@ -264,10 +245,8 @@ mod tests { #[test] fn tool_schemas_shrink_the_room_the_clamp_leaves() { - // A tool-carrying request the text-only estimate called - // satisfiable now clamps: the schemas eat the output room. The - // input must still fit the window — zero room leaves the budget - // for the overflow recovery arm instead. + // The schemas eat the output room; the input must still fit the window — zero room leaves + // the budget for the overflow recovery arm instead. let model = test_model(1_000, 40_000); let mut context = text_context(3_000); // 750 text tokens let tool: crate::types::Tool = serde_json::from_value(json!({ @@ -283,9 +262,8 @@ mod tests { ..Default::default() }; clamp_output_budget(&model, &context, Some(&mut options)); - // 250 exactly fit the 750-token text input; the schema's - // serialized tokens leave less room than the budget requests, - // so the budget clamps to exactly what is left. + // The schema's serialized tokens leave less room than the budget requests, so the budget + // clamps to exactly what is left. let room = 1_000u64.saturating_sub((3_000 + 48 + serialized.chars().count() as u64).div_ceil(4)); assert_eq!(options.max_tokens, Some(room)); @@ -294,8 +272,8 @@ mod tests { #[test] fn clamp_shrinks_an_unsatisfiable_output_budget() { - // The live failure shape: an input estimate leaving less room than - // the requested output budget. + // The live failure shape: an input estimate leaving less room than the requested output + // budget. let model = test_model(1_000, 40_000); let context = text_context(3_000); // 750 estimated input tokens let mut options = StreamOptions { @@ -308,8 +286,8 @@ mod tests { #[test] fn clamp_resolves_the_default_budget_when_none_set() { - // The main-loop shape: no explicit max_tokens, so the effective - // request budget is min(model.maxTokens, 32000). + // The main-loop shape: no explicit max_tokens, so the effective request budget is + // min(model.maxTokens, 32000). let model = test_model(1_000, 40_000); let context = text_context(3_600); // 900 estimated input tokens let mut options = StreamOptions::default(); @@ -336,8 +314,8 @@ mod tests { #[test] fn clamp_takes_whatever_room_exists() { - // A sub-floor budget still fits: the clamp honors exactly the room - // the estimate leaves (250 room -> 250 requested output). + // A sub-floor budget still fits: the clamp honors exactly the room the estimate leaves (250 + // room -> 250 requested output). let model = test_model(1_000, 40_000); let context = text_context(3_000); // 750 estimated input tokens let mut options = StreamOptions { @@ -346,8 +324,8 @@ mod tests { }; clamp_output_budget(&model, &context, Some(&mut options)); assert_eq!(options.max_tokens, Some(250)); - // The input estimate fills the window: no budget can save the - // request, so it stays as sent for the overflow recovery arm. + // The input estimate fills the window: no budget can save the request, so it stays as sent + // for the overflow recovery arm. let context = text_context(4_400); // 1,100 estimated input tokens let mut options = StreamOptions { max_tokens: Some(400), diff --git a/crates/pa-ai/src/types.rs b/crates/pa-ai/src/types.rs index 083559334d8..5643c7fd458 100644 --- a/crates/pa-ai/src/types.rs +++ b/crates/pa-ai/src/types.rs @@ -1,10 +1,7 @@ //! AI surface types for providers. //! -//! The wire/domain types (messages, content blocks, usage, stream events, -//! models) live in [`pa_types::ai`] and are re-exported here for provider -//! code. This module adds the provider-internal option structs -//! ([`StreamOptions`], [`SimpleStreamOptions`]) and hooks that never cross -//! the wire, plus small extension helpers over the shared types. +//! The wire/domain types live in [`pa_types::ai`] and are re-exported here for provider code; this +//! module adds the provider-internal option structs and hooks that never cross the wire. use tokio_util::sync::CancellationToken; @@ -28,19 +25,13 @@ pub use pa_types::ai::{ /// here it is stored as the raw JSON value. pub type JsonSchema = serde_json::Value; -// --------------------------------------------------------------------------- -// User/tool-result block payload view -// --------------------------------------------------------------------------- - /// Provider payload view of one user/tool-result content block. /// -/// Most provider conversions map a block to either a text part or an image -/// part. Un-modeled blocks ([`UserOrToolContent::Raw`]: a missing `type` tag, -/// as persisted by earlier daemon builds, or an unknown kind from a newer -/// build) never reach the prompt as structured parts - a bare text block maps -/// to [`UserBlockPayload::Text`], a bare image block to -/// [`UserBlockPayload::Image`], and anything else to [`UserBlockPayload::Opaque`] -/// (its JSON, as text) so no content is silently dropped from a request. +/// Most provider conversions map a block to either a text part or an image part. Un-modeled blocks +/// ([`UserOrToolContent::Raw`]: a missing `type` tag or an unknown kind) never reach the prompt as +/// structured parts - a bare text block maps to [`UserBlockPayload::Text`], a bare image block to +/// [`UserBlockPayload::Image`], and anything else to [`UserBlockPayload::Opaque`] (its JSON, as +/// text) so no content is silently dropped from a request. #[derive(Debug, Clone, PartialEq)] pub enum UserBlockPayload<'a> { Text(&'a str), @@ -48,7 +39,6 @@ pub enum UserBlockPayload<'a> { Opaque(String), } -/// Classify a user/tool-result block for provider payload conversion. #[must_use] pub fn user_block_payload(block: &UserOrToolContent) -> UserBlockPayload<'_> { if let Some(text) = block.text() { @@ -57,8 +47,8 @@ pub fn user_block_payload(block: &UserOrToolContent) -> UserBlockPayload<'_> { if let Some((data, mime_type)) = block.image() { return UserBlockPayload::Image { data, mime_type }; } - // Un-modeled without recognized text/image fields: pass the block JSON - // through as text so a resumed conversation never silently loses content. + // Un-modeled without recognized text/image fields: pass the block JSON through as text so a + // resumed conversation never silently loses content. let json = match serde_json::to_value(block) { Ok(value) => value.to_string(), Err(error) => format!("{{\"serialize_error\": {error:?}}}"), @@ -66,19 +56,15 @@ pub fn user_block_payload(block: &UserOrToolContent) -> UserBlockPayload<'_> { UserBlockPayload::Opaque(json) } -// --------------------------------------------------------------------------- -// Hooks -// --------------------------------------------------------------------------- - -/// Hook invoked with the outbound provider payload before sending. Return None -/// to keep the payload unchanged. +/// Hook invoked with the outbound provider payload before sending. Return None to keep the payload +/// unchanged. pub type OnPayloadHook = std::sync::Arc Option + Send + Sync>; /// Hook invoked after the HTTP response is received and before the body is read. pub type OnResponseHook = std::sync::Arc; -/// Options shared by all providers (`StreamOptions` in the TS reference). +/// Options shared by all providers. #[derive(Clone, Default)] pub struct StreamOptions { pub temperature: Option, @@ -136,19 +122,13 @@ impl SimpleStreamOptions { } } -// --------------------------------------------------------------------------- -// Extension helpers over the shared wire types -// --------------------------------------------------------------------------- - -/// Provider-side helpers over [`Model`] (the TS `Model` methods live with the -/// type definition; here they are an extension trait because `Model` itself -/// is owned by `pa-types`). +/// Provider-side helpers over [`Model`] (the TS `Model` methods live with the type definition; here +/// they are an extension trait because `Model` itself is owned by `pa-types`). pub trait ModelExt { /// Parsed compat overrides for this model, when present. fn compat_kind(&self) -> Option; - /// Value mapped for a thinking level (provider-specific string); the outer - /// Option is None when the map is absent, the inner when the level is - /// unsupported/absent. + /// Value mapped for a thinking level (provider-specific string); the outer Option is None when + /// the map is absent, the inner when the level is unsupported/absent. fn thinking_level_map_value(&self, level: ModelThinkingLevel) -> Option>; /// Whether the model accepts image input blocks. fn supports_image_input(&self) -> bool; @@ -172,16 +152,11 @@ impl ModelExt for Model { } } -// --------------------------------------------------------------------------- -// Stop-reason mapping helpers -// --------------------------------------------------------------------------- - /// Map a [`StopReason`] to the terminal reason of a `done` event. /// /// # Panics /// -/// Panics for `error`/`aborted`, which only terminate streams through `error` -/// events. +/// Panics for `error`/`aborted`, which only terminate streams through `error` events. #[must_use] pub fn done_reason(reason: StopReason) -> DoneStopReason { match reason { @@ -227,7 +202,7 @@ pub fn zero_model_cost() -> ModelCost { } } -/// Zeroed usage (the TS `Usage` type is initialized with all-zero fields). +/// Zeroed usage. #[must_use] pub fn zeroed_usage() -> Usage { Usage::default() diff --git a/crates/pa-ai/src/utils_inner/diagnostics.rs b/crates/pa-ai/src/utils_inner/diagnostics.rs index 1b721754b7c..b07d5bfd106 100644 --- a/crates/pa-ai/src/utils_inner/diagnostics.rs +++ b/crates/pa-ai/src/utils_inner/diagnostics.rs @@ -1,7 +1,5 @@ -//! Structured diagnostics attached to assistant messages on failures and -//! recoveries. Ported from `packages/ai/src/utils/diagnostics.ts`; the types -//! themselves are the shared [`AssistantMessageDiagnostic`] / -//! [`DiagnosticErrorInfo`] from `pa-types`. +//! Structured diagnostics attached to assistant messages on failures and recoveries; the types are +//! the shared [`AssistantMessageDiagnostic`] / [`DiagnosticErrorInfo`] from `pa-types`. pub use crate::types::{AssistantMessage, AssistantMessageDiagnostic, DiagnosticErrorInfo}; diff --git a/crates/pa-ai/src/utils_inner/h2_classify.rs b/crates/pa-ai/src/utils_inner/h2_classify.rs index f87acd55edd..4565fd90dec 100644 --- a/crates/pa-ai/src/utils_inner/h2_classify.rs +++ b/crates/pa-ai/src/utils_inner/h2_classify.rs @@ -1,17 +1,12 @@ -//! http2 transport-failure classification for the bedrock h2 transports. -//! -//! The TS bedrock client's default transport is the AWS SDK's -//! `NodeHttp2Handler` on bun's `node:http2`: HTTP/2 with h2c prior knowledge -//! over cleartext (and h2-only ALPN over TLS). When the transport fails, the -//! observable surface is bun's `node:http2` error text and codes — which the -//! provider-error probe pinned byte-for-byte against the TS binary. This -//! module turns `h2` crate errors (directly, or through a reqwest error +//! http2 transport-failure classification for the bedrock h2 transports: the observable surface is +//! bun's `node:http2` error text and codes, pinned byte-for-byte against the TS binary by the +//! provider-error probe. This module turns `h2` crate errors (directly, or through a reqwest error //! chain) into the failure detail that composes those texts. use crate::utils_inner::stream_failure::H2Failure; -/// The nghttp2 error-code name bun composes for a stream reset -/// ("Stream closed with error code NGHTTP2_"). +/// The nghttp2 error-code name bun composes for a stream reset ("Stream closed with error code +/// NGHTTP2_"). pub(crate) fn nghttp2_code_name(reason: h2::Reason) -> String { match reason { h2::Reason::NO_ERROR => "NGHTTP2_NO_ERROR", @@ -28,9 +23,8 @@ pub(crate) fn nghttp2_code_name(reason: h2::Reason) -> String { h2::Reason::ENHANCE_YOUR_CALM => "NGHTTP2_ENHANCE_YOUR_CALM", h2::Reason::INADEQUATE_SECURITY => "NGHTTP2_INADEQUATE_SECURITY", h2::Reason::HTTP_1_1_REQUIRED => "NGHTTP2_HTTP_1_1_REQUIRED", - // `h2::Reason` is an open u32 newtype; unknown codes have no nghttp2 - // name, so fall back to the wire number like nghttp2's own - // `nghttp2_strerror` does for unknown codes. + // `h2::Reason` is an open u32 newtype; unknown codes have no nghttp2 name, so fall back to + // the wire number like nghttp2's own `nghttp2_strerror` does for unknown codes. other => return format!("NGHTTP2_UNKNOWN_{}", u32::from(other)), } .to_string() @@ -43,9 +37,9 @@ pub(crate) enum H2ErrorShape { RemoteGoAway { code: u32 }, /// A `RST_STREAM` frame received from the peer (stream-level failure). RemoteReset { reason: h2::Reason }, - /// An h2 library-detected protocol violation (e.g. an HTTP/1.1 answer at - /// a prior-knowledge peer surfaces as a locally-initiated GOAWAY with the - /// frame-size reason); bun surfaces these as its generic protocol error. + /// An h2 library-detected protocol violation (e.g. an HTTP/1.1 answer at a prior-knowledge peer + /// surfaces as a locally-initiated GOAWAY with the frame-size reason); bun surfaces these as + /// its generic protocol error. LibraryViolation { reason: h2::Reason }, /// A stream/socket failure (peer reset or close at the TCP layer). Io, @@ -53,9 +47,8 @@ pub(crate) enum H2ErrorShape { Other, } -/// The observable shape of an h2 error: what initiated it (remote frame vs -/// local detection vs socket) and its reason code, which decides the -/// TS-visible failure detail. +/// The observable shape of an h2 error: what initiated it (remote frame vs local detection vs +/// socket) and its reason code, which decides the TS-visible failure detail. pub(crate) fn h2_error_shape(error: &h2::Error) -> H2ErrorShape { if error.is_go_away() { if error.is_remote() { @@ -87,8 +80,7 @@ pub(crate) fn h2_error_shape(error: &h2::Error) -> H2ErrorShape { H2ErrorShape::Other } -/// The failure detail a shape composes (see the TS evidence in -/// `stream_failure::h2_failure_text`). +/// The failure detail a shape composes (see the TS evidence in `stream_failure::h2_failure_text`). pub(crate) fn classify_h2_shape(shape: &H2ErrorShape) -> H2Failure { match shape { H2ErrorShape::RemoteGoAway { code } => H2Failure::SessionClosed { code: *code }, @@ -105,8 +97,8 @@ pub(crate) fn classify_h2_error(error: &h2::Error) -> H2Failure { classify_h2_shape(&h2_error_shape(error)) } -/// Walk an error's source chain for the embedded `h2::Error` (reqwest wraps -/// it in a `hyper::Error`, which the provider plumbing does not name). +/// Walk an error's source chain for the embedded `h2::Error` (reqwest wraps it in a `hyper::Error`, +/// which the provider plumbing does not name). pub(crate) fn h2_error_from_chain<'a>( mut error: &'a (dyn std::error::Error + 'static), ) -> Option<&'a h2::Error> { @@ -118,9 +110,9 @@ pub(crate) fn h2_error_from_chain<'a>( } } -/// The failure detail behind a reqwest transport error. When no h2 detail is -/// reachable (raw TLS/socket failure), the stream failed at the socket: the -/// TS h2 transport surfaces that as a canceled pending stream. +/// The failure detail behind a reqwest transport error. When no h2 detail is reachable (raw +/// TLS/socket failure), the stream failed at the socket: the TS h2 transport surfaces that as a +/// canceled pending stream. pub(crate) fn classify_reqwest_error(error: &reqwest::Error) -> H2Failure { match h2_error_from_chain(error) { Some(h2_error) => classify_h2_error(h2_error), @@ -163,8 +155,8 @@ mod tests { nghttp2_code: "NGHTTP2_INTERNAL_ERROR".to_string() } ); - // An h2 library violation (HTTP/1.1 answer at a prior-knowledge - // peer): bun's generic protocol error. + // An h2 library violation (HTTP/1.1 answer at a prior-knowledge peer): bun's generic + // protocol error. assert_eq!( classify_h2_shape(&H2ErrorShape::LibraryViolation { reason: h2::Reason::FRAME_SIZE_ERROR @@ -178,9 +170,8 @@ mod tests { #[test] fn reason_only_errors_classify_as_protocol() { - // A bare `Reason` error (the only constructible h2 shape in tests) - // is neither a remote frame nor an io failure: the generic protocol - // error, like the HTTP/1.1-answer case. + // A bare `Reason` error (the only constructible h2 shape in tests) is neither a remote + // frame nor an io failure: the generic protocol error, like the HTTP/1.1-answer case. let error = h2::Error::from(h2::Reason::INTERNAL_ERROR); assert_eq!(classify_h2_error(&error), H2Failure::Protocol); } diff --git a/crates/pa-ai/src/utils_inner/hash.rs b/crates/pa-ai/src/utils_inner/hash.rs index ed1b3e691eb..4b331e9ba6d 100644 --- a/crates/pa-ai/src/utils_inner/hash.rs +++ b/crates/pa-ai/src/utils_inner/hash.rs @@ -1,5 +1,4 @@ -//! Short deterministic hash used for tool-call id normalization. -//! Ported from `packages/ai/src/utils/hash.ts` (must match TS output exactly). +//! Short deterministic hash used for tool-call id normalization (must match TS output exactly). #[allow(dead_code)] // used by tool-call id normalization in upcoming providers pub fn short_hash(input: &str) -> String { diff --git a/crates/pa-ai/src/utils_inner/headers.rs b/crates/pa-ai/src/utils_inner/headers.rs index ff64269b683..d6fbaecc070 100644 --- a/crates/pa-ai/src/utils_inner/headers.rs +++ b/crates/pa-ai/src/utils_inner/headers.rs @@ -1,4 +1,4 @@ -//! Header helpers. Ported from `packages/ai/src/utils/headers.ts`. +//! Header helpers. /// Convert a header map into a plain record with lowercase keys. #[allow(dead_code)] // SDK header conversion for upcoming providers diff --git a/crates/pa-ai/src/utils_inner/http.rs b/crates/pa-ai/src/utils_inner/http.rs index 5dae3e0bd93..99f62d62010 100644 --- a/crates/pa-ai/src/utils_inner/http.rs +++ b/crates/pa-ai/src/utils_inner/http.rs @@ -1,10 +1,7 @@ -//! Minimal async HTTP client plumbing for providers. -//! -//! Providers in the TS reference go through SDK clients configured with -//! `maxRetries: 0`; here each provider issues one streaming HTTP request -//! through a shared `reqwest` client. Aborts are surfaced as -//! [`ProviderError::Aborted`]; HTTP failures as [`ProviderError::Http`]; -//! request-send failures as [`ProviderError::Connection`]. +//! Minimal async HTTP client plumbing for providers: one streaming HTTP request through a shared +//! `reqwest` client (TS SDKs run `maxRetries: 0`). Aborts surface as [`ProviderError::Aborted`]; +//! HTTP failures as [`ProviderError::Http`]; request-send failures as +//! [`ProviderError::Connection`]. use std::sync::OnceLock; @@ -18,10 +15,8 @@ use crate::utils::stream_failure::{ static CLIENT: OnceLock = OnceLock::new(); static H2_ALPN_CLIENT: OnceLock = OnceLock::new(); -/// The HTTP/1.1 client every provider shares (the transport all TS SDK -/// clients but bedrock's default `NodeHttp2Handler` speak). Pinned with -/// `http1_only()` so that enabling the reqwest `http2` feature (bedrock) -/// cannot change the transport of any other provider. +/// The HTTP/1.1 client every provider shares, pinned with `http1_only()` so that enabling the +/// reqwest `http2` feature (bedrock) cannot change the transport of any other provider. fn client() -> &'static reqwest::Client { CLIENT.get_or_init(|| { reqwest::Client::builder() @@ -32,11 +27,8 @@ fn client() -> &'static reqwest::Client { }) } -/// The TLS-ALPN client for bedrock https endpoints: HTTP/2 preferred -/// (ALPN-negotiated), like the TS default transport. Cleartext bedrock -/// endpoints do not go through reqwest at all — the bedrock provider -/// drives h2c prior-knowledge HTTP/2 directly there (see -/// `providers/bedrock/h2.rs`). +/// The TLS-ALPN client for bedrock https endpoints: HTTP/2 preferred (ALPN-negotiated), like the TS +/// default transport; cleartext bedrock endpoints go through `providers/bedrock/h2.rs` instead. fn h2_alpn_client() -> &'static reqwest::Client { H2_ALPN_CLIENT.get_or_init(|| { reqwest::Client::builder() @@ -61,8 +53,8 @@ pub struct HttpResponse { pub headers: std::collections::HashMap, body: reqwest::Response, signal: Option, - /// The request's connection-error profile: body-read failures on the AWS - /// http2 profile surface the TS bedrock transport's mid-stream texts. + /// The request's connection-error profile: body-read failures on the AWS http2 profile surface + /// the TS bedrock transport's mid-stream texts. pub(crate) connection: ConnectionErrorProfile, } @@ -121,10 +113,9 @@ impl HttpResponse { } } - /// Classify a body-read failure. The AWS bedrock http2 profile surfaces - /// the TS transport's mid-stream failure texts (the event-stream reader - /// fails, so the AWS SDK appends its deserialization hint); every other - /// provider keeps the generic body-read error. + /// Classify a body-read failure: the AWS bedrock http2 profile surfaces the TS transport's + /// mid-stream texts (the AWS SDK appends its deserialization hint); every other provider keeps + /// the generic body-read error. fn body_error(&self, error: &reqwest::Error) -> ProviderError { if let ConnectionErrorProfile::AwsHttp2 { .. } = self.connection { let failure = crate::utils_inner::h2_classify::classify_reqwest_error(error); @@ -163,12 +154,11 @@ pub struct RequestOptions { pub body: Option, pub signal: Option, pub timeout_ms: Option, - /// The provider family's connection-error shape (fixed texts, names, - /// and error codes the TS binary surfaces per SDK); the openai/anthropic - /// `Sdk` default covers the Stainless-generated SDK family. + /// The provider family's connection-error shape (fixed texts, names, and error codes the TS + /// binary surfaces per SDK); the openai/anthropic `Sdk` default covers the Stainless-generated + /// SDK family. pub connection: ConnectionErrorProfile, - /// The wire transport (HTTP/1.1 by default; bedrock https requests use - /// ALPN-negotiated HTTP/2). + /// The wire transport (HTTP/1.1 by default; bedrock https requests use ALPN-negotiated HTTP/2). pub transport: Transport, } @@ -188,9 +178,8 @@ impl RequestOptions { } } -/// Issue a request and return the response with a streaming body. No retries: -/// retry ownership lives with the caller (agent layer), matching the TS -/// `maxRetries: 0` client configuration. +/// Issue a request and return the response with a streaming body. No retries: retry ownership lives +/// with the caller (agent layer), matching the TS `maxRetries: 0` client configuration. pub async fn send(request: RequestOptions) -> Result { let signal = request.signal.clone(); if signal @@ -250,27 +239,25 @@ pub async fn send(request: RequestOptions) -> Result send_future.await, }; - // The TS SDKs surface request-send failures as their fixed connection - // error texts: the openai/anthropic SDK family throws - // `APIConnectionError` ("Connection error.") / `APIConnectionTimeoutError` - // ("Request timed out.") for every fetch failure; providers whose SDK - // appends the raw cause (mistral) or surfaces undici's raw text (codex, - // bedrock, google: "fetch failed") rewrite it at their catch site. + // The TS SDKs surface request-send failures as their fixed connection error texts: the + // openai/anthropic SDK family throws `APIConnectionError` ("Connection error.") / + // `APIConnectionTimeoutError` ("Request timed out.") for every fetch failure; providers whose + // SDK appends the raw cause (mistral) or surfaces undici's raw text (codex, bedrock, google: + // "fetch failed") rewrite it at their catch site. let response = response.map_err(|error| { let kind = if error.is_timeout() { ConnectionErrorKind::Timeout } else if error.is_connect() { ConnectionErrorKind::Connect } else if matches!(request.connection, ConnectionErrorProfile::AwsHttp2 { .. }) { - // Pre-response http2 failure on the bedrock https transport: the - // h2 failure detail (no deserialization hint — no response yet). + // Pre-response http2 failure on the bedrock https transport: the h2 failure detail (no + // deserialization hint — no response yet). ConnectionErrorKind::H2Request(crate::utils_inner::h2_classify::classify_reqwest_error( &error, )) } else { - // The peer closed or reset after the connection was established - // but before the response arrived (only distinguishable from - // refused connects on the AWS handler surfaces). + // The peer closed or reset after the connection was established but before the response + // arrived (only distinguishable from refused connects on the AWS handler surfaces). ConnectionErrorKind::Reset }; ProviderError::Connection(ProviderConnectionError { diff --git a/crates/pa-ai/src/utils_inner/json_parse.rs b/crates/pa-ai/src/utils_inner/json_parse.rs index 929e3a8d98b..a83fe51f95f 100644 --- a/crates/pa-ai/src/utils_inner/json_parse.rs +++ b/crates/pa-ai/src/utils_inner/json_parse.rs @@ -1,9 +1,7 @@ -//! JSON parsing with repair and partial (streaming) tolerance. -//! Ported from `packages/ai/src/utils/json-parse.ts`. The partial parser -//! reproduces the semantics of the npm `partial-json` package used by the TS -//! reference: return the longest usable prefix of truncated JSON (truncated -//! strings keep their content, truncated containers are closed, incomplete -//! keys/values are dropped), and fail only on genuinely invalid input. +//! JSON parsing with repair and partial (streaming) tolerance. The partial parser reproduces the +//! npm `partial-json` semantics used by the TS reference: the longest usable prefix of truncated +//! JSON (truncated strings keep their content, truncated containers are closed, incomplete +//! keys/values are dropped), failing only on genuinely invalid input. use std::fmt::Write as _; @@ -100,9 +98,8 @@ pub fn repair_json(json: &str) -> String { /// /// # Errors /// -/// Returns the original parse error when the text stays invalid after repair -/// (including when the repair leaves it unchanged), otherwise the parse error -/// of the repaired text. +/// Returns the original parse error when the text stays invalid after repair (including when the +/// repair leaves it unchanged), otherwise the parse error of the repaired text. pub fn parse_json_with_repair(json: &str) -> Result { match serde_json::from_str::(json) { Ok(value) => Ok(value), @@ -121,20 +118,17 @@ pub fn parse_json_with_repair(json: &str) -> Result { pub enum ParseError { /// Genuinely invalid JSON (not just truncated). Invalid, - /// Input ended in the middle of a literal or container member: the member - /// is unusable but the enclosing prefix is recoverable. + /// Input ended in the middle of a literal or container member: the member is unusable but the + /// enclosing prefix is recoverable. Truncated, } -/// Tolerant partial-JSON parser. `Ok` means a usable value was recovered -/// (possibly a partial one); `Err(ParseError::Invalid)` means the input is not -/// parseable JSON even with truncation tolerance. +/// Tolerant partial-JSON parser. `Ok` means a usable value was recovered (possibly a partial one); +/// `Err(ParseError::Invalid)` means the input is not parseable JSON even with truncation tolerance. /// /// # Errors /// -/// Returns `Err(ParseError::Invalid)` when the input is not usable even with -/// truncation tolerance: a truncated top-level literal, malformed input, or -/// trailing non-whitespace after the recovered value. +/// Returns `Err(ParseError::Invalid)` when the input is not usable even with truncation tolerance. pub fn parse_partial_json(input: &str) -> Result { let mut parser = PartialParser { chars: input.chars().collect(), @@ -196,8 +190,8 @@ impl PartialParser { for expected in literal_chars { match self.bump() { Some(actual) if actual == expected => {} - // Truncated literal at EOF: the value is dropped, but the - // enclosing container prefix remains usable. + // Truncated literal at EOF: the value is dropped, but the enclosing container + // prefix remains usable. None => return Err(ParseError::Truncated), Some(_) => return Err(ParseError::Invalid), } @@ -212,7 +206,6 @@ impl PartialParser { } let text: String = self.chars[start..self.pos].iter().collect(); let mut candidate = text.as_str(); - // Take the longest prefix that is a valid JSON number. while !candidate.is_empty() { if serde_json::from_str::(candidate).is_ok() { break; @@ -231,17 +224,15 @@ impl PartialParser { return Err(ParseError::Invalid); } let number = serde_json::from_str::(candidate).map_err(|_| ParseError::Invalid)?; - // When the number was truncated mid-literal ("12.", "1e"), consume the - // whole fragment so the trailing remainder is treated as truncation - // rather than invalid trailing input. + // When the number was truncated mid-literal ("12.", "1e"), consume the whole fragment so + // the trailing remainder is treated as truncation rather than invalid trailing input. self.pos = if candidate.len() == text.len() { start + candidate.len() } else { start + text.len() }; - // Keep integers as integers so partial parses compare equal to the - // strict-JSON representation (the npm partial-json package produces - // JS numbers, which are indistinguishable between 12 and 12.0). + // Keep integers as integers so partial parses compare equal to the strict-JSON + // representation (JS numbers are indistinguishable between 12 and 12.0). if !candidate.contains('.') && !candidate.contains('e') && !candidate.contains('E') { if let Ok(int) = candidate.parse::() { return Ok(Value::Number(int.into())); @@ -252,10 +243,9 @@ impl PartialParser { )) } - /// Parse a string. Returns the content plus whether the closing quote was - /// seen (false when EOF truncated the string). + /// Parse a string. Returns the content plus whether the closing quote was seen (false when EOF + /// truncated the string). fn parse_string(&mut self) -> Result<(String, bool), ParseError> { - // Consume opening quote. self.bump(); let mut out = String::new(); loop { @@ -418,9 +408,8 @@ impl PartialParser { Some(_) => return Err(ParseError::Invalid), } - // Key: on EOF inside the key string the pair is dropped. - // parse_string never fails on truncation, only on invalid - // escape sequences inside the key. + // Key: on EOF inside the key string the pair is dropped. parse_string never fails on + // truncation, only on invalid escape sequences inside the key. let Ok((key, key_closed)) = self.parse_string() else { return Err(ParseError::Invalid); }; @@ -463,8 +452,8 @@ impl PartialParser { } } -/// Attempts to parse potentially incomplete JSON during streaming. -/// Always returns a valid object, even if the JSON is incomplete. +/// Attempts to parse potentially incomplete JSON during streaming. Always returns a valid object, +/// even if the JSON is incomplete. #[must_use] pub fn parse_streaming_json(partial_json: Option<&str>) -> Value { let Some(partial_json) = partial_json else { @@ -489,18 +478,15 @@ pub fn parse_streaming_json(partial_json: Option<&str>) -> Value { const EAGER_PARSE_LENGTH: usize = 8 * 1024; -/// Streamed tool-call argument JSON with a best-effort parsed preview (port of -/// the TS `StreamingJsonAccumulator`). +/// Streamed tool-call argument JSON with a best-effort parsed preview. /// -/// Re-parsing the whole buffer on every delta is quadratic in the argument -/// size, so past `EAGER_PARSE_LENGTH` the preview is refreshed only after the -/// buffer grew by 1/16 since the last parse, keeping total parse work linear. -/// Callers still parse `text` with [`parse_streaming_json`] when the block -/// ends. +/// Re-parsing the whole buffer on every delta is quadratic, so past `EAGER_PARSE_LENGTH` the +/// preview is refreshed only after the buffer grew by 1/16. Callers still parse `text` with +/// [`parse_streaming_json`] when the block ends. pub struct StreamingJsonAccumulator { text: String, - /// Buffer length in UTF-16 code units, the metric of the TS reference - /// (`String::length`); maintained incrementally so `append` stays O(delta). + /// Buffer length in UTF-16 code units, the metric of the TS reference (`String::length`); + /// maintained incrementally so `append` stays O(delta). len_utf16: usize, parsed_length: usize, } @@ -521,22 +507,21 @@ impl StreamingJsonAccumulator { &self.text } - /// Appends a delta and returns a fresh partial parse, or `None` while the - /// refresh is throttled (the caller keeps the previous preview). + /// Appends a delta and returns a fresh partial parse, or `None` while the refresh is throttled + /// (the caller keeps the previous preview). pub fn append(&mut self, delta: &str) -> Option { self.text.push_str(delta); self.len_utf16 += delta.chars().map(char::len_utf16).sum::(); let length = self.len_utf16; - // `length - parsed_length < parsed_length / 16` (the TS float - // comparison) in exact integer form. + // `length - parsed_length < parsed_length / 16` in exact integer form. if length > EAGER_PARSE_LENGTH && 16 * (length - self.parsed_length) < self.parsed_length { return None; } Some(self.parse()) } - /// Parses text not covered by the last returned parse; `None` when the - /// preview is already current. + /// Parses text not covered by the last returned parse; `None` when the preview is already + /// current. pub fn flush(&mut self) -> Option { (self.parsed_length != self.len_utf16).then(|| self.parse()) } @@ -625,8 +610,8 @@ mod tests { fn accumulator_keeps_exact_live_parse_while_small() { let mut acc = StreamingJsonAccumulator::default(); assert_eq!(acc.flush(), None); - // `\q` is an invalid escape and the raw newline is invalid JSON: the - // preview must still track the repaired partial parse exactly. + // `\q` is an invalid escape and the raw newline is invalid JSON: the preview must still + // track the repaired partial parse exactly. let text = concat!( r#"{"command":"say \"hi\"","note":"bad \q escape","#, r#""multi":"line"#, @@ -652,8 +637,8 @@ mod tests { parses += 1; last_parsed_length = acc.text().len(); } else { - // The ASCII payload makes byte length equal the TS - // `text.length` (UTF-16 code units). + // The ASCII payload makes byte length equal the TS `text.length` (UTF-16 code + // units). assert!(acc.text().len() - last_parsed_length < last_parsed_length / 16 + 1); } } @@ -662,15 +647,13 @@ mod tests { assert_eq!(acc.flush(), None); } - // Benchmark, not a CI test: measures the throttled accumulator against - // the pre-PR per-delta reparse. Run with: - // cargo test -p pa-ai --release accumulator_benchmark -- --ignored --nocapture + // Benchmark, not a CI test: the throttled accumulator vs the per-delta whole-buffer reparse. + // Run with: cargo test -p pa-ai --release accumulator_benchmark -- --ignored --nocapture #[test] #[ignore = "benchmark; see the comment above for the run command"] fn accumulator_benchmark_10k_deltas() { - // Synthetic tool-call arguments through a 10k-delta stream: the - // per-delta whole-buffer reparse (pre-PR behavior) vs the - // growth-throttled accumulator. + // Synthetic tool-call arguments through a 10k-delta stream: the per-delta whole-buffer + // reparse vs the growth-throttled accumulator. let payload = format!( r#"{{"content":"{}","path":"/tmp/stream.json"}}"#, "x".repeat(150 * 1024) diff --git a/crates/pa-ai/src/utils_inner/log.rs b/crates/pa-ai/src/utils_inner/log.rs index 5d7b4360541..f3342c4f1ca 100644 --- a/crates/pa-ai/src/utils_inner/log.rs +++ b/crates/pa-ai/src/utils_inner/log.rs @@ -1,6 +1,5 @@ -//! Minimal structured logger shared by pa-ai and its consumers. -//! Ported from `packages/ai/src/log.ts`: entries go to an injectable sink; the -//! library never writes files and logging must never throw into the caller. +//! Minimal structured logger shared by pa-ai and its consumers: entries go to an injectable sink; +//! the library never writes files and logging must never throw into the caller. use std::sync::RwLock; @@ -90,8 +89,8 @@ fn iso_timestamp() -> String { fn civil_from_days(z: i64) -> (i64, u32, u32) { let z = z + 719_468; let era = if z >= 0 { z } else { z - 146_096 } / 146_097; - // Howard Hinnant's algorithm: the era remainder is 0..=146_096, the year - // of era 0..=399, day 1..=31, and month 1..=12 for any input day count. + // Howard Hinnant's algorithm: the era remainder is 0..=146_096, the year of era 0..=399, day + // 1..=31, and month 1..=12 for any input day count. let doe = u64::try_from(z - era * 146_097).expect("day of era is 0..=146_096"); let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146_096) / 365; let y = i64::try_from(yoe).expect("year of era is 0..=399") + era * 400; diff --git a/crates/pa-ai/src/utils_inner/overflow.rs b/crates/pa-ai/src/utils_inner/overflow.rs index 7ebb408f287..1762b0fe1f1 100644 --- a/crates/pa-ai/src/utils_inner/overflow.rs +++ b/crates/pa-ai/src/utils_inner/overflow.rs @@ -1,6 +1,4 @@ -//! Context overflow detection. -//! Ported from `packages/ai/src/utils/overflow.ts`, including the provider -//! pattern table and the silent-overflow heuristics. +//! Context overflow detection: the provider pattern table and the silent-overflow heuristics. use regex::Regex; use std::sync::OnceLock; @@ -58,10 +56,9 @@ fn non_overflow_patterns() -> &'static Vec { /// Check if an assistant message represents a context overflow error. /// -/// Handles error-based overflow (`stop_reason` "error" with a pattern-matching -/// message), silent overflow (usage.input exceeds the context window while the -/// stream reported success), and length-stop overflow (server truncates input, -/// returns `stop_reason` "length" with zero output). +/// Handles error-based overflow (`stop_reason` "error" with a pattern-matching message), silent +/// overflow (usage.input exceeds the context window while the stream reported success), and +/// length-stop overflow (server truncates input, returns `stop_reason` "length" with zero output). #[must_use] pub fn is_context_overflow(message: &AssistantMessage, context_window: Option) -> bool { if message.stop_reason == StopReason::Error { @@ -87,8 +84,8 @@ pub fn is_context_overflow(message: &AssistantMessage, context_window: Option String { text.to_string() diff --git a/crates/pa-ai/src/utils_inner/sse.rs b/crates/pa-ai/src/utils_inner/sse.rs index 54977b60ca1..a4bcd0d241b 100644 --- a/crates/pa-ai/src/utils_inner/sse.rs +++ b/crates/pa-ai/src/utils_inner/sse.rs @@ -1,8 +1,7 @@ //! Server-sent event decoding shared by streaming providers. //! -//! Mirrors the SSE decoder from the Anthropic provider in the TS reference: -//! handles \n, \r\n and \r line breaks, comment lines, `event:`/`data:` fields -//! and multi-line data, flushing on blank lines and at end-of-stream. +//! Mirrors the TS SSE decoder: \n, \r\n and \r line breaks, comment lines, `event:`/`data:` fields +//! and multi-line data, blank-line/EOF flush. #[derive(Debug, Clone, PartialEq, Eq)] pub struct ServerSentEvent { diff --git a/crates/pa-ai/src/utils_inner/stream_failure.rs b/crates/pa-ai/src/utils_inner/stream_failure.rs index d3e74891c92..d61017d99d5 100644 --- a/crates/pa-ai/src/utils_inner/stream_failure.rs +++ b/crates/pa-ai/src/utils_inner/stream_failure.rs @@ -1,7 +1,6 @@ //! Shared classification and reporting for provider stream failures, so no //! provider collapses a specific cause (refusal, safety filter, overload, ...) //! into a generic string before it is logged and persisted. -//! Ported from `packages/ai/src/utils/stream-failure.ts`. use std::fmt::Write as _; @@ -19,11 +18,8 @@ use crate::utils::diagnostics::{ pub enum StreamFailureKind { Refusal, Safety, - /// A payment/balance rejection (HTTP 402): the account or team wallet - /// cannot fund the request. Deterministic by status — a wallet drain - /// does not refill inside a retry ladder, so the status classifies - /// before any body-text pattern (the 402 diagnosis: the same incident - /// must not fork on the response body's `error.type` text). + /// A payment/balance rejection (HTTP 402), deterministic by status (credits do not refill + /// inside a retry ladder). PaymentRequired, Overloaded, RateLimit, @@ -79,7 +75,6 @@ impl StreamFailureInfo { } } -/// A stream failure carrying structured classification info. #[derive(Debug, Clone, PartialEq)] pub struct StreamFailureError { pub message: String, @@ -94,83 +89,61 @@ impl std::fmt::Display for StreamFailureError { impl std::error::Error for StreamFailureError {} -/// Connection-level transport failure kinds: connect failures, request -/// timeouts, and the post-connection transport failures (AWS handler -/// surfaces: http1 reset, http2 stream/session/protocol failures). #[derive(Debug, Clone, PartialEq, Eq)] pub enum ConnectionErrorKind { /// The transport could not be established (refused, unreachable, DNS). Connect, - /// The request exceeded its configured deadline. Timeout, - /// The peer closed or reset the connection before a response arrived. - /// For the AWS http1 handler surface this is node's `read ECONNRESET`. + /// The peer closed or reset the connection before a response arrived. For the AWS http1 handler + /// surface this is node's `read ECONNRESET`. Reset, - /// An http2-level failure before any response arrived (bedrock's default - /// transport): the `H2Failure` text without the deserialization hint. + /// An http2-level failure before any response arrived (bedrock's default transport): the + /// `H2Failure` text without the deserialization hint. H2Request(H2Failure), - /// An http2-level failure inside a received response body (bedrock's - /// default transport): the AWS SDK's event-stream reader fails, so the - /// message carries its deserialization hint. + /// An http2-level failure inside a received response body (bedrock's default transport): the + /// AWS SDK's event-stream reader fails, so the message carries its deserialization hint. H2MidStream(H2Failure), } -/// The http2 transport failure detail, with the byte-exact user-facing text -/// the TS bedrock client (bun's node:http2 behind the AWS SDK's -/// `NodeHttp2Handler`) surfaces for it. Verified against the TS binary by the -/// provider-error probe. +/// The http2 transport failure detail, with the byte-exact user-facing text the TS bedrock client +/// surfaces (bun's node:http2 behind the AWS SDK's `NodeHttp2Handler`). #[derive(Debug, Clone, PartialEq, Eq)] pub enum H2Failure { - /// A `RST_STREAM` received from the peer: "Stream closed with error code - /// NGHTTP2_" with the nghttp2 name of the carried code. + /// A `RST_STREAM` received from the peer. StreamReset { nghttp2_code: String }, - /// A GOAWAY received from the peer: "Session closed with error code N" - /// with the numeric code. + /// A GOAWAY received from the peer. SessionClosed { code: u32 }, - /// A stream/socket failure (peer reset or closed mid-stream): - /// "The pending stream has been canceled". + /// A stream/socket failure: peer reset or closed mid-stream. Canceled, - /// Any other http2 protocol violation (e.g. an HTTP/1.1 answer at a - /// prior-knowledge h2 peer): "Protocol error". + /// Any other http2 protocol violation (e.g. an HTTP/1.1 answer at a prior-knowledge h2 peer). Protocol, } -/// Connection-error shapes per provider family, verified against the TS -/// binary (0.9.5, refused-connect probes): each family surfaces a fixed -/// text and records a fixed diagnostic `error.name` / `err.code`. +/// Connection-error shapes per provider family: each family surfaces a fixed text and records a +/// fixed diagnostic `error.name` / `err.code` (TS-binary verified). #[derive(Debug, Clone, PartialEq, Eq)] pub enum ConnectionErrorProfile { - /// The openai/anthropic SDK family (openai-completions, - /// openai-responses, azure, anthropic): the SDK's fixed texts - /// ("Connection error." / "Request timed out.") and a plain `Error` - /// name with no error code. + /// The openai/anthropic SDK family (openai-completions, openai-responses, azure, anthropic): a + /// plain `Error` name with no error code. Sdk, - /// Raw `fetch` providers (openai-codex-responses, google): the - /// runtime's own error text (bun's refused-connect message), `TypeError` - /// name, `ConnectionRefused` code. + /// Raw `fetch` providers (openai-codex-responses, google): the runtime's own error text. RawFetch, /// The mistral SDK's `UnexpectedClientError` wrapper shape. MistralSdk, - /// The AWS node/http1 handler: the node `connect ECONNREFUSED - /// :` text with the `ECONNREFUSED` code — the TS - /// `AWS_BEDROCK_FORCE_HTTP1` surface (and the proxy-env handler mode). - /// A peer close before the response is node's `read ECONNRESET` - /// (`TimeoutError` name, TS-binary verified). + /// The AWS node/http1 handler: the TS `AWS_BEDROCK_FORCE_HTTP1` surface (and the proxy-env + /// handler mode). AwsHttp1 { host: String, port: u16 }, - /// The AWS `NodeHttp2Handler` surface — the TS default bedrock transport - /// (http2 with h2c prior knowledge over cleartext): the bun node:http2 - /// failure texts and `ERR_HTTP2_*` codes, TS-binary verified. + /// The AWS `NodeHttp2Handler` surface — the TS default bedrock transport (h2c prior knowledge + /// over cleartext), TS-binary verified. AwsHttp2 { host: String, port: u16 }, } -/// The AWS SDK's deserialization hint the TS binary appends to failures -/// inside a received response body (the event-stream reader has a response -/// to lose). Byte-exact, TS-binary verified. +/// The AWS SDK's deserialization hint the TS binary appends to failures inside a received response +/// body. pub const AWS_DESERIALIZATION_HINT: &str = "\n Deserialization error: to see the raw response, inspect the hidden field {error}.$response on this object."; -/// The base failure text of an http2 transport failure (without the -/// deserialization hint). +/// The base failure text of an http2 transport failure (without the deserialization hint). #[must_use] pub fn h2_failure_text(failure: &H2Failure) -> String { match failure { @@ -183,8 +156,7 @@ pub fn h2_failure_text(failure: &H2Failure) -> String { } } -/// The user-facing failure text, with the AWS SDK deserialization hint for -/// mid-body failures. +/// The user-facing failure text, with the AWS SDK deserialization hint for mid-body failures. #[must_use] pub fn h2_failure_message(failure: &H2Failure, mid_stream: bool) -> String { let mut message = h2_failure_text(failure); @@ -194,8 +166,8 @@ pub fn h2_failure_message(failure: &H2Failure, mid_stream: bool) -> String { message } -/// Errors raised by provider HTTP/SSE plumbing, carrying the raw pieces the TS -/// reference extracts from provider SDK exceptions. +/// Errors raised by provider HTTP/SSE plumbing, carrying the raw pieces the TS reference extracts +/// from provider SDK exceptions. #[derive(Debug, Clone, PartialEq)] pub struct ProviderHttpError { pub message: String, @@ -203,17 +175,14 @@ pub struct ProviderHttpError { pub body: Option, pub headers: std::collections::HashMap, pub request_id: Option, - /// The TS SDK error class name recorded in the `provider_stream_failure` - /// diagnostic (e.g. "`BadRequestError`", "`CodexApiError`", "`SDKError`"); the - /// `ProviderHttpError` internal fallback when unset. + /// The TS SDK error class name recorded in the `provider_stream_failure` diagnostic (e.g. + /// "`BadRequestError`"). pub sdk_name: Option, - /// Server-requested wait already resolved by the provider (Retry-After - /// header, `resets_at` body); overrides header re-parsing, like the TS - /// `err.retryAfterMs` field takes precedence over `parseRetryAfterMs`. + /// Server-requested wait already resolved by the provider (Retry-After header, `resets_at` + /// body); overrides header re-parsing. pub retry_after_ms: Option, - /// The provider error's own wire `code` (TS `err.code`), which the - /// classification prefers over the class name when the body carries no - /// error type. + /// The provider error's own wire `code`, which the classification prefers over the class name + /// when the body carries no error type. pub provider_error_type: Option, } @@ -225,10 +194,8 @@ impl std::fmt::Display for ProviderHttpError { impl std::error::Error for ProviderHttpError {} -/// A connection-level transport failure. `Display` is the user-facing text -/// the TS binary surfaces for the provider's SDK/runtime connection error -/// (fixed strings per provider family, verified against the installed TS -/// binary); the raw `cause` is kept for logging. +/// A connection-level transport failure. `Display` is the fixed per-family user-facing text the TS +/// binary surfaces; the raw `cause` is kept for logging. #[derive(Debug, Clone, PartialEq)] pub struct ProviderConnectionError { pub kind: ConnectionErrorKind, @@ -236,8 +203,8 @@ pub struct ProviderConnectionError { pub cause: String, } -/// The runtime's refused-connect message the TS binary (bun `fetch`) surfaces -/// verbatim on the raw-`fetch` providers (codex, google). +/// The runtime's refused-connect message the TS binary (bun `fetch`) surfaces verbatim on the +/// raw-`fetch` providers (codex, google). pub const RUNTIME_CONNECT_REFUSED_MESSAGE: &str = "Unable to connect. Is the computer able to access the url?"; @@ -245,11 +212,9 @@ impl ProviderConnectionError { /// The user-facing text the TS binary surfaces for this failure. #[must_use] pub fn message(&self) -> String { - // A peer reset before the response carries the same fixed text as the - // connect failure for the raw-fetch/SDK families (the TS binary - // surfaces one per-family connection error; reset-vs-refused is only - // distinguishable on the AWS handler surfaces, which have dedicated - // texts below). + // A peer reset before the response carries the same fixed text as the connect failure for + // the raw-fetch/SDK families; reset-vs-refused is only distinguishable on the AWS handler + // surfaces. match (&self.profile, &self.kind) { ( ConnectionErrorProfile::Sdk, @@ -262,9 +227,8 @@ impl ProviderConnectionError { ConnectionErrorProfile::Sdk | ConnectionErrorProfile::AwsHttp1 { .. }, ConnectionErrorKind::Timeout, ) => "Request timed out.".to_string(), - // Raw `fetch` (bun) and the mistral `RequestTimeoutError` append - // the raw cause to a fixed timeout prefix; the refused-connect - // text is the runtime's own fixed message. + // Raw `fetch` (bun) and the mistral `RequestTimeoutError` append the raw cause to a + // fixed timeout prefix. ( ConnectionErrorProfile::RawFetch, ConnectionErrorKind::Connect @@ -298,20 +262,20 @@ impl ProviderConnectionError { ConnectionErrorKind::H2Request(_) | ConnectionErrorKind::H2MidStream(_), ) => "read ECONNRESET".to_string(), (ConnectionErrorProfile::AwsHttp2 { host, port }, ConnectionErrorKind::Connect) => { - // The refused connect surfaces as a canceled pending stream - // with the node-style connect cause embedded. + // The refused connect surfaces as a canceled pending stream with the node-style + // connect cause embedded. format!( "The pending stream has been canceled (caused by: connect ECONNREFUSED {host}:{port})" ) } (ConnectionErrorProfile::AwsHttp2 { .. }, ConnectionErrorKind::Timeout) => { - // No TS ground truth: the TS client configures no transport - // timeout (NodeHttp2Handler without requestTimeout). + // No TS ground truth: the TS client configures no transport timeout + // (NodeHttp2Handler without requestTimeout). "Request timed out.".to_string() } (ConnectionErrorProfile::AwsHttp2 { .. }, ConnectionErrorKind::Reset) => { - // A pre-response non-connect failure at a cleartext prior- - // knowledge h2 peer (HTTP/1.1 answer): bun's protocol error. + // A pre-response non-connect failure at a cleartext prior- knowledge h2 peer + // (HTTP/1.1 answer): bun's protocol error. "Protocol error".to_string() } (ConnectionErrorProfile::AwsHttp2 { .. }, ConnectionErrorKind::H2Request(failure)) => { @@ -324,8 +288,7 @@ impl ProviderConnectionError { } } - /// The TS runtime/SDK error class name recorded in the - /// `provider_stream_failure` diagnostic. + /// The TS runtime/SDK error class name recorded in the `provider_stream_failure` diagnostic. #[must_use] pub fn error_name(&self) -> &'static str { if matches!(self.profile, ConnectionErrorProfile::RawFetch) { @@ -334,9 +297,8 @@ impl ProviderConnectionError { if matches!(self.profile, ConnectionErrorProfile::MistralSdk) { return "UnexpectedClientError"; } - // bun records the http1 pre-response reset as a TimeoutError - // (TS-binary verified); every other AWS handler failure is a plain - // Error. + // bun records the http1 pre-response reset as a TimeoutError (TS-binary verified); every + // other AWS handler failure is a plain Error. if matches!(self.profile, ConnectionErrorProfile::AwsHttp1 { .. }) && matches!(self.kind, ConnectionErrorKind::Reset) { @@ -345,11 +307,8 @@ impl ProviderConnectionError { "Error" } - /// The TS `err.code` the classification uses as the provider error type - /// (bun's `ConnectionRefused` for raw `fetch`, the SDK class name for - /// mistral, node's `ECONNREFUSED` for the AWS http1 handler and bun's - /// `ERR_HTTP2_*` codes for the AWS http2 handler; the openai/anthropic - /// SDK family records none). + /// The TS `err.code` the classification uses as the provider error type; the openai/anthropic + /// SDK family records none. #[must_use] pub fn error_code(&self) -> Option<&'static str> { match (&self.profile, &self.kind) { @@ -361,8 +320,8 @@ impl ProviderConnectionError { (ConnectionErrorProfile::AwsHttp1 { .. }, ConnectionErrorKind::Reset) => { Some("ECONNRESET") } - // The TS client configures no AWS transport timeout, so there is - // no ground-truth code; the classification records none. + // The TS client configures no AWS transport timeout, so there is no ground-truth code; + // the classification records none. (ConnectionErrorProfile::Sdk, _) | ( ConnectionErrorProfile::AwsHttp1 { .. }, @@ -391,11 +350,8 @@ impl ProviderConnectionError { } } -/// A WebSocket transport failure thrown out of a provider stream (the codex -/// WS path, after events were emitted): `Display` is the raw runtime text -/// (verbatim, like the TS), and the TS `provider_stream_failure` diagnostic -/// records the runtime WS error class name — `WebSocketCloseError` for -/// close events, plain `Error` otherwise — plus the numeric close code. +/// A WebSocket transport failure thrown out of a provider stream (the codex WS path): `Display` is +/// the raw runtime text, verbatim like the TS. #[derive(Debug, Clone, PartialEq, Eq)] pub struct ProviderWsTransportError { pub message: String, @@ -403,8 +359,7 @@ pub struct ProviderWsTransportError { } impl ProviderWsTransportError { - /// The TS runtime/WS error class name recorded in the diagnostic - /// (`error.name`); the close-code presence decides it. + /// The runtime WS error class name recorded in the diagnostic; the close code decides it. #[must_use] pub fn error_name(&self) -> &'static str { match self.close_code { @@ -428,10 +383,9 @@ pub enum ProviderError { StreamFailure(StreamFailureError), Http(ProviderHttpError), Connection(ProviderConnectionError), - /// WebSocket transport failure (codex WS path): raw runtime text plus - /// the TS diagnostic's WS error class name and close code. + /// WebSocket transport failure (codex WS path). Transport(ProviderWsTransportError), - /// Plain error message; classified from its text like unrecognized TS errors. + /// Plain error message; classified from its text. Message(String), Aborted, } @@ -452,17 +406,16 @@ impl std::fmt::Display for ProviderError { impl std::error::Error for ProviderError {} impl ProviderError { - /// Build an HTTP error from a status code and response body, classifying - /// the failure from the body text like the TS `stream-failure.ts` parser. + /// Build an HTTP error from a status code and response body, classifying the failure from the + /// body text. #[must_use] pub fn from_http_status_body( status: u16, body: &str, headers: std::collections::HashMap, ) -> Self { - // The OpenAI SDK surfaces `400 ` as the error message; the - // classification pipeline reads the structured `body` field, and the - // user-facing message is rebuilt from the classified parts. + // The OpenAI SDK surfaces `400 ` as the error message; the user-facing message is + // rebuilt from the classified parts. let message = if body.trim().is_empty() { format!("{status}") } else { @@ -569,21 +522,16 @@ pub fn stream_failure_message(info: &StreamFailureInfo, detail: Option<&str>) -> /// /// # Panics /// -/// Panics only if one of the built-in regex patterns fails to compile; the -/// patterns are static literals, so this never fires in practice. +/// Panics only if one of the built-in regex patterns fails to compile (static literals). #[must_use] pub fn classify_stream_failure( provider_error_type: Option<&str>, status: Option, ) -> StreamFailureKind { let type_lower = provider_error_type.unwrap_or("").to_lowercase(); - // A 402 is a payment failure regardless of the body's `error.type` - // text: gateways surface wallet drains as `insufficient_credits`, - // `insufficient_balance`, `invalid_request_error`, or bare numeric - // codes, and the pre-fix classification forked on exactly that text - // (the same 402 retried as `unknown` or settled permanently as - // `invalid_request` — the silent-arm diagnosis). The status wins: - // credits do not refill inside a retry ladder. + // A 402 is a payment failure regardless of the body's `error.type` text: gateways surface + // wallet drains as `insufficient_credits`, `insufficient_balance`, or bare numeric codes. + // Credits do not refill inside a retry ladder, so the status wins. if status == Some(402) { return StreamFailureKind::PaymentRequired; } @@ -638,8 +586,8 @@ pub fn classify_stream_failure( StreamFailureKind::Unknown } -/// Failure for a stream that terminated with a provider stop/finish reason that -/// maps to "error" (e.g. Anthropic "refusal", Gemini "SAFETY"). +/// Failure for a stream that terminated with a provider stop/finish reason that maps to "error" +/// (e.g. Anthropic "refusal", Gemini "SAFETY"). pub fn stream_failure_from_stop_reason( raw_stop_reason: Option<&str>, request_id: Option<&str>, @@ -717,8 +665,8 @@ const MAX_RAW_LENGTH: usize = 2000; #[must_use] pub fn truncate_raw_payload(raw: &str) -> String { if raw.len() > MAX_RAW_LENGTH { - // Match the TS slice-by-16-bit-code-unit behavior closely enough for - // post-mortem truncation while staying on char boundaries in Rust. + // Match the TS slice-by-16-bit-code-unit behavior closely enough for post-mortem truncation + // while staying on char boundaries in Rust. let mut end = MAX_RAW_LENGTH; while end > 0 && !raw.is_char_boundary(end) { end -= 1; @@ -729,11 +677,6 @@ pub fn truncate_raw_payload(raw: &str) -> String { } } -// The HTTP `retry-after` parsing family lives in the child module -// (stream_failure::http_retry); `parse_retry_after_ms` keeps its `pub` level -// (the pub(crate) re-export serves its external importer) and `header_value` -// gets ONE pub(super) bump (the facade's extract_parts calls); -// `ExtractedParts` re-homes facade-side (its consumer is facade-resident). mod http_retry; use http_retry::header_value; pub(crate) use http_retry::parse_retry_after_ms; @@ -748,8 +691,8 @@ fn extract_parts_from_http(error: &ProviderHttpError) -> ExtractedParts { let mut body_message: Option = None; if let Some(body) = &error.body { if let Ok(parsed) = serde_json::from_str::(body) { - // Error bodies come nested differently per SDK: Anthropic/OpenAI expose - // `error.error = {type|code, message}` (sometimes doubly nested). + // Error bodies come nested differently per SDK: Anthropic/OpenAI expose `error.error = + // {type|code, message}` (sometimes doubly nested). let mut node = &parsed; if let Some(nested) = node.get("error") { if nested.is_object() && nested.get("error").is_some() { @@ -775,15 +718,13 @@ fn extract_parts_from_http(error: &ProviderHttpError) -> ExtractedParts { let header_request_id = header_value(&error.headers, "request-id") .or_else(|| header_value(&error.headers, "x-request-id")); let request_id = error.request_id.clone().or(header_request_id); - // An error-resolved wait (Retry-After vs resets_at maximum) overrides the - // raw header, like the TS `err.retryAfterMs` field takes precedence. + // An error-resolved wait (Retry-After vs resets_at maximum) overrides the raw header. let retry_after_ms = error .retry_after_ms .or_else(|| parse_retry_after_ms(&error.headers)); - // TS `extractStreamFailureParts`: the SDK error's own `code` field and - // then its class `name` stand in for the provider error type when the - // body does not carry one. + // The SDK error's own `code` and then its class `name` stand in for the provider error type + // when the body carries none (TS `extractStreamFailureParts`). let provider_error_type = body_type .or_else(|| error.provider_error_type.clone()) .or_else(|| error.sdk_name.clone()); @@ -818,17 +759,14 @@ pub fn extract_stream_failure_info(error: &ProviderError) -> StreamFailureInfo { match error { ProviderError::StreamFailure(failure) => failure.info.clone(), ProviderError::Http(http) => extract_parts_from_http(http).info, - // The TS connection errors never classify (their names/codes — - // "Error", "TypeError", "UnexpectedClientError", "ConnectionRefused", - // "ECONNREFUSED" — match no kind pattern); the provider error type - // is the recorded err.code (if any). + // TS connection errors never classify (their names/codes match no kind pattern); the + // provider error type is the recorded `err.code`. ProviderError::Connection(connection) => StreamFailureInfo { provider_error_type: connection.error_code().map(str::to_string), ..StreamFailureInfo::unknown() }, - // The TS WS transport errors never classify ("WebSocketCloseError" - // matches no kind pattern); the provider error type is the error's - // class name, like `err.name !== "Error"` in the TS extraction. + // TS WS transport errors never classify; the provider error type is the error's class name, + // like `err.name !== "Error"` in TS. ProviderError::Transport(transport) => StreamFailureInfo { provider_error_type: match transport.error_name() { "Error" => None, @@ -844,18 +782,17 @@ pub fn extract_stream_failure_info(error: &ProviderError) -> StreamFailureInfo { } } -/// User-facing message for a thrown stream error: a classified one-liner with -/// the provider's own short message, never the raw payload/trace. Unrecognized -/// errors pass through verbatim so their text (which downstream retry matching -/// may depend on) is preserved. +/// User-facing message for a thrown stream error: a classified one-liner with the provider's own +/// short message, never the raw payload/trace. Unrecognized errors pass through verbatim so their +/// text (which downstream retry matching may depend on) is preserved. #[must_use] pub fn format_stream_failure_message(error: &ProviderError) -> String { match error { ProviderError::StreamFailure(failure) => failure.message.clone(), ProviderError::Aborted => "Request was aborted".to_string(), ProviderError::Connection(connection) => connection.message(), - // The TS WS transport errors classify as "unknown", so the raw - // runtime text passes through verbatim. + // WS transport errors classify as "unknown", so the raw runtime text passes through + // verbatim. ProviderError::Transport(transport) => transport.message.clone(), ProviderError::Http(http) => { let parts = extract_parts_from_http(http); @@ -876,14 +813,9 @@ pub(crate) fn diagnostic_error_info(error: &ProviderError) -> DiagnosticErrorInf error.to_string(), None, ), - // The TS diagnostic records the provider SDK's error class name - // ("BadRequestError", "APIError", "SDKError", ...); the provider sets - // it where it builds the HTTP error, falling back to the internal - // name for raw plumbing errors. - // The TS Stainless-generated SDK errors (openai, anthropic, azure) - // do not set `error.name`, so JS records the inherited plain "Error"; - // providers whose SDK names the class record it (mistral "SDKError", - // codex "CodexApiError", google "ApiError", AWS exception names). + // The TS diagnostic records the provider SDK's error class name; Stainless-generated SDKs + // (openai, anthropic, azure) do not set `error.name`, so JS records the inherited plain + // "Error". ProviderError::Http(http) => ( Some(http.sdk_name.clone().unwrap_or_else(|| "Error".to_string())), error.to_string(), @@ -894,8 +826,8 @@ pub(crate) fn diagnostic_error_info(error: &ProviderError) -> DiagnosticErrorInf error.to_string(), None, ), - // The TS diagnostic records the runtime WS error class name and, - // for close events, the numeric close code as `error.code`. + // The TS diagnostic records the runtime WS error class name and, for close events, the + // numeric close code as `error.code`. ProviderError::Transport(transport) => ( Some(transport.error_name().to_string()), transport.message.clone(), @@ -919,10 +851,9 @@ pub(crate) fn diagnostic_error_info(error: &ProviderError) -> DiagnosticErrorInf } } -/// Record a terminal stream failure on the message (structured diagnostic that -/// persists to session JSONL) and emit one structured log line. Call from the -/// provider's terminal catch after `stop_reason/error_message` are set; no-op for -/// user-initiated aborts. +/// Record a terminal stream failure on the message (structured diagnostic that persists to session +/// JSONL) and emit one structured log line. Call from the provider's terminal catch after +/// `stop_reason/error_message` are set; no-op for user-initiated aborts. pub fn record_stream_failure( model: (&str, &str, &str), output: &mut AssistantMessage, @@ -963,7 +894,5 @@ pub fn record_stream_failure( ); } -// The inline unit battery lives in the child module (stream_failure::tests); -// its use-super glob resolves through this facade's bindings. #[cfg(test)] mod tests; diff --git a/crates/pa-ai/src/utils_inner/stream_failure/tests.rs b/crates/pa-ai/src/utils_inner/stream_failure/tests.rs index 0084677d3a9..ca96fe0d1a6 100644 --- a/crates/pa-ai/src/utils_inner/stream_failure/tests.rs +++ b/crates/pa-ai/src/utils_inner/stream_failure/tests.rs @@ -57,10 +57,8 @@ fn classifies_provider_error_types() { classify_stream_failure(Some("weird"), None), StreamFailureKind::Unknown ); - // A 402 classifies by status, before any body-text pattern: the - // same wallet drain must not fork on the response body's - // `error.type` text (the silent-arm diagnosis — variant A - // retried 13-15s on a dead wallet, variant B settled silently). + // A 402 classifies by status, before any body-text pattern: the same wallet drain must not fork + // on the response body's `error.type` text. assert_eq!( classify_stream_failure(Some("insufficient_credits"), Some(402)), StreamFailureKind::PaymentRequired @@ -92,8 +90,8 @@ fn builds_user_facing_messages() { } /// The classified shape the anthropic/openai-responses providers surface -/// (`formatStreamFailureMessage`): kind text, parenthesized qualifiers -/// (provider type and/or status), detail after the colon. +/// (`formatStreamFailureMessage`): kind text, parenthesized qualifiers (provider type and/or +/// status), detail after the colon. #[test] fn classified_message_with_parenthesized_status() { let status_only = StreamFailureInfo { @@ -145,9 +143,8 @@ fn parses_retry_after_headers() { assert_eq!(parse_retry_after_ms(&headers), Some(3000)); } -/// Connection-level failures carry the per-family texts the TS binary -/// surfaces (verified by the provider-error probe), never classify, and -/// record the family's `error.name` / `err.code`. +/// Connection-level failures carry the per-family texts the TS binary surfaces (verified by the +/// provider-error probe), never classify, and record the family's `error.name` / `err.code`. #[test] fn connection_error_texts() { let connect = ProviderError::Connection(ProviderConnectionError { @@ -164,14 +161,13 @@ fn connection_error_texts() { assert_eq!(timeout.to_string(), "Request timed out."); // The classified-format providers surface them verbatim too. assert_eq!(format_stream_failure_message(&connect), "Connection error."); - // The classification is unknown, like the TS SDK connection errors, - // and the openai/anthropic family records no error code. + // The classification is unknown, like the TS SDK connection errors, and the openai/anthropic + // family records no error code. assert_eq!( extract_stream_failure_info(&connect), StreamFailureInfo::unknown() ); - // The TS Stainless SDK errors do not set `error.name`: JS records - // the inherited plain "Error". + // The TS Stainless SDK errors do not set `error.name`: JS records the inherited plain "Error". assert_eq!( diagnostic_error_info(&connect).name.as_deref(), Some("Error") @@ -238,10 +234,9 @@ fn connection_error_texts() { ); } -/// The AWS http2 transport failure texts (TS-binary verified, bedrock -/// http2 mode): connect-refused stream cancel, pre-response protocol -/// error, and the mid-stream classes carrying the AWS SDK deserialization -/// hint. +/// The AWS http2 transport failure texts (TS-binary verified, bedrock http2 mode): connect-refused +/// stream cancel, pre-response protocol error, and the mid-stream classes carrying the +/// deserialization hint. #[test] fn aws_http2_transport_texts() { let profile = || ConnectionErrorProfile::AwsHttp2 { @@ -256,8 +251,7 @@ fn aws_http2_transport_texts() { }) }; - // Refused connect: the canceled pending stream embeds the node-style - // connect cause. + // Refused connect: the canceled pending stream embeds the node-style connect cause. let connect = error(ConnectionErrorKind::Connect); assert_eq!( connect.to_string(), @@ -284,8 +278,7 @@ fn aws_http2_transport_texts() { Some("Error") ); - // RST_STREAM mid-body: the nghttp2 code name plus the AWS SDK's - // deserialization hint. + // RST_STREAM mid-body: the nghttp2 code name plus the AWS SDK's deserialization hint. let reset = error(ConnectionErrorKind::H2MidStream(H2Failure::StreamReset { nghttp2_code: "NGHTTP2_INTERNAL_ERROR".to_string(), })); @@ -313,8 +306,8 @@ fn aws_http2_transport_texts() { Some("ERR_HTTP2_SESSION_ERROR") ); - // Socket reset/close mid-body: the canceled pending stream plus the - // hint (no connect cause — the request had already gone out). + // Socket reset/close mid-body: the canceled pending stream plus the hint (no connect cause — + // the request had already gone out). let canceled = error(ConnectionErrorKind::H2MidStream(H2Failure::Canceled)); assert_eq!( canceled.to_string(), @@ -327,9 +320,8 @@ fn aws_http2_transport_texts() { ); } -/// The AWS http1 handler's pre-response reset text (TS-binary verified): -/// node's `read ECONNRESET` recorded under a `TimeoutError` name with the -/// `ECONNRESET` code. +/// The AWS http1 handler's pre-response reset text (TS-binary verified): node's `read ECONNRESET` +/// recorded under a `TimeoutError` name with the `ECONNRESET` code. #[test] fn aws_http1_reset_text() { let reset = ProviderError::Connection(ProviderConnectionError { @@ -350,9 +342,8 @@ fn aws_http1_reset_text() { ); } -/// Mid-stream protocol failures (h2 framing errors inside the body) -/// surface the deserialization hint too, like every failure the AWS -/// SDK's event-stream reader can hit. +/// Mid-stream protocol failures (h2 framing errors inside the body) surface the deserialization +/// hint too, like every failure the AWS SDK's event-stream reader can hit. #[test] fn h2_mid_stream_protocol_hint() { let failure = H2Failure::Protocol; @@ -364,14 +355,13 @@ fn h2_mid_stream_protocol_hint() { assert_eq!(h2_failure_message(&failure, false), "Protocol error"); } -/// The TS `extractStreamFailureParts` fallback chain: a body without an -/// error type takes the SDK error's own class name, and an error-resolved -/// retry wait overrides the raw header. +/// The TS `extractStreamFailureParts` fallback chain: a body without an error type takes the SDK +/// error's own class name, and an error-resolved retry wait overrides the raw header. #[test] fn http_error_name_fallback_and_retry_override() { let error = ProviderError::Http(ProviderHttpError { - // A type-less 429 body, like a google `ApiError` (its error - // `code` is numeric): the qualifiers show the class name. + // A type-less 429 body, like a google `ApiError` (its error `code` is numeric): the + // qualifiers show the class name. message: "429 {\"error\":{\"code\":429}}".to_string(), status: Some(429), body: Some("{\"error\":{\"code\":429}}".to_string()), @@ -393,8 +383,8 @@ fn http_error_name_fallback_and_retry_override() { Some("ApiError") ); - // An explicit `err.code` beats both the body type and the class name, - // and the error-resolved wait beats the header. + // An explicit `err.code` beats both the body type and the class name, and the error-resolved + // wait beats the header. let mut headers = std::collections::HashMap::new(); headers.insert("retry-after".to_string(), "1".to_string()); let error = ProviderError::Http(ProviderHttpError { @@ -419,10 +409,9 @@ fn http_error_name_fallback_and_retry_override() { ); } -/// The google `ApiError` carrier: the class name is the qualifier and -/// the classified form carries no detail (the genai `ApiError` exposes -/// no `.error` object to the TS classifier); unnamed plumbing errors -/// fall back to the plain JS "Error" the Stainless SDK family records. +/// The google `ApiError` carrier: the class name is the qualifier and the classified form carries +/// no detail (the genai `ApiError` exposes no `.error` object to the TS classifier); unnamed +/// plumbing errors fall back to the plain JS "Error" the Stainless SDK family records. #[test] fn http_error_records_sdk_name() { let mut named = ProviderError::from_http_status_body( diff --git a/crates/pa-cli/src/args.rs b/crates/pa-cli/src/args.rs index f14152ae61d..97fad869464 100644 --- a/crates/pa-cli/src/args.rs +++ b/crates/pa-cli/src/args.rs @@ -1,14 +1,13 @@ -//! CLI argument parsing, a faithful port of `cli/args.ts` from the TypeScript -//! product. The parser is intentionally hand-written: `--resume`/`--print` -//! optionally consume the next token and diagnostics carry their own -//! formatting, none of which a stock derive-based parser can express. +//! CLI argument parsing, a faithful port of `cli/args.ts`. The parser is +//! intentionally hand-written: `--resume`/`--print` optionally consume the +//! next token and diagnostics carry their own formatting, none of which a +//! stock derive-based parser can express. use pa_types::ai::ModelThinkingLevel; -/// Supported reasoning-effort levels (`THINKING_LEVELS` in the TS product). +/// Supported reasoning-effort levels. pub const THINKING_LEVELS: [&str; 7] = ["off", "minimal", "low", "medium", "high", "xhigh", "max"]; -/// Parse a thinking level value into the shared pa-types enum. pub fn parse_thinking_level(value: &str) -> Option { match value { "off" => Some(ModelThinkingLevel::Off), @@ -80,7 +79,6 @@ impl Diagnostic { } } -/// Autonomous gate options, mirroring `runtimeAutonomousConfigFromArgs`. #[derive(Debug, Clone, Default, PartialEq, Eq)] pub struct AutonomousGates { pub commands: Vec, @@ -130,7 +128,6 @@ impl AutonomousConfig { } } -/// Parsed CLI arguments, mirroring `Args` in `cli/args.ts`. #[derive(Debug, Clone, Default)] #[allow(clippy::struct_excessive_bools)] // the TS `Args` surface mirrored verbatim pub struct Args { @@ -144,7 +141,6 @@ pub struct Args { pub continue_: bool, /// `true` when `--resume` was given without a selector. pub resume_bare: bool, - /// The `--resume ` value. pub resume: Option, pub help: bool, pub version: bool, @@ -194,10 +190,8 @@ impl Args { } fn parse_positive_u32(value: &str, flag: &str, diagnostics: &mut Vec) -> Option { - // Number() accepts arbitrary precision, so parse as i128 to cover the - // full accepted range before the integer/positivity/range checks. The - // u32::MAX bound is the point of the function: a value past it is a - // user error, never a silent truncation into the flag's u32 field. + // Number() accepts arbitrary precision, so parse as i128; a value past + // u32::MAX is a user error, never a silent truncation. match value.trim().parse::() { Ok(parsed) if parsed > 0 && parsed <= i128::from(u32::MAX) => u32::try_from(parsed).ok(), _ => { @@ -223,7 +217,6 @@ fn parse_positive_u64(value: &str, flag: &str, diagnostics: &mut Vec } } -/// Parse the CLI arguments the same way `parseArgs` in `cli/args.ts` does. pub fn parse_args(args: &[String]) -> Args { let mut result = Args::default(); let internal_runtime_command = @@ -488,8 +481,8 @@ pub fn parse_args(args: &[String]) -> Args { result } -/// `hasRequiredOptionValue` from args.ts: the value flag either consumes the -/// next token or records a "requires a value" error. +/// The value flag either consumes the next token or records a +/// "requires a value" error. fn take_required_value( args: &[String], index: usize, diff --git a/crates/pa-cli/src/client_settings.rs b/crates/pa-cli/src/client_settings.rs index df8f3e62ee9..c875c08cf1c 100644 --- a/crates/pa-cli/src/client_settings.rs +++ b/crates/pa-cli/src/client_settings.rs @@ -1,7 +1,5 @@ -//! The interactive client-settings seam implementation: every call opens -//! the file-backed settings manager over the run's directories (the store -//! is a pair of small JSON files, so the re-read is the same freshness -//! the TS manager's `reload` produces) and applies the one setting. +//! The interactive client-settings seam implementation: every call opens the +//! file-backed settings manager over the run's directories. use anyhow::Result; use std::path::PathBuf; @@ -9,8 +7,7 @@ use std::sync::Arc; use pa_tui::client_settings::ClientSettings; -/// The seam handle the interactive run carries (TS injects the same -/// settings manager into the interactive mode). +/// The seam handle the interactive run carries. #[derive(Clone)] pub struct CliClientSettings { cwd: PathBuf, @@ -61,8 +58,8 @@ impl ClientSettings for CliClientSettings { } fn default_service_tier(&self) -> String { - // The wire name of the persisted default tier (TS - // `getDefaultServiceTier()`), "default" when unset or unreadable. + // The wire name of the persisted default tier; "default" when + // unset or unreadable. serde_json::to_value(self.manager().get_default_service_tier()) .ok() .and_then(|value| value.as_str().map(str::to_string)) @@ -197,7 +194,7 @@ impl ClientSettings for CliClientSettings { ); /// `updateChannel`: the settings enum's wire value; unset reads as - /// `None` (TS's global-only `getUpdateChannel`). + /// `None`. fn update_channel(&self) -> Option { let channel = self.manager().get_update_channel()?; Some( @@ -267,9 +264,7 @@ impl ClientSettings for CliClientSettings { mod tests { use super::*; - /// The seam over the real settings store: every write persists through - /// the pa-core manager and the next read (a fresh manager over the same - /// dirs, exactly what every call does) sees it. + /// The seam over the real pa-core settings store. #[test] fn seam_round_trips_through_the_settings_store() { let dir = tempfile::TempDir::new().expect("temp dir"); @@ -277,7 +272,6 @@ mod tests { std::fs::create_dir_all(&agent_dir).expect("agent dir"); let settings = CliClientSettings::new(dir.path().to_path_buf(), agent_dir.clone()); - // The TS defaults read first. assert!(settings.show_images()); assert!(!settings.quiet_startup()); assert_eq!(settings.idle_eviction_minutes(), "90"); @@ -285,7 +279,6 @@ mod tests { assert_eq!(settings.tree_filter_mode(), "user-only"); assert!(settings.warnings_anthropic_extra_usage()); - // Writes persist (the settings file lands in the agent dir). settings.set_theme("dark").expect("theme"); settings.set_idle_eviction_minutes("off").expect("idle"); settings.set_tree_filter_mode("all").expect("tree filter"); @@ -296,7 +289,6 @@ mod tests { assert_eq!(settings.tree_filter_mode(), "all"); assert!(!settings.show_images()); - // The persisted file the real consumers read. let content = std::fs::read_to_string(agent_dir.join("settings.json")).expect("settings file"); let value: serde_json::Value = serde_json::from_str(&content).expect("parse"); diff --git a/crates/pa-cli/src/client_traces.rs b/crates/pa-cli/src/client_traces.rs index ea3646c6c02..661b47a148f 100644 --- a/crates/pa-cli/src/client_traces.rs +++ b/crates/pa-cli/src/client_traces.rs @@ -1,9 +1,5 @@ -//! The composition root's `/traces` state and engine (TS -//! `getAgentTracesEnabled` / `setAgentTracesEnabled`, -//! `getPrimeAgentTraceCredential`, and `core/agent-traces.ts`'s upload -//! arms): the settings flag, the resolved credential, the session -//! preview, the one-shot upload, the upload-all sweep, and the terminal -//! Prime Agent Traces login. +//! The `/traces` state and engine: the settings flag, the resolved credential, +//! the session preview, the one-shot upload, and the upload-all sweep. use std::path::{Path, PathBuf}; @@ -19,7 +15,6 @@ use pa_tui::traces::{ TraceUploadReport, TracesCommands, TracesFuture, }; -/// The trace-sharing state against one daemon's shared directories. #[derive(Clone)] pub struct ClientTraces { cwd: PathBuf, @@ -45,8 +40,6 @@ impl ClientTraces { trace_credential(&self.agent_dir).map(|credential| credential.label) } - /// TS `uploadCurrentTraceOnce` → `uploadAgentTraceFile` (the one-shot - /// arm with `requireEnabled: false`, `reloadConfig: false`). async fn upload_once(&self, session_file: Option<&str>) -> TraceUploadReport { let http = pa_core::agent_traces::ReqwestTraceHttp; let session_file = session_file.map(PathBuf::from); @@ -70,8 +63,7 @@ impl ClientTraces { } } -/// The engine result mapped to the TUI outcome (the fields the TS -/// formatter reads). +/// The engine result mapped to the TUI outcome. fn map_upload_result(result: TraceUploadResult) -> TraceUploadOutcome { match result { TraceUploadResult::Uploaded { bytes_stored, .. } => { @@ -99,7 +91,6 @@ fn map_upload_result(result: TraceUploadResult) -> TraceUploadOutcome { } } -/// The engine preview mapped to the TUI outcome. fn map_preview_result(result: TracePreviewResult) -> TracePreviewOutcome { match result { TracePreviewResult::Ready(data) => TracePreviewOutcome::Ready(Box::new(TracePreviewInfo { @@ -153,7 +144,6 @@ impl TracesCommands for ClientTraces { }) } - /// TS `previewCurrentTrace` → `previewAgentTraceFile`. fn preview(&self, session_file: Option<&str>) -> TracesFuture { let session_file = session_file.map(str::to_string); Box::pin(async move { @@ -163,16 +153,14 @@ impl TracesCommands for ClientTraces { }) } - /// TS `uploadCurrentTraceOnce` → `uploadAgentTraceFile`. fn upload_current(&self, session_file: Option<&str>) -> TracesFuture { let provider = self.clone(); let session_file = session_file.map(str::to_string); Box::pin(async move { provider.upload_once(session_file.as_deref()).await }) } - /// TS `uploadAllTraces` → `uploadAllAgentTraces`: the spawned sweep - /// (progress through the note channel, cancellation through the - /// handle bridged into the engine's abort). + /// The spawned sweep: progress through the note channel, cancellation through + /// the handle bridged into the engine's abort. fn upload_all( &self, session_dir: Option<&str>, @@ -185,7 +173,6 @@ impl TracesCommands for ClientTraces { Box::pin(async move { let http = pa_core::agent_traces::ReqwestTraceHttp; let engine_cancel = EngineCancel::new(); - // The TUI handle bridges into the engine's abort. let bridge = { let tui_handle = cancel.clone(); let engine_handle = engine_cancel.clone(); @@ -238,9 +225,8 @@ impl TracesCommands for ClientTraces { }) } - /// TS `runPrimeAgentTracesLogin`: the login flow against the inline - /// auth panel (the TUI mounts it; the panel channel carries the - /// flow's surfaces and the settled outcome). + /// The login flow against the inline auth panel; the panel channel + /// carries the flow's surfaces and the settled outcome. fn login(&self, panel: pa_tui::auth_panel::AuthPanelHandle) -> TracesFuture { let agent_dir = self.agent_dir.clone(); Box::pin(async move { crate::traces_login::run_traces_login(&agent_dir, panel).await }) @@ -277,8 +263,7 @@ mod tests { .set_enabled(true) .await .expect("the opt-in write persists"); - // A fresh manager over the same directories reads the write (TS - // reloads settings before reporting the flag). + // A fresh manager over the same directories reads the write. let traces = ClientTraces::new("/tmp", agent.clone()); assert!(traces.enabled().await); } @@ -294,7 +279,6 @@ mod tests { let (_dir, agent) = temp_agent_dir(); let traces = ClientTraces::new("/tmp", agent.clone()); assert_eq!(traces.credential().await, None); - // A stored prime-inference key is the fallback credential. let mut auth = pa_core::auth::AuthStorage::create(&agent); auth.set( "prime-inference", @@ -307,7 +291,6 @@ mod tests { traces.credential().await.as_deref(), Some("Prime Inference credential") ); - // The dedicated traces key wins over the inference fallback. auth.set( "prime-agent-traces", pa_core::auth::AuthCredential::ApiKey { @@ -319,7 +302,6 @@ mod tests { traces.credential().await.as_deref(), Some("Prime Agent Traces credential") ); - // The traces env key wins over everything. std::env::set_var("PRIME_AGENT_TRACES_API_KEY", "env-key"); assert_eq!( traces.credential().await.as_deref(), diff --git a/crates/pa-cli/src/client_update.rs b/crates/pa-cli/src/client_update.rs index 8bdabe3517a..d5d7bf2e1e2 100644 --- a/crates/pa-cli/src/client_update.rs +++ b/crates/pa-cli/src/client_update.rs @@ -8,7 +8,6 @@ use pa_core::update::installer::{self, InstallerOutput}; -/// The `/update` funnel handle (the interactive options carry it). #[derive(Clone, Default)] pub struct ClientUpdate; diff --git a/crates/pa-cli/src/codex_subscription_login.rs b/crates/pa-cli/src/codex_subscription_login.rs index 9bda9fe61a8..7a0408c86dc 100644 --- a/crates/pa-cli/src/codex_subscription_login.rs +++ b/crates/pa-cli/src/codex_subscription_login.rs @@ -1,20 +1,8 @@ -//! The composition root's Codex Subscription login (TS -//! `auth-flows.ts`'s `showLoginDialog` over the AI library's -//! `openaiCodexOAuthProvider`): the browser authorization URL block, the -//! manual paste racing the localhost callback, the token exchange, and -//! the credential write under the `openai-codex` provider id. Every -//! surface renders through the inline auth panel (TS the login dialog in -//! the TUI); nothing touches the plain terminal. The TS flow's -//! account-id claim rides the stored credential (`accountId`, the -//! `auth.json` wire shape), and a stored credential makes the provider's -//! subscription models resolvable (the request path extracts the -//! account id from the token itself, like TS). -//! -//! Cancellation (#2770): the panel handle's shared flag is the seam — -//! the driving pane marks it on exit and this flow checks it after the -//! flow returns and before the credential write, so an exited pane never -//! lands a credential (a task abort cannot reach the started blocking -//! body). +//! The Codex Subscription login: the browser authorization URL block, the +//! manual paste racing the localhost callback, the token exchange, and the +//! credential write under `openai-codex`, all through the inline auth panel. +//! Cancellation (#2770): the pane marks the shared flag on exit; this flow +//! checks it before the credential write. use std::future::Future; use std::path::Path; @@ -27,10 +15,6 @@ use pa_core::auth::{AuthCredential, AuthStorage, OPENAI_CODEX_PROVIDER_ID}; use pa_tui::auth_panel::{AuthPanelHandle, PastePromptTone, PasteStyle}; use pa_tui::provider_auth::ProviderAuthOutcome; -/// The inline auth panel as the codex login's surface (TS the login -/// dialog): the browser URL block (the flow opens the browser; the panel -/// renders), the manual paste racing the browser callback, and the -/// fallback prompt ride the panel channel. pub(crate) struct PanelCodexLoginUi { panel: AuthPanelHandle, } @@ -75,9 +59,8 @@ impl CodexLoginUi for PanelCodexLoginUi { } } -/// TS `showLoginDialog` + `completeProviderAuthentication`: run the -/// flow, store the credential, and report the TS status. A cancelled -/// surface stays silent; a failed flow reports the TS error row. +/// Run the flow, store the credential, and report the status; a +/// cancelled surface stays silent. pub(crate) async fn run_codex_subscription_login( agent_dir: &Path, provider_name: &str, @@ -95,9 +78,7 @@ pub(crate) async fn run_codex_subscription_login( )); } }; - // The pane exited while the login ran: no credential write lands (TS - // the dialog's abort signal; #2770 — the flag is the seam, the - // blocking body checks it before the store). + // The pane exited while the login ran: no credential write lands. if ui.is_cancelled() { return ProviderAuthOutcome::Cancelled; } @@ -136,7 +117,6 @@ mod tests { use pa_ai::oauth::CodexHttpResponse; - /// A scripted transport (url -> response); unknown urls fail. struct ScriptedHttp(std::collections::HashMap); impl CodexHttp for ScriptedHttp { @@ -151,7 +131,6 @@ mod tests { } } - /// A scripted surface: a fixed paste answer and a shared cancel flag. struct ScriptedUi { cancelled: Arc, } @@ -174,8 +153,7 @@ mod tests { fn on_manual_code_input( &self, ) -> Option> + Send>>> { - // A paste with no state echoes (TS's falsy state skips the - // check): the code is used as-is. + // A paste with no state echoes: the code is used as-is. Some(Box::pin(std::future::ready(Some( "http://localhost:1455/auth/callback?code=abc".to_string(), )))) @@ -193,7 +171,6 @@ mod tests { } } - /// One fake access token carrying the account id. fn account_jwt(account_id: &str) -> String { use base64::Engine as _; let segment = |value: &serde_json::Value| { @@ -209,7 +186,6 @@ mod tests { ) } - /// The scripted token endpoint for one fake login. fn token_http(access: &str) -> ScriptedHttp { ScriptedHttp( [( @@ -258,9 +234,7 @@ mod tests { } other => panic!("expected the logged-in status, got {other:?}"), } - // The packaged auth.json wire shape: the TS credential with its - // `accountId` (the daemon and every packaged build read this - // file; the flow wrote it through the shared store). + // The packaged `auth.json` wire shape, with its `accountId`. let document: serde_json::Value = serde_json::from_str(&std::fs::read_to_string(agent.join("auth.json")).unwrap()) .unwrap(); @@ -268,21 +242,19 @@ mod tests { assert_eq!(stored["type"], "oauth"); assert_eq!(stored["access"], account_jwt("acct-1")); assert_eq!(stored["refresh"], "r-1"); - // The expiry is `now + expires_in * 1000` (TS's convention). + // The expiry is `now + expires_in * 1000`. let expires = stored["expires"].as_i64().expect("the expiry is numeric"); assert!( expires >= before_ms + 3_600_000 && expires <= before_ms + 3_600_000 + 5_000, "the expiry lands one hour out: {expires} vs {before_ms}" ); assert_eq!(stored["accountId"], "acct-1"); - // The stored credential resolves as the provider's api key (the - // subscription models become selectable). + let mut auth = AuthStorage::create(&agent); assert_eq!( auth.get_api_key("openai-codex"), Some(account_jwt("acct-1")) ); - // The /logout row appears for it. assert_eq!( auth.get_all().credential("openai-codex").map(|credential| { matches!( @@ -297,9 +269,6 @@ mod tests { ); } - /// A cancelled pane never receives the credential (#2770: no write - /// after the exit) — the regression test for the abort-cleanup - /// contract. #[tokio::test] async fn a_cancelled_pane_writes_no_credential() { let dir = tempfile::tempdir().expect("temp dir"); @@ -330,7 +299,6 @@ mod tests { let dir = tempfile::tempdir().expect("temp dir"); let agent = dir.path().join("agent"); std::fs::create_dir_all(&agent).expect("agent dir"); - // Nothing scripted: the token request fails. let http = ScriptedHttp(std::collections::HashMap::new()); let ui = ScriptedUi::new(); assert_eq!( @@ -350,10 +318,7 @@ mod tests { ); } - /// The credential round-trip: the flow's stored credential reloads, - /// resolves while unexpired, and refreshes at expiry through the - /// default provider integration (the packaged-build path: the same - /// `AuthStorage::create` every surface uses). + /// Through the default provider integration. #[tokio::test] async fn the_stored_credential_round_trips_and_refreshes() { let dir = tempfile::tempdir().expect("temp dir"); @@ -362,15 +327,15 @@ mod tests { let http = token_http(&account_jwt("acct-1")); let ui = ScriptedUi::new(); run_codex_subscription_login(&agent, "Codex", &http, &ui).await; - // Reload through the default integration (the daemon's path): - // an unexpired credential resolves its access token. + // An unexpired credential resolves its access token through the + // default integration (the daemon's path). let mut auth = AuthStorage::create(&agent); assert_eq!( auth.get_api_key("openai-codex"), Some(account_jwt("acct-1")) ); // An expired credential refreshes through the integration's - // scripted endpoint and the fresh token resolves. + // scripted endpoint. let mut data = auth.get_all(); if let Some(document) = data.0.get_mut("openai-codex") { document["expires"] = serde_json::json!(1); diff --git a/crates/pa-cli/src/command_registry.rs b/crates/pa-cli/src/command_registry.rs index f585a44b2ff..cbf51d42ff5 100644 --- a/crates/pa-cli/src/command_registry.rs +++ b/crates/pa-cli/src/command_registry.rs @@ -1,8 +1,7 @@ -//! Command specs and help formatting, ported from `cli/command-registry.ts`. +//! Command specs and help formatting. use crate::config::APP_NAME; -/// A registered public command. #[derive(Debug, Clone)] pub struct CommandSpec { pub path: &'static [&'static str], @@ -307,7 +306,6 @@ and prints the per-layer breakdown (cached static layers, then the dynamic tail) pub const REMOVED_COMMAND_NAMES: &[&str] = &["app", "daemon", "install", "manage", "remove", "uninstall"]; -/// The top-level public command names. pub fn public_command_names() -> Vec<&'static str> { COMMAND_SPECS .iter() @@ -457,14 +455,12 @@ const TOP_LEVEL_OPTION_GROUPS: &[OptionGroup] = &[ }, ]; -/// Look up a command spec by its exact path. pub fn get_command_spec(path: &[&str]) -> Option<&'static CommandSpec> { COMMAND_SPECS.iter().find(|spec| { spec.path.len() == path.len() && spec.path.iter().zip(path).all(|(a, b)| a == b) }) } -/// The direct child command specs of a path. pub fn get_child_command_specs(path: &[&str]) -> Vec<&'static CommandSpec> { COMMAND_SPECS .iter() @@ -497,9 +493,8 @@ pub fn is_help_command_request(path: &[&str]) -> bool { find_command_suggestion(path[path.len() - 1], &candidates).is_some() } -/// Suggest the closest candidate command name. The edit-distance heuristic -/// (`findSlashCommandSuggestion` in core/slash-commands.ts) is shared -/// vocabulary: `pa_types::slash_commands`. +/// Suggest the closest candidate command name (the shared edit-distance +/// heuristic in `pa_types::slash_commands`). pub fn find_command_suggestion<'a>(input: &str, candidates: &[&'a str]) -> Option<&'a str> { pa_types::slash_commands::find_slash_command_suggestion(input, candidates) } @@ -513,7 +508,7 @@ fn pad_end(value: &str, width: usize) -> String { } } -/// The full `--help` output, mirroring `formatTopLevelHelp`. +/// The full `--help` output. pub fn format_top_level_help() -> String { let commands: Vec<&CommandSpec> = COMMAND_SPECS .iter() @@ -570,7 +565,7 @@ pub fn format_top_level_help() -> String { ) } -/// Per-command help output, mirroring `formatCommandHelp`. +/// Per-command help output. pub fn format_command_help(path: &[&str]) -> Option { let spec = get_command_spec(path)?; let children = get_child_command_specs(path); diff --git a/crates/pa-cli/src/config.rs b/crates/pa-cli/src/config.rs index 271e771bfb1..511a997e7e2 100644 --- a/crates/pa-cli/src/config.rs +++ b/crates/pa-cli/src/config.rs @@ -1,29 +1,19 @@ -//! Product-wide constants and environment handling, ported from -//! `packages/coding-agent/src/config.ts`. +//! Product-wide constants and environment handling. use std::path::{Path, PathBuf}; -/// The user-facing application name (`piConfig.name` in package.json). pub const APP_NAME: &str = "prime-agent"; -/// The agent state directory name (`piConfig.configDir` in package.json). pub const CONFIG_DIR_NAME: &str = ".prime/agent"; -/// `PRIME_AGENT_CODING_AGENT_DIR`: overrides the agent state directory. pub const ENV_AGENT_DIR: &str = "PRIME_AGENT_CODING_AGENT_DIR"; -/// `PRIME_AGENT_SESSION_DIR`: overrides the session directory. pub const ENV_SESSION_DIR: &str = "PRIME_AGENT_SESSION_DIR"; -/// `PRIME_AGENT_DAEMON_SOCKET`: overrides the daemon socket path when no -/// explicit `--daemon-socket` flag is given. The `prime-agent` launcher -/// (written by install-rust.sh) pins it, so the Rust product's daemon -/// runs beside - never on, never replacing - the TypeScript product's -/// daemon: the two -/// products share the session store (`~/.prime/agent`) but not the -/// daemon, and a Rust CLI that found the TS daemon on the default socket -/// would treat the schema-id mismatch as a stale daemon and shut it down -/// when idle. +/// `PRIME_AGENT_DAEMON_SOCKET`: overrides the daemon socket path when no explicit +/// `--daemon-socket` flag is given. The launcher pins it so the Rust daemon runs +/// beside — never replacing — the TS daemon (a Rust CLI that found the TS daemon +/// on the default socket would treat the schema-id mismatch as staleness). pub const ENV_DAEMON_SOCKET: &str = "PRIME_AGENT_DAEMON_SOCKET"; /// The daemon socket path: an explicit `--daemon-socket` flag wins, then @@ -40,11 +30,9 @@ pub fn resolve_daemon_socket_path(daemon_socket: Option<&str>) -> PathBuf { .unwrap_or_else(pa_daemon::socket::default_daemon_socket_path) } -/// [`expand_tilde_path`] over a raw environment value: a tilde-prefixed -/// value expands against the home dir; anything else passes through as -/// the original bytes — a `to_string_lossy` here would silently rewrite a -/// non-UTF-8 socket path (U+FFFD) and point the CLI at a socket nobody -/// is serving. +/// [`expand_tilde_path`] over a raw environment value: anything but a +/// tilde-prefixed value passes through as the original bytes — a lossy read +/// here would rewrite a non-UTF-8 socket path. pub fn expand_tilde_path_os(value: &std::ffi::OsStr) -> PathBuf { if value.to_str().is_some_and(|path| path.starts_with('~')) { return expand_tilde_path(&value.to_string_lossy()); @@ -52,17 +40,14 @@ pub fn expand_tilde_path_os(value: &std::ffi::OsStr) -> PathBuf { PathBuf::from(value) } -/// `PRIME_AGENT_CODING_AGENT_SESSION_DIR`: legacy session-dir override. pub const ENV_LEGACY_SESSION_DIR: &str = "PRIME_AGENT_CODING_AGENT_SESSION_DIR"; /// The version compiled into this build, used when no packaged manifest -/// overrides it (dev checkouts, cargo target dirs). +/// overrides it. pub const VERSION: &str = env!("CARGO_PKG_VERSION"); /// The product version: the packaged `package.json` manifest next to the -/// executable wins (TS `VERSION` reads `getPackageJsonPath()` at runtime, so -/// a repackaged release reports the pinned manifest version), falling back -/// to the compiled-in version. +/// executable wins, falling back to the compiled-in version. pub fn version() -> &'static str { static VERSION: std::sync::OnceLock = std::sync::OnceLock::new(); VERSION.get_or_init(|| match packaged_manifest_version() { @@ -72,7 +57,7 @@ pub fn version() -> &'static str { } /// The packaged package-dir (`PI_PACKAGE_DIR` wins, else the directory of -/// the executable — the TS `getPackageDir` bun-binary layout). +/// the executable). fn package_dir() -> PathBuf { if let Ok(env_dir) = std::env::var("PI_PACKAGE_DIR") { if !env_dir.is_empty() { @@ -92,14 +77,12 @@ fn packaged_manifest_version() -> Option { (!version.is_empty()).then(|| version.to_string()) } -/// `PRIME_AGENT_OFFLINE`: truthy values enable offline mode. pub const ENV_OFFLINE: &str = "PI_OFFLINE"; -/// `PRIME_AGENT_STARTUP_BENCHMARK`: truthy values enable startup benchmarking. pub const ENV_STARTUP_BENCHMARK: &str = "PI_STARTUP_BENCHMARK"; -/// Expand a leading `~`, `~/`, or (Windows) `~\` segment against the home -/// directory (TS `expandTildePath`, including the win32 backslash arm). +/// Expand a leading `~`, `~/`, or (Windows) `~\` segment against the +/// home directory. pub fn expand_tilde_path(path: &str) -> PathBuf { let Some(home) = pa_types::platform::home_dir() else { return PathBuf::from(path); @@ -117,7 +100,6 @@ pub fn expand_tilde_path(path: &str) -> PathBuf { PathBuf::from(path) } -/// The agent state directory, honoring `PRIME_AGENT_CODING_AGENT_DIR`. pub fn get_agent_dir() -> PathBuf { match std::env::var(ENV_AGENT_DIR) { Ok(dir) if !dir.is_empty() => expand_tilde_path(&dir), @@ -127,7 +109,6 @@ pub fn get_agent_dir() -> PathBuf { } } -/// The session directory override from the environment, if any. pub fn get_session_dir_env_override() -> Option { std::env::var(ENV_SESSION_DIR) .ok() @@ -136,8 +117,8 @@ pub fn get_session_dir_env_override() -> Option { .map(|value| expand_tilde_path(&value)) } -/// Truthy environment flag check, matching `isTruthyEnvFlag` in main.ts: -/// only `1`, `true`, and `yes` (case-insensitive) count. +/// Truthy environment flag check: only `1`, `true`, and `yes` +/// (case-insensitive) count. pub fn is_truthy_env_flag(value: Option<&str>) -> bool { match value { None => false, @@ -161,11 +142,7 @@ pub(crate) fn env_lock() -> std::sync::MutexGuard<'static, ()> { mod tests { use super::*; - /// Precedence: an explicit `--daemon-socket` flag wins over the - /// `PRIME_AGENT_DAEMON_SOCKET` environment, which wins over the - /// per-user default. The env is what the `prime-agent` launcher - /// pins, so the flag/env/default order is the co-existence contract: - /// an explicit flag still overrides what any launcher installed. + /// The flag/env/default order is the co-existence contract (the launcher pins the env). #[test] fn daemon_socket_resolution_prefers_flag_then_env_then_default() { let default = pa_daemon::socket::default_daemon_socket_path(); @@ -195,10 +172,7 @@ mod tests { assert_eq!(expand_tilde_path("~foo"), PathBuf::from("~foo")); } - /// The TS `expandTildePath` win32 arm this crate already carries: a - /// `~\`-prefixed value expands against the home dir (the pa-types - /// twin gained the same arm, so the CLI and the daemon agree on the - /// state dir). + /// The TS `expandTildePath` win32 arm (the pa-types twin carries it too). #[test] #[cfg(windows)] fn expands_the_win32_backslash_tilde() { diff --git a/crates/pa-cli/src/config_command.rs b/crates/pa-cli/src/config_command.rs index 33a0b683f5b..e24e1130477 100644 --- a/crates/pa-cli/src/config_command.rs +++ b/crates/pa-cli/src/config_command.rs @@ -1,6 +1,5 @@ -//! `prime-agent config`: the resource-configuration view (TS -//! `handleConfigCommand`): resolve session resources, report settings -//! errors, then open the interactive selector until Esc. +//! `prime-agent config`: the resource-configuration view — resolve session +//! resources, report settings errors, then open the interactive selector. use std::path::PathBuf; @@ -11,8 +10,8 @@ use pa_tui::config_selector::{ }; use pa_tui::keybindings::KeybindingsManager; -/// Run the config command. Returns the process exit code; the TS product -/// exits 0 after the view closes (Esc) or immediately on Ctrl+C. +/// Run the config command. Returns the process exit code; exits 0 +/// after the view closes (Esc) or immediately on Ctrl+C. pub fn run() -> i32 { let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from(".")); let agent_dir = crate::config::get_agent_dir(); @@ -31,8 +30,7 @@ pub fn run() -> i32 { let (rows, items) = selector_rows(&groups); let selector = ConfigSelector::new(rows); let theme = pa_tui::app::load_theme(&theme_name); - // TS `setKeybindings(KeybindingsManager.create())` in main.ts: the - // config selector navigates with the user's effective bindings too. + // The config selector navigates with the user's effective bindings. let keybindings = KeybindingsManager::create(&agent_dir); let options = ConfigSelectorOptions::new(theme, keybindings); let mut toggle_settings = SettingsManager::create(&cwd, &agent_dir); diff --git a/crates/pa-cli/src/daemon_client.rs b/crates/pa-cli/src/daemon_client.rs index 69b8f80a827..683d1d10b5d 100644 --- a/crates/pa-cli/src/daemon_client.rs +++ b/crates/pa-cli/src/daemon_client.rs @@ -1,15 +1,7 @@ -//! Daemon socket client for the CLI's daemon-backed public commands -//! (`list`, `stop`, `rename`, `send`, `schedule`). -//! -//! Port of `modes/daemon/daemon-client.ts` restricted to the one-shot request -//! shape these commands use: connect, read the `daemon_hello` greeting, send -//! one `command` envelope per request, and match responses by request id. -//! Reconnect/recovery machinery is TUI-oriented and stays out of the CLI. -//! -//! The client never spawns a daemon: the TS CLI only auto-starts one for the -//! internal `daemon start`/`open` commands, which are not reachable from the -//! public command surface. When no daemon answers the socket, the exact TS -//! connect error is surfaced to the user. +//! Daemon socket client for the CLI's daemon-backed public commands (`list`, +//! `stop`, `rename`, `send`, `schedule`): connect, read the `daemon_hello`, +//! send one `command` envelope per request, match responses by id. The client +//! never spawns a daemon; an unanswered socket surfaces the exact TS error. use std::io::{BufRead, BufReader, Write}; use std::path::{Path, PathBuf}; @@ -24,15 +16,12 @@ use serde_json::json; use crate::config; -/// Default response timeout, mirroring `DEFAULT_DAEMON_REQUEST_TIMEOUT_MS`. const REQUEST_TIMEOUT_MS: u64 = 30_000; -/// Greeting timeout. The TS `waitForHello` default is 3s; raised to 15s -/// so daemons busy loading large sessions can still greet in time. +/// Greeting timeout. The TS default is 3s; raised to 15s so daemons +/// busy loading large sessions can still greet in time. const HELLO_TIMEOUT_MS: u64 = 15_000; -/// Read poll granularity for deadline-driven reads. const READ_POLL: Duration = Duration::from_millis(50); -/// A client connection to one daemon socket. #[derive(Debug)] pub(crate) struct DaemonClient { socket_path: PathBuf, @@ -48,7 +37,6 @@ pub(crate) struct DaemonClient { } impl DaemonClient { - /// Connect to the daemon socket, ready for the hello handshake. pub(crate) fn connect(socket_path: &Path) -> Result { Self::connect_raw(socket_path).map_err(|error| { anyhow!( @@ -60,8 +48,7 @@ impl DaemonClient { } /// [`Self::connect`] without the user-facing error decoration: discovery - /// probes expect unreachable sockets and classify them instead of - /// surfacing the connect error. + /// probes classify unreachable sockets instead of surfacing the error. pub(crate) fn connect_probe(socket_path: &Path) -> Result { Self::connect_raw(socket_path).map_err(|error| anyhow!("connect: {error}")) } @@ -81,11 +68,8 @@ impl DaemonClient { }) } - /// Send one command envelope and wait for its response with the default - /// timeout. - /// - /// Errors carry the exact TS client message text, including the socket and - /// daemon-log path the TS product prints so users can self-diagnose. + /// Send one command envelope and wait for its response. Errors carry the exact + /// TS client message text (socket and daemon-log path), so users can self-diagnose. pub(crate) fn request(&mut self, command: DaemonCommand) -> Result { self.request_with_timeout(command, REQUEST_TIMEOUT_MS) } @@ -108,9 +92,8 @@ impl DaemonClient { } self.request_id += 1; let id = format!("daemon_{}", self.request_id); - // The envelope and the command body both carry the request id, like - // the TS client's `{ ...command, id }` (the daemon matches responses - // by the envelope id; the body id is wire parity). + // The envelope and the command body both carry the request id, like the TS + // client's `{ ...command, id }` (the daemon matches by the envelope id). let mut command_value = serde_json::to_value(command)?; if !command_value.is_object() { return Err(anyhow!("invalid daemon command")); @@ -229,7 +212,6 @@ impl DaemonClient { } } -/// The operation a read is waiting on; shapes the timeout error text. #[derive(Clone, Copy)] enum Operation<'a> { Handshake, @@ -247,12 +229,10 @@ impl Operation<'_> { } } -/// Command type tag on the wire, mirroring `DaemonCommand["type"]`. fn command_type_name(command: &DaemonCommand) -> &str { pa_daemon::protocol::command_type_name(command) } -/// The protocol identity advertised in the hello. fn daemon_protocol(hello: &serde_json::Value) -> Result { hello .get("protocol") @@ -261,8 +241,7 @@ fn daemon_protocol(hello: &serde_json::Value) -> Result { .ok_or_else(|| anyhow!("invalid daemon hello")) } -/// `Socket: . Daemon log: .`, mirroring -/// `daemonEndpointDetails` in daemon-client.ts. +/// `Socket: . Daemon log: .` fn endpoint_details(socket_path: &Path) -> String { let log = pa_daemon::paths::daemon_log_path(socket_path, &config::get_agent_dir()); format!( @@ -272,8 +251,8 @@ fn endpoint_details(socket_path: &Path) -> String { ) } -/// Node's `connect` error message for the same failure, so the printed error -/// matches the TS product (`connect ENOENT ` and friends). +/// Node's `connect` error message for the same failure, so the printed +/// error matches the TS product (`connect ENOENT ` and friends). fn node_connect_error(error: &std::io::Error, socket_path: &Path) -> String { let path = socket_path.display().to_string(); match error.kind() { @@ -300,8 +279,6 @@ mod tests { } } - /// A minimal scripted daemon for protocol-level client tests: hello, one - /// response line, matching the response id from the request envelope. #[test] fn request_matches_response_by_id() { let dir = tempfile::TempDir::new().unwrap(); diff --git a/crates/pa-cli/src/daemon_command.rs b/crates/pa-cli/src/daemon_command.rs index 9f7426c3f90..3c23393a164 100644 --- a/crates/pa-cli/src/daemon_command.rs +++ b/crates/pa-cli/src/daemon_command.rs @@ -1,11 +1,7 @@ //! The daemon-backed command runner behind the public commands `list`, //! `sessions`, `stop`, `rename`, `send`, and `schedule`: argument parsing, -//! request shaping, and output rendering. Ported from -//! `cli/daemon-command.ts` (the `handleDaemonCommand` surface reachable -//! from public routing). -//! -//! `schedule` maps to the internal `cron` command and `stop` to `kill`, exactly -//! like `runInternalAgentCommand`/`runNestedAgentCommand` in public-command.ts. +//! request shaping, and output rendering. `schedule` maps to the internal +//! `cron` command and `stop` to `kill`. use std::path::{Path, PathBuf}; @@ -19,15 +15,13 @@ use crate::daemon_session_list::{ matches_session_id_suffix, }; -/// Parsed arguments for one daemon client command. #[derive(Debug)] struct ParsedDaemonCommand { socket_path: PathBuf, json: bool, positionals: Vec, - /// `--help`/`-h` becomes the internal no-op `help` command, exactly like - /// the TS `runDaemonClientCommand` fallthrough. The public router - /// intercepts help requests before this layer. + /// `--help`/`-h` becomes the internal no-op `help` command, exactly like the TS + /// `runDaemonClientCommand` fallthrough. help: bool, } @@ -50,9 +44,8 @@ pub(crate) fn run_daemon_command(command: &str, args: &[String]) -> Result<()> { } } -/// Port of `parseDaemonClientCommand`: option scanning with `--` passthrough -/// semantics (`send`/`cron` keep the separator as an operand, the others -/// consume it). The command name is fixed by the public router. +/// Option scanning with `--` passthrough semantics (`send`/`cron` keep the +/// separator as an operand, the others consume it). fn parse_daemon_command(command: &str, args: &[String]) -> Result { let mut socket_path = default_socket_path(); let mut json = false; @@ -66,7 +59,6 @@ fn parse_daemon_command(command: &str, args: &[String]) -> Result Result PathBuf { crate::config::resolve_daemon_socket_path(None) } -/// `normalizeSocketPath`: lexically resolve against the current directory. +/// Lexically resolve against the current directory. fn normalize_socket_path(value: &str) -> PathBuf { let path = Path::new(value); if path.is_absolute() { @@ -123,7 +113,7 @@ fn normalize_socket_path(value: &str) -> PathBuf { } } -/// `requireSuccess`: surface the daemon's error text. +/// Surface the daemon's error text. fn require_success(response: pa_types::daemon::DaemonResponse) -> Result> { if !response.success { return Err(anyhow!(response.error.unwrap_or_default())); @@ -138,17 +128,12 @@ fn print_json(value: &Value) { } } -/// `requireActiveSessionId`: the first operand. fn require_active_session_id(args: &[String]) -> Result { args.first() .cloned() .ok_or_else(|| anyhow!("Missing agent id or name")) } -// --------------------------------------------------------------------------- -// list -// --------------------------------------------------------------------------- - fn run_list(client: &mut DaemonClient, args: &[String], json: bool) -> Result<()> { let mut all = false; for arg in args { @@ -194,12 +179,8 @@ fn list_command(all: bool) -> DaemonCommand { } } -// --------------------------------------------------------------------------- -// sessions -// --------------------------------------------------------------------------- - /// The same list RPC as `prime-agent list`, rendered as the -/// one-line-per-agent operator table (TS `runSessions`). +/// one-line-per-agent operator table. fn run_sessions(client: &mut DaemonClient, args: &[String], json: bool) -> Result<()> { let mut all = false; for arg in args { @@ -240,8 +221,8 @@ fn run_sessions(client: &mut DaemonClient, args: &[String], json: bool) -> Resul Ok(()) } -/// `resolveLiveSessionSelector`: match a name/id/session-id selector against -/// the live session list, with unambiguous hex-suffix fallback. +/// Match a name/id/session-id selector against the live session list, +/// with unambiguous hex-suffix fallback. fn resolve_live_session_selector(client: &mut DaemonClient, selector: &str) -> Result { let response = client.request(list_command(false))?; let data = require_success(response)?; @@ -279,10 +260,6 @@ fn resolve_live_session_selector(client: &mut DaemonClient, selector: &str) -> R } } -// --------------------------------------------------------------------------- -// kill (stop) -// --------------------------------------------------------------------------- - fn run_kill(client: &mut DaemonClient, args: &[String], json: bool) -> Result<()> { let active_session_id = require_active_session_id(args)?; let response = client.request(DaemonCommand::Kill { @@ -293,8 +270,8 @@ fn run_kill(client: &mut DaemonClient, args: &[String], json: bool) -> Result<() print_response_data(&response, json) } -/// `printResponseData`: pretty-print the response data (the whole response as -/// JSON when there is none and `--json` was asked), else `ok`. +/// Pretty-print the response data (the whole response as JSON when +/// there is none and `--json` was asked), else `ok`. fn print_response_data(response: &pa_types::daemon::DaemonResponse, json: bool) -> Result<()> { let data = require_success(response.clone())?; if json || data.is_some() { @@ -327,10 +304,6 @@ fn response_value(response: &pa_types::daemon::DaemonResponse) -> Value { value } -// --------------------------------------------------------------------------- -// rename -// --------------------------------------------------------------------------- - fn run_rename(client: &mut DaemonClient, args: &[String], json: bool) -> Result<()> { let active_session_id = require_active_session_id(args)?; let name = args[1..].join(" ").trim().to_string(); @@ -366,10 +339,6 @@ fn run_rename(client: &mut DaemonClient, args: &[String], json: bool) -> Result< Ok(()) } -// --------------------------------------------------------------------------- -// send -// --------------------------------------------------------------------------- - struct ParsedSendArgs { target_active_session_id: String, from_active_session_id: Option, @@ -392,7 +361,7 @@ fn run_send(client: &mut DaemonClient, args: &[String], json: bool) -> Result<() print_json(&data); return Ok(()); } - // `isAgentMessageReceipt`: a target block with a routable active id. + // A target block with a routable active id. let receipt_target = data .get("target") .filter(|target| { @@ -484,10 +453,6 @@ fn parse_send_args(args: &[String]) -> Result { }) } -// --------------------------------------------------------------------------- -// cron (schedule) -// --------------------------------------------------------------------------- - fn run_cron(client: &mut DaemonClient, args: &[String], json: bool) -> Result<()> { let subcommand = args.first().map_or("list", String::as_str); match subcommand { @@ -592,7 +557,7 @@ fn run_cron_cancel(client: &mut DaemonClient, args: &[String], json: bool) -> Re Ok(()) } -/// `getCronJob`: the job id and next run when the response carries a job. +/// The job id and next run when the response carries a job. fn cron_job_id_and_next_run(data: &Value) -> Option<(String, String)> { let job = data.get("job")?; let id = job.get("id").and_then(Value::as_str)?.to_string(); @@ -603,7 +568,6 @@ fn cron_job_id_and_next_run(data: &Value) -> Option<(String, String)> { Some((id, next_run)) } -/// `formatAgentCronJob`: the one-line schedule list entry. fn format_agent_cron_job(job: &Value) -> String { let id = job.get("id").and_then(Value::as_str).unwrap_or_default(); let status = job @@ -648,9 +612,8 @@ fn format_agent_cron_job(job: &Value) -> String { ) } -/// `toLocaleString()` for a cron timestamp: en-US long-form-ish date with a -/// 12-hour clock, e.g. `9/16/2026, 6:36:59 PM`. Rendered in UTC; a daemon -/// machine running a non-UTC system timezone shifts the wall-clock part. +/// `toLocaleString()` for a cron timestamp: en-US date with a 12-hour clock, +/// e.g. `9/16/2026, 6:36:59 PM`. Rendered in UTC. fn cron_datetime(value: Option<&Value>) -> String { let Some(value) = value.and_then(Value::as_str) else { return "-".to_string(); diff --git a/crates/pa-cli/src/daemon_discovery/format.rs b/crates/pa-cli/src/daemon_discovery/format.rs index 36d5b703e0b..577885815b4 100644 --- a/crates/pa-cli/src/daemon_discovery/format.rs +++ b/crates/pa-cli/src/daemon_discovery/format.rs @@ -1,12 +1,10 @@ -//! Output rendering for the discovery commands: the daemon table (TS -//! `cli/daemon-ps-format.ts`) and the chalk-colored action lines of -//! `daemon-ps.ts`. Colors follow chalk's auto-detection: styled output only -//! when stdout is a terminal and `NO_COLOR` is unset. Piped output (the -//! differential corpus) is plain. +//! Output rendering for the discovery commands: the daemon table and the +//! colored action lines. Colors follow chalk's auto-detection: styled +//! output only when stdout is a terminal and `NO_COLOR` is unset. Piped +//! output (the differential corpus) is plain. use super::{DaemonInfo, DaemonStatus}; -/// The wire name of a status (TS serializes the kebab-case literal). fn status_name(status: DaemonStatus) -> String { match status { DaemonStatus::Current => "current".to_string(), @@ -41,24 +39,20 @@ fn reset_code(code: &str) -> &'static str { } } -/// `chalk.green` fn green(text: &str) -> String { paint("32", text) } -/// `chalk.red` fn red(text: &str) -> String { paint("31", text) } -/// `chalk.dim` fn dim(text: &str) -> String { paint("2", text) } -/// The discovered-daemon table (TS `formatDaemonListTable`): socket, pid, -/// version, status, sessions, uptime; the default socket is starred with a -/// footnote. +/// The discovered-daemon table: socket, pid, version, status, +/// sessions, uptime; the default socket is starred with a footnote. pub(crate) fn format_daemon_list_table(daemons: &[DaemonInfo]) -> String { let headers = ["socket", "pid", "version", "status", "sessions", "uptime"]; let rows: Vec<[String; 6]> = daemons @@ -92,7 +86,7 @@ pub(crate) fn format_daemon_list_table(daemons: &[DaemonInfo]) -> String { .unwrap_or(0) }) .collect(); - // Two spaces between columns (TS `formatTable`). + // Two spaces between columns. let mut lines = vec![headers .iter() .enumerate() @@ -116,8 +110,8 @@ pub(crate) fn format_daemon_list_table(daemons: &[DaemonInfo]) -> String { } } -/// The status cell carries its severity color (TS `colorStatus`); the column -/// width math runs on the visible text, not the escape codes. +/// The status cell carries its severity color; the column width math +/// runs on the visible text, not the escape codes. fn color_status(status: DaemonStatus, value: &str) -> String { match status { DaemonStatus::Current => green(value), @@ -127,7 +121,7 @@ fn color_status(status: DaemonStatus, value: &str) -> String { } } -/// Compact uptime (TS `formatUptime`): seconds, minutes, hours, days, weeks. +/// Compact uptime: seconds, minutes, hours, days, weeks. pub(crate) fn format_uptime(uptime_seconds: Option) -> String { let Some(seconds) = uptime_seconds else { return String::new(); @@ -160,8 +154,7 @@ fn pad_end(text: &str, width: usize) -> String { } } -/// The reap report: green `reaped` lines then dim `kept` lines -/// (TS `runReap` text output). +/// The reap report: green `reaped` lines then dim `kept` lines. pub(crate) fn print_reap_report(reaped: &[(String, String)], skipped: &[(String, String)]) { if reaped.is_empty() && skipped.is_empty() { println!("No background services found."); @@ -175,8 +168,7 @@ pub(crate) fn print_reap_report(reaped: &[(String, String)], skipped: &[(String, } } -/// The shutdown report: green `stopped` lines then red `failed` lines -/// (TS `runShutdownAllConverging` text output). +/// The shutdown report: green `stopped` lines then red `failed` lines. pub(crate) fn print_shutdown_report(stopped: &[(String, String)], failed: &[(String, String)]) { if stopped.is_empty() && failed.is_empty() { println!("No background services found."); @@ -242,7 +234,6 @@ mod tests { .next() .unwrap() .starts_with("/tmp/prime-agent-1000/daemon.sock * 42 0.1.0")); - // The footnote names the default service. assert!(table.ends_with("* default background service")); } diff --git a/crates/pa-cli/src/daemon_discovery/kill.rs b/crates/pa-cli/src/daemon_discovery/kill.rs index dc53d323d79..1ac957e50d7 100644 --- a/crates/pa-cli/src/daemon_discovery/kill.rs +++ b/crates/pa-cli/src/daemon_discovery/kill.rs @@ -1,7 +1,5 @@ -//! Process-kill primitives for stopping daemons and tracked workers (TS -//! `forceKillDaemon`, `stopTrackedProcess`, `terminateVerifiedListener(s)`): -//! every signal is identity-gated by the process start id so a recycled pid -//! can never be mistaken for the process discovery saw. +//! Process-kill primitives: every signal is identity-gated by the process start +//! id so a recycled pid can never be mistaken for the process discovery saw. use std::path::Path; @@ -10,17 +8,15 @@ use pa_types::platform::process::{is_process_alive, process_start_id}; use super::{evaluate_shutdown_quiet_period, DaemonStateRoot, DiscoveredDaemonProcess}; -/// How long the residual sweep may run before it declares the listener set -/// stuck (TS `SHUTDOWN_CONVERGENCE_TIMEOUT_MS`). +/// How long the residual sweep may run before it declares the listener +/// set stuck. const SHUTDOWN_CONVERGENCE_TIMEOUT_MS: u128 = 10_000; -/// Verified force-kill (TS `forceKillDaemon`, hardened): SIGTERM, a 1s -/// grace, then SIGKILL, then a poll loop (25ms slices, 1s deadline) that -/// reports the kill only once the process is confirmed gone (zombies count -/// as dead — [`is_process_alive`]'s lease semantics). TS fires the -/// SIGKILL and returns without verifying; the supervisor-side stop paths -/// here must not claim a stop a D-state process never performed, so the -/// verdict is the divergence. +/// Verified force-kill, hardened: SIGTERM, a 1s grace, then SIGKILL, then a +/// poll loop (25ms slices, 1s deadline) reporting the kill only once the +/// process is confirmed gone (zombies count as dead — [`is_process_alive`]). +/// Deliberate TS divergence (TS fires SIGKILL and returns without verifying): +/// a stop path must not claim a stop a D-state process never performed. pub(super) fn force_kill_daemon(pid: u32) -> bool { kill_daemon(pid); let deadline = std::time::Instant::now() + std::time::Duration::from_secs(1); @@ -53,9 +49,8 @@ pub(super) fn is_alive(pid: u32) -> bool { is_process_alive(pid).unwrap_or(false) } -/// Remove a socket file if present; false when the unlink fails (TS -/// `removeSocketFile`). Never-touch paths are refused here as the last line -/// of containment, whatever the caller derived. +/// Remove a socket file if present; false when the unlink fails. Never-touch +/// paths are refused here as the last line of containment. pub(super) fn remove_socket_file(socket_path: &Path) -> bool { if super::is_never_touch(socket_path) { return false; @@ -67,10 +62,8 @@ pub(super) fn remove_socket_file(socket_path: &Path) -> bool { } } -/// Stop every worker tracked for one supervisor socket and clean up its -/// records (TS `forceStopTrackedWorkers`). Returns the failure reasons. -/// Workers are read from the given agent dir only (the invocation's state -/// root), never the ambient agent dir. +/// Stop every worker tracked for one supervisor socket and clean up its records. +/// Returns the failure reasons. Workers are read from the given agent dir. pub(super) fn force_stop_tracked_workers( supervisor_socket_path: &Path, agent_dir: &Path, @@ -91,9 +84,8 @@ pub(super) fn force_stop_tracked_workers( failures } -/// Identity-gated stop: SIGTERM the worker (it exits keeping its resume -/// entry), then SIGKILL if it hangs (TS `stopTrackedProcess`). The start-id -/// gate defeats pid reuse between discovery and the signal. +/// Identity-gated stop: SIGTERM the worker (it exits keeping its resume entry), +/// then SIGKILL if it hangs. The start-id gate defeats pid reuse. pub(super) fn stop_tracked_process(pid: u32, expected_start_id: Option<&str>) -> bool { if !is_alive(pid) { return true; @@ -124,11 +116,11 @@ pub(super) fn stop_tracked_process(pid: u32, expected_start_id: Option<&str>) -> !is_alive(pid) } -/// The `--force` residual sweep (TS `terminateVerifiedResiduals`): kill -/// whatever product listeners remain in the invocation's state root until -/// the set quiets down or proves stuck; report the survivors as failures. -/// The sweep re-scans with the same root it was given, so daemons in any -/// other root — or on the never-touch list — are never candidates. +/// The `--force` residual sweep: kill whatever product listeners remain in +/// the invocation's state root until the set quiets down or proves stuck; +/// report the survivors as failures. The sweep re-scans with the same root, +/// so daemons in any other root — or on the never-touch list — are never +/// candidates. pub(super) fn terminate_verified_residuals( root: &DaemonStateRoot, stopped: &mut Vec<(String, String)>, @@ -196,8 +188,8 @@ pub(super) fn record_residuals( } } -/// Kill one verified listener (TS `terminateVerifiedListener`): the start-id -/// gate must still name the same process before and after the signal. +/// Kill one verified listener: the start-id gate must still name the +/// same process before and after the signal. pub(super) fn terminate_verified_listener(listener: &DiscoveredDaemonProcess) -> bool { let Some(start_id) = process_start_id(listener.pid) else { return false; @@ -214,10 +206,8 @@ pub(super) fn terminate_verified_listener(listener: &DiscoveredDaemonProcess) -> } if process_start_id(listener.pid).as_deref() == Some(start_id.as_str()) { let _ = kill_pid(listener.pid as i32, Signal::Kill); - // Verified death (the same hardening as `force_kill_daemon`): a - // single post-SIGKILL check races a slow teardown or reads a - // mid-death process as survived, so poll the identity until it - // changes or the deadline lapses. + // Verified death (the same hardening as `force_kill_daemon`): a single + // post-SIGKILL check races a slow teardown, so poll the identity. let deadline = std::time::Instant::now() + std::time::Duration::from_secs(1); while process_start_id(listener.pid).as_deref() == Some(start_id.as_str()) && std::time::Instant::now() < deadline @@ -295,9 +285,8 @@ mod tests { } fn spawn_term_ignoring_shell() -> std::process::Child { - // A shell that swallows SIGTERM: the force-kill must escalate to - // SIGKILL to make it die (the grandchild `sleep 1` exits on its own - // at most a second after the shell dies, so no stray processes). + // A shell that swallows SIGTERM: the force-kill must escalate to SIGKILL + // (the grandchild `sleep 1` exits on its own shortly after, no strays). std::process::Command::new("sh") .arg("-c") .arg("trap : TERM; while :; do sleep 1; done") @@ -355,11 +344,8 @@ mod tests { .spawn() .expect("spawn a sleep child"); let pid = child.id(); - // A dead direct child lingers as a zombie until its parent reaps - // it, and a zombie's start id never changes - the production - // daemon's parent (the spawning shell) reaps it, so the test - // reaps concurrently or the identity poll would outwait both - // deadlines on a process that is already dead. + // A dead direct child lingers as a zombie until its parent reaps it, and + // a zombie's start id never changes — the test reaps concurrently. let reaper = std::thread::spawn(move || child.wait()); let listener = DiscoveredDaemonProcess { pid, diff --git a/crates/pa-cli/src/daemon_discovery/mod.rs b/crates/pa-cli/src/daemon_discovery/mod.rs index 8b0400f684f..ce9d8237307 100644 --- a/crates/pa-cli/src/daemon_discovery/mod.rs +++ b/crates/pa-cli/src/daemon_discovery/mod.rs @@ -1,32 +1,8 @@ //! Daemon discovery: find every product daemon in this state root and probe -//! it for identity and session count (TS `cli/daemon-ps.ts`). -//! -//! Discovery merges two sources by socket path: the OS census of listening -//! unix sockets owned by a product process (the only reliable socket→pid -//! mapping when daemons run on arbitrary `--daemon-socket` paths), and a sweep -//! of the default socket dir, which also catches orphaned socket files left -//! by daemons that are no longer running. Worker sockets (tracked by the -//! supervisor's worker descriptors) add their supervisor's socket to the set -//! so a supervisor whose own listener vanished is still reachable for -//! `shutdown --force`. -//! -//! Scope: one *state root* — the agent dir plus the default socket dir. A -//! daemon started under a different HOME or agent dir is another root's -//! business; stopping it from here would kill unrelated live sessions. -//! (TS also keeps a supervisor-ownership registry rule for custom socket -//! paths outside both directories; that registry is not ported yet, so such -//! paths are invisible to discovery from another invocation until the -//! registry lane lands.) -//! -//! Containment (operator-mandated): every scan, probe, -//! and stop is scoped to an explicit [`DaemonStateRoot`] handed in by the -//! caller — the CLI passes the env-resolved current root, tests pass only -//! fixture directories they created — and [`NEVER_TOUCH_SOCKET_DIRS`] is a -//! hard exclusion list the scan, probe, and unlink paths check -//! unconditionally, so a state root that resolves onto this box's ambient -//! mission daemons (via a leaked HOME/TMPDIR) still cannot enumerate, probe, -//! or stop them. A daemon outside the root an invocation was given is -//! invisible to it, always. +//! it for identity and session count — the OS census of listening sockets +//! plus a sweep of the default socket dir (orphaned files included). +//! Containment is operator-mandated: everything is scoped to one +//! [`DaemonStateRoot`], and [`NEVER_TOUCH_SOCKET_DIRS`] is checked always. use std::collections::BTreeSet; use std::path::{Path, PathBuf}; @@ -46,7 +22,6 @@ pub(crate) mod stop; pub(crate) use format::format_daemon_list_table; pub(crate) use stop::{run_ps, run_reap, run_shutdown_all}; -/// One discovered daemon process: an owning pid and the socket it listens on. #[derive(Debug, Clone)] pub(crate) struct DiscoveredDaemonProcess { pub pid: u32, @@ -55,8 +30,7 @@ pub(crate) struct DiscoveredDaemonProcess { } /// The state root an invocation reads: the agent dir and the default socket -/// dir (TS `DaemonStateRoot`). Both follow HOME/TMPDIR/agent-dir overrides, -/// so an isolated root resolves to isolated paths. +/// dir, both following HOME/TMPDIR/agent-dir overrides. #[derive(Debug, Clone)] pub(crate) struct DaemonStateRoot { pub agent_dir: PathBuf, @@ -65,19 +39,13 @@ pub(crate) struct DaemonStateRoot { } /// Directories the discovery code must never touch, unconditionally -/// (operator-mandated containment guard; see the module docs). -/// These hold this box's live mission infrastructure; -/// an ambient `HOME`/`TMPDIR` leaking into a test process makes -/// `current_state_root()` resolve onto them, so root matching alone cannot -/// be trusted. NOTE: `/tmp/prime-agent-1000` is also the product-default -/// socket dir for uid 1000 — the exclusion is deliberate and mission-local. -/// The `-0` entries are the uid-0 -/// twins: the product-default socket dir is `/prime-agent-`, -/// so on a root-user Linux box (uid 0 — the fleet's root-uid gate and -/// mission topology) the ambient mission daemon lives under -/// `/tmp/prime-agent-0` / `/tmp/mission-tmp/prime-agent-0`, and the guard -/// must cover it exactly like the uid-1000 pair; without them the whole -/// never-touch protection silently disappears at uid 0. +/// (operator-mandated containment guard; see the module docs). These hold +/// this box's live mission infrastructure; an ambient `HOME`/`TMPDIR` +/// leaking into a test process makes `current_state_root()` resolve onto +/// them, so root matching alone cannot be trusted. `/tmp/prime-agent-1000` +/// is also the product-default socket dir for uid 1000 (deliberate, +/// mission-local); the `-0` entries are the uid-0 twins — without them the +/// protection silently disappears at uid 0. pub(crate) const NEVER_TOUCH_SOCKET_DIRS: &[&str] = &[ "/tmp/prime-agent-1000", "/tmp/mission-tmp/prime-agent-1000", @@ -86,14 +54,12 @@ pub(crate) const NEVER_TOUCH_SOCKET_DIRS: &[&str] = &[ "/tmp/mission-tmp/prime-agent-0", ]; -/// True when `path` is or sits inside a never-touch directory. pub(crate) fn is_never_touch(path: &Path) -> bool { NEVER_TOUCH_SOCKET_DIRS .iter() .any(|dir| path.starts_with(Path::new(dir))) } -/// Discovered-daemon classification (TS `DaemonStatus`). #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)] #[serde(rename_all = "kebab-case")] pub(crate) enum DaemonStatus { @@ -103,7 +69,6 @@ pub(crate) enum DaemonStatus { OrphanFile, } -/// How a discovered daemon's pid was established (TS `pidSource`). #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "lowercase")] pub(crate) enum PidSource { @@ -111,8 +76,7 @@ pub(crate) enum PidSource { Hello, } -/// One discovered daemon, probed (TS `DaemonInfo`; field order is the TS JSON -/// shape, options omitted exactly like the TS spread/conditionals). +/// One discovered daemon, probed; field order matches the TS JSON shape. #[derive(Debug, Clone, Serialize)] #[serde(rename_all = "camelCase")] pub(crate) struct DaemonInfo { @@ -141,7 +105,6 @@ pub(crate) struct DaemonInfo { pub has_tracked_workers: Option, } -/// The current invocation's state root (TS `currentDaemonStateRoot`). pub(crate) fn current_state_root() -> DaemonStateRoot { DaemonStateRoot { agent_dir: config::get_agent_dir(), @@ -150,10 +113,8 @@ pub(crate) fn current_state_root() -> DaemonStateRoot { } } -/// A socket belongs to the root when it is the default path, sits in the -/// socket dir, or anywhere inside the agent dir (TS -/// `createDaemonStateRootMatcher` minus the not-yet-ported ownership -/// registry rule). +/// A socket belongs to the root when it is the default path, sits in the socket +/// dir, or anywhere inside the agent dir (TS ownership registry not ported). fn state_root_matches(root: &DaemonStateRoot, socket_path: &Path) -> bool { if is_never_touch(socket_path) { return false; @@ -161,9 +122,7 @@ fn state_root_matches(root: &DaemonStateRoot, socket_path: &Path) -> bool { #[cfg(windows)] { // Windows daemons share one named pipe per machine, so there is - // nothing to scope beyond the containment guard (TS - // `createDaemonStateRootMatcher` returns an always-true predicate on - // win32). + // nothing to scope beyond the containment guard. let _ = (root, socket_path); true } @@ -177,8 +136,6 @@ fn state_root_matches(root: &DaemonStateRoot, socket_path: &Path) -> bool { } } -/// True when `directory` is `parent` or sits below it (TS `isInside`). Only -/// the non-Windows root matcher scopes; the Windows arm accepts any path. #[cfg(not(windows))] fn inside(directory: Option<&Path>, parent: &Path) -> bool { let Some(directory) = directory else { @@ -190,10 +147,8 @@ fn inside(directory: Option<&Path>, parent: &Path) -> bool { } } -/// Worker sockets: `worker-*.sock` in the given socket dir (TS -/// `isWorkerSocketPath`) — the supervisor's own socket is never a worker -/// socket. The socket dir comes from the state root, never the ambient -/// environment. +/// Worker sockets: `worker-*.sock` in the given socket dir (never the +/// supervisor's own). The dir comes from the state root, never the ambient env. pub(crate) fn is_worker_socket_path(socket_path: &Path, socket_dir: &Path) -> bool { if socket_path.parent() != Some(socket_dir) { return false; @@ -207,17 +162,14 @@ pub(crate) fn is_worker_socket_path(socket_path: &Path, socket_dir: &Path) -> bo .is_some_and(|ext| ext == "sock") } -/// Listening daemons in this state root (TS `scanListeningDaemons`). The OS -/// census is filtered to the root inside the scan, before any probe or -/// uptime lookup touches a pid: a scan run from one root can never see — -/// let alone stop — a daemon in another root. +/// Listening daemons in this state root. The census is filtered to the root +/// inside the scan: a scan from one root can never see another root's daemon. pub(crate) fn scan_listening_daemons(root: &DaemonStateRoot) -> Vec { scan::scan_all_listening_daemons(config::APP_NAME, root) } -/// True when the pid still listens on exactly this socket (TS -/// `isDaemonProcessListening`): a fresh scan against the same root, so a -/// re-probe sees the same listener set the discovery did. +/// True when the pid still listens on exactly this socket: a fresh scan against +/// the same root, so a re-probe sees the discovery's listener set. pub(crate) fn is_daemon_process_listening( pid: u32, socket_path: &Path, @@ -228,9 +180,8 @@ pub(crate) fn is_daemon_process_listening( .any(|daemon| daemon.pid == pid && daemon.socket_path == socket_path) } -/// Socket files in the given socket dir (TS `scanSocketDir`): live daemons -/// and orphaned files alike. Never-touch paths are filtered out here too, -/// so even a root handed in on purpose cannot sweep them. +/// Socket files in the given socket dir: live daemons and orphaned files alike. +/// Never-touch paths are filtered here too. #[cfg(unix)] fn scan_socket_dir(socket_dir: &Path) -> Vec { let Ok(entries) = std::fs::read_dir(socket_dir) else { @@ -255,14 +206,12 @@ fn scan_socket_dir(_socket_dir: &Path) -> Vec { Vec::new() } -/// True when the path is a unix socket file. #[cfg(unix)] fn is_socket_file(path: &Path) -> bool { use std::os::unix::fs::FileTypeExt; std::fs::symlink_metadata(path).is_ok_and(|meta| meta.file_type().is_socket()) } -/// One tracked worker from a supervisor descriptor (TS `TrackedWorker`). #[derive(Debug, Clone)] pub(crate) struct TrackedWorker { pub descriptor_path: PathBuf, @@ -273,9 +222,8 @@ pub(crate) struct TrackedWorker { pub recovery_journal_path: PathBuf, } -/// Every tracked worker recorded in this agent dir (TS `findAllTrackedWorkers`): -/// `daemon-workers/*/.json` descriptors. The `supervisor-config` file -/// carries no `.json` extension and is skipped by construction. +/// Every tracked worker recorded in this agent dir: `daemon-workers/*/.json` +/// descriptors (`supervisor-config` has no `.json` and is skipped). pub(crate) fn find_all_tracked_workers(agent_dir: &Path) -> Vec { let root = agent_dir.join("daemon-workers"); let Ok(entries) = std::fs::read_dir(&root) else { @@ -301,7 +249,7 @@ pub(crate) fn find_all_tracked_workers(agent_dir: &Path) -> Vec { } /// Parse one descriptor file; invalid or concurrently removed descriptors -/// are not safe shutdown targets and are skipped (TS `isTrackedWorkerDescriptor`). +/// are not safe shutdown targets and are skipped. fn read_tracked_worker(path: &Path) -> Option { let content = std::fs::read_to_string(path).ok()?; let descriptor: serde_json::Value = serde_json::from_str(&content).ok()?; @@ -326,7 +274,6 @@ fn read_tracked_worker(path: &Path) -> Option { }) } -/// What a probe learned about one daemon (TS `ProbeResult`). #[derive(Debug, Default)] pub(crate) struct ProbeResult { version: Option, @@ -340,14 +287,12 @@ pub(crate) struct ProbeResult { reachable: bool, } -/// Probe one socket: connect (300ms), read the hello (1500ms), and ask for -/// the session count over `list` (30s when greeted, 1500ms otherwise). Old or -/// foreign daemons connect without a recognizable greeting; the session -/// count then also gets the short deadline (TS `probeDaemon`). +/// Probe one socket: connect (300ms), read the hello (1500ms), and ask for the +/// session count over `list` (30s when greeted, else 1500ms). pub(crate) fn probe_daemon(socket_path: &Path) -> ProbeResult { if is_never_touch(socket_path) { - // Containment: never even connect to a forbidden path, whatever the - // caller's root says. + // Containment: never even connect to a forbidden path, whatever + // the caller's root says. return ProbeResult::default(); } let Ok(mut client) = DaemonClient::connect_probe(socket_path) else { @@ -419,12 +364,11 @@ pub(crate) fn probe_daemon(socket_path: &Path) -> ProbeResult { probe } -/// Probe deadlines (TS `probeDaemon`). const HELLO_TIMEOUT_MS: u64 = 1_500; const LIST_TIMEOUT_MS: u64 = 30_000; -/// Reachable daemons are `current` only when the protocol, schema, and app -/// version all match this build (TS `classifyReachable`). +/// Reachable daemons are `current` only when the protocol, schema, and +/// app version all match this build. fn classify_reachable(probe: &ProbeResult) -> DaemonStatus { if probe.protocol_version == Some(pa_types::daemon::DAEMON_PROTOCOL_VERSION) && probe.schema_id.as_deref() == Some(pa_types::daemon::DAEMON_SCHEMA_ID) @@ -437,8 +381,7 @@ fn classify_reachable(probe: &ProbeResult) -> DaemonStatus { } /// The hello's supervisor pid, but only when it is alive and its process -/// identity still matches the one the daemon reported (TS -/// `verifyHelloSupervisorPid`; the start-id gate defeats pid reuse). +/// identity still matches (the start-id gate defeats pid reuse). pub(crate) fn verify_hello_supervisor_pid( pid: Option, expected_process_start_id: Option<&str>, @@ -460,10 +403,8 @@ pub(crate) fn verify_hello_supervisor_pid( Some(pid) } -/// Discover every daemon in this state root and probe each (TS -/// `discoverDaemons`). The root is explicit: the CLI passes the env-resolved -/// current root, tests pass their own fixture dirs. A daemon outside the -/// root is never discovered, probed, or stopped. +/// Discover every daemon in this state root and probe each. The root is +/// explicit (the CLI passes the env-resolved root; tests pass fixture dirs). pub(crate) fn discover_daemons(root: &DaemonStateRoot) -> Vec { discover_daemons_with(root, cfg!(windows)) } @@ -549,8 +490,7 @@ fn discover_daemons_with(root: &DaemonStateRoot, named_pipes: bool) -> Vec) -> bool { quiet_since_ms .is_some_and(|quiet_since| now_ms.saturating_sub(quiet_since) >= SHUTDOWN_QUIET_PERIOD_MS) } -/// How long the residual sweep must see no listener before it succeeds (TS -/// `SHUTDOWN_QUIET_PERIOD_MS`). +/// How long the residual sweep must see no listener before it succeeds. const SHUTDOWN_QUIET_PERIOD_MS: u128 = 1_000; #[cfg(test)] mod tests { use super::*; - /// A synthetic state root inside a fixture directory: unit tests never - /// touch the ambient environment's real agent dir or socket dir. + /// A synthetic state root inside a fixture directory: unit tests + /// never touch the ambient environment's real agent dir or socket dir. #[cfg(not(windows))] fn fixture_root(dir: &Path) -> DaemonStateRoot { DaemonStateRoot { @@ -603,8 +541,6 @@ mod tests { )); } - /// Unix scoping semantics; the Windows matcher is deliberately - /// always-true after the containment guard (one pipe per machine). #[cfg(not(windows))] #[test] fn state_root_matches_own_paths_only() { @@ -651,11 +587,8 @@ mod tests { #[test] fn a_scan_rooted_on_a_never_touch_dir_surfaces_no_listeners() { - // The ambient mission daemon's workers listen under these dirs and - // are owned by real `prime-agent` processes: root matching alone - // would find them, the containment guard must not. The loop covers - // every guarded dir — the uid-1000 mission paths on a devbox and - // their uid-0 twins on a root-user Linux box. + // The ambient mission daemon's workers listen under these dirs, owned + // by real `prime-agent` processes: root matching alone would find them. for dir in NEVER_TOUCH_SOCKET_DIRS { let dir = *dir; let root = DaemonStateRoot { @@ -672,9 +605,8 @@ mod tests { #[test] fn a_probe_never_connects_to_a_never_touch_path() { - // When the guard works, this never opens a connection. A regression - // (guard removed) would probe the live mission daemon once and fail - // the assertion — never kill it. + // When the guard works, this never opens a connection; a regression + // would probe the live mission daemon once and fail the assert. let probe = probe_daemon(Path::new("/tmp/mission-daemon/daemon.sock")); assert!(!probe.reachable); } @@ -685,8 +617,8 @@ mod tests { let tmp = tempfile::tempdir().expect("tempdir"); let root = fixture_root(tmp.path()); std::fs::create_dir_all(&root.socket_dir).expect("socket dir"); - // Bind and drop: the listener's socket file stays behind (std does - // not unlink it), an orphan file in the fixture root. + // Bind and drop: the listener's socket file stays behind (std + // does not unlink it), an orphan file in the fixture root. drop( std::os::unix::net::UnixListener::bind(root.socket_dir.join("leftover.sock")) .expect("bind"), @@ -695,7 +627,6 @@ mod tests { assert_eq!(infos.len(), 1); assert_eq!(infos[0].socket_path, root.socket_dir.join("leftover.sock")); assert_eq!(infos[0].status, DaemonStatus::OrphanFile); - // Not the root's default path: leftover.sock, not daemon.sock. assert!(!infos[0].is_default); } diff --git a/crates/pa-cli/src/daemon_discovery/plan.rs b/crates/pa-cli/src/daemon_discovery/plan.rs index 763b67ea303..e01ef373d95 100644 --- a/crates/pa-cli/src/daemon_discovery/plan.rs +++ b/crates/pa-cli/src/daemon_discovery/plan.rs @@ -1,12 +1,10 @@ -//! Pure action planners for the discovery commands (TS `planReap` / -//! `planShutdownAll` / `planShutdownConfirmation`): no side effects, unit- -//! tested in isolation from the executors. +//! Pure action planners for the discovery commands: no side effects, +//! unit-tested in isolation from the executors. use std::collections::HashMap; use super::{DaemonInfo, DaemonStatus}; -/// One planned action for a discovered daemon (TS `ReapAction`). #[derive(Debug, Clone, PartialEq, Eq)] pub(crate) enum ReapActionKind { RemoveFile, @@ -22,10 +20,10 @@ pub(crate) struct ReapAction { pub reason: Option, } -/// What `doctor --fix` may do with each discovered daemon (pure; TS -/// `planReap`). Only clearly-safe targets are touched: orphaned socket -/// files, and reachable idle daemons on non-default sockets. The default -/// daemon, and any daemon with live sessions, are never touched. +/// What `doctor --fix` may do with each discovered daemon (pure). Only +/// clearly-safe targets are touched: orphaned socket files, and +/// reachable idle daemons on non-default sockets. The default daemon, +/// and any daemon with live sessions, are never touched. pub(crate) fn plan_reap(daemons: &[DaemonInfo], force: bool) -> Vec { let mut pid_counts: HashMap = HashMap::new(); for daemon in daemons { @@ -36,9 +34,8 @@ pub(crate) fn plan_reap(daemons: &[DaemonInfo], force: bool) -> Vec daemons .iter() .map(|daemon| { - // An orphan socket file has no owning process, so removing it is - // safe even on the default path (a stale daemon.sock left by a - // crash) — decided before the default guard. + // An orphan socket file has no owning process, so removing it is safe even + // on the default path (a stale daemon.sock left by a crash). if daemon.status == DaemonStatus::OrphanFile { return ReapAction { kind: ReapActionKind::RemoveFile, @@ -100,9 +97,8 @@ pub(crate) fn plan_reap(daemons: &[DaemonInfo], force: bool) -> Vec .collect() } -/// What `shutdown` does with each discovered daemon (pure; TS -/// `planShutdownAll`): orphan files go, unreachable ones only with `force`, -/// everything reachable is asked to stop. +/// What `shutdown` does with each discovered daemon (pure): orphan files go, +/// unreachable ones only with `force`, reachable ones are asked to stop. pub(crate) fn plan_shutdown_all(daemons: &[DaemonInfo], force: bool) -> Vec { daemons .iter() @@ -316,7 +312,7 @@ mod tests { } } -/// The confirmation decision for `shutdown` (TS `planShutdownConfirmation`). +/// The confirmation decision for `shutdown`. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub(crate) enum ShutdownConfirmationPlan { None, diff --git a/crates/pa-cli/src/daemon_discovery/scan.rs b/crates/pa-cli/src/daemon_discovery/scan.rs index c1e8073b7a5..ba743d49a71 100644 --- a/crates/pa-cli/src/daemon_discovery/scan.rs +++ b/crates/pa-cli/src/daemon_discovery/scan.rs @@ -1,9 +1,7 @@ -//! OS-level daemon discovery scans (TS `cli/daemon-ps.ts` scan half): the -//! listening-socket census (`ss` on Linux, `lsof` on macOS), the pid census, -//! and uptime enrichment. Parsing is pure and unit-tested against the exact -//! tool output shapes; the process spawning is Unix-only behind this module -//! (Windows daemons live on one named pipe per machine, so there is nothing -//! to sweep - TS returns [] there too). +//! OS-level daemon discovery scans: the listening-socket census (`ss` on +//! Linux, `lsof` on macOS), the pid census, and uptime enrichment. Parsing +//! is pure and unit-tested against the exact tool output shapes; the process +//! spawning is Unix-only (Windows daemons live on one named pipe per machine). use std::collections::HashMap; use std::path::{Path, PathBuf}; @@ -19,8 +17,8 @@ fn process_name_matches(name: &str, app_name: &str) -> bool { name == app_name || app_name.get(..MAX_COMM_LENGTH) == Some(name) } -/// Lexical socket identity (TS `normalizeSocketPath`): the absolute path, -/// without requiring the socket to exist. +/// Lexical socket identity: the absolute path, without requiring the +/// socket to exist. fn normalize_socket_path(path: &str) -> PathBuf { let absolute = Path::new(path); if absolute.is_absolute() { @@ -32,9 +30,8 @@ fn normalize_socket_path(path: &str) -> PathBuf { } } -/// Parse `ss -lxp` output into the product daemons listening on unix sockets -/// (TS `parseSsListeners`): LISTEN rows with a unix socket path and an owner -/// process named like the app. +/// Parse `ss -lxp` output into the product daemons listening on unix sockets: +/// LISTEN rows with a socket path and an owner named like the app. pub(crate) fn parse_ss_listeners(stdout: &str, app_name: &str) -> Vec { let mut daemons = Vec::new(); for line in stdout.split('\n') { @@ -73,8 +70,8 @@ fn ss_listener_owner(line: &str) -> Option<(&str, u32)> { Some((name, pid)) } -/// Parse `lsof -nP -F pn -U` output into listening unix socket owners, one -/// per (pid, socket) pair (TS `parseLsofListeners`). +/// Parse `lsof -nP -F pn -U` output into listening unix socket owners, +/// one per (pid, socket) pair. pub(crate) fn parse_lsof_listeners(stdout: &str) -> Vec { let mut daemons = Vec::new(); let mut seen = std::collections::HashSet::new(); @@ -101,8 +98,8 @@ pub(crate) fn parse_lsof_listeners(stdout: &str) -> Vec daemons } -/// Parse `ps -axo pid=,comm=,args=` output into pids whose command or argv0 -/// names this product (TS `parsePrimeAgentProcessIds`). +/// Parse `ps -axo pid=,comm=,args=` output into pids whose command or +/// argv0 names this product. pub(crate) fn parse_prime_agent_process_ids(stdout: &str, app_name: &str) -> Vec { let mut pids = Vec::new(); for line in stdout.split('\n') { @@ -133,8 +130,7 @@ pub(crate) fn parse_prime_agent_process_ids(stdout: &str, app_name: &str) -> Vec pids } -/// Parse `ps -o pid=,etimes=` output into a pid → uptime-seconds map -/// (TS `parsePsEtimes`). +/// Parse `ps -o pid=,etimes=` output into a pid → uptime-seconds map. pub(crate) fn parse_ps_etimes(stdout: &str) -> HashMap { let mut uptimes = HashMap::new(); for line in stdout.split('\n') { @@ -150,8 +146,8 @@ pub(crate) fn parse_ps_etimes(stdout: &str) -> HashMap { uptimes } -/// Run one command, capturing stdout; a missing tool or failure yields None -/// (TS `spawnSyncHidden` + error/status guards). +/// Run one command, capturing stdout; a missing tool or failure yields +/// `None`. fn capture_stdout(program: &str, args: &[&str]) -> Option { let output = std::process::Command::new(program) .args(args) @@ -165,7 +161,6 @@ fn capture_stdout(program: &str, args: &[&str]) -> Option { } } -/// Union of discovered processes by pid + socket (TS `mergeDiscoveredDaemonProcesses`). pub(crate) fn merge_discovered( groups: &[Vec], ) -> Vec { @@ -178,20 +173,12 @@ pub(crate) fn merge_discovered( by_identity.into_values().collect() } -/// Parse `/proc/net/unix` rows into (inode, path) pairs for *listening* -/// unix sockets: the accept-connections flag `SS_ACCEPTCONN` (kernel -/// include/uapi/linux/net.h, hex `00010000`) plus a filesystem path. -/// Format: `Num RefCount Protocol Flags Type St Inode Path`. -/// -/// Byte-level on purpose: a unix socket pathname may contain any byte -/// sequence (unix(7) — one non-UTF-8 name anywhere in the file must not -/// reject the whole census), and it may contain spaces. The kernel pads -/// the fixed columns with runs of spaces, so the seven columns scan with -/// padding collapsed and the path keeps the whole row remainder. A row -/// whose pathname is not valid UTF-8 drops out on its own (product socket -/// paths are UTF-8; the rest of the census stands). The header row fails -/// the hex flag parse and drops out; unnamed and non-listening rows (no -/// path, or no `SS_ACCEPTCONN`) drop out too. +/// Parse `/proc/net/unix` rows into (inode, path) pairs for *listening* unix +/// sockets: the accept-connections flag `SS_ACCEPTCONN` (hex `00010000`) +/// plus a filesystem path. Byte-level on purpose: a socket pathname may +/// contain any byte sequence and spaces, so the seven columns scan with +/// padding collapsed and the path keeps the row remainder; invalid UTF-8, +/// header, and unnamed/non-listening rows drop out on their own. #[cfg(target_os = "linux")] fn parse_proc_net_unix(bytes: &[u8]) -> Vec<(String, String)> { const SS_ACCEPTCONN: u32 = 0x0001_0000; @@ -234,7 +221,6 @@ fn parse_proc_net_unix(bytes: &[u8]) -> Vec<(String, String)> { listeners } -/// Skip leading ASCII whitespace bytes. #[cfg(target_os = "linux")] fn skip_ascii_whitespace(bytes: &[u8]) -> &[u8] { let start = bytes @@ -244,8 +230,6 @@ fn skip_ascii_whitespace(bytes: &[u8]) -> &[u8] { &bytes[start..] } -/// Split the first whitespace-terminated token from the front of the row: -/// the token, and the bytes after it (None when the row is exhausted). #[cfg(target_os = "linux")] fn split_first_token(bytes: &[u8]) -> Option<(&[u8], &[u8])> { if bytes.is_empty() { @@ -258,11 +242,9 @@ fn split_first_token(bytes: &[u8]) -> Option<(&[u8], &[u8])> { Some((&bytes[..end], &bytes[end..])) } -/// Every live process and the unix-socket inodes it holds, from -/// `/proc//fd/*` symlinks shaped `socket:[]`, with the pid's -/// `/proc//comm` name. Ascending pid order keeps the census -/// deterministic; processes whose fd directory or comm cannot be read -/// (permission, or the process exited mid-scan) are skipped silently. +/// Every live process and the unix-socket inodes it holds, from `/proc//fd/*` +/// symlinks shaped `socket:[]`, with the pid's comm name (ascending pid +/// order keeps the census deterministic). #[cfg(target_os = "linux")] fn proc_socket_inodes() -> Vec<(u32, String, std::collections::HashSet)> { let mut processes = Vec::new(); @@ -302,15 +284,10 @@ fn proc_socket_inodes() -> Vec<(u32, String, std::collections::HashSet)> processes } -/// The dependency-free Linux listening census (operator-mandated fallback -/// for tool-less root-user systems): map -/// `/proc/net/unix` listeners to their owning pids and keep those whose -/// comm name is this product. Visibility matches `ss -lxp`: uid 0 sees -/// every daemon on the machine, an unprivileged user only its own — other -/// users' `/proc//fd` is unreadable, exactly the pid info `ss` hides -/// from non-root callers. TS has no equivalent fallback (`daemon-ps.ts` -/// yields nothing without `ss`/`lsof`), so the three discovery e2e tests -/// fail on stock root-user Linux images that ship neither tool. +/// The dependency-free Linux listening census (operator-mandated fallback for +/// tool-less root-user systems): map `/proc/net/unix` listeners to their +/// owning pids and keep those whose comm name is this product. Visibility +/// matches `ss -lxp`; TS has no equivalent fallback. #[cfg(target_os = "linux")] fn scan_proc_listeners(app_name: &str) -> Vec { let Ok(unix) = std::fs::read("/proc/net/unix") else { @@ -344,7 +321,6 @@ fn scan_proc_listeners(_app_name: &str) -> Vec { Vec::new() } -/// Attach `ps` uptimes to the discovered daemons (TS `enrichUptimes`). fn enrich_uptimes(mut daemons: Vec) -> Vec { if daemons.is_empty() { return daemons; @@ -363,13 +339,11 @@ fn enrich_uptimes(mut daemons: Vec) -> Vec Vec { if let Some(stdout) = capture_stdout("ss", &["-lxp"]) { return parse_ss_listeners(&stdout, app_name); @@ -419,9 +390,7 @@ fn scan_listening_daemons_machine_wide(app_name: &str) -> Vec i32 { let daemons = discover_daemons(root); let mut reaped: Vec<(String, String)> = Vec::new(); @@ -74,9 +69,8 @@ pub(crate) fn run_reap(json: bool, root: &DaemonStateRoot) -> i32 { } } ReapActionKind::Kill => { - // Re-probe right before killing: a daemon classified - // unreachable at discovery may have started answering; never - // signal one that now responds. + // Re-probe right before killing: a daemon classified unreachable at + // discovery may have started answering; never signal one that responds. if probe_daemon(&action.daemon.socket_path).reachable { apply( reap_reachable_daemon(&action.daemon.socket_path, pid), @@ -111,8 +105,8 @@ pub(crate) fn run_reap(json: bool, root: &DaemonStateRoot) -> i32 { 0 } -/// Ask a reachable daemon to stop, but only after a fresh probe confirms it -/// is idle (TS `reapReachableDaemon`). +/// Ask a reachable daemon to stop, but only after a fresh probe confirms +/// it is idle. fn reap_reachable_daemon(socket_path: &Path, pid: Option) -> StopOutcome { let probe = probe_daemon(socket_path); if !probe.reachable { @@ -152,9 +146,8 @@ fn apply( } } -/// `shutdown` (TS `runShutdownAll` + `runShutdownAllConverging`). Returns the -/// process exit code: 1 when anything failed (or the JSON confirmation -/// error), 0 otherwise. +/// `shutdown`. Returns the process exit code: 1 when anything failed +/// (or the JSON confirmation error), 0 otherwise. pub(crate) fn run_shutdown_all(json: bool, force: bool, root: &DaemonStateRoot) -> i32 { let daemons = discover_daemons(root); match plan_shutdown_confirmation( @@ -178,10 +171,8 @@ pub(crate) fn run_shutdown_all(json: bool, force: bool, root: &DaemonStateRoot) 1 } ShutdownConfirmationPlan::TtyError => { - // TS throws this out of `runShutdownAll` and the public-command - // wrapper turns the throw into the standard `Error: …` failure - // (stderr + exit 1); only reachable once there are daemons to - // stop, so an empty machine shuts down cleanly without a TTY. + // The public-command wrapper turns the throw into the standard `Error: …` + // failure (stderr + exit 1); only reachable once there are daemons to stop. eprintln!( "Error: Shutdown requires confirmation in an interactive terminal. Use \"prime-agent shutdown --force\"." ); @@ -200,8 +191,8 @@ pub(crate) fn run_shutdown_all(json: bool, force: bool, root: &DaemonStateRoot) } } -/// TS `runShutdownAllConverging`: run the planned actions, then (with -/// `force`) sweep residuals until the listener set quiets down. +/// Run the planned actions, then (with `force`) sweep residuals until +/// the listener set quiets down. fn run_shutdown_converging(json: bool, force: bool, root: &DaemonStateRoot) -> i32 { let mut stopped: Vec<(String, String)> = Vec::new(); let mut failed: Vec<(String, String)> = Vec::new(); @@ -326,8 +317,7 @@ fn run_shutdown_converging(json: bool, force: bool, root: &DaemonStateRoot) -> i terminate_verified_residuals(root, &mut stopped, &mut failed, &handled_pids); } - // The exit code follows the failures in both output modes (TS sets - // process.exitCode = 1 for any failed stop). + // The exit code follows the failures in both output modes. if json { println!("{}", shutdown_report_json(&stopped, &failed)); return i32::from(!failed.is_empty()); @@ -348,8 +338,7 @@ fn apply_stop( } } -/// Stop one daemon gracefully, escalating only with `force` (TS -/// `stopBackgroundService`). +/// Stop one daemon gracefully, escalating only with `force`. fn stop_background_service( socket_path: &Path, pid: Option, @@ -385,10 +374,9 @@ fn stop_background_service( /// Verified force-kill for one daemon (the supervisor-side contract the /// worker-side `stop_tracked_process` already implements): the pid joins -/// `handled_pids` and the socket file is removed only on confirmed death — -/// a daemon that survives SIGKILL is reported as failed, with its socket -/// file deliberately kept so the invisible listener stays discoverable -/// for the `--force` residual sweep and the doctor's re-probe. +/// `handled_pids` and the socket file is removed only on confirmed death — a +/// survivor of SIGKILL is reported failed, its socket file kept so the +/// invisible listener stays discoverable for the sweep and the doctor. fn verified_force_kill( pid: u32, socket_path: &Path, @@ -406,8 +394,7 @@ fn verified_force_kill( } /// Ask the daemon to stop and confirm it actually stopped listening: the ack -/// alone is not proof, so success is reported only once the socket stops -/// accepting connections (TS `shutdownDaemon`). +/// alone is not proof; success only once the socket stops accepting. fn shutdown_daemon(socket_path: &Path, force: bool) -> bool { let Ok(mut client) = crate::daemon_client::DaemonClient::connect_probe(socket_path) else { return false; @@ -431,7 +418,7 @@ fn shutdown_daemon(socket_path: &Path, force: bool) -> bool { false } -/// `promptYesNo`: empty or anything-but-yes resolves false (default No). +/// Empty or anything-but-yes resolves false (default No). pub(crate) fn prompt_yes_no(message: &str) -> bool { use std::io::Write as _; print!("{message} [y/N] "); @@ -444,8 +431,8 @@ pub(crate) fn prompt_yes_no(message: &str) -> bool { normalized == "y" || normalized == "yes" } -/// One acted-on service in the JSON reports (TS prints the socket path -/// first, then the action, or the reason on failure). +/// One acted-on service in the JSON reports: the socket path first, +/// then the action, or the reason on failure. #[derive(Serialize)] #[serde(rename_all = "camelCase")] struct ActionEntry { @@ -460,7 +447,7 @@ struct ReasonEntry { reason: String, } -/// The reap JSON report (TS prints `{reaped, skipped}` in that order). +/// The reap JSON report, `{reaped, skipped}` in that order. #[derive(Serialize)] #[serde(rename_all = "camelCase")] struct ReapReport { @@ -468,7 +455,7 @@ struct ReapReport { skipped: Vec, } -/// The shutdown JSON report (TS prints `{stopped, failed}` in that order). +/// The shutdown JSON report, `{stopped, failed}` in that order. #[derive(Serialize)] #[serde(rename_all = "camelCase")] struct ShutdownReport { @@ -541,8 +528,6 @@ mod tests { } StopOutcome::Skipped(reason) => panic!("expected a reaped outcome, got {reason}"), } - // Only the confirmed death joins the handled set and unlinks the - // socket (the contract this helper enforces). assert!(handled_pids.contains(&pid)); assert!( !socket_path.exists(), @@ -553,9 +538,8 @@ mod tests { #[test] fn shutdown_report_json_pins_the_failure_shape() { - // Every failure path funnels into this report (TS prints - // `{stopped, failed}`); the shape is the `--json` contract, so a - // survived SIGKILL must surface as a `failed` reason entry. + // Every failure path funnels into this report; a survived + // SIGKILL must surface as a `failed` reason entry. let report = serde_json::from_str::(&shutdown_report_json( &[], &[( diff --git a/crates/pa-cli/src/daemon_mode.rs b/crates/pa-cli/src/daemon_mode.rs index dbfb29af638..1a82729a4d3 100644 --- a/crates/pa-cli/src/daemon_mode.rs +++ b/crates/pa-cli/src/daemon_mode.rs @@ -1,13 +1,10 @@ -//! `--mode daemon`: the supervisor process. The interactive client spawns -//! this mode (detached) when no daemon is listening, so `prime-agent` alone -//! is enough to bring the full session stack up (port of the TS -//! `daemon-mode.ts` entry: the CLI process becomes the supervisor). +//! `--mode daemon`: the supervisor process. The interactive client spawns this +//! mode (detached) when no daemon is listening. use anyhow::Result; use crate::config; -/// Run the daemon supervisor in-process until it shuts down. pub fn run_daemon_mode(daemon_socket: Option<&str>) -> Result { let socket_path = config::resolve_daemon_socket_path(daemon_socket); let agent_dir = config::get_agent_dir(); diff --git a/crates/pa-cli/src/daemon_session_list.rs b/crates/pa-cli/src/daemon_session_list.rs index 83954583426..5806d28e208 100644 --- a/crates/pa-cli/src/daemon_session_list.rs +++ b/crates/pa-cli/src/daemon_session_list.rs @@ -1,17 +1,14 @@ -//! Session-list rendering for the `list` command: summary validation, display -//! ids, and the fixed-column table, ported from `cli/daemon-list-format.ts`, -//! `core/session-id.ts`, and the summary guards in `cli/daemon-command.ts`. +//! Session-list rendering for the `list` command: summary validation, +//! display ids, and the fixed-column table. use serde_json::Value; use std::time::{SystemTime, UNIX_EPOCH}; -/// 12-char display id, mirroring `DISPLAY_ID_LENGTH`. const DISPLAY_ID_LENGTH: usize = 12; /// Display order for the status column. const LIST_STATUS_ORDER: [&str; 3] = ["working", "idle", "archived"]; -/// A validated session summary row ready for the table. #[derive(Debug, Clone, PartialEq)] pub(crate) struct SessionSummary { id: String, @@ -46,8 +43,8 @@ impl SessionSummary { } } -/// `isSessionSummary`: a structural guard so malformed daemon rows fall back -/// to raw JSON output exactly like the TS client. +/// A structural guard so malformed daemon rows fall back to raw JSON +/// output. fn is_session_summary(value: &Value) -> bool { if !value.is_object() { return false; @@ -88,7 +85,7 @@ fn pointer<'a>(value: &'a Value, path: &str) -> Option<&'a Value> { .try_fold(value, |current, key| current.get(key)) } -/// `isLiveSessionSummary`: a session summary with a routable active id. +/// A session summary with a routable active id. fn is_live_session_summary(value: &Value) -> bool { is_session_summary(value) && string_field(value, "activeSessionId").is_some() } @@ -116,9 +113,8 @@ fn session_summary_from_value(value: &Value) -> Option { }) } -/// `getSessionSummaries` for surfaces that read the wire rows directly (the -/// sessions table): `Some(rows)` when every row validates, else `None` so -/// the caller prints raw JSON like the TS client. +/// `Some(rows)` when every row validates, else `None` so the caller +/// prints raw JSON (for surfaces that read the wire rows directly). pub(crate) fn validated_session_values(data: &Value) -> Option> { let sessions = data.get("sessions")?.as_array()?; sessions @@ -127,8 +123,8 @@ pub(crate) fn validated_session_values(data: &Value) -> Option> { .collect() } -/// `getSessionSummaries`: `Some(rows)` when every row validates, else `None` -/// so the caller prints raw JSON like the TS client. +/// `getSessionSummaries` for wire-row surfaces: `Some(rows)` when every +/// row validates, else `None`. pub(crate) fn get_session_summaries(data: &Value) -> Option> { validated_session_values(data)? .iter() @@ -136,14 +132,13 @@ pub(crate) fn get_session_summaries(data: &Value) -> Option> .collect() } -/// `isLiveSessionSummary` as a public guard for create/rename output paths. +/// A public guard for create/rename output paths. pub(crate) fn live_session_summary(data: &Value) -> Option<&Value> { is_live_session_summary(data).then_some(data) } -/// The shared CLI table renderer (TS `formatTable`): every column pads to -/// the widest cell's terminal display width, so a wide glyph (CJK, emoji) -/// cannot drift the columns after it. Two spaces separate columns. +/// The shared CLI table renderer (TS `formatTable`): every column pads to the widest +/// cell's terminal display width, so a wide glyph cannot drift the columns after it. pub(crate) fn format_table(headers: &[&str; N], rows: &[[String; N]]) -> String { let widths: [usize; N] = std::array::from_fn(|column| { rows.iter() @@ -156,9 +151,8 @@ pub(crate) fn format_table(headers: &[&str; N], rows: &[[String; row.iter() .zip(widths) .map(|(cell, width)| { - // TS `padCell`: pad only, never truncate — a cell wider - // than its column (an unsanitized ANSI name) renders whole - // like TS, its escape bytes skipped by both measures. + // Pad only, never truncate — a wider cell renders whole; its + // escape bytes are skipped by both measures. let pad = width.saturating_sub(pa_tui::width::str_width(cell)); format!("{cell}{}", " ".repeat(pad)) }) @@ -178,8 +172,7 @@ const LIST_HEADERS: [&str; 7] = [ "name", "id", "status", "age", "model", "messages", "clients", ]; -/// The fixed-column table, mirroring `formatSessionListTable` (colors are -/// TTY-only in TS; this output is color-free like TS piped output). +/// The fixed-column table; color-free like TS piped output. pub(crate) fn format_session_list_table(sessions: &[SessionSummary]) -> String { let now = now_ms(); let mut sorted: Vec<&SessionSummary> = sessions.iter().collect(); @@ -205,7 +198,7 @@ pub(crate) fn format_session_list_table(sessions: &[SessionSummary]) -> String { format_table(&LIST_HEADERS, &rows) } -/// `formatSessionDisplayId`: the last 12 chars of a hex-normalized id. +/// The last 12 chars of a hex-normalized id. pub(crate) fn format_session_display_id(id: &str) -> String { let normalized = normalize_session_id(id); if is_hex(&normalized) { @@ -214,7 +207,7 @@ pub(crate) fn format_session_display_id(id: &str) -> String { tail(id, DISPLAY_ID_LENGTH) } -/// `matchesSessionIdSuffix`: hex-suffix matching for short selectors. +/// Hex-suffix matching for short selectors. pub(crate) fn matches_session_id_suffix(candidate: &str, suffix: &str) -> bool { let normalized_candidate = normalize_session_id(candidate); let normalized_suffix = normalize_session_id(suffix); @@ -240,7 +233,7 @@ fn tail(value: &str, length: usize) -> String { } } -/// `formatSessionAge`: `s|m|h|d|w|y` bucketing from the modified timestamp. +/// `s|m|h|d|w|y` bucketing from the modified timestamp. pub(crate) fn format_session_age(modified: Option<&str>, now_ms: u64) -> String { let Some(modified) = modified else { return String::new(); @@ -272,7 +265,7 @@ pub(crate) fn format_session_age(modified: Option<&str>, now_ms: u64) -> String } /// RFC 3339 timestamp to epoch milliseconds, the subset `new Date(text)` -/// accepts for daemon timestamps (UTC `Z`-suffixed ISO strings). +/// accepts (UTC `Z`-suffixed ISO strings). pub(crate) fn parse_iso_ms(text: &str) -> Option { let text = text.trim(); let (date, rest) = text.split_once('T')?; diff --git a/crates/pa-cli/src/file_processor.rs b/crates/pa-cli/src/file_processor.rs index 370189fb159..13d0b2ebf22 100644 --- a/crates/pa-cli/src/file_processor.rs +++ b/crates/pa-cli/src/file_processor.rs @@ -1,23 +1,15 @@ -//! `@file` argument expansion for the initial prompt, ported from -//! `cli/file-processor.ts` (`processFileArguments`): each argument becomes -//! either a `` text block or a base64 image attachment. -//! -//! The image path is the `utils/mime.ts` sniff (magic bytes, never the -//! extension) plus the same 4.5MB inline limit TS enforces on the base64 -//! payload. TS resizes oversized images through its Photon converter; this -//! build has no resize engine, so an oversized image under the auto-resize -//! setting falls back to the converter-unavailable text TS emits -//! (`[Image omitted: ...]`) instead of attaching an unusable payload. With -//! auto-resize off, TS attaches the raw payload regardless of size, and so -//! does this path. +//! `@file` argument expansion for the initial prompt: each argument becomes +//! either a `` text block or a base64 image attachment (the +//! magic-byte sniff, never the extension, plus the same 4.5MB inline limit). +//! No resize engine: an oversized image under auto-resize falls back to the +//! converter-unavailable text (`[Image omitted: ...]`) TS emits. use std::fmt::Write as _; use std::path::{Path, PathBuf}; use pa_agent::types::ImageContent; -/// TS `DEFAULT_MAX_BYTES`: 4.5MB of base64 payload, headroom below the -/// provider's 5MB limit. +/// 4.5MB of base64 payload, headroom below the provider's 5MB limit. const DEFAULT_MAX_BYTES: usize = 4_500_000; /// The expanded first prompt: @file text blocks joined into one string, @@ -28,18 +20,16 @@ pub struct ProcessedFiles { pub images: Vec, } -/// A file-argument failure: the exact stderr line TS prints before -/// `process.exit(1)`. +/// A file-argument failure: the exact stderr line printed before exit 1. #[derive(Debug, Clone, PartialEq)] pub struct FileProcessingError { pub message: String, } -/// Expand the `@file` arguments (TS `processFileArguments`): every -/// argument resolves against the cwd (with the TS macOS filename -/// variants), a missing file fails the run, an empty file is skipped, an -/// image attaches as base64, and anything else embeds as a `` -/// text block. +/// Expand the `@file` arguments: every argument resolves against the +/// cwd (with the TS macOS filename variants), a missing file fails the +/// run, an empty file is skipped, an image attaches as base64, and +/// anything else embeds as a `` text block. pub fn process_file_arguments( file_args: &[String], cwd: &Path, @@ -72,9 +62,8 @@ pub fn process_file_arguments( }); let _ = writeln!(processed.text, ""); } - // Not an image: embed the content in a file block. Node's - // utf-8 read decodes invalid sequences lossily (U+FFFD), so - // binary non-image files embed instead of failing the run. + // Not an image: embed the content in a file block (Node's utf-8 read decodes + // invalid sequences lossily, so binary non-image files embed instead of failing). Ok(None) => { let bytes = std::fs::read(&absolute_path).map_err(|error| FileProcessingError { message: format!("Error: Could not read file {resolved}: {error}"), diff --git a/crates/pa-cli/src/global_flags.rs b/crates/pa-cli/src/global_flags.rs index f8e84484dee..89ce1760b92 100644 --- a/crates/pa-cli/src/global_flags.rs +++ b/crates/pa-cli/src/global_flags.rs @@ -1,6 +1,5 @@ -//! Leading global-flag scanning, ported from `cli/global-flags.ts`. Both the -//! public command router and the arg parser must agree on which token is the -//! subcommand, so flag consumption mirrors `parse_args` exactly. +//! Leading global-flag scanning. Both the public command router and the arg +//! parser must agree on which token is the subcommand. use std::collections::HashSet; @@ -30,9 +29,7 @@ pub const GLOBAL_VALUE_FLAGS: [&str; 22] = [ "--autonomous-timeout-ms", ]; -/// Value flags that also appear in `GLOBAL_VALUE_FLAGS`. const FREEFORM_VALUE_FLAGS: [&str; 2] = ["--goal", "--autonomous-gate"]; -/// Prompt value flags whose text may look like a long option. const PROMPT_VALUE_FLAGS: [&str; 2] = ["--system-prompt", "--append-system-prompt"]; /// Flags that mark a one-shot prompt run; their positional is a message. @@ -54,8 +51,6 @@ const GLOBAL_BOOLEAN_FLAGS: [&str; 11] = [ "--offline", ]; -/// True when parseArgs consumes the token after `args[index]` as part of the -/// flag at `args[index]`, mirroring `consumesFollowingToken` in global-flags.ts. fn consumes_following_token(args: &[String], index: usize) -> bool { let Some(next) = args.get(index + 1) else { return false; @@ -87,7 +82,6 @@ fn consumes_following_token(args: &[String], index: usize) -> bool { && !next.starts_with('@') } -/// The first positional argument, skipping global flags the way parseArgs does. #[derive(Debug, Clone, PartialEq, Eq)] pub struct FirstPositionalArgument { pub index: usize, @@ -96,7 +90,6 @@ pub struct FirstPositionalArgument { pub after_separator: bool, } -/// Find the first positional argument, mirroring `findFirstPositionalArgument`. pub fn find_first_positional_argument(args: &[String]) -> Option { let mut index = 0; while index < args.len() { @@ -140,10 +133,10 @@ pub fn is_command_positional( } } -/// Move leading global flags behind the subcommand they were written in front -/// of, mirroring `rotateGlobalFlagsBeforeCommand`. Arguments are returned -/// unchanged when no known command is present, when `--` already escaped the -/// token, and for one-shot prompt runs. +/// Move leading global flags behind the subcommand they were written in +/// front of. Arguments are returned unchanged when no known command is +/// present, when `--` already escaped the token, and for one-shot prompt +/// runs. pub fn rotate_global_flags_before_command( args: &[String], public_commands: &HashSet<&str>, @@ -183,8 +176,7 @@ pub fn rotate_global_flags_before_command( } /// The command path a `help` request names, with global run flags (and their -/// values) excluded, mirroring `extractHelpCommandPath`. Returns `None` when -/// the tail contains `--` or a bare explicit `--help`/`-h`. +/// values) excluded. Returns `None` on `--` or a bare `--help`/`-h`. pub fn extract_help_command_path(args: &[String], from: usize) -> Option> { let mut path: Vec = Vec::new(); let mut index = from; diff --git a/crates/pa-cli/src/headless_autonomous.rs b/crates/pa-cli/src/headless_autonomous.rs index 47a1800dd81..cd5a2919a09 100644 --- a/crates/pa-cli/src/headless_autonomous.rs +++ b/crates/pa-cli/src/headless_autonomous.rs @@ -1,14 +1,8 @@ //! The autonomous run state for headless print/json runs — the verifier and -//! eval composition surface. CLI autonomous flags build the run state (TS -//! `runtimeAutonomousConfigFromArgs`); after every settled model turn the -//! [`ShellAutonomousDriver`] runs the configured gate commands in the -//! session cwd (the #98 seams, reused unmodified). The continuation itself -//! rides the agent's natural-turn-end hook -//! ([`crate::print_autonomous`], the TS in-run shape): continuations land -//! as durable user rows churned inside the one prompt wait, and a stop -//! surfaces only through the process exit code and its stderr line (the TS -//! print-mode contract, `print-mode.ts` + the selection half of -//! `headless-completion.ts`, which live in pa-core). +//! eval composition surface. After every settled turn the [`ShellAutonomousDriver`] +//! runs the gate commands in the session cwd (the #98 seams, unmodified); the +//! continuation rides the natural-turn-end hook ([`crate::print_autonomous`]), +//! a stop surfaces only through the exit code and its stderr line. use std::path::PathBuf; use std::sync::Arc; @@ -25,8 +19,8 @@ use pa_types::session::CustomMessage; use crate::args::AutonomousConfig; -/// The autonomous runtime config from the typed CLI flags (TS -/// `runtimeAutonomousConfigFromArgs`: any autonomous flag enables the run). +/// The autonomous runtime config from the typed CLI flags: any +/// autonomous flag enables the run. pub fn autonomous_runtime_config(config: &AutonomousConfig) -> AgentAutonomousConfig { AgentAutonomousConfig { enabled: Some(true), @@ -47,16 +41,12 @@ pub fn autonomous_runtime_config(config: &AutonomousConfig) -> AgentAutonomousCo } } -/// One headless autonomous run: the runtime state plus the shell-gate -/// driver, shared with the per-message accounting subscription, the in-run -/// continuation hook, and the session-command executor (`/autonomous` -/// rewrites the same state live). +/// One headless autonomous run: the runtime state plus the shell-gate driver. pub struct HeadlessAutonomous { state: Arc>, driver: ShellAutonomousDriver, - /// The continuation the threshold arm minted ahead of its compaction - /// (TS `_queueAutonomousContinuationForThresholdCompaction`): held for - /// the settled boundary's queued `followUp` admission. + /// The continuation the threshold arm minted ahead of its compaction, + /// held for the settled boundary's queued `followUp` admission. held: tokio::sync::Mutex>, } @@ -68,9 +58,8 @@ impl HeadlessAutonomous { Self::from_state(state, cwd) } - /// The session's default run (TS `createAgentSession` always carries an - /// autonomous state; a print run without CLI flags starts disabled, and - /// `/autonomous on` rewrites it live). + /// The session's default run: a print run without CLI flags starts + /// disabled, and `/autonomous on` rewrites it live. pub fn disabled(cwd: impl Into) -> Self { let state = create_autonomous_runtime_state(None, None); Self::from_state(state, cwd) @@ -90,9 +79,8 @@ impl HeadlessAutonomous { Arc::clone(&self.state) } - /// Per-message usage accounting: every settled assistant message is - /// forwarded to the driver as it arrives (the daemon worker runs the - /// same policy through its own subscription). + /// Per-message usage accounting: every settled assistant message forwards to + /// the driver as it arrives (the daemon worker runs the same policy). pub async fn wire_accounting( &self, agent: &Arc, @@ -124,12 +112,8 @@ impl HeadlessAutonomous { .await } - /// The in-run continuation decision for one settled turn (TS - /// `nextAutonomousContinuation` inside `_getContinuationMessages`): - /// the driver decides, a `Continue` returns the continuation text, a - /// stop (or an inactive mode) ends the loop. The budget bump rides - /// the driver's decision (the caller owns the admission: the in-run - /// hook runs the text as the next turn, the threshold arm holds it). + /// The in-run continuation decision for one settled turn: the driver decides, + /// `Continue` returns the text, a stop (or inactive mode) ends the loop. pub(crate) async fn follow_up_text( &self, message: &pa_agent::types::AssistantMessage, @@ -145,22 +129,14 @@ impl HeadlessAutonomous { } } - /// Hold the continuation the threshold arm minted ahead of its - /// compaction (TS `_queueAutonomousContinuationForThresholdCompaction` - /// queues it as a `followUp` admission): the print boundary compacts - /// at the settled turn, then [`HeadlessAutonomous::drive_boundary`] - /// admits the held turn through the boundary pair. + /// Hold the continuation the threshold arm minted ahead of its compaction; the + /// boundary compacts at the settled turn, then `drive_boundary` admits it. pub(crate) async fn hold_threshold_continuation(&self, text: String) { *self.held.lock().await = Some(text); } - /// The settled boundary's autonomous drain (the print driver's queue - /// loop, the TS queued `followUp` admission): each held continuation - /// runs as this invocation's follow-up turn through the boundary pair - /// (the pre-turn compaction arm runs before it, the settled-turn arms - /// after it), and its own natural end churns the in-run hook again — - /// a re-crossing threshold holds the next continuation for the next - /// drain. + /// The settled boundary's autonomous drain: each held continuation runs as + /// this invocation's follow-up turn; a re-crossing threshold holds the next. #[allow(clippy::too_many_arguments)] pub(crate) async fn drive_boundary( &self, @@ -184,10 +160,10 @@ impl HeadlessAutonomous { Ok(()) } - /// The TS print-mode exit contract: stderr text when the run must exit - /// non-zero — a configured gate still failing (after its retry window, - /// or with an autonomous limit reached), or an autonomous run without - /// gates that stopped before terminal evidence. + /// The print-mode exit contract: stderr text when the run must exit + /// non-zero — a configured gate still failing (after its retry window or + /// an autonomous limit), or an ungated run stopping before terminal + /// evidence. pub async fn exit_stderr(&self) -> Option { let state = self.state.lock().await; let status = autonomous_status(&state); @@ -226,7 +202,6 @@ impl HeadlessAutonomous { } } -/// The latest settled assistant message of the loop state, if any. async fn latest_assistant(engine: &SessionEngine) -> Option { let state = engine.session.agent().state().await; state @@ -241,9 +216,8 @@ async fn latest_assistant(engine: &SessionEngine) -> Option Option> { latest_assistant(engine).await.and_then(|message| { (message.stop_reason == pa_types::ai::StopReason::Error) diff --git a/crates/pa-cli/src/incident/mod.rs b/crates/pa-cli/src/incident/mod.rs index ff8a99489ef..88f44e20b15 100644 --- a/crates/pa-cli/src/incident/mod.rs +++ b/crates/pa-cli/src/incident/mod.rs @@ -1,13 +1,8 @@ //! `prime-agent incident`: reconstructs what the daemon did during a time -//! window from its diagnostic logs (the CLI half of TS `src/cli/incident.ts`; -//! the shared classifier lives in `pa_types::incident`, imported by both -//! this command and the agents-view notice). -//! -//! The primary source is the shared structured log -//! (`~/.prime/agent/logs/agent.jsonl`, plus its `.old` rotation); when -//! that file is missing, empty, or unreadable, the newest per-daemon log -//! (`~/.prime/agent/logs/..log`, plain-text lines) is used -//! as a fallback. +//! window from its diagnostic logs (the shared classifier lives in +//! `pa_types::incident`). The primary source is the shared structured log +//! (`~/.prime/agent/logs/agent.jsonl` plus its `.old` rotation); when it is +//! missing, empty, or unreadable, the newest per-daemon log is the fallback. pub(crate) mod report; pub(crate) mod time; @@ -19,10 +14,9 @@ use pa_types::incident::{ }; use std::path::{Path, PathBuf}; -/// TS `DEFAULT_WINDOW_MS`: the default `--since` is 24 hours ago. +/// The default `--since` is 24 hours ago. const DEFAULT_WINDOW_MS: i64 = 24 * 60 * 60 * 1000; -/// The parsed `incident` arguments (TS `IncidentCommandOptions`). #[derive(Debug, Clone, Default, PartialEq, Eq)] pub(crate) struct IncidentCommandOptions { pub(crate) since: Option, @@ -30,8 +24,7 @@ pub(crate) struct IncidentCommandOptions { pub(crate) session: Option, } -/// A usage error carrying the operator-facing message (TS -/// `IncidentUsageError`). +/// A usage error carrying the operator-facing message. #[derive(Debug, Clone, PartialEq, Eq)] pub(crate) struct IncidentUsageError(pub(crate) String); @@ -43,20 +36,17 @@ impl std::fmt::Display for IncidentUsageError { impl std::error::Error for IncidentUsageError {} -/// The resolved `--since`/`--until` window (TS `IncidentWindow`). #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub(crate) struct IncidentWindow { pub(crate) since_ms: i64, pub(crate) until_ms: i64, } -/// Parse `incident [--since