fix(volcengine): scope assistant placeholder by endpoint

[Ingwannu]

Summary

Fixes #1571 by separating the two Volcengine Ark Chat endpoint contracts.

The #796 workaround previously matched only the Ark hostname and therefore sent its inferred structured empty assistant placeholder to both:

• pay-as-you-go Chat: /api/v3
• Coding Plan Chat: /api/coding/v3

Live evidence in #1571 shows that Coding Plan accepts content: "" and rejects [{"type":"text","text":""}] for a tool-call continuation. This patch keeps the structured placeholder only on recognized Ark hosts at the exact normalized /api/v3 base path. Coding Plan and unrelated paths retain the ordinary empty string.

Why this shape

Model IDs cannot identify the wire contract because the same model family can appear behind different Ark products. Removing the workaround globally would reopen the still-distinct #796 contract. The base endpoint family is the narrow boundary supported by the available evidence.

The architecture note records this decision and its tradeoffs.

Validation

Exact head 52b1bef7e05aef23711e82cbbc672702943d3c2a:

• bun test tests/volcengine-ark-assistant-content.test.ts — 8 pass, 0 fail
• bun run typecheck — pass
• bun run privacy:scan — pass
• git diff --check — pass

A CPU-limited full-suite run reached this change's focused coverage but later encountered unrelated environment/timeout failures: the ambient OPENCODEX_API_AUTH_TOKEN overrode an isolated shim fixture, and several existing long-running history/credential-sidecar tests timed out under the two-core limit. The isolated shim test passes when that ambient variable is removed. Exact-head repository CI remains required before merge.

Summary by CodeRabbit

• Bug Fixes

  • Improved Volcengine Ark endpoint detection for assistant continuation handling.
  • Standard Ark endpoints now receive the correct structured placeholder, while Coding Plan endpoints retain empty assistant content.
  • Prevented Ark-specific formatting from being applied to unrelated hosts or paths.

• Documentation

  • Documented the endpoint-specific assistant content behavior.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 64febb71-5853-460c-8d88-e1b7a3d4122f

📥 Commits

Reviewing files that changed from the base of the PR and between 872c526 and 52b1bef.

📒 Files selected for processing (3)

• src/adapters/openai-chat.ts
• structure/04_transports-and-sidecars.md
• tests/volcengine-ark-assistant-content.test.ts

---

📝 Walkthrough

Walkthrough

The adapter now applies the structured empty assistant-content placeholder only to recognized Volcengine Ark pay-as-you-go endpoints using /api/v3. Coding Plan and unrelated host or path configurations retain empty-string content. Tests and documentation cover these contracts.

Changes

Volcengine Ark assistant-content handling

Layer / File(s)	Summary
Endpoint-specific Ark detection src/adapters/openai-chat.ts:675-686	The adapter replaces hostname-only detection with normalized path and host checks. The structured placeholder applies only to the /api/v3 pay-as-you-go endpoint.
Continuation contract and regression coverage tests/volcengine-ark-assistant-content.test.ts:12-14, tests/volcengine-ark-assistant-content.test.ts:26, tests/volcengine-ark-assistant-content.test.ts:84-89, tests/volcengine-ark-assistant-content.test.ts:103-116, structure/04-transports-and-sidecars.md:590-605	Tests cover the /api/coding/v3 Coding Plan endpoint, lookalike hosts, unrelated paths, and empty-string content. Documentation records the endpoint-specific continuation payloads.

Estimated code review effort: 2 (Simple) | ~10 minutes

Mergeability Score: ⚪ Minimal · up to 52b1b

The change narrows the Volcengine assistant placeholder behavior to the intended endpoint while preserving the existing contract elsewhere. No actionable merge-blocking risk remains beyond normal checks and review.

Possibly related PRs

• lidge-jun/opencodex#611: Both changes update Volcengine Ark handling and distinguish /api/v3 from Coding Plan endpoints.

Suggested reviewers: lidge-jun, wibias

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the Volcengine assistant placeholder fix and its endpoint-specific scope.
Linked Issues check	✅ Passed	The changes fix issue #1571 by using an empty string for /api/coding/v3 while preserving the structured placeholder for /api/v3.
Out of Scope Changes check	✅ Passed	The adapter changes, tests, and documentation directly support the endpoint-specific assistant placeholder fix.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/fix-1571-volcengine-coding-content

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Ingwannu]

Exact-head CI is fully green at 52b1bef7e05aef23711e82cbbc672702943d3c2a, including all Linux shards and macOS. I have marked the PR ready for independent maintainer review; as the author, I will not approve or merge it myself.

[Wibias]

The endpoint split is the right direction, but this needs one compatibility fix before merge.

Latest dev now accepts openai-chat baseUrl values that already include a terminal /chat/completions and normalizes that suffix away before sending. This PR classifies Ark by inspecting the raw configured pathname and requiring it to equal exactly /api/v3.

That means a now-valid pay-as-you-go configuration such as:

https://ark.cn-beijing.volces.com/api/v3/chat/completions

is misclassified as non-PAYG and falls back to content: "", even though it is the same PAYG endpoint as /api/v3 after the adapter's URL normalization.

Please normalize a terminal /chat/completions before deciding the Ark endpoint family, and add regression coverage for both:

• /api/v3/chat/completions -> same structured placeholder behavior as /api/v3
• /api/coding/v3/chat/completions -> same empty-string behavior as /api/coding/v3

The branch also predates the current dev, so please rebase after that fix and rerun the relevant CI.