Repository navigation
docs: correct the OpenCode/Kilo workaround, which does not exist - #1374
Merged
Merged
Conversation
Confirmed against both trees while debugging why the console still shows no session for these clients: the gateway side works (Claude Code and Codex rows carry sessions), and the gap is entirely client-side. What I had written was wrong in a way that would waste someone's afternoon. The advice was to add a `chat.headers` plugin on the runner that sends no headers. That hook exists only on the OLDER `packages/opencode` path -- which already builds the header block directly. The newer core runner (`packages/core/src/session/runner/llm.ts`, the one `location-services.ts` registers as SessionRunnerLLM.node) has neither the header block nor any plugin hook to add one with. So where the hook exists the fix is unnecessary, and where the headers are missing there is nothing to hook. The text now says that plainly, names the file and the registration so the next reader can check it in a minute, and gives the two real remedies: upgrade OpenCode past anomalyco/opencode#43188, and for Kilo port that same change into the fork, since Kilo branched before the restore. `make lint` and `make docs-verify` pass; the zh_CN catalog carries both rewritten paragraphs. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01WpETEerrhcCpsg69ucjrEt
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
🟡 Changes recommended
The rewritten docs aim to be exact about file locations but currently cite the core runner path without the src/ segment, which risks sending readers to the wrong/non-existent file.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR updates the developer database documentation to correct guidance around OpenCode/Kilo Code session headers, clarifying which client request path does (and does not) send session headers and why the previously suggested chat.headers workaround is not applicable on the missing-header path.
Changes:
- Rewrites the OpenCode/Kilo session-header paragraph in
docs/developer/database.mdto distinguish the two runners and the absence of a plugin hook on the newer path. - Updates the zh_CN gettext catalog entries to match the revised English paragraphs (plus POT creation timestamp update).
File summaries
| File | Description |
|---|---|
| docs/developer/database.md | Clarifies OpenCode/Kilo request paths and removes the incorrect “add chat.headers” workaround guidance for the core runner path. |
| docs/developer/locale/zh_CN/LC_MESSAGES/database.po | Updates zh_CN translations for the rewritten paragraphs and refreshes POT metadata. |
Review details
Suppressed comments (1)
docs/developer/locale/zh_CN/LC_MESSAGES/database.po:585
- The Chinese translation mirrors the same (likely incorrect) core runner path without the
src/segment; update it to match the corrected path so the translation stays consistent with the English doc.
"这些客户端有两条请求路径，只有其中一条会发会话头。较旧的 `packages/opencode` 路径直接"
"构造这些头；较新的 `packages/core/session/runner/llm.ts` runner 一度把它们弄丢了，"
"上游在 `sst/opencode#43188`（2026-08-18）中才补回来。Kilo Code 是在那次修复之前分叉"
- Files reviewed: 2/2 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Copilot caught that the paragraph cited `packages/core/session/runner/llm.ts` without the `src/` segment. The file is `packages/core/src/session/runner/llm.ts` in both trees; the path as written resolves to nothing. That matters more than a typo usually would: the point of naming the file was so a reader could confirm the claim in a minute rather than take the prose on trust, and a path that does not exist defeats exactly that. Fixed in the English and in the zh_CN translation, which had mirrored it. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01WpETEerrhcCpsg69ucjrEt
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #1371, correcting guidance I got wrong there.
What prompted it
The console still showed no session for OpenCode and Kilo after #1371 deployed to staging. Checking which rows were affected settled it: Claude Code and Codex rows do carry sessions, so the gateway side works end to end — resolver,
metadata["session_id"], theapi_logs.session_idcolumn, the admin query, the response model, the console. The gap is entirely client-side.The error
#1371's docs said: on the runner that sends no headers, add a
chat.headersplugin that setsX-Session-ID.That is useless in both directions:
chat.headershook exists only on the olderpackages/opencode/src/session/llm/request.tspath — which already builds the header block directly. Where the hook exists, nothing needs fixing.packages/core/src/session/runner/llm.ts, registered asSessionRunnerLLM.nodeinlocation-services.ts) has neither the header block nor any plugin hook. Where the headers are missing, there is nothing to hook.I verified both against the
sst/opencodeandKilo-Org/kilocodetrees rather than reasoning from the earlier read.What it says now
The two paths are named explicitly, along with the registration site, so the next reader can confirm it in about a minute instead of trusting the prose. And the two real remedies:
sst/opencode#43188(2026-08-18), which restored the block on the core runner.Docs only; no code change.
Verification
make lintclean andmake docs-verifyreports translations match the English build. Both rewritten paragraphs are translated in the zh_CN catalog.🤖 Generated with Claude Code
https://claude.ai/code/session_01WpETEerrhcCpsg69ucjrEt
Generated by Claude Code